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

ACTIONS

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
19       action-name (boolean-expression, arguments)
20
21       Action-name is one of call-proc, declare, get-values or set-values.
22
23       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
29       Arguments are self-explanatory; when starting with  a  $  they  name  a
30       variable, otherwise, they indicate a resource name.
31
32       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
39       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
45       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
50       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
56       Here  is a sample translation to make a label widget behave like a but‐
57       ton:
58
59       <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

DISPLAY LISTS

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
69       [class-name:]function-name arguments[[{;\n}]...]
70
71       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
75       Function-name  is  the  drawing or configuration function to be called,
76       described bellow.
77
78       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
86       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
92       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
98       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
105       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
110       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
115       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
123       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
130       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
138       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
146       dashes i1[...,in]
147               Sets the dashes for line drawing.  Accepts up to 127 arguments.
148               Example:
149               dashes 3,7 9,10
150
151       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
157       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
163       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
171       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
177       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
182       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
189       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
195       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
201       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
208       font font-spec
209               Sets the font for text functions.  Example:
210               font -*-*-*-R-*-*-*-120-*-*-*-*-ISO8859-1
211
212       fg color-spec
213       foreground color-spec
214               Like  background, but sets the current foreground color.  Exam‐
215               ple:
216               foreground blue
217
218       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
221       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
231       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
237       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
247       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
253       line-width integer
254               Selects a line width for drawing.  Example:
255               line-width 2
256
257       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
263       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
269       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
274       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
280       plane-mask integer
281               Sets the plane mask.  Requires an integer parameter.  Example:
282               plane-mask -1
283
284       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
289       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
295       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
301       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
306       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
313       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
318       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
323       umask   Disables the GC mask, if it has been set with the command mask.
324               Requires no arguments.
325
326       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

PIXMAPS

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

TEXT WIDGET

355       Most of the changes to this version of the Xaw library were done in the
356       TextWidget, TextSrcObject, TextSinkObject and related files.
357
358       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
370       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
374       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
378       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
383       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
388       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
393       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
397       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
402       undo    Sets the enableUndo resource of the textSrcObject.  Not enabled
403               by default, but bound to Control<Key>_.
404
405       New and modified Text widget resources include:
406
407       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
412       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
417       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
432       resize (Class Resize)
433               No longer supported, but recognized for backward  compatibility
434               with resource specifications written for the Xaw6 Text widget.
435
436       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
441       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

TEXT SOURCE OBJECT

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
458       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
463       enableUndo (Class Undo)
464               A  boolean resource that enables or disables the undo function.
465               The default value is False.
466
467       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

TEXT SINK OBJECT

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
479       cursorColor (Class Color)
480               Sets the cursor color of the text.  This color is also used  to
481               draw selected text.
482

SIMPLE MENU WIDGET

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

SME BSB OBJECT

489       A new resource has been added to the smeBSBObject to allow binding sub‐
490       menus to it.  The new resource is:
491
492       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

RESTRICTIONS

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

AUTHORS

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

SEE ALSO

519       Athena Widget Set - C Language Interface
520
521
522
523X Version 11                     libXaw 1.0.2                           Xaw(3)
Impressum