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