XmpTable(3)

NAME
XmpTable - Motif Public Table Widget

SYNOPSIS
In C++ or C:
#include <X11/Intrinsic.h>
#include <X11/Xmp/Table.h>
Widget newTable = XtCreateWidget( name, xmpTableWidgetClass, pw, ... );
Widget another = XmpCreateTable( pw, name, arglist, argcount );

LINK BY
example% ld -o prog prog.o -lXmp -lXm <WclOption> -lXmu -lXt -lX11

XmpTable does not require the use of Wcl, but the author obviously encourages its use ;^). See Wcl(3) for usage and linking of Wcl.

DESCRIPTION

XmpTable is a manager widget which allows widgets to be arranged in a tabular form. The XmpTable widget has a layout resource which is used to specify the column and row position of each child. Children can span rows and/or columns. Layout options are available to control the initial sizes, justification, and dynamic resizing of children.

Amazing as this may sound, XmpTable is internally fully object-oriented, but all methods and members of internal objects are in fact accessible to client applications. Rather than being pedantic about "information hiding", the author tries to follow the principle that XmpTable is going to be used by programmers, and programmers sometimes need to do things the author did not foresee. The structures and methods of the XmpTable and all of its component objects are declared in the TableP.h include file. Some methods which some may find useful are XmpTableLocFindPosition() and XmpTableLocFind() which clients can use to find the location information for widgets at some specific location in an XmpTable, or for some specific widget in an XmpTable.

  Classes
XmpTable inherits behavior and resources from Core, Composite, Constraint, XmManager, and XmBulletinBoard classes.

The class pointer is xmpTableWidgetClass.

The class name is XmpTable.

  New Resources
The following table defines a set of widget resources used by the programmer to specify data. The programmer can also set the resource values for the inherited classes to set attributes for this widget. To reference a resource by name or by class in an application defaults file, remove the XtN or XtC prefix and use the remaining letters. The codes in the access column indicate if the given resource can be set at creation time (C), set by using XtSetValues (S), retrieved by using XtGetValues (G), or is not applicable (N/A).
XmpTable Resource Set
Name              Class             Type         Default Access
XtNlayout         XtCLayout         XmpTableLoc  NULL    CSG
XtNdefaultOptions XtCDefaultOptions XmpTableOpts NULL    CSG
XtNshrinkSimple   XtCShrinkSimple   Boolean      True    CSG
XtNforceShrink    XtCForceShrink    Boolean      True    CSG
XtNcolumnSpacing  XtCSpacing        int          0       CSG
XtNrowSpacing     XtCSpacing        int          0       CSG

XtNlayout
    Specifies the column, row, column span, row span, and options for each child. The options field is optional, and takes the identical form of the XtNdefaultOptions resource discussed below. If no options are specified for a child, that childs options will be the value of the XtNdefaultOptions resource when the child is first managed. Children which are not named in the layout specification are positioned in column 0, row 0, with colum and row spans of 1, and using the default options. If the layout is changed after the XmpTable is created, then a complete re-layout is performed. The internal type XmpTableLoc which must be passed to XtCreateWidget() or to XtSetValues() is obtained by passing a string representation of the layout specification to XmpTableLocParse() which will be discussed below. A layout resource consists of one layout specification per named child, with each layout specification being separated (or terminated) by a ";" and with each layout specification of the form:

        <name> <col> <row> [<opts>]

XtNdefaultOptions
    Specifies the layout options which apply to all children which do not have specific layout options in the child's layout specification. The layout options allow a child widget to be justified within the table cell, and allow the initial size and dynamic resizing of children to be constrained. Combinations of options can be used: tr means top and right, or north-east justification. Note that the justification does not do anything special with labels of XmLabel widgets, or text in XmText widgets: it simply sets the positioning of the entire child widget within the cell of the XmpTable. The layout options consist of a series of adjacent case sensitive letters, each of which sets a layout option:

        l   left justify child in table cell.

        r   right justify child in table cell.

        t   top justify child in table cell.

        b   bottom justify child in table cell.

        w   do not stretch width of column in which child is positioned during resizing. Column width will remain wide enough to contain the widest child in the column.

        h   do not stretch height of row in which child is positioned during resizing. Row height will remain high enough to contain the tallest child in the row.

        W   do not stretch width of child during resizing. The width of the column may grow (unless constrained by w), and the child will be justified according to its layout options.

        H   do not stretch height of child during resizing. The height of the row may grow (unless constrained by h), and the child will be justified according to its layout options.

