_________________________________________________________XawPlus

The Form Widget

Application Header file
Class Header file
Class
Class Name
Superclass

<X11/XawPlus/Form.h>
<X11/XawPlus/FormP.h>
formWidgetClass
Form
Constraint

The Form widget can contain an arbitrary number of children or subwidgets. The Form provides geometry management for its children, which allows individual control of the position of each child. Any combination of children can be added to a Form. The initial positions of the children may be computed relative to the positions of previously created children. When the Form is resized, it computes new positions and sizes for its children. This computation is based upon information provided when a child is added to the Form.

The default width of the Form is the minimum width needed to enclose the children after computing their initial layout, with a margin of defaultDistance at the right and bottom edges. If a width and height is assigned to the Form that is too small for the layout, the children will be clipped by the right and bottom edges of the Form.

Differences between Xaw and XawPlus

The default background color is grey75.

Resources

When creating a Form widget instance, the following resources are retrieved from the argument list of XtSetValues() or XtVaSetValues() or from the resource database:

Name	Class	Type	Default Value
OBJECT:
destroyCallback	Callback	Pointer	NULL
RECTANGLE:
borderWidth height sensitive width x y	BorderWidth Height Sensitive Width Position Position	Dimension Dimension Boolean Dimension Position Position	1 Space for all children True Space for all children 0 0
CORE:
border background mappedWhenManaged	BorderColor Background MappedWhenManaged	Pixel Pixel Boolean	XtDefaultForeground grey75 True
FORM:
defaultDistance	Thickness	int	4

defaultDistance

The default internal spacing for the children. This is the default value for constrained resources horizDistance and vertDistance.

Constraint Resources

Each child of the Form widget may request special layout resources be applied to it. These constraint resources allow the Form widget's children to specify individual layout requirements.

Name	Class	RepType	Default Value
bottom fromHoriz fromVert horizDistance left resizable right top vertDistance	Edge Widget Widget Thickness Edge Boolean Edge Edge Thickness	XtEdgeType Widget Widget int XtEdgeType Boolean XtEdgeType XtEdgeType int	XtRubber (left edge of form) (top of form) defaultDistance XtRubber False XtRubber XtRubber defaultDistance

Layout Semantics

XawRubber Rubber Edges will move a proportional distance

Edge Type	Resource Name	Description
XawChainBottom	ChainBottom	Edge remains a fixed distance from bottom of Form
XawChainLeft	ChainLeft	Edge remains a fixed distance from left of Form
XawChainRight	ChainRight	Edge remains a fixed distance from right of Form
XawChainTop	ChainTop	Edge remains a fixed distance from top of Form

Example

If you wish to force the Form to never resize one or more of its children, then set left and right to XawChainLeft and top and bottom to XawChainTop. This will cause the child to remain a fixed distance from the top and left edges of the Form, and never to resize.

Convenience Routines

To force or defer a re-layout of the Form, use XawFormDoLayout().

void XawFormDoLayout(w, do_layout)
Widget w;
Boolean do_layout;

w Specifies the Form widget.

do_layout Specifies whether the layout of the Form widget is enabled (True) or disabled (False).

When making several changes to the children of a Form widget after the Form has been realized, it is a good idea to disable relayout until after all changes have been made.

XawPlus_________________________________________________________

XawPlusDoc/Dialog.html The Dialog Widget

_________________________________________________________XawPlus

The Dialog Widget

Application Header file
Class Header file
Class
Class Name
Superclass

<X11/XawPlus/Dialog.h>
<X11/XawPlus/DialogP.h>
dialogWidgetClass
Dialog
Form

The Dialog widget implements a commonly used interaction semantic to prompt for auxiliary input from a user. For example, you can use a Dialog widget when an application requires a small piece of information, such as a filename, from the user. A Dialog widget, which is simply a special case of the Form widget, provides a convenient way to create a preconfigured form.

The typical Dialog widget contains three areas. The first line contains a description of the function of the Dialog widget, for example, the string Filename:. The second line contains an area into which the user types input. The third line can contain buttons that let the user confirm or cancel the Dialog input. Any of these areas may be omitted by the application.

Differences between Xaw and XawPlus

Since release 2.1 of XawPlus Dialog has installed pixmap converters for the icon and a clip mask for nonrectangular color icons. A new resource clipMask is added.

Resources

When creating a Dialog widget instance, the following resources are retrieved from the argument list of XtSetValues() or XtVaSetValues() or from the resource database:

Name	Class	Type	Default Value
OBJECT:
destroyCallback	Callback	Pointer	NULL
RECTANGLE:
borderWidth height sensitive width x y	BorderWidth Height Sensitive Width Position Position	Dimension Dimension Boolean Dimension Position Position	1 Space for all children True Space for all children 0 0
CORE:
border background mappedWhenManaged	BorderColor Background MappedWhenManaged	Pixel Pixel Boolean	XtDefaultForeground grey75 True
FORM:
defaultDistance	Thickness	int	4
DIALOG:
icon clipMask label value	Pixmap Pixmap Label Value	Bitmap ClipMask String String	None None NULL NULL

icon	A pixmap image to be displayed immediately to the left of the Dialog widget's label.
label	A Latin1 string to be displayed at the top of the Dialog widget.
value	An initial value for the string field that the user will enter text into. By default, no text entry field is available to the user. Specifying an initial value for value activates the text entry field. If string input is desired, but no initial value is to be specified then set this resource to "" (empty string).

Constraint Resources

Each child of the Dialog widget may request special layout resources be applied to it. These constraint resources allow the Dialog widget's children to specify individual layout requirements.

Name	Class	RepType	Default Value
bottom fromHoriz fromVert horizDistance left resizable right top vertDistance	Edge Widget Widget Thickness Edge Boolean Edge Edge Thickness	XtEdgeType Widget Widget int XtEdgeType Boolean XtEdgeType XtEdgeType int	XtRubber (left edge of form) (top of form) defaultDistance XtRubber False XtRubber XtRubber defaultDistance

Layout Semantics

Edge Type	Resource Name	Description
XawChainBottom	ChainBottom	Edge remains a fixed distance from bottom of Dialog
XawChainLeft	ChainLeft	Edge remains a fixed distance from left of Dialog
XawChainRight	ChainRight	Edge remains a fixed distance from right of Dialog
XawChainTop	ChainTop	Edge remains a fixed distance from top of Dialog
XawRubber	Rubber	Edges will move a proportional distance

Example

If you wish to force the Dialog to never resize one or more of its children then set left and right to XawChainLeft and top and bottom to XawChainTop. This will cause the child to remain a fixed distance from the top and left edges of the Dialog, and to never resize.

Special Considerations

The Dialog widget automatically sets the top and bottom resources for all Children that are subclasses of the Command widget, as well as the widget children that are used to contain the label, value, and icon. This policy allows the buttons at the bottom of the Dialog to interact correctly with the predefined children, and makes it possible for a client to simply create and manage a new Command button without having to specify its constraints.

The Dialog will also set fromLeft to the last button in the Dialog for each new button added to the Dialog widget.

The automatically added constraints cannot be overridden, as they are policy decisions of the Dialog widget. If a more flexible Dialog is desired, the application is free to use the Form widget to create its own Dialog policy.

Automatically Created Children

The Dialog uses Label widgets to contain the label and icon. These widgets are named label and icon respectively. The Dialog value is contained in an AsciiText widget whose name is value. Using XtNameToWidget the application can change those resources associated with each of these widgets that are not available through the Dialog widget itself.

Convenience Routines

To return the character string in the text field, use XawDialogGetValueString():

String XawDialogGetValueString(w)
Widget w;

w	Specifies the Dialog widget.

This function returns a copy of the value string of the Dialog widget. This string is allocated by the AsciiText widget and will remain valid and unchanged until another call to XawDialogGetValueString() or an XtGetValues() call on the value widget, when the string will be automatically freed, and a new string is returned. This string may be freed earlier by calling the function XawAsciiSourceFreeString().

To add a new button to the Dialog widget use XawDialogAddButton().

void XawDialogAddButton(w, name, func, client_data)
Widget w;
String name;
XtCallbackProc func;
XtPointer client_data;

w	Specifies the Dialog widget.
name	Specifies the name of the new Command button to be added to the Dialog.
func	Specifies a callback function to be called when this button is activated. If NULL is specified then no callback is added.
client_data	Specifies the client_data to be passed to the func.

This function is merely a shorthand for the code sequence:

Widget button = XtCreateManagedWidget(name, commandWidgetClass, w, NULL, ZERO);
XtAddCallback(button, XtNcallback, func, client_data);

XawPlus_________________________________________________________

XawPlusDoc/Viewport.html The Viewport Widget

_________________________________________________________XawPlus

The Viewport Widget

Application Header file
Class Header file
Class
Class Name
Superclass

<X11/XawPlus/Viewport.h>
<X11/XawPlus/ViewportP.h>
viewportWidgetClass
Viewport
Form

The Viewport widget consists of a frame window, one or two Scrollbars, and an inner window. The size of the frame window is determined by the viewing size of the data that is to be displayed and the dimensions to which the Viewport is created. The inner window is the full size of the data that is to be displayed and is clipped by the frame window. The Viewport widget controls the scrolling of the data directly. No application callbacks are required for scrolling.

When the geometry of the frame window is equal in size to the inner window, or when the data does not require scrolling, the Viewport widget automatically removes any scrollbars. The forceBars option causes the Viewport widget to display all scrollbars permanently.

Differences between Xaw and XawPlus

Since XawPlus release 1.4 the scrollbars are placed at bottom and right side of the window. The default values of the resources useBottom and useRight changes from False to True.

Resources

When creating a Viewport widget instance, the following resources are retrieved from the argument list of XtSetValues() or XtVaSetValues() or from the resource database:

Name	Class	Type	Default Value
OBJECT:
destroyCallback	Callback	Pointer	NULL
RECTANGLE:
borderWidth height sensitive width x y	BorderWidth Height Sensitive Width Position Position	Dimension Dimension Boolean Dimension Position Position	1 Space for all children True Space for all children 0 0
CORE:
border background mappedWhenManaged	BorderColor Background MappedWhenManaged	Pixel Pixel Boolean	XtDefaultForeground grey75 True
FORM:
defaultDistance	Thickness	int	4
VIEWPORT:
allowHoriz allowVert foreceBars reportCallback useBottom useRight	Boolean Boolean Boolean ReportCallback Boolean Boolean	Boolean Boolean Boolean Pointer Boolean Boolean	False False False NULL True True

allowHoriz allowVert	If these resources are False then the Viewport will never create a scrollbar in this direction. If it is True then the scrollbar will only appear when it is needed, unless forceBars is True.
forceBars	When this resource ist set to True, the scrollbars that have been allowed will always be visible on the screen. If False the scrollbars will be visible only when the inner window is larger than the frame.
reportCallback	These callbacks will be executed whenever the Viewport adjusts the viewed area of the child. The call_data parameter is a pointer to an XawPannerReport structure.
useBottom useRight	By default the scrollbars appear on the right and bottom of the screen. These resources allow the vertical scrollbar to be placed on the left edge of the Viewport, and the horizontal scrollbar on the top edge of the Viewport.

Layout Semantics

The Viewport widget manages a single child widget. When the size of the child is larger than the size of the Viewport, the user can interactively move the child within the Viewport by repositioning the scrollbars.

The default size of the Viewport before it is realized is the width and/or height of the child. After it is realized, the Viewport will allow its child to grow vertically or horizontally if allowVert or allowHoriz are set, respectively. If the corresponding vertical or horizontal scrollbar is not enabled, the Viewport will propagate the geometry request to its own parent and the child will be allowed to change size only if the Viewport's parent allows it. Regardless of whether or not scrollbars are enabled in the corresponding direction, if the child requests a new size smaller than the Viewport size, the change will be allowed only if the parent of the Viewport allows the Viewport to shrink to the appropriate dimension.

The scrollbar children of the Viewport are named horizontal and vertical. By using these names the programmer can specify resources for the individual scrollbars. XtSetValues() can be used to modify the resources dynamically once the widget ID has been obtained with XtNameToWidget().

Although the Viewport is a Subclass of the Form, no resources for the Form may be supplied for any of the children of the Viewport. These constraints are managed internally, and are not meant for public consumption.

XawPlus_________________________________________________________

XawPlusDoc/TextFuncs.html Text Functions

_________________________________________________________XawPlus

Text Functions

The following functions are provided as convenience routines for use with the Text widget. Although many of these actions can be performed by modifying resources, these interfaces are frequently more efficient.

These data structures are defined in the Text widget's public header file, <X11/Xaw/Text.h>.

typedef long XawTextPosition;

Character positions in the Text widget begin at 0 and end at n+1, where n is the number of characters in the Text source widget.

typedef struct {

int firstPos;
int length;
char *ptr;
unsigned long format;

} XawTextBlock, *XawTextBlockPtr;

firstPos	The first position, or index, to use within the ptr field. The value is commonly zero.
length	The number of characters to be used from the ptr field. The number of characters used is commonly the number of characters in ptr, and must not be greater than the length of the string in ptr.
ptr	Contains the string to be referenced by the Text widget.
format	This field is not currently used, but should be specified as XawFmt8Bit.

Selecting Text

To select a piece of text, use XawTextSetSelection():

void XawTextSetSelection(w, left, right)
Widget w;
XawTextPosition left, right;

w	Specifies the Text widget.
left	Specifies the character position at which the selection begins.
right	Specifies the character position at which the selection ends.

If redisplay is enabled, this function highlights the text and makes it the PRIMARY selection. This function does not have any effect on CUT_BUFFER0.

Unhighlighting Text

To unhighlight previously highlighted text in a widget, use XawTextUnsetSelection():

void XawTextUnsetSelection(w)
Widget w;

w	Specifies the Text widget.

Getting Current Text Selection

To retrieve the text that has been selected by this text widget use XawTextGetSelectionPos():

void XawTextGetSelectionPos(w, begin_return, end_return)
Widget w;
XawTextPosition *begin_return, *end_return;

w	Specifies the Text widget.
begin_return	Returns the beginning of the text selection.
end_return	Returns the end of the text selection.

If the returned values are equal, no text is currently selected.

Replacing Text

To modify the text in an editable Text widget use XawTextReplace():

int XawTextReplace(w, start, end, text)
Widget w;
XawTextPosition start, end;
XawTextBlock *text;

w	Specifies the Text widget.
start	Specifies the starting character position of the text replacement.
end	Specifies the ending character position of the text replacement.
text	Specifies the text to be inserted into the file. This function will not be able to replace text in read-only text widgets. It will also only be able to append text to an append-only text widget.

This function may return the following values:

XawEditDone	The text replacement was successful.
XawPositionError	The edit mode is XawtextAppend and start is not the position of the last character of the source.
XawEditError	Either the Source was read-only or the range to be deleted is larger than the length of the Source.

The XawTextReplace arguments start and end represent the text source character positions for the existing text that is to be replaced by the text in the text block. The characters from start up to but not including end are deleted, and the characters specified on the text block are inserted in their place. If start and end are equal, no text is deleted and the new text is inserted after start.

Searching for Text

To search for a string in the Text widget, use XawTextSearch():

XawTextPosition XawTextSearch(w, dir, text)
Widget w;
XawTextScanDirection dir;
XawTextBlock *text;

w	Specifies the Text widget.
dir	Specifies the direction to search in. Legal values are XawsdLeft and XawsdRight.
text	Specifies a text block structure that contains the text to search for.

The XawTextSearch() function will begin at the insertion point and search in the direction specified for a string that matches the one passed in text. If the string is found the location of the first character in the string is returned. If the string could not be found then the value XawTextSearchError is returned.

Redisplaying Text

To redisplay a range of characters, use XawTextInvalidate():

void XawTextInvalidate(w, from, to)
Widget w;
XawTextPosition from, to;

w	Specifies the Text widget.
from	Specifies the start of the text to redisplay.
to	Specifies the end of the text to redisplay.

The XawTextInvalidate function causes the specified range of characters to be redisplayed immediately if redisplay is enabled or the next time that redisplay is enabled.

To enable redisplay, use XawTextEnableRedisplay():

void XawTextEnableRedisplay(w)
Widget w;

w	Specifies the Text widget.

The XawTextEnableRedisplay() function flushes any changes due to batched updates when XawTextDisableRedisplay() was called and allows future changes to be reflected immediately.

To disable redisplay while making several changes, use XawTextDisableRedisplay().

void XawTextDisableRedisplay(w)
Widget w;

w	Specifies the Text widget.

The XawTextDisableRedisplay() function causes all changes to be batched until either XawTextDisplay() or XawTextEnableRedisplay() is called. To display batched updates, use XawTextDisplay():

void XawTextDisplay(w)
Widget w;

w	Specifies the Text widget.

The XawTextDisplay() function forces any accumulated updates to be displayed.

Resources Convenience Routines

To obtain the character position of the left-most character on the first line displayed in the widget (the value of the displayPosition resource), use XawTextTopPosition().

XawTextPosition XawTextTopPosition(w)
Widget w;

w	Specifies the Text widget.

To assign a new selection array to a text widget use XawTextSetSelectionArray():

void XawTextSetSelectionArray(w, sarray)
Widget w;
XawTextSelectType *sarray;

w	Specifies the Text widget.
sarray	Specifies a selection array as defined in the section called Text Selections for Application Programmers.

Calling this function is equivalent to setting the value of the selectionTypes resource.

To move the insertion point to the specified source position, use XawTextSetInsertionPoint():

void XawTextSetInsertionPoint(w, position)
Widget w;
XawTextPosition position;

w	Specifies the Text widget.
position	Specifies the new position for the insertion point.

The text will be scrolled vertically if necessary to make the line containing the insertion point visible. Calling this function is equivalent to setting the insertPosition resource.

To obtain the current position of the insertion point, use XawTextGetInsertionPoint():

XawTextPosition XawTextGetInsertionPoint(w)
Widget w;

w	Specifies the Text widget.

The result is equivalent to retrieving the value of the insertPosition resource.

To replace the text source in the specified widget, use XawTextSetSource():

void XawTextSetSource(w, source, position)
Widget w;
Widget source;
XawTextPosition position;

w	Specifies the Text widget.
source	Specifies the text source object.
position	Specifies character position that will become the upper left hand corner of the displayed text. This is usually set to zero.

A display update will be performed if redisplay is enabled.

To obtain the current text source for the specified widget, use XawTextGetSource():

Widget XawTextGetSource(w)
Widget w;

w	Specifies the Text widget.

This function returns the text source that this Text widget is currently using.

To enable and disable the insertion point, use XawTextDisplayCaret():

void XawTextDisplayCaret(w, visible)
Widget w;
Boolean visible;

w	Specifies the Text widget.
visible	Specifies whether or not the caret should be displayed.

If visible is False the insertion point will be disabled. The marker is re-enabled either by setting visible to True, by calling XtSetValues(), or by executing the display-caret action routine.

Differences between Xaw and XawPlus

None.

XawPlus_________________________________________________________

XawPlusDoc/Tree.html The Tree Widget

_________________________________________________________XawPlus

The Tree Widget

Application Header file
Class Header file
Class
Class Name
Superclass

<X11/XawPlus/Tree.h>
<X11/XawPlus/TreeP.h>
treeWidgetClass
Tree
Constraint

The Tree widget provides geometry management of arbitrary widgets arranged in a directed, acyclic graph (i.e., a tree). The hierarchy is contructed by attaching a constraint resource called treeParent to each widget indicating which other node in the tree should be treated as the widget's superior. The structure of the tree is shown by laying out the nodes in the standard format for tree diagrams with lines drawn connecting each node with its children.

The Tree sizes itself according to the needs of its children and is not intended to be resized by its parent. Instead, it should be placed inside another composite widget (such as the Porthole or Viewport) that can be used to scroll around in the tree.

Differences between Xaw and XawPlus

None.

Resources

When creating a Tree widget instance, the following resources are retrieved from the argument list of XtSetValues() or XtVaSetValues() or from the resource database:

Name	Class	Type	Default Value
OBJECT:
destroyCallback	Callback	Pointer	NULL
RECTANGLE:
borderWidth height sensitive width x y	BorderWidth Height Sensitive Width Position Position	Dimension Dimension Boolean Dimension Position Position	1 Space for all children True Space for all children 0 0
CORE:
border background mappedWhenManaged	BorderColor Background MappedWhenManaged	Pixel Pixel Boolean	XtDefaultForeground grey75 True
TREE:
autoReconfigure foreground gravity hSpace lineWidth vSpace	AutoReconfigure Foreground Gravity HSpace LineWidth VSpace	Boolean Pixel XtGravity Dimension Dimension Dimension	FALSE XtDefaultForeground West 20 0 6

autoReconfigure	Whether or not to layout the tree every time a node is added or removed.
gravity	Specifies the side of the widget from which the tree should grow. Valid values include WestGravity, NorthGravity, EastGravity, and SouthGravity.
hSpace vSpace	The amount of space, in pixels, to leave between the children. This resource specifies the amount of space left between the outermost children and the edge of the box.
lineWidth	The width of the lines from nodes that do not have a treeGC constraint resource to their children.

Layout Semantics

Each time a child is managed or unmanaged, the Tree widget will attempt to reposition the remaining children to fix the shape of the tree if the autoReconfigure resource is set. Children at the top (most superior) of the tree are drawn at the side specified by the gravity resource.

After positioning all children, the Tree widget attempts to shrink its own size to the minimum dimensions required for the layout.

Convenience Routines

The most efficient way to layout a tree is to set autoReconfigure to False and then use XawTreeForceLayout() to arrange the children:

void XawTreeForceLayout(w)
Widget w;

w	Specifies the Tree widget.

XawPlus_________________________________________________________

XawPlusDoc/Porthole.html The Porthole Widget

_________________________________________________________XawPlus

The Porthole Widget

Application Header file
Class Header file
Class
Class Name
Superclass

<X11/XawPlus/Porthole.h>
<X11/XawPlus/PortholeP.h>
portholeWidgetClass
Porthole
Composite

The Porthole widget provides geometry management of a list of arbitrary widgets, only one of which may be managed at any particular time. The managed child widget is reparented within the porthole and is moved around by the application (typically under the control of a Panner widget).

Differences between Xaw and XawPlus

The default background color is grey75.

Resources

When creating a Porthole widget instance, the following resources are retrieved from the argument list of XtSetValues() or XtVaSetValues() or from the resource database:

Name	Class	Type	Default Value
OBJECT:
destroyCallback	Callback	Pointer	NULL
RECTANGLE:
borderWidth height sensitive width x y	BorderWidth Height Sensitive Width Position Position	Dimension Dimension Boolean Dimension Position Position	1 see Layout Semantics True see Layout Semantics 0 0
CORE:
border background mappedWhenManaged	BorderColor Background MappedWhenManaged	Pixel Pixel Boolean	XtDefaultForeground grey75 True
PORTHOLE:
reportCallback	ReportCallback	Pointer	NULL

reportCallback

A list of functions to invoke whenever the managed child widget changes size or position.

Layout Semantics

The Porthole widget allows its managed child to request any size that is as large or larger than the Porthole itself and any location so long as the child still obscures all of the Porthole. This widget typically is used together with a Panner widget.

Porthole Callbacks

The functions registered on the reportCallback list are invoked whenever the managed child changes size or position:

void ReportProc(porthole, client_data, report)
Widget porthole;
XtPointer client_data;
XtPointer report;

porthole	Specifies the Porthole widget.
client_data	Specifies the client data.
report	Specifies a pointer to an XawPannerReport structure containing the location and size of the slider and the size of the canvas.

XawPlus_________________________________________________________

XawPlusDoc/TextSink.html The TextSink Object

_________________________________________________________XawPlus

The TextSink Object

Application Header file
Class Header file
Class
Class Name
Superclass

<X11/XawPlus/TextSink.h>
<X11/XawPlus/TextSinkP.h>
textSinkObjectClass
TextSink
Object

The TextSink object is the root object for all text sinks. Any new text sink objects should be subclasses of the TextSink Object. The TextSink Class contains all methods that the Text widget expects a text sink to export.

Since all text sinks will have some resources in common, the TextSink defines a few new resources.

Differences between Xaw and XawPlus

The default background color changes from XtDefaultBackground to grey75.

Resources

When creating a TextSink object instance, the following resources are retrieved from the argument list of XtSetValues() or XtVaSetValues() or from the resource database:

Name	Class	Type	Default Value
OBJECT:
destroyCallback	Callback	Pointer	NULL
TEXTSINK:
foreground background	Foreground Background	Pixel Pixel	XtDefaultForeground grey75

Subclassing the TextSink

