dwww Home | Manual pages | Find package

Xaw(3)                     Library Functions Manual                     Xaw(3)

NAME
        Xaw - X Athena Widgets

DESCRIPTION
       Xaw  is  a  widget  set based on the X Toolkit Intrinsics (Xt) Library.
       This release by the X.Org Foundation includes additions  and  modifica-
       tions  originally  made for The XFree86 Project, Inc.  This manual page
       describes these changes as well as some of the  common  interfaces  be-
       tween its version and the previous X Consortium release (Xaw6).

       The  bulk  of the Xaw documentation is located in the API specification
       which may be installed in /usr/share/doc/libxaw7-dev, or found  on  the
       X.Org website.

ACTIONS
       All  of the Xaw widgets now have the additional translations call-proc,
       declare, get-values and set-values. The syntax for these actions is:

       action-name (boolean-expression, arguments)

       Action-name is one of call-proc, declare, get-values or set-values.

       Boolean-expression is composed with the operators | (or),  &  (and),  ^
       (xor),  and  ~ (not). The operands can be a variable name, which starts
       with a $; a resource name without the bindings .  or *; or  a  constant
       name,  including  mine  (event->xany.window == XtWindow(widget)), faked
       (event->xany.send_event != 0), true (1) and false (0).

       Arguments are self-explanatory; when starting with  a  $  they  name  a
       variable, otherwise, they indicate a resource name.

       call-proc (boolean-expression, procedure-name)
               This  action  allows  the evaluation of a boolean expression in
               the first parameter before calling  a  action  procedure.   The
               procedure  is  only called if the expression evaluates as true.
               Example:
               call-proc("$inside & $pressed", notify)

       declare (boolean-expression, variable, value, ...)
               This action is used to create new  variables  or  change  their
               values.   Any number of variable-value tuples may be specified.
               Example:
               declare(1, $pressed, 1)

       get-values (boolean-expression, variable, value, ...)
               This action reads a widget resource value into a variable.  Any
               number of variable-value tuples may be specified.  Example:
               get-values(1, $fg, foreground, $bg, background)

       set-values (boolean-expression, variable, value, ...)
               This  action  sets  a widget resource to the given value, which
               may be a variable.  Any number of variable-value tuples may  be
               specified.  Example:
               set-values(1, foreground, $bg, background, $fg)

       Here  is a sample translation to make a label widget behave like a but-
       ton:

       <Map>:      get-values(1, $fg, foreground, $bg, background)\n\
       <Btn1Down>: set-values(1, foreground, yellow, background, gray30)\n\
       <Btn1Up>:   set-values(1, foreground, $fg, background, $bg)

