Microline/man/XmLFolder.3x

   1 .\" ***** BEGIN LICENSE BLOCK *****
   2 .\" Version: MPL 1.1/GPL 2.0/LGPL 2.1
   3 .\"
   4 .\" The contents of this file are subject to the Mozilla Public License Version
   5 .\" 1.1 (the "License"); you may not use this file except in compliance with
   6 .\" the License. You may obtain a copy of the License at
   7 .\" http://www.mozilla.org/MPL/
   8 .\"
   9 .\" Software distributed under the License is distributed on an "AS IS" basis,
  10 .\" WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  11 .\" for the specific language governing rights and limitations under the
  12 .\" License.
  13 .\"
  14 .\" The Original Code is the Microline Widget Library, originally made available under the NPL by Neuron Data <http://www.neurondata.com>.
  15 .\"
  16 .\" The Initial Developer of the Original Code is
  17 .\" Netscape Communications Corporation.
  18 .\" Portions created by the Initial Developer are Copyright (C) 1998
  19 .\" the Initial Developer. All Rights Reserved.
  20 .\"
  21 .\" Contributor(s):
  22 .\"
  23 .\" Alternatively, the contents of this file may be used under the terms of
  24 .\" either the GNU General Public License Version 2 or later (the "GPL"), or
  25 .\" the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  26 .\" in which case the provisions of the GPL or the LGPL are applicable instead
  27 .\" of those above. If you wish to allow use of your version of this file only
  28 .\" under the terms of either the GPL or the LGPL, and not to allow others to
  29 .\" use your version of this file under the terms of the MPL, indicate your
  30 .\" decision by deleting the provisions above and replace them with the notice
  31 .\" and other provisions required by the GPL or the LGPL. If you do not delete
  32 .\" the provisions above, a recipient may use your version of this file under
  33 .\" the terms of any one of the MPL, the GPL or the LGPL.
  34 .\"
  35 .\" In addition, as a special exception to the GNU GPL, the copyright holders
  36 .\" give permission to link the code of this program with the Motif and Open
  37 .\" Motif libraries (or with modified versions of these that use the same
  38 .\" license), and distribute linked combinations including the two. You
  39 .\" must obey the GNU General Public License in all respects for all of
  40 .\" the code used other than linking with Motif/Open Motif. If you modify
  41 .\" this file, you may extend this exception to your version of the file,
  42 .\" but you are not obligated to do so. If you do not wish to do so,
  43 .\" delete this exception statement from your version.
  44 .\"
  45 .\" ***** END LICENSE BLOCK *****
  46 .TH XmLFolder 3X "R1" "XML1" "XML"
  47 .SH NAME
  48 XmLFolder
  49 .SH SYNOPSIS
  50 #include <XmL/Folder.h>
  51 .LP
  52 .SH DESCRIPTION
  53 Provides a Folder containing tabs along the top, bottom, left or
  54 right and an area managed by the tabs in the center.  Each tab
  55 consists of a Primitive widget surrounded by tab decorations including
  56 an optional pixmap.  Any non-Primitive widget children of the Folder
  57 are placed in the center area.  The widgets contained in the tabs
  58 can be assigned a non-Primitive widget to display/manage when the
  59 tab widget is selected.
  60 .SS Class Information
  61 Folder inherits from XmManager, Constraint, Composite and Core. Its
  62 class pointer is xmlFolderWidgetClass.  Its class name is XmLFolder.
  63 .SS New Resources
  64
  65 .nf
  66 .ft B
  67 Name                     Class
  68  Type                     Default              Access
  69 .ft P
  70 XmNactiveTab             XmCActiveTab
  71  int                      -1                   G
  72 XmNautoSelect            XmCAutoSelect
  73  Boolean                  True                 CSG
  74 XmNblankBackground       XmCBlankBackground
  75  Pixel                    dynamic              CSG
  76 XmNblankBackgroundPixmap XmCBlankBackgroundPixmap
  77  Pixmap                   dynamic              CSG
  78 XmNcornerDimension       XmCCornerDimension
  79  Dimension                2                    CSG
  80 XmNcornerStyle           XmCCornerStyle
  81  unsigned char            XmCORNER_ARC         CSG
  82 XmNdebugLevel            XmCDebugLevel
  83  int                      0                    CSG
  84 XmNfontList              XmCFontList
  85  XmFontList               dynamic              CSG
  86 XmNhighlightThickness    XmCHighlightThickness
  87  Dimension                2                    CSG
  88 XmNinactiveBackground    XmCInactiveBackground
  89  Pixel                    dynamic              CSG
  90 XmNinactiveForeground    XmCInactiveForeground
  91  Pixel                    dynamic              CSG
  92 XmNmarginHeight          XmCMarginHeight
  93  Dimension                0                    CSG
  94 XmNmarginWidth           XmCMarginWidth
  95  Dimension                0                    CSG
  96 XmNpixmapMargin          XmCPixmapMargin
  97  Dimension                2                    CSG
  98 XmNresizePolicy          XmCFolderResizePolicy
  99  XmRFolderResizePolicy    XmRESIZE_STATIC      CSG
 100 XmNrotateWhenLeftRight   XmCRotateWhenLeftRight
 101  Boolean                  True                 CSG
 102 XmNspacing               XmCSpacing
 103  Dimension                0                    CSG
 104 XmNtabBarHeight          XmCTabBarHeight
 105  Dimension                dynamic              G
 106 XmNtabCount              XmCTabCount
 107  int                      0                    G
 108 XmNtabPlacement          XmCTabPlacement
 109  unsigned char            XmFOLDER_TOP         CSG
 110 XmNtabsPerRow            XmCTabsPerRow
 111  int                      0                    CSG
 112 XmNtabTranslations       XmCTranslations
 113  XtTranslations           [focus translations] CG
 114 XmNtabWidgetList         XmCReadOnly
 115  WidgetList               dynamic              G
 116 .fi
 117 .IP XmNactiveTab
 118 The position of the currently active tab. The first tab on the
 119 left has a position of 0. If no tab is active, this value equals -1.
 120 .IP XmNautoSelect
 121 If True (the default), the Folder will activate its first tab
 122 when it is realized.  No callback is generated by this action.
 123 If False, no initial tab will be activated.
 124 .IP XmNblankBackground
 125 The color of the area between tabs, around tabs, and between
 126 tabs and the edge of the Folder.
 127 .IP XmNblankBackgroundPixmap
 128 The pixmap to display as a background (tiled) in the blank background
 129 area.  See XmNblankBackground.
 130 .IP XmNcornerDimension
 131 If XmNcornerStyle is XmCORNER_LINE, this value is used to determine
 132 the length of the lines that clip the corners of the tabs. The
 133 greater this value is, the longer the corner lines will be. If
 134 XmNcornerStyle is XmCORNER_ARC, this value is used to determine
 135 the sizes of the arcs in the corners of the tabs. If XmNcornerStyle
 136 is XmCORNER_NONE, this resource has no effect.
 137 .IP XmNcornerStyle
 138 Defines the type of corners on the individual tabs. Possible values:
 139
 140 .nf
 141      XmCORNER_NONE     /* no corners */
 142      XmCORNER_LINE     /* corners are beveled */
 143      XmCORNER_ARC      /* corners are round */
 144 .fi
 145 .IP XmNdebugLevel
 146 If set to a value greater than 0, debugging messages will be
 147 printed to stderr.  When set to 0 (the default) only error
 148 messages will be generated.
 149 .IP XmNfontList
 150 The default font list for tabs created with the XmLFolderAddTab()
 151 functions.  Changing this value does not affect existing widgets.
 152 If this value is NULL, a font list is obtained from the nearest
 153 parent that is a subclass of BulletinBoard, MenuShell, or VendorShell.
 154 .IP XmNhighlightThickness
 155 The thickness of the highlight drawn around the Primitive widget
 156 contained in the active tab. When a Primitive widget is added to
 157 the Folder, its highlightThickness is set to 0. The Folder is
 158 responsible for drawing the highlight in the active tab.
 159 This is necessary because if the Primitive widget were allowed
 160 to draw the highlight, it would erase the highlight with
 161 an incorrect color.
 162 .IP XmNinactiveBackground
 163 The background color of inactive tabs. This value is initially set
 164 to the background color of the Folder widget.
 165 .IP XmNinactiveForeground
 166 The foreground color of inactive tabs. This value is initially
 167 set to the foreground color of the Folder widget.
 168 .IP XmNmarginHeight
 169 If tab placement is on the top or bottom, this value is the margin
 170 between tab widgets and the top of tabs, and between tab widgets
 171 and the bottom of tabs.  If tab placement is on the left or right,
 172 this value is the margin between tab widgets and the left of tabs,
 173 and between tab widgets and the right of tabs.
 174 .IP XmNmarginWidth
 175 If tab placement is on the top or bottom, this value is the margin
 176 between tab widgets and the left of tabs, and between tab widgets
 177 and the right of tabs.  If tab placement is on the left
 178 or right, this value is the margin between tab widgets and the top of
 179 tabs and between tab widgets and bottoms of tabs.
 180 .IP XmNpixmapMargin
 181 The margin between the tab widget and any pixmap to its left.
 182 .IP XmNresizePolicy
 183 This policy determines when the Folder should perform a request
 184 for a new size from its parent.
 185 A policy of XmRESIZE_STATIC (the default) will cause the Folder
 186 to initially request a size which includes the preferred size of
 187 its children and then reject any subsequent resize requests from
 188 its non-tab widget children.  A policy of XmRESIZE_DYNAMIC will
 189 cause the Folder to resize itself to include the preferred size
 190 of any of its children whenever its children change size.  A
 191 policy of XmRESIZE_NONE will cause the Folder to never generate
 192 a resize request and also will cause it not to perform geometry
 193 management on its non-tab widget children.  Possible values:
 194
 195 .nf
 196      XmRESIZE_NONE    /* no resize requests and no
 197                          placement or geometry management
 198                          of non-tab children */
 199      XmRESIZE_STATIC  /* initially layout to include
 200                          preferred size of children */
 201      XmRESIZE_DYNAMIC /* dynamically resize as children
 202                          request new size */
 203 .fi
 204 .IP XmNrotateWhenLeftRight
 205 If True, XmDrawnButton based tabs (including tabs created with the
 206 XmLFolderAddTab() functions) will display their text vertically
 207 instead of horizontally if they are placed on the left or right
 208 of the Folder.  This occurs when the Folder's XmNtabPlacement
 209 resource is XmFOLDER_LEFT or XmFOLDER_RIGHT.  Tabs on the
 210 left would have their text drawn up and tabs on the right
 211 would have their text drawn down.  If False, tabs are left
 212 oriented horizontally regardless of their placement.
 213 .IP XmNspacing
 214 The amount of space between tabs.
 215 .IP XmNtabBarHeight
 216 The height, in pixels, of the tab bar. If tab placement is on
 217 the left or right, this value is the width of the tab bar.
 218 This value may not be set and is only valid after the Folder
 219 has been managed and has performed its layout.
 220 .IP XmNtabCount
 221 The number of tabs displayed.
 222 .IP XmNtabPlacement
 223 Where to place the tabs. Possible values:
 224
 225 .nf
 226      XmFOLDER_TOP     /* top left to right */
 227      XmFOLDER_BOTTOM  /* bottom left to right */
 228      XmFOLDER_LEFT    /* left top to bottom */
 229      XmFOLDER_RIGHT   /* right top to bottom */
 230 .fi
 231 .IP XmNtabsPerRow
 232 If set to 0 (the default), the Folder will place tabs in a
 233 single row one after another during layout.  If non-zero,
 234 this value specifies the number of rows of tabs to appear
 235 in the Folder and the Folder will pad each row to the width
 236 of the Folder by proportionally sizing the tabs based on
 237 their contents and the width of the row.
 238 .IP XmNtabTranslations
 239 The translation table used to augment the translations of
 240 Primitive widgets added to the Folder. The Folder overrides
 241 the FocusIn and FocusOut translations of its Primitive widget
 242 children allowing it to draw and erase tab highlights.
 243 .IP XmNtabWidgetList
 244 The list of widgets contained inside the tabs. These widgets
 245 are subclasses of XmPrimitive.
 246 .SS Constraint Resources
 247 Folder defines the following constraint resources.
 248
 249 .nf
 250 .ft B
 251 Name                     Class
 252  Type                     Default               Access
 253 .ft P
 254 XmNtabFreePixmaps        XmCTabFreePixmap
 255  Boolean                  False                 CSG
 256 XmNtabInactivePixmap     XmCTabInactivePixmap
 257  Pixmap                   XmUNSPECIFIED_PIXMAP  CSG
 258 XmNtabManagedName        XmCTabManagedName
 259  String                   NULL                  CSG
 260 XmNtabManagedWidget      XmCTabManagedWidget
 261  Widget                   NULL                  CSG
 262 XmNtabPixmap             XmCTabPixmap
 263  Pixmap                   XmUNSPECIFIED_PIXMAP  CSG
 264 .fi
 265 .IP XmNtabFreePixmaps
 266 If True, the Folder will call XFreePixmap on the XmNtabPixmap and
 267 XmNtabInactivePixmap pixmaps when this widget is destroyed.
 268 This value is set to True for tabs created by the
 269 XmLFolderAddBitmapTab() functions.
 270 .IP XmNtabInactivePixmap
 271 The pixmap to appear in the left of the tab when the tab is inactive.
 272 .IP XmNtabManagedName
 273 By setting a managed name on a tab widget and setting the same
 274 managed name on a Manager widget, you specify that the tab
 275 manages the Manager widget.  You can also specify that a tab
 276 manages a specific Manager widget by setting the managed name
 277 on the tab widget to the name (XtName) of the Manager widget.
 278 If a tab widget has a managed name, the XmNtabManagedWidget
 279 resource of the tab widget is ignored.
 280 .IP XmNtabManagedWidget
 281 Specifies a widget to be managed when this widget is activated.
 282 When this widget is deactivated, its managed widget will be
 283 unmanaged. This resource allows Manager widgets contained in the
 284 center of the Folder to be attached to tabs, so when a user
 285 selects a tab its attached Manager widget will be displayed on
 286 the screen.
 287 .IP XmNtabPixmap
 288 The pixmap to appear in the left of the tab when the tab is active.
 289 .SS Callback Resources
 290 Folder defines the following callback resources.
 291
 292 .nf
 293 .ft B
 294 Callback               Reason
 295 .ft P
 296 XmNactivateCallback    XmCR_ACTIVATE
 297 .fi
 298 .SS Callback Structure
 299 Each callback function is passed a pointer to the structure shown below.
 300
 301 .nf
 302    typedef struct
 303      {
 304      int reason;         /* callback reason */
 305      XEvent *event;      /* event callback or NULL */
 306      int pos;            /* position of tab to act */
 307      int allowActivate;  /* allow/disallow act (1/0) */
 308      } XmLFolderCallbackStruct;
 309 .fi
 310
 311 pos will be set to the position of the tab (with 0 as the first tab
 312 on the left) to activate for XmNactivateCallback callbacks.
 313 If allowActivate is set to 0 by the callback function, the tab will not
 314 be activated and the attempt to activate the given tab will be rejected.
 315 .SS Inherited Resources
 316 Folder inherits the resources shown below.
 317
 318 .nf
 319 .ft B
 320 Resource              From        Resource                  From
 321 .ft P
 322 XmNaccelerators       Core        XmNinitialResourcePersist Core
 323 XmNancestorSensitive  Core        XmNinsertPosition         Composite
 324 XmNbackground         Core        XmNmappedWhenManaged      Core
 325 XmNbackgroundPixmap   Core        XmNnavagationType         Manager
 326 XmNborderColor        Core        XmNnumChildren            Composite
 327 XmNborderPixmap       Core        XmNscreen                 Core
 328 XmNborderWidth        Core        XmNsensitive              Core
 329 XmNbottomShadowColor  Manager     XmNshadowThicknses        Manager
 330 XmNbottomShadowPixmap Manager     XmNstringDirection        Manager
 331 XmNchildren           Composite   XmNtopShadowColor         Manager
 332 XmNcolormap           Core        XmNtopShadowPixmap        Manager
 333 XmNdepth              Core        XmNtranslations           Core
 334 XmNdestroyCallback    Core        XmNtraversalOn            Manager
 335 XmNforeground         Manager     XmNunitType               Manager
 336 XmNheight             Core        XmNuserData               Manager
 337 XmNhelpCallback       Manager     XmNwidth                  Core
 338 XmNhighlightColor     Manager     XmNx                      Core
 339 XmNhighlightPixmap    Manager     XmNy                      Core
 340 .fi
 341
 342 .SS Folder Translations
 343 Folder defines the translations shown below.
 344
 345 .nf
 346 .ft B
 347 Event            Action
 348 .ft P
 349 BSelect Press    XmLFolderActivate()
 350 .fi
 351 .SS Folder Primitive Translations
 352 Folder overrides the translations shown below for all of
 353 its Primitive widget children.
 354
 355 .nf
 356 .ft B
 357 Event       Action
 358 .ft P
 359 FocusIn     PrimitiveFocusIn() XmLFolderPrimFocusIn()
 360 FocusOut    PrimtiveFocusOut() XmLFolderPrimFocusOut()
 361 .fi
 362 .SS Action Routines
 363 Folder defines the actions shown below.
 364 .IP XmLFolderActivate()
 365 Activates the tab at the location of the event passed to the action routine.
 366 .IP XmLFolderPrimFocusIn()
 367 Draws a highlight around the given widget.
 368 .IP XmLFolderPrimFocusOut()
 369 Erases the highlight around the given widget.
 370 .SH "SEE ALSO"
 371 XmLCreateFolder(3X) XmLFolderAddBitmapTab(3X) XmLFolderAddBitmapTabForm(3X)
 372 XmLFolderAddTab(3X) XmLFolderAddTabForm(3X) XmLFolderSetActiveTab(3X)