1Xaw(3) Library Functions Manual Xaw(3)
2
6 Xaw - X Athena Widgets
7
9 Xaw is a widget set based on the X Toolkit Intrinsics (Xt) Library.
10 This release by the X.Org Foundation includes additions and modifica‐
11 tions originally made for The XFree86 Project, Inc. This manual page
12 describes these changes as well as some of the common interfaces be‐
13 tween its version and the previous X Consortium release (Xaw6).
14 The bulk of the Xaw documentation is located in the API specification
16 which may be installed in /usr/share/doc/libXaw, or found on the X.Org
17 website.
18
20 All of the Xaw widgets now have the additional translations call-proc,
21 declare, get-values and set-values. The syntax for these actions is:
22 action-name (boolean-expression, arguments)
24 Action-name is one of call-proc, declare, get-values or set-values.
26 Boolean-expression is composed with the operators | (or), & (and), ^
28 (xor), and ~ (not). The operands can be a variable name, which starts
29 with a $; a resource name without the bindings . or *; or a constant
30 name, including mine (event->xany.window == XtWindow(widget)), faked
31 (event->xany.send_event != 0), true (1) and false (0).
32 Arguments are self-explanatory; when starting with a $ they name a
34 variable, otherwise, they indicate a resource name.
35 call-proc (boolean-expression, procedure-name)
37 This action allows the evaluation of a boolean expression in
38 the first parameter before calling a action procedure. The
39 procedure is only called if the expression evaluates as true.
40 Example:
41 call-proc("$inside & $pressed", notify)
42 declare (boolean-expression, variable, value, ...)
44 This action is used to create new variables or change their
45 values. Any number of variable-value tuples may be specified.
46 Example:
47 declare(1, $pressed, 1)
48 get-values (boolean-expression, variable, value, ...)
50 This action reads a widget resource value into a variable. Any
51 number of variable-value tuples may be specified. Example:
52 get-values(1, $fg, foreground, $bg, background)
53 set-values (boolean-expression, variable, value, ...)
55 This action sets a widget resource to the given value, which
56 may be a variable. Any number of variable-value tuples may be
57 specified. Example:
58 set-values(1, foreground, $bg, background, $fg)
59 Here is a sample translation to make a label widget behave like a but‐
61 ton:
62 <Map>: get-values(1, $fg, foreground, $bg, background)\n\
64 <Btn1Down>: set-values(1, foreground, yellow, background, gray30)\n\
65 <Btn1Up>: set-values(1, foreground, $fg, background, $bg)
66
68 All of the Xaw widgets have now the additional resource displayList.
69 This resource allows drawing the widget decorations using commands em‐
70 bedded in a resource string. The displayList resource has the syntax:
71 [class-name:]function-name arguments[[{;\n}]...]
73 Class-name is any registered set of functions to draw in the widget.
75 Currently the only existing class is xlib, which provides access to the
76 Xlib drawing primitives.
77 Function-name is the drawing or configuration function to be called,
79 described bellow.
80 Arguments may be anything suitable to the displayList function being
82 called. When the function requires a coordinate, the syntax is {+-}<in‐
83 teger> or <integer>/<integer>. Examples:
84 +0,+0 top, left
85 -0,-0 bottom, right
86 -+10,-+10 bottom+10, right+10
87 +0,1/2 left, vertical-center
88 arc-mode mode
90 Sets the arc mode. Accepted modes are "pieslice" and "chord",
91 which set the arc to ArcPieSlice or ArcChord, respectively.
92 Example:
93 arc-mode chord
94 bg color-spec
96 background color-spec
97 Sets the background color. color-spec must a valid color
98 specification. Example:
99 background red
100 cap-style style
102 Sets the cap style. Accepted styles are "notlast", "butt",
103 "round", and "projecting", which set the cap style to CapNot‐
104 Last, CapBut, CapRound or CapProjecting, respectively. Exam‐
105 ple:
106 cap-style round
107 clip-mask pixmap-spec
109 Sets the pixmap for the clip mask. Requires a pixmap parame‐
110 ter, as described in the PIXMAPS section below. Example:
111 clip-mask xlogo11
112 clip-origin x,y
114 Sets the clip x and y origin. Requires two arguments, the x
115 and y coordinates. Example:
116 clip-origin 10,10
117 clip-rects x1,y1,x2,y2 [...,xn,yn]
119 clip-rectangles x1,y1,x2,y2 [...,xn,yn]
120 Sets a list of rectangles to the clip mask. The number of ar‐
121 guments must be a multiple of four. The arguments are coordi‐
122 nates. The parser calculates the width and height of the rec‐
123 tangles. Example:
124 clip-rects 0,0,10,20, 20,10,30,30
125 coord-mode mode
127 Changes the coord mode for fill-polygon, draw-lines, and draw-
128 points. Accepted parameters are "modeorigin" and "previous",
129 that sets the coord mode to CoordModeOrigin or CoordModePrevi‐
130 ous, respectively. Example:
131 coord-mode previous
132 copy-area {pixmap-spec|.},dstx,dsty[,x2,y2,srcx,srcy]
134 Calls XCopyArea. The character . means copy the window con‐
135 tents; pixmap-spec is as defined in the PIXMAPS section below.
136 X2 and y2 are the coordinates of the end copy, not the width
137 and height; if not defined, the parser calculates them. src_x
138 and src_y default to zero. Example:
139 copy-area Term,10,10
140 copy-plane {pixmap-spec|.},dstx,dsty[,x2,y2,srcx,srcy,plane]
142 Calls XCopyPlane. The character . means copy the window con‐
143 tents; pixmap-spec is as defined in the PIXMAPS section below.
144 X2 and y2 are the coordinates of the end copy, not the width
145 and height; if not defined, the parser calculates them. src_x
146 and src_y default to zero. Plane defaults to one. Example:
147 copy-plane star,10,10
148 dashes i1[...,in]
150 Sets the dashes for line drawing. Accepts up to 127 arguments.
151 Example:
152 dashes 3,7 9,10
153 draw-arc x1,y1,x2,y2[,start-angle,end-angle]
155 Draws an arc. The four first arguments are the rectangle en‐
156 closing the arc. The two remaining arguments, if specified,
157 are the start and end angle, in degrees. Example:
158 draw-arc +0,+0,-1,-1,0,90
159 draw-rect x1,y1,x2,y2
161 draw-rectangle x1,y1,x2,y2
162 Draws a rectangle. Requires four arguments, which are the
163 start and end coordinate pairs. Example:
164 draw-rect +1,+1,-5,-5
165 draw-string x,y,"string"
167 Draws a text string. Requires three arguments, a x coordinate,
168 a y coordinate, and a string. Strings that have white space
169 can be quoted with the " character; the backslash character \
170 can also be used, but it will be necessary escape it twice.
171 Example:
172 draw-string 10,10, "Hello world!"
173 exposures boolean
175 Sets graphics exposures in the GC. Allowed parameters are a
176 integer or the strings "true", "false", "on" and "off". Exam‐
177 ple:
178 exposures true
179 fill-arc x1,y1,x2,y2[,start-angle,end-angle]
181 Like draw-arc, but fills the contents of the arc with the cur‐
182 rently selected foreground. Example:
183 fill-arc +0,+0,-1,-1,0,180
184 fill-poly x1,y1 [...,xn,yn]
186 fill-polygon x1,y1 [...,xn,yn]
187 Like draw-lines, but fills the enclosed polygon and joins the
188 first and last point, if they are not at the same position.
189 Example:
190 fill-poly +0,+10, +10,+20, +30,+0
191 fill-rect x1,y1,x2,y2
193 fill-rectangle x1,y1,x2,y2
194 Like draw-rect, but fills the contents of the rectangle with
195 the selected foreground color. Example:
196 fill-rect +10,+10,-20,-20
197 fill-rule rule
199 Sets the fill rule. Accepted parameters are "evenodd" and
200 "winding", which set the fill rule to EvenOddRule or Windin‐
201 gRule, respectively. Example:
202 fill-rule winding
203 fill-style style
205 Sets the fill style. Allowed parameters are "solid", "tiled",
206 "stippled" and "opaquestippled", which set the fill style to
207 FillSolid, FillTiled, FillStippled or FillOpaqueStippled, re‐
208 spectively. Example:
209 fill-style tiled
210 font font-spec
212 Sets the font for text functions. Example:
213 font -*-*-*-R-*-*-*-120-*-*-*-*-ISO8859-1
214 fg color-spec
216 foreground color-spec
217 Like background, but sets the current foreground color. Exam‐
218 ple:
219 foreground blue
220 mask This command is useful when you want to draw only in the region
222 that really needs to be repainted. Requires no arguments.
223 function function-spec
225 Sets the specific GC function. Allowed parameters are "set",
226 "clear", "and", "andreverse", "copy", "andinverted", "noop",
227 "xor", "or", "nor", "equiv", "invert", "orreverse", "copyin‐
228 verted" and "nand", which set the function to GXset, GXclear,
229 GXand, GXandReverse, GXcopy, GXandInverted, GXnoop, GXxor,
230 GXor, GXnor, GXequiv, GXinvert, GXorReverse, GXcopyInverted or
231 GXnand, respectively. Example:
232 function xor
233 join-style style
235 Sets the join style. Allowed parameters are "miter", "round"
236 and "bevel", which set the join style to JoinMiter, JoinRound
237 and JoinBevel, respectively. Example:
238 join-style round
239 image {pixmap-spec},xs,ys,[xe,ye]
241 This function is implemented as a way to quickly compose com‐
242 plex decorations in widgets. Pixmap-spec is as defined in the
243 PIXMAPS section below. xs and ys are the coordinates from where
244 to start copying the pixmap; xe and ye are optional (they de‐
245 fault to xs + pixmap.width and ys + pixmap.height, respec‐
246 tively). If the pixmap has a mask, the copy is masked accord‐
247 ingly. Example:
248 image pixmap.xpm,0,0,20,20
249 line x1,y1,x2,y2
251 draw-line x1,y1,x2,y2
252 Draws a line with the current foreground color. Requires four
253 arguments, the starting and ending coordinate pairs. Example:
254 line +0,+0, -1,-1
255 line-width integer
257 Selects a line width for drawing. Example:
258 line-width 2
259 line-style style
261 Sets the line style. Accepted parameters are "solid", "onoff‐
262 dash" and "doubledash", which set the line style to LineSolid,
263 LineOnOffDash or LineDoubleDash, respectively. Example:
264 line-style onoffdash
265 lines x1,y1,x2,y2 [...,xn,yn]
267 draw-lines x1,y1,x2,y2 [...,xn,yn]
268 Draws a list of lines. Any number of argument pairs may be sup‐
269 plied. Example:
270 lines +0,-1, -1,-1, -1,+0
271 paint-string x,y,"string"
273 Identical to draw-string, but also uses the background color.
274 Example:
275 paint-string 10,20, "Sample text"
276 point x,y
278 draw-point x,y
279 Draws a point. Requires two arguments, a coordinate pair. Ex‐
280 ample:
281 point +10,+10
282 plane-mask integer
284 Sets the plane mask. Requires an integer parameter. Example:
285 plane-mask -1
286 points x1,y1 [...,xn,yn]
288 draw-points x1,y1 [...,xn,yn]
289 Draws a list of points at the specified coordinates. Example:
290 points +1,+2, +1,+4, +1,+6
291 segments x1,y1,x2,y2 [...,xn,yn]
293 draw-segments x1,y1,x2,y2 [...,xn,yn]
294 Draws a list of segment lines. The number of parameters must
295 be multiple of 4. Example:
296 segments +1,+2,+1,-3, +2,-2,-3,-2
297 shape-mode mode
299 Sets the shape mode used in fill-polygon. Accepted parameters
300 are "complex", "convex" or "nonconvex", which set the shape
301 mode to Complex, Convex or Nonconvex, accordingly. Example:
302 shape-mode convex
303 stipple pixmap-spec
305 Sets the pixmap for a stipple. Requires a pixmap parameter, as
306 described in the PIXMAPS section below. Example:
307 stipple plaid
308 subwindow-mode mode
310 Sets the subwindow mode in the GC. Accepted parameters are
311 "includeinferiors" and "clipbychildren", which set the subwin‐
312 dow mode to IncludeInferiors or ClipByChildren, respectively.
313 Example:
314 subwindow-mode includeinferiors
315 tile pixmap-spec
317 Sets the pixmap for a tile. Requires a pixmap parameter, as
318 described in the PIXMAPS section below. Example:
319 tile xlogo11?foreground=red&background=gray80
320 ts-origin x,y
322 Sets the tile stipple x and y origin. Requires two arguments,
323 a x and y coordinate. Example:
324 ts-origin 10,10
325 umask Disables the GC mask, if it has been set with the command mask.
327 Requires no arguments.
328 Example for drawing a shadow effect in a widget:
330 foreground gray30;\
331 draw-lines +1,-1,-1,-1,-1,+1;\
332 foreground gray85;\
333 draw-lines -1,+0,+0,+0,+0,-1
334
336 A String to Pixmap converter has been added to Xaw. This converter is
337 meant to be extended, and has enough abstraction to allow loading sev‐
338 eral image formats. It uses a format that resembles a URL, with the
339 syntax:
340 [type:]name[?arg=val[{&}...]]
342 Type can be one of bitmap, gradient or xpm.
344 Name may be a file name, or, in the case of type gradient, may be ei‐
346 ther vertical or horizontal.
347 Arg=val is a list of arguments to the converter. An argument list is
349 preceded by a question mark, and multiple arguments are separated by
350 ampersands. The most common arguments are foreground and background.
351 Gradients also support the arguments start and end (colors with which
352 to start and end the gradient); the steps argument, to allow using less
353 colors; and the dimension argument to specify the size of the gradi‐
354 ent. The xpm converter understands the closeness argument, which
355 aids in using fewer colors (useful if you have a limited colormap).
356
358 Most of the changes to this version of the Xaw library were done in the
359 TextWidget, TextSrcObject, TextSinkObject and related files.
360 A couple of highly visible changes in the Text widget are due to many
362 bugs in the Xaw6 implementation involving scrollbars and auto-resizing.
363 Scrollbars being added or removed caused several problems in keeping
364 the text cursor visible, and in Xaw6 it was very easy to have a widget
365 thinking the cursor was visible, when it was not. Also, permitting au‐
366 tomatic resizing of the widget to a larger geometry created other prob‐
367 lems, making it difficult to have a consistent layout in the applica‐
368 tion, and, if the window manager did not interfere, windows larger than
369 the screen could result. Therefore, some functionality involving
370 scrollbars and auto-resizing has been disabled; see the section on new
371 and modified Text widget resources below.
372 The Text widget's default key bindings were originally based on the
374 Emacs text editor. In this release, even more operations familiar to
375 Emacs users have been added. New text actions include:
376 indent Indents text blocks. Not bound by default. The Text widget
378 also does not attempt to perform auto-indentation of its source
379 object by default.
380 keyboard-reset
382 Resets the keyboard state. Reverts the action multiplier to 1,
383 and if undo is enabled, toggles between undo and redo. Bound
384 by default to Control<Key>G.
385 kill-ring-yank
387 In this version of Xaw, text killed in any text field is kept
388 in memory, allowing cut and paste operations internally to the
389 program between text fields. Bound by default to Meta<Key>Y.
390 numeric Listed here only for purposes of documentation. Called by de‐
392 fault when one of the characters 1, 2, 3, 4, 5, 6, 7, 8, 9, 0,
393 or - is typed, allowing composition of the multiplication num‐
394 ber of text actions.
395 set-keyboard-focus
397 Sets the input focus of the top level widget to the text field.
398 Not enabled by default, but bound to the <Btn1Down> event.
399 toggle-overwrite
401 Toggles overwrite mode. In overwrite mode, any text inserted
402 in a text field will replace existing text. Bound by default
403 to <Key>Insert.
404 undo Sets the enableUndo resource of the textSrcObject. Not enabled
406 by default, but bound to Control<Key>_.
407 New and modified Text widget resources include:
409 justify (Class Justify)
411 Sets the text justification. Can be one of left, right, cen‐
412 ter, or full. Only enabled when the autoFill resource is set,
413 and the resources leftColumn and rightColumn are correctly set.
414 leftColumn (Class Column)
416 Specifies the left column at which to break text. Text lines
417 started with an alphanumeric character will automatically start
418 at this column.
419 positionCallback (Class Callback)
421 Allows installation of a callback to be called every time the
422 cursor is moved, and/or the file changes its size. The call‐
423 back is called with a pointer to a structure containing the
424 following data:
425 typedef struct {
426 int line_number;
427 int column_number;
428 XawTextPosition insert_position;
429 XawTextPosition last_position;
430 Boolean overwrite_mode;
431 } XawTextPositionInfo;
432 This callback is intended to help programmers write text edi‐
433 tors based on the Xaw widget set.
434 resize (Class Resize)
436 No longer supported, but recognized for backward compatibility
437 with resource specifications written for the Xaw6 Text widget.
438 rightColumn (Class Column)
440 Specifies the right column at which to break text. Text lines
441 started with an alphanumeric character will automatically end
442 at this column.
443 scrollHorizontal (Class Scroll)
445 scrollVertical (Class Scroll)
446 These resources control the placement of scrollbars on the left
447 and bottom edges of the Text widget. They accept the values
448 XawtextScrollAlways and XawtextScrollNever. A converter is
449 registered for this resource that will convert the following
450 strings: always and never. The value XawtextScrollWhenNeeded
451 (and whenNeeded, recognized by the converter), is accepted for
452 backwards compatibility with resource specifications written
453 for the Xaw6 Text widget, but ignored (effectively treated as
454 XawtextScrollNever).
455
457 The textSrcObject allows display of its contents to more than one win‐
458 dow, and also stores undo information. The new resources for the
459 textSrcObject are:
460 callback (Class Callback)
462 Previous versions of Xaw had this resource in subclasses of the
463 TextSource object. This was changed to make it possible to
464 tell the callback the state of the text when undo is enabled.
465 enableUndo (Class Undo)
467 A boolean resource that enables or disables the undo function.
468 The default value is False.
469 sourceChanged (Class Changed)
471 Like the callback resource, this resource was previously in
472 subclasses of the TextSource object. It is now in the textSr‐
473 cObject to control the changed/unchanged state when undo is en‐
474 abled.
475
477 The textSinkObject subclasses asciiSinkObject and multiSinkObject have
478 been changed slightly to use a new cursor shape (no longer a caret at
479 the baseline) that indicates the input focus of the text widget, and
480 allow specification of the cursor color. The new resource is:
481 cursorColor (Class Color)
483 Sets the cursor color of the text. This color is also used to
484 draw selected text.
485
487 The simpleMenuWidget algorithm to lay out menu entries has been changed
488 to enable multiple columns when a single column does not fit on the
489 screen. It was also modified to enable submenus.
490
492 A new resource has been added to the smeBSBObject to allow binding sub‐
493 menus to it. The new resource is:
494 menuName (Class MenuName)
496 Specifies the name of the popup widget to be popped up when the
497 pointer is over the menu entry, or NULL. Note that the named
498 menu must be a child of the popup parent of the smeBSBObject.
499
501 The original X Consortium version of the Athena Widget Set and its doc‐
502 umentation were the work of many people, including Chris D. Peterson,
503 Ralph Swick, Mark Ackerman, Donna Converse, Jim Fulton, Loretta Guar‐
504 ino-Reid, Charles Haynes, Rich Hyde, Mary Larson, Joel McCormack, Ron
505 Newman, Jeanne Rich, Terry Weissman, Mike Gancarz, Phil Karlton, Kath‐
506 leen Langone, Ram Rao, Smokey Wallace, Al Mento, and Jean Diaz.
507 The additions and modifications to Xaw which were originally made for
509 XFree86 were written by Paulo César Pereira de Andrade.
510
512 Athena Widget Set - C Language Interface
513X Version 11 libXaw 1.0.14 Xaw(3)