DISPLAY LISTS
       All of the Xaw widgets have now the  additional  resource  displayList.
       This  resource allows drawing the widget decorations using commands em-
       bedded in a resource string.  The displayList resource has the syntax:

       [class-name:]function-name arguments[[{;\n}]...]

       Class-name is any registered set of functions to draw  in  the  widget.
       Currently the only existing class is xlib, which provides access to the
       Xlib drawing primitives.

       Function-name is the drawing or configuration function  to  be  called,
       described bellow.

       Arguments  may  be  anything suitable to the displayList function being
       called. When the function requires a coordinate, the syntax is {+-}<in-
       teger> or <integer>/<integer>. Examples:
            +0,+0      top, left
            -0,-0      bottom, right
            -+10,-+10  bottom+10, right+10
            +0,1/2     left, vertical-center

       arc-mode mode
               Sets  the arc mode.  Accepted modes are "pieslice" and "chord",
               which set the arc to  ArcPieSlice  or  ArcChord,  respectively.
               Example:
               arc-mode chord

       bg color-spec
       background color-spec
               Sets  the   background  color.   color-spec  must a valid color
               specification.  Example:
               background red

       cap-style style
               Sets the cap style.  Accepted  styles  are  "notlast",  "butt",
               "round",  and  "projecting", which set the cap style to CapNot-
               Last, CapBut, CapRound or CapProjecting,  respectively.   Exam-
               ple:
               cap-style round

       clip-mask pixmap-spec
               Sets  the  pixmap for the clip mask.  Requires a pixmap parame-
               ter, as described in the PIXMAPS section below.  Example:
               clip-mask xlogo11

       clip-origin x,y
               Sets the clip x and y origin.  Requires two  arguments,  the  x
               and y coordinates.  Example:
               clip-origin 10,10

       clip-rects x1,y1,x2,y2 [...,xn,yn]
       clip-rectangles x1,y1,x2,y2 [...,xn,yn]
               Sets  a list of rectangles to the clip mask.  The number of ar-
               guments must be a multiple of four.  The arguments are  coordi-
               nates.   The parser calculates the width and height of the rec-
               tangles.  Example:
               clip-rects 0,0,10,20, 20,10,30,30

       coord-mode mode
               Changes the coord mode for fill-polygon, draw-lines, and  draw-
               points.   Accepted  parameters are "modeorigin" and "previous",
               that sets the coord mode to CoordModeOrigin or  CoordModePrevi-
               ous, respectively.  Example:
               coord-mode previous

       copy-area {pixmap-spec|.},dstx,dsty[,x2,y2,srcx,srcy]
               Calls  XCopyArea.   The  character . means copy the window con-
               tents; pixmap-spec is as defined in the PIXMAPS section  below.
               X2  and  y2  are the coordinates of the end copy, not the width
               and height; if not defined, the parser calculates  them.  src_x
               and src_y default to zero.  Example:
               copy-area Term,10,10

       copy-plane {pixmap-spec|.},dstx,dsty[,x2,y2,srcx,srcy,plane]
               Calls  XCopyPlane.  The  character . means copy the window con-
               tents; pixmap-spec is as defined in the PIXMAPS section  below.
               X2  and  y2  are the coordinates of the end copy, not the width
               and height; if not defined, the parser calculates them.   src_x
               and src_y default to zero. Plane defaults to one.  Example:
               copy-plane star,10,10

       dashes i1[...,in]
               Sets the dashes for line drawing.  Accepts up to 127 arguments.
               Example:
               dashes 3,7 9,10

       draw-arc x1,y1,x2,y2[,start-angle,end-angle]
               Draws an arc.  The four first arguments are the  rectangle  en-
               closing  the  arc.   The two remaining arguments, if specified,
               are the start and end angle, in degrees.  Example:
               draw-arc +0,+0,-1,-1,0,90

       draw-rect x1,y1,x2,y2
       draw-rectangle x1,y1,x2,y2
               Draws a rectangle.  Requires  four  arguments,  which  are  the
               start and end coordinate pairs.  Example:
               draw-rect +1,+1,-5,-5

       draw-string x,y,"string"
               Draws a text string.  Requires three arguments, a x coordinate,
               a y coordinate, and a string.  Strings that  have  white  space
               can  be  quoted with the " character; the backslash character \
               can also be used, but it will be  necessary  escape  it  twice.
               Example:
                draw-string 10,10, "Hello world!"

       exposures boolean
               Sets  graphics  exposures  in the GC.  Allowed parameters are a
               integer or the strings "true", "false", "on" and "off".   Exam-
               ple:
               exposures true

       fill-arc x1,y1,x2,y2[,start-angle,end-angle]
               Like  draw-arc, but fills the contents of the arc with the cur-
               rently selected foreground.  Example:
               fill-arc +0,+0,-1,-1,0,180

       fill-poly x1,y1 [...,xn,yn]
       fill-polygon x1,y1 [...,xn,yn]
               Like draw-lines, but fills the enclosed polygon and  joins  the
               first  and  last  point,  if they are not at the same position.
               Example:
               fill-poly +0,+10, +10,+20, +30,+0

       fill-rect x1,y1,x2,y2
       fill-rectangle x1,y1,x2,y2
               Like draw-rect, but fills the contents of  the  rectangle  with
               the selected foreground color.  Example:
               fill-rect +10,+10,-20,-20

       fill-rule rule
               Sets  the  fill  rule.   Accepted  parameters are "evenodd" and
               "winding", which set the fill rule to  EvenOddRule  or  Windin-
               gRule, respectively.  Example:
               fill-rule winding

       fill-style style
               Sets  the fill style.  Allowed parameters are "solid", "tiled",
               "stippled" and "opaquestippled", which set the  fill  style  to
               FillSolid,  FillTiled,  FillStippled or FillOpaqueStippled, re-
               spectively.  Example:
               fill-style tiled

       font font-spec
               Sets the font for text functions.  Example:
               font -*-*-*-R-*-*-*-120-*-*-*-*-ISO8859-1

       fg color-spec
       foreground color-spec
               Like background, but sets the current foreground color.   Exam-
               ple:
               foreground blue

       mask    This command is useful when you want to draw only in the region
               that really needs to be repainted.  Requires no arguments.

       function function-spec
               Sets the specific GC function.  Allowed parameters  are  "set",
               "clear",  "and",  "andreverse",  "copy", "andinverted", "noop",
               "xor", "or", "nor", "equiv",  "invert",  "orreverse",  "copyin-
               verted"  and  "nand", which set the function to GXset, GXclear,
               GXand,  GXandReverse,  GXcopy,  GXandInverted,  GXnoop,  GXxor,
               GXor,  GXnor, GXequiv, GXinvert, GXorReverse, GXcopyInverted or
               GXnand, respectively.  Example:
               function xor

       join-style style
               Sets the join style.  Allowed parameters are  "miter",  "round"
               and  "bevel",  which set the join style to JoinMiter, JoinRound
               and JoinBevel, respectively.  Example:
               join-style round

       image {pixmap-spec},xs,ys,[xe,ye]
               This function is implemented as a way to quickly  compose  com-
               plex  decorations in widgets.  Pixmap-spec is as defined in the
               PIXMAPS section below. xs and ys are the coordinates from where
               to  start  copying the pixmap; xe and ye are optional (they de-
               fault to xs + pixmap.width  and  ys  +  pixmap.height,  respec-
               tively).   If the pixmap has a mask, the copy is masked accord-
               ingly.  Example:
               image pixmap.xpm,0,0,20,20

       line x1,y1,x2,y2
       draw-line x1,y1,x2,y2
               Draws a line with the current foreground color.  Requires  four
               arguments, the starting and ending coordinate pairs.  Example:
               line +0,+0, -1,-1

       line-width integer
               Selects a line width for drawing.  Example:
               line-width 2

       line-style style
               Sets  the line style.  Accepted parameters are "solid", "onoff-
               dash" and "doubledash", which set the line style to  LineSolid,
               LineOnOffDash or LineDoubleDash, respectively.  Example:
               line-style onoffdash

       lines x1,y1,x2,y2 [...,xn,yn]
       draw-lines x1,y1,x2,y2 [...,xn,yn]
               Draws a list of lines. Any number of argument pairs may be sup-
               plied.  Example:
               lines +0,-1, -1,-1, -1,+0

       paint-string x,y,"string"
               Identical to draw-string, but also uses the  background  color.
               Example:
                paint-string 10,20, "Sample text"

       point x,y
       draw-point x,y
               Draws a point.  Requires two arguments, a coordinate pair.  Ex-
               ample:
               point +10,+10

       plane-mask integer
               Sets the plane mask.  Requires an integer parameter.  Example:
               plane-mask -1

       points x1,y1 [...,xn,yn]
       draw-points x1,y1 [...,xn,yn]
               Draws a list of points at the specified coordinates.  Example:
               points +1,+2, +1,+4, +1,+6

       segments x1,y1,x2,y2 [...,xn,yn]
       draw-segments x1,y1,x2,y2 [...,xn,yn]
               Draws a list of segment lines.  The number of  parameters  must
               be multiple of 4.  Example:
               segments +1,+2,+1,-3, +2,-2,-3,-2

       shape-mode mode
               Sets  the shape mode used in fill-polygon.  Accepted parameters
               are "complex", "convex" or "nonconvex",  which  set  the  shape
               mode to Complex, Convex or Nonconvex, accordingly.  Example:
               shape-mode convex

       stipple pixmap-spec
               Sets the pixmap for a stipple.  Requires a pixmap parameter, as
               described in the PIXMAPS section below.  Example:
               stipple plaid

       subwindow-mode mode
               Sets the subwindow mode in the  GC.   Accepted  parameters  are
               "includeinferiors"  and "clipbychildren", which set the subwin-
               dow mode to IncludeInferiors or  ClipByChildren,  respectively.
               Example:
               subwindow-mode includeinferiors

       tile pixmap-spec
               Sets  the  pixmap  for a tile.  Requires a pixmap parameter, as
               described in the PIXMAPS section below.  Example:
               tile xlogo11?foreground=red&background=gray80

       ts-origin x,y
               Sets the tile stipple x and y origin.  Requires two  arguments,
               a x and y coordinate.  Example:
               ts-origin 10,10

       umask   Disables the GC mask, if it has been set with the command mask.
               Requires no arguments.

       Example for drawing a shadow effect in a widget:
       foreground gray30;\
       draw-lines +1,-1,-1,-1,-1,+1;\
       foreground gray85;\
       draw-lines -1,+0,+0,+0,+0,-1

