XAW(3)

NAME
 XAW - X Athena Widgets

DESCRIPTION
Xaw is a Widget set based on the Xt Intrinsics. This manual page describes the XFree86 additions and modifications to the Xaw library, as well as some of the common interfaces.

ACTIONS
All 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, that starts with a $; a resource name without the bindings . and *; 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, else, a resource name.

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

declare
    This action, like get-values is used to create new variables, or change their value. Example:
    declare(1, $pressed, 1)

get-values
    This actions allows reading a resource value into a variable. Example:
    get-values(1, $fg, foreground, $bg, background)

set-values
    This action allow setting a resource in the widget. Example:
    set-values(1, foreground, $bg, background, $fg)

Sample translation to make a label widget behave like a button:
<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 the Xaw widgets have now the additional resource displayList. This resource allows drawing the widget decorations with commands embedded in the 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.
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 {+-}<integer> 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 parameters are "pieslice" and "chord", that sets the arc to ArcPieSlice or ArcChord, respectively. Example:
    arc-mode chord

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

cap-style style
    Sets the cap style. Accepted parameters are "notlast", "butt", "round", and "projecting", that sets the cap style to CapNotLast, CapBut, CapRound or CapProjecting, respectively. Example:
    cap-style round

clip-mask pixmap-spec
    Sets the pixmap for the clip mask. Requires a pixmap parameter, as described in the PIXMAPS section of this man page. Example:
    clip-mask xlogo11

clip-origin x,y
    Sets the clip x and y origin. Requires two arguments, a x and y coordinate. 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 arguments must be a multiple of four. The arguments are coordinates. The parser calculates the width and height of the rectangles. 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 CoordModePrevious, respectively. Example:
    coord-mode previous

copy-area {pixmap-spec|.},dstx,dsty[,x2,y2,srcx,srcy]
    Calls XCopyArea. The character . means copy the window contents, pixmap-spec is as defined in the PIXMAPS sction of this manual page. X2, and y2 are coordinates of the end copy, not the width and height; if not defined, the parser calculates it. Src_x and src_y defaults 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 contents, pixmap-spec is as defined in the PIXMAPS sction of this manual page. X2, and y2 are coordinates of the end copy, not the width and height; if not defined, the parser calculates it. Src_x and src_y defaults 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 enclosing the arc. The two remaining arguments, if any, 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, that are the start and end coordinates. 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 spaces can be quoted with the " character, the character \ can also be used, but, you need to escape this character twice. Example:
    draw-string 10,10, "Hello world!"

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

fill-arc x1,y1,x2,y2[,start-angle,end-angle]
    Like draw-arc, but fills the contents of the arc with the currently 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", that sets the fill rule to EvenOddRule or WindingRule, respectively. Example:
    fill-rule winding

fill-style style
    Sets the fill style. Allowed parameters are "solid", "tiled", "stippled" and "opaquestippled", that sets the fill style to FillSolid, FillTiled, FillStippled or FillOpaqueStippled, respectively. 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. Example:
    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", "copyinverted" and "nand", that 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", that sets 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 complex decorations in widgets. Pixmap-spec is as defined in the PIXMAPS section of this manual page, xs and ys are the coodinates from where start copying the pixmap, xe and ye are optional (defaults to xs + pixmap.width and ys + pixmap.height respectively). If the pixmap has a mask, the copy is masked accordingly. 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. Require four arguments. Example:
    line +0,+0, -1,-1

line-width integer
    Allow selecting a different line width for the drawing. Example:
    line-width 2

line-style style
    Sets the line style. Accepted parameters are "solid", "onoffdash" and "doubledash", that sets 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 arguments may be supplied. 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. Example:
    point +10,+10

plane-mask integer
    Allows setting the plane mask. Requires a 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. Number of parameters must be multiple of 4. Example:
    segments +1,+2,+1,-3, +2,-2,-3,-2

shape-mode mode
    Allows setting the shape mode used in fill-polygon. Accepted parameters are "complex", "convex" or "nonconvex", that sets the shape mode to Complex, Convex or Nonconvex, accordingly. Example:
    shape-mode convex

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

