XmLFolder(3X)

NAME
XmLFolder

SYNOPSIS
#include <XmL/Folder.h>

DESCRIPTION
Provides a Folder containing tabs along the top, bottom, left or right and an area managed by the tabs in the center. Each tab consists of a Primitive widget surrounded by tab decorations including an optional pixmap. Any non-Primitive widget children of the Folder are placed in the center area. The widgets contained in the tabs can be assigned a non-Primitive widget to display/manage when the tab widget is selected.

  Class Information
Folder inherits from XmManager, Constraint, Composite and Core. Its class pointer is xmlFolderWidgetClass. Its class name is XmLFolder.

  New Resources
Name                     Class
 Type                     Default              Access
XmNactiveTab             XmCActiveTab
 int                      -1                   G
XmNautoSelect            XmCAutoSelect
 Boolean                  True                 CSG
XmNblankBackground       XmCBlankBackground
 Pixel                    dynamic              CSG
XmNblankBackgroundPixmap XmCBlankBackgroundPixmap
 Pixmap                   dynamic              CSG
XmNcornerDimension       XmCCornerDimension
 Dimension                2                    CSG
XmNcornerStyle           XmCCornerStyle
 unsigned char            XmCORNER_ARC         CSG
XmNdebugLevel            XmCDebugLevel
 int                      0                    CSG
XmNfontList              XmCFontList
 XmFontList               dynamic              CSG
XmNhighlightThickness    XmCHighlightThickness
 Dimension                2                    CSG
XmNinactiveBackground    XmCInactiveBackground
 Pixel                    dynamic              CSG
XmNinactiveForeground    XmCInactiveForeground
 Pixel                    dynamic              CSG
XmNmarginHeight          XmCMarginHeight
 Dimension                0                    CSG
XmNmarginWidth           XmCMarginWidth
 Dimension                0                    CSG
XmNpixmapMargin          XmCPixmapMargin
 Dimension                2                    CSG
XmNresizePolicy          XmCFolderResizePolicy
 XmRFolderResizePolicy    XmRESIZE_STATIC      CSG
XmNrotateWhenLeftRight   XmCRotateWhenLeftRight
 Boolean                  True                 CSG
XmNspacing               XmCSpacing
 Dimension                0                    CSG
XmNtabBarHeight          XmCTabBarHeight
 Dimension                dynamic              G
XmNtabCount              XmCTabCount
 int                      0                    G
XmNtabPlacement          XmCTabPlacement
 unsigned char            XmFOLDER_TOP         CSG
XmNtabsPerRow            XmCTabsPerRow
 int                      0                    CSG
XmNtabTranslations       XmCTranslations
 XtTranslations           [focus translations] CG
XmNtabWidgetList         XmCReadOnly
 WidgetList               dynamic              G

XmNactiveTab
    The position of the currently active tab. The first tab on the left has a position of 0. If no tab is active, this value equals -1.

XmNautoSelect
    If True (the default), the Folder will activate its first tab when it is realized. No callback is generated by this action. If False, no initial tab will be activated.

XmNblankBackground
    The color of the area between tabs, around tabs, and between tabs and the edge of the Folder.

XmNblankBackgroundPixmap
    The pixmap to display as a background (tiled) in the blank background area. See XmNblankBackground.

XmNcornerDimension
    If XmNcornerStyle is XmCORNER_LINE, this value is used to determine the length of the lines that clip the corners of the tabs. The greater this value is, the longer the corner lines will be. If XmNcornerStyle is XmCORNER_ARC, this value is used to determine the sizes of the arcs in the corners of the tabs. If XmNcornerStyle is XmCORNER_NONE, this resource has no effect.

XmNcornerStyle
    Defines the type of corners on the individual tabs. Possible values:
         XmCORNER_NONE     /* no corners */
         XmCORNER_LINE     /* corners are beveled */
         XmCORNER_ARC      /* corners are round */

XmNdebugLevel
    If set to a value greater than 0, debugging messages will be printed to stderr. When set to 0 (the default) only error messages will be generated.

XmNfontList
    The default font list for tabs created with the XmLFolderAddTab() functions. Changing this value does not affect existing widgets. If this value is NULL, a font list is obtained from the nearest parent that is a subclass of BulletinBoard, MenuShell, or VendorShell.

