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