PIXMAPS
       A String to Pixmap converter has been  added to Xaw.  This converter is
       meant  to be extended, and has enough abstraction to allow loading sev-
       eral image formats.  It uses a format that resembles a  URL,  with  the
       syntax:

       [type:]name[?arg=val[{&}...]]

       Type can be one of bitmap, gradient or xpm.

       Name  may  be a file name, or, in the case of type gradient, may be ei-
       ther vertical or horizontal.

       Arg=val is a list of arguments to the converter.  An argument  list  is
       preceded  by  a  question mark, and multiple arguments are separated by
       ampersands.  The most common arguments are foreground  and  background.
       Gradients  also  support the arguments start and end (colors with which
       to start and end the gradient); the steps argument, to allow using less
       colors;  and  the  dimension argument to specify the size of the gradi-
       ent.     The xpm converter understands the  closeness  argument,  which
       aids in using fewer colors (useful if you have a limited colormap).

TEXT WIDGET
       Most of the changes to this version of the Xaw library were done in the
       TextWidget, TextSrcObject, TextSinkObject and related files.

       A couple of highly visible changes in the Text widget are due  to  many
       bugs in the Xaw6 implementation involving scrollbars and auto-resizing.
       Scrollbars being added or removed caused several  problems  in  keeping
       the  text cursor visible, and in Xaw6 it was very easy to have a widget
       thinking the cursor was visible, when it was not.  Also, permitting au-
       tomatic resizing of the widget to a larger geometry created other prob-
       lems, making it difficult to have a consistent layout in  the  applica-
       tion, and, if the window manager did not interfere, windows larger than
       the screen  could  result.   Therefore,  some  functionality  involving
       scrollbars  and auto-resizing has been disabled; see the section on new
       and modified Text widget resources below.

       The Text widget's default key bindings were  originally  based  on  the
       Emacs  text  editor.  In this release, even more operations familiar to
       Emacs users have been added.  New text actions include:

       indent  Indents text blocks.  Not bound by default.   The  Text  widget
               also does not attempt to perform auto-indentation of its source
               object by default.

       keyboard-reset
               Resets the keyboard state.  Reverts the action multiplier to 1,
               and  if  undo is enabled, toggles between undo and redo.  Bound
               by default to Control<Key>G.

       kill-ring-yank
               In this version of Xaw, text killed in any text field  is  kept
               in  memory, allowing cut and paste operations internally to the
               program between text fields.  Bound by default to Meta<Key>Y.

       numeric Listed here only for purposes of documentation.  Called by  de-
               fault  when one of the characters 1, 2, 3, 4, 5, 6, 7, 8, 9, 0,
               or - is typed, allowing composition of the multiplication  num-
               ber of text actions.

       set-keyboard-focus
               Sets the input focus of the top level widget to the text field.
               Not enabled by default, but bound to the <Btn1Down> event.

       toggle-overwrite
               Toggles overwrite mode.  In overwrite mode, any  text  inserted
               in  a  text field will replace existing text.  Bound by default
               to <Key>Insert.

       undo    Sets the enableUndo resource of the textSrcObject.  Not enabled
               by default, but bound to Control<Key>_.

       New and modified Text widget resources include:

       justify (Class Justify)
               Sets  the  text justification.  Can be one of left, right, cen-
               ter, or full.  Only enabled when the autoFill resource is  set,
               and the resources leftColumn and rightColumn are correctly set.

       leftColumn (Class Column)
               Specifies  the  left column at which to break text.  Text lines
               started with an alphanumeric character will automatically start
               at this column.

       positionCallback (Class Callback)
               Allows  installation  of a callback to be called every time the
               cursor is moved, and/or the file changes its size.   The  call-
               back  is  called  with  a pointer to a structure containing the
               following data:
               typedef struct {
                   int line_number;
                   int column_number;
                   XawTextPosition insert_position;
                   XawTextPosition last_position;
                   Boolean overwrite_mode;
               } XawTextPositionInfo;
               This callback is intended to help programmers write  text  edi-
               tors based on the Xaw widget set.

       resize (Class Resize)
               No  longer supported, but recognized for backward compatibility
               with resource specifications written for the Xaw6 Text widget.

       rightColumn (Class Column)
               Specifies the right column at which to break text.  Text  lines
               started  with  an alphanumeric character will automatically end
               at this column.

       scrollHorizontal (Class Scroll)
       scrollVertical (Class Scroll)
               These resources control the placement of scrollbars on the left
               and  bottom  edges  of the Text widget.  They accept the values
               XawtextScrollAlways and  XawtextScrollNever.   A  converter  is
               registered  for  this  resource that will convert the following
               strings: always and never.  The  value  XawtextScrollWhenNeeded
               (and  whenNeeded, recognized by the converter), is accepted for
               backwards compatibility with  resource  specifications  written
               for  the  Xaw6 Text widget, but ignored (effectively treated as
               XawtextScrollNever).

