
T h e   X m + +   C l a s s   R e f e r e n c e
===============================================


Preleminary draft, version 1 - 05/31/1993

Copyright (c) 1992, 1993  Bernhard Strassl
   Vienna User Interface Group
   Institute for Applied Computer Science and Information Systems
   University of Vienna, Austria



class XmApp
-----------

Description:
	This class handles application startup and manages the top level
	windows. An instance is automatically created by the UNIX main()
	function contained in the Xm++ library.

Public member functions:

void initialize();
	Has to be implemented by the user and must create at least
	one application window.

char* getName();
	Returns the program name (argv[0]).

Display* getDisplay();
Screen* getScreen();
XrmDatabase getResourceDatabase();
XtAppContext getAppContext();
	These functions return various X-Windows parameters and
	will usually not be needed by an application programmer.

char* getCmdArg(int index);
	Returns the command line argument with the given index or
	NULL if index > argcount.

char* xmPlusPlusVersion();
	Returns the library version number string.


class XmManager
---------------

Description:
	The superclass for all remaining Xm++ classes. It's purpose is
	to provide a non-windowed class as the general ancestor for all
	other classes which can have callback members. This allows - in
	the terminology of the MVC model - the creation of 'model classes'
	which are independend from any view/controller behavior inherited
	by all other classes.

Public member functions:

XmManager();
virtual ~XmManager();
	Constructor/Destructor handling internal things.

XmWindow* window(char* name);
XmUserDialog* dialog(char* name);
XmDialogWindow* dialogWindow(char* name);
	These functions return a named child in the appropriate type,
	or NULL if there is no child with the given name.

void changed(char* topic, XmObject* initiator = NULL);
	Calls the update(topic) function of each managed child - this allows
	the notification of one child's changes to all others without knowing
	about them (borrowed also from MVC).



class XmObject (: public XmManager)
--------------

Description:
	An abstract superclass of all windowed Xm++ object classes. It handles
	most of the general X-windows and Xtk interfacing and implements the
	default virtuals which are common for all displayable objects.

Public member functions:

XmObject* getParent();
	Returns the windowed parent of an object or NULL if there is none - can
	be true only for application windows.

const char* getName();
	Returns the name of an object. Eevery Xm++ object must have a textual
	name, it is usually given as an agument to the subclass' constructor.

bool isNamed(char* name);
	Returns TRUE if name matches the objects name, FALSE otherwise. An inline
	which helps to avoid too much strcmps troughout the application.

Widget handle();
virtual Widget topHandle();
	These functions return Xtk widget handles, they should usually not be
	needed by an application programmer.

bool valid();
	A simple object integry check for debugging.

virtual bool realize();
	Displays an object after creating and initializing it. If called on
	a root of an object tree (i.e. main window or dialog box) the entire
	tree will be realized.

virtual bool destroy();
	Destroys the external (Xtk) representation of a single Xm++ object or
	an object tree without deleting the Xm++ object - normally not used by
	application programmers.

bool destroyOnDelete();
	Sets a parameter which designates the automatic destruction of the
	external (Xtk) representation when the Xm++ object is deleted. This
	parameter is set for default in all top level objects (instances of main
	window or dialog box classes). This function needs to be called by the
	application programmer only in situations, where branches inside an object
	tree should be deleted (and this need will be eleminated in future
	releases of Xm++).

bool hide();
	Temporarily hide the object (tree) presentation.

bool show();
	Restore hidden object (tree) presentation.

virtual bool move(int x, int y);
virtual bool resize(int width, int height);
virtual bool reframe(int x, int y, int width, int height);
	Positioning and sizing functions, the coordinate arguments are assumed
	to be absolute in respect to the parent object (move/resize TO value).

bool setCallback(	XmManager* receiver,
					cbProc cbCode,
					bool setOrReset = TRUE,
					void* data = CB_OBJ_PTR	);
bool setCallback(	char* cbName,
					XmManager* receiver,
					cbProc cbCode,
					bool setOrReset = TRUE,
					void* data = CB_OBJ_PTR	);
	The callback initialization function. It's two forms differ only in that
	way, that the first form uses a class specific default name for the
	callback (i.e. XmNselectCallback for a push-button). receiver is a pointer
	to the object whose member function should be called, cbCode is a pointer
	to this member function of type 'void f(void*)', and data is a value on
	which the parameter passed to the callback member depends.
	Possible values for data are:

value:				callback member called with:

CB_NO_DATA			NULL pointer
CB_XM_DATA			object specific data (i.e. the status of a toggle button)
CB_XM_HANDLE		the Xtk widget handle (only for internal usage)
CB_OBJ_NAME			a pointer to the triggering object's name 
CB_OBJ_PTR			a pointer to the triggering object itself


(CB_XM_DATA is not implemented yet)

	When setOrReset is FALSE (remove a callback), the receiver and cbCode
	values must match exactly those given when the callback was set. The
	data parameter will be ignored.

virtual void update(char*);
	This virtual function will be called when a manager of the receiving
	object has changed. Default is to do nothing.



struct Entry
------------

Description:
	The one and only purpose of this struct is to hold the data for a
	single menu item. This is useful to speed up the creation of menues
	by passing a list of entries (using varargs).

Entry(char* text, cbProc callback, void* data = NULL);
Entry(char* text, XmObject* receiver, cbProc callback, void* data = NULL);
	These contructors take the information necessary to create an menu
	entry. text is taken for both object name and item text (may contain a
	'&' character which denotes the item mnemonic), receiver and callback
	are used to set the item callback, data is a pointer which can be passed
	to the callback function. The first form (whithout giving a receiver
	object) takes the menue's parent (application window) as default.

A Note on menu callbacks and callback data:
	Menu callbacks are called with the entry name as the callback data.
	Passing CB_XM_DATA as data causes Xm++ to use the item text (which is
	initially the same but can be changed) instead of the name.

#define NULLENTRY Entry()
	Creates an empty entry to terminale a list of entries.


class XmMenu (: public XmObject)
------------

Description:
	An abstract superclass for all menu classes. It implements most of
	the menu bahavior.

Public member functions:

void insertItemPos(int pos);
	Sets the (0 based) numeric index for subsequently added items, separators
	or submenues. If not explicitly set with this function, all added items are
	appended at the lower end of a menu.

bool addSeparator(char* name = (char* )NULL);
bool removeSeparator(char* name);
	Separator operations. Separators need to be named only when it should
	be possible to remove them later.

bool addItem(Entry e);
bool addItems(Entry, ...);
	Item add operations. The second form uses a NULLENTRY terminated list.

bool removeItem(char* name);
bool removeItems(char*, ...);
bool enableItem(char* name);
bool enableItems(char*, ...);
bool disableItem(char* name);
bool disableItems(char*, ...);
	Item remove/enable/disable operations. The item(s) which should be
	accessed are identified by their name(s). These functions return
	TRUE on success, FALSE on failure (i.e. when an item with name does
	not exist).

XmSubMenu* addSubmenu(char* text);
bool removeSubmenu(char* name);
XmSubMenu* submenuAt(char* name);
	Submenue operations. addSubmenu returns a pointer to the created submenu.
	submenuAt returns a pointer to an existing submenu. Both functions return
	NULL on failure. removeSubmenu works like removeItem.

bool changeItemText(char* name, char* newText);
	Changes the text of an existing menu item or submenu, the item name
	remains unchanged.


class XmPopupMenu (: public XmMenu)
-----------------

Description:
	A class implementing popup menues. Such a menue can be popped up by
	pressing the rightmost mouse button (default translation) inside the
	window for which it was created.

Public member functions:

bool setLabel(char* text);
	Sets the popup menu label to the given text string.


class XmDropdownMenu (: public XmMenu)
--------------------

Description:
	A class implementing the well known menu bar, consisting of horizontally
	oriented label buttons and dropdown menues which are displayed, when a
	label button is clicked. The menu bar is always located on top of the
	window for which it was created.

void insertLabelPos(int pos);
	Sets the (0 based) numeric index for subsequently added labels. If not
	explicitly set with this function, all added labels are appended after
	the rightmost label in a menu bar.

bool addLabel(char* text);
bool addLabels(char*, ...);
bool removeLabel(char* text);
bool removeLabels(char*, ...);
	These functions work similar to the item functions in class XmMenu
	except that they operate on labels.

