XAW(3)XAW(3)NAME
XAW - X Athena Widgets
DESCRIPTIONXaw is a Widget set based on the Xt Intrinsics. This man-
ual page describes the XFree86 additions and modifications
to the Xaw library, as well as some of the common inter-
faces.
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 vari-
able 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 wid-
get. 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)
XFree86 Version 3.9 1
XAW(3)XAW(3)DISPLAY LISTS
All the Xaw widgets have now the additional resource dis-
playList. This resource allows drawing the widget decora-
tions 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 coor-
dinate, the syntax is {+-}<integer> or <integer>/<inte-
ger>. 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 "pies-
lice" and "chord", that sets the arc to ArcPieS-
lice 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 "not-
last", "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 sec-
tion of this man page. Example:
clip-mask xlogo11
clip-origin x,y
Sets the clip x and y origin. Requires two argu-
ments, 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.
XFree86 Version 3.9 2
XAW(3)XAW(3)
The arguments are coordinates. The parser calcu-
lates 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 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 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. Exam-
ple:
draw-rect +1,+1,-5,-5
XFree86 Version 3.9 3
XAW(3)XAW(3)
draw-string x,y,"string"
Draws a text string. Requires three argu-
ments, 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 char-
acter 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. Exam-
ple:
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
XFree86 Version 3.9 4
XAW(3)XAW(3)
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, respec-
tively. 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
XFree86 Version 3.9 5
XAW(3)XAW(3)
sets the line style to LineSolid, LineOnOff-
Dash 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 back-
ground 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 coordi-
nates. 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 parame-
ters 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
XFree86 Version 3.9 6
XAW(3)XAW(3)
"clipbychildren", that sets the subwindow mode
to IncludeInferiors or ClipByChildren, respec-
tively. 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 con-
verter 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
XFree86 Version 3.9 7
XAW(3)XAW(3)
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 aut-
oFill resource is set, and the resources leftCol-
umn 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
XFree86 Version 3.9 8
XAW(3)XAW(3)
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 con-
tents in more than one window, and also store undo infor-
mation. 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 sub-
classes 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 multi-
SinkObject 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
XFree86 Version 3.9 9
XAW(3)XAW(3)
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.
RESTRICTIONSXaw 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 develop-
ment. Several efforts are being done to avoid such prob-
lems, 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
XFree86 Version 3.9 10