TEXT SOURCE OBJECT
       The textSrcObject allows display of its contents to more than one  win-
       dow,  and  also  stores  undo  information.  The  new resources for the
       textSrcObject are:

       callback (Class Callback)
               Previous versions of Xaw had this resource in subclasses of the
               TextSource  object.   This  was  changed to make it possible to
               tell the callback the state of the text when undo is enabled.

       enableUndo (Class Undo)
               A boolean resource that enables or disables the undo  function.
               The default value is False.

       sourceChanged (Class Changed)
               Like  the  callback  resource,  this resource was previously in
               subclasses of the TextSource object.  It is now in the  textSr-
               cObject to control the changed/unchanged state when undo is en-
               abled.

TEXT SINK OBJECT
       The textSinkObject subclasses asciiSinkObject and multiSinkObject  have
       been  changed  slightly to use a new cursor shape (no longer a caret at
       the baseline) that indicates the input focus of the  text  widget,  and
       allow specification of the cursor color.  The new resource is:

       cursorColor (Class Color)
               Sets  the cursor color of the text.  This color is also used to
               draw selected text.

SIMPLE MENU WIDGET
       The simpleMenuWidget algorithm to lay out menu entries has been changed
       to  enable  multiple  columns  when a single column does not fit on the
       screen.  It was also modified to enable submenus.

SME BSB OBJECT
       A new resource has been added to the smeBSBObject to allow binding sub-
       menus to it.  The new resource is:

       menuName (Class MenuName)
               Specifies the name of the popup widget to be popped up when the
               pointer is over the menu entry, or NULL.  Note that  the  named
               menu must be a child of the popup parent of the smeBSBObject.

AUTHORS
       The original X Consortium version of the Athena Widget Set and its doc-
       umentation were the work of many people, including Chris  D.  Peterson,
       Ralph  Swick,  Mark Ackerman, Donna Converse, Jim Fulton, Loretta Guar-
       ino-Reid, Charles Haynes, Rich Hyde, Mary Larson, Joel  McCormack,  Ron
       Newman,  Jeanne Rich, Terry Weissman, Mike Gancarz, Phil Karlton, Kath-
       leen Langone, Ram Rao, Smokey Wallace, Al Mento, and Jean Diaz.

       The additions and modifications to Xaw which were originally  made  for
       XFree86 were written by Paulo César Pereira de Andrade.

SEE ALSO
       Athena Widget Set - C Language Interface

X Version 11                     libXaw 1.0.14                          Xaw(3)

Generated by dwww version 1.15 on Sun Jun 16 12:43:55 CEST 2024.