bool setCurrentLabel(char* name);
	Sets the 'current label', the menu label to which add item operations
	in a menu bar will apply (the inherited addItem(s) functions have no
	label argument). The current label defaults to the last added label.

bool changeLabelText(char*, char*);
bool changeItemText(char* l, char* i, char* txt);


class XmSubMenu (: public XmMenu)
---------------

Description:
	A menu class which allows to build cascaded menu systems. Instances
	are created by the XmMenu's addSubmenu function.

no new public member functions.


class XmDialog (: virtual public XmObject)
--------------

Description:
	Abstract base class for modal or modeless dialog windows. 

no new public member functions.


class XmSystemDialog (: public XmDialog)
--------------------

Description:
	Abstract base class for predefined dialogs. In the current Xm++ version
	all subclasses of this class are only interfaces to Motif or Xaw system
	dialogs - so this class inherits only from XmDialog. Since Xaw has only
	one simple prompter widget class, most of the functionality of these
	dialogs is missing when using Xaw - future releases will have better
	support for Xaw.

	System dialogs in Xm++ can be used - independend of the dialog's contents
	- in 'synchronous' or 'asynchronous' mode in respect to the program
	flow control. The Xtk provides only 'asynchronous' mode - create the
	dialog,	specify callbacks for the components, and then exit the function
	to return to the XtMainLoop waiting for events. Xm++ also provides a
	'synchronous' technique for modal dialogs, allowing to retrieve a single
	value entered oder selected by the user without specifying callbacks and
	without leaving the current function, i.e.:	

	char* aFilename;
	if(aFilename = new XmFileSelector("/usr/*")->promptFile())
	{	... do something with the selected file ...
	}

	The application program flow is halted here because the promptFile()
	function does not return until the user has selected a file or canceled
	the dialog. This feature makes the usage of system dialogs more convenient.

no new public member functions.


class XmMsgBox (: public XmSystemDialog)
--------------

Description:
	A class for creating message-, question-, warning- and error-boxes. They
	differ in the icon displayed beside the text and in number and labeling
	of command buttons, their appearance is controlled by styles.

Applicable styles:
	controlling icon:
		XmSmsgMemo, XmSmsgInfo, XmSmsgQuestion,
		XmSmsgWorking, XmSmsgWarning, XmSmsgError
	controlling buttons:
		XmSmsgOk, XmSmsgOkCancel, XmSmsgOkCancelHelp,
		XmSmsgYesNo, XmSmsgYesNoCancel
	controlling mode:
		XmSdlgModeless, XmSdlgWinModal,
		XmSdlgAppModal, XmSdlgSysModal
	predefined combined styles:
		XmSmboxInfo     (XmSdlgWinModal | XmSmsgOk | XmSmsgInfo)
		XmSmboxQuestion (XmSdlgWinModal | XmSmsgYesNo | XmSmsgQuestion)
		XmSmboxWarning  (XmSdlgAppModal | XmSmsgOk | XmSmsgWarning)
		XmSmboxError  	(XmSdlgSysModal | XmSmsgOk | XmSmsgError)

Public member functions:

XmMsgBox(	char* text,
			char* label,
			xmStyle s = 0,
			XmObject* receiver = NULL,
			cbProc callback = NULL	);
	This constructor creates a message box with the given style, label and
	message text. An 'asynchronous' button callback (will be called with
	the button name) can be specified with the receiver and callback pointers,
	the dialog must be displayed with the realize() function.

bool showMsg();
	The 'synchronous' function. It displays the dialog and returns TRUE if
	the user selected OK or Yes, FALSE after Cancel or No.
	Note: To use a Help button, an 'asynchronous' callback must be
	specified too (showMsg() does not return on Help).

bool setButtonText(msgButton button, char* newName);
	Allows to change a button label to newName where button is one of
	OK, CANCEL or HELP (OK also denotes a Yes, CANCEL a No button).


class XmPrompter (: public XmMsgBox)
----------------

Description:
	A prompter is like a message box but with an editable text area. Button
	labels are always OK and Cancel (and Help if desired).

Public member functions:

XmPrompter(	char* message,
			char* label,
			char* defaultReply,
			xmStyle s = 0,
			XmObject* receiver = NULL,
			cbProc callback = NULL	);
	Like the constructor of the message box, defaultReply allows to specify
	a default contents for the editable field.