XmNhighlightThickness
    The thickness of the highlight drawn around the Primitive widget contained in the active tab. When a Primitive widget is added to the Folder, its highlightThickness is set to 0. The Folder is responsible for drawing the highlight in the active tab. This is necessary because if the Primitive widget were allowed to draw the highlight, it would erase the highlight with an incorrect color.

XmNinactiveBackground
    The background color of inactive tabs. This value is initially set to the background color of the Folder widget.

XmNinactiveForeground
    The foreground color of inactive tabs. This value is initially set to the foreground color of the Folder widget.

XmNmarginHeight
    If tab placement is on the top or bottom, this value is the margin between tab widgets and the top of tabs, and between tab widgets and the bottom of tabs. If tab placement is on the left or right, this value is the margin between tab widgets and the left of tabs, and between tab widgets and the right of tabs.

XmNmarginWidth
    If tab placement is on the top or bottom, this value is the margin between tab widgets and the left of tabs, and between tab widgets and the right of tabs. If tab placement is on the left or right, this value is the margin between tab widgets and the top of tabs and between tab widgets and bottoms of tabs.

XmNpixmapMargin
    The margin between the tab widget and any pixmap to its left.

XmNresizePolicy
    This policy determines when the Folder should perform a request for a new size from its parent. A policy of XmRESIZE_STATIC (the default) will cause the Folder to initially request a size which includes the preferred size of its children and then reject any subsequent resize requests from its non-tab widget children. A policy of XmRESIZE_DYNAMIC will cause the Folder to resize itself to include the preferred size of any of its children whenever its children change size. A policy of XmRESIZE_NONE will cause the Folder to never generate a resize request and also will cause it not to perform geometry management on its non-tab widget children. Possible values:
         XmRESIZE_NONE    /* no resize requests and no
                             placement or geometry management
                             of non-tab children */
         XmRESIZE_STATIC  /* initially layout to include
                             preferred size of children */
         XmRESIZE_DYNAMIC /* dynamically resize as children
                             request new size */

XmNrotateWhenLeftRight
    If True, XmDrawnButton based tabs (including tabs created with the XmLFolderAddTab() functions) will display their text vertically instead of horizontally if they are placed on the left or right of the Folder. This occurs when the Folder's XmNtabPlacement resource is XmFOLDER_LEFT or XmFOLDER_RIGHT. Tabs on the left would have their text drawn up and tabs on the right would have their text drawn down. If False, tabs are left oriented horizontally regardless of their placement.

XmNspacing
    The amount of space between tabs.

XmNtabBarHeight
    The height, in pixels, of the tab bar. If tab placement is on the left or right, this value is the width of the tab bar. This value may not be set and is only valid after the Folder has been managed and has performed its layout.

XmNtabCount
    The number of tabs displayed.

XmNtabPlacement
    Where to place the tabs. Possible values:
         XmFOLDER_TOP     /* top left to right */
         XmFOLDER_BOTTOM  /* bottom left to right */
         XmFOLDER_LEFT    /* left top to bottom */
         XmFOLDER_RIGHT   /* right top to bottom */

XmNtabsPerRow
    If set to 0 (the default), the Folder will place tabs in a single row one after another during layout. If non-zero, this value specifies the number of rows of tabs to appear in the Folder and the Folder will pad each row to the width of the Folder by proportionally sizing the tabs based on their contents and the width of the row.

XmNtabTranslations
    The translation table used to augment the translations of Primitive widgets added to the Folder. The Folder overrides the FocusIn and FocusOut translations of its Primitive widget children allowing it to draw and erase tab highlights.

XmNtabWidgetList
    The list of widgets contained inside the tabs. These widgets are subclasses of XmPrimitive.

  Constraint Resources
Folder defines the following constraint resources.
Name                     Class
 Type                     Default               Access
XmNtabFreePixmaps        XmCTabFreePixmap
 Boolean                  False                 CSG
XmNtabInactivePixmap     XmCTabInactivePixmap
 Pixmap                   XmUNSPECIFIED_PIXMAP  CSG
XmNtabManagedName        XmCTabManagedName
 String                   NULL                  CSG