XtNshrinkSimple
    Specifies if simple widgets (widgets which have NULL query_geometry methods) should be forced smaller when the table widget is made smaller. Such simple widgets will be forced to their original preferred sizes, but not smaller. Widgets suffering from this malady in the Motif widget set include XmArrowButton, XmArrowButtonGadget, XmDrawnButton, XmScale, XmScrollBar, XmSeparator. By default, this is True. Older versions of XmpTable did not provide this feature, and so setting this resource False will give the old behavior, which the author found obnoxious.

XtNforceShrink
    Specifies if widgets should be made smaller than their "preferred" sizes. The XmpTable widget tries to respect the preferred geometries of its children. This virtually always works when the table is initially created, but after widgets are managed, many widgets simply respond with their current sizes: this means when the Table is made larger, some children will claim they do not want to be made smaller. The difficulty arises because the vocabulary of the query geometry prototcol is somewhat limited. Widgets which are locked using options including any of "whWH" will continue to be excluded from stretching, but others will be stretched and then can be shrunk back to their initial preferred sizes from the time they were last managed. When the table is shrunk further, all children are shrunk an equal number of pixels until they are of size 1 (the smallest legal size of a Widget). By default, this resource is True. Older versions of XmpTable did not provide this feature, and so setting this resource False will give the old behavior, which the author found obnoxious.

XtNcolumnSpacing
    Specifies the number of pixels between columns.

XtNrowSpacing
    Specifies the number of pixels between rows.

  Inherited Resources
XmpTable inherits behavior and resources from the following superclasses. For a complete description of each resource, refer to the man page for that superclass.
XmBulletinBoard Resource Set
Name                Class              Type           Default      Access
XmNallowOverlap     XmCAllowOverlap    Boolean        True         CSG
XmNautoUnmanage     XmCAutoUnmanage    Boolean        True         CG
XmNbuttonFontList   XmCButtonFontList  XmFontList     dynamic      CSG
XmNcancelButton     XmCWidget          Window         NULL         SG
XmNdefaultButton    XmCWidget          Window         NULL         SG
XmNdefaultPosition  XmCDefaultPosition Boolean        True         CSG
XmNdialogStyle      XmCDialogStyle     unsigned char  dynamic      CSG
XmNdialogTitle      XmCDialogTitle     XmString       NULL         CSG
XmNfocusCallback    XmCCallback        XtCallbackList NULL         C
XmNlabelFontList    XmCLabelFontList   XmFontList     dynamic      CSG
XmNmapCallback      XmCCallback        XtCallbackList NULL         C
XmNmarginHeight     XmCMarginHeight    Dimension      10           CSG
XmNmarginWidth      XmCMarginWidth     Dimension      10           CSG
XmNnoResize         XmCNoResize        Boolean        False        CSG
XmNresizePolicy     XmCResizePolicy    unsigned char  XmRESIZE_ANY CSG
XmNshadowType       XmCShadowType      unsigned char  XmSHADOW_OUT CSG
XmNtextFontList     XmCTextFontList    XmFontList     dynamic      CSG
XmNtextTranslations XmCTranslations    XtTranslations NULL         C
XmNunmapCallback    XmCCallback        XtCallbackList NULL         C
XmManager Resource Set
Name                  Class                 Type              Default Access
XmNbottomShadowColor  XmCBottomShadowColor  Pixel             dynamic CSG
XmNbottomShadowPixmap XmCBottomShadowPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG
XmNforeground         XmCForeground         Pixel             dynamic CSG
XmNhelpCallback       XmCCallback           XtCallbackList    NULL    C
XmNhighlightColor     XmCHighlightColor     Pixel             dynamic CSG
XmNhighlightPixmap    XmCHighlightPixmap    Pixmap            dynamic CSG
XmNnavigationType     XmCNavigationType     XmNavigationType XmTAB_GROUP CSG
XmNshadowThickness    XmCShadowThickness    Dimension         dynamic CSG
XmNstringDirection    XmCStringDirection    XmStringDirection dynamic CG
XmNtopShadowColor     XmCBackgroundTopShadowColor Pixel       dynamic CSG
XmNtopShadowPixmap    XmCTopShadowPixmap    Pixmap            dynamic CSG
XmNtraversalOn        XmCTraversalOn        Boolean           True    CSG
XmNuserData           XmCUserData           Pointer           NULL    CSG
Composite Resource Set
Name              Class              Type        Default Access
XmNchildren       XmCReadOnly        WidgetList  NULL    G
XmNinsertPosition XmCInsertPosition  (*)()       NULL    CSG
XmNnumChildren    XmCReadOnly        Cardinal    0       G
Core Resource Set
Name                 Class                Type           Default Access
XmNaccelerators      XmCAccelerators      XtAccelerators NULL    CSG
XmNancestorSensitive XmCSensitive         Boolean        dynamic G
XmNbackground        XmCBackground        Pixel          dynamic CSG
XmNbackgroundPixmap  XmCPixmap            Pixmap  XmUNSPECIFIED_PIXMAP CSG
XmNborderColor       XmCBorderColor       Pixel   XtDefaultForeground  CSG
XmNborderPixmap      XmCPixmap            Pixmap  XmUNSPECIFIED_PIXMAP CSG
XmNborderWidth       XmCBorderWidth       Dimension      0       CSG
XmNcolormap          XmCColormap          Colormap       dynamic CG
XmNdepth             XmCDepth             int            dynamic CG
XmNdestroyCallback   XmCCallback          XtCallbackList NULL    C
XmNheight            XmCHeight            Dimension      dynamic CSG
XmNmappedWhenManaged XmCMappedWhenManaged Boolean        True    CSG
XmNscreen            XmCScreen            Screen*        dynamic CG
XmNsensitive         XmCSensitive         Boolean        True    CSG
XmNtranslations      XmCTranslations      XtTranslations NULL    CSG
XmNwidth             XmCWidth             Dimension      dynamic CSG
XmNx                 XmCPosition          Position       0       CSG
XmNy                 XmCPosition          Position       0       CSG