char* prompt();
	The 'synchronous' function. Returns the contents of the editable field
	when the user clicked OK, or NULL if the user clicked Cancel.

bool setText(char* newText);
char* getText();
	These two functions are only useful in 'asynchronous' mode. setText
	replaces the text in the editable with newText. getText returns its
	current value (must be used in the button callback to retrieve the
	text before destroying the prompter).


class XmListPrompter (: public XmPrompter)
--------------------

Description:
	A Prompter with an additional list box where the user can select
	the reply from predefined values.

Public member functions:

XmListPrompter(	char** list,
				char* message,
				char* label,
				int defaultReply,
				xmStyle s = 0,
				XmObject* receiver = NULL,
				cbProc callback = NULL	);
	Like the prompter's constructor, list is a NULL terminated array
	of strings which will be used to fill the list box, defaultReply is
	an index to this array.

int promptIndex();
	The 'synchronous' function. Returns the index of the selected item
	or -1 if the user clicked cancel.

XmListPrompter* selectText(char* string);
XmListPrompter* selectIndex(int index);
int getIndex();
	Functions to be used in 'asynchronous' mode. selectText and selectIndex
	allow to change the current selection, getIndex returns the index of
	the current selection.


class XmFileSelector (: public XmPrompter)
--------------------

Description:
	A special kind of list prompter for searching and selecting a file
	in a directory tree.

Public member functions:

XmFileSelector(	char* startingPath,
				xmStyle s = 0, 
				XmObject* receiver = NULL,
				cbProc callback = NULL	);
	The constructor of the file selecor. startingPath is used to define
	the initial contents of the file list.

char* promptFile();
	The 'synchronous' function. Returns the selected path or NULL if the
	user canceled the dialog.

bool setPath(char*);
char* getPath();
	Functions for 'asynchronous' mode. setPath resets the contents of the
	file list, getPath returns the currently selected path.


class XmControlPane
-------------------

Description:
	This abstract class is the base of an inheritance hierarchy for all
	Xm++ objects which may have other objects as children. The child
	objects are called 'controls' (borrowed from Microsoft's terminology)
	and can be primitives (like texts, buttons, etc.) or descendants of
	this class (like the group box).

no public member functions.


class XmDialogPane (: public XmControlPane)
------------------

Description:
	A class implementing children management with static layout for creating
	non resizeable dialog boxes or windows.
 
Public member functions:

bool add(	XmControl* child,
			XmManager* receiver = NULL,
			cbProc callback = NULL,
			void* data = CB_OBJ_PTR	);
	Adds the control child to the dialog pane's children. receiver, callback
	and data allow to specify the child's default callback - but this will
	usually not be needed because these add statements are automatically
	generated when using the dialog editor.

bool remove(char* name);
	Removes the child with the given name. Returns TRUE on success, FALSE if
	an error occured or a child with name does not exist.

XmGroupBox* groupBox(char* name);
XmStaticText* staticText(char* name);
XmStaticImage* staticImage(char* name);
XmPushButton* pushButton(char* name);
XmRadioButton* radioButton(char* name);
XmCheckBox* checkBox(char* name);
XmEdit* edit(char* name);
XmScrollBar* scrollBar(char* name);
XmListBox* listBox(char* name);
XmComboBox* comboBox(char* name);
	These functions return a (correctly casted) pointer to the child
	with the given name, or NULL if the child with name has another type
	or does not exist.
	Caution: the expression edit("myEdit")->setText("..."); causes a
	core dump if no such edit exists!


class XmUserDialog (: public XmDialog, public XmDialogPane)
------------------

Description:
	The base class for user defined dialog boxes.

Applicable styles:
	controlling border and system menu (Motif only):
		XmSmaximize, XmSminimize, XmSbordered, XmSmoveable,
		XmSresizeable, XmScloseable, XmStitled, XmSsysMenu
	controlling mode:
		XmSdlgModeless, XmSdlgWinModal,
		XmSdlgAppModal, XmSdlgSysModal

XmUserDialog(char* name, XmObject* parent = NULL, xmStyle s= 0);
XmUserDialog(char* name, XmObject* parent, XmManager* mgr, xmStyle s = 0);
	The constructor initializes a dialog box according to the given
	values. The parent parameter influences the window stacking order and
	should not be NULL when style contains XmSdlgWinModal. If the first
	form is used, the manager of the window defaults to its parent. If no
	parent is given, the first main window created by the application is
	used.

void createContents();
	Is automatically generated when using the dialog editor and contains
	all add(new Control(...)) statements to create and add the controls that
	make up the dialog box.

virtual void initContents();
	This function is called from open() and should be overridden by subclasses.
	Application specific initialization (i.e. enabling or disabling of controls,
	setting initial text and selection values) should be written here. Default
	is to do nothing.

bool open();
	Displays the initialized dialog by calling initContents() and realize().

bool setLabel(char* text);
	Set the dialog label to text. If this function is not used the dialog
	label defaults to the dialog's name.

bool setFocus(char* name);
	Set the keyboard input focus to the named control (does not work
	properly in this release).

bool setDefaultButton(char* name);
	Set the dialog's default button (the button which will be selected when
	hitting the enter key) to the named button.