The only purpose of the TextSink Object is to be subclassed. It contains the minimum set of class methods that all text sinks must have. While all may be inherited, the direct descendant of TextSink must specify some of them as TextSink does contain enough information to be a valid text sink by itself. Do not try to use the TextSink as a valid sink for the Text widget, it is not intended to be used as a sink by itself and bad things will probably happen.

Function	Public Interface	must specify
DisplayText InsertCursor ClearToBackground FindPosition FindDistance Resolve MaxLines MaxHeight SetTabs GetCursorBounds	XawTextSinkDisplayText XawTextSinkInsertCursor XawTextSinkClearToBackground XawTextSinkFindPosition XawTextSinkFindDistance XawTextSinkResolve XawTextSinkMaxLines XawTextSinkMaxHeight XawTextSinkSetTabs XawTextSinkGetCursorBounds	yes yes no yes yes yes no no no yes

Displaying Text

To display a section of the text buffer contained in the text source use the function DisplayText():

void DisplayText(w, x, y, pos1, pos2, highlight)
Widget w;
Position x, y;
XawTextPosition pos1, pos2;
Boolean highlight;

w	Specifies the TextSink object.
x	Specifies the x location to start drawing the text.
y	Specifies the y location to start drawing text.
pos1	Specifies the location within the text source of the first character to be printed.
pos2	Specifies the location within the text source of the last character to be printed.
highlight	Specifies whether or not to paint the text region highlighted.

The Text widget will only pass one line at a time to the text sink, so this function does not need to know how to line feed the text. It is acceptable for this function to just ignore Carriage Returns. x and y denote the upper left hand corner of the first character to be displayed.

Displaying the Insert Point

The function that controls the display of the text cursor is InsertCursor. This function will be called whenever the text widget desires to change the state of, or move the insert point.

void InsertCursor(w, x, y, state)
Widget w;
Position x, y;
XawTextInsertState state;

w	Specifies the TextSink object.
x	Specifies the x location of the cursor in Pixels.
y	Specifies the y location of the cursor in Pixels.
state	Specifies the state of the cursor, may be one of XawisOn or XawisOff.

x and y denote the upper left hand corner of the insert point.

Clearing Portions of the Text window

To clear a portion of the Text window to its background color, the Text widget will call ClearToBackground(). The TextSink object already defines this function as calling XClearArea() on the region passed. This behavior will be used if you specify XtInheritClearToBackground for this method.

void ClearToBackground(w, x, y, width, height)
Widget w;
Position x, y;
Dimension width, height;

w	Specifies the TextSink object.
x	Specifies the x location, in pixels, of the Region to clear.
y	Specifies the y location, in pixels, of the Region to clear.
width	Specifies the width, in pixels, of the Region to clear.
height	Specifies the height, in pixels, of the Region to clear.

x and y denote the upper left hand corner of region to clear.

Finding a Text Position Given Pixel Values

To find the text character position that will be rendered at a given x location the Text widget uses the function FindPosition():

void FindPosition(w, fromPos, fromX, width, stopAtWordBreak, pos_return, width_return, height_return)
Widget w;
XawTextPosition fromPos;
int fromX, width;
Boolean stopAtWordBreak;
XawTextPosition *pos_return;
int *width_return, *height_return;

w	Specifies the TextSink object.
fromPos	Specifies a reference position, usually the first character in this line. This character is always to the left of the desired character location.
fromX	Specifies the distance that the left edge of fromPos is from the left edge of the window. This is the reference x location for the reference position.
width	Specifies the distance, in pixels, from the reference position to the desired character position.
stopAtWordBreak	Specifies whether or not the position that is returned should be forced to be on a word boundary.
pos_return	Returns the character position that corresponds to the location that has been specified, or the work break immediately to the left of the position if stopAtWordBreak is True.
width_return	Returns the actual distance between fromPos and pos_return.
height_return	Returns the maximum height of the text between fromPos and pos_return.

This function need make no attempt to deal with line feeds. The text widget will only call it one line at a time.

Another means of finding a text position is provided by the Resolve() function:

void Resolve(w, fromPos, fromX, width, pos_return)
Widget w;
XawTextPosition fromPos;
int fromX, width;
XawTextPosition *pos_return;

w	Specifies the TextSink object.
fromPos	Specifies a reference position, usually the first character in this line. This character is always to the left of the desired character location.
fromX	Specifies the distance that the left edge of fromPos is from the left edge of the window. This is the reference x location for the reference position.
width	Specifies the distance, in pixels, from the reference position to the desired character position.
pos_return	Returns the character position that corresponds to the location that has been specified, or the word break immediately to the left if stopAtWordBreak is True.

This function need make no attempt to deal with line feeds. The text widget will only call it one line at a time. This is a more convenient interface to the FindPosition function, and provides a subset of its functionality.

Finding the Distance Between two Text Positions

To find the distance in pixels between two text positions on the same line use the function FindDistance().

void FindDistance(w, fromPos, fromX, toPos, width_return, pos_return, height_return)
Widget w;
XawTextPosition fromPos, toPos;
int fromX;
XawTextPosition *pos_return;
int *width_return, *height_return;

w	Specifies the TextSink object.
fromPos	Specifies the text buffer position, in characters, of the first position.
fromX	Specifies the distance that the left edge of fromPos is from the left edge of the window. This is the reference x location for the reference position.
toPos	Specifies the text buffer position, in characters, of the second position.
resWidth	Return the actual distance between fromPos and pos_return.
resPos	Returns the character position that corresponds to the actual character position used for toPos in the calculations. This may be different than toPos, for example if fromPos and toPos are on different lines in the file.
height_return	Returns the maximum height of the text between fromPos and pos_return.

This function need make no attempt to deal with line feeds. The Text widget will only call it one line at a time.

Finding the Size of the Drawing area

To find the maximum number of lines that will fit into the current Text widget, use the function MaxLines(). The TextSink already defines this function to compute the maximum number of lines by using the height of font.

int MaxLines(w, height)
Widget w;
Dimension height;

w	Specifies the TextSink object.
height	Specifies the height of the current drawing area.

Returns the maximum number of lines that will fit in height.

To find the height required for a given number of text lines, use the function MaxHeight(). The TextSink already defines this function to compute the maximum height of the window by using the height of font.

int MaxHeight(w, lines)
Widget w;
int lines;

w	Specifies the TextSink object.
height	Specifies the height of the current drawing area.

Returns the height that will be taken up by the number of lines passed.

Setting the Tab Stops

To set the tab stops for a text sink use the SetTabs() function. The TextSink already defines this function to set the tab x location in pixels to be the number of characters times the figure width of font.

void SetTabs(w, tab_count, tabs)
Widget w;
int tab_count, *tabs;

w	Specifies the TextSink object.
tab_count	Specifies the number of tabs passed in tabs.
tabs	Specifies the position, in characters, of the tab stops.

This function is responsible for the converting character positions passed to it into whatever internal positions the TextSink uses for tab placement.

Getting the Insert Point's Size and Location

To get the size and location of the insert point use the GetCursorBounds() function.

void GetCursorBounds(w, rect_return)
Widget w;
XRectangle *rect_return;

w	Specifies the TextSink object.
rect_return	Returns the location and size of the insert point.

Rect will be filled with the current size and location of the insert point.

XawPlus_________________________________________________________

XawPlusDoc/AsciiSink.html The Ascii Sink and Mulit Sink Objects

_________________________________________________________XawPlus

The Ascii Sink and Multi Sink Objects

Application Header file	<X11/XawPlus/AsciiSink.h> or <X11/XawPlus/MultiSink.h>
Class Header file	<X11/XawPlus/AsciiSinkP.h> or <X11/XawPlus/MultiSinkP.h>
Class	asciiSinkObjectClass or multiSinkObjectClass
Class Name	AsciiSink or MultiSink
Superclass	TextSink

The AsciiSink or MultiSink object is used by a text widget to render the text. Depending on its international resource, a AsciiText will create one or the other of these when the AsciiText itself is created. Both types are nearly identical; the following discussion applies to both, with MultiSink differences noted only as they occur.

The AsciiText will display all characters in an 8 bit font, along with handling Tab and Carriage Return. The name has left as AsciiSink for compatibility. The MultiSink will display all printing characters in a font set, along with handling Tab and Carriage Return. These objects also reports the text window metrics to the text widgets.

Differences between Xaw and XawPlus

The background color is changed from XtDefaultBackground to grey75.

Resources

When creating a AsciiSink or MultiSink object instance, the following resources are retrieved from the argument list of XtSetValues() or XtVaSetValues() or from the resource database:

Name	Class	Type	Default Value
OBJECT:
destroyCallback	Callback	Pointer	NULL
TEXTSINK OBJECT:
foreground background	Foreground Background	Pixel Pixel	XtDefaultForeground grey75
ASCIISINK OBJECT:
font fontSet echo displayNonprinting	Font FontSet Output Output	XFontStruct * XFontSet Boolean Boolean	XtDefaultFont XtDefaultFontSet True True

font	Only in AsciiSink: The text font to use when displaying the string.
fontSet	Only in MultiSink: The text font set to use when displaying the string.
echo	Whether or not to echo characters to the screen. The buffer can still be edited but nothing is displayed. This mode is useful for entering passwords or other sensitive information.
displayNonprinting	If this resource is True, the Sink object will display all non-printable characters as the string ^@. Otherwise the Sink object will just leave a blank space.

XawPlus_________________________________________________________

XawPlusDoc/AsciiSource.html The Ascii Source and Multi Source Objects

_________________________________________________________XawPlus

The Ascii Source and Multi Source Objects

Application Header file	<X11/XawPlus/AsciiSrc.h> or <X11/XawPlus/MultiSrc.h>
Class Header file	<X11/XawPlus/AsciiSrcP.h> or <X11/XawPlus/MultiSrcP.h>
Class	asciiSrcObjectClass or multiSrcObjectClass
Class Name	AsciiSrc or MultiSrc
Superclass	TextSource

The AsciiSrc or MultiSrc object is used by a text widget to read the text from a file or string in memory. Depending on its international resource an AsciiText widget will create one or the other of thesewhen the AsciiText itself is created. Both types are nearly identical; the following discussion applies to both, with MultiSrc differences noted only if the occur.

The AdciiSrc understands all Latin1 characters plus Tab and Carriage Return. The MultiSrc understands all any set of character sets that the underlying X implementation's internationalization handles.

The AsciiSrc can be either of two types: XawAsciiFile or XawAsciiString. AsciiSrc objects of type XawAsciiFile read the text from a file and store it into an internal buffer. This buffer may then be modified, provided the text widget is in the correct edit mode, just as if it were a source of type XawAsciiString. Unlike R3 and earlier versions of the AsciiSrc, it is now possible to specify an editable disk source. The file is not updated, however, until a call to XawAsciiSave is made. When the source is in this mode the useStringInPlace resource is ignored.

AsciiSrc objects of type XawAsciiString have the text buffer implemented as a string. The string owner is responsible for allocating and managing storage for the string.

In the default case for AsciiSrc objects of type XawAsciiString, the resource useStringInPlace is false, and the widget owns the string. The initial value of the string resource, and any update made by the application programmer to the string resource with XtSetValues(), is copied into memory private to the widget, and managed internally by the widget. The application writer does not need to worry about running out of buffer space (subject to the total memory available to the application). The performance does not decay linearly as the buffer grows large, as is necessarily the case when the text buffer is used in place. The application writer must use XtGetValues() to determine the contents of the text buffer, which will return a copy of the widget's text buffer as it existed at the time of the XtGetValues() call. This copy is not affected by subsequent updates to the text buffer, i.e., it is not updated as the user types input into the text buffer. This copy is freed upon the next call to XtGetValues() to retrieve the string resource; however, to conserve memory, there is a convenience routine, XawAsciiSrcFreeString, allowing the application programmer to direct the widget to free the copy.

When the resource useStringInPlace is true and the AsciiSrc object is of type XawAsciiString, the application is the string owner. The widget will take the value of the string resource as its own text buffer, and the length resource indicates the buffer size. In this case the buffer contents change as the user types at the widget; it is not necessary to call XtGetValues() on the string resource to determine the contents of the buffer -- it will simply return the address of the application's implementation of the text buffer.

Differences between Xaw and XawPlus

None.

Resources

When creating a AsciiSrc object instance, the following resources are retrieved from the argument list of XtSetValues() or XtVaSetValues() or from the resource database:

Name	Class	Type	Default Value
OBJECT:
destroyCallback	Callback	Pointer	NULL
TEXTSRC OBJECT:
editType	EditType	XawTextEditType	XawtextRead
ASCIISRC OBJECT:
callback dataCompression length pieceSize string type useStringInPlace	Callback DataCompression Length PieceSize String Type UseStringInPlace	Callback Boolean int int String XawAsciiType Boolean	(none) True (internal) BUFSIZ NULL XawAsciiString False

Convenience Routines

The AsciiSrc has a few convenience routines that allow the application programmer quicker or easier access to some of the commonly used functionality of the AsciiSrc.

Conserving Memory

When the AsciiSrc widget is not in useStringInPlace mode space must be allocated whenever the file is saved, or the string is requested with a call to XtGetValues(). This memory is allocated on the fly, and remains valid until the next time a string needs to be allocated. You may save memory by freeing this string as soon as you are done with it by calling XawAsciiSrcFreeString():

void XawAsciiSourceFreeString(w)
Widget w;

w	Specifies the AsciiSrc object.

This function will free the memory that contains the string pointer returned by XtGetValues(). This will normally happen automatically when the next call to XtGetValues() occurs, or when the widget is destroyed.

Saving Files

To save the changes made in the current text source into a file use XawAsciiSave():

Boolean XawAsciiSave(w)
Widget w;

w	Specifies the AsciiSrc object.

XawAsciiSave() returns True if the save was successful. It will update the file named in the string resource. If the buffer has not been changed, no action will be taken. This function only works on an AsciiSrc of type XawAsciiFile.

To save the contents of the current text buffer into a named file use XawAsciiSaveAsFile().

Boolean XawAsciiSaveAsFile(w, name)
Widget w;
String name;

w	Specifies the AsciiSrc object.
name	The name of the file to save the current buffer into.

This function returns True if the save was successful. XawAsciiSaveAsFile will work with a buffer of either type XawAsciiString or type XawAsciiFile.

Seeing if the Source has Changed

To find out if the text buffer in an AsciiSrc object has changed since the last time it was saved with XawAsciiSave() or queried use XawAsciiSourceChanged().

Boolean XawAsciiSourceChanged(w)
Widget w;

w	Specifies the AsciiSrc object.

This function will return True if the source has changed since the last time it was saved or queried. The internal change flag is reset whenever the string is queried via XtGetValues() or the buffer is saved via XawAsciiSave().

XawPlus_________________________________________________________

XawPlusDoc/DrawingArea.html The DrawingArea Widget

_________________________________________________________XawPlus

The DrawingArea Widget

Application Header file
Class Header file
Class
Class Name
Superclass

<X11/XawPlus/DrawingArea.h>
<X11/XawPlus/DrawingAreaP.h>
drawingAreaWidgetClass
drawingArea
Simple

The DrawingArea widget adds a backing store machanism to the Simple widget, so it becomes usable as a drawing area. With this backing store DrawingArea is able to handle resize and redisplay events without any action from your application. A set of drawing functions is provided which are equivalent to the Xlib drawing functions, except that these functions work on a DrawingArea widget.

It is possible to use DrawingArea directly, using the drawing functions with their procedural interface. It is also possible (and a good idea) to use this widget as superclass of an application specific drawing widget.

Differences between Xaw and XawPlus

This widget is new in XawPlus and not available with the Xaw widget set.

Resources

When creating a DrawingArea widget instance, the following resources are retrieved from the argument list of XtSetValues() or XtVaSetValues() or from the resource database:

Name	Class	Type	Default Value
OBJECT:
destroyCallback	Callback	Pointer	NULL
RECTANGLE:
borderWidth height sensitive width x y	BorderWidth Height Sensitive Width Position Position	Dimension Dimension Boolean Dimension Position Position	0 12 True 12 0 0
CORE:
border background mappedWhenManaged	BorderColor Background MappedWhenManaged	Pixel Pixel Boolean	XtDefaultForeground grey75 True
SIMPLE:
cursor cursorName pointerColor pointerColorBackground insensitiveBorder international highlightColor shadowColor buttonBorderWidth	Cursor Cursor Foreground Background Insensitive International Background Background Width	Cursor String Pixel Pixel Pixmap Boolean Pixel Pixel Dimension	None NULL XtDefaultForeground XtDefaultBackground NULL False grey90 grey40 2

DrawingArea adds no new resources to the resource list.

Drawing functions

DrawingArea comes with a set of drawing functions. These functions are known from the Xlib. The difference is, that these function work directly on a DrawingArea widget including support of the backing store. That is the reason why you never should try to use the Xlib functions on a DrawingArea widget.

This is not a complete description of the drawing functions. To learn more about these functions take a look to the Xlib reference. To find the equivalent function, replace Xaw with X in the function name.

Function Name	Arguments	Description
XawClearWindow	w	Drawing area widget

Use this function to clear the drawing area.

Function Name	Arguments	Description
XawDrawPoint	w gc x, y	Drawing area widget graphics context coordinates of the point

Use this function to draw a point using the given graphics context gc in the drawing area.

Function Name	Arguments	Description
XawDrawPoints	w gc points[] npoints mode	Drawing area widget graphics context list of point coordinates number of points drawing mode: Relative to origin or previous point

Use this function to draw a set of points using the given gc in the drawing area.

Function Name	Arguments	Description
XawDrawLine	w gc x1, y1 x2, y2	Drawing area widget graphics context starting point end point

Use this function to draw a line using the given gc in the drawing area.

Function Name	Arguments	Description
XawDrawLines	w gc points[] npoints mode	Drawing area widget graphics context list of point coordinates number of points drawing mode: Relative to origin or previous point

Use this function to draw connected lines using the given gc in the drawing area.

Function Name	Arguments	Description
XawDrawSegments	w gc segments[] nsegments	Drawing area widget graphics context list of line coordinates number of segments

Use this function to draw unconnected lines using the given gc in the drawing area.

Function Name	Arguments	Description
XawDrawRectangle	w gc x, y width, height	Drawing area widget graphics context upper left edge of the rectangle widht and height of the rectangle

Use this function to draw a rectangle using the given graphics context gc in the drawing area.

Function Name	Arguments	Description
XawDrawRectangles	w gc rectangles n	Drawing area widget graphics context list of rectangle coordinates number of rectangles

Use this function to draw a set of rectangles using the given graphics context gc in the drawing area.

Function Name	Arguments	Description
XawDrawArc	w gc x, y width, height angle1, angle2	Drawing area widget graphics context center position of the circle/elipsoid widht and height of the circle/elipsoid draw from angle 1 to angle 2

Use this function to draw a circle, an elpsoid or a part of it using the given graphics context gc in the drawing area.

Function Name	Arguments	Description
XawDrawArcs	w gc arcs n	Drawing area widget graphics context parameters of the circles/elipsoids number of circles

Use this function to draw a set of circles using the given graphics context gc in the drawing area.

Function Name	Arguments	Description
XawFillRectangle	w gc x, y width, height	Drawing area widget graphics context upper left edge of the rectangle widht and height of the rectangle

Use this function to draw a filled rectangle using the given graphics context gc in the drawing area.

Function Name	Arguments	Description
XawFillRectangles	w gc rectangles n	Drawing area widget graphics context list of rectangle coordinates number of rectangles

Use this function to draw a set of filled rectangles using the given graphics context gc in the drawing area.

Function Name	Arguments	Description
XawFillArc	w gc x, y width, height angle1, angle2	Drawing area widget graphics context center position of the circle/elipsoid widht and height of the circle/elipsoid draw from angle 1 to angle 2

Use this function to draw a filled circle, a filled elpsoid or a part of it using the given graphics context gc in the drawing area.

Function Name	Arguments	Description
XawFillArcs	w gc arcs n	Drawing area widget graphics context parameters of the circles/elipsoids number of circles

Use this function to draw a set of filled circles using the given graphics context gc in the drawing area.

Function Name	Arguments	Description
XawFillPolygon	w gc points[] npoints shape mode	Drawing area widget graphics context list of point coordinates number of points drawing mode complex, convex or nonconvex relative or absolute coordinates

Use this function to draw a filled polygon using the given gc in the drawing area.

Function Name	Arguments	Description
XawDrawString	w gc x, y str n	Drawing area widget graphics context position of the string in the widget the text string number of characters

Use this function to draw a string on a transparent background using the given graphics context gc in the drawing area.

Function Name	Arguments	Description
XawDrawImageString	w gc x, y str n	Drawing area widget graphics context position of the string in the widget the text string number of characters

Use this function to draw a string with filling the background using the given graphics context gc in the drawing area.

XawPlus_________________________________________________________

XawPlusDoc/Paned.html The Paned Widget

_________________________________________________________XawPlus

The Paned Widget

Application Header file
Class Header file
Class
Class Name
Superclass

<X11/XawPlus/Paned.h>
<X11/XawPlus/PanedP.h>
panedWidgetClass
Paned
Constraint

The Paned widget manages children in a vertically or horizontally tiled fashion. The panes may be dynamically resized by the user by using the grips that appear near the right or bottom edge of the border between two panes.
The Paned widget may accept any widget class as a pane except Grip. Grip widgets have a special meaning for the Paned widget, and adding a Grip as its own pane will confuse the Paned widget.

Differences between Xaw and XawPlus

The Paned widget uses the new color resources intBorderHighlight and intBorderShadow to draw a 3D styled separator line between the managed children. The resource internalBorderColor is not longer supported.

Using the Paned widget

The grips allow the panes to be resized by the user. The semantics of how these panes resize is somewhat complicated, and warrants further explanation here. When the mouse pointer is positioned on a grip and pressed, an arrow is displayed that indicates the pane that is to be to be resized. While keeping the mouse button down, the user can move the grip up and down (or left and right). This, in turn, changes the size of the pane. The size of the Paned widget will not change. Instead, it chooses another pane (or panes) to resize. For more details on which pane it chooses to resize, see Layout Semantics.

One pointer binding allows the border between two panes to be moved, without affecting any of the other panes. When this occurs the pointer will change to an arrow that points along the pane border.

The default bindings for the Paned widget's grips are:

	Pane to Resize	Pane to Resize
Mouse button 1 (left) 2 (middle) 3 (right)	Vertical above the grip adjust border below the grip	Horizontal left of the grip adjust border right of the grip

Resources

When creating a Form widget instance, the following resources are retrieved from the argument list of XtSetValues() or XtVaSetValues() or from the resource database:

Name	Class	Type	Default Value
OBJECT:
destroyCallback	Callback	Pointer	NULL
RECTANGLE:
borderWidth height sensitive width x y	BorderWidth Height Sensitive Width Position Position	Dimension Dimension Boolean Dimension Position Position	1 Space for all children True Space for all children 0 0
CORE:
border background mappedWhenManaged	BorderColor Background MappedWhenManaged	Pixel Pixel Boolean	XtDefaultForeground grey75 True
PANED:
orientation refigureMode intBorderHighlight intBorderShadow gripIndent betweenCursor cursor gripCursor leftCursor lowerCursor rightCursor upperCursor verticalGripCursor verticalBetweenCursor horizontalGripCursor horizontalBetweencursor	Orientation Boolean BorderColor BorderColor GripIndent Cursor Cursor Cursor Cursor Cursor Cursor Cursor Cursor Cursor Cursor Cursor	XtOrientation Boolean Pixel Pixel Position Cursor Cursor Cursor Cursor Cursor Cursor Cursor Cursor Cursor Cursor Cursor	XtorientVertical On grey90 grey40 10 None sb_left_arrow sb_down_arrow sb_right_arrow sb_up_arrow sb_v_double_arrow sb_left_arrow sb_h_double_arrow sb_up_arrow

** These resources now are set to the vertical or horizontal cursor depending upon orientation, by default. If a value is specified here then that cursor will be used reguardless of orientation.

