XmForm(3X)XmForm(3X)NAMEXmForm — The Form widget class
SYNOPSIS
#include <Xm/Form.h>
VERSION
This page documents version 1.2 of the Motif library.
DESCRIPTION
Form is a container widget with no input semantics of its own. Con‐
straints are placed on children of the Form to define attachments for
each of the child's four sides. These attachments can be to the Form,
to another child widget or gadget, to a relative position within the
Form, or to the initial position of the child. The attachments deter‐
mine the layout behavior of the Form when resizing occurs.
The default value for XmNinitialFocus is the value of XmNdefaultButton.
Following are some important considerations in using a Form: Every
child must have an attachment on either the left or the right. If ini‐
tialization or XtSetValues leaves a widget without such an attachment,
the result depends upon the value of XmNrubberPositioning.
If XmNrubberPositioning is False, the child is given an XmNleftAttach‐
ment of XmATTACH_FORM and an XmNleftOffset equal to its current x
value.
If XmNrubberPositioning is True, the child is given an XmNleftAttach‐
ment of XmATTACH_POSITION and an XmNleftPosition proportional to the
current x value divided by the width of the Form.
In either case, if the child has not been previously given an x value,
its x value is taken to be 0, which places the child at the left side
of the Form. If you want to create a child without any attachments,
and then later (e.g., after creating and managing it, but before real‐
izing it) give it a right attachment via XtSetValues, you must set its
XmNleftAttachment to XmATTACH_NONE at the same time. The XmNresizable
resource controls only whether a geometry request by the child will be
granted. It has no effect on whether the child's size can be changed
because of changes in geometry of the Form or of other children. Every
child has a preferred width, based on geometry requests it makes
(whether they are granted or not). If a child has attachments on both
the left and the right sides, its size is completely controlled by the
Form. It can be shrunk below its preferred width or enlarged above it,
if necessary, due to other constraints. In addition, the child's geom‐
etry requests to change its own width may be refused. If a child has
attachments on only its left or right side, it will always be at its
preferred width (if resizable, otherwise at is current width). This
may cause it to be clipped by the Form or by other children. If a
child's left (or right) attachment is set to XmATTACH_SELF, its corre‐
sponding left (or right) offset is forced to 0. The attachment is then
changed to XmATTACH_POSITION, with a position that corresponds to x
value of the child's left (or right) edge. To fix the position of a
side at a specific x value use XmATTACH_FORM or XmATTACH_OPPOSITE_FORM
with the x value as the left (or right) offset. Unmapping a child has
no effect on the Form except that the child is not mapped. Unmanaging
a child unmaps it. If no other child is attached to it, or if all
children attached to it and all children recursively attached to them
are also all unmanaged, all of those children are treated as if they
did not exist in determining the size of the Form. When using XtSet‐
Values to change the XmNx resource of a child, you must simultaneously
set its left attachment to either XmATTACH_SELF or XmATTACH_NONE. Oth‐
erwise, the request is not granted. If XmNresizable is False, the
request is granted only if the child's size can remain the same. A
left (or right) attachment of XmATTACH_WIDGET, where XmNleftWidget (or
XmNrightWidget) is NULL, acts like an attachment of XmATTACH_FORM. If
an attachment is made to a widget that is not a child of the Form, but
an ancestor of the widget is a child of the Form, the attachment is
made to the ancestor.
All these considerations are true of top and bottom attachments as
well, with top acting like left, bottom acting like right, y acting
like x, and height acting like width.
Classes
Form inherits behavior and resources from Core, Composite, Constraint,
XmManager, and XmBulletinBoard classes.
The class pointer is xmFormWidgetClass.
The class name is XmForm.
New Resources
The following table defines a set of widget resources used by the pro‐
grammer to specify data. The programmer can also set the resource val‐
ues for the inherited classes to set attributes for this widget. To
reference a resource by name or by class in a .Xdefaults file, remove
the XmN or XmC prefix and use the remaining letters. To specify one of
the defined values for a resource in a .Xdefaults file, remove the Xm
prefix and use the remaining letters (in either lowercase or uppercase,
but include any underscores between words). 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).
XmForm Resource Set
Name Class Type Default Access
───────────────────────────────────────────────────────────────────────────
XmNfractionBase XmCMaxValue int 100 CSG
XmNhorizontalSpacing XmCSpacing Dimension 0 CSG
XmNrubberPositioning XmCRubberPositioning Boolean False CSG
XmNverticalSpacing XmCSpacing Dimension 0 CSG
Specifies the denominator used in calculating the relative position of
a child widget using XmATTACH_POSITION constraints. The value must not
be 0.
If the value of a child's XmNleftAttachment (or XmNrightAttachment) is
XmATTACH_POSITION, the position of the left (or right) side of the
child is relative to the left side of the Form and is a fraction of the
width of the Form. This fraction is the value of the child's XmNleft‐
Position (or XmNrightPosition) resource divided by the value of the
Form's XmNfractionBase.
If the value of a child's XmNtopAttachment (or XmNbottomAttachment) is
XmATTACH_POSITION, the position of the top (or bottom) side of the
child is relative to the top side of the Form and is a fraction of the
height of the Form. This fraction is the value of the child's XmNtop‐
Position (or XmNbottomPosition) resource divided by the value of the
Form's XmNfractionBase. Specifies the offset for right and left
attachments. This resource is only used if no offset resource is spec‐
ified (when attaching to a widget), or if no margin resource is speci‐
fied (when attaching to the Form). Indicates the default near (left)
and top attachments for a child of the Form. (Note: Whether this
resource actually applies to the left or right side of the child and
its attachment may depend on the value of the XmNstringDirection
resource.)
The default left attachment is applied whenever initialization or
XtSetValues leaves the child without either a left or right attachment.
The default top attachment is applied whenever initialization or XtSet‐
Values leaves the child without either a top or bottom attachment.
If this Boolean resource is set to False, XmNleftAttachment and XmN‐
topAttachment default to XmATTACH_FORM, XmNleftOffset defaults to the
current x value of the left side of the child, and XmNtopOffset
defaults to the current y value of the child. The effect is to posi‐
tion the child according to its absolute distance from the left or top
side of the Form.
If this resource is set to True, XmNleftAttachment and XmNtopAttachment
default to XmATTACH_POSITION, XmNleftPosition defaults to a value pro‐
portional to the current x value of the left side of the child divided
by the width of the Form, and XmNtopPosition defaults to a value pro‐
portional to the current y value of the child divided by the height of
the Form. The effect is to position the child relative to the left or
top side of the Form and in proportion to the width or height of the
Form. Specifies the offset for top and bottom attachments. This
resource is only used if no offset resource is specified (when attach‐
ing to a widget), or if no margin resource is specified (when attaching
to the Form).
XmForm Constraint Resource Set
Name Class Type Default Access
─────────────────────────────────────────────────────────────────────────────
XmNbottomAttachment XmCAttachment unsigned char XmATTACH_NONE CSG
XmNbottomOffset XmCOffset int 0 CSG
XmNbottomPosition XmCAttachment int 0 CSG
XmNbottomWidget XmCWidget Widget NULL CSG
XmNleftAttachment XmCAttachment unsigned char XmATTACH_NONE CSG
XmNleftOffset XmCOffset int 0 CSG
XmNleftPosition XmCAttachment int 0 CSG
XmNleftWidget XmCWidget Widget NULL CSG
XmNresizable XmCBoolean Boolean True CSG
XmNrightAttachment XmCAttachment unsigned char XmATTACH_NONE CSG
XmNrightOffset XmCOffset int 0 CSG
XmNrightPosition XmCAttachment int 0 CSG
XmNrightWidget XmCWidget Widget NULL CSG
XmNtopAttachment XmCAttachment unsigned char XmATTACH_NONE CSG
XmNtopOffset XmCOffset int 0 CSG
XmNtopPosition XmCAttachment int 0 CSG
XmNtopWidget XmCWidget Widget NULL CSG
Specifies attachment of the bottom side of the child. It can have the
following values: XmATTACH_NONE—Do not attach the bottom side of the
child. XmATTACH_FORM—Attach the bottom side of the child to the bottom
side of the Form. XmATTACH_OPPOSITE_FORM—Attach the bottom side of the
child to the top side of the Form. XmNbottomOffset can be used to
determine the visibility of the child. XmATTACH_WIDGET—Attach the bot‐
tom side of the child to the top side of the widget or gadget specified
in the XmNbottomWidget resource. If XmNbottomWidget is NULL, XmAT‐
TACH_WIDGET is replaced by XmATTACH_FORM, and the child is attached to
the bottom side of the Form. XmATTACH_OPPOSITE_WIDGET—Attach the bot‐
tom side of the child to the bottom side of the widget or gadget speci‐
fied in the XmNbottomWidget resource. XmATTACH_POSITION—Attach the
bottom side of the child to a position that is relative to the top side
of the Form and in proportion to the height of the Form. This position
is determined by the XmNbottomPosition and XmNfractionBase resources.
XmATTACH_SELF—Attach the bottom side of the child to a position that is
proportional to the current y value of the bottom of the child divided
by the height of the Form. This position is determined by the XmNbot‐
tomPosition and XmNfractionBase resources. XmNbottomPosition is set to
a value proportional to the current y value of the bottom of the child
divided by the height of the Form. Specifies the constant offset
between the bottom side of the child and the object to which it is
attached. The relationship established remains, regardless of any
resizing operations that occur. When this resource is explicitly set,
the value of XmNverticalSpacing is ignored. This resource is used to
determine the position of the bottom side of the child when the child's
XmNbottomAttachment is set to XmATTACH_POSITION. In this case the
position of the bottom side of the child is relative to the top side of
the Form and is a fraction of the height of the Form. This fraction is
the value of the child's XmNbottomPosition resource divided by the
value of the Form's XmNfractionBase. For example, if the child's XmN‐
bottomPosition is 50, the Form's XmNfractionBase is 100, and the Form's
height is 200, the position of the bottom side of the child is 100.
Specifies the widget or gadget to which the bottom side of the child is
attached. This resource is used if XmNbottomAttachment is set to
either XmATTACH_WIDGET or XmATTACH_OPPOSITE_WIDGET.
A string-to-widget resource converter is automatically installed for
use with this resource. With this converter, the widget that is to be
the value of the resource must exist at the time the widget that has
the resource is created. Specifies attachment of the near (left) side
of the child. (Note: Whether this resource actually applies to the
left or right side of the child and its attachment may depend on the
value of the XmNstringDirection resource.) It can have the following
values: XmATTACH_NONE—Do not attach the left side of the child. If
XmNrightAttachment is also XmATTACH_NONE, this value is ignored and the
child is given a default left attachment. XmATTACH_FORM—Attach the
left side of the child to the left side of the Form. XmATTACH_OPPO‐
SITE_FORM—Attach the left side of the child to the right side of the
Form. XmNleftOffset can be used to determine the visibility of the
child. XmATTACH_WIDGET—Attach the left side of the child to the right
side of the widget or gadget specified in the XmNleftWidget resource.
If XmNleftWidget is NULL, XmATTACH_WIDGET is replaced by XmATTACH_FORM,
and the child is attached to the left side of the Form. XmATTACH_OPPO‐
SITE_WIDGET—Attach the left side of the child to the left side of the
widget or gadget specified in the XmNleftWidget resource. XmAT‐
TACH_POSITION—Attach the left side of the child to a position that is
relative to the left side of the Form and in proportion to the width of
the Form. This position is determined by the XmNleftPosition and XmN‐
fractionBase resources. XmATTACH_SELF—Attach the left side of the
child to a position that is proportional to the current x value of the
left side of the child divided by the width of the Form. This position
is determined by the XmNleftPosition and XmNfractionBase resources.
XmNleftPosition is set to a value proportional to the current x value
of the left side of the child divided by the width of the Form. Speci‐
fies the constant offset between the near (left) side of the child and
the object to which it is attached. (Note: Whether this resource
actually applies to the left or right side of the child and its attach‐
ment may depend on the value of the XmNstringDirection resource.) The
relationship established remains, regardless of any resizing operations
that occur. When this resource is explicitly set, the value of XmNhor‐
izontalSpacing is ignored. This resource is used to determine the
position of the near (left) side of the child when the child's XmNleft‐
Attachment is set to XmATTACH_POSITION. (Note: Whether this resource
actually applies to the left or right side of the child and its attach‐
ment may depend on the value of the XmNstringDirection resource.)
In this case the position of the left side of the child is relative to
the left side of the Form and is a fraction of the width of the Form.
This fraction is the value of the child's XmNleftPosition resource
divided by the value of the Form's XmNfractionBase. For example, if
the child's XmNleftPosition is 50, the Form's XmNfractionBase is 100,
and the Form's width is 200, the position of the left side of the child
is 100. Specifies the widget or gadget to which the near (left) side
of the child is attached. (Note: Whether this resource actually
applies to the left or right side of the child and its attachment may
depend on the value of the XmNstringDirection resource.) This resource
is used if XmNleftAttachment is set to either XmATTACH_WIDGET or XmAT‐
TACH_OPPOSITE_WIDGET.
A string-to-widget resource converter is automatically installed for
use with this resource. With this converter, the widget that is to be
the value of the resource must exist at the time the widget that has
the resource is created. This Boolean resource specifies whether or
not a child's request for a new size is (conditionally) granted by the
Form. If this resource is set to True the request is granted if possi‐
ble. If this resource is set to False the request is always refused.
If a child has both left and right attachments, its width is completely
controlled by the Form, regardless of the value of the child's XmNre‐
sizable resource. If a child has a left or right attachment but not
both, the child's XmNwidth is used in setting its width if the value of
the child's XmNresizable resource is True. These conditions are also
true for top and bottom attachments, with height acting like width.
Specifies attachment of the far (right) side of the child. (Note:
Whether this resource actually applies to the left or right side of the
child and its attachment may depend on the value of the XmNstringDirec‐
tion resource.) It can have the following values: XmATTACH_NONE—Do not
attach the right side of the child. XmATTACH_FORM—Attach the right
side of the child to the right side of the Form. XmATTACH_OPPO‐
SITE_FORM—Attach the right side of the child to the left side of the
Form. XmNrightOffset can be used to determine the visibility of the
child. XmATTACH_WIDGET—Attach the right side of the child to the left
side of the widget or gadget specified in the XmNrightWidget resource.
If XmNrightWidget is NULL, XmATTACH_WIDGET is replaced by XmAT‐
TACH_FORM, and the child is attached to the right side of the Form.
XmATTACH_OPPOSITE_WIDGET—Attach the right side of the child to the
right side of the widget or gadget specified in the XmNrightWidget
resource. XmATTACH_POSITION—Attach the right side of the child to a
position that is relative to the left side of the Form and in propor‐
tion to the width of the Form. This position is determined by the XmN‐
rightPosition and XmNfractionBase resources. XmATTACH_SELF—Attach the
right side of the child to a position that is proportional to the cur‐
rent x value of the right side of the child divided by the width of the
Form. This position is determined by the XmNrightPosition and XmNfrac‐
tionBase resources. XmNrightPosition is set to a value proportional to
the current x value of the right side of the child divided by the width
of the Form. Specifies the constant offset between the far (right)
side of the child and the object to which it is attached. (Note:
Whether this resource actually applies to the left or right side of the
child and its attachment may depend on the value of the XmNstringDirec‐
tion resource.) The relationship established remains, regardless of
any resizing operations that occur. When this resource is explicitly
set, the value of XmNhorizontalSpacing is ignored. This resource is
used to determine the position of the far (right) side of the child
when the child's XmNrightAttachment is set to XmATTACH_POSITION.
(Note: Whether this resource actually applies to the left or right
side of the child and its attachment may depend on the value of the
XmNstringDirection resource.)
In this case the position of the right side of the child is relative to
the left side of the Form and is a fraction of the width of the Form.
This fraction is the value of the child's XmNrightPosition resource
divided by the value of the Form's XmNfractionBase. For example, if
the child's XmNrightPosition is 50, the Form's XmNfractionBase is 100,
and the Form's width is 200, the position of the right side of the
child is 100. Specifies the widget or gadget to which the far (right)
side of the child is attached. (Note: Whether this resource actually
applies to the left or right side of the child and its attachment may
depend on the value of the XmNstringDirection resource.) This resource
is used if XmNrightAttachment is set to either XmATTACH_WIDGET or XmAT‐
TACH_OPPOSITE_WIDGET.
A string-to-widget resource converter is automatically installed for
use with this resource. With this converter, the widget that is to be
the value of the resource must exist at the time the widget that has
the resource is created. Specifies attachment of the top side of the
child. It can have following values: XmATTACH_NONE—Do not attach the
top side of the child. If XmNbottomAttachment is also XmATTACH_NONE,
this value is ignored and the child is given a default top attachment.
XmATTACH_FORM—Attach the top side of the child to the top side of the
Form. XmATTACH_OPPOSITE_FORM—Attach the top side of the child to the
bottom side of the Form. XmNtopOffset can be used to determine the
visibility of the child. XmATTACH_WIDGET—Attach the top side of the
child to the bottom side of the widget or gadget specified in the XmN‐
topWidget resource. If XmNtopWidget is NULL, XmATTACH_WIDGET is
replaced by XmATTACH_FORM, and the child is attached to the top side of
the Form. XmATTACH_OPPOSITE_WIDGET—Attach the top side of the child to
the top side of the widget or gadget specified in the XmNtopWidget
resource. XmATTACH_POSITION—Attach the top side of the child to a
position that is relative to the top side of the Form and in proportion
to the height of the Form. This position is determined by the XmNtop‐
Position and XmNfractionBase resources. XmATTACH_SELF—Attach the top
side of the child to a position that is proportional to the current y
value of the child divided by the height of the Form. This position is
determined by the XmNtopPosition and XmNfractionBase resources. XmN‐
topPosition is set to a value proportional to the current y value of
the child divided by the height of the Form. Specifies the constant
offset between the top side of the child and the object to which it is
attached. The relationship established remains, regardless of any
resizing operations that occur. When this resource is explicitly set,
the value of XmNverticalSpacing is ignored. This resource is used to
determine the position of the top side of the child when the child's
XmNtopAttachment is set to XmATTACH_POSITION. In this case the posi‐
tion of the top side of the child is relative to the top side of the
Form and is a fraction of the height of the Form. This fraction is the
value of the child's XmNtopPosition resource divided by the value of
the Form's XmNfractionBase. For example, if the child's XmNtopPosition
is 50, the Form's XmNfractionBase is 100, and the Form's height is 200,
the position of the top side of the child is 100. Specifies the widget
or gadget to which the top side of the child is attached. This
resource is used if XmNtopAttachment is set to either XmATTACH_WIDGET
or XmATTACH_OPPOSITE_WIDGET.
A string-to-widget resource converter is automatically installed for
use with this resource. With this converter, the widget that is to be
the value of the resource must exist at the time the widget that has
the resource is created.
Inherited Resources
Form 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 Widget NULL SG
XmNdefaultButton XmCWidget Widget 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 0 CSG
XmNmarginWidth XmCMarginWidth Dimension 0 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
XmNinitialFocus XmCInitialFocus Widget dynamic CSG
XmNnavigationType XmCNavigationType XmNavigationType XmTAB_GROUP CSG
XmNshadowThickness XmCShadowThickness Dimension dynamic CSG
XmNstringDirection XmCStringDirection XmStringDirection dynamic CG
XmNtopShadowColor XmCTopShadowColor Pixel dynamic CSG
XmNtopShadowPixmap XmCTopShadowPixmap Pixmap dynamic CSG
XmNtraversalOn XmCTraversalOn Boolean True CSG
XmNunitType XmCUnitType unsigned char dynamic CSG
XmNuserData XmCUserData XtPointer NULL CSG
Composite Resource Set
Name Class Type Default Access
───────────────────────────────────────────────────────────────────────
XmNchildren XmCReadOnly WidgetList NULL G
XmNinsertPosition XmCInsertPosition XtOrderProc NULL CSG
XmNnumChildren XmCReadOnly Cardinal 0 G
Core Resource Set
Name Class Type Default Access
───────────────────────────────────────────────────────────────────────────────────────────────────────────────
XmNaccelerators XmCAccelerators XtAccelerators dynamic N/A
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
XmNinitialResourcesPersistent XmCInitialResourcesPersistent Boolean True C
XmNmappedWhenManaged XmCMappedWhenManaged Boolean True CSG
XmNscreen XmCScreen Screen * dynamic CG
XmNsensitive XmCSensitive Boolean True CSG
XmNtranslations XmCTranslations XtTranslations dynamic CSG
XmNwidth XmCWidth Dimension dynamic CSG
XmNx XmCPosition Position 0 CSG
XmNy XmCPosition Position 0 CSG
Translations
XmForm inherits translations from XmBulletinBoard.
RELATED INFORMATIONComposite(3X), Constraint(3X), Core(3X), XmBulletinBoard(3X), XmCreate‐
Form, XmCreateFormDialog(3X), and XmManager(3X).
XmForm(3X)