SUPPORT PROCEDURES

XmpTable provides the following procedures and functions which can be used to create and manipulate XmpTables and the children of XmpTables:
XmpTableLoc XmpTableLocParse( char* layout );
void XmpTableLocFree( XmpTableLoc toFree );
XmpTableOpts XmpTableOptsParse( char* options );
void XmpTableChildPosition( Widget child, int col, int row );
void XmpTableChildResize( Widget child, int col_span, int row_span );
void XmpTableChildOptions( Widget child, XmpTableOpts opts );
void XmpTableChildConfig( Widget child,
                          int col, int row, int col_span, int row_span,
                          XmpTableOpts opts );
Widget XmpCreateTable( Widget, char*, ArgList, Cardinal );
Widget XmpCreateTableDialog( Widget, char*, ArgList, Cardinal );
Widget XmpCreateTableTransient( Widget, char*, ArgList, Cardinal );

Each of these routines can also be invoked from resource files, as the Xmp library procedure XmpRegisterMotif() registers the names of each of these procedures as both actions and callbacks with the Wcl string-to-callback converter and with the Xt Translation Manager. These routines are discussed in more detail below.

XmpTableLoc XmpTableLocParse( char* layout );
    This function takes a string which specifies a layout resource for and XmpTable widget and returns an XmpTableLoc, a pointer to an opaque type, which can then passed to XtCreateWidget(), any of the XmpCreateTable constructors, or to XtSetValues(). The XmpTable copies the storage, and so the XmpTableLoc storage must be released by the client when no longer needed (often immediately after use) by passing the XmpTableLoc to XmpTableLocFree().

void XmpTableLocFree( XmpTableLoc toFree );
    This procedure releases the storage pointed to by the XmpTableLoc opaque pointer.

XmpTableOpts XmpTableOptsParse( char* options );
    This function parses the options specifier string into an XmpTableOpts which can then be passed to .B XtCreateWidget(), any of the XmpCreateTable constructors, or to XtSetValues(). XmpTableOpts is typedef'd to a standard machine data type (currently an int), and so does not need to be free'd.

void XmpTableChildPosition( Widget child, int col, int row );
    This procedure allows a child of an XmpTable widget to be moved to a different cell. If the child spans multiple columns and/or rows, the column and row indicates the upper left corner of the child widget. The defaultLayout resource of the XmpTable is actually changed by this procedure, so the new location of the child will be remembered even if the child is unmanaged and re-managed. The layout of the XmpTable is recomputed, which means all issues involved in the positioning and sizes of all children of the XmpTable are also re-analyzed. For example, if the child widget has the option W specified, then the column to which the child widget is moved will then be prevented from becoming wider, and the column from which the child widget came may be enabled to be made wider.

void XmpTableChildResize( Widget, int col_span, int row_span );
    This procedure allows a child of an XmpTable widget to be resized so the child spans a different number of columns or rows. Again, the layout of the XmpTable is recomputed, which means all issues involved in the positioning and sizes of all children of the XmpTable are re-analyzed. For example, if the child widget has the option W specified, then all of the columns which the child widget spans will be prevented from becoming wider.

