diff options
Diffstat (limited to 'libXaw/specs/Form.xml')
| -rw-r--r-- | libXaw/specs/Form.xml | 531 |
1 files changed, 531 insertions, 0 deletions
diff --git a/libXaw/specs/Form.xml b/libXaw/specs/Form.xml new file mode 100644 index 000000000..13cc36a5a --- /dev/null +++ b/libXaw/specs/Form.xml @@ -0,0 +1,531 @@ +<sect1 id="Form_Widget"> +<title>Form Widget</title> +<para> +<!-- .LP --> +<!-- .XS --> +<!-- Form Widget --> +<!-- .XE --> +<!-- .IN "Form widget" "" "@DEF@" --> +<literallayout class="monospaced"> +<!-- .TA 2.0i --> +<!-- .ta 2.0i --> +<!-- .sp --> +Application Header file <X11/Xaw/Form.h> +<!-- .IN "Form.h" "" --> +Class Header file <X11/Xaw/FormP.h> +<!-- .IN "FormP.h" "" --> +Class formWidgetClass +<!-- .IN "formWidgetClass" "" --> +Class Name Form +<!-- .IN "Form widget" "class name" --> +Superclass Constraint +<!-- .sp --> +</literallayout> +</para> +<para> +<!-- .LP --> +The Form widget can contain an arbitrary number of children or +subwidgets. The Form provides geometry management for its children, +which allows individual control of the position of each child. Any +combination of children can be added to a Form. The initial positions +of the children may be computed relative to the positions of previously +created children. When the Form is resized, it computes new positions and +sizes for its children. This computation is based upon information +provided when a child is added to the Form. +</para> +<para> +<!-- .LP --> +The default width of the Form is the minimum width needed to +enclose the children after computing their initial layout, with a +margin of <function>defaultDistance</function> +at the right and bottom edges. If a width and height is assigned +to the Form that is too small for the layout, the children will +be clipped by the right and bottom edges of the Form. +</para> +<sect2 id="form_resources"> +<title>Resources</title> +<para> +<!-- .LP --> +When creating a Form widget instance, the following resources are +retrieved from the argument list or from the resource database: +</para> +<para> +<!-- .LP --> +<!-- .IN "Form widget" "resources" --> +<informaltable> + <tgroup cols='5' align='center'> + <colspec colname='c1'/> + <colspec colname='c2'/> + <colspec colname='c3'/> + <colspec colname='c4'/> + <colspec colname='c5'/> + <thead> + <row> + <entry>Name</entry> + <entry>Class</entry> + <entry>Type</entry> + <entry>Notes</entry> + <entry>Default Value</entry> + </row> + </thead> + <tbody> + <row> + <entry>accelerators</entry> + <entry>Accelerators</entry> + <entry>AcceleratorTable</entry> + <entry></entry> + <entry>NULL</entry> + </row> + <row> + <entry>ancestorSensitive</entry> + <entry>AncestorSensitive</entry> + <entry>Boolean</entry> + <entry>D</entry> + <entry>True</entry> + </row> + <row> + <entry>background</entry> + <entry>Background</entry> + <entry>Pixel</entry> + <entry></entry> + <entry>XtDefaultBackground</entry> + </row> + <row> + <entry>backgroundPixmap</entry> + <entry>Pixmap</entry> + <entry>Pixmap</entry> + <entry></entry> + <entry>XtUnspecifiedPixmap</entry> + </row> + <row> + <entry>borderColor</entry> + <entry>BorderColor</entry> + <entry>Pixel</entry> + <entry></entry> + <entry>XtDefaultForeground</entry> + </row> + <row> + <entry>borderPixmap</entry> + <entry>Pixmap</entry> + <entry>Pixmap</entry> + <entry></entry> + <entry>XtUnspecifiedPixmap</entry> + </row> + <row> + <entry>borderWidth</entry> + <entry>BorderWidth</entry> + <entry>Dimension</entry> + <entry></entry> + <entry>1</entry> + </row> + <row> + <entry>children</entry> + <entry>ReadOnly</entry> + <entry>WidgetList</entry> + <entry>R</entry> + <entry>NULL</entry> + </row> + <row> + <entry>colormap</entry> + <entry>Colormap</entry> + <entry>Colormap</entry> + <entry></entry> + <entry>Parent's Colormap</entry> + </row> + <row> + <entry>defaultDistance</entry> + <entry>Thickness</entry> + <entry>int</entry> + <entry></entry> + <entry>4</entry> + </row> + <row> + <entry>depth</entry> + <entry>Depth</entry> + <entry>int</entry> + <entry>C</entry> + <entry>Parent's Depth</entry> + </row> + <row> + <entry>destroyCallback</entry> + <entry>Callback</entry> + <entry>XtCallbackList</entry> + <entry></entry> + <entry>NULL</entry> + </row> + <row> + <entry>height</entry> + <entry>Height</entry> + <entry>Dimension</entry> + <entry>A</entry> + <entry>Enough space to contain all children</entry> + </row> + <row> + <entry>mappedWhenManaged</entry> + <entry>MappedWhenManaged</entry> + <entry>Boolean</entry> + <entry></entry> + <entry>True</entry> + </row> + <row> + <entry>numChildren</entry> + <entry>ReadOnly</entry> + <entry>Cardinal</entry> + <entry>R</entry> + <entry>0</entry> + </row> + <row> + <entry>screen</entry> + <entry>Screen</entry> + <entry>Screen</entry> + <entry>R</entry> + <entry>Parent's Screen</entry> + </row> + <row> + <entry>sensitive</entry> + <entry>Sensitive</entry> + <entry>Boolean</entry> + <entry></entry> + <entry>True</entry> + </row> + <row> + <entry>translations</entry> + <entry>Translations</entry> + <entry>TranslationTable</entry> + <entry></entry> + <entry>NULL</entry> + </row> + <row> + <entry>width</entry> + <entry>Width</entry> + <entry>Dimension</entry> + <entry>A</entry> + <entry>Enough space to contain all children</entry> + </row> + <row> + <entry>x</entry> + <entry>Position</entry> + <entry>Position</entry> + <entry></entry> + <entry>0</entry> + </row> + <row> + <entry>y</entry> + <entry>Position</entry> + <entry>Position</entry> + <entry></entry> + <entry>0</entry> + </row> + <row> + <entry>_</entry> + </row> + </tbody> + </tgroup> +</informaltable> +<!-- .Ac --> +<!-- .As --> +<!-- .Bg --> +<!-- .Gp --> +<!-- .Bc --> +<!-- .Bp --> +<!-- .Bw --> +<!-- .Ch --> +<!-- .Cm --> +<!-- .Dd Bold --> +<!-- .Dp --> +<!-- .Dc --> +<!-- .Hw --> +<!-- .Mm --> +<!-- .Nc --> +<!-- .Sc --> +<!-- .Se --> +<!-- .Tr --> +<!-- .Xy --> +</para> +</sect2> +<sect2 id="form_constraint_resources"> +<title>Constraint Resources</title> +<para> +<!-- .LP --> +<!-- .IN "Form widget" "constraint resources" --> +Each child of the Form widget may request special layout resources +be applied to it. These <emphasis remap='I'>constraint</emphasis> resources allow the Form +widget's children to specify individual layout requirements. +</para> +<para> +<!-- .LP --> +</para> +<para> +<!-- .LP --> +<informaltable> + <tgroup cols='5' align='center'> + <colspec colname='c1'/> + <colspec colname='c2'/> + <colspec colname='c3'/> + <colspec colname='c4'/> + <colspec colname='c5'/> + <thead> + <row> + <entry>Name</entry> + <entry>Class</entry> + <entry>Type</entry> + <entry>Notes</entry> + <entry>Default Value</entry> + </row> + </thead> + <tbody> + <row> + <entry>bottom</entry> + <entry>Edge</entry> + <entry>XawEdgeType</entry> + <entry></entry> + <entry>XawRubber</entry> + </row> + <row> + <entry>fromHoriz</entry> + <entry>Widget</entry> + <entry>Widget</entry> + <entry></entry> + <entry>NULL (left edge of Form)</entry> + </row> + <row> + <entry>fromVert</entry> + <entry>Widget</entry> + <entry>Widget </entry> + <entry></entry> + <entry>NULL (top edge of Form)</entry> + </row> + <row> + <entry>horizDistance</entry> + <entry>Thickness</entry> + <entry>int</entry> + <entry></entry> + <entry><function>defaultDistance</function> resource</entry> + </row> + <row> + <entry>left</entry> + <entry>Edge</entry> + <entry>XawEdgeType</entry> + <entry></entry> + <entry>XawRubber</entry> + </row> + <row> + <entry>resizable</entry> + <entry>Boolean</entry> + <entry>Boolean</entry> + <entry></entry> + <entry>FALSE</entry> + </row> + <row> + <entry>right</entry> + <entry>Edge</entry> + <entry>XawEdgeType</entry> + <entry></entry> + <entry>XawRubber</entry> + </row> + <row> + <entry>top</entry> + <entry>Edge</entry> + <entry>XawEdgeType</entry> + <entry></entry> + <entry>XawRubber</entry> + </row> + <row> + <entry>vertDistance</entry> + <entry>Thickness</entry> + <entry>int</entry> + <entry></entry> + <entry><function>defaultDistance</function> resource</entry> + </row> + </tbody> + </tgroup> +</informaltable> +<!-- .Bt Bold --> +<!-- .Fh Bold --> +<!-- .Hd Bold --> +<!-- .Rl Bold --> +</para> +<literallayout class="monospaced"> +bottom +left +right +top What to do with this edge of the child when + the parent is resized. This resource may be + any edgeType. See Layout Semantics for + details. + +fromHoriz +fromVert Which widget this child should be placed + underneath (or to the right of). If a value + of NULL is specified then this widget will be + positioned relative to the edge of the par- + ent. + +horizDistance +vertDistance The amount of space, in pixels, between this + child and its left or upper neighbor. + +resizable If this resource is False then the parent + widget will ignore all geometry request made + by this child. The parent may still resize + this child itself, however. +</literallayout> +<!-- .Bt --> +</sect2> +<sect2 id="form_layout_semantics"> +<title>Layout Semantics</title> +<para> +The Form widget uses two different sets of layout semantics. +One is used when initially laying out the children. The +other is used when the Form is resized. +</para> +<para> +The first layout method uses the <function>fromVert</function> +and <function>fromHoriz</function> +resources to place the children of the Form. A single pass +is made through the Form widget's children in the order that +they were created. Each child is then placed in the Form +widget below or to the right of the widget specified by the +<function>fromVert</function> and <function>fromHoriz</function> +resources. The distance the new +child is placed from its left or upper neighbor is deter- +mined by the <function>horizDistance</function> and +<function>vertDistance</function> resources. This +implies some things about how the order of creation affects +the possible placement of the children. The Form widget +registers a string to widget converter which does not post- +pone conversion and does not cache conversion results. +</para> +<para> +The second layout method is used when the Form is resized. +It does not matter what causes this resize, and it is possi- +ble for a resize to happen before the widget becomes visible +(due to constraints imposed by the parent of the Form). +This layout method uses the <function>bottom</function>, +<function>top</function>, <function>left</function>, and +<function>right</function> +resources. These resources are used to determine what will +happen to each edge of the child when the Form is resized. +If a value of <function>XawChain</function> +<<emphasis remap='I'>something</emphasis>> is specified, the the edge +of the child will remain a fixed distance from the +<emphasis remap='I'>chain</emphasis> +edge of the Form. For example if <function>XawChainLeft</function> is specified +for the <function>right</function> resource of a child then the right edge of +that child will remain a fixed distance from the left edge +of the Form widget. If a value of <function>XawRubber</function> is specified, +that edge will grow by the same percentage that the Form +grew. For instance if the Form grows by 50% the left edge +of the child (if specified as <function>XawRubber</function> will be 50% farther +from the left edge of the Form). One must be very careful +when specifying these resources, for when they are specified +incorrectly children may overlap or completely occlude other +children when the Form widget is resized. +<!-- .LP --> +<!-- .Lt Form --> +</para> +<para> +<!-- .LP --> +<informaltable> + <tgroup cols='3' align='center'> + <colspec colname='c1'/> + <colspec colname='c2'/> + <colspec colname='c3'/> + <thead> + <row> + <entry>Edge Type</entry> + <entry>Resource Name</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>XawChainBottom</entry> + <entry>ChainBottom</entry> + <entry>Edge remains a fixed distance from bottom of Form</entry> + </row> + <row> + <entry>XawChainLeft</entry> + <entry>ChainLeft</entry> + <entry>Edge remains a fixed distance from left of Form</entry> + </row> + <row> + <entry>XawChainRight</entry> + <entry>ChainRight</entry> + <entry>Edge remains a fixed distance from right of Form</entry> + </row> + <row> + <entry>XawChainTop</entry> + <entry>ChainTop</entry> + <entry>Edge remains a fixed distance from top of Form</entry> + </row> + <row> + <entry>XawRubber</entry> + <entry>Rubber</entry> + <entry>Edges will move a proportional distance</entry> + </row> + </tbody> + </tgroup> +</informaltable> +</para> +<sect3 id="form_example"> +<title>Example</title> +<para> +<!-- .LP --> +If you wish to force the Form to never resize one or more of its +children, then set <function>left</function> and <function>right</function> to <function>XawChainLeft</function> and +<function>top</function> and <function>bottom</function> to <function>XawChainTop</function>. This will cause the +child to remain a fixed distance from the top and left edges of the +Form, and never to resize. +</para> +</sect3> +</sect2> +<sect2 id="form_convenience_routines"> +<title>Convenience Routines</title> +<para> +<!-- .LP --> +To force or defer a re-layout of the Form, use +<!-- .PN XawFormDoLayout . --> +<!-- .IN "Form widget" "re-layout" --> +<!-- .IN "XawFormDoLayout" "" "@DEF@" --> +<funcsynopsis> +<funcprototype> + <funcdef>void<function> XawFormDoLayout</function></funcdef> + <paramdef>Widget<parameter> w</parameter></paramdef> + <paramdef>Boolean<parameter> do_layout</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the Form widget. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>do_layout</emphasis> + </term> + <listitem> + <para> +Specifies whether the layout of the Form widget is enabled (<function>True</function>) +or disabled (<function>False</function>). + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +When making several changes to the children of a Form widget +after the Form has been realized, it is a good idea to disable +relayout until after all changes have been made. + +</para> +</sect2> +</sect1> |