http://invisible-island.net/athena_widgets/XawPlus

_________________________________________________________XawPlus

The XawPlus 3.1.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.1.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.6 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 3.0.1 ?

Port to X11R6.6:

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

Full UNICODE support for menu's:

SmeBSB now has as Label full UNICODE support, independent of the locale settings, using UTF8 coded strings.

Selection of menu entries if NumLock or CapsLock is set:

In previous versions of XawPlus menu entries are not highlighted and not selectible, if NumLock or CapsLock is activated. This bug is now fixed.

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_________________________________________________________