1Xaw(3)                     Library Functions Manual                     Xaw(3)
2
3
4

NAME

6        Xaw - X Athena Widgets
7

DESCRIPTION

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
15       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

ACTIONS

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
23       action-name (boolean-expression, arguments)
24
25       Action-name is one of call-proc, declare, get-values or set-values.
26
27       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
33       Arguments are self-explanatory; when starting with  a  $  they  name  a
34       variable, otherwise, they indicate a resource name.
35
36       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
43       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
49       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
54       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
60       Here  is a sample translation to make a label widget behave like a but‐
61       ton:
62
63       <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

DISPLAY LISTS

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
73       [class-name:]function-name arguments[[{;\n}]...]
74
75       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
79       Function-name  is  the  drawing or configuration function to be called,
80       described bellow.
81
82       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
90       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
96       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
102       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
109       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
114       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
119       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
127       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
134       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
142       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
150       dashes i1[...,in]
151               Sets the dashes for line drawing.  Accepts up to 127 arguments.
152               Example:
153               dashes 3,7 9,10
154
155       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
161       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
167       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
175       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
181       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
186       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
193       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
199       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
205       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
212       font font-spec
213               Sets the font for text functions.  Example:
214               font -*-*-*-R-*-*-*-120-*-*-*-*-ISO8859-1
215
216       fg color-spec
217       foreground color-spec
218               Like  background, but sets the current foreground color.  Exam‐
219               ple:
220               foreground blue
221
222       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
225       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
235       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
241       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
251       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
257       line-width integer
258               Selects a line width for drawing.  Example:
259               line-width 2
260
261       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
267       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
273       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
278       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
284       plane-mask integer
285               Sets the plane mask.  Requires an integer parameter.  Example:
286               plane-mask -1
287
288       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
293       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
299       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
305       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
310       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
317       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
322       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
327       umask   Disables the GC mask, if it has been set with the command mask.
328               Requires no arguments.
329
330       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

PIXMAPS

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
342       [type:]name[?arg=val[{&}...]]
343
344       Type can be one of bitmap, gradient or xpm.
345
346       Name may be a file name, or, in the  case  of  type  gradient,  may  be
347       either vertical or horizontal.
348
349       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

TEXT WIDGET

359       Most of the changes to this version of the Xaw library were done in the
360       TextWidget, TextSrcObject, TextSinkObject and related files.
361
362       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
374       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
378       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
382       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
387       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
392       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
397       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
401       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
406       undo    Sets the enableUndo resource of the textSrcObject.  Not enabled
407               by default, but bound to Control<Key>_.
408
409       New and modified Text widget resources include:
410
411       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
416       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
421       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
436       resize (Class Resize)
437               No longer supported, but recognized for backward  compatibility
438               with resource specifications written for the Xaw6 Text widget.
439
440       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
445       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

TEXT SOURCE OBJECT

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
462       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
467       enableUndo (Class Undo)
468               A  boolean resource that enables or disables the undo function.
469               The default value is False.
470
471       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

TEXT SINK OBJECT

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
483       cursorColor (Class Color)
484               Sets the cursor color of the text.  This color is also used  to
485               draw selected text.
486

SIMPLE MENU WIDGET

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

SME BSB OBJECT

493       A new resource has been added to the smeBSBObject to allow binding sub‐
494       menus to it.  The new resource is:
495
496       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

AUTHORS

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
509       The  additions  and modifications to Xaw which were originally made for
510       XFree86 were written by Paulo César Pereira de Andrade.
511

SEE ALSO

513       Athena Widget Set - C Language Interface
514
515
516
517X Version 11                     libXaw 1.0.13                          Xaw(3)
Impressum