orientation	The orientation to stack the panes. This value can be either XtorientVertical or XtorientHorizontal.
refigureMode	This resource allows pane layout to be suspended. If this value is False, then no layout actions will be taken. This may improve efficiency when adding or removing more than one pane from the Paned widget.
internalBorderWidth	The width of each line of the internal borders. This is the amount of space left between the panes. The class name of this resource allows PanedBorderWidth: 3* to set the total internal border width to 6 for the Paned widget.
intBorderHighlight intBorderShadow	A pixel value which indexes the widget's colormap to derive the internal border colors of the widget's window. The class name of this resource allows to set the internal border colors for the Paned widget.
gripIndent	The amount of space left between the right (or bottom) edge of the Paned widget and all the grips.
cursor	The cursor to use when the mouse pointer is over the Paned widget, but not in any of its children (children may also inherit this cursor). It should be noted that the internal borders are actually part of the Paned widget, not the children.
gripCursor	The cursor to use when the grips are not active. The default value is verticalGripCursor or horizontalGripCursor depending on the orientation of the Paned widget.
gripTranslation	Translation table that will be applied to all grips.
horizontalBetweenCursor verticalBetweenCursor	The cursor to be used for the grip when changing the boundary between two panes. These resources allow the cursors to be different depending on the orientation of the Paned widget.
horizontalGripCursor verticalGripCursor	The cursor to be used for the grips when they are not active. These resources allow the cursors to be different depending on the orientation of the Paned widget.
leftCursor rightCursor	The cursor used to indicate which is the important pane to resize when the Paned widget is oriented horizontally.
lowerCursor upperCursor	The cursor used to indicate which is the important pane to resize when the Paned widget is oriented vertically. This is not the same as the number of panes, since this also contains a grip for some of the panes, use XawPanedGetNumSub() to retrieve the number of panes.

Constraint Resources

Each child of the Paned widget may request special layout resources be applied to it. These constraint resources allow the Form widget's children to specify individual layout requirements.

Name	Class	RepType	Default Value
allowResize max min preferredPaneSize resizeToPreferred showGrip skipAdjust	Boolean Max Min PerferredPaneSize Boolean ShowGrip Boolean	Boolean Dimension Dimension Dimension Boolean Boolean Boolean	False unlimited Grip Size PANED_ASK_CHILD False True False

allowResize	If this value is False the the Paned widget will disallow all geometry requests from this child.
max, min	The absolute maximum or minimum size for this pane. These values will never be overridden by the Paned widget. This may cause some panes to be pushed off the bottom (or right) edge of the paned widget.
preferredPaneSize	Normally the paned widget makes a QueryGeometry call on a child to determine the preferred size of the child's pane. There are times when the application programmer or the user has a better idea of the preferred size of a pane. Setting this resource causes the value passed to be interpreted as the preferred size, in pixels, of this pane.
resizeToPreferred	Determines whether or not to resize each pane to its preferred size when the Paned widget is resized. See Layout Semantics for details.
showGrip	If True then a grip will be shown for this pane. The grip associated with a pane is either below or to the right of the pane. No grip is ever shown for the last pane.
skipAdjust	This resource is used to determine which pane is forced to be resized. Setting this value to True makes this pane less likely to be forced to be resized. See Layout Semantics for details.

Layout Semantics

In order to make effective use of the Paned widget it is helpful to know the rules it uses to determine which child will be resized in any given situation. There are three rules used to determine which child is resized. While these rules are always the same, the panes that are searched can change depending upon what caused the relayout.

Layout Rules

Do not let a pane grow larger than its max or smaller than its min.
Do not adjust panes with skipAdjust set.
Do not adjust panes away from their preferred size, although moving one closer to its preferred size is fine.

When searching the children the Paned widget looks for panes that satisfy all the rules, and if unsuccessful then it eliminates rule 3 and then 2. Rule 1 is always enforced.

If the relayout is due to a resize or change in management then the panes are searched from bottom to top. If the relayout is due to grip movement then they are searched from the grip selected in the direction opposite the pane selected.

Resizing Panes from a Grip Action

The pane above the grip is resized by invoking the GripAction with UpLeftPane specified. The panes below the grip are each checked against all rules, then rules 2 and 1 and finally against rule 1 only. No pane above the chosen pane will ever be resized.

The pane below the grip is resized by invoking the GripAction with LowRightPane specified. The panes above the grip are each checked in this case. No pane below the chosen pane will ever be resized.

Invoking GripAction with ThisBorderOnly specified just moves the border between the panes. No other panes are ever resized.

Resizing Panes after the Paned widget is resized

When the Pane widget is resized it must determine a new size for each pane. There are two methods of doing this. The Paned widget can either give each pane its preferred size and then resize the panes to fit, or it can use the current sizes and then resize the panes to fit. The resizeToPreferred resource allows the application to tell the Paned widget whether to query the child about its preferred size (subject to the the preferredPaneSize) or to use the current size when refiguring the pane locations after the pane has been resized.

There is one special case. All panes assume they should resize to their preferred size until the Paned widget becomes visible to the user.

Managing Children and Geometry Management

The Paned widget always resizes its children to their preferred sizes when a new child is managed, or a geometry management request is honored. The Paned widget will first attempt to resize itself to contain its panes exactly. If this is not possible then it will hunt through the children, from bottom to top (right to left), for a pane to resize.

Special Considerations

When a user resizes a pane with the grips, the Paned widget assumes that this new size is the preferred size of the pane.

Grip Translations

The Paned widget has no action routines of its own, as all actions are handled through the grips. The grips are each assigned a default Translation table.

GripAction(Start, UpLeftPane)
GripAction(Start, ThisBorderOnly)
GripAction(Start, LowRightPane)
GripAction(Move, UpLeftPane)
GripAction(Move, ThisBorderOnly)
GripAction(Move, LowRightPane)
GripAction(Commit)

The Paned widget interprets the GripAction as taking two arguments. The first argument may be any of the following:

Start	Sets up the Paned widget for resizing and changes the cursor of the grip. The second argument determines which pane will be resized, and can take on any of the three values shown above.
Move	The internal borders are drawn over the current pane locations to animate where the borders would actually be placed if you were to move this border as shown. The second argument must match the second argument that was passed to the Start action, that began this process. If these arguments are not passed, the behavior is undefined.
Commit	This argument causes the Paned widget to commit the changes selected by the previously started action. The cursor is changed back to the grip's inactive cursor. No second argument is needed in this case.

Convenience Routines

To enable or disable a child's request for pane resizing, use XawPanedAllowResize():

void XawPanedAllowResize(w, allow_resize)
Widget w;
Boolean allow_resize;

w	Specifies the child pane.
allow_resize	Specifies whether or not resizing requests for this child will be granted by the Paned widget.

If allow_resize is True, the Paned widget allows geometry requests from the child to change the pane's height. If allow_resize is False, the Paned widget ignores geometry requests from the child to change the pane's height. The default state is True before the Pane is realized and False after it is realized. This procedure is equivalent to changing the allowResize constraint resource for the child.

To change the minimum and maximum height settings for a pane, use XawPanedSetMinMax():

void XawPanedSetMinMax(w, min, max)
Widget w;
int min, max;

w	Specifies the child pane.
min	Specifies the new minimum height of the child, expressed in pixels.
max	Specifies new maximum height of the child, expressed in pixels.

This procedure is equivalent to setting the min and max constraint resources for the child.

To retrieve the minimum and maximum height settings for a pane, use XawPanedGetMinMax():

void XawPanedGetMinMax(w, min_return, max_return)
Widget w;
int *min_return, *max_return;

w	Specifies the child pane.
min_return	Returns the minimum height of the child, expressed in pixels.
max_return	Returns the maximum height of the child, expressed in pixels.

This procedure is equivalent to getting the min and max resources for this child.

To enable or disable automatic recalculation of pane sizes and positions, use XawPanedSetRefigureMode():

void XawPanedSetRefigureMode(w, mode)
Widget w;
Boolean mode;

w	Specifies the Paned widget.
mode	Specifies whether the layout of the Paned widget is enabled (True) or disabled (False).

When making several changes to the children of a Paned widget after the Paned has been realized, it is a good idea to disable relayout until after all changes have been made.

To retrieve the number of panes in a paned widget use XawPanedGetNumSub():

int XawPanedGetNumSub(w)
Widget w;

w	Specifies the Paned widget,

This function returns the number of panes in the Paned widget. This is not the same as the number of children, since the grips are also children of the Paned widget.

XawPlus_________________________________________________________

XawPlusDoc/index.html Index of the XawPlus documentation

_________________________________________________________XawPlus

The XawPlus 3.0 Documentation

This set of documents describes the features and usage of XawPlus. This is no introduction in how to develop applications for X11 using XawPlus in general. It is meant for programmers, who are familiar in programming with the original Xaw or Motif library. The main idea is to describe all features and the deviations to the original Xaw library, because there are no new features without deviations to the original ;-)

This documentation based completely on documents that comes with the X distribution. The description of the widgets based on the manual set and the rest is partial borrowed from a postscript document, found in the document path of the xc archives.

1. What is XawPlus and what is new ?

XawPlus 3.0 is a clone of the original Xaw library, providing a more up to date look to the original Athena widget set. This library is as compatible as possible to the original in its X11R6.4 version. It should be possible to compile the source code of any Xaw client without any changes (except the include path of the XawPlus header files) to get the new look of XawPlus to this client. A lot of applications also works fine without recompilation, if the original Xaw library is replaced with XawPlus.

XawPlus make it possible to use XPM pixmaps in labels, toggles or buttons without changing the code of your application via setting the bitmap resource. A transparent background is provided. XawPlus also provide tooltips for buttons, toggles, repeaters and menu buttons without changes of the source code.

XawPlus comes with a set of adapted applications, using also the new features and widgets.

2. What is different to XawPlus 2.1 ?

Port to X11R6.4:

XawPlus now based completely on the X11R6.4 sources of Xaw. All extensions of XawPlus are merged into these sources.

More compatibility to the original:

XawPlus is now much more compatible to the original. The implementation for the 3D extensions are moved to the Simple widget. The add3dExt class is not longer required and was removed. The class tree is now again identical to the class tree of Xaw. The definitions of unsupported resources are moved back to the XawPlus header files to make it easier to recompile Xaw clients with XawPlus.

The IconList widget is removed:

All extensions of the IconList widget are now merged into the code of the List widget.

Full UNICODE support for Label based widgets:

Label now has full UNICODE support, independent of the locale settings.

3. Short description of the widgets

3.1 Simple Widgets

Each of these widgets performs a specific user interface function. They are simple because they cannot have widget children like manager widgets. These widgets display information or take user input.

Command	A push button that, when selected, may cause a specific action to take place. This widget can display a multi-line string or a bitmap or pixmap image.
DrawingArea	This widget adds a backing store an a set of drawing functions to the Simple widget. It is posssible to draw in it using the drawing functions. DrawingArea then handle the redisplay of its area while popup the window of your application or when the window was partial or completely hidden.
Grip	A rectangle that, when selected, will cause an moving action to take place.
IconList	A list of text strings and/or pixmaps or bitmaps presented in a row column format, that may be individually selected. If an element is selected an action may take place.
Label	A rectangular area, that can display a multi-line string, a bitmap or pixmap image.
List	A list of text strings presented in a row column format, that may be individually selected. If an element is selected an action may take place.
Panner	A rectangular area containing a slider that may be moved in two dimensions. This widget is almost used with a porthole widget to control the visible area in it.
Repeater	A push button that triggers an action at an increasing rate when selected like a fire button. This widget can display a multi-line string, a bitmap or a pixmap image.
Scrollbar	A rectangular area containing a thumb that when slid along one dimension may cause a specific action to take place. The scrollbar may be oriented horizontally or vertically
Simple	The base class for most of the simple widgets described here. It provides a rectangular area with a settable mouse cursor and special border.
StripChart	A simple real time graph that will automatically update and scroll.
Toggle	A push button that contains state information. Toggles may also be used as radio buttons to implement a `one of many' or `zero or more of many' group of buttons. This widget can display a multi-line string, a bitmap or a pixmap image.

3.2 Menus

The Athena Widget Set provides support for single paned non-hirarchical popup and pulldown menus. Since menus are such a common user interface tool, support for must be provided in even the most basic widget sets.

Menus are implemented as a menu container (the SimpleMenu widget) and a collection of objects that comprise the menu entries. The SimpleMenu widget is itself a direct subclass of the OverrideShell widget class, so no other shell is necessary when creating a menu. The managed children of a SimpleMenu must be subclasses of the Sme (Simple Menu Entry) object.

