Unix/Linux Go Back    


X11R7.4 - man page for xaw (x11r4 section 3)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


Xaw(3)											   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 modifications  originally  made	for  The  XFree86
       Project,  Inc.	This  manual  page  describes these changes as well as some of the common
       interfaces between its version and the previous X Consortium release (Xaw6).

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(wid-
       get)), 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  vari-
	       able-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 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 of the Xaw widgets have now the additional resource displayList.  This resource allows
       drawing	the  widget  decorations  using commands embedded in a resource string.  The dis-
       playList 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 {+-}<integer> or <integer>/<integer>.  Exam-
       ples:
	    +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.   Exam-
	       ple:
	       background red

       cap-style style
	       Sets the cap style.  Accepted styles are "notlast", "butt", "round", and "project-
	       ing", which set 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 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 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 CoordMode-
	       Origin 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 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 contents;  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 enclosing 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 coordi-
	       nate 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".  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 fore-
	       ground.	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  fore-
	       ground 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 WindingRule, 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, 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", 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  complex  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  default 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.   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", "onoffdash" and "dou-
	       bledash", 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 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, a coordinate pair.  Example:
	       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 subwindow mode to IncludeInferiors or  ClipByChil-
	       dren, 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  coordi-
	       nate.  Example:
	       ts-origin 10,10

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

       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 several 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 either vertical or hori-
       zontal.

       Arg=val	is a list of arguments to the converter.  An argument list is preceded by a ques-
       tion 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 gradient.	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 auto-
       matic resizing of the widget to a larger geometry created other problems, making it diffi-
       cult  to  have  a consistent layout in the application, 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 modi-
       fied 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 default when one of the
	       characters  1,  2,  3, 4, 5, 6, 7, 8, 9, 0, or - is typed, allowing composition of
	       the multiplication number 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, center, or full.  Only
	       enabled when the autoFill resource is set, and the resources leftColumn and right-
	       Column 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 callback 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 editors based on the  Xaw
	       widget set.

       resize (Class Resize)
	       No longer supported, but recognized for backward compatibility with resource spec-
	       ifications 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 XawtextScroll-
	       Never.	A converter is registered for this resource that will convert the follow-
	       ing 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 window, 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   textSrcObject   to   control   the
	       changed/unchanged state when undo is enabled.

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 submenus  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 documentation were the
       work of many people, including Chris D. Peterson, Ralph Swick, Mark Ackerman,  Donna  Con-
       verse,  Jim  Fulton,  Loretta  Guarino-Reid,  Charles Haynes, Rich Hyde, Mary Larson, Joel
       McCormack, Ron Newman, Jeanne Rich, Terry Weissman, Mike Gancarz, Phil  Karlton,  Kathleen
       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 Cesar Pereira de Andrade.

SEE ALSO
       Athena Widget Set - C Language Interface

X Version 11				   libXaw 1.0.5 				   Xaw(3)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 06:24 AM.