subwindow-mode mode
    Sets the subwindow mode in the GC. Accepted parameters are "includeinferiors" and "clipbychildren", that sets the subwindow mode to IncludeInferiors or ClipByChildren, respectively. Example:
    subwindow-mode includeinferiors

tile pixmap-spec
    Sets the pixmap for the tile. Requires a pixmap parameter, as described in the PIXMAPS section of this man page. 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, when it was 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 was added to Xaw. This converter is meant to be extended, and has enough abstraction to allow loading several image formats. It uses a format that resembles a URL, with the syntax:
[type:]name[?arg=val[{&}...]]
Type actually can be one of bitmap, gradient or xpm.
Name may be a file name, or, in the case of type gradient, may be either vertical or horizontal.
Arg=val is a list of arguments to the converter. The most common arguments are foreground and background. Gradients supports also the arguments start and end (colors to start and end the gradient); the steps argument, to allow using less colors; and the size argument to specify the size of the gradient. The xpm converter understands the closeness argument, that helps using less 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. The text widget is based in the emacs text editor. In this release, the emacs compatibility was increased. New text actions include:

indent
    This action allow indenting text blocks. It is not enabled by default. A translation to call this action was added to the xedit editor, binded to Control<Key>X,<Key>Tab.

keyboard-reset
    Resets the keyboard state. Reverts the multiply to 1, and if undo is enabled, toggle between undo and redo. Binded 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 to cut and paste internally to the program between text fields. The default key binding to this actions is Meta<Key>Y.

numeric
    Listed here only for purposes of documentation. It is called by default when one of the characters 1, 2, 3, 4, 5, 6, 7, 8, 9, 0, or - is typed, allowing composing the multiplication number of text actions.

set-keyboard-focus
    This action is normally binded to the <Btn1Down> event. Will set the input focus on the top level widget to the text field. Not enabled by default.

toggle-overwrite
    This action toggles overwrite mode. In overwrite mode, any text inserted in a text field will replace existing text. Normally binded to <Key>Insert.

undo
    Binded by default to Control<Key>_, will call the undo function. Undo is not enabled by default. It is enabled setting the enableUndo resource of the textSrcObject.

The new text resources include:

justify (Class Justify)
    Sets the text justification. Can be one of left, right, center 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 to break text. Text lines started with a alphanumeric character will automatically start at this column.

positionCallback (Class Callback)
    Allows installing a callback that will be called every time the cursor is moved and/or the file change its size. The callback is called with a pointer 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 to write text editors based on the Xaw widget set.

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

TEXT SOURCE OBJECT
The textSrcObject was modified to allow showing its contents in more than one window, and also store undo information. The new resources for the textSrcObject are:

callback (Class Callback)
    Previous versions of Xaw had this resource in the subclasses. 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, it was on the subclasses on previous versions. Now it is in the textSrcObject to control the changed/unchanged state, when undo is enabled.

TEXT SINK OBJECT
The textSinkObject subclasses asciiSinkObject and multiSinkObject were slightly changed to offer a new cursor shape, that indicates the input focus of the text widget and allow setting its color. The new resource is:

cursorColor (Class Color)
    Allows setting 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 was changed to enable multiple columns when one single column does not fit in the screen. It was also modified to enable sub menus.

SME BSB OBJECT
A new resource was added to the smeBSBObject, to allow binding sub menus to it. The new resource is:

menuName (Class MenuName)
    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.

RESTRICTIONS
Xaw is actually being actively worked. Programs intending to be fully compatible with future releases of the Xaw library should use only the public interfaces. While widget subclassification is not a bad, and some times encouraged programming practice, programs that access private data structures may have problems with newer releases, in the current stage of the Xaw development. Several efforts are being done to avoid such problems, and, at least, guarantee that newer releases will be source and binary compatible.

AUTHORS
The XFree86 additions and modifications to Xaw, were written by Paulo Cesar Pereira de Andrade