bool disable(char** names);
bool disable(char* name, ...);
bool enable(char** names);
bool enable(char* name, ...);
bool hideAll(char** names);
bool hideAll(char* name, ...);
bool showAll(char** names);
bool showAll(char* name, ...);
	These functions operate either with a null terminated array of
	string (names) or a null terminated varargs list to perform an
	operation on all given controls. The meanings of the operations
	are explained in the reference entries for XmObject (hide/show)
	and XmControl (disable/enable).


class XmControl (: public XmObject)
---------------

Description:
	An abstract base class for controls.

The (protected) constructor is a template for all subclasses:

	XmControl(char* name, int x, int y, int w, int h, xmStyle s);

	The arguments are: object name, coordinates relative to the parent
	object, size, and style.

Applicable styles:
	XmStabStop

	Other styles are subclass specific - they are summarized for each class
	in its reference entry.

Public member functions:

XmUserDialog* getDialog();
	Returns the dialog box or window to which this control belongs (can
	be different from the parent when group boxes are used).

bool changeStyle(xmStyle s);
	Allows to change the control's style, works only if the control has
	not been realized.

virtual XmControl* setText(char* newText);
virtual XmControl* setFont(char* fontname);
virtual char* getText();
	These functions are generic and operate on all subclasses, which have
	text to display (static texts, edits, buttons, etc.). setText changes
	the object's text to newText, setFont changes the font in which the text
	is displayed, and getText returns the current text of the object.
	If a control has text and these functions were not used, it's text
	defaults to the control name.
 	fontname must be a valid font name for the X-server where the application
	is run (the xslfonts command can be used to get a list).

virtual XmControl* setImage(Pixmap);
	Most of the controls are also able to display images instead of text, this
	function assigns a X11 pixmap to a control (see the macro reference how
	to get such a pixmap from a xbm or gif file).

virtual XmControl* setFocus();
	Sets the keyboard input focus to this control (does not work
	properly in this release).

virtual XmControl* disable();
virtual XmControl* enable();
	These functions disable/enable a control. In disabled state a control
	accepts no input, and if it shows text, the text is grayed.


class XmGroupBox (: public XmControl, public XmDialogPane)
----------------

Description:
	A group box is a control that allows the visual grouping of logical
	related controls. As this class inherits from the dialog pane class,
	its behavior is widely identical to the dialog's. Group boxes can be
	added to other group boxes, and they can have a title string (can be
	specified with the setText() function).
	Note: If a dialog contains a group box and an arbitray control is added
	to it and the control's origin lies within the borders of the group box,
	this control is added to the group box and not to the dialog.

No subclass specific styles defined.

Public member functions:

XmGroupBox(char* name, int x, int y, int w, int h, xmStyle s = 0);
	The group box constructor.



class XmPane (: public XmControl, public XmControlPane)
------------

Description:
	A pane acts as link between a primitive control (like an edit or a
	list box) and a pane area. It surrounds its child an can have a label.
	Panes are created with the XmWindow's addSubpane() function.

No subclass specific styles defined.

Public member functions:

bool changeLabel(char* text);
	Change the pane label to text. The initial label text is given at
	creation as an argument to the addSubpane() function.


class XmPaneArea (: public XmGroupBox)
----------------

Description:
	A pane area divides a window into multiple 'subpanes' (borrowed from
	Smalltalk terminology) which can be resized by the end user. The current
	implementation supports only vertical dividing in application windows
	of class XmWindow.

No subclass specific styles defined.

Public member functions:

XmPaneArea(char* name, int x, int y, int w, int h);
	The pane area constructor.

bool addSubpane(	XmControl* aControl,
					char* label = NULL,
					XmObject* receiver = NULL,
					cbProc callback = NULL	);
	This function adds a subpane containing aControl, with label as the
	subpane label. The control's default callback can be set by specifying
	receiver and callback.

bool removeSubpane(char* name);
	Removes the subpane which holds a control with name.

int numSubpanes();
	Returns the current number of subpanes in a pane area.

bool changeSubpaneLabel(char* name, char* newLabel);
	Changes the label of the subpane which holds a control with name to the
	string pointed by newName.


class XmToolBar (: public XmGroupBox)
---------------

Description:
	Tool bars are areas within windows, which perform automatic layout
	for controls added to them. A toolbar's size depends on its parent
	window and contents. They can currently be used only in combination
	with instances of the XmWindow class.

Applicable styles:
	XmShorizontal, XmSvertical

Public member functions:

XmToolBar(char* name, xmStyle s = XmShorizontal);
	The toolbar's constructor. The style argument specifies the orientation.

bool setRows(int n);
	A toolbar can layout it's contents in one or multiple rows (if horizontally
	oriented) or columns (if vertically oriented). The height/width of each
	row/column depends on the contents. This function specifies the maximum
	number of rowms/columns.


class XmStatusBar (: public XmGroupBox)
-----------------

Description:
	A special kind of toolbar - always horizontally oriented and containing
	a static text as the leftmost control, other control are added to the
	right of it. Can currently be used only in combination with instances of
	the XmWindow class.

No subclass specific styles defined.

Public member functions:

XmStatusBar(char* name);
	The status bar constructor.

bool setMessage(char* text);
	Changes the bar's status message to text.


class XmStaticText (: public XmControl)
------------------

Description:
	Uneditable single- or multi-line text without border.

Applicable styles:
	XmSleft, XmSright, XmScenter

Public member functions:

XmStaticText(char*, int = 0, int = 0, int = 0, int = 0, xmStyle = 0);
	The constructor.


class XmStaticImage (: public XmControl)
-------------------

Description:
	Static control displaying an image.

No subclass specific styles defined.

Public member functions:

XmStaticImage(char*, int = 0, int = 0, int = 0, int = 0, xmStyle = 0);
	The constructor.


class XmPushButton (: public XmControl)
------------------

Description:
	A command button.

Applicable styles:
	XmSleft, XmSright, XmScenter, XmSdefault

Public member functions:

XmPushButton(char*, int = 0, int = 0, int = 0, int = 0, xmStyle = 0);
	The constructor.


class XmCheckBox (: public XmControl)
----------------

Description:
	A simple toggle button.

No subclass specific styles defined.

Public member functions:

XmCheckBox(char*, int = 0, int = 0, int = 0, int = 0, xmStyle = 0);
	The constructor.

bool setState(bool newState);
bool getState();
	Both functions return the current button state (TRUE if selected, FALSE
	otherwise), setState() also changes the button state to newState.


class XmRadioButton (: public XmCheckBox)
-------------------

Description:
	A toggle button that, when selected, forces all other radio buttons
	within it's group to be unselected. A radio button group are all radio
	buttons with the same parent object (dialog or group box).

No subclass specific styles defined.

Public member functions:

XmRadioButton(char*, int = 0, int = 0, int = 0, int = 0, xmStyle = 0);
	The constructor.


class XmEdit (: public XmControl)
------------

Description:
	Editable single- or multi-line text.

Applicable styles:
	XmSleft, XmSright, XmSautovscroll, XmSautohscroll, XmSmultiLine

Public member functions:

XmEdit(char*, int = 0, int = 0, int = 0, int = 0, xmStyle = 0);
	The constructor.

long getInsertPosition(int* line = NULL, int* column = NULL);
	Returns the current insert position as the number of characters from
	the beginning of the text. If the integer pointer line or column is
	not null, the respective offset is calculated and assigned.

char* getSelection();
	Returns the string which makes up the current selection.

bool setSelection(long from, long to);
	Sets the current selection to the text between the from and to offset
	values.

bool clearSelection();
	Deletes the current selection from the text buffer.

bool cut();
bool copy();
bool paste();
	Clipboard functions: cut or copy the current selection to the clipboard,
	insert the clipboard contents at the current insert position.


class XmListBox (: public XmControl)
---------------

Description:
	A list box.

Applicable styles:
	XmSautovscroll, XmSautohscroll, XmSsingleSel, XmSmultipleSel

Public member functions:

XmListBox(char*, int = 0, int = 0, int = 0, int = 0, xmStyle = 0);
	The constructor.

XmListBox* add(char* text);
	Add item text after the last item in the list.

XmListBox* insert(int index, char* text);
	Insert item text before the item with index (1 based).

bool remove(char* text);
	Remove the first item matching text.

bool remove(int index);
	Remove the item with the given index.

XmListBox* addAll(char** list);
XmListBox* addAll(char* text, ...);
XmListBox* insertAll(int, char** list);
XmListBox* insertAll(int, char* text, ...);
bool removeAll(char** list);
bool removeAll(char* text, ...);
bool removeAll(int* list);
bool removeAll(int text, ...);
	These functions work like their single form but operate on
	a null terminated array or varargs list.

bool clear();
	Remove all items in the listbox.

bool selectText(char* text, bool notify = FALSE);
bool selectIndex(int index, bool notify = FALSE);
	Select the item matching text or with the given index. If notify is
	set to TRUE invoke the listbox's select callbacks.

bool deselectText(char* text);
bool deselectIndex(int index);
	Un-select the item matching text or with the given index.

bool deselectAll();
	Un-select all items in the listbox.

bool setDoubleClickProc(XmObject* receiver, cbProc callback);
	Set the callback to be invoked when an item is selected with a
	doubleclick.

int selectedCount();
	Returns the number of items currently selected.

char* selectedItem();
	Returns the text of the selected item or NULL if none - valid for
	single selection listboxes only (style XmSsingleSel set).

char** selectedItems();
	Returns a null terminated array of selected items or NULL if no item
	is selected - valid for multiple selection listboxes only (style
	XmSmultipleSel set).

int selectedIndex();
int* selectedIndices();
	Like above but return the index / a null terminated array of indexes.


class XmComboBox (: public XmGroupBox, public XmPushButton,
----------------	public XmListBox, public XmEdit)

Description:
	This class implements a non-Motif-standard control, Macintosh- and
	Ms-Windows users will know it. It consists of an edit field and a
	single selection listbox placed below it. If an item in the list is
	selected, the contents of the edit is set to the list item's text.
	Styles are used to define three different kinds of combo boxes:
		Simple:		the listbox is always shown, the contents of the text
					field is editable.
		Dropdown:	has an arrow button to the right of the text field, the
					listbox is not initially shown but popped up when the
					button is pressed. Making a selection or pressing the
					button a second time lets the listbox disappear.
		Dropdownlist:	like dropdown but the text is read only and the
					listbox does not disappear after making a selection.


Applicable styles:
	XmSsimple, XmSdropdown, XmSdropdownlist

Public member functions:

XmComboBox(char*, int = 0, int = 0, int = 35, int = 35, xmStyle = 0);
	The constructor.

(All the other stuff is inherited from the superclasses!).



class XmDialogWindow (: public XmUserDialog)
--------------------

*Description:
	The non-paned application main window class. Unlike dialogs which
	are always transient windows, instances of this class may be treated as
	top level windows by the window manager and can have menues.

*Applicable styles:
	controlling border and system menu (Motif only):
		XmSmaximize, XmSminimize, XmSbordered, XmSmoveable,
		XmSresizeable, XmScloseable, XmStitled, XmSsysMenu

*Public member functions:

XmDialogWindow(char* name, XmObject* parent = NULL, xmStyle s = 0);
XmDialogWindow(char* name, XmObject* parent, XmManager* mgr, xmStyle s = 0);
	The constructors. Usually no parent argument will be supplied. If done,
	this class acts like an ordinary user dialog with the additional
	feature of menues.

XmPopupMenu* createPopupMenu(char* name = "&Menu");
XmDropdownMenu* createDropdownMenu();
	Create and return the requested menu.

XmPopupMenu* getPopup();
XmDropdownMenu* getDropdown();
	Return an alreday created menu.


class XmWindow (: public XmDialogWindow)
--------------

*Description:
	The paned version of the application window classes with the additional
	feature of toolbars and a status bar - see the descriptions of
	XmDialogWindow, XmPaneArea, XmPane, XmToolBar and XmStatusBar.

*No subclass specific styles defined.

*Public member functions:

XmWindow(char* name, XmObject* parent = NULL, xmStyle s = 0);
XmWindow(char* name, XmObject* parent, XmManager* mgr, xmStyle s = 0);
	The constructors - identical to XmDialogWindow.

bool addSubpane(	XmControl* control,
					char* label = NULL,
					XmObject* receiver = NULL,
					cbProc callback = NULL  );
	Adds the given control as a subpane to the window's pane area. If label
	is not null, the subpane will be labeled with the given string. receiver
	and callback allow to set the control's default callback. The new subpane
	will be created below all existing subpanes (there is currently no way
	to control the insert position, should be fixed in future releases).

bool addSubpane(	ctrlType type,
					char* name,
					char* label = NULL,
					int widht = 0,
					int height = 0,
					XmObject* receiver = NULL,
					cbProc callback = NULL  );
	Works like the function above but instead of passing a control instance
	the user only needs to specify the control type (currently one of: edit,
	listBox, drawing) and name. The control is then created by this class and
	added. If width and/or height are zero, defaults will be used.
	
bool removeSubpane(char* name);
	Removes and destroys the named subpane.

bool changeSubpaneLabel(char* name, char* newLabel);
	Sets the label of the named subpane to newLabel.

XmToolBar* addToolbar(xmStyle s);
	Adds an empty toolbar to the window, the orientation and alignment is
	controlled by the style parameter (one of: XmStop, XmSleft, XmSright,
	XmSbottom). On success, a pointer to the new toolbar, on failure (i.e.
	when a tollbar with the given style already exists) NULL is returned.

bool removeToolbar(xmStyle s); ##
	Removes and destroys the toolbar with style s.

XmToolBar* toolbar(xmStyle s);
	Returns a pointer to the toolbar with style s, or NULL if it has not
	been created.

XmStatusBar* createStatusBar();
	Creates and returns an empty status bar, returns NULL on failure.

XmStatusBar* getStatusBar();
	Returns a pointer to the status bar, or NULL if it has not
	been created.


class XmToolBox (: public XmDialogWindow, public XmToolBar)
---------------

*Description:
	This class implements a toolbox - a modeless dialog window which
	performs automatic layout for its children like a toolbar.

*No subclass specific styles defined.

*Public member functions:

XmToolBox(	char* name,
			XmObject* parent,
			xmStyle = XmSvertical,
			int rows = 1 );
XmToolBox(	char* name,
			XmObject* parent,
			XmManager* mgr,
			xmStyle s = XmSvertical,
			int rows = 1 );
	The constructors. See superclasses (dialog window, toolbar) for details.



Macros and defines:
===================

#define cb(a) XmN##a##Callback
#define CB(x) ((cbProc )&x)
	Shorthands for callback names and functions.

extern Pixmap _createXmPixmap(char*, int, int);
#define getRuntimeImage(name) _createXmPixmap(name, 0, 0)
#define getCompiledImage(name) _createXmPixmap(name##_bits, name##_width, name##_height)
	This function and it's associated macros generates a X Pixmap from
	static bitmap data or a file containing bitmap or GIF data. Note: the
	format is not detected automatically - GIF files must have a name ending
	with the string ".gif"

Caution: on machines with a cpp which does not recognize the ## concatenation
syntax (like SUNs with SUN-OS 4.1.X) the cb(a) macro cannot be used and
getCompiledImage() needs the three parameters of an X bitmap:

#define getCompiledImage(n, w, h) _createXmPixmap(n, w, h)

which has to be used for a bitmap named 'test':

getCompiledImage(test_bitmap_bits, test_bitmap_width, test_bitmap_height)