void XmpTableChildOptions( Widget child, XmpTableOpts opts );
    This procedure allows a child of an XmpTable widget to have its layout options changed. Again, the layout of the XmpTable is recomputed, which means all issues involved in the positioning and sizes of all children of the XmpTable are re-analyzed. For example, if the child widget has the option W specified, then all of the columns which the child widget spans will be prevented from becoming wider.

void XmpTableChildConfig( Widget child,
                          int col, int row,
                          int col_span, int row_span,
                          XmpTableOpts opts );

    This procedure allows a child of an XmpTable widget to have all of its layout specifications changed at once.

Widget XmpCreateTable( Widget, char*, ArgList, Cardinal );
    This function creates a new XmpTable widget. The Widget argument specifies the parent widget ID, the char* argument specifies the name of the created widget, the ArgList argument specifies the argument list, and the Cardinal argument specifies the number of attribute/value pairs in the argument list.

Widget XmpCreateTableDialog(Widget,char*,ArgList,Cardinal);
    This function creates a new XmpTable widget as a child of a new XmDialogShell. The name of the new XmDialogShell has the same name as the new XmpTable but with the characters "_popup" concatenated to the end. The Widget argument specifies the parent widget ID, the char* argument specifies the name of the created XmpTable widget, the ArgList argument specifies the argument list, and the Cardinal argument specifies the number of attribute/value pairs in the argument list.

Widget XmpCreateTableTransient(Widget,char*,ArgList,Cardinal);
    This is almost identical to XmpCreateTableDialog() except the shell widget is an XtTransientShell, with the XtNtransientFor resource set if it is available (after R4) and the related bug is fixed (still broken in early releases of R5).

TRANSLATIONS

XmpTable inherits translations from XmBulletinBoard.

ACTIONS AND CALLBACKS

The Xmp library provides the following callbacks and actions for manipulating children of XmpTable widgets:

XmpTableChildConfig( widget col row [h_span [v_span [opts]]] )
XmpTableChildPosition( widget col row )
XmpTableChildResize( widget h_span v_span )
XmpTableChildOptions( widget options )

Each callback procedure can also be named in resource files as the name of the procedure followed by CB: i.e, XmpTableChildConfig() can also be invoked as a callback by giving the name XmpTableChildConfigCB() for a callback resource value. Also, each action procedure can also be named by appending ACT to the procedure name. Normally, I just use the procedure name, so it is less trouble to change behavior from callbacks to actions triggered by translations or accelerators, and vice versa. The CB and ACT endings are maintained for backward compatibility, and because some people like to be more explicit. It is all a matter of taste.

Arguments to the procedures are provided as strings, the characters between the parenthesis following the procedure name. If no parenthesis follow the procedure name, then a NULL string is passed to the procedure. Some procedures require arguments, some provide reasonable defaults when no arguments are given. For example:

    *foo.activateCallback:       XmpTableChildPosition( this 2 4 )

Each XmpTable callback and action procedure is discussed in detail below.

XmpTableChildConfig( w col row [h_span [v_span [opts]]] )
    This allows a child of an XmpTable to be moved to a new row or column, to be given a different horizontal or vertical span, and to change the justification and re-size options of the child.

XmpTableChildPosition( w col row )
    This allows a child of an XmpTable to be moved to a new row or column.

XmpTableChildResize( w h_span v_span )
    This allows a child of an XmpTable to be given a different horizontal or vertical span.

XmpTableChildOptions( w options )
    This allows a child of an XmpTable to be given new justification and re-size options.

SEE ALSO
Xmp (3), Mri (1), Wcl (3), X (1), Core (3X), Composite (3X), Constraint (3X), XmBulletinBoard (3X).

BUGS

The geometry management of XmScrolledWindow is still broken in Motif 1.1, and so a hack has been made to XmpTable to work around the XmScrolledWindow bug. This hack is controlled by a Boolean resource named XtNbrokenXmScrolledWindow, with class XtCBrokenXmScrolledWindow. By default, this resource is True. You should only set the resource False if you have a fixed version of XmScrolledWindow.

The bug in XmScrolledWindow is rarely noticable, but when it is, it is obnoxious. The manifestation is multiple redundant resizes of XmScrolledWindows inside XmpTables.

AUTHORS
David E. Smyth (David.Smyth@sniap.mchp.sni.de) at Siemens Nixdorf Informationssysteme AG, Munich Germany. The original Table widget on which the external interface and many concepts of the XmpTable were derived was written by David Harrison in 1989 while he was at the University of California, Berkeley.