MenuButton	A push button, that pops up an override shell containing the menu.
SimpleMenu	The override shell containing the menu entries. These entries are SmeBSB or SmeLine objects.
Sme	The base class of all menu entries. It may be used as a menu entry itself to provide blank space in an menu. `Sme' means `Simple Menu Entry'.
SmeBSB	This menu entry provides a selectable entry containing a text string. A bitmap or a pixmap may also be placed in the left and right margins. BSB means `Bitmap String Bitmap'.
SmeLine	This menu entry provides an unselectable entry containing a separator line.

3.3 Text Widgets

The Text widget provides a window that will allow an application to display and edit one or more lines of text. Options are provided to allow the user to add Scrollbars to its window, search for a specific string and modify the text in the buffer.

The Text widget is made up of a number of pieces; it was modularize to ease customization. The AsciiText widget class (not limited to ascii but so named for compatibility) is be general enough to most needs. This is the widget, which is meant to instantiate directly from an application. If more features are needed as provided in AsciiText, they can be be added by creating a new widget, subclassing the Text widget.

AsciiText widget	This widget implements complete text editor capabilities. It can be used as line editor or as an text editor. Since X11R6 this widget is able to handle simple ascii text using the *AsciiSource* and *AsciiSink* objects or multi byte coded international text using the *MultiSource* and *MultiSink* objects.
AsciiSource object	Handle the ascii source (file or memory buffer) for the AsciiText widget. This object is part of the AsciiText widget.
AsciiSink object	Handles the ascii sink (the output in a window) for the AsciiText widget. This object is part of the AsciiText widget.
MultiSource object	Handle the multi byte source (file or memory buffer) for the AsciiText widget. This object is part of the AsciiText widget.
MultiSink object	Handles the smuli byte sink (the output in a window) for the AsciiText widget. This object is part of the AsciiText widget.
Text Actions	A list of actions, defined in an AsciiText window.
Text functions	For programmmers: A description of functions usable for the text widget.
Text widget	The superclass of the AsciiText widget. This is the base class for the implementation of new Text widgets.
Text sink	The base class for the AsciiSink and MultiSink object.
Text source	The base class for the AsciiSource and MultiSource object.

3.4 Manager Widgets

Manager widgets contains other widgets and controls the size and position of their location. The managed widgets can either be simple widgets like labels, buttons and lists or other manager widgets. These manager widgets differs in the way they handle the geometry management of their children. Geometry management means how to organize the position and possibly defined depencies between the childrens position in the managed area.

Box widget	This widget will its children as tightly as possible in non-overlapping rows or columns.
Dialog widget	This is not really a manager widget but a complete simple dialog, derived from the form widget. So it is described here.
Form widget	A more sophisticated layout widget that allows the children to specify their position relative to the other children, or to the edges of the form.
Paned widget	This manager organizes its children tiled vertically or horizontally. Controls are also provided to allow the user to resize dynamically the individual panes.
Porthole widget	Allows viewing of a managed child which is as large as, or lager than its parent, typically under control of a Panner widget.
Tree widget	Provides geometry management of widgets arranged in a horizontal or vertical tree.
Viewport widget	This widget consists of a frame, one or two scrollbars and an inner window. The inner window will be clipped by the frame. With the scrollbar the user can control which part of this inner window is visible.

XawPlus_________________________________________________________

XawPlusDoc/AsciiText.html The AsciiText Widget

_________________________________________________________XawPlus

The AsciiText Widget

Application Header file
Class Header file
Class
Class Name
Superclass

<X11/XawPlus/AsciiText.h>
<X11/XawPlus/AsciiTextP.h>
asciiTextWidgetClass
AsciiText
Text

The AsciiText widget is really a collection of smaller parts. It includes the Text widget, an AsciiSrc, and an AsciiSink for ASCII locales or a MultiSrc, and an MultiSink for non-ASCII locales. This is dependent on the international resource.

If you want to specify resources for AsciiSrc or AsciiSink in a resource file be sure to use *AsciiText*resource_name instead of *AsciiText.resource_name, since they actually belong to the children of the AsciiText widget, and not the AsciiText widget itself. However, these resources may be set directly on the AsciiText widget at widget creation time, or via XtSetValues().

Differences between Xaw and XawPlus

Since the 3D extensions of Simple are inserted, the AsciiText widget has the additional (but at this time not used) resources highlightColor, shadowColor and buttonBorderWidth. The default background color is now grey75.

Resources

When creating a AsciiText widget instance, the following resources are retrieved from the argument list of XtSetValues() or XtVaSetValues() or from the resource database:

Name	Class	Type	Default Value
OBJECT:
destroyCallback	Callback	Pointer	NULL
RECTANGLE:
borderWidth height sensitive width x y	BorderWidth Height Sensitive Width Position Position	Dimension Dimension Boolean Dimension Position Position	0 12 True 100 0 0
CORE:
border background mappedWhenManaged	BorderColor Background MappedWhenManaged	Pixel Pixel Boolean	XtDefaultForeground grey75 True
SIMPLE:
cursor cursorName pointerColor pointerColorBackground insensitiveBorder international highlightColor shadowColor buttonBorderWidth	Cursor Cursor Foreground Background Insensitive International Background Background Width	Cursor String Pixel Pixel Pixmap Boolean Pixel Pixel Dimension	None NULL XtDefaultForeground XtDefaultBackground NULL False grey90 grey40 2
TEXT:
autoFill bottomMargin topMargin leftMargin rightMargin displayPosition insertPosition resize scrollHorizontal scrollVertical selectTypes textSink textSource unrealizeCallback wrap displayCaret	AutoFill Margin Margin Margin Margin TextPosition TextPosition Resize Scroll Scroll SelectTypes TextSink TextSource Callback Wrap Output	Boolean Position Position Position Position XawTextPosition XawTextPosition XawTextResizeMode XawTextScrollMode XawTextScrollMode Pointer Widget Widget Callback XawTextWrapMode Boolean	False 2 2 2 4 0 0 XawTextResizeNever XawtextScrollNever XawtextScrollNever see documentation NULL NULL NULL XawTextWrapNever True

Note, that the AsciiText widget class don't add any resources to the Text widget class.

XawPlus_________________________________________________________

XawPlusDoc/TextSource.html The Text Source Object

_________________________________________________________XawPlus

The Text Source Object

Application Header file
Class Header file
Class
Class Name
Superclass

<X11/XawPlus/TextSrc.h>
<X11/XawPlus/TextSrcP.h>
textSrcObjectClass
TextSource
Object

The TextSrc object is the root object for all text sources. Any new text source objects should be subclasses of the TextSrc Object. The TextSrc Class contains all methods the Text widget expects a text source to export.
Since all text sources will have some resources in common the TextSrc defines a few new resources.

Differences between Xaw and XawPlus

None.

Resources

When creating a TextSrc object instance, the following resources are retrieved from the argument list of XtSetValues() or XtVaSetValues() or from the resource database:

Name	Class	Type	Default Value
OBJECT:
destroyCallback	Callback	Pointer	NULL
TEXTSRC OBJECT:
editType	EditType	XawTextEditType	XawtextRead

Subclassing the TextSrc

The only purpose of the TextSrc Object is to be subclassed. It contains the minimum set of class methods that all text sources must have. All class methods of the TextSrc must be defined, as the Text widget uses them all. While all may be inherited, the direct descendant of TextSrc must specify some of them as TextSrc does not contain enough information to be a valid text source by itself. Do not try to use the TextSrc as a valid source for the Text widget; it is not intended to be used as a source by itself and bad things will probably happen.

Function	Public Interface	must specify
Read Replace Scan Search SetSelection ConvertSelection	XawTextSourceRead XawTextSourceReplace XawTextSourceScan XawTextSourceSearch XawTextSourceSetSelection XawTextSourceConvertSelection	yes no yes no no no

Reading Text

To read the text in a text source use the Read() function:

XawTextPosition Read(w, pos, text_return, length)
Widget w;
XawTextPosition pos;
XawTextBlock *text_return;
int length;

w	Specifies the TextSrc object.
pos	Specifies the position of the first character to be read from the text buffer.
text	Returns the text read from the source.
length	Specifies the maximum number of characters the TextSrc should return to the application in text_return.

This function returns the actual number of characters read from the text buffer. The function is not required to return length characters if that many characters are in the file, it may break at any point that is convenient to the internal structure of the source. It may take several calls to Read() before the desired portion of the text buffer is fully retrieved.

Replacing Text

To replace or edit the text in a text buffer use the Replace() function:

XawTextPosition Replace(w, start, end, text)
Widget w;
XawTextPosition start, end;
XawTextBlock *text;

w	Specifies the TextSrc object.
start	Specifies the position of the first character to be removed from the text buffer. This is also the location to begin inserting the new text.
end	Specifies the position immediately after the last character to be removed from the text buffer.
text	Specifies the text to be added to the text source.

This function can return any of the following values:

XawEditDone	The text replacement was successful.
XawPositionError	The edit mode is XawtextAppend and start is not the last character of the source.
XawEditError	Either the Source was read-only or the range to be deleted is larger than the length of the Source.

The Replace arguments start and end represent the text source character positions for the existing text that is to be replaced by the text in the text block. The characters from start up to but not including end are deleted, and the buffer specified by the text block is inserted in their place. If start and end are equal, no text is deleted and the new text is inserted after start.

Scanning the TextSrc

To search the text source for one of the predefined boundary types use the Scan() function:

XawTextPosition Scan(w, position, type, dir, count, include)
Widget w;
XawTextPosition position;
XawTextScanType type;
XawTextScanDirection dir;
int count;
Boolean include;

w	Specifies the TextSrc object.
position	Specifies the position to begin scanning the source.
type	Specifies the type of boundary to scan for, may be one of: XawstPosition, XawstWhiteSpace, XawstEOL, XawstParagraph, XawstAll. The exact meaning of these boundaries is left up to the individual text source.
dir	Specifies the direction to scan, may be either XawsdLeft to search backward, or XawsdRight to search forward.
count	Specifies the number of boundaries to scan for.
include	Specifies whether the boundary itself should be included in the scan.

The Scan() function returns the position in the text source of the desired boundary. It is expected to return a valid address for all calls made to it, thus if a particular request is made that would take the text widget beyond the end of the source it must return the position of that end.

Searching through a TextSrc

To search for a particular string use the Search() function.

XawTextPosition Search(w, position, dir, text)
Widget w;
XawTextPosition position;
XawTextScanDirection dir;
XawTextBlock *text;

w	Specifies the TextSrc object.
position	Specifies the position to begin the search.
dir	Specifies the direction to search, may be either XawsdLeft to search backward, or XawsdRight to search forward.
text	Specifies a text block containing the text to search for.

This function will search through the text buffer attempting to find a match for the string in the text block. If a match is found in the direction specified, then the character location of the first character in the string is returned. If no text was found then XawTextSearchError is returned.

Text Selections

While many selection types are handled by the Text widget, text sources may have selection types unknown to the Text widget. When a selection conversion is requested by the X server the Text widget will first call the ConvertSelection function, to attempt the selection conversion.

Boolean ConvertSelections(w, selection, target, type, value_return, length_return, format_return)
Widget w;
Atom *selection, *target, *type;
caddr_t *value_return;
unsigned long *length_return;
int *format_return;

w	Specifies the TextSrc object.
selection	Specifies the type of selection that was requested (e.g. PRIMARY).
target	Specifies the type of the selection that has been requested, which indicates the desired information about the selection (e.g. Filename, Text, Window).
type	Specifies a pointer to the atom into which the property type of the converted value of the selection is to be stored. For instance, either file name or text might have property type XA_STRING.
value_return	Returns a pointer into which a pointer to the converted value of the selection is to be stored. The selection owner is responsible for allocating this storage. The memory is considered owned by the toolkit, and is freed by XtFree when the Intrinsics selection mechanism is done with it.
length_return	Returns a pointer into which the number of elements in value is to be stored. The size of each element is determined by format.
format_return	Returns a pointer into which the size in bits of the data elements of the selection value is to be stored.

If this function returns True then the Text widget will assume that the source has taken care of converting the selection, Otherwise the Text widget will attempt to convert the selection itself.

If the source needs to know when the text selection is modified it should define a SetSelection() procedure:

void SetSelection(w, start, end, selection)
Widget w;
XawTextPosition start, end;
Atom selection;

w	Specifies the TextSrc object.
start	Specifies the character position of the beginning of the new text selection.
end	Specifies the character position of the end of the new text selection.
selection	Specifies the type of selection that was requested (e.g. PRIMARY).

XawPlus_________________________________________________________

XawPlusDoc/IconList.html The IconList Widget

_____________________________________________________XawPlus

The IconList Widget

Application Header file
Class Header file
Class
Class Name
Superclass

<X11/XawPlus/IconList.h>
<X11/XawPlus/ListP.h>
iconListWidgetClass
List
Simple

The List widget contains a list of strings and/or bitmaps formatted into rows and columns. When one of the strings is selected, it is highlighted, and the List widget's Notify action is invoked, calling all routines on its callback list. Only one string may be selected at a time.

Since release 3.0 of XawPlus, this widget is only a IconList compatible mapping to the List widget. Programmers may use IconList as in previous versions for the future but a List widget will be created.

Resources

When creating a List widget instance, the following resources are retrieved from the argument list of XtSetValues() or XtVaSetValues() or from the resource database:

Name	Class	Type	Default Value
OBJECT:
destroyCallback	Callback	Pointer	NULL
RECTANGLE:
borderWidth height sensitive width x y	BorderWidth Height Sensitive Width Position Position	Dimension Dimension Boolean Dimension Position Position	0 12 True 12 0 0
CORE:
border background mappedWhenManaged	BorderColor Background MappedWhenManaged	Pixel Pixel Boolean	XtDefaultForeground grey75 True
ADD3DEXT:
highlightColor shadowColor buttonBorderWidth	Background Background Width	Pixel Pixel Dimension	grey90 grey40 2
SIMPLE:
cursor cursorName pointerColor pointerColorBackground insensitiveBorder	Cursor Cursor Foreground Background Insensitive	Cursor String Pixel Pixel Pixmap	left_ptr NULL XtDefaultForeground XtDefaultBackground NULL
ICONLIST:
callback pasteBuffer foreground font internalHeight internalWidth defaultColumns columnSpacing rowSpacing forceColumns verticalList list longest numberStrings iconHeight iconWidth iconDepth	Callback Boolean Foreground Font Height Width Columns Spacing Spacing Columns Boolean List Longest NumberStrings Height Width Depth	XtCallbackList Boolean Pixel XFontStruct * Dimension Dimension int Dimension Dimension Boolean Boolean XawIconList[] int int Dimension Dimension Dimension	NULL False XtDefaultForeground XtDefaultFont 2 4 2 6 4 False False NULL 0 0 0 0 1

callback	All functions on this list are called whenever the notify action is invoked. The call_data argument contains information about the element selected and is described in detail in the IconList Callbacks section.
columnSpacing rowSpacing	The amount of space, in pixels, between each of the rows and columns in the list.
defaultColumns	The default number of columns. This value is used when neither the width nor the height of the IconList widget is specified or when forceColumns is True.
forceColumns	Forces the default number of columns to be used regardless of the IconList widget's current size.
foreground	A pixel value which indexes the widget's colormap to derive the color used to paint the text of the list elements.
internalHeight, internalWidth	The margin, in pixels, between the edges of the list and the corresponding edge of the IconList widget's window.
list	An array of text strings and icons displayed in the IconList widget. If numberStrings is zero (the default) then the list must be NULL terminated. If a value is not specified for the list, then numberStrings is set to 1, and the name of the widget is used as the list, and longest is set to the length of the name of the widget. The list is used in place, and must be available to the IconList widget for the lifetime of this widget, or until it is changed with XtSetValues() or better with XawIconListChange(). Note that XtSetValues() only works well, if the memory location of the list structure changes. It is a good idea to use always XawIconListChange().
longest	Specifies the width, in pixels, of the longest string in the current list. The IconList widget will compute this value if zero (the default) is specified. If this resource is not correctly specified, selection of list items may not work properly.
numberStrings	The number of strings in the current list. If a value of zero (the default) is specified, the IconList widget will compute it. When computing the number of strings the IconList widget assumes that the list is NULL terminated.
pasteBuffer	If this resource is set to True then the name of the currently selected list element will be put into CUT_BUFFER_0.
verticalList	If this resource is set to True then the list elements will be presented in column major order.
iconHeight, iconWidth	Set this resources to the width and height of your bitmap or pixmap icons. iconWidth and iconHeight are used to reserve enough space in the list entries.
iconDepth	Use the value of 1 for traditional XBM bitmap icons or the depth of your pixmaps for color icons like XPMs.

IconList Actions

The IconList widget supports the following actions:

Highlighting and unhighlighting the list element under the pointer with Set and Unset.
Processing application callbacks with Notify.

The following is the default translation table used by the IconList Widget:

<Btn1Down>,<Btn1Up>

Set(), Notify()

The full list of actions supported by IconList widget is:

Set()	Sets the list element that is currently under the pointer. To inform the user that this element is currently set, it is drawn with is foreground and background colors reversed. If this action is called when there is no list element under the cursor, the currently set element will be unset.
Unset()	Cancels the set state of the element under the pointer, and redraws it with normal foreground and background colors.
Notify()	Calls all callbacks on the IconList widget's callback list. Information about the currently selected list element is passed in the call_data argument (see IconList Callback below).

IconList Callbacks

All procedures on the IconList widget's callback list will have a XawIconListReturnStruct passed to them as call_data. The structure is defined in the IconList widget's application header file.

typedef struct _XawIconListReturnStruct {

String string; /* string shown in the list. */
int list_index; /* index of the item selected. */

} XawIconListReturnStruct;

The list_index item used to be called simply index. Unfortunately, this name collided with a global name defined on some operating systems, and had to be changed.

Changing the List

To change the list that is displayed, use XawIconListChange():

void XawIconListChange(w, list, nitems, longest, resize)
Widget w;
XawIconList *list;
int nitems, longest;
int width, height, depth;
Boolean resize;

w	Specifies the IconList widget.
list	Specifies the new list for the IconList widget to display.
nitems	Specifies the number of items in the list. If a value less than 1 is specified, list must be NULL terminated, and the number of items will be calculated by the IconList widget.
longest	Specifies the length of the longest item in the list in pixels. If a value less than 1 is specified, the IconList widget will calculate the value.
width, height	Specifies the width and height of your bitmap or pixmap icons. These values are used to reserve enough space for the icons in the list entries.
iconDepth	Use the value of 1 for traditional XBM bitmap icons or the depth of your pixmaps for color icons like XPMs.
resize	Specifies a Boolean value that if True indicates that the IconList widget should try to resize itself after making the change. The constraints of the IconList widget's parent are always enforced, regardless of the value specified here.

The IconList has the following structure:

typedef struct _XawIconList {

Pixmap bitmap; /* the icon, used as left bitmap */
Pixmap clipMask; /* drawing mask for the icon */
String string; /* text for the list entry */

} XawIconList;

bitmap	A bitmap or pixmap displayed left of the string entry. Use XtUnspecifiedPixmap if you don't want to display an icon for a list entry. Use XCreateBitmapFromData() to create a 1 bit depth XBM styled pixmap or XpmCreatePixmapFromData() for XPMs included in your source code. The XPM function returns in addition a clip mask if one of the colors (normally the background color) used in the XPM source is set to None.
clipMask	A clip mask is used to display nonrectagular icons. If you don't want to use clip masks, set this entry to XtUnspecifiedPixmap.
string	The string for a list entry.

Highlighting an Item

To highlight an item in the list, use XawIconListHighlight():

void XawIconListHighlight(w, item)
Widget w;
int item;

w	Specifies the IconList widget.
item	Specifies an index into the current list that indicates the item to be highlighted.

Only one item can be highlighted at a time. If an item is already highlighted when XawIconListHighlight() is called, the highlighted item is unhighlighted before the new item is highlighted.

Unhighlighting an Item

To unhighlight the currently highlighted item in the list, use XawIconListUnhighlight():

void XawIconListUnhighlight(w)
Widget w;

w	Specifies the IconList widget.

Retrieving the Currently Selected Item

To retrieve the list element that is currently set, use XawIconListShowCurrent().

XawIconListReturnStruct *XawIconListShowCurrent(w)
Widget w;

w	Specifies the IconList widget.

XawIconListShowCurrent() returns a pointer to an XawIconListReturnStruct structure, containing the currently highlighted item. If the value of the index member is XAW_LIST_NONE, the string member is undefined, and no item is currently selected.

XawPlus_____________________________________________________

XawPlusDoc/SimpleMenu.html The SimpleMenu Widget

_________________________________________________________XawPlus

The SimpleMenu Widget

Application Header file
Class Header file
Class
Class Name
Superclass

<X11/XawPlus/SimpleMenu.h>
<X11/XawPlus/SimpleMenP.h>
simpleMenuWidgetClass
SimpleMenu
OverrideShell

The SimpleMenu widget is a container for the menu entries. It is a direct subclass of shell, and is usually created with XtCreatePopupShell(). This is the only part of the menu that actually contains a window. The SimpleMenu serves as the glue to bind the individual menu entries together into a menu.

Differences between Xaw and XawPlus

In XawPlus the menus entries (the Sme objects) are drawn in a 3D styled menu window, supplied by this widget. For this feature SimpleMenu has some new resources described below.

Resources

When creating a Simple widget instance, the following resources are retrieved from the argument list of XtSetValues() or XtVaSetValues() or from the resource database:

Name	Class	Type	Default Value
OBJECT:
destroyCallback	Callback	Pointer	NULL
RECTANGLE:
borderWidth height sensitive width x y	BorderWidth Height Sensitive Width Position Position	Dimension Dimension Boolean Dimension Position Position	0 12 True 12 0 0
CORE:
border background mappedWhenManaged	BorderColor Background MappedWhenManaged	Pixel Pixel Boolean	XtDefaultForeground grey75 True
SHELL:
allowShellResize geometry overrideRedirect popdownCallback popupCallback saveUnder	AllowShellResize Geometry OverrideRedirect Callback Callback SaveUnder	Boolean String Boolean Callback Callback Boolean	True NULL see above see above see above True
SIMPLEMENU:
backingStore menuOnScreen popupOnEntry cursor label labelClass rowHeight bottomMargin topMargin highlightColor shadowColor buttonBorderWidth	BackingStore MenuOnScreen PopupOnEntry Cursor Label LabelClass RowHeight VerticalMargins VerticalMargins Background Background Width	BackingStore Boolean Widget Cursor String Pointer Dimension Dimension Dimension Pixel Pixel Dimension	default True NULL None NULL (No label) smeBSBObjectClass Height of Font VerticalSpace VerticalSpace grey90 grey40 2

backingStore	Determines what type of backing store will be used for the menu. Legal values for this resource are NotUseful, WhenMapped, and Always. These values are the backing store integers defined in . If default is specified (the default behavior) the server will use whatever it thinks is appropriate.
bottomMargin, topMargin	The amount of space between the top or bottom of the menu and the menu entry closest to that edge.
cursor	The shape of the mouse pointer whenever it is in this widget.
geometry	If this resource is specified it will override the x, y, width and height of this widget. The format of this string is [<width>x<height>][{+ -} <xoffset> {+ -}<yoffset>].
label	This label will be placed at the top of the SimpleMenu, and may not be highlighted. The name of the label object is menuLabel. Using this name it is possible to modify the label's attributes through the resource database. When the label is created, the label is hard coded to the value of label, and justify is hard coded as XtJustifyCenter.
labelClass	Specifies the type of Sme object created as the menu label.
menuOnScreen	If the menu is automatically positioned under the cursor with the XawPositionSimpleMenu action, and this resource is True, then the menu will always be fully visible on the screen.
overrideRedirect	Determines the value of the override_redirect attribute of the SimpleMenu's window. The override_redirect attribute of a window determines whether or not a window manager may interpose itself between this window and the root window of the display. For more information see the Interclient Communications Conventions Manual.
popdownCallback, popupCallback	These callback functions are called by the Xt Intrinsics whenever the shell is popped up or down (See Xt for details).
popupOnEntry	The XawPositionSimpleMenu action will, by default, popup the SimpleMenu with its label (or first entry) directly under the pointer. To popup the menu under another entry, set this resource to the menu entry that should be under the pointer, when the menu is popped up. This allows the application to offer the user a default menu entry that can be selected with out moving the pointer.
rowHeight	If this resources is zero (the default) then each menu entry will be given its desired height. If this resource has any other value then all menu entries will be forced to be rowHeight pixels high.
saveUnder	If this is True then save unders will be active on the menu's window.
highlightColor	This color is used for the highlighted part of the menu border.
shadowColor	This color is used for the shadowed part of the menu border.
buttonBorderWidth	The border width of the menu. The reason for the name is compatibility with the resource of the Simple widget.

SimpleMenu Actions

The SimpleMenu widget supports the following actions:

Switching the entry under the mouse pointer between the foreground and background colors with highlight and unhighlight
Processing menu entry callbacks with notify

The following are the default translation bindings used by the SimpleMenu widget:

<EnterWindow>:
<LeaveWindow>:
<BtnMotion>:
<BtnUp>:

highlight()
unhighlight()
highlight()
MenuPopdown() notify() unhighlight()

The user can pop down the menu without activating any of the callback functions by releasing the pointer button when no menu item is highlighted.

The full list of actions supported by SimpleMenu is:

highlight()	Highlight the menu entry that is currently under the pointer. Only a item that is highlighted will be notified when the notify() action is invoked. The look of a highlighted entry is determined by the menu entry.
unhighlight()	Unhighlights the currently highlighted menu item, and returns it to its normal look.
notify()	Notifies the menu entry that is currently highlighted that is has been selected. It is the responsibility of the menu entry to take the appropriate action.
MenuPopdown(menu)	This action is defined in Xt.

Positioning the SimpleMenu

If the SimpleMenu widget is to be used as a pulldown menu then the MenuButton widget, or some other outside means should be used to place the menu when it is popped up.

If popup menus are desired it will be necessary to add the XawPositionSimpleMenu() and MenuPopup() actions to the translation table of the widget that will be popping up the menu. The MenuPopup() action is described in Xt. XawPositionSimpleMenu() is a global action procedure registered by the SimpleMenu widget when the first one is created or the convenience routine XawSimpleMenuAddGlobalActions() is called.

Translation writers should be aware that Xt does not register grabs on don't care modifiers, and therefore the left hand side of the production should be written to exclude unspecified modifiers. For example these are the translations needed to popup some of xterm's menus:

!Ctrl<Btn1Down>:
!Ctrl<Btn2Down>:

XawPositionSimpleMenu(xterm) MenuPopup(xterm)
XawPositionSimpleMenu(modes) MenuPopup(modes)

XawPositionSimpleMenu(menu)

The XawPositionSimpleMenu() routine will search for the menu name passed to it using XtNameToWidget() starting with the widget invoking the action as the reference widget. If it is unsuccessful it will continue up the widget tree using each of the invoking widget's ancestors as the reference widget. If it is still unsuccessful it will print a warning message and give up. XawPositionSimpleMenu will position the menu directly under the pointer cursor. The menu will be placed so that the pointer cursor is centered on the entry named by the popupOnEntry resource. If the menuOnScreen resource is True then the menu will always be fully visible on the screen.

Convenience Routines

Registering the Global Action Routines

The XawPositionSimpleMenu() action routine may often be invoked before any menus have been created. This can occur when an application uses dynamic menu creation. In these cases an application will need to register this global action routine by calling XawSimpleMenuAddGlobalActions():

void XawSimpleMenuAddGlobalActions(app_con)
XtAppContext app_con;

app_con

Specifies the application context in which this action should be registered.

This function need only be called once per application and must be called before any widget that uses XawPositionSimpleMenu() action is realized.

Getting and Clearing the Current Menu Entry

To get the currently highlighted menu entry use XawSimpleMenuGetActiveEntry():

Widget XawSimpleMenuGetActiveEntry(w)
Widget w;

w	Specifies the SimpleMenu widget.

This function returns the menu entry that is currently highlighted, or NULL if no entry is highlighted.

To clear the SimpleMenu widget's internal information about the currently highlighted menu entry use XawSimpleMenuClearActiveEntry():

Widget XawSimpleMenuClearActiveEntry(w)
Widget w;

w	Specifies the SimpleMenu widget.

This function unsets all internal references to the currently highlighted menu entry. It does not unhighlight or otherwise alter the appearance of the active entry. This function is primarily for use by implementors of menu entries.

XawPlus_________________________________________________________

XawPlusDoc/Sme.html The Sme Object

_________________________________________________________XawPlus

The Sme Object

Application Header file
Class Header file
Class
Class Name
Superclass

<X11/XawPlus/Sme.h>
<X11/XawPlus/SmeP.h>
smeObjectClass
Sme
RectObj

The Sme object is the base class for all menu entries. While this object is mainly intended to be subclassed, it may be used in a menu to add blank space between menu entries.

Differences between Xaw and XawPlus

Sme now has the new resources highlightColor and shadowColor to inherit them to SmeLine and SmeBSB. These resources are not used from Sme.

Resources

The resources associated with the SmeLine object are defined in this section, and affect only the single menu entry specified by this object. There are no new resources added for this class, as it picks up all its resources from the RectObj class.

Name	Class	Type	Default Value
OBJECT:
destroyCallback	Callback	Pointer	NULL
RECTANGLE:
borderWidth height sensitive width x y	BorderWidth Height Sensitive Width Position Position	Dimension Dimension Boolean Dimension Position Position	0 0 True 0 0 0
SME:
callback highlightColor shadowColor international	Callback Background Background International	Pointer Pixel Pixel Boolean	NULL grey90 grey40 False

highlightColor	The color is used for the highlighted part of the line in SmeLine and for the highlighted part of the text from insensitive entries in SmeBSB.
shadowColor	The color is used for the shadowed part of the line in SmeLine and for the shadowed part of the text from insensitive entries in SmeBSB.
international	This is a boolean flag, only settable at widget creation time. A value of false signals not to use the X11R6 internationalization facility. A value of true signals to use font sets and support of multi byte code to display text etc. This resource is used from widgets which has to handle text output like SmeBSB.

Keep in mind that the SimpleMenu widget will force all menu items to be the width of the widest entry.

Subclassing the Sme Object

To Create a new Sme object you will need to define a few class procedures. These procedures allow the SimpleMenu to highlight and unhighlight the menu entry as the pointer cursor moves over it, as well as notifying the entry when the user has selected it.

There are three new class methods defined by the Sme Object. All of these methods may be inherited from the Sme object, although the default semantics are not very interesting.

Highlight()	Called to put the menu entry into the highlighted state.
Unhighlight()	Called to return the widget to its normal (unhighlighted) state.
Notify()	Called when the user selects this menu entry.

Other then these specialized class procedures creating a new object is straight forward. Just subclass Sme and define new redisplay and highlight procedures. Here is some information that may help you avoid some common mistakes.

Objects can be zero pixels high.
Objects draw on their parent's window, therefore the Drawing dimensions are different from those of widgets. For instance, y locations vary from y to y + height, not 0 to height.
SetValues calls may come from the application while the SimpleMenu is in its notify procedure. The SimpleMenu may later call the menu entries unhighlight procedure. Due to the asynchronous nature of X the expose event generated by XtSetValues() will come after this unhighlight.
Remember the menu entry does not own the window. Share the space with other menu entries, never draw outside your own section of the menu.

XawPlus_________________________________________________________

XawPlusDoc/Box.html Box Widget

_________________________________________________________XawPlus

The Box Widget

Application Header file
Class Header file
Class
Class Name
Superclass

<X11/XawPlus/Box.h>
<X11/XawPlus/BoxP.h>
boxWidgetClass
Box
Composite

The Box widget provides geometry management of arbitrary widgets in a box of a specified dimension. The children are rearranged when resizing events occur either on the Box or its children, or when children are managed or unmanaged. The Box widget always attempts to pack its children as tightly as possible within the geometry allowed by its parent.

Box widgets are commonly used to manage a related set of buttons and are often called ButtonBox widgets, but the children are not limited to buttons. The Box's children are arranged on a background that has its own specified dimensions and color.

Differences between Xaw and XawPlus

The Background color is changed from XtDefaultBackground to grey75.

Resources

When creating a Box widget instance, the following resources are retrieved from the argument list of XtSetValues() or XtVaSetValues() or from the resource database:

Name	Class	Type	Default Value
OBJECT:
destroyCallback	Callback	Pointer	NULL
RECTANGLE:
borderWidth height width sensitive x y	BorderWidth Height Width Sensitive Position Position	Dimension Dimension Dimension Boolean Position Position	1 0 0 True 0 0
CORE:
border background mappedWhenManaged	BorderColor Background MappedWhenManaged	Pixel Pixel Boolean	XtDefaultForeground grey75 True
BOX:
hSpace vSpace orientation	HSpace VSpace Orientation	Dimension Dimension XtOrientation	4 4 vertical

hSpace
vSpace

The amount of space, in pixels, to leave between the children. This resource specifies the amount of space left between the outermost children and the edge of the box.

orientation

Specifies whether the preferred shape of the box (i.e. the result returned by the query_geometry class method) is tall and narrow XtorientVertical or short and wide XtorientHorizontal. When the Box is a child of a parent which enforces width constraints, it is usually better to specify XtorientVertical (the default). When the parent enforces height constraints, it is usually better to specify XtorientHorizontal.

Layout Semantic

Each time a child is managed or unmanaged, the Box widget will attempt to reposition the remaining children to compact the box. Children are positioned in order left to right or top to bottom. The packing algorithm used depends on the orientation of the Box.

XtorientVertical	When the next child does not fit on the current row, a new row is started. If a child is wider than the width of the box, the box will request a larger width from its parent and will begin the layout process from the beginning if a new width is granted.
XtorientHorizontal	When the next child does not fit in the current column, a new column is started. If a child is taller than the height of the box, the box will request a larger height from its parent and will begin the layout process from the beginning if a new height is granted.

After positioning all children, the Box widget attempts to shrink its own size to the minimum dimensions required for the layout.

XawPlus_________________________________________________________

XawPlusDoc/Grip.html The Grip Widget

_________________________________________________________XawPlus

The Grip Widget

Application Header file
Class Header file
Class
Class Name
Superclass

<X11/XawPlus/Grip.h>
<X11/XawPlus/GripP.h>
gripWidgetClass
Grip
Simple

The Grip widget provides a small rectangular region in which user input events (such as ButtonPress or ButtonRelease) may be handled. The most common use for the Grip widget is as an attachment point for visually repositioning an object, such as the pane border in a Paned widget.

Differences between Xaw and XawPlus

The resource foreground is not needed by XawPlus and therefore deleted . Since the core extension class Add3dExt is inserted, the Grip widget has the additional resources highlightColor, shadowColor and buttonBorderWidth. The default background color is now grey75.

Resources

When creating a Grip widget instance, the following resources are retrieved from the argument list of XtSetValues() or XtVaSetValues() or from the resource database:

Name	Class	Type	Default Value
OBJECT:
destroyCallback	Callback	Pointer	NULL
RECTANGLE:
borderWidth height sensitive width x y	BorderWidth Height Sensitive Width Position Position	Dimension Dimension Boolean Dimension Position Position	0 12 True 12 0 0
CORE:
border background mappedWhenManaged	BorderColor Background MappedWhenManaged	Pixel Pixel Boolean	XtDefaultForeground grey75 True
SIMPLE:
cursor cursorName pointerColor pointerColorBackground insensitiveBorder international highlightColor shadowColor buttonBorderWidth	Cursor Cursor Foreground Background Insensitive International Background Background Width	Cursor String Pixel Pixel Pixmap Boolean Pixel Pixel Dimension	None NULL XtDefaultForeground XtDefaultBackground NULL False grey90 grey40 2
GRIP:
callback	Callback	Pointer	NULL

callback

All routines on this list are called whenever the GripAction action routine is invoked. The call_data contains all information passed to the action routine. A more thorough description is given below in the Grip Actions section.

Grip Actions

The Grip widget does not declare any default event translation bindings, but it does declare a single action routine named GripAction. The client specifies an arbitrary event translation table, optionally giving parameters to the GripAction routine.

The GripAction routine executes the callbacks on the callback list, passing as call_data a pointer to a XawGripCallData structure, defined in the Grip widget's application header file.

typedef struct _XawGripCallData {

XEvent *event;
String *params;
Cardinal num_params;

} XawGripCallDataRec, *XawGripCallData, GripCallDataRec, *GripCallData;

In this structure, the event is a pointer to the input event that triggered the action. params and num_params give the string parameters specified in the translation table for the particular event binding.

The following is an example of a translation table that uses the GripAction:

<Btn1Down> :
<Btn1Motion> :
<Btn1Up> :

GripAction(press)
GripAction(move)
GripAction(release)

XawPlus_________________________________________________________

XawPlusDoc/Simple.html The Simple Widget

_________________________________________________________XawPlus

The Simple Widget

Application Header file
Class Header file
Class
Class Name
Superclass

<X11/XawPlus/Simple.h>
<X11/XawPlus/SimpleP.h>
simpleWidgetClass
Simple
Core

The Simple widget is not very useful by itself, as it has no semantics of its own. It main purpose is to be used as a common superclass for the other simple Athena widgets. This widget adds nine resources to the resource list provided by the Core widget and their superclasses.

Differences between Xaw and XawPlus

With version 3.0 of XawPlus all resources and methods of Add3dExt are moved to this widget class. Add3dExt was removed for a better source compatibility to the original Xaw library.

The Simple widget has the additional resources highlightColor, shadowColor and buttonBorderWidth and a set of drawing methods, used by Command, Scrollbar and other widgets to draw 3D shaped buttons, sliders etc.

The default background color of Simple and all its children is now grey75.

Resources

When creating a Simple widget instance, the following resources are retrieved from the argument list of XtSetValues() or XtVaSetValues() or from the resource database:

Name	Class	Type	Default Value
OBJECT:
destroyCallback	Callback	Pointer	NULL
RECTANGLE:
borderWidth height sensitive width x y	BorderWidth Height Sensitive Width Position Position	Dimension Dimension Boolean Dimension Position Position	0 12 True 12 0 0
CORE:
border background mappedWhenManaged	BorderColor Background MappedWhenManaged	Pixel Pixel Boolean	XtDefaultForeground grey75 True
SIMPLE:
cursor cursorName pointerColor pointerColorBackground insensitiveBorder international highlightColor shadowColor buttonBorderWidth	Cursor Cursor Foreground Background Insensitive International Background Background Width	Cursor String Pixel Pixel Pixmap Boolean Pixel Pixel Dimension	None NULL XtDefaultForeground XtDefaultBackground NULL False grey90 grey40 2

cursor	The image that will be displayed as the pointer cursor whenever it is in this widget. The use of this resource is deprecated in favor of cursorName.
cursorName	The name of the symbol to use to represent the pointer cursor. This resource will override the cursor resource if both are specified.
pointerColor	The foreground color used to draw the pointer cursor.
pointerColorBackground	The background color used to draw the pointer cursor.
insensitiveBorder	This pixmap will be tiled into the widgets border, if the widget becomes insensitive.
international	This is a boolean flag, only settable at widget creation time. A value of false signals not to use the X11R6 internationalization facility. A value of true signals to use font sets and support of multi byte code to display text etc. This resource is used from widgets which has to handle text input and output like Label and AsciiText.
highlightColor	The color used to draw highlighted borders. The default value is grey90.
shadowColor	The color used to draw shadow borders. The default value is grey40.
buttonBorderWidth	This resource is used to determine the width of rectangular shapes, used to draw buttons, sliders etc. The default value is 2.

Convenience Routines

The following methods are used from children of the Simple widget to simplify the drawing of rectangular 3D styled shapes, filled rectangular 3D styled areas like buttons or sliders, or to remove them. All methods uses the color resources background, highlightColor and shadowColor. The resource buttonBorderWidth is used to determine the width of the border.

To remove the shape of a pressed or highlighted button use XawFlatRectangle():

XawFlatRectangle(w, x, y, width, height)
Widget w;
int x, y;
unsigned int width, height;

w	Specifies the widget.
x, y	The drawing position of the upper left corner inside the widgets window.
width, height	The width and height of the rectangle to draw.

To draw a visible raised button shape use XawRaisedRectangle():

XawRaisedRectangle(w, x, y, width, height)
Widget w;
int x, y;
unsigned int width, height;

w	Specifies the widget.
x, y	The drawing position of the upper left corner inside the widgets window.
width, height	The width and height of the rectangle to draw.

To draw the shape of a pressed button use XawSunkenRectangle():

XawSunkenRectangle(w, x, y, width, height)
Widget w;
int x, y;
unsigned int width, height;

w	Specifies the widget.
x, y	The drawing position of the upper left corner inside the widgets window.
width, height	The width and height of the rectangle to draw.

To draw a filled flat button using the internal resources of Simple use XawFlatButton():

XawFlatButton(w, x, y, width, height)
Widget w;
int x, y;
unsigned int width, height;

w	Specifies the widget.
x, y	The drawing position of the upper left corner inside the widgets window.
width, height	The width and height of the rectangle to draw.

To draw a filled button using the internal resources of Simple use XawRaisedButton():

XawRaisedButton(w, x, y, width, height)
Widget w;
int x, y;
unsigned int width, height;

w	Specifies the widget.
x, y	The drawing position of the upper left corner inside the widgets window.
width, height	The width and height of the rectangle to draw.

To draw a filled pressed button using the internal resources of Simple use XawSunkenButton():

XawSunkenButton(w, x, y, width, height)
Widget w;
int x, y;
unsigned int width, height;

w	Specifies the widget.
x, y	The drawing position of the upper left corner inside the widgets window.
width, height	The width and height of the rectangle to draw.

XawPlus_________________________________________________________

XawPlusDoc/Label.html The Label Widget

_________________________________________________________XawPlus

The Label Widget

Application Header file
Class Header file
Class
Class Name
Superclass

<X11/XawPlus/Label.h>
<X11/XawPlus/LabelP.h>
labelWidgetClass
Label
Simple

A Label widget is a text string or bitmap displayed within a rectangular region of the screen. The label may contain multiple lines of characters. The Label widget will allow its string to be left, right, or center justified. Normally, this widget can be neither selected nor directly edited by the user. It is intended for use as an output device only.

Differences between Xaw and XawPlus

Since the 3D extensions of Simple are inserted, the Label widget has the additional resources highlightColor, shadowColor and buttonBorderWidth. The default background color is grey75. The bitmap and leftBitmap resources also provides support of XPM styled pixmaps. These pixmaps may be nonrectangular, using the clipMask or the leftClipMask resource. Label has installed converters to supply these resources from the resource database.

Label has a truncate mechanism for label strings, which are too long for the labels window. Those strings will be truncated from the left or from the right side, dependent on the resource truncLeftSide. Default is to truncate from the right side. It is possible to deactivate this mechanism with the the resource truncateLabel. This feature is not very useful for multiline labels and therefore not supported.

With release 3.0 of XawPlus full UNICODE support is available using the encoding resource. UNICODE support works independent of the locale settings and requires UTF8 coded label strings. Since it is not possible to put UNICODE directly in resource files, UTF8 code is used to avoid problems with the resource manager.

Resources

When creating a Label widget instance, the following resources are retrieved from the argument list of XtSetValues() or XtVaSetValues() or from the resource database:

Name	Class	Type	Default Value
OBJECT:
destroyCallback	Callback	Pointer	NULL
RECTANGLE:
borderWidth height sensitive width x y	BorderWidth Height Sensitive Width Position Position	Dimension Dimension Boolean Dimension Position Position	0 12 True 12 0 0
CORE:
border background mappedWhenManaged	BorderColor Background MappedWhenManaged	Pixel Pixel Boolean	XtDefaultForeground grey75 True
SIMPLE:
cursor cursorName pointerColor pointerColorBackground insensitiveBorder international highlightColor shadowColor buttonBorderWidth	Cursor Cursor Foreground Background Insensitive International Background Background Width	Cursor String Pixel Pixel Pixmap Boolean Pixel Pixel Dimension	None NULL XtDefaultForeground XtDefaultBackground NULL False grey90 grey40 2
LABEL:
font fontset encoding foreground internalHeight internalWidth justify resize truncateLabel truncLeftSide label leftBitmap leftClipMask bitmap clipMask	Font FontSet Encoding Foreground Height Width Justify Resize Truncate Truncate Label LeftBitmap LeftBitmap Pixmap Pixmap	XFontStruct* FontSet unsigned char Pixel Dimension Dimension XtJustify Boolean Boolean Boolean String Bitmap ClipMask Bitmap ClipMask	XtDefaultFont XtDefaultFontSet XawTextEncoding8bit XtDefaultForeground 2 4 XtJustifyCenter True True False NULL None None None None

internalHeight, internalWidth	These resources defines the internal border width between the label string or the bitmap and the border of this widget.
justify	Defines how to jusify a label string in a label widget (left, right or centered).
resize	Defines how to handle a resize event after creation of the widget. Default is to handle every resize event and to justify the labels interiors.
truncateLabel	Defines what to do with a label string, if it is too long. Default is to truncate the string until it fits into the widgets window.
truncateLeftSide	Defines to truncate a too long label string from the left side. In this case the strings starts with two dots and the end of the string remains visible. Default ist to cut it from the right side.
font	With this resource it is possible to set any available font to display the label text.
fontset	A set of fonts which will be used, if the international resource is set.
encoding	Two types of encoding are available, the default 8 bit encoding and the 16 bit encoding (unicode). With 16 bit encoding the label string is expected in UTF8 and displayed with the font found in the font resource. The handling of UNICODE is independent of the locale settings. Note that the character codes from 0x00 to 0x7f are also valid as UTF8 code. For this range of characters every editor is usable to edit label strings. If you need character codes in the range from 0x80 to 0xffff a special editor like *yudit* is required. If any malformed UTF8 code is found, it is displayed as an asterix *. If the UTF8 code of a character is out of range (higher than 0xffff), it is displayed as a tilde sign.
foreground	This is the foreground color, used to display a label text.
label	Defines the label text. It is not possible to use both a label and a bitmap, but it is possible to use a label with a leftBitmap.
leftBitmap	This resource defines a bitmap or a XPM styled pixmap, placed left of the label text. XPM pixmaps are detected through their filename extension .xpm.
leftClipMask	This resource defines a bitmap or a XPM styled pixmap, used as a clip mask for the leftBitmap resource. If the background color of an XPM pixmap is defined as None, it is usable as bitmap and as a clip mask. Otherwise the user needs a second bitmap, if a clip mask is required.
bitmap	Defines a bitmap or a XPM styled pixmap to display in the label widget. It is not possible to use a bitmap together with a label or a leftBitmap.
clipMask	This resource defines a bitmap or a XPM styled pixmap, used as a clip mask for the bitmap resource.

Convenience Routines

Since XawPlus 2.1 there is a new function to control the truncate mechanism. In Label the truncate mechanism is only activated, if it is a Label itself and not the superclass of another widget. The reason is, that derived widgets have another idea how to place the label interiors correctly.

void TruncateLabelString(lw, usableWidth)
LabelWidget lw;
int usableWidth;

lw	Specifies the Label widget.
usableWidth	Specifies the usable window width inside of the label.

XawPlus_________________________________________________________

XawPlusDoc/Command.html The Command Widget

_________________________________________________________XawPlus

The Command Widget

Application Header file
Class Header file
Class
Class Name
Superclass

<X11/XawPlus/Command.h>
<X11/XawPlus/CommandP.h>
commandWidgetClass
Command
Label

The Command widget is an rectangular area, that contains a text label or bitmap image. Those selectable areas are often referred to as "buttons". When the pointer cursor is on a button, it becomes highlighted. This highlighting indicates that the button is ready for selection. When pointer button 1 (normally the left mouse button) is pressed, the Command widget indicates that it has been selected by changing its shape so it looks like a sunken button. When the button is released, the Command widget's notify action will be invoked, calling all functions on its callback list. If the pointer is moved out of the widget before the button is released, the widget changed the shape to an unpressed button. Releasing the button has no effect in this case. This behavior allows the user to cancel an action.

Differences between Xaw and XawPlus

Since the 3D extensions of Simple are inserted, the Command widget has the additional resources highlightColor, shadowColor and buttonBorderWidth. The default background color is now grey75. These three colors and the width of the button border are used to draw the shape of a button with the inherited methods of the Simple class. Since XawPlus only supply rectangular buttons, the resources shapeStyle and cornerRoundPercent has no meaning.

The bitmap and leftBitmap resources now also provide support of XPM styled pixmaps. These resources are inherited from the Label widget class. Look there for a description of this new feature.

Command provides tooltips. If a help text and useHelp is set in the resources, a help window is popped up afer 1.2 seconds when the mouse pointer stay over the widgets window.

Resources

When creating a Command widget instance, the following resources are retrieved from the argument list of XtSetValues() or XtVaSetValues() or from the resource database:

Name	Class	Type	Default Value
OBJECT:
destroyCallback	Callback	Pointer	NULL
RECTANGLE:
borderWidth height sensitive width x y	BorderWidth Height Sensitive Width Position Position	Dimension Dimension Boolean Dimension Position Position	0 12 True 12 0 0
CORE:
border background mappedWhenManaged	BorderColor Background MappedWhenManaged	Pixel Pixel Boolean	XtDefaultForeground grey75 True
SIMPLE:
cursor cursorName pointerColor pointerColorBackground insensitiveBorder international highlightColor shadowColor buttonBorderWidth	Cursor Cursor Foreground Background Insensitive International Background Background Width	Cursor String Pixel Pixel Pixmap Boolean Pixel Pixel Dimension	None NULL XtDefaultForeground XtDefaultBackground NULL False grey90 grey40 2
LABEL:
font fontset encoding foreground internalHeight internalWidth justify resize truncateLabel truncLeftSide label leftBitmap leftClipMask bitmap clipMask	Font FontSet Encoding Foreground Height Width Justify Resize Truncate Truncate Label LeftBitmap LeftBitmap Pixmap Pixmap	XFontStruct* FontSet unsigned char Pixel Dimension Dimension XtJustify Boolean Boolean Boolean String Bitmap ClipMask Bitmap ClipMask	XtDefaultFont XtDefaultFontSet XawTextEncoding8bit XtDefaultForeground 2 4 XtJustifyCenter True True False NULL None None None None
COMMAND:
helpText helpBackground useHelp highlightThickness highlightMode callback translations accelerators ancestorSensitive	Label Background Boolean Thickness Boolean Callback Translations Accelerators AncestorSensitive	String Pixel Boolean Dimension Boolean XtCallbackList TranslationTable AcceleratorTable Boolean	NULL LightGoldenrodYellow True 2 True NULL see doc or source NULL True

helpText	The help text, used in the help popup window.
helpBackground	The background color of the help window.
useHelp	If this resource is set to True and a help text is set, the help function is activated. Command creates an override shell, containing a Label widget. The Label widget get the helpBackground resource as background color and the helpText resource as label text.
highlightMode	If this resource is set to True, the new highlighting of the command widget is activated. By default the button looks flat. If the mouse pointer enters the button, the interior looks like a raised button shape. If this resource is set to False no highlighting is available. The button shows its raised interior by default. The old hightlight mode of Xaw is not longer supported.

Command Actions

The Command widget supports the following actions:

Switching the button's interior between raised and sunken and flat button shape

set, unset

reset

Processing application callbacks with notify.
Switching the internal border between highlighted and unhighlighted states with

highlight

unhighlight

The following are the default translation bindings used by the Command widget:

<EnterWindow>

<LeaveWindow>

<Btn1Down>

<Btn1Up>

highlight()
reset()
set()
notify(), unset()

The full list of actions supported by Command is:

highlight()	Displays the interior of the button in the raised button style, if highlightMode is set to True. If not, the button is always displayed in the raised button style. In this case highlight() has no meaning. Since XawPlus 2.0 the conditions WhenUnset and Always are not longer supported.
unhighlight()	Displays a flat button border if highlightMode is set to True. If not, the button is displayed in the raised button style. In this case unhighlight() has no meaning.
set()	Enters the set state, in which notify is possible. This action causes the button to display its interior in the sunken button style.
unset()	Cancels the set state and displays the interior of the button in the raised button style.
reset()	Cancels any set or highlight and displays the interior of the button in the flat button style if highlightMode is set to True. If not, the button is displayed in the raised button style.
notify()	When the button is in the set state this action calls all functions in the callback list named by the callback resource. The value of the call_data argument passed to these functions is undefined.

In contrast to Xaw, with XawPlus the set(), unset(), and reset() actions have the same effect with a multi-plane XPM pixmap.

XawPlus_________________________________________________________

XawPlusDoc/MenuButton.html The MenuButton Widget

_________________________________________________________XawPlus

The MenuButton Widget

Application Header file
Class Header file
Class
Class Name
Superclass

<X11/XawPlus/MenuButton.h>
<X11/XawPlus/MenuButtonP.h>
menuButtonWidgetClass
MenuButton
Command

The MenuButton widget is an rectangular area, that contains a text label or bitmap image. When the pointer cursor is on the button, the button becomes highlighted. This highlighting indicates that the button is ready for selection. When a pointer button is pressed, the MenuButton widget will pop up the menu that has been named in the menuName resource.

Differences between Xaw and XawPlus

Since the 3D extensions of Simple are inserted, the MenuButton widget has the additional resources highlightColor, shadowColor and buttonBorderWidth. The default background color is now grey75. These three colors and the width of the button border are used to draw the shape of a button with an inherited method of the Simple class. Since XawPlus only supply rectangular buttons, the resources shapeStyle and cornerRoundPercent (inherited from the Command widget class) lost their meaning.

The bitmap and leftBitmap resources now also provide support of XPM styled pixmaps. These resources are inherited from the Label widget class. Look there for a description of this new feature.

Since Command provides tooltips, this feature is also available in MenuButton. If a help text and useHelp is set in the resources, a help window is popped up afer 1.2 seconds when the mouse pointer stay over the widgets window.

Resources

When creating a MenuButton widget instance, the following resources are retrieved from the argument list of XtSetValues() or XtVaSetValues() or from the resource database:

Name	Class	Type	Default Value
OBJECT:
destroyCallback	Callback	Pointer	NULL
RECTANGLE:
borderWidth height sensitive width x y	BorderWidth Height Sensitive Width Position Position	Dimension Dimension Boolean Dimension Position Position	0 12 True 12 0 0
CORE:
border background mappedWhenManaged	BorderColor Background MappedWhenManaged	Pixel Pixel Boolean	XtDefaultForeground grey75 True
SIMPLE:
cursor cursorName pointerColor pointerColorBackground insensitiveBorder international highlightColor shadowColor buttonBorderWidth	Cursor Cursor Foreground Background Insensitive International Background Background Width	Cursor String Pixel Pixel Pixmap Boolean Pixel Pixel Dimension	None NULL XtDefaultForeground XtDefaultBackground NULL False grey90 grey40 2
LABEL:
font fontset encoding foreground internalHeight internalWidth justify resize truncateLabel truncLeftSide label leftBitmap leftClipMask bitmap clipMask	Font FontSet Encoding Foreground Height Width Justify Resize Truncate Truncate Label LeftBitmap LeftBitmap Pixmap Pixmap	XFontStruct* FontSet unsigned char Pixel Dimension Dimension XtJustify Boolean Boolean Boolean String Bitmap ClipMask Bitmap ClipMask	XtDefaultFont XtDefaultFontSet XawTextEncoding8bit XtDefaultForeground 2 4 XtJustifyCenter True True False NULL None None None None
COMMAND:
helpText helpBackground useHelp highlightThickness highlightMode callback translations accelerators ancestorSensitive	Label Background Boolean Thickness Boolean Callback Translations Accelerators AncestorSensitive	String Pixel Boolean Dimension Boolean XtCallbackList TranslationTable AcceleratorTable Boolean	NULL LightGoldenrodYellow True 2 True NULL see doc or source NULL True
MENUBUTTON:
menuName	MenuName	String	"menu"

menuName

The name of a popup shell to popup as a menu. The MenuButton will search for this name using XtNameToWidget starting with itself as the reference widget. If it is unsuccessful it will continue up the widget tree using each of its ancestors as the reference widget. If it is still unsuccessful it will print a warning message and give up. When the menu is found it will be popped up exclusive and spring_loaded. The MenuButton widget does not copy the value of this resource into newly allocated memory. The application programmer must pass the resource value in nonvolatile memory.

MenuButton Actions

The MenuButton widget supports the following actions:

Switching the button's interior between raised and sunken button shape with set,
unset and reset.
Processing application callbacks with notify
Switching the internal border between highlighted and unhighlighted states with
highlight and unhighlight.
Popping up a menu with PopupMenu

The following are the default translation bindings used by the MenuButton widget:

highlight()
reset()
reset(), PopupMenu()

The full list of actions supported by MenuButton is:

highlight()	Displays the interior of the button in the raised style, if highlightMode is set to True. If not, the button is always displayed in the raised style. In this case highlight() has no meaning. Since XawPlus 2.0 the conditions WhenUnset and Always are not longer supported.
unhighlight()	Displays a flat border if highlightMode is set to True. If not, the button is displayed in the raised style. In this case unhighlight() has no meaning.
set()	Enters the set state, in which notify is possible. This action causes the button to display its interior in the sunken button style.
unset()	Cancels the set state and displays the interior of the button in the raised button style
reset()	Cancels any set or highlight and displays the interior of the toggle in the flat style if highlightMode is set to True. If not, the toggle is displayed in the raised style.
notify()	When the button is in the set state this action calls all functions in the callback list named by the callback resource. The value of the call_data argument passed to these functions is undefined.
PopupMenu()	Pops up the menu specified by the menuName resource.

The MenuButton widget does not place a server grab on itself. Instead, PopupMenu is registered as a grab action. As a result, clients which popup menus without using XtMenuPopup or MenuPopup or PopupMenu in translations will fail to have a grab active. They should make a call to XtRegisterGrabAction on the appropriate action in the application initialization routine, or use a different translation.

XawPlus_________________________________________________________

XawPlusDoc/Toggle.html The Toggle Widget

_________________________________________________________XawPlus

The Toggle Widget

Application Header file
Class Header file
Class
Class Name
Superclass

<X11/XawPlus/Toggle.h>
<X11/XawPlus/ToggleP.h>
toggleWidgetClass
Toggle
Command

The Toggle widget is an rectangular area, containing a text label or bitmap image. This widget maintains a Boolean state (e.g. True/False or On/Off) and changes state whenever it is selected. When the pointer is on the toggle, its shape may become highlighted. This highlighting indicates that the toggle is now ready for selection. When pointer button 1 is pressed and released, the Toggle widget indicates that it has changed state by displaying itself as a sunken button and its notify action is invoked, calling all functions on its callback list. If the pointer is moved out of the widget before the toggle is released, the widget display itself as an unpressed button and releasing the button has no effect. This behavior allows the user to cancel an action.

Toggle buttons may also be part of a radio group. A radio group is a list of at least two Toggle buttons in which no more than one Toggle may be set at any time. A radio group is identified by the widget ID of any one of its members. The convenience routine XawToggleGetCurrent will return information about the Toggle button in the radio group. Toggle widget state is preserved across changes in sensitivity.

Differences between Xaw and XawPlus

Since the 3D extensions of Simple are inserted, the Toggle widget has the additional resources highlightColor, shadowColor and buttonBorderWidth. The default background color is now grey75. These three colors and the width of the button border are used to draw the shape of a button with the inherited methods of the Simple widget class. Since XawPlus only supply rectangular buttons, the resources shapeStyle and cornerRoundPercent has no meaning.

The bitmap and leftBitmap resources now also provide support of XPM styled pixmaps. These resources are inherited from the Label widget class. Look there for a description of this new feature.

Toggle provides tooltips. If a help text and useHelp is set in the resources, a help window is popped up afer 1.2 seconds when the mouse pointer stay over the widgets window. This feature is inherited from the Command widget class.

Resources

When creating a Toggle widget instance, the following resources are retrieved from the argument list of XtSetValues() or XtVaSetValues() or from the resource database:

Name	Class	Type	Default Value
OBJECT:
destroyCallback	Callback	Pointer	NULL
RECTANGLE:
borderWidth height sensitive width x y	BorderWidth Height Sensitive Width Position Position	Dimension Dimension Boolean Dimension Position Position	0 12 True 12 0 0
CORE:
border background mappedWhenManaged	BorderColor Background MappedWhenManaged	Pixel Pixel Boolean	XtDefaultForeground grey75 True
SIMPLE:
cursor cursorName pointerColor pointerColorBackground insensitiveBorder international highlightColor shadowColor buttonBorderWidth	Cursor Cursor Foreground Background Insensitive International Background Background Width	Cursor String Pixel Pixel Pixmap Boolean Pixel Pixel Dimension	None NULL XtDefaultForeground XtDefaultBackground NULL False grey90 grey40 2
LABEL:
font fontset encoding foreground internalHeight internalWidth justify resize truncateLabel truncLeftSide label leftBitmap leftClipMask bitmap clipMask	Font FontSet Encoding Foreground Height Width Justify Resize Truncate Truncate Label LeftBitmap LeftBitmap Pixmap Pixmap	XFontStruct* FontSet unsigned char Pixel Dimension Dimension XtJustify Boolean Boolean Boolean String Bitmap ClipMask Bitmap ClipMask	XtDefaultFont XtDefaultFontSet XawTextEncoding8bit XtDefaultForeground 2 4 XtJustifyCenter True True False NULL None None None None
COMMAND:
helpText helpBackground useHelp highlightThickness highlightMode callback translations accelerators ancestorSensitive	Label Background Boolean Thickness Boolean Callback Translations Accelerators AncestorSensitive	String Pixel Boolean Dimension Boolean XtCallbackList TranslationTable AcceleratorTable Boolean	NULL LightGoldenrodYellow True 2 True NULL see doc or source NULL True
TOGGLE:
radioGroup radioData state	RadioGroup RadioData State	Widget Pointer Boolean	NULL ) (caddr_t)Widget *) Off

*)	To use the toggle as a radio toggle button, set this resource to point to any other widget in the radio group.
**)	This is the data returned from a call to XtToggleGetCurrent, by default this is set to the name of toggle widget.

radioData	Specifies the data that will be returned by XawToggleGetCurrent() when this is the currently set widget in the radio group. This value is also used to identify the Toggle that will be set by a call to XawToggleSetCurrent(). The value NULL will be returned by XawToggleGetCurrent() if no widget in a radio group is currently set. Programmers must not specify NULL (or Zero) as radioData.
radioGroup	Specifies another Toggle widget that is in the radio group to which this Toggle widget should be added. A radio group is a group of at least two Toggle widgets, only one of which may be set at a time. If this value is NULL (the default) then the Toggle will not be part of any radio group and can change state without affecting any other Toggle widgets. If the widget specified in this resource is not already in a radio group then a new radio group will be created containing these two Toggle widgets. No Toggle widget can be in multiple radio groups. The behavior of a radio group of one toggle is undefined. A converter is registered which will convert widget names to widgets without caching.
state	Specifies whether the Toggle widget is set (True) or unset (False).

Toggle Actions

The Toggle widget supports the following actions:

Switching the button between raised or sunken shape with set, unset and toggle.
Processing application callbacks with notify
Switching between highlighted and unhighlighted states with highlight and unhighlight.

The following are the default translation bindings used by the Toggle widget:

highlight()
unhighlight()
toggle(), notify()

The full list of actions supported by Toggle is:

highlight()	Displays the interior of the toggle in the raised button style, if highlightMode is set to True. If not, the toggle is always displayed in the raised button style. In this case highlight() has no meaning. Since XawPlus 2.0 the conditions WhenUnset and Always are not longer supported.
unhighlight()	Displays a flat border if highlightMode is set to True. If not, the toggle is displayed in the raised style. In this case unhighlight() has no meaning.
set()	Enters the set state, in which notify is possible. This action causes the toggle to display its interior in the sunken style.
unset()	Cancels the set state and displays the interior as a raised button.
toggle()	Changes the current state of the Toggle widget, causing to be set if it was previously unset, and unset if it was previously set. If the widget is to be set, and is in a radio group then this procedure may unset another Toggle widget causing all routines on its callback list to be invoked. The callback routines for the Toggle that is to be unset will be called before the one that is to be set.
reset()	Cancels any set or highlight and displays the interior of the toggle in the flat style if highlightMode is set to True. If not, the toggle is displayed in the raised style.
notify()	When the button is in the set state this action calls all functions in the callback list named by the callback resource. The value of the call_data argument in these callback functions is undefined.

In contrast to Xaw with XawPlus the set(), unset(), and reset() actions have the same effect with a multi-plane XPM pixmap.

Radio Groups

There are typically two types of radio groups desired by applications. The default translations for the Toggle widget implement a "zero or one of many" radio group. This means that there may be no more than one button active, but there need not be any buttons active.

The other type of radio group is "one of many" and has the more strict policy that there will always be exactly one radio button active. Toggle widgets can be used to provide this interface with a slight modification to the translation table of each Toggle in the group.

highlight()
unhighlight()
set(), notify()

This translation table will not allow any Toggle to be unset except as a result of another Toggle becoming set. It is the application programmer's responsibility to choose an initial state for the radio group by setting the state resource of one of its member widgets to True.

Convenience Routines

The following functions allow easy access to the Toggle widget's radio group functionality.

To enable an application to change the Toggle's radio group, add the Toggle to a radio group, or remove the Toggle from a radio group, use XawToggleChangeRadioGroup():

void XawToggleChangeRadioGroup(w, radio_group)
Widget w, radio_group;

w	Specifies the Toggle widget.
radio_group	Specifies any Toggle in the new radio group. If NULL then the Toggle will be removed from any radio group of which it is a member.

If a Toggle is already set in the new radio group, and the Toggle to be added is also set then the previously set Toggle in the radio group is unset and its callback procedures are invoked.

To find the currently selected Toggle in a radio group of Toggle widgets use XawToggleGetCurrent():

XtPointer XawToggleGetCurrent(radio_group);
Widget radio_group;

radio_group

Specifies any Toggle widget in the radio group.

The value returned by this function is the radioData of the Toggle in this radio group that is currently set. The default value for radioData is the name of that Toggle widget. If no Toggle is set in the radio group specified then NULL is returned.

To change the Toggle that is currently set in a radio group use XawToggleSetCurrent():

void XawToggleSetCurrent(radio_group, radio_data);
Widget radio_group;
XtPointer radio_data;

radio_group	Specifies any Toggle widget in the radio group.
radio_data	Specifies the radioData identifying the Toggle that should be set in the radio group specified by the radio_group argument.

XawToggleSetCurrent() locates the Toggle widget to be set by matching radio_data against the radioData for each Toggle in the radio group. If none match, XawToggleSetCurrent() returns without making any changes. If more than one Toggle matches, XawToggleSetCurrent() will choose a Toggle to set arbitrarily. If this causes any Toggle widgets to change state, all routines in their callback lists will be invoked. The callback routines for a Toggle that is to be unset will be called before the one that is to be set.

To unset all Toggle widgets in a radio group use XawToggleUnsetCurrent():

void XawToggleUnsetCurrent(radio_group);
Widget radio_group;

radio_group

Specifies any Toggle widget in the radio group.

If this causes a Toggle widget to change state, all routines on its callback list will be invoked.

XawPlus__________________________________________________________

XawPlusDoc/Repeater.html The Repeater Widget

_________________________________________________________XawPlus

The Repeater Widget

Application Header file
Class Header file
Class
Class Name
Superclass

<X11/XawPlus/Repeater.h>
<X11/XawPlus/RepeaterP.h>
repeaterWidgetClass
Repeater
Command

The Repeater widget is a version of the Command button that triggers at an increasing rate while it is held down. It is typically used to implement valuators or certain types of scrollbars.

Differences between Xaw and XawPlus

Since the 3D extensions of Simple are inserted, the Repeater widget has the additional resources highlightColor, shadowColor and buttonBorderWidth. The default background color is now grey75. These three colors and the width of the button border are used to draw the shape of a button with the inherited methods of the Simple class. Since XawPlus only supply rectangular buttons, the resources shapeStyle and cornerRoundPercent has no meaning.

The bitmap and leftBitmap resources now also provide support of XPM styled pixmaps. These resources are inherited from the Label widget class. Look there for a description of this new feature.

Repeater provides tooltips, inherited from Command. If a help text and useHelp is set in the resources, a help window is popped up afer 1.2 seconds when the mouse pointer stay over the widgets window.

Resources

When creating a Command widget instance, the following resources are retrieved from the argument list of XtSetValues() or XtVaSetValues() or from the resource database:

Name	Class	Type	Default Value
OBJECT:
destroyCallback	Callback	Pointer	NULL
RECTANGLE:
borderWidth height sensitive width x y	BorderWidth Height Sensitive Width Position Position	Dimension Dimension Boolean Dimension Position Position	0 12 True 12 0 0
CORE:
border background mappedWhenManaged	BorderColor Background MappedWhenManaged	Pixel Pixel Boolean	XtDefaultForeground grey75 True
SIMPLE:
cursor cursorName pointerColor pointerColorBackground insensitiveBorder international highlightColor shadowColor buttonBorderWidth	Cursor Cursor Foreground Background Insensitive International Background Background Width	Cursor String Pixel Pixel Pixmap Boolean Pixel Pixel Dimension	None NULL XtDefaultForeground XtDefaultBackground NULL False grey90 grey40 2
LABEL:
font fontset encoding foreground internalHeight internalWidth justify resize truncateLabel truncLeftSide label leftBitmap leftClipMask bitmap clipMask	Font FontSet Encoding Foreground Height Width Justify Resize Truncate Truncate Label LeftBitmap LeftBitmap Pixmap Pixmap	XFontStruct* FontSet unsigned char Pixel Dimension Dimension XtJustify Boolean Boolean Boolean String Bitmap ClipMask Bitmap ClipMask	XtDefaultFont XtDefaultFontSet XawTextEncoding8bit XtDefaultForeground 2 4 XtJustifyCenter True True False NULL None None None None
COMMAND:
helpText helpBackground useHelp highlightThickness highlightMode callback translations accelerators ancestorSensitive	Label Background Boolean Thickness Boolean Callback Translations Accelerators AncestorSensitive	String Pixel Boolean Dimension Boolean XtCallbackList TranslationTable AcceleratorTable Boolean	NULL LightGoldenrodYellow True 2 True NULL see doc or source NULL True
REPEATER:
decay flash initialDelay minimumDelay repeatDelay startCallback stopCallback	Decay Boolean Delay MinimumDelay Delay StartCallback StopCallback	int Boolean int int int XtCallbackList XtCallbackList	5 milliseconds FALSE 200 milliseconds 10 milliseconds 50 milliseconds NULL NULL

decay	The number of milliseconds that should be subtracted from each succeeding interval while the Repeater button is being held down until the interval has reached minimumDelay milliseconds.
flash	Whether or not to flash the Repeater button whenever the timer goes off.
initialDelay	The number of milliseconds between the beginning of the Repeater button being held down and the first invocation of the callback function.
minimumDelay	The minimum time between callbacks in milliseconds.
repeatDelay	The number of milliseconds between each callback after the first (minus an increasing number of decays).
startCallback	The list of functions to invoke by the start action (typically when the Repeater button is first pressed). The callback data parameter is set to NULL.
stopCallback	The list of functions to invoke by the stop action (typically when the Repeater button is released). The callback data parameter is set to NULL.

Repeater Actions

The Repeater widget supports the following actions beyond those of the Command button:

start()	This invokes the functions on the startCallback and callback lists and sets a timer to go off in initialDelay milliseconds. The timer will cause the callback functions to be invoked with increasing frequency until the stop action occurs.
stop()	This invokes the functions on the stopCallback list and prevents any further timers from occuring until the next start action.

The following are the default translation bindings used by the Repeater widget:

highlight()
unhighlight()
set(), start()
stop(), unset()

XawPlus_________________________________________________________

XawPlusDoc/SmeLine.html The SmeLine Object

_________________________________________________________XawPlus

The SmeLine Object

Application Header file
Class Header file
Class
Class Name
Superclass

<X11/XawPlus/SmeLine.h>
<X11/XawPlus/SmeLineP.h>
smeLineObjectClass
SmeLine
Sme

The SmeLine object is used to add a horizontal line or menu separator to a menu. Since each menu entry is an independent object, the application is able to change the color, height, and other attributes of the menu entries, on an entry by entry basis. This entry is not selectable, and will not highlight when the pointer cursor is over it.

Differences between Xaw and XawPlus

The menu separator of XawPlus is now 3D styled. That is the reason why the resources foreground and stipple are not longer used. Instead of this, the SmeLine object uses the resources highlightColor and shadowColor inherited from Sme, to draw the horizontal lines.

Resources

The resources associated with the SmeLine object are defined in this section, and affect only the single menu entry specified by this object.

Name	Class	Type	Default Value
OBJECT:
destroyCallback	Callback	Pointer	NULL
RECTANGLE:
borderWidth height sensitive width x y	BorderWidth Height Sensitive Width Position Position	Dimension Dimension Boolean Dimension Position Position	0 0 True 0 0 0
SME:
callback highlightColor shadowColor international	Callback Background Background International	Pointer Pixel Pixel Boolean	NULL grey90 grey40 False
SMELINE:
lineWidth	Width	Dimension	1

lineWidth

This is the width of the horizontal line that is to be displayed. Since this object is displayed with a highlighted and a shadowed line and this object draw each line with the width lineWidth, the total width becomes 2 * lineWidth.

XawPlus_________________________________________________________

XawPlusDoc/SmeBSB.html The SmeBSB Object

_________________________________________________________XawPlus

The SmeBSB Object

Application Header file
Class Header file
Class
Class Name
Superclass

<X11/XawPlus/SmeBSB.h>
<X11/XawPlus/SmeBSBP.h>
smeBSBObjectClass
SmeBSB
Sme

The SmeBSB object is used to create a menu entry that contains a string, and optional bitmaps in its left and right margins. Since each menu entry is an independent object, the application is able to change the font, color, height, and other attributes of the menu entries, on an entry by entry basis.

Differences between Xaw and XawPlus

Insensitive entries are shown embossed using the color resources inherited from the Sme object. The left and right bitmaps may be color pixmaps. Support of clip masks for nonrectangular pixmaps is available. Installed converters for the left and right bitmaps and its clip masks are available.

Resources

The resources associated with the SmeBSB object are defined in this section, and affect only the single menu entry specified by this object.

Name	Class	Type	Default Value
OBJECT:
destroyCallback	Callback	Pointer	NULL
RECTANGLE:
borderWidth height sensitive width x y	BorderWidth Height Sensitive Width Position Position	Dimension Dimension Boolean Dimension Position Position	0 0 True 0 0 0
SME:
callback highlightColor shadowColor international	Callback Background Background International	Pointer Pixel Pixel Boolean	NULL grey90 grey40 False
SMEBSB:
foreground font fontSet label justify vertSpace leftMargin rightMargin leftBitmap leftClipMask rightBitmap rightClipMask	Foreground Font FontSet Label Justify VertSpace HorizontalMargins HorizontalMargins LeftBitmap LeftBitmap RightBitmap RightBitmap	Pixel XFontStruct * FontSet String Justify int Dimension Dimension Bitmap ClipMask Bitmap ClipMask	XtDefaultForeground XtDefaultFont XtDefaultFontSet Name of entry XtJustifyLeft 25 4 4 None None None None

foreground	A pixel value which indexes the SimpleMenu's colormap to derive the foreground color of the menu entry's window. This color is also used to render all 1's in the left and right bitmaps. Keep in mind that the SimpleMenu widget will force the width of all menu entries to be the width of the longest entry.
font	The font used to display the text label.
fontSet	The fontSet used to display the text label, if the international resource is set.
justify	How the label is to be rendered between the left and right margins when the space is wider than the actual text. This resource may be specified with the values XtJustifyLeft, XtJustifyCenter, or XtJustifyRight. When specifying the justification from a resource file the values left, center, or right may be.
label	This is a the string that will be displayed in the menu entry. The exact location of this string within the bounds of the menu entry is controlled by the leftMargin, rightMargin, vertSpace, and justify resources.
vertSpace	This is the amount of vertical padding, expressed as a percentage of the height of the font, that is to be placed around the label of a menu entry. The label and bitmaps are always centered vertically within the menu. The default value for this resource (25) causes the default height to be 125% of the height of the font.
leftMargin, rightMargin	This is the amount of space (in pixels) that will be left between the edge of the menu entry and the label string.
leftBitmap, leftClipMask, rightBitmap, rightClipMask	This is a name of a bitmap or pixmap to display in the left or right margin of the menu entry. All 1's of a bitmap will be rendered in the foreground color, and all 0's will be drawn in the background color of the SimpleMenu widget. Color pixmaps support works a little different. The color values are copied directly into the rectangular area, reserved for the pixmap. Support of nonrectangular areas is available using the left and right clip masks. These clip masks have no meaning to normal bitmaps. It is the programmers responsibility to make sure that the menu entry is tall enough, and the appropriate margin wide enough to accept the bitmap. If care is not taken the bitmap may extend into another menu entry, or into this entry's label.

XawPlus_________________________________________________________

XawPlusDoc/List.html The List Widget

_________________________________________________________XawPlus

The List Widget

Application Header file
Class Header file
Class
Class Name
Superclass

<X11/XawPlus/List.h>
<X11/XawPlus/ListP.h>
ListWidgetClass
List
Simple

Differences between Xaw and XawPlus

Since the 3D extensions of Simple are inserted, the List widget has the additional resources highlightColor, shadowColor and buttonBorderWidth. The default background color is now grey75.

With Release 3.0 of XawPlus the List widget also has support for lists with an additional icon on the left side like the IconList widget in previous versions of XawPlus. To display icons and text in the list, the XawIconList structure is used, which contains pointer to strings and icons defined by the application programmer.

Resources

When creating a List widget instance, the following resources are retrieved from the argument list of XtSetValues() or XtVaSetValues() or from the resource database:

Name	Class	Type	Default Value
OBJECT:
destroyCallback	Callback	Pointer	NULL
RECTANGLE:
borderWidth height sensitive width x y	BorderWidth Height Sensitive Width Position Position	Dimension Dimension Boolean Dimension Position Position	0 12 True 12 0 0
CORE:
border background mappedWhenManaged	BorderColor Background MappedWhenManaged	Pixel Pixel Boolean	XtDefaultForeground grey75 True
SIMPLE:
cursor cursorName pointerColor pointerColorBackground insensitiveBorder international highlightColor shadowColor buttonBorderWidth	Cursor Cursor Foreground Background Insensitive International Background Background Width	Cursor String Pixel Pixel Pixmap Boolean Pixel Pixel Dimension	None NULL XtDefaultForeground XtDefaultBackground NULL False grey90 grey40 2
LIST:
callback pasteBuffer foreground font fontSet internalHeight internalWidth defaultColumns columnSpacing rowSpacing forceColumns verticalList list iconList longest numberStrings iconHeight iconWidth iconDepth	Callback Boolean Foreground Font FontSet Height Width Columns Spacing Spacing Columns Boolean List List Longest NumberStrings Height Width Depth	XtCallbackList Boolean Pixel XFontStruct * FontSet Dimension Dimension int Dimension Dimension Boolean Boolean String * XawIconList[] int int Dimension Dimension Dimension	NULL False XtDefaultForeground XtDefaultFont XtDefaultFontSet 2 4 2 6 4 False False NULL NULL 0 0 0 0 1

callback	All functions on this list are called whenever the notify action is invoked. The call_data argument contains information about the element selected and is described in detail in the List Callbacks section.
pasteBuffer	If this resource is set to True then the name of the currently selected list element will be put into CUT_BUFFER_0.
foreground	A pixel value which indexes the widget's colormap to derive the color used to paint the text of the list elements.
font	With this resource it is possible to set any available font to display the list text.
fontset	A set of fonts which will be used, if the international resource is set.
internalHeight, internalWidth	The margin, in pixels, between the edges of the list and the corresponding edge of the List widget's window.
defaultColumns	The default number of columns. This value is used when neither the width nor the height of the List widget is specified or when forceColumns is True.
columnSpacing rowSpacing	The amount of space, in pixels, between each of the rows and columns in the list.
forceColumns	Forces the default number of columns to be used regardless of the List widget's current size.
verticalList	If this resource is set to True then the list elements will be presented in column major order.
list	An array of text strings displayed in the List widget, if there is no iconList defined. If it exists, the iconlist is used with a higher priority. If numberStrings is zero (the default) then the list must be NULL terminated. If a value is not specified for the list, then numberStrings is set to 1, and the name of the widget is used as the list, and longest is set to the length of the name of the widget. The list is used in place, and must be available to the List widget for the lifetime of this widget, or until it is changed with XtSetValues() or XawListChange(). Note that XtSetValues() only works well, if the memory location of the list structure changes. It is a good idea to use always XawListChange(). This function also overrides the higher priority of the iconList resource, if you want to change from an icon list to a simple list while runtime.
iconList	An array of text strings and icons displayed in the List widget. If numberStrings is zero (the default) then the iconList must be NULL terminated. If a value is not specified for the iconList, then the list resource is used. The iconList must be available to the List widget for the lifetime of this widget, or until it is changed with XtSetValues() or better with XawIconListChange(). Note that XtSetValues() only works well, if the memory location of the list structure changes. It is a good idea to use always XawIconListChange().
longest	Specifies the width, in pixels, of the longest string in the current list. The List widget will compute this value if zero (the default) is specified. If this resource is not correctly specified, selection of list items may not work properly.
numberStrings	The number of strings in the current list. If a value of zero (the default) is specified, the List widget will compute it. When computing the number of strings the List widget assumes that the list is NULL terminated.
iconHeight, iconWidth	Set this resources to the width and height of your bitmap or pixmap icons. iconWidth and iconHeight are used to reserve enough space in the list entries.
iconDepth	Use the value of 1 for traditional XBM bitmap icons or the depth of your pixmaps for color icons like XPMs.

List Actions

The List widget supports the following actions:

Highlighting and unhighlighting the list element under the pointer with Set and Unset.
Processing application callbacks with Notify.

The following is the default translation table used by the List Widget:

<Btn1Down>,<Btn1Up>

Set(), Notify()

The full list of actions supported by List widget is:

Set()	Sets the list element that is currently under the pointer. To inform the user that this element is currently set, it is drawn with is foreground and background colors reversed. If this action is called when there is no list element under the cursor, the currently set element will be unset.
Unset()	Cancels the set state of the element under the pointer, and redraws it with normal foreground and background colors.
Notify()	Calls all callbacks on the List widget's callback list. Information about the currently selected list element is passed in the call_data argument (see List Callback below).

List Callbacks

All procedures on the List widget's callback list will have a XawListReturnStruct passed to them as call_data. The structure is defined in the List widget's application header file.

typedef struct _XawListReturnStruct {

String string; /* string shown in the list. */
int list_index; /* index of the item selected. */

} XawListReturnStruct;

The list_index item used to be called simply index. Unfortunately, this name collided with a global name defined on some operating systems, and had to be changed.

Changing the List

To change the list that is displayed, use XawListChange():

void XawListChange(w, list, nitems, longest, resize)
Widget w;
String * list;
int nitems, longest;
Boolean resize;

w	Specifies the List widget.
list	Specifies the new list for the List widget to display.
nitems	Specifies the number of items in the list. If a value less than 1 is specified, list must be NULL terminated, and the number of items will be calculated by the List widget.
longest	Specifies the length of the longest item in the list in pixels. If a value less than 1 is specified, the List widget will calculate the value.
resize	Specifies a Boolean value that if True indicates that the List widget should try to resize itself after making the change. The constraints of the List widget's parent are always enforced, regardless of the value specified here.

Changing the Icon List

To change the list that is displayed, use XawIconListChange():

void XawIconListChange(w, list, nitems, longest, resize)
Widget w;
XawIconList *list;
int nitems, longest;
int width, height, depth;
Boolean resize;

w	Specifies the List widget.
list	Specifies the new list for the List widget to display.
nitems	Specifies the number of items in the list. If a value less than 1 is specified, list must be NULL terminated, and the number of items will be calculated by the List widget.
longest	Specifies the length of the longest item in the list in pixels. If a value less than 1 is specified, the List widget will calculate the value.
width, height	Specifies the width and height of your bitmap or pixmap icons. These values are used to reserve enough space for the icons in the list entries.
iconDepth	Use the value of 1 for traditional XBM bitmap icons or the depth of your pixmaps for color icons like XPMs.
resize	Specifies a Boolean value that if True indicates that the IconList widget should try to resize itself after making the change. The constraints of the IconList widget's parent are always enforced, regardless of the value specified here.

The IconList has the following structure:

typedef struct _XawIconList {

Pixmap bitmap; /* the icon, used as left bitmap */
Pixmap clipMask; /* drawing mask for the icon */
String string; /* text for the list entry */

} XawIconList;

It is not required to set all entries of the structure. Unused entries of the type Pixmap has to be initialized with XtUnspecifiedPixmap and unused strings with NULL.

Highlighting an Item

To highlight an item in the list, use XawListHighlight():

void XawListHighlight(w, item)
Widget w;
int item;

w	Specifies the List widget.
item	Specifies an index into the current list that indicates the item to be highlighted.

Only one item can be highlighted at a time. If an item is already highlighted when XawListHighlight() is called, the highlighted item is unhighlighted before the new item is highlighted.

Unhighlighting an Item

To unhighlight the currently highlighted item in the list, use XawListUnhighlight():

void XawListUnhighlight(w)
Widget w;

w	Specifies the List widget.

Retrieving the Currently Selected Item

To retrieve the list element that is currently set, use XawListShowCurrent().

XawListReturnStruct *XawListShowCurrent(w)
Widget w;

w	Specifies the List widget.

XawListShowCurrent() returns a pointer to an XawListReturnStruct structure, containing the currently highlighted item. If the value of the index member is XAW_LIST_NONE, the string member is undefined, and no item is currently selected.

XawPlus_________________________________________________________

XawPlusDoc/Panner.html The Panner Widget

_________________________________________________________XawPlus

The Panner Widget

Application Header file
Class Header file
Class
Class Name
Superclass

<X11/XawPlus/Panner.h>
<X11/XawPlus/PannerP.h>
pannerWidgetClass
Panner
Simple

The Panner widget represents a rectangular region (called the ``canvas'') of which only a smaller, enclosed rectangular region (called the ``slider'') by is visible at any given time. It is typically used with a Porthole widget to scroll a third widget in two dimensions.

When a Panner is created, it is drawn with the slider in a contrasting color. The slider may be moved around the canvas by pressing, dragging, and then releasing Button1. While scrolling is in progress, the application receives notification through callback procedures which it may use to update any associated widgets. Notification may be done either continuously whenever the slider moves or discretely whenever the slider has been given a new location.

Differences between Xaw and XawPlus

Since the 3D extensions of Simple are inserted, the Panner widget has the additional resources highlightColor, shadowColor and buttonBorderWidth. The color resources and the border width resource are used to display a three dimensional styled slider. The default background color is now grey75.

The backgroundStipple, lineWidth, rubberBand, shadowThickness and foreground resources are not longer used. The old shadowColor resource is replaced by Simple with a different meaning.

The set() action is not supported by the XawPlus version of this widget.

Resources

When creating a Panner widget instance, the following resources are retrieved from the argument list of XtSetValues() or XtVaSetValues() or from the resource database:

Name	Class	Type	Default Value
OBJECT:
destroyCallback	Callback	Pointer	NULL
RECTANGLE:
borderWidth height sensitive width x y	BorderWidth Height Sensitive Width Position Position	Dimension Dimension Boolean Dimension Position Position	0 12 True 12 0 0
CORE:
border background mappedWhenManaged	BorderColor Background MappedWhenManaged	Pixel Pixel Boolean	XtDefaultForeground grey75 True
SIMPLE:
cursor cursorName pointerColor pointerColorBackground insensitiveBorder international highlightColor shadowColor buttonBorderWidth	Cursor Cursor Foreground Background Insensitive International Background Background Width	Cursor String Pixel Pixel Pixmap Boolean Pixel Pixel Dimension	None NULL XtDefaultForeground XtDefaultBackground NULL False grey90 grey40 2
PANNER:
allowOff canvasWidth canvasHeight defaultScale internalSpace reportCallback resize sliderX sliderY sliderWidth sliderHeight	AllowOff CanvasWidth CanvasHeight DefaultScale InternalSpace ReportCallback Resize SliderX SliderY SliderWidth SliderHeight	Boolean Dimension Dimension Dimension Dimension XtCallbackList Boolean Position Position Dimension Dimension	FALSE 0 0 8 percent 4 NULL TRUE 0 0 0 0

allowOff	Whether to allow the edges of the slider to go off the edges of the canvas.
canvasHeight canvasWidth	The size of the canvas.
defaultScale	The percentage size that the Panner widget should have relative to the size of the canvas.
internalSpace	The width of internal border in pixels between a slider representing the full size of the canvas and the edge of the Panner widget.
reportCallback	All functions on this callback list are called when the notify action is invoked. See the Panner Actions section for details.
resize	Whether or not to resize the panner whenever the canvas size is changed so that the defaultScale is maintained.
sliderX sliderY	The location of the slider in the coordinates of the canvas.
sliderHeight sliderWidth	The size of the slider.

Panner Actions

The actions supported by the Panner widget are:

start()	This action begins movement of the slider.
stop()	This action ends movement of the slider.
abort()	This action ends movement of the slider and restores it to the position it held when the start action was invoked.
move()	This action moves the slider.
page(xamount,yamount)	This action moves the slider by the specified amounts. The format for the amounts is a signed or unsigned floating-point number (e.g., +1.0 or -0.5) followed by either p indicating pages (slider sizes), or c indicating canvas sizes. Thus, page(+0, +0.5p) represents vertical movement down one-half the height of the slider and page(0, 0) represents moving to the upper left corner of the canvas.
notify()	This action informs the application of the slider's current position by invoking the reportCallback functions registered by the application.

The default bindings for Panner are:

<Btn1Down>:
<Btn1Motion>:
<Btn1Up>:
<Btn2Down>:
<Key>space:
<Key>Delete:
<Key>BackSpace:
<Key>Left:
<Key>Right:
<Key>Up:
<Key>Down:
<Key>Home:

start()
move()
notify(), stop()
abort()
page(1p, 1p)
page(-1p, -1p)
page(-1p, -1p)
page(-0.5p, 0)
page(0.5p, 0)
page(0, -0.5p)
page(0, 0.5p)
page(0, 0)

Panner Callbacks

The functions registered on the reportCallback list are invoked by the notify action as follows:

void ReportProc(panner, client_data, report)
Widget panner;
XtPointer client_data;
XtPointer report; /* (XawPannerReport *) */

panner Specifies the Panner widget.

client_data Specifies the client data.

report Specifies a pointer to an XawPannerReport structure containing the location and size of the slider and the size of the canvas.

XawPlus_________________________________________________________
XawPlusDoc/Scrollbar.html The Scrollbar Widget
_________________________________________________________XawPlus

The Scrollbar Widget

Application Header file
Class Header file
Class
Class Name
Superclass <X11/XawPlus/Scrollbar.h>
<X11/XawPlus/ScrollbarP.h>
scrollbarWidgetClass
Scrollbar
Simple

The Scrollbar widget is a rectangular area containing a slide region, a thumb (also known as a slide bar) and two arrow keys. A Scrollbar can be used alone, as a value generator, or it can be used within a composite widget (for example, a Viewport). A Scrollbar can be oriented either vertically or horizontally.

When a Scrollbar is created, it is drawn with the thumb as a 3D styled bar and the arrow keys at the ends of the slide region. The thumb is normally used to scroll client data and to give visual feedback (through its length) on the percentage of the client data, that is visible.

Each pointer button invokes a specific action. By default clicking with the middle mouse button (poiter button 2) let the thumb jump to the current pointer position in the slide region. With pointer 1 or 3 (left or right mouse button) the user can step page by page up or down through the corresponding document. If the pointer button 1 or 3 is clicked onto the thumb, held down and the pointer is moved, the thumb follows the pointer.

While scrolling is in progress, the application receives notification through callback procedures. For both discrete scrolling actions, the callback returns the scrollbar widget, the client_data, and the pixel position of the pointer when the button was released. For continuous scrolling, the callback routine returns the scrollbar widget, the client data, and the current relative position of the thumb.

Differences between Xaw and XawPlus

Since the 3D extensions of Simple are inserted, the Scrollbar widget has the additional resources highlightColor, shadowColor and buttonBorderWidth. The default background color is now grey75. Since Release 2.0 of XawPlus the scrollbar is Motif styled. The implementation is derived from the scrollbar implementation of Xaw3d Release 1.4.

The resources foreground and thumb and all the cursor resources are not longer used.

Resources

When creating a Scrollbar widget instance, the following resources are retrieved from the argument list of XtSetValues() or XtVaSetValues() or from the resource database:

Name Class Type Default Value

OBJECT:

destroyCallback Callback Pointer NULL

RECTANGLE:

borderWidth
height
sensitive
width
x
y BorderWidth
Height
Sensitive
Width
Position
Position Dimension
Dimension
Boolean
Dimension
Position
Position 0
12
True
12
0
0

CORE:

border
background
mappedWhenManaged BorderColor
Background
MappedWhenManaged Pixel
Pixel
Boolean XtDefaultForeground
grey75
True

SIMPLE:

cursor
cursorName
pointerColor
pointerColorBackground
insensitiveBorder
international
highlightColor
shadowColor
buttonBorderWidth Cursor
Cursor
Foreground
Background
Insensitive
International
Background
Background
Width Cursor
String
Pixel
Pixel
Pixmap
Boolean
Pixel
Pixel
Dimension None
left_ptr
XtDefaultForeground
XtDefaultBackground
NULL
False
grey90
grey40
2

SCROLLBAR:

accelerators
ancestorSensitive
jumpProc
scrollProc
thumbProc
translations

length
minimumThumb
thickness
orientation
shown
topOfThumb Accelerators
AncestorSensitive
Callback
Callback
Callback
Translations

Length
MinimumThumb
Thickness
Orientation
Shown
TopOfThumb AcceleratorTable
Boolean
XtCallbackList
XtCallbackList
XtCallbackList
TranslationTable

Dimension
Dimension
Dimension
XtOrientation
Float
Float NULL
True
NULL
NULL
NULL
see above

1
12
16
XtorientVertical
0.0
0.0

jumpProc All functions on this callback list are called when the NotifyThumb action is invoked. See the Scrollbar Actions section for details.

length The height of a vertical scrollbar or the width of a horizontal scrollbar.

minimumThumb The smallest size in pixels, to which the thumb can shrink.

orientation The orientation is the direction that the thumb will be allowed to move. This value can be either XtorientVertical or XtorientHorizontal.

scrollProc All functions on this callback list may be called when the NotifyScroll action is invoked. See the Scrollbar Actions section for details.

shown This is the size of the thumb, expressed as a percentage (0.0 - 1.0) of the length of the scrollbar.

thickness The width of a vertical scrollbar or the height of a horizontal scrollbar.

topOfThumb The location of the top of the thumb, as a percentage (0.0 - 1.0) of the length of the scrollbar. This resource was called top in previous versions of the Athena widget set. The name collided with the a Form widget constraint resource, and had to be changed.

Scrollbar Actions

The actions supported by the Scrollbar widget are:

StartScroll(value) The possible values are Forward, Backward, or Continuous. This must be the first action to begin a new movement.

NotifyScroll(value) The possible values are Proportional or FullLength. If the argument to StartScroll was Forward or Backward, NotifyScroll executes the scrollProc callbacks and passes either; the position of the pointer, if value is Proportional, or the full length of the scroll bar, if value is FullLength. If the argument to StartScroll was Continuous, NotifyScroll returns without executing any callbacks.

EndScroll() This must be the last action after a movement is complete.

MoveThumb() Repositions the Scrollbar's thumb to the current pointer location.

NotifyThumb() Calls the jumpProc callbacks and passes the relative position of the pointer as a percentage of the scroll bar length.

The default bindings for Scrollbar are:

<Btn1Down> :
<Btn2Down> :
<Btn3Down> :
<Btn1Motion> :
<Btn2Motion> :
<Btn3Motion> :
<BtnUp> : NotifyScroll()
MoveThumb() NotifyThumb()
NotifyScroll()
HandleThumb()
HandleThumb()
MoveThumb() NotifyThumb()
EndScroll()

Examples of additional bindings a user might wish to specify in a resource file are:

*Scrollbar.Translations: \\
~Metaspace: StartScroll(Forward) NotifyScroll(FullLength) \\n\\
Metaspace: StartScroll(Backward) NotifyScroll(FullLength) \\n\\
EndScroll()

Scrollbar Callbacks

There are two callback lists provided by the Scrollbar widget. The procedural interface for these functions is described here.

The calling interface to the scrollProc callback procedure is:

void ScrollProc(scrollbar, client_data, position)
Widget scrollbar;
XtPointer client_data;
XtPointer position; /* int */

scrollbar Specifies the Scrollbar widget.

client_data Specifies the client data.

position Specifies a pixel position in integer form.

The scrollProc callback is used for incremental scrolling and is called by the NotifyScroll action. The position argument is a signed quantity and should be cast to an int when used. Using the default button bindings, button 1 returns a positive value, and button 3 returns a negative value. In both cases, the magnitude of the value is the distance of the pointer in pixels from the top (or left) of the Scrollbar. The value will never be greater than the length of the Scrollbar.

The calling interface to the jumpProc callback procedure is:

void JumpProc(scrollbar, client_data, percent)
Widget scrollbar;
XtPointer client_data;
XtPointer percent_ptr; /* float* */

scrollbar Specifies the ID of the scroll bar widget.

client_data Specifies the client data.

percent_ptr Specifies the floating point position of the thumb (0.0, -1.0).

The jumpProc callback is used to implement smooth scrolling and is called by the NotifyThumb action. Percent_ptr must be cast to a pointer to float before use; i.e.

float percent = *(float*)percent_ptr;

With the default button bindings, button 2 (the middle mouse button) moves the thumb interactively, and the jumpProc is called on each new position of the pointer, while the pointer button remains down. The value specified by percent_ptr is the current location of the thumb (from the top or left of the Scrollbar) expressed as a percentage of the length of the Scrollbar.

Convenience Routines

To set the position and length of a Scrollbar thumb, use XawScrollbarSetThumb():

void XawScrollbarSetThumb(w, top, shown)
Widget w;
float top;
float shown;

w Specifies the Scrollbar widget.

top Specifies the position of the top of the thumb as a fraction of the length of the Scrollbar.

shown Specifies the length of the thumb as a fraction of the total length of the Scrollbar.

XawScrollbarThumb() moves the visible thumb to a new position (0.0, -1.0) and length (0.0, -1.0). Either the top or shown arguments can be specified as -1.0, in which case the current value is left unchanged. Values greater than 1.0 are truncated to 1.0.

If called from jumpProc, XawScrollbarSetThumb() has no effect.

Setting Float Resources

The shown and topOfThumb resources are of type float. These resources can be difficult to get into an argument list. The reason is that C performs an automatic cast of the float value to an integer value, usually truncating the important information. The following code fragment is one portable method of getting a float into an argument list.

top = 0.5;
if (sizeof(float) > sizeof(XtArgVal)) {

/*
* If a float is larger than an XtArgVal then pass this
* resource value by reference.
*/
XtSetArg(args[0], XtNshown, &top);

}
else {

/*
* Convince C not to perform an automatic conversion, which
* would truncate 0.5 to 0.
*/
XtArgVal * l_top = (XtArgVal *) ⊤
XtSetArg(args[0], XtNshown, *l_top);

}

XawPlus_________________________________________________________
XawPlusDoc/StripChart.html The StripChart Widget
_________________________________________________________XawPlus

The StripChart Widget

Application Header file
Class Header file
Class
Class Name
Superclass <X11/XawPlus/StripChart.h>
<X11/XawPlus/StripChartP.h>
stripChartWidgetClass
StripChart
Simple

The StripChart widget is used to provide a real time graphical chart of a single value. This widget is used by xload to provide the load graph. It will read data from an application, and update the chart at the update interval specified.

Differences between Xaw and XawPlus

Since the 3D extensions of Simple are inserted, the StripChart widget has the additional (but at this time not used) resources highlightColor, shadowColor and buttonBorderWidth. The default background color is now grey75.

Resources

When creating a Simple widget instance, the following resources are retrieved from the argument list of XtSetValues() or XtVaSetValues() or from the resource database:

Name Class Type Default Value

OBJECT:

destroyCallback Callback Pointer NULL

RECTANGLE:

borderWidth
height
sensitive
width
x
y BorderWidth
Height
Sensitive
Width
Position
Position Dimension
Dimension
Boolean
Dimension
Position
Position 0
120
True
120
0
0

CORE:

border
background
mappedWhenManaged BorderColor
Background
MappedWhenManaged Pixel
Pixel
Boolean XtDefaultForeground
grey75
True

SIMPLE:

cursor
cursorName
pointerColor
pointerColorBackground
insensitiveBorder
international
highlightColor
shadowColor
buttonBorderWidth Cursor
Cursor
Foreground
Background
Insensitive
International
Background
Background
Width Cursor
String
Pixel
Pixel
Pixmap
Boolean
Pixel
Pixel
Dimension None
NULL
XtDefaultForeground
XtDefaultBackground
NULL
False
grey90
grey40
2

STRIPCHART:

foreground
getValue
highlight
jumpScroll
minScale
update Foreground
Callback
Foreground
JumpScroll
Scale
Interval Pixel
XtCallbackList
Pixel
int
int
int XtDefaultForeground
NULL
XtDefaultForeground
1/2 width
1
10 (seconds)

foreground A pixel value which indexes the widget's colormap to derive the color that will be used to draw the graph.

getValue This is a list of functions to call every update seconds. This function will get the value to be graphed by the StripChart widget. The section Getting the StripChart Value will describe the calling interface in more detail. This callback list should contain only one function. If this callback list contains more than one function, the behavior is undefined.

highlight A pixel value which indexes the widget's colormap to derive the color that will be used to draw the scale lines on the graph.

jumpScroll When the graph reaches the right edge of the window it must be scrolled to the left. This resource specifies the number of pixels it will jump. Smooth scrolling can be achieved by setting this resource to 1.

minScale The minimum scale for the graph. The number of divisions on the graph will always be greater than or equal to this value.

update The number of seconds between graph updates. Each update is represented on the graph as a 1 pixel wide line. Every update seconds the getValue procedure will be used to get a new graph point, and this point will be added to the right end of the StripChart.

Getting The StripChart Value

The StripChart widget will call the application routine passed to it as the getValue callback function every update seconds to obtain another point for the StripChart graph.

The calling interface for the getValue callback is:

void (*getValueProc)(w, client_data, value)
Widget w;
XtPointer client_data;
XtPointer value; /* double * */

w Specifies the StripChart widget.

client_data Specifies the client data.

value Returns a pointer to a double. The application should set the address pointed to by this argument to a double containing the value to be graphed on the StripChart.

This function is used by the StripChart to call an application routine. The routine will pass the value to be graphed back to the the StripChart in the value field of this routine.

XawPlus_________________________________________________________
XawPlusDoc/Text.html The Text Widget
_________________________________________________________XawPlus

The Text Widget

Application Header file
Class Header file
Class
Class Name
Superclass <X11/XawPlus/Text.h>
<X11/XawPlus/TextP.h>
textWidgetClass
Text
Simple

The Text widget is the glue that binds all the other pieces together, it maintains the internal state of the displayed text, and acts as a mediator between the text source and the text sink.

This section lists the resources that are actually part of the Text widget, and explains the functionality provided by each.

Note that the Text widget itself is not very useful. It is meant for subclassing to create other more specific text widgets like AsciiText.

Differences between Xaw and XawPlus

Since the 3D extensions of Simple are inserted, the Text widget has the additional (but at this time not used) resources highlightColor, shadowColor and buttonBorderWidth. The default background color is now grey75. The vertical scrollbar is always placed on the right side of the text window, if it is visible.

Resources

When creating a Text widget instance, the following resources are retrieved from the argument list of XtSetValues() or XtVaSetValues() or from the resource database:

Name Class Type Default Value

OBJECT:

destroyCallback Callback Pointer NULL

RECTANGLE:

borderWidth
height
sensitive
width
x
y BorderWidth
Height
Sensitive
Width
Position
Position Dimension
Dimension
Boolean
Dimension
Position
Position 0
12
True
12
0
0

CORE:

border
background
mappedWhenManaged BorderColor
Background
MappedWhenManaged Pixel
Pixel
Boolean XtDefaultForeground
grey75
True

SIMPLE:

cursor
cursorName
pointerColor
pointerColorBackground
insensitiveBorder
international
highlightColor
shadowColor
buttonBorderWidth Cursor
Cursor
Foreground
Background
Insensitive
International
Background
Background
Width Cursor
String
Pixel
Pixel
Pixmap
Boolean
Pixel
Pixel
Dimension None
NULL
XtDefaultForeground
XtDefaultBackground
NULL
False
grey90
grey40
2

TEXT:

autoFill
bottomMargin
topMargin
leftMargin
rightMargin
displayPosition
insertPosition
resize
scrollHorizontal
scrollVertical
selectTypes
textSink
textSource
unrealizeCallback
wrap
displayCaret AutoFill
Margin
Margin
Margin
Margin
TextPosition
TextPosition
Resize
Scroll
Scroll
SelectTypes
TextSink
TextSource
Callback
Wrap
Output Boolean
Position
Position
Position
Position
XawTextPosition
XawTextPosition
XawTextResizeMode
XawTextScrollMode
XawTextScrollMode
Pointer
Widget
Widget
Callback
XawTextWrapMode
Boolean False
2
2
2
4
0
0
XawTextResizeNever
XawtextScrollNever
XawtextScrollNever
see documentation
NULL
NULL
NULL
XawTextWrapNever
True

autoFill If this resource is True the text widget will automatically break a line when the user attempts to type into the right margin. The attribute has no effect on files or text inserted into the text widget. It only checks to see if the action should be taken when a user enters a new character via the insert-character action.

bottomMargin, topMargin,
leftMargin, rightMargin The amount of space, in pixels, between the edge of the window and the corresponding edge of the text within the window. If there is a scrollbar active on this edge, then this is the space between the text and the scrollbar.

displayPosition The position in the text buffer of the character that is currently displayed in the upper left hand corner of the text display.

insertPosition This is the position of the insert point. It is expressed in characters from the beginning of the file. The cursor will always be forced to be on the screen. This resource may therefore be used to scroll the text display to a certain character position

resize Controls whether or not the text widget attempts to resize itself when it is no lonber able to display the full text buffer in the associated window. Any attempt by the text widget to resize itself is always subject to the constraints imposed by its parent. The Value XawTextResizeNever, XawTextResizeWidth, XawTextResizeHeight and XawTextResizeBoth are all acceptable for this resource. A converter is registered for this resource that will convert the following strings: never, heght, width and both.

scrollHorizontal, scrollVertical These resources control the the placement of scrollbars on the right and bottom edge of the text widget. These resources accept the values XawtextScrollAlways, XawtextScrollWhenNeeded and XawtextScrollNever. A converter is registered for this resource that will convert the strings always, never and whenNeeded into the corresponding values. If XawtextScrollWhenNeeded is specified, the appropriate scrollbar will only appear when there is text in the buffer that is not able to fit within the bounds of the widgets window. The scrollbar will disappear when the text again fits within the window.

selectTypes Specifies the selection type array that is used when multi-click is activated. See Text Selection for Application Programmers for details.

textSink, textSource These are the TextSink and the TextSource objects used by this widgets. When using the Text widget these must be set by the application programmer.

unrealizeCallback A list of callback functions which will be executed when the text widget is unrealized.

wrap When a text in any line is wider than the window there are several possible actions. This resource allows the user to decide what will happen. The accepted values for this resource are XawtextWrapNever, XawtextWrapLine and XawtextWrapWord. With XawtextWrapLine all text that is beyond the right edge of the window will be display on the next line. With XawtextWrapWord the same action occurs but the text is broken at a word boundary if possible. If no wrapping is enabled then the text will extend off the edge of the window and a small rectangle will be painted in the right margin to alert the user that this line is too long. A converter is registered for this resource that will convert the strings never, word and line.

displayCaret Whether ot not to display the text insertion point.

XawPlus_________________________________________________________
XawPlusDoc/TextActions.html Text Widget Actions
_________________________________________________________XawPlus

Text Widget Actions

All editing functions are performed by translation manager actions that may be specified through the translations resource in the Text widget.

Differences between Xaw and XawPlus

None.

Cursor Movement Actions

forward-character()
backward-character() These actions move the insert point forward or backward one character in the buffer. If the insert point is at the end or beginning of a line this action will move the insert point to the next (or previous) line.

backward-character() These actions move the insert point forward or backward one character in the buffer. If the insert point is at the end or beginning of a line this action will move the insert point to the next (or previous) line.

forward-word()
backward-word() These actions move the insert point to the next or previous word boundary. A word boundary is defined as a Space, Tab or Carriage Return.

forward-paragraph()
backward-paragraph() These actions move the insert point to the next or previous paragraph boundary. A paragraph boundary is defined as two Carriage Returns in a row with only Spaces or Tabs between them.

beginning-of-line()
end-of-line() These actions move to the beginning or end of the current line. If the insert point is already at the end or beginning of the line then no action is taken.

next-line()
previous-line() These actions move the insert point up or down one line. If the insert point is currently N characters from the beginning of the line then it will be N characters from the beginning of the next or previous line. If N is past the end of the line, the insert point is placed at the end of the line.

next-page()
previous-page() These actions move the insert point up or down one page in the file. One page is defined as the current height of the text widget. The insert point is always placed at the first character of the top line by this action.

beginning-of-file()
end-of-file() These actions place the insert point at the beginning or end of the current text buffer. The text widget is then scrolled the minimum amount necessary to make the new insert point location visible.

scroll-one-line-up()
scroll-one-line-down() These actions scroll the current text field up or down by one line. They do not move the insert point. Other than the scrollbars this is the only way that the insert point may be moved off of the visible text area. The widget will be scrolled so that the insert point is back on the screen as soon as some other action is executed.

Delete Actions

delete-next-character()
delete-previous-character() These actions remove the character immediately before or after the insert point. If a Carriage Return is removed then the next line is appended to the end of the current line.

delete-next-word()
delete-previous-word() These actions remove all characters between the insert point location and the next word boundary. A word boundary is defined as a Space, Tab or Carriage Return.

delete-selection() This action removes all characters in the current selection. The selection can be set with the selection actions.

Selection Actions

select-word() This action selects the word in which the insert point is currently located. If the insert point is between words then it will select the previous word.

select-all() This action selects the entire text buffer.

select-start() This action sets the insert point to the current pointer location. It will then begin a selection at this location. If many of these selection actions occur quickly in succession then the selection count mechanism will be invoked (see the section titled Text Selections for Application Programmers for details).

select-adjust() This action allows a selection started with the select-start action to be modified, as described above.

select-end (name[,name, ...]) This action ends a text selection that began with the select-start action, and asserts ownership of the selection or selections specified. A name can be a selection (e.g. PRIMARY) or a cut buffer (e.g CUT_BUFFER0). Note that case is important. If no names are specified, PRIMARY is asserted.

extend-start() This action finds the nearest end of the current selection, and moves it to the current pointer location.

extend-adjust() This action allows a selection started with an extend-start action to be modified.

extend-end (name[,name, ...]) This action ends a text selection that began with the extend-start action, and asserts ownership of the selection or selections specified. A name can be a selection (e.g. PRIMARY) or a cut buffer (e.g CUT_BUFFER0). Note that case is important. If no names are given, PRIMARY is asserted.

insert-selection (name[,name ,...]) This action retrieves the value of the first (left-most) named selection that exists or the cut buffer that is not empty and inserts it into the Text widget at the current insert point location. A name can be a selection (e.g. PRIMARY) or a cut buffer (e.g CUT_BUFFER0). Note that case is important.

New Line Actions

newline-and-indent() This action inserts a newline into the text and adds spaces to that line to indent it to match the previous line.

newline-and-backup() This action inserts a newline into the text after the insert point.

newline() This action inserts a newline into the text before the insert point.

Kill Actions

kill-word()
backward-kill-word() These actions act exactly like the delete-next-word and delete-previous-word actions, but they stuff the word that was killed into the kill buffer (CUT_BUFFER_1).

kill-selection() This action deletes the current selection and stuffs the deleted text into the kill buffer (CUT_BUFFER_1).

kill-to-end-of-line() This action deletes the entire line to the right of the insert point position, and stuffs the deleted text into the kill buffer (CUT_BUFFER_1).

kill-paragraph() This action deletes the current paragraph, if between paragraphs it deletes the paragraph above the insert point, and stuffs the deleted text into the kill buffer (CUT_BUFFER_1).

kill-to-end-of-paragraph() This action deletes everything between the current insert point location and the next paragraph boundary, and stuffs the deleted text into the kill buffer (CUT_BUFFER_1).

Miscellaneous Actions

redraw-display() This action recomputes the location of all the text lines on the display, scrolls the text to vertically center the line containing the insert point on the screen, clears the entire screen, and redisplays it.

insert-file([filename]) This action activates the insert file popup. The filename option specifies the default filename to put in the filename buffer of the popup. If no filename is specified the buffer is empty at startup.

insert-char() This action may only be attached to a key event. It calls XLookupString to translate the event into a (rebindable) Latin-1 character (sequence) and inserts that sequence into the text at the insert point position.

insert-string (string[,string ,...]) This action inserts each string into the text at the insert point location. Any string beginning with the characters "0x" and containing only valid hexadecimal digits in the remainder is interpreted as a hexadecimal constant and the corresponding single character is inserted instead.

display-caret (state,when) This action allows the insert point to be turned on and off. The state argument specifies the desired state of the insert point. This value may be any of the string values accepted for Boolean resources (e.g. on, True, off, False, etc.). If no arguments are specified, the default value is True. The when argument specifies, for EnterNotify or LeaveNotify events whether or not the focus field in the event is to be examined. If the second argument is not specified, or specified as something other than always then if the action is bound to an EnterNotify or LeaveNotify event, the action will be taken only if the focus field is True. An augmented binding that might be useful is:
*Text.Translations: #override \\
: display-caret(on) \\n\\
: display-caret(off)

focus-in()
focus-out() These actions do not currently do anything.

search(direction, [string]) This action activates the search popup. The direction must be specified as either forward or backward. The string is optional and is used as an initial value for the Search for: string. For further explanation of the search widget see the section on Text Searches.

multiply(value) The multiply action allows the user to multiply the effects of many of the text actions. Thus the following action sequence multiply(10) delete-next-word() will delete 10 words. It does not matter whether these actions take place in one event or many events. Using the default translations the key sequence Control-u, Control-d will delete 4 characters. Multiply actions can be chained, thus multiply(5) multiply(5) is the same as multiply(25). If the string reset is passed to the multiply action the effects of all previous multiplies are removed and a beep is sent to the display.

form-paragraph() This action removes all the Carriage Returns from the current paragraph and reinserts them so that each line is as long as possible, while still fitting on the current screen. Lines are broken at word boundaries if at all possible. This action currently works only on Text widgets that use ASCII text.

transpose-characters() This action will swap the position of the character to the left of the insert point with the character to the right of the insert point. The insert point will then be advanced one character.

no-op([action]) The no-op action makes no change to the text widget, and is mainly used to override translations. This action takes one optional argument. If this argument is RingBell then a beep is sent to the display.

XawWMProtocols ([wm_protocol_name]) This action is written specifically for the transient shells instantiated by the Text widget, which are the file insertion and the search and replace dialog boxes. This action is attached to those shells by the Text widget, in order to handle ClientMessage events with the WM_PROTOCOLS atom in the detail field. This action supports WM_DELETE_WINDOW on the Text widget popups, and may support other window manager protocols if necessary in the future. The popup will be dismissed if the window manager sends a WM_DELETE_WINDOW request and there are no parameters in the action call, which is the default. The popup will also be dismissed if the parameters include the string "wm_delete_window", and the event is a ClientMessage event requesting dismissal or is not a ClientMessage event. This action is not sensitive to the case of the strings passed as parameters.

Text Selections for Application Programmers

The default behavior of the text selection array is described in the section called Text Selections for Users. To modify the selections a programmer must construct a XawTextSelectType array (called the selection array), containing the selections desired, and pass this as the new value for the selectionTypes resource. The selection array may also be modified using the XawTextSetSelectionArray function. All selection arrays must end with the value XawselectNull. The selectionTypes resource has no converter registered and cannot be modified through the resource manager.

The array contains a list of entries that will be called when the user attempts to select text in rapid succession with the select-start action (usually by clicking a pointer button). The first entry in the selection array will be used when the select-start action is initially called. The next entry will be used when select-start is called again, and so on. If a timeout value (1/10 of a second) is exceeded, the the next select-start action will begin at the top of the selection array. When XawselectNull is reached the array is recycled beginning with the first element.

XawselectAll Selects the contents of the entire buffer.

XawselectChar Selects text characters as the pointer moves over them.

XawselectLine Selects the entire line.

XawselectNull Indicates the end of the selection array.

XawselectParagraph Selects the entire paragraph.

XawselectPosition Selects the current pointer position.

XawselectWord Selects whole words as the pointer moves onto them.

The default selectType array is: {XawselectPosition, XawselectWord, XawselectLine, XawselectParagraph, XawselectAll, XawselectNull}

The selection array is not copied by the text widgets. The application must allocate space for the array and cannot deallocate or change it until the text widget is destroyed or until a new selection array is set.

Default Translation Bindings

The following translations are defaults built into every Text widget. They can be overridden, or replaced by specifying a new value for the Text widget's translations resource.

Ctrl<Key>A:
Ctrl<Key>B:
Ctrl<Key>D:
Ctrl<Key>E:
Ctrl<Key>F:
Ctrl<Key>G:
Ctrl<Key>H:
Ctrl<Key>J:
Ctrl<Key>K:
Ctrl<Key>L:
Ctrl<Key>M:
Ctrl<Key>N:
Ctrl<Key>O:
Ctrl<Key>P:
Ctrl<Key>R:
Ctrl<Key>S:
Ctrl<Key>T:
Ctrl<Key>U:
Ctrl<Key>V:
Ctrl<Key>W:
Ctrl<Key>Y:
Ctrl<Key>Z:
Meta<Key>B:
Meta<Key>F:
Meta<Key>I:
Meta<Key>K:
Meta<Key>Q:
Meta<Key>V:
Meta<Key>Y:
Meta<Key>Z:
:Meta<Key>d:
:Meta<Key>D:
:Meta<Key>h:
:Meta<Key>H:
:Meta<Key>\\<:
:Meta<Key>\\>:
:Meta<Key>]:
:Meta<Key>[:
~Shift Meta<Key>Delete:
\ Shift Meta<Key>Delete:
~Shift Meta<Key>Backspace:
\ Shift Meta<Key>Backspace:
<Key>Right:
<Key>Left:
<Key>Down:
<Key>Up:
<Key>Delete:
<Key>BackSpace:
<Key>Linefeed:
<Key>Return:
<Key>:
<FocusIn>:
<FocusOut>:
<Btn1Down>:
<Btn1Motion>:
<Btn1Up>:
<Btn2Down>:
<Btn3Down>:
<Btn3Motion>:
<Btn3Up>: beginning-of-line()
backward-character()
delete-next-character()
end-of-line()
forward-character()
multiply(Reset)
delete-previous-character()
newline-and-indent()
kill-to-end-of-line()
redraw-display()
newline()
next-line()
newline-and-backup()
previous-line()
search(backward)
search(forward)
transpose-characters()
multiply(4)
next-page()
kill-selection()
insert-selection(CUT_BUFFER1)
scroll-one-line-up()
backward-word()
forward-word()
insert-file()
kill-to-end-of-paragraph()
form-paragraph()
previous-page()
insert-selection(PRIMARY, CUT_BUFFER0)
scroll-one-line-down()
delete-next-word()
kill-word()
delete-previous-word()
backward-kill-word()
beginning-of-file()
end-of-file()
forward-paragraph()
backward-paragraph()
delete-previous-word()
backward-kill-word()
delete-previous-word()
backward-kill-word()
forward-character()
backward-character()
next-line()
previous-line()
delete-previous-character()
delete-previous-character()
newline-and-indent()
newline()
insert-char()
focus-in()
focus-out()
select-start()
extend-adjust()
extend-end(PRIMARY, CUT_BUFFER0)
insert-selection(PRIMARY, CUT_BUFFER0)
extend-start()
extend-adjust()
extend-end(PRIMARY, CUT_BUFFER0)

XawPlus_________________________________________________________

w	Specifies the Form widget.
do_layout	Specifies whether the layout of the Form widget is enabled (True) or disabled (False).

panner	Specifies the Panner widget.
client_data	Specifies the client data.
report	Specifies a pointer to an XawPannerReport structure containing the location and size of the slider and the size of the canvas.

jumpProc	All functions on this callback list are called when the NotifyThumb action is invoked. See the Scrollbar Actions section for details.
length	The height of a vertical scrollbar or the width of a horizontal scrollbar.
minimumThumb	The smallest size in pixels, to which the thumb can shrink.
orientation	The orientation is the direction that the thumb will be allowed to move. This value can be either XtorientVertical or XtorientHorizontal.
scrollProc	All functions on this callback list may be called when the NotifyScroll action is invoked. See the Scrollbar Actions section for details.
shown	This is the size of the thumb, expressed as a percentage (0.0 - 1.0) of the length of the scrollbar.
thickness	The width of a vertical scrollbar or the height of a horizontal scrollbar.
topOfThumb	The location of the top of the thumb, as a percentage (0.0 - 1.0) of the length of the scrollbar. This resource was called top in previous versions of the Athena widget set. The name collided with the a Form widget constraint resource, and had to be changed.

StartScroll(value)	The possible values are Forward, Backward, or Continuous. This must be the first action to begin a new movement.
NotifyScroll(value)	The possible values are Proportional or FullLength. If the argument to StartScroll was Forward or Backward, NotifyScroll executes the scrollProc callbacks and passes either; the position of the pointer, if value is Proportional, or the full length of the scroll bar, if value is FullLength. If the argument to StartScroll was Continuous, NotifyScroll returns without executing any callbacks.
EndScroll()	This must be the last action after a movement is complete.
MoveThumb()	Repositions the Scrollbar's thumb to the current pointer location.
NotifyThumb()	Calls the jumpProc callbacks and passes the relative position of the pointer as a percentage of the scroll bar length.

scrollbar	Specifies the Scrollbar widget.
client_data	Specifies the client data.
position	Specifies a pixel position in integer form.

scrollbar	Specifies the ID of the scroll bar widget.
client_data	Specifies the client data.
percent_ptr	Specifies the floating point position of the thumb (0.0, -1.0).

w	Specifies the Scrollbar widget.
top	Specifies the position of the top of the thumb as a fraction of the length of the Scrollbar.
shown	Specifies the length of the thumb as a fraction of the total length of the Scrollbar.

foreground	A pixel value which indexes the widget's colormap to derive the color that will be used to draw the graph.
getValue	This is a list of functions to call every update seconds. This function will get the value to be graphed by the StripChart widget. The section Getting the StripChart Value will describe the calling interface in more detail. This callback list should contain only one function. If this callback list contains more than one function, the behavior is undefined.
highlight	A pixel value which indexes the widget's colormap to derive the color that will be used to draw the scale lines on the graph.
jumpScroll	When the graph reaches the right edge of the window it must be scrolled to the left. This resource specifies the number of pixels it will jump. Smooth scrolling can be achieved by setting this resource to 1.
minScale	The minimum scale for the graph. The number of divisions on the graph will always be greater than or equal to this value.
update	The number of seconds between graph updates. Each update is represented on the graph as a 1 pixel wide line. Every update seconds the getValue procedure will be used to get a new graph point, and this point will be added to the right end of the StripChart.

w	Specifies the StripChart widget.
client_data	Specifies the client data.
value	Returns a pointer to a double. The application should set the address pointed to by this argument to a double containing the value to be graphed on the StripChart.

autoFill	If this resource is True the text widget will automatically break a line when the user attempts to type into the right margin. The attribute has no effect on files or text inserted into the text widget. It only checks to see if the action should be taken when a user enters a new character via the insert-character action.
bottomMargin, topMargin, leftMargin, rightMargin	The amount of space, in pixels, between the edge of the window and the corresponding edge of the text within the window. If there is a scrollbar active on this edge, then this is the space between the text and the scrollbar.
displayPosition	The position in the text buffer of the character that is currently displayed in the upper left hand corner of the text display.
insertPosition	This is the position of the insert point. It is expressed in characters from the beginning of the file. The cursor will always be forced to be on the screen. This resource may therefore be used to scroll the text display to a certain character position
resize	Controls whether or not the text widget attempts to resize itself when it is no lonber able to display the full text buffer in the associated window. Any attempt by the text widget to resize itself is always subject to the constraints imposed by its parent. The Value XawTextResizeNever, XawTextResizeWidth, XawTextResizeHeight and XawTextResizeBoth are all acceptable for this resource. A converter is registered for this resource that will convert the following strings: never, heght, width and both.
scrollHorizontal, scrollVertical	These resources control the the placement of scrollbars on the right and bottom edge of the text widget. These resources accept the values XawtextScrollAlways, XawtextScrollWhenNeeded and XawtextScrollNever. A converter is registered for this resource that will convert the strings always, never and whenNeeded into the corresponding values. If XawtextScrollWhenNeeded is specified, the appropriate scrollbar will only appear when there is text in the buffer that is not able to fit within the bounds of the widgets window. The scrollbar will disappear when the text again fits within the window.
selectTypes	Specifies the selection type array that is used when multi-click is activated. See Text Selection for Application Programmers for details.
textSink, textSource	These are the TextSink and the TextSource objects used by this widgets. When using the Text widget these must be set by the application programmer.
unrealizeCallback	A list of callback functions which will be executed when the text widget is unrealized.
wrap	When a text in any line is wider than the window there are several possible actions. This resource allows the user to decide what will happen. The accepted values for this resource are XawtextWrapNever, XawtextWrapLine and XawtextWrapWord. With XawtextWrapLine all text that is beyond the right edge of the window will be display on the next line. With XawtextWrapWord the same action occurs but the text is broken at a word boundary if possible. If no wrapping is enabled then the text will extend off the edge of the window and a small rectangle will be painted in the right margin to alert the user that this line is too long. A converter is registered for this resource that will convert the strings never, word and line.
displayCaret	Whether ot not to display the text insertion point.

forward-character() backward-character()	These actions move the insert point forward or backward one character in the buffer. If the insert point is at the end or beginning of a line this action will move the insert point to the next (or previous) line.
backward-character()	These actions move the insert point forward or backward one character in the buffer. If the insert point is at the end or beginning of a line this action will move the insert point to the next (or previous) line.
forward-word() backward-word()	These actions move the insert point to the next or previous word boundary. A word boundary is defined as a Space, Tab or Carriage Return.
forward-paragraph() backward-paragraph()	These actions move the insert point to the next or previous paragraph boundary. A paragraph boundary is defined as two Carriage Returns in a row with only Spaces or Tabs between them.
beginning-of-line() end-of-line()	These actions move to the beginning or end of the current line. If the insert point is already at the end or beginning of the line then no action is taken.
next-line() previous-line()	These actions move the insert point up or down one line. If the insert point is currently N characters from the beginning of the line then it will be N characters from the beginning of the next or previous line. If N is past the end of the line, the insert point is placed at the end of the line.
next-page() previous-page()	These actions move the insert point up or down one page in the file. One page is defined as the current height of the text widget. The insert point is always placed at the first character of the top line by this action.
beginning-of-file() end-of-file()	These actions place the insert point at the beginning or end of the current text buffer. The text widget is then scrolled the minimum amount necessary to make the new insert point location visible.
scroll-one-line-up() scroll-one-line-down()	These actions scroll the current text field up or down by one line. They do not move the insert point. Other than the scrollbars this is the only way that the insert point may be moved off of the visible text area. The widget will be scrolled so that the insert point is back on the screen as soon as some other action is executed.

delete-next-character() delete-previous-character()	These actions remove the character immediately before or after the insert point. If a Carriage Return is removed then the next line is appended to the end of the current line.
delete-next-word() delete-previous-word()	These actions remove all characters between the insert point location and the next word boundary. A word boundary is defined as a Space, Tab or Carriage Return.
delete-selection()	This action removes all characters in the current selection. The selection can be set with the selection actions.

select-word()	This action selects the word in which the insert point is currently located. If the insert point is between words then it will select the previous word.
select-all()	This action selects the entire text buffer.
select-start()	This action sets the insert point to the current pointer location. It will then begin a selection at this location. If many of these selection actions occur quickly in succession then the selection count mechanism will be invoked (see the section titled Text Selections for Application Programmers for details).
select-adjust()	This action allows a selection started with the select-start action to be modified, as described above.
select-end (name[,name, ...])	This action ends a text selection that began with the select-start action, and asserts ownership of the selection or selections specified. A name can be a selection (e.g. PRIMARY) or a cut buffer (e.g CUT_BUFFER0). Note that case is important. If no names are specified, PRIMARY is asserted.
extend-start()	This action finds the nearest end of the current selection, and moves it to the current pointer location.
extend-adjust()	This action allows a selection started with an extend-start action to be modified.
extend-end (name[,name, ...])	This action ends a text selection that began with the extend-start action, and asserts ownership of the selection or selections specified. A name can be a selection (e.g. PRIMARY) or a cut buffer (e.g CUT_BUFFER0). Note that case is important. If no names are given, PRIMARY is asserted.
insert-selection (name[,name ,...])	This action retrieves the value of the first (left-most) named selection that exists or the cut buffer that is not empty and inserts it into the Text widget at the current insert point location. A name can be a selection (e.g. PRIMARY) or a cut buffer (e.g CUT_BUFFER0). Note that case is important.

newline-and-indent()	This action inserts a newline into the text and adds spaces to that line to indent it to match the previous line.
newline-and-backup()	This action inserts a newline into the text after the insert point.
newline()	This action inserts a newline into the text before the insert point.

kill-word() backward-kill-word()	These actions act exactly like the delete-next-word and delete-previous-word actions, but they stuff the word that was killed into the kill buffer (CUT_BUFFER_1).
kill-selection()	This action deletes the current selection and stuffs the deleted text into the kill buffer (CUT_BUFFER_1).
kill-to-end-of-line()	This action deletes the entire line to the right of the insert point position, and stuffs the deleted text into the kill buffer (CUT_BUFFER_1).
kill-paragraph()	This action deletes the current paragraph, if between paragraphs it deletes the paragraph above the insert point, and stuffs the deleted text into the kill buffer (CUT_BUFFER_1).
kill-to-end-of-paragraph()	This action deletes everything between the current insert point location and the next paragraph boundary, and stuffs the deleted text into the kill buffer (CUT_BUFFER_1).

redraw-display()	This action recomputes the location of all the text lines on the display, scrolls the text to vertically center the line containing the insert point on the screen, clears the entire screen, and redisplays it.
insert-file([filename])	This action activates the insert file popup. The filename option specifies the default filename to put in the filename buffer of the popup. If no filename is specified the buffer is empty at startup.
insert-char()	This action may only be attached to a key event. It calls XLookupString to translate the event into a (rebindable) Latin-1 character (sequence) and inserts that sequence into the text at the insert point position.
insert-string (string[,string ,...])	This action inserts each string into the text at the insert point location. Any string beginning with the characters "0x" and containing only valid hexadecimal digits in the remainder is interpreted as a hexadecimal constant and the corresponding single character is inserted instead.
display-caret (state,when)	This action allows the insert point to be turned on and off. The state argument specifies the desired state of the insert point. This value may be any of the string values accepted for Boolean resources (e.g. on, True, off, False, etc.). If no arguments are specified, the default value is True. The when argument specifies, for EnterNotify or LeaveNotify events whether or not the focus field in the event is to be examined. If the second argument is not specified, or specified as something other than always then if the action is bound to an EnterNotify or LeaveNotify event, the action will be taken only if the focus field is True. An augmented binding that might be useful is: *Text.Translations: #override \\ : display-caret(on) \\n\\ : display-caret(off)
focus-in() focus-out()	These actions do not currently do anything.
search(direction, [string])	This action activates the search popup. The direction must be specified as either forward or backward. The string is optional and is used as an initial value for the Search for: string. For further explanation of the search widget see the section on Text Searches.
multiply(value)	The multiply action allows the user to multiply the effects of many of the text actions. Thus the following action sequence multiply(10) delete-next-word() will delete 10 words. It does not matter whether these actions take place in one event or many events. Using the default translations the key sequence Control-u, Control-d will delete 4 characters. Multiply actions can be chained, thus multiply(5) multiply(5) is the same as multiply(25). If the string reset is passed to the multiply action the effects of all previous multiplies are removed and a beep is sent to the display.
form-paragraph()	This action removes all the Carriage Returns from the current paragraph and reinserts them so that each line is as long as possible, while still fitting on the current screen. Lines are broken at word boundaries if at all possible. This action currently works only on Text widgets that use ASCII text.
transpose-characters()	This action will swap the position of the character to the left of the insert point with the character to the right of the insert point. The insert point will then be advanced one character.
no-op([action])	The no-op action makes no change to the text widget, and is mainly used to override translations. This action takes one optional argument. If this argument is RingBell then a beep is sent to the display.
XawWMProtocols ([wm_protocol_name])	This action is written specifically for the transient shells instantiated by the Text widget, which are the file insertion and the search and replace dialog boxes. This action is attached to those shells by the Text widget, in order to handle ClientMessage events with the WM_PROTOCOLS atom in the detail field. This action supports WM_DELETE_WINDOW on the Text widget popups, and may support other window manager protocols if necessary in the future. The popup will be dismissed if the window manager sends a WM_DELETE_WINDOW request and there are no parameters in the action call, which is the default. The popup will also be dismissed if the parameters include the string "wm_delete_window", and the event is a ClientMessage event requesting dismissal or is not a ClientMessage event. This action is not sensitive to the case of the strings passed as parameters.

XawselectAll	Selects the contents of the entire buffer.
XawselectChar	Selects text characters as the pointer moves over them.
XawselectLine	Selects the entire line.
XawselectNull	Indicates the end of the selection array.
XawselectParagraph	Selects the entire paragraph.
XawselectPosition	Selects the current pointer position.
XawselectWord	Selects whole words as the pointer moves onto them.