XmNtabManagedWidget      XmCTabManagedWidget
 Widget                   NULL                  CSG
XmNtabPixmap             XmCTabPixmap
 Pixmap                   XmUNSPECIFIED_PIXMAP  CSG

XmNtabFreePixmaps
    If True, the Folder will call XFreePixmap on the XmNtabPixmap and XmNtabInactivePixmap pixmaps when this widget is destroyed. This value is set to True for tabs created by the XmLFolderAddBitmapTab() functions.

XmNtabInactivePixmap
    The pixmap to appear in the left of the tab when the tab is inactive.

XmNtabManagedName
    By setting a managed name on a tab widget and setting the same managed name on a Manager widget, you specify that the tab manages the Manager widget. You can also specify that a tab manages a specific Manager widget by setting the managed name on the tab widget to the name (XtName) of the Manager widget. If a tab widget has a managed name, the XmNtabManagedWidget resource of the tab widget is ignored.

XmNtabManagedWidget
    Specifies a widget to be managed when this widget is activated. When this widget is deactivated, its managed widget will be unmanaged. This resource allows Manager widgets contained in the center of the Folder to be attached to tabs, so when a user selects a tab its attached Manager widget will be displayed on the screen.

XmNtabPixmap
    The pixmap to appear in the left of the tab when the tab is active.

  Callback Resources
Folder defines the following callback resources.
Callback               Reason
XmNactivateCallback    XmCR_ACTIVATE

  Callback Structure
Each callback function is passed a pointer to the structure shown below.
   typedef struct
     {
     int reason;         /* callback reason */
     XEvent *event;      /* event callback or NULL */
     int pos;            /* position of tab to act */
     int allowActivate;  /* allow/disallow act (1/0) */
     } XmLFolderCallbackStruct;
pos will be set to the position of the tab (with 0 as the first tab on the left) to activate for XmNactivateCallback callbacks. If allowActivate is set to 0 by the callback function, the tab will not be activated and the attempt to activate the given tab will be rejected.

  Inherited Resources
Folder inherits the resources shown below.
Resource              From        Resource                  From
XmNaccelerators       Core        XmNinitialResourcePersist Core
XmNancestorSensitive  Core        XmNinsertPosition         Composite
XmNbackground         Core        XmNmappedWhenManaged      Core
XmNbackgroundPixmap   Core        XmNnavagationType         Manager
XmNborderColor        Core        XmNnumChildren            Composite
XmNborderPixmap       Core        XmNscreen                 Core
XmNborderWidth        Core        XmNsensitive              Core
XmNbottomShadowColor  Manager     XmNshadowThicknses        Manager
XmNbottomShadowPixmap Manager     XmNstringDirection        Manager
XmNchildren           Composite   XmNtopShadowColor         Manager
XmNcolormap           Core        XmNtopShadowPixmap        Manager
XmNdepth              Core        XmNtranslations           Core
XmNdestroyCallback    Core        XmNtraversalOn            Manager
XmNforeground         Manager     XmNunitType               Manager
XmNheight             Core        XmNuserData               Manager
XmNhelpCallback       Manager     XmNwidth                  Core
XmNhighlightColor     Manager     XmNx                      Core
XmNhighlightPixmap    Manager     XmNy                      Core

  Folder Translations
Folder defines the translations shown below.
Event            Action
BSelect Press    XmLFolderActivate()

  Folder Primitive Translations
Folder overrides the translations shown below for all of its Primitive widget children.
Event       Action
FocusIn     PrimitiveFocusIn() XmLFolderPrimFocusIn()
FocusOut    PrimtiveFocusOut() XmLFolderPrimFocusOut()

  Action Routines
Folder defines the actions shown below.

XmLFolderActivate()
    Activates the tab at the location of the event passed to the action routine.

XmLFolderPrimFocusIn()
    Draws a highlight around the given widget.

XmLFolderPrimFocusOut()
    Erases the highlight around the given widget.

SEE ALSO
XmLCreateFolder(3X) XmLFolderAddBitmapTab(3X) XmLFolderAddBitmapTabForm(3X) XmLFolderAddTab(3X) XmLFolderAddTabForm(3X) XmLFolderSetActiveTab(3X)