Athena Widget Set — C Language Interface X Window System X Version 11, Release 7 libXaw 1.0.7 Chris D.
X Window System is a trademark of The Open Group.
Acknowledgments Many thanks go to Ralph Swick (Project Athena / Digital) who has contributed much time and effort to this widget set. Previous versions of the widget set are largely due to his time and effort. Many of the improvements that I have been able to make are because he provided a solid foundation to build upon. While much of the effort has been Ralph’s, many other people have contributed to the code.
The R6 edition of this document has been edited to reflect changes brought about by research staff of the Omron Corporation, with special recognition to Li Yuhong, Seiji Kuwari, and Hiroshi Kuribayashi for the X11R5/contrib/lib/Xaw internationalization that inspired this version.
Chapter 1 Athena Widgets and The Intrinsics The X Toolkit is made up of two distinct pieces, the Xt Intrinsics and a widget set. The Athena widget set is a sample implementation of a widget set built upon the Intrinsics. In the X Toolkit, a widget is the combination of an X window or subwindow and its associated input and output semantics.
Athena Widget Set • • • libXaw 1.0.7 Model Conventions used in this manual Format of the Widget Reference Chapters 1.2. Terminology In addition to the terms already defined for X programming (see Xlib — C Language X Interface), the following terms are specific to the Intrinsics and Athena widget set and used throughout this document. Application programmer A programmer who uses the X Toolkit to produce an application user interface. Child A widget that is contained within another "parent" widget.
Athena Widget Set libXaw 1.0.7 Widget An object providing a user-interface abstraction (for example, a Scrollbar widget). Widget class The general group to which a specific widget belongs, otherwise known as the type of the widget. Widget programmer A programmer who adds new widgets to the X Toolkit. 1.3. Underlying Model The underlying architectural model is based on the following premises: Widgets are X windows Every user-interface widget is associated with an X window.
Athena Widget Set libXaw 1.0.7 1.5. Format of the Widget Reference Chapters The majority of this document is a reference guide for the Athena widget set. Chapters three through six give the programmer all information necessary to use the widgets. The layout of the chapters follows a specific pattern to allow the programmer to easily find the desired information. The first few pages of every chapter give an overview of the widgets in that section. Widgets are grouped into chapters by functionality.
Athena Widget Set libXaw 1.0.7 D Do not modify this resource. While setting this resource will work, it can cause unexpected behavior. When this symbol appears there is another, preferred, interface provided by the X Toolkit. R This resource is READ-ONLY, and may not be modified. After the resource table is a detailed description of every resource available to that widget. Many of these are redundant, but printing them with each widget saves page flipping.
Athena Widget Set libXaw 1.0.7 Chapter 2 Using Widgets Widgets serve as the primary tools for building a user interface or application environment. The Athena widget set consists of primitive widgets that contain no children (for example, a command button) and composite widgets which may contain one or more widget children (for example, a Box widget). The remaining chapters explain the widgets that are provided by the Athena widget set.
Athena Widget Set libXaw 1.0.7 app_con_return application_class Returns the application context of this application, if non-NULL. Specifies the class name of this application, which is usually the generic name for all instances of this application. A useful convention is to form the class name by capitalizing the first letter of the application name. For example, the application named ‘‘xman’’ has a class name of ‘‘Xman’’.
Athena Widget Set libXaw 1.0.7 For further information, see X Toolkit Intrinsics — C Language Interface. 2.4. Common Resources Although a widget can have unique arguments that it understands, all widgets have common arguments that provide some regularity of operation. The common arguments allow arbitrary widgets to be managed by higher-level components without regard for the individual widget type. Widgets will ignore any argument that they do not understand.
Athena Widget Set libXaw 1.0.7 2.5.1. Cursor Conversion The value for the cursorName resource is specified in the resource database as a string, and is of the following forms: • A standard X cursor name from < X11/cursorfont.h >. The names in cursorfont.h each describe a specific cursor. The resource names for these cursors are exactly like the names in this file except the XC_ is not used. The cursor definition XC_gumby has a resource name of gumby.
Athena Widget Set libXaw 1.0.7 2.7. Processing Events Now that the application has created, managed and realized its widgets, it is ready to process the events that will be delivered by the X Server to this client. A function call that will process the events is XtAppMainLoop. void XtAppMainLoop(app_context) XtAppContext app_context; app_context Specifies the application context of this application. The value is normally returned by XtAppInitialize.
Athena Widget Set libXaw 1.0.7 void XtManageChildren(children, num_children) WidgetList children; Cardinal num_children; children Specifies a list of children to add. num_children Specifies the number of children to add. If the parent is already visible on the screen, it is especially important to batch updates so that the minimum amount of visible window reconfiguration is performed. For further information about these functions, see the X Toolkit Intrinsics — C Language Interface. 2.8.2.
Athena Widget Set libXaw 1.0.7 The arguments and values that are passed will depend on the widget being modified. Some widgets may not allow certain resources to be modified after the widget instance has been created or realized. No notification is given if any part of a XtSetValues request is ignored. For further information about these functions, see the X Toolkit Intrinsics — C Language Interface.
Athena Widget Set libXaw 1.0.7 void XtAddCallback(w, callback_name, callback, client_data) Widget w; String callback_name; XtCallbackProc callback; XtPointer client_data; w Specifies the widget to add the callback to. callback_name Specifies the callback list within the widget to append to. callback Specifies the callback procedure to add. client_data Specifies the data to be passed to the callback when it is invoked. XtAddCallback adds the specified callback to the list for the named widget.
Athena Widget Set 9. libXaw 1.0.7 For information about this function, see the X Toolkit Intrinsics — C Language Interface. Link your application with libXaw (the Athena widgets), libXmu (miscellaneous utilities), libXt (the X Toolkit Intrinsics), libSM (Session Management), libICE (Inter-Client Exchange), libXext (the extension library needed for the shape extension code which allows rounded Command buttons), and libX11 (the core X library).
Athena Widget Set libXaw 1.0.7 of applications named xman. (Note that while typically two widgets that are siblings will have different names, it is not prohibited.) Xman.Form.Command This will match any Command widget that is a child of a Form widget that is itself a child of an application of class Xman. Xman.Form.button1 This is a mixed resource name with both widget names and classes specified. This syntax allows an application programmer to specify any widget in the widget tree.
Athena Widget Set libXaw 1.0.7 2.10.2.2. Creating Argument Lists To set up an argument list for the inline specification of widget attributes, you may use any of the four approaches discussed in this section. Each resource name has a global symbol associated with it. This global symbol has the form XtNresource name. For example, the symbol for ‘‘foreground’’ is XtNforeground. For further information, see the X Toolkit Intrinsics — C Language Interface.
Athena Widget Set libXaw 1.0.7 Note that in this example, as in the previous example, XtNumber would return 10, not 2, and therefore would not be useful. The fourth approach is to use a mixture of the first and third approaches: you can statically define the argument list but modify some entries at runtime. For example: static Arg arglist[] = { {XtNwidth, (XtArgVal) 400}, {XtNheight, (XtArgVal) NULL}, }; arglist[1].
Athena Widget Set libXaw 1.0.7 Chapter 3 Simple Widgets Each of these widgets performs a specific user interface function. They are simple because they cannot have widget children—they may only be used as leaves of the widget tree. These widgets display information or take user input. Command Grip Label List Panner Repeater Scrollbar Simple StripChart Toggle A push button that, when selected, may cause a specific action to take place.
Athena Widget Set libXaw 1.0.7 3.1.1.
Athena Widget Set libXaw 1.0.7 be used instead of the background color. A bitmap to display instead of the label. The default size of the widget will be just large enough to contain the bitmap and the widget’s internal width and height. The resource converter for this resource constructs bitmaps from the contents of files. (See Converting Bitmaps for details.) If this bitmap is one bit deep then the 1’s will be rendered in the foreground color, and the 0’s in the background color.
Athena Widget Set international justify libXaw 1.0.7 This is a boolean flag, only settable at widget creation time. A value of false signals the widget to use pre-R6 internationalization (specifically, the lack thereof), such as using fonts for displaying text, etc. A value of true directs the widget to act in an internationalized manner, such as utilizing font sets for displaying text, etc. Specifies left, center, or right alignment of graphic within the widget.
Athena Widget Set libXaw 1.0.7 3.1.2. Command Actions The Command widget supports the following actions: • Switching the button’s interior between the foreground and background colors with set, unset, and reset.
Athena Widget Set libXaw 1.0.7 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. 3.2.1.
Athena Widget Set borderWidth callback colormap cursor cursorName depth destroyCallback foreground libXaw 1.0.7 The width of this widget’s window border. 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 detailed description is given below in the Grip Actions section. The colormap that this widget will use. The image that will be displayed as the pointer cursor whenever it is in this widget.
Athena Widget Set libXaw 1.0.7 XEvent *event; String *params; Cardinal num_params; } XawGripCallDataRec, *XawGripCallData, GripCallDataRec, *GripCallData; /* supported for R4 compatibility */ 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.
Athena Widget Set libXaw 1.0.
Athena Widget Set cursorName depth destroyCallback encoding font fontSet foreground height width insensitiveBorder internalHeight internalWidth international justify libXaw 1.0.7 The name of the symbol to use to represent the pointer cursor. This resource will override the cursor resource if both are specified. (See 2.4.1) The depth of this widget’s window. All functions on this list are called when this widget is destroyed. The encoding method used by the value of the label resource.
Athena Widget Set resize screen sensitive translations x y libXaw 1.0.7 Specifies whether the widget should attempt to resize to its preferred dimensions whenever its resources are modified with XtSetValues. This attempt to resize may be denied by the parent of this widget. The parent is always free to resize the widget regardless of the state of this resource. The screen on which this widget is displayed. This is not a settable resource. Whether or not the toolkit should pass user events to this widget.
Athena Widget Set libXaw 1.0.
Athena Widget Set defaultColumns depth destroyCallback font fontSet forceColumns foreground height width insensitiveBorder libXaw 1.0.7 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. The depth of this widget’s window. All functions on this list are called when this widget is destroyed. The text font to use when displaying the list, when the international resource is false.
Athena Widget Set screen sensitive translations verticalList x y libXaw 1.0.7 The screen on which this widget is displayed. This is not a settable resource. Whether or not the toolkit should pass user events to this widget. The widget will not get input events if either ancestorSensitive or sensitive is False. The event bindings associated with this widget. If this resource is set to True then the list elements will be presented in column major order.
Athena Widget Set libXaw 1.0.7 void XawListChange(w, list, nitems, longest, resize) Widget w; String * list; int nitems, longest; Boolean resize; w list nitems Specifies the List widget. Specifies the new list for the List widget to display. 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.
Athena Widget Set libXaw 1.0.7 3.4.8. Restrictions Many programmers create a ‘‘scrolled list’’ by putting a List widget with many entries as a child of a Viewport widget. The List continues to create a window as big as its contents, but that big window is only visible where it intersects the parent Viewport’s window. (I.e., it is ‘‘clipped.’’) While this is a useful technique, there is a serious drawback.
Athena Widget Set libXaw 1.0.
Athena Widget Set defaultScale depth destroyCallback foreground libXaw 1.0.7 The percentage size that the Panner widget should have relative to the size of the canvas. The depth of this widget’s window. All functions on this list are called when this widget is destroyed. A pixel value which indexes the widget’s colormap to derive the color used to draw the slider. height width internalSpace The height and width of this widget in pixels.
Athena Widget Set libXaw 1.0.7 3.5.2. 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 outline of the slider (if the rubberBand resource is True) or the slider itself (by invoking the notify action procedure).
Athena Widget Set libXaw 1.0.7 3.6. Repeater Widget Application header file Class header file Class Class Name Superclass repeaterWidgetClass Repeater Command The Repeater widget is a subclass of the Command widget; see the Command documentation for details. The difference is that the Repeater can call its registered callbacks repeatedly, at an increasing rate.
Athena Widget Set libXaw 1.0.7 Name Class Type resize screen sensitive shapeStyle startCallback stopCallback translations width x y Resize Screen Sensitive ShapeStyle StartCallback StopCallback Translations Width Position Position Boolean Pointer Boolean ShapeStyle Callback Callback TranslationTable Dimension Position Position accelerators A list of event to action bindings to be executed by this widget, even though the event occurred in another widget.
Athena Widget Set depth destroyCallback encoding flash font fontSet foreground height width highlightThickness initialDelay insensitiveBorder internalHeight internalWidth international justify libXaw 1.0.7 interval has reached minimumDelay milliseconds. The depth of this widget’s window. All functions on this list are called when this widget is destroyed. The encoding method used by the value of the label resource. The value may be XawTextEncoding8bit or XawTextEncodingChar2b.
Athena Widget Set libXaw 1.0.7 minimumDelay pointerColor The minimum time between callbacks in milliseconds. A pixel value which indexes the widget’s colormap to derive the foreground color of the pointer symbol specified by the cursorName resource. pointerColorBackground A pixel value which indexes the widget’s colormap to derive the background color of the pointer symbol specified by the cursorName resource.
Athena Widget Set libXaw 1.0.7 : stop( ) unset( ) 3.7. Scrollbar Widget Application header file Class header file Class Class Name Superclass scrollbarWidgetClass Scrollbar Simple A Scrollbar widget is a rectangle, called the ‘‘canvas,’’ on which another rectangle, the ‘‘thumb,’’ moves in one dimension, either vertically or horizontally.
Athena Widget Set libXaw 1.0.
Athena Widget Set depth destroyCallback foreground libXaw 1.0.7 2.4.1) The depth of this widget’s window. All functions on this list are called when this widget is destroyed. A pixel value which indexes the widget’s colormap to derive the color used to draw the thumb. height width insensitiveBorder The height and width of this widget in pixels. This pixmap will be tiled into the widget’s border if the widget becomes insensitive.
Athena Widget Set thumb topOfThumb translations x y libXaw 1.0.7 This pixmap is used to tile (or stipple) the thumb of the scrollbar. If no tiling is desired, then set this resource to None. This resource will accept either a bitmap or a pixmap that is the same depth as the window. The resource converter for this resource constructs bitmaps from the contents of files. (See Converting Bitmaps for details.) The location of the top of the thumb, as a percentage (0.0 - 1.0) of the length of the scrollbar.
Athena Widget Set libXaw 1.0.7 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.
Athena Widget Set libXaw 1.0.7 3.7.5. 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.
Athena Widget Set libXaw 1.0.
Athena Widget Set libXaw 1.0.7 mappedWhenManaged If this resource is True, then the widget’s window will automatically be mapped by the Toolkit when it is realized and managed. pointerColor A pixel value which indexes the widget’s colormap to derive the foreground color of the pointer symbol specified by the cursorName resource. pointerColorBackground A pixel value which indexes the widget’s colormap to derive the background color of the pointer symbol specified by the cursorName resource.
Athena Widget Set libXaw 1.0.
Athena Widget Set libXaw 1.0.7 width highlight The height and width of this widget in pixels. 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. insensitiveBorder This pixmap will be tiled into the widget’s border if the widget becomes insensitive. international This is a boolean flag, only settable at widget creation time.
Athena Widget Set libXaw 1.0.7 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. 3.10. Toggle Widget Application Header file Class Header file Class Class Name Superclass toggleWidgetClass Toggle Command The Toggle widget is an area, often rectangular, that displays a graphic.
Athena Widget Set libXaw 1.0.
Athena Widget Set libXaw 1.0.7 callback colormap cornerRoundPercent A list of routines to be called when the notify action is invoked. The colormap that this widget will use. When a ShapeStyle of roundedRectangle is used, this resource controls the radius of the rounded corner. The radius of the rounded corners is specified as a percentage of the length of the shortest side of the widget. The image that will be displayed as the pointer cursor whenever it is in this widget.
Athena Widget Set libXaw 1.0.7 label Specifies the text string to be displayed in the widget’s window if no bitmap is specified. The default is the name of this widget. Regardless of the value of encoding or international, a single newline character (1 byte) will cause a line break. leftBitmap Specifies a bitmap to display to the left of the graphic in the widget’s window.
Athena Widget Set y libXaw 1.0.7 The location of the upper left outside corner of this widget in its parent. 3.10.2.
Athena Widget Set libXaw 1.0.7 3.10.4. 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 Toggle widget active, but there need not be any Toggle widgets 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.
Athena Widget Set libXaw 1.0.7 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.
Athena Widget Set libXaw 1.0.7 Chapter 4 Menus The Athena widget set provides support for single paned non-hierarchical popup and pulldown menus. Since menus are such a common user interface tool, support for them must be provided in even the most basic widget sets. In menuing as in other areas, the Athena Widget Set provides only basic functionality. Menus in the Athena widget set are implemented as a menu container (the SimpleMenu widget) and a collection of objects that comprise the menu entries.
Athena Widget Set libXaw 1.0.7 Class Class Name Superclass simpleMenuWidgetClass SimpleMenu OverrideShell The SimpleMenu widget is a container for the menu entries. It is a direct subclass of shell, and is should be created with XtCreatePopupShell, not XtCreateManagedWidget. This is the only part of the menu that actually is associated with a window. The SimpleMenu serves as the glue to bind the individual menu entries together into a menu. 4.2.1.
Athena Widget Set ancestorSensitive backingStore background backgroundPixmap borderColor borderPixmap borderWidth bottomMargin topMargin children colormap cursor depth destroyCallback geometry libXaw 1.0.7 The sensitivity state of the ancestors of this widget. A widget is insensitive if either it or any of its ancestors is insensitive. This resource should not be changed with XtSetValues, although it may be queried. Determines what type of backing store will be used for the menu.
Athena Widget Set libXaw 1.0.7 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 popupOnEntry rowHeight saveUnder screen sensitive translations x y These callback functions are called by the Xt Intrinsics whenever the shell is popped up or down (See X Toolkit Intrinsics — C Language Interface for details).
Athena Widget Set libXaw 1.0.7 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 X Toolkit Intrinsics — C Language Interface. 4.2.3. 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.
Athena Widget Set libXaw 1.0.7 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.
Athena Widget Set libXaw 1.0.7 Name Class Type Notes Default Value width Width Dimension A TextWidth + margins ancestorSensitive callback destroyCallback font fontSet foreground height width international justify label leftBitmap rightBitmap leftMargin rightMargin sensitive vertSpace The sensitivity state of the ancestors of this widget. A widget is insensitive if either it or any of its ancestors is insensitive.
Athena Widget Set libXaw 1.0.7 The default value for this resource (25) causes the default height to be 125% of the height of the font. 4.4. SmeLine Object Application Header file Class Header file Class Class Name Superclass smeLineObjectClass SmeLine Sme The SmeLine object is used to add a horizontal line or menu separator to a menu.
Athena Widget Set Class Name Superclass libXaw 1.0.7 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. 4.5.1. 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.
Athena Widget Set libXaw 1.0.7 3) XtSetValues calls may come from the application while the Sme is highlighted, and if the SetValues method returns True, will result in an expose event. The SimpleMenu may later call the menu entry’s unhighlight procedure. However, due to the asynchronous nature of X, the expose event generated by XtSetValues will come after this unhighlight. 4) Remember that your subclass of the Sme does not own the window.
Athena Widget Set libXaw 1.0.
Athena Widget Set cursorName depth destroyCallback font fontSet foreground height width highlightThickness insensitiveBorder internalHeight internalWidth international justify libXaw 1.0.7 The name of the symbol to use to represent the pointer cursor. This resource will override the cursor resource if both are specified. (See 2.4.1) The depth of this widget’s window. All functions on this list are called when this widget is destroyed.
Athena Widget Set libXaw 1.0.7 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. pointerColor A pixel value which indexes the widget’s colormap to derive the foreground color of the pointer symbol specified by the cursorName resource.
Athena Widget Set libXaw 1.0.7 procedure. If no argument is passed, WhenUnset is assumed. Displays the internal highlight border in the color (XtNforeground or background ) that matches the interior color of the MenuButton widget. set( ) Enters the set state, in which notify is possible. This action causes the button to display its interior in the foreground color. The label or bitmap is displayed in the background color.
Athena Widget Set libXaw 1.0.7 Chapter 5 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 modularized to ease customization.
Athena Widget Set Ctrl-o Ctrl-p Ctrl-r Ctrl-s Ctrl-t Ctrl-u Ctrl-v Ctrl-w Ctrl-y Ctrl-z Ctrl-\ Kanji libXaw 1.0.
Athena Widget Set libXaw 1.0.7 Using these special key sequences should allow simple searches without ever removing one’s hands from the keyboard. Near the bottom of the search popup is a row of buttons. These buttons allow the same actions to to be performed as the key sequences, but the buttons will leave the popup active. This can be quite useful if many searches are being performed, as the popup will be left on the display.
Athena Widget Set libXaw 1.0.7 Label label Text text Command insert Command cancel 5.1.4. Text Selections for Users The text widgets have a text selection mechanism that allows the user to copy pieces of the text into the PRIMARY selection, and paste into the text widget some text that another application (or text widget) has put in the PRIMARY selection.
Athena Widget Set libXaw 1.0.
Athena Widget Set next-page( ) previous-page( ) beginning-of-file( ) end-of-file( ) scroll-one-line-up( ) scroll-one-line-down( ) libXaw 1.0.7 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. These actions place the insert point at the beginning or end of the current text buffer.
Athena Widget Set libXaw 1.0.7 event) or text cursor location (if triggered by a key event). 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.
Athena Widget Set insert-char( ) insert-string(string[,string,...]) display-caret(state,when) libXaw 1.0.7 This action may only be attached to a key event. When the international resource is false, this action calls XLookupString to translate the event into a (rebindable) Latin-1 character (sequence) and inserts it into the text at the insert point.
Athena Widget Set libXaw 1.0.7 only on Text widgets that use ASCII text. 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.
Athena Widget Set libXaw 1.0.7 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.
Athena Widget Set :MetaH: :Meta\<: :Meta\>: :Meta]: :Meta[: ˜Shift MetaDelete: Shift MetaDelete: ˜Shift MetaBackspace: Shift MetaBackspace: Right: Left: Down: Up: Delete: BackSpace: Linefeed: Return: : Kanji: : : : : : : : : : libXaw 1.0.
Athena Widget Set libXaw 1.0.7 ptr format Contains the string to be referenced by the Text widget. This flag indicates whether the data pointed to by ptr is char or wchar_t. When the associated widget has international set to false this field must be XawFmt8Bit. When the associated widget has international set to true this field must be either XawFmt8Bit or XawFmtWide. Note: Previous versions of Xaw used FMT8BIT, which has been retained for backwards compatibility.
Athena Widget Set libXaw 1.0.7 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. See section 5.4 for a description of XawTextPosition and XawTextBlock. This function may return the following values: XawEditDone The text replacement was successful.
Athena Widget Set libXaw 1.0.7 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.
Athena Widget Set libXaw 1.0.7 To obtain the current position of the insertion point, use XawTextGetInsertionPoint: XawTextPosition XawTextGetInsertionPoint(w) Widget w; w Specifies the Text widget. See section 5.4 for a description of XawTextPosition. The result is equivalent to retrieving the value of the insertPosition resource.
Athena Widget Set libXaw 1.0.7 management), and a ‘‘Sink’’ (which handles the display). There are currently two supported sources, the AsciiSrc and MultiSrc, and two supported sinks, the AsciiSink and MultiSink. Some of the resources listed below are not actually resources of the AsciiText, but belong to the associated source or sink. This is is noted in the explanation of each resource where it applies.
Athena Widget Set libXaw 1.0.7 Name Class Type textSink textSource topMargin translations type useStringInPlace width wrap x y TextSink TextSource Margin Translations Type UseStringInPlace Width Wrap Position Position Widget Widget Position TranslationTable XawAsciiType Boolean Dimension WrapMode Position Position accelerators A list of event to action bindings to be executed by this widget, even though the event occurred in another widget.
Athena Widget Set dataCompression depth destroyCallback displayCaret displayNonprinting displayPosition editType echo font font foreground libXaw 1.0.7 The AsciiSrc uses an algorithm that may cause the text buffer to grow to about twice the size of the actual text over time, as the text is edited. On systems where CPU cycles are cheaper than memory, it is helpful to spend some extra time to compress this buffer back to its minimum size.
Athena Widget Set libXaw 1.0.7 pointerColorBackground pieceSize resize screen scrollHorizontal scrollVertical selectTypes sensitive string textSink textSource A pixel value which indexes the widget’s colormap to derive the background color of the pointer symbol specified by the cursorName resource. This is the size of the internal chunks into which the text buffer is broken down for memory management.
Athena Widget Set translations type useStringInPlace wrap x y libXaw 1.0.7 resources to point to an MultiSink and MultiSrc respectively. When international is set to false the AsciiText widget initializes these resources to point to an AsciiSink and AsciiSrc respectively. The event bindings associated with this widget. This resource may be either XawAsciiString or XawAsciiFile.
Athena Widget Set libXaw 1.0.7 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.
Athena Widget Set editType length pieceSize string type useStringInPlace libXaw 1.0.7 If this resource is True, the AsciiSrc will compress its data to the minimum size required every time the text string is saved, or the value of the string is queried. This is the type of editing that will be allowed in this text widget. Legal values are XawtextRead, XawtextEdit, and XawtextAppend. A converter is registered for this resource that will convert the following strings: read, edit, and append.
Athena Widget Set libXaw 1.0.7 memory by freeing this string as soon as you are done with it by calling XawAsciiSourceFreeString. 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. 5.6.2.2.
Athena Widget Set libXaw 1.0.7 with MultiSink differences noted only as they occur. The AsciiSink will display all printing characters in an 8 bit font, along with handling Tab and Carriage Return. The name has been left as ‘‘AsciiSink’’ for compatibility. The MultiSink will display all printing characters in a font set, along with handling Tab and Carriage Return. The source object also reports the text window metrics to the text widgets. 5.7.1.
Athena Widget Set TextSink TextSrc AsciiSink MultiSink AsciiSrc MultiSrc AsciiText libXaw 1.0.7 This object is responsible for displaying and clearing the drawing area. It also reports the configuration of the window that contains the drawing area. The TextSink does not have its own window; instead it does its drawing on the Text widget’s window. This object is responsible for reading, editing and searching through the text buffer.
Athena Widget Set libXaw 1.0.
Athena Widget Set topMargin colormap cursor cursorName depth destroyCallback displayCaret displayPosition libXaw 1.0.7 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. The colormap that this widget will use. The image that will be displayed as the pointer cursor whenever it is in this widget.
Athena Widget Set libXaw 1.0.7 the current window. The scrollbar will disappear when the text once again fits within the window. Specifies the selection type array that is used when multi-click is activated (see Text Selections for Application Programmers for details). This resource is used in place, and must not be freed until the widget is destroyed. There is no type converter registered for this resource, so it may not be set from the resource manager.
Athena Widget Set libXaw 1.0.7 Name Class Type editType EditType EditMode destroyCallback editType Notes Default Value NULL All functions on this list are called when this widget is destroyed. This is the type of editing that will be allowed in this text widget. Legal values are XawtextRead, XawtextEdit, and XawtextAppend. A converter is registered for this resource that will convert the following strings: read, edit, and append. 5.10.2.
Athena Widget Set libXaw 1.0.7 w start Specifies the TextSrc object. 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.
Athena Widget Set libXaw 1.0.7 position dir Specifies the position to begin the search. 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.
Athena Widget Set libXaw 1.0.7 5.11. TextSink Object Application Header file Class Header file Class Class Name Superclass 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.
Athena Widget Set libXaw 1.0.7 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.
Athena Widget Set libXaw 1.0.7 5.11.2.4. 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 fromPos Specifies the TextSink object.
Athena Widget Set libXaw 1.0.7 5.11.2.5. 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 fromPos fromX Specifies the TextSink object.
Athena Widget Set libXaw 1.0.7 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. 5.11.2.8.
Athena Widget Set libXaw 1.0.7 Chapter 6 Composite and Constraint Widgets These widgets may contain arbitrary widget children. They implement a policy for the size and location of their children. Box This widget will pack its children as tightly as possible in non-overlapping rows. Dialog An implementation of a commonly used interaction semantic to prompt for auxiliary input from the user, such as a filename.
Athena Widget Set libXaw 1.0.7 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.
Athena Widget Set borderWidth children colormap depth destroyCallback height width hSpace vSpace libXaw 1.0.7 The width of this widget’s window border. A list of all this composite widget’s current children. The colormap that this widget will use. The depth of this widget’s window. All functions on this list are called when this widget is destroyed. The height and width of this widget in pixels. The amount of space, in pixels, to leave between the children.
Athena Widget Set libXaw 1.0.7 Class Class Name Superclass 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.
Athena Widget Set borderColor borderPixmap borderWidth children colormap defaultDistance depth destroyCallback height width icon libXaw 1.0.7 be used instead of the background color. A pixel value which indexes the widget’s colormap to derive the border color of the widget’s window. The border pixmap of this widget’s window. If this resource is set to anything other than XtUnspecifiedPixmap, the pixmap specified will be used instead of the border color. The width of this widget’s window border.
Athena Widget Set libXaw 1.0.7 Name Class Type vertDistance Thickness int bottom left right top fromHoriz fromVert horizDistance vertDistance resizable Notes Default Value defaultDistance resource What to do with this edge of the child when the parent is resized. This resource may be any edgeType. See Layout Semantics for details. Which widget this child should be placed underneath (or to the right of).
Athena Widget Set libXaw 1.0.7 6.2.3.1. 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. 6.2.3.2.
Athena Widget Set libXaw 1.0.7 Widget button = XtCreateManagedWidget(name, commandWidgetClass, w, NULL, ZERO); XtAddCallback(button, XtNcallback, func, client_data); } 6.3. Form Widget Application Header file Class Header file Class Class Name Superclass formWidgetClass Form Constraint The Form widget can contain an arbitrary number of children or subwidgets.
Athena Widget Set accelerators ancestorSensitive background backgroundPixmap borderColor borderPixmap borderWidth children colormap defaultDistance libXaw 1.0.7 A list of event to action bindings to be executed by this widget, even though the event occurred in another widget. (See the X Toolkit Intrinsics — C Language Interface for details). The sensitivity state of the ancestors of this widget. A widget is insensitive if either it or any of its ancestors is insensitive.
Athena Widget Set libXaw 1.0.7 Name Class Type resizable right top vertDistance Boolean Edge Edge Thickness Boolean XawEdgeType XawEdgeType int bottom left right top fromHoriz fromVert horizDistance vertDistance resizable Notes Default Value FALSE XawRubber XawRubber defaultDistance resource What to do with this edge of the child when the parent is resized. This resource may be any edgeType. See Layout Semantics for details.
Athena Widget Set libXaw 1.0.7 Edge Type Resource Name Description XawChainTop XawRubber ChainTop Rubber Edge remains a fixed distance from top of Form Edges will move a proportional distance 6.3.3.1. 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. 6.3.4.
Athena Widget Set libXaw 1.0.7 The default bindings for the Paned widget’s grips are: Mouse button Pane to Resize - Vertical Pane to Resize - Horizontal 1 (left) 2 (middle) 3 (right) above the grip adjust border below the grip left of the grip adjust border right of the grip 6.4.2.
Athena Widget Set background backgroundPixmap borderColor borderPixmap borderWidth children colormap cursor depth destroyCallback gripCursor gripIndent libXaw 1.0.7 not be changed with XtSetValues, although it may be queried. A pixel value which indexes the widget’s colormap to derive the background color of the widget’s window. The background pixmap of this widget’s window.
Athena Widget Set libXaw 1.0.7 lowerCursor upperCursor The cursor used to indicate which is the important pane to resize when the Paned widget is oriented vertically. mappedWhenManaged If this resource is True, then the widget’s window will automatically be mapped by the Toolkit when it is realized and managed. numChildren The number of children in this composite widget.
Athena Widget Set showGrip skipAdjust libXaw 1.0.7 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. 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. 6.4.4.
Athena Widget Set libXaw 1.0.7 6.4.4.4. 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. 6.4.5. 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.
Athena Widget Set libXaw 1.0.7 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.
Athena Widget Set libXaw 1.0.7 6.5.1.
Athena Widget Set libXaw 1.0.7 mappedWhenManaged If this resource is True, then the widget’s window will automatically be mapped by the Toolkit when it is realized and managed. numChildren The number of children in this composite widget. reportCallback A list of functions to invoke whenever the managed child widget changes size or position. screen The screen on which this widget is displayed. This is not a settable resource. sensitive Whether or not the toolkit should pass user events to this widget.
Athena Widget Set libXaw 1.0.7 6.6.1.
Athena Widget Set gravity height width hSpace vSpace libXaw 1.0.7 Specifies the side of the widget from which the tree should grow. Valid values include WestGravity, NorthGravity, EastGravity, and SouthGravity. A converter is registered for this resource that will convert the following strings: the legal values. The height and width of this widget in pixels. The amount of space, in pixels, to leave between the children.
Athena Widget Set libXaw 1.0.7 void XawTreeForceLayout(w) Widget w; w Specifies the Tree widget. 6.7. Viewport Widget Application Header file Class Header file Class Class Name Superclass viewportWidgetClass Viewport Form The Viewport widget consists of a frame window, one or two Scrollbars, and an inner window.
Athena Widget Set accelerators allowHoriz allowVert ancestorSensitive background backgroundPixmap borderColor borderPixmap borderWidth children colormap depth destroyCallback forceBars libXaw 1.0.7 A list of event to action bindings to be executed by this widget, even though the event occurred in another widget. (See the X Toolkit Intrinsics — C Language Interface for details). If these resources are False then the Viewport will never create a scrollbar in this direction.
Athena Widget Set x y libXaw 1.0.7 The location of the upper left outside corner of this widget in its parent. 6.7.2. 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.
Athena Widget Set libXaw 1.0.7 Chapter 7 Creating New Widgets (Subclassing) Written By: Ralph Swick Although the task of creating a new widget may at first appear a little daunting, there is a basic simple pattern that all widgets follow. The Athena Widget library contains a special widget called the Template widget that is intended to assist the novice widget programmer in writing a custom widget.
Athena Widget Set libXaw 1.0.7 here. Section 1.4 of the Intrinsics should be read in conjunction with this section.
Athena Widget Set libXaw 1.0.7 #define XtCTemplateResource "TemplateResource" /* declare specific TemplateWidget class and instance datatypes */ typedef struct _TemplateClassRec* typedef struct _TemplateRec* TemplateWidgetClass; TemplateWidget; /* declare the class constant */ extern WidgetClass templateWidgetClass; #endif /* _Template_h */ You will notice that most of this file is documentation.
Athena Widget Set libXaw 1.0.7 #include /* include superclass private header file */ #include /* define unique representation types not found in
Athena Widget Set libXaw 1.0.7 #include #include #include "TemplateP.h" static XtResource resources[] = { #define offset(field) XtOffsetOf(TemplateRec, template.
Athena Widget Set libXaw 1.0.7 The resource list for the ‘‘WindowWidget’’ might look like the following: static XtResource resources[] = { #define offset(field) XtOffsetOf(WindowWidgetRec, window.
Athena Widget Set /* expose libXaw 1.0.7 */ Redisplay, The ‘‘WindowWidget’’ will also declare three public procedures to return the drawing colors and the font id, saving the application the effort of constructing an argument list for a call to XtGetValues: Pixel WindowColor1(w) Widget w; { return ((WindowWidget)w)->window.color_1; } Pixel WindowColor2(w) Widget w; { return ((WindowWidget)w)->window.color_2; } Font WindowFont(w) Widget w; { return ((WindowWidget)w)->window.
Table of Contents Acknowledgments .................................................................................................................... Chapter 1 − Athena Widgets and The Intrinsics ...................................................................... Introduction to the X Toolkit ......................................................................................... Terminology ...............................................................................................................
TextSink Object .............................................................................................................. Chapter 6 - Composite and Constraint Widgets ....................................................................... Box Widget .................................................................................................................... Dialog Widget ................................................................................................................ Form Widget .
