1407 lines
43 KiB
XML
1407 lines
43 KiB
XML
<chapter id='Composite_Widgets_and_Their_Children'>
|
|
<title>Composite Widgets and Their Children</title>
|
|
<para>
|
|
Composite widgets (widgets whose class is a subclass of
|
|
<function>compositeWidgetClass</function>)
|
|
can have an arbitrary number of children.
|
|
Consequently, they are responsible for much more than primitive widgets.
|
|
Their responsibilities (either implemented directly by the widget class
|
|
or indirectly by Intrinsics functions) include:
|
|
</para>
|
|
<itemizedlist spacing='compact'>
|
|
<listitem>
|
|
<para>
|
|
Overall management of children from creation to destruction.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Destruction of descendants when the composite widget is destroyed.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Physical arrangement (geometry management) of a displayable subset of
|
|
children (that is, the managed children).
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Mapping and unmapping of a subset of the managed children.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
Overall management is handled by the generic procedures
|
|
<xref linkend='XtCreateWidget' xrefstyle='select: title'/>
|
|
and
|
|
<xref linkend='XtDestroyWidget' xrefstyle='select: title'/>.
|
|
<xref linkend='XtCreateWidget' xrefstyle='select: title'/>
|
|
adds children to their parent by calling the parent's insert_child
|
|
procedure.
|
|
<xref linkend='XtDestroyWidget' xrefstyle='select: title'/>
|
|
removes children from their parent by calling the parent's delete_child
|
|
procedure and ensures that all children of a destroyed composite widget
|
|
also get destroyed.
|
|
</para>
|
|
|
|
<para>
|
|
Only a subset of the total number of children is actually managed by
|
|
the geometry manager and hence possibly visible.
|
|
For example, a composite editor widget
|
|
supporting multiple editing buffers might allocate one child
|
|
widget for each file buffer,
|
|
but it might display only a small number of the existing buffers.
|
|
Widgets that are in this displayable subset are called managed widgets
|
|
and enter into geometry manager calculations.
|
|
The other children are called unmanaged widgets
|
|
and, by definition, are not mapped by the Intrinsics.
|
|
</para>
|
|
|
|
<para>
|
|
Children are added to and removed from their parent's managed set by using
|
|
<xref linkend='XtManageChild' xrefstyle='select: title'/>,
|
|
<xref linkend='XtManageChildren' xrefstyle='select: title'/>,
|
|
<xref linkend='XtUnmanageChild' xrefstyle='select: title'/>,
|
|
<xref linkend='XtUnmanageChildren' xrefstyle='select: title'/>,
|
|
and
|
|
<xref linkend='XtChangeManagedSet' xrefstyle='select: title'/>,
|
|
which notify the parent to recalculate the physical layout of its children
|
|
by calling the parent's change_managed procedure.
|
|
The
|
|
<xref linkend='XtCreateManagedWidget' xrefstyle='select: title'/>
|
|
convenience function calls
|
|
<xref linkend='XtCreateWidget' xrefstyle='select: title'/>
|
|
and
|
|
<xref linkend='XtManageChild' xrefstyle='select: title'/>
|
|
on the result.
|
|
</para>
|
|
|
|
<para>
|
|
Most managed children are mapped,
|
|
but some widgets can be in a state where they take up physical space
|
|
but do not show anything.
|
|
Managed widgets are not mapped automatically
|
|
if their <emphasis remap='I'>map_when_managed</emphasis> field is
|
|
<function>False</function>.
|
|
The default is
|
|
<function>True</function>
|
|
and is changed by using
|
|
<xref linkend='XtSetMappedWhenManaged' xrefstyle='select: title'/>.
|
|
</para>
|
|
|
|
<para>
|
|
Each composite widget class declares a geometry manager,
|
|
which is responsible for figuring out where the managed children
|
|
should appear within the composite widget's window.
|
|
Geometry management techniques fall into four classes:
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>Fixed boxes</term>
|
|
<listitem>
|
|
<para>
|
|
Fixed boxes have a fixed number of children created by the parent.
|
|
All these children are managed,
|
|
and none ever makes geometry manager requests.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Homogeneous boxes</term>
|
|
<listitem>
|
|
<para>
|
|
Homogeneous boxes treat all children equally and apply the same geometry
|
|
constraints to each child.
|
|
Many clients insert and delete widgets freely.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Heterogeneous boxes</term>
|
|
<listitem>
|
|
<para>
|
|
Heterogeneous boxes have a specific location where each child is placed.
|
|
This location usually is not specified in pixels,
|
|
because the window may be resized, but is expressed rather
|
|
in terms of the relationship between a child
|
|
and the parent or between the child and other specific children.
|
|
The class of heterogeneous boxes is usually a subclass of
|
|
Constraint.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Shell boxes</term>
|
|
<listitem>
|
|
<para>
|
|
Shell boxes typically have only one child,
|
|
and the child's size is usually
|
|
exactly the size of the shell.
|
|
The geometry manager must communicate with the window manager, if it exists,
|
|
and the box must also accept
|
|
<function>ConfigureNotify</function>
|
|
events when the window size is changed by the window manager.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
<sect1 id="Addition_of_Children_to_a_Composite_Widget_The_insert_child_Procedure">
|
|
<title>Addition of Children to a Composite Widget: The insert_child Procedure</title>
|
|
<para>
|
|
To add a child to
|
|
the parent's list of children, the
|
|
<xref linkend='XtCreateWidget' xrefstyle='select: title'/>
|
|
function calls the parent's class routine insert_child.
|
|
The insert_child procedure pointer in a composite widget is of type
|
|
<xref linkend='XtWidgetProc' xrefstyle='select: title'/>.
|
|
</para>
|
|
|
|
<funcsynopsis id='XtWidgetProc_2'>
|
|
<funcprototype>
|
|
<funcdef>typedef void <function>(*XtWidgetProc)</function></funcdef>
|
|
<paramdef>Widget <parameter>w</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>w</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Passes the newly created child.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<para>
|
|
Most composite widgets inherit their superclass's operation.
|
|
The insert_child routine in
|
|
<function>CompositeWidgetClass calls the insert_position procedure</function>
|
|
and inserts the child at the specified position
|
|
in the <emphasis remap='I'>children</emphasis> list, expanding it if necessary.
|
|
</para>
|
|
|
|
<para>
|
|
Some composite widgets define their own insert_child routine
|
|
so that they can order their children in some convenient way,
|
|
create companion controller widgets for a new widget,
|
|
or limit the number or class of their child widgets.
|
|
A composite widget class that wishes
|
|
to allow nonwidget children (see <xref linkend='Nonwidget_Objects' />) must specify a
|
|
<function>CompositeClassExtension</function>
|
|
extension record as described
|
|
in <xref linkend='CompositeClassPart_Structure' />
|
|
and set the <emphasis remap='I'>accepts_objects</emphasis> field in this record to
|
|
<function>True</function>.
|
|
If the
|
|
<function>CompositeClassExtension</function>
|
|
record is not specified or the
|
|
<emphasis remap='I'>accepts_objects</emphasis> field is
|
|
<function>False</function>,
|
|
the composite widget can assume that all its children are of a subclass of Core
|
|
without an explicit subclass test in the insert_child procedure.
|
|
</para>
|
|
|
|
<para>
|
|
If there is not enough room to insert a new child in the <emphasis remap='I'>children</emphasis> array
|
|
(that is, <emphasis remap='I'>num_children</emphasis> is equal to <emphasis remap='I'>num_slots</emphasis>),
|
|
the insert_child procedure must first reallocate the array
|
|
and update <emphasis remap='I'>num_slots</emphasis>.
|
|
The insert_child procedure then places the child at the appropriate position
|
|
in the array and increments the <emphasis remap='I'>num_children</emphasis> field.
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 id="Insertion_Order_of_Children_The_insert_position_Procedure">
|
|
<title>Insertion Order of Children: The insert_position Procedure</title>
|
|
<para>
|
|
Instances of composite widgets sometimes need to specify more about the order in which
|
|
their children are kept.
|
|
For example,
|
|
an application may want a set of command buttons in some logical order
|
|
grouped by function,
|
|
and it may want buttons that represent file names to be kept
|
|
in alphabetical order without constraining the order in which the
|
|
buttons are created.
|
|
</para>
|
|
|
|
<para>
|
|
An application controls the presentation order of a set of children by
|
|
supplying an
|
|
XtNinsertPosition
|
|
resource.
|
|
The insert_position procedure pointer in a composite widget instance is of type
|
|
<xref linkend='XtOrderProc' xrefstyle='select: title'/>.
|
|
</para>
|
|
|
|
<funcsynopsis id='XtOrderProc'>
|
|
<funcprototype>
|
|
<funcdef>typedef Cardinal <function>(*XtOrderProc)</function></funcdef>
|
|
|
|
<paramdef>Widget <parameter>w</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>w</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Passes the newly created widget.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<para>
|
|
Composite widgets that allow clients to order their children (usually
|
|
homogeneous boxes) can call their widget instance's insert_position
|
|
procedure from the class's insert_child procedure to determine where a new
|
|
child should go in its <emphasis remap='I'>children</emphasis> array.
|
|
Thus, a client using a composite class can apply different sorting criteria
|
|
to widget instances of the class, passing in a different insert_position
|
|
procedure resource when it creates each composite widget instance.
|
|
</para>
|
|
|
|
<para>
|
|
The return value of the insert_position procedure
|
|
indicates how many children should go before the widget.
|
|
Returning zero indicates that the widget should go before all other children,
|
|
and returning <emphasis remap='I'>num_children</emphasis> indicates that it should go after all other children.
|
|
The default insert_position function returns <emphasis remap='I'>num_children</emphasis>
|
|
and can be overridden by a specific composite widget's resource list
|
|
or by the argument list provided when the composite widget is created.
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 id="Deletion_of_Children_The_delete_child_Procedure">
|
|
<title>Deletion of Children: The delete_child Procedure</title>
|
|
|
|
<para>
|
|
To remove the child from the parent's <emphasis remap='I'>children</emphasis> list, the
|
|
<xref linkend='XtDestroyWidget' xrefstyle='select: title'/>
|
|
function eventually causes a call to the Composite parent's class delete_child
|
|
procedure.
|
|
The delete_child procedure pointer is of type
|
|
<xref linkend='XtWidgetProc' xrefstyle='select: title'/>.
|
|
</para>
|
|
|
|
<funcsynopsis id='_XtWidgetProc'>
|
|
<funcprototype>
|
|
<funcdef>typedef void <function>(*XtWidgetProc)</function></funcdef>
|
|
<paramdef>Widget <parameter>w</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>w</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Passes the child being deleted.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
|
|
<para>
|
|
Most widgets inherit the delete_child procedure from their superclass.
|
|
Composite widgets that create companion widgets define their own
|
|
delete_child procedure to remove these companion widgets.
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 id="Adding_and_Removing_Children_from_the_Managed_Set">
|
|
<title>Adding and Removing Children from the Managed Set</title>
|
|
<para>
|
|
The Intrinsics provide a set of generic routines to permit the addition of
|
|
widgets to or the removal of widgets from a composite widget's managed set.
|
|
These generic routines eventually call the composite widget's change_managed
|
|
procedure if the procedure pointer is non-NULL.
|
|
The change_managed procedure pointer is of type
|
|
<xref linkend='XtWidgetProc' xrefstyle='select: title'/>.
|
|
The widget argument specifies the composite widget whose managed child
|
|
set has been modified.
|
|
</para>
|
|
|
|
<sect2 id="Managing_Children">
|
|
<title>Managing Children</title>
|
|
<para>
|
|
To add a list of widgets to the geometry-managed (and hence displayable)
|
|
subset of their Composite parent, use
|
|
<xref linkend='XtManageChildren' xrefstyle='select: title'/>.
|
|
</para>
|
|
|
|
<para>typedef Widget *WidgetList;</para>
|
|
|
|
<funcsynopsis id='XtManageChildren'>
|
|
<funcprototype>
|
|
<funcdef>void <function>XtManageChildren</function></funcdef>
|
|
<paramdef>WidgetList <parameter>children</parameter></paramdef>
|
|
<paramdef>Cardinal <parameter>num_children</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>children</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies a list of child widgets. Each child must be of class
|
|
RectObj or any subclass thereof.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>num_children</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the number of children in the list.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<para>
|
|
The
|
|
<xref linkend='XtManageChildren' xrefstyle='select: title'/>
|
|
function performs the following:
|
|
</para>
|
|
<itemizedlist spacing='compact'>
|
|
<listitem>
|
|
<para>
|
|
Issues an error if the children do not all have the same parent or
|
|
if the parent's class is not a subclass of
|
|
<function>compositeWidgetClass</function>.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Returns immediately if the common parent is being destroyed;
|
|
otherwise, for each unique child on the list,
|
|
<xref linkend='XtManageChildren' xrefstyle='select: title'/>
|
|
ignores the child if it already is managed or is being destroyed,
|
|
and marks it if not.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
If the parent is realized and after all children have been marked,
|
|
it makes some of the newly managed children viewable:
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<itemizedlist spacing='compact'>
|
|
<listitem>
|
|
<para>
|
|
Calls the change_managed routine of the widgets' parent.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Calls
|
|
<xref linkend='XtRealizeWidget' xrefstyle='select: title'/>
|
|
on each previously unmanaged child that is unrealized.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Maps each previously unmanaged child that has <emphasis remap='I'>map_when_managed</emphasis>
|
|
<function>True</function>.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
Managing children is independent of the ordering of children and
|
|
independent of creating and deleting children.
|
|
The layout routine of the parent
|
|
should consider children whose <emphasis remap='I'>managed</emphasis> field is
|
|
<function>True</function>
|
|
and should ignore all other children.
|
|
Note that some composite widgets, especially fixed boxes, call
|
|
<xref linkend='XtManageChild' xrefstyle='select: title'/>
|
|
from their insert_child procedure.
|
|
</para>
|
|
|
|
<para>
|
|
If the parent widget is realized,
|
|
its change_managed procedure is called to notify it
|
|
that its set of managed children has changed.
|
|
The parent can reposition and resize any of its children.
|
|
It moves each child as needed by calling
|
|
<xref linkend='XtMoveWidget' xrefstyle='select: title'/>,
|
|
which first updates the <emphasis remap='I'>x</emphasis> and <emphasis remap='I'>y</emphasis> fields and which then calls
|
|
<function>XMoveWindow</function>.
|
|
</para>
|
|
|
|
<para>
|
|
If the composite widget wishes to change the size or border width of any of
|
|
its children, it calls
|
|
<xref linkend='XtResizeWidget' xrefstyle='select: title'/>,
|
|
which first updates the
|
|
<emphasis remap='I'>width</emphasis>, <emphasis remap='I'>height</emphasis>, and <emphasis remap='I'>border_width</emphasis>
|
|
fields and then calls
|
|
<function>XConfigureWindow</function>.
|
|
Simultaneous repositioning and resizing may be done with
|
|
<xref linkend='XtConfigureWidget' xrefstyle='select: title'/>;
|
|
see <xref linkend='Widget_Placement_and_Sizing' />.
|
|
</para>
|
|
|
|
<para>
|
|
To add a single child to its parent widget's set of managed children, use
|
|
<xref linkend='XtManageChild' xrefstyle='select: title'/>.
|
|
</para>
|
|
|
|
<funcsynopsis id='XtManageChild'>
|
|
<funcprototype>
|
|
<funcdef>void <function>XtManageChild</function></funcdef>
|
|
<paramdef>Widget <parameter>child</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>child</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the child. Must be of class RectObj or any subclass thereof.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<para>
|
|
The
|
|
<xref linkend='XtManageChild' xrefstyle='select: title'/>
|
|
function constructs a
|
|
<function>WidgetList</function>
|
|
of length 1 and calls
|
|
<xref linkend='XtManageChildren' xrefstyle='select: title'/>.
|
|
</para>
|
|
|
|
<para>
|
|
To create and manage a child widget in a single procedure, use
|
|
<xref linkend='XtCreateManagedWidget' xrefstyle='select: title'/>
|
|
or
|
|
<xref linkend='XtVaCreateManagedWidget' xrefstyle='select: title'/>.
|
|
</para>
|
|
|
|
<funcsynopsis id='XtCreateManagedWidget'>
|
|
<funcprototype>
|
|
<funcdef>Widget <function>XtCreateManagedWidget</function></funcdef>
|
|
<paramdef>String <parameter>name</parameter></paramdef>
|
|
<paramdef>WidgetClass <parameter>widget_class</parameter></paramdef>
|
|
<paramdef>Widget <parameter>parent</parameter></paramdef>
|
|
<paramdef>ArgList <parameter>args</parameter></paramdef>
|
|
<paramdef>Cardinal <parameter>num_args</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>name</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the resource instance name for the created widget.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>widget_class</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the widget class pointer for the created widget. (rC
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>parent</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the parent widget. Must be of class Composite or any
|
|
subclass thereof.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>args</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the argument list to override any other resource specifications.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>num_args</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the number of entries in the argument list.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<para>
|
|
The
|
|
<xref linkend='XtCreateManagedWidget' xrefstyle='select: title'/>
|
|
function is a convenience routine that calls
|
|
<xref linkend='XtCreateWidget' xrefstyle='select: title'/>
|
|
and
|
|
<xref linkend='XtManageChild' xrefstyle='select: title'/>.
|
|
</para>
|
|
|
|
<funcsynopsis id='XtVaCreateManagedWidget'>
|
|
<funcprototype>
|
|
<funcdef>Widget <function>XtVaCreateManagedWidget</function></funcdef>
|
|
<paramdef>String <parameter>name</parameter></paramdef>
|
|
<paramdef>WidgetClass <parameter>widget_class</parameter></paramdef>
|
|
<paramdef>Widget <parameter>parent</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>name</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the resource instance name for the created widget.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>widget_class</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the widget class pointer for the created widget. (rC
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>parent</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the parent widget. Must be of class Composite or any
|
|
subclass thereof.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
...
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the variable argument list to override any other
|
|
resource specifications.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<para>
|
|
<xref linkend='XtVaCreateManagedWidget' xrefstyle='select: title'/>
|
|
is identical in function to
|
|
<xref linkend='XtCreateManagedWidget' xrefstyle='select: title'/>
|
|
with the <emphasis remap='I'>args</emphasis> and <emphasis remap='I'>num_args</emphasis> parameters replaced
|
|
by a varargs list, as described in Section 2.5.1.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="Unmanaging_Children">
|
|
<title>Unmanaging Children</title>
|
|
<para>
|
|
To remove a list of children from a parent widget's managed list, use
|
|
<xref linkend='XtUnmanageChildren' xrefstyle='select: title'/>.
|
|
</para>
|
|
|
|
<funcsynopsis id='XtUnmanageChildren'>
|
|
<funcprototype>
|
|
<funcdef>void <function>XtUnmanageChildren</function></funcdef>
|
|
<paramdef>WidgetList <parameter>children</parameter></paramdef>
|
|
<paramdef>Cardinal <parameter>num_children</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>children</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies a list of child widgets. Each child must be of class
|
|
RectObj or any subclass thereof.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>num_children</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the number of children.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<para>
|
|
The
|
|
<xref linkend='XtUnmanageChildren' xrefstyle='select: title'/>
|
|
function performs the following:
|
|
</para>
|
|
<itemizedlist spacing='compact'>
|
|
<listitem>
|
|
<para>
|
|
Returns immediately if the common parent is being destroyed.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Issues an error if the children do not all have the same parent
|
|
or if the parent is not a subclass of
|
|
<function>compositeWidgetClass</function>.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
For each unique child on the list,
|
|
<xref linkend='XtUnmanageChildren' xrefstyle='select: title'/>
|
|
ignores the child if it is unmanaged; otherwise it performs the following:
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<itemizedlist spacing='compact'>
|
|
<listitem>
|
|
<para>
|
|
Marks the child as unmanaged.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
If the child is realized and the <emphasis remap='I'>map_when_managed</emphasis> field is
|
|
<function>True</function>,
|
|
it is unmapped.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
If the parent is realized and if any children have become unmanaged,
|
|
calls the change_managed routine of the widgets' parent.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
<xref linkend='XtUnmanageChildren' xrefstyle='select: title'/>
|
|
does not destroy the child widgets.
|
|
Removing widgets from a parent's managed set is often a temporary banishment,
|
|
and some time later the client may manage the children again.
|
|
To destroy widgets entirely,
|
|
<xref linkend='XtDestroyWidget' xrefstyle='select: title'/>
|
|
should be called instead;
|
|
see <xref linkend='Exiting_from_an_Application' />.
|
|
</para>
|
|
|
|
<para>
|
|
To remove a single child from its parent widget's managed set, use
|
|
<xref linkend='XtUnmanageChild' xrefstyle='select: title'/>.
|
|
</para>
|
|
|
|
<funcsynopsis id='XtUnmanageChild'>
|
|
<funcprototype>
|
|
<funcdef>void <function>XtUnmanageChild</function></funcdef>
|
|
<paramdef>Widget <parameter>child</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>child</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the child. Must be of class RectObj or any subclass thereof.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<para>
|
|
The
|
|
<xref linkend='XtUnmanageChild' xrefstyle='select: title'/>
|
|
function constructs a widget list
|
|
of length 1 and calls
|
|
<xref linkend='XtUnmanageChildren' xrefstyle='select: title'/>.
|
|
</para>
|
|
|
|
<para>
|
|
These functions are low-level routines that are used by generic
|
|
composite widget building routines.
|
|
In addition, composite widgets can provide widget-specific,
|
|
high-level convenience procedures.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="Bundling_Changes_to_the_Managed_Set">
|
|
<title>Bundling Changes to the Managed Set</title>
|
|
<para>
|
|
A client may simultaneously unmanage and manage children
|
|
with a single call to the Intrinsics. In this same call the
|
|
client may provide a callback procedure that can modify the
|
|
geometries of one or more children. The composite widget class
|
|
defines whether this single client call results in separate invocations
|
|
of the change_managed method, one to unmanage and the other to
|
|
manage, or in just a single invocation.
|
|
</para>
|
|
|
|
<para>
|
|
To simultaneously remove from and add to the geometry-managed
|
|
set of children of a composite parent, use
|
|
<xref linkend='XtChangeManagedSet' xrefstyle='select: title'/>.
|
|
</para>
|
|
|
|
<funcsynopsis id='XtChangeManagedSet'>
|
|
<funcprototype>
|
|
<funcdef>void <function>XtChangeManagedSet</function></funcdef>
|
|
<paramdef>WidgetList <parameter>unmanage_children</parameter></paramdef>
|
|
<paramdef>Cardinal <parameter>num_unmanage_children</parameter></paramdef>
|
|
<paramdef>XtDoChangeProc <parameter>do_change_proc</parameter></paramdef>
|
|
<paramdef>XtPointer <parameter>client_data</parameter></paramdef>
|
|
<paramdef>WidgetList <parameter>manage_children</parameter></paramdef>
|
|
<paramdef>Cardinal <parameter>num_manage_children</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>unmanage_children</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the list of widget children to initially remove from the managed set.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>num_unmanage_children</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the number of entries in the <emphasis remap='I'>unmanage_children</emphasis> list.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>do_change_proc</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies a procedure to invoke between unmanaging
|
|
and managing the children, or NULL.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>client_data</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies client data to be passed to the do_change_proc.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>manage_children</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the list of widget children to finally add to the managed set.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>num_manage_children</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the number of entries in the <emphasis remap='I'>manage_children</emphasis> list.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<para>
|
|
The
|
|
<xref linkend='XtChangeManagedSet' xrefstyle='select: title'/>
|
|
function performs the following:
|
|
</para>
|
|
<itemizedlist spacing='compact'>
|
|
<listitem>
|
|
<para>
|
|
Returns immediately if <emphasis remap='I'>num_unmanage_children</emphasis> and
|
|
<emphasis remap='I'>num_manage_children</emphasis> are both 0.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Issues a warning and returns if the widgets specified in the
|
|
<emphasis remap='I'>manage_children</emphasis> and
|
|
the <emphasis remap='I'>unmanage_children</emphasis> lists do not all have the same parent or if
|
|
that parent is not a subclass of
|
|
<function>compositeWidgetClass</function>.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Returns immediately if the common parent is being destroyed.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
If <emphasis remap='I'>do_change_proc</emphasis> is not NULL and the parent's
|
|
<function>CompositeClassExtension</function>
|
|
<emphasis remap='I'>allows_change_managed_set</emphasis> field is
|
|
<function>False</function>,
|
|
then
|
|
<xref linkend='XtChangeManagedSet' xrefstyle='select: title'/>
|
|
performs the following:
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<itemizedlist spacing='compact'>
|
|
<listitem>
|
|
<para>
|
|
Calls
|
|
<xref linkend='XtUnmanageChildren' xrefstyle='select: title'/>
|
|
(<emphasis remap='I'>unmanage_children</emphasis>, <emphasis remap='I'>num_unmanage_children</emphasis>).
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Calls the <emphasis remap='I'>do_change_proc</emphasis>.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Calls
|
|
<xref linkend='XtManageChildren' xrefstyle='select: title'/>
|
|
(<emphasis remap='I'>manage_children</emphasis>, <emphasis remap='I'>num_manage_children</emphasis>).
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Otherwise, the following is performed:
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<itemizedlist spacing='compact'>
|
|
<listitem>
|
|
<para>
|
|
For each child on the <emphasis remap='I'>unmanage_children</emphasis> list; if the child is
|
|
already unmanaged it is ignored, otherwise it is marked as unmanaged,
|
|
and if it is realized and its <emphasis remap='I'>map_when_managed</emphasis> field is
|
|
<function>True</function>,
|
|
it is unmapped.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
If <emphasis remap='I'>do_change_proc</emphasis> is non-NULL, the procedure is invoked.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
For each child on the <emphasis remap='I'>manage_children</emphasis> list; if the child is already
|
|
managed or is being destroyed, it is ignored; otherwise it is
|
|
marked as managed.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
If the parent is realized and after all children have been marked,
|
|
the change_managed method of the parent is invoked, and subsequently
|
|
some of the newly managed children are made viewable by calling
|
|
<xref linkend='XtRealizeWidget' xrefstyle='select: title'/>
|
|
on each previously unmanaged child that is unrealized and
|
|
mapping each previously unmanaged child that has <emphasis remap='I'>map_when_managed</emphasis>
|
|
<function>True</function>.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
If no
|
|
<function>CompositeClassExtension</function>
|
|
record is found in the parent's composite class part <emphasis remap='I'>extension</emphasis> field
|
|
with record type
|
|
<emphasis role='strong'>NULLQUARK</emphasis>
|
|
and version greater than 1, and if
|
|
<function>XtInheritChangeManaged</function>
|
|
was specified in the parent's class record during class initialization,
|
|
the value of the <emphasis remap='I'>allows_change_managed_set</emphasis>
|
|
field is inherited from the superclass. The value inherited from
|
|
<function>compositeWidgetClass</function>
|
|
for the <emphasis remap='I'>allows_change_managed_set</emphasis> field is
|
|
<function>False</function>.
|
|
</para>
|
|
|
|
<para>
|
|
It is not an error to include a child in both the <emphasis remap='I'>unmanage_children</emphasis>
|
|
and the <emphasis remap='I'>manage_children</emphasis> lists. The effect of such a call is that
|
|
the child remains managed following the call, but the <emphasis remap='I'>do_change_proc</emphasis> is
|
|
able to affect the child while it is in an unmanaged state.
|
|
</para>
|
|
|
|
<para>
|
|
The <emphasis remap='I'>do_change_proc</emphasis> is of type
|
|
<xref linkend='XtDoChangeProc' xrefstyle='select: title'/>.
|
|
</para>
|
|
|
|
<funcsynopsis id='XtDoChangeProc'>
|
|
<funcprototype>
|
|
<funcdef>typedef void <function>*XtDoChangeProc</function></funcdef>
|
|
|
|
<paramdef>Widget <parameter>composite_parent</parameter></paramdef>
|
|
<paramdef>WidgetList <parameter>unmange_children</parameter></paramdef>
|
|
<paramdef>Cardinal *<parameter>num_unmanage_children</parameter></paramdef>
|
|
<paramdef>WidgetList <parameter>manage_children</parameter></paramdef>
|
|
<paramdef>Cardinal *<parameter>num_manage_children</parameter></paramdef>
|
|
<paramdef>XtPointer <parameter>client_data</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>composite_parent</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Passes the composite parent whose managed set is being altered.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>unmanage_children</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Passes the list of children just removed from the managed set.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>num_unmanage_children</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Passes the number of entries in the <emphasis remap='I'>unmanage_children</emphasis> list.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>manage_children</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Passes the list of children about to be added to the managed set.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>num_manage_children</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Passes the number of entries in the <emphasis remap='I'>manage_children</emphasis> list.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>client_data</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Passes the client data passed to
|
|
<xref linkend='XtChangeManagedSet' xrefstyle='select: title'/>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<para>
|
|
The <emphasis remap='I'>do_change_proc</emphasis> procedure is used by the caller of
|
|
<xref linkend='XtChangeManagedSet' xrefstyle='select: title'/>
|
|
to make changes to one or more children at the point when the
|
|
managed set contains the fewest entries. These changes may
|
|
involve geometry requests, and in this case the caller of
|
|
<xref linkend='XtChangeManagedSet' xrefstyle='select: title'/>
|
|
may take advantage of the fact that the Intrinsics internally grant
|
|
geometry requests made by unmanaged children without invoking
|
|
the parent's geometry manager. To achieve this advantage, if
|
|
the <emphasis remap='I'>do_change_proc</emphasis> procedure
|
|
changes the geometry of a child or of a descendant of a child, then
|
|
that child should be included in the <emphasis remap='I'>unmanage_children</emphasis> and
|
|
<emphasis remap='I'>manage_children</emphasis> lists.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="Determining_if_a_Widget_Is_Managed">
|
|
<title>Determining if a Widget Is Managed</title>
|
|
<para>
|
|
To determine the managed state of a given child widget, use
|
|
<xref linkend='XtIsManaged' xrefstyle='select: title'/>.
|
|
</para>
|
|
|
|
<funcsynopsis id='XtIsManaged'>
|
|
<funcprototype>
|
|
<funcdef>Boolean <function>XtIsManaged</function></funcdef>
|
|
<paramdef>Widget <parameter>w</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>w</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the widget. Must be of class Object or any subclass thereof.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<para>
|
|
The
|
|
<xref linkend='XtIsManaged' xrefstyle='select: title'/>
|
|
function returns
|
|
<function>True</function>
|
|
if the specified widget is of class RectObj or any subclass thereof
|
|
and is managed, or
|
|
<function>False</function>
|
|
otherwise.
|
|
</para>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<sect1 id="Controlling_When_Widgets_Get_Mapped">
|
|
<title>Controlling When Widgets Get Mapped</title>
|
|
<para>
|
|
A widget is normally mapped if it is managed.
|
|
However,
|
|
this behavior can be overridden by setting the XtNmappedWhenManaged resource
|
|
for the widget when it is created
|
|
or by setting the <emphasis remap='I'>map_when_managed</emphasis> field to
|
|
<function>False</function>.
|
|
</para>
|
|
|
|
<para>
|
|
To change the value of a given widget's <emphasis remap='I'>map_when_managed</emphasis> field, use
|
|
<xref linkend='XtSetMappedWhenManaged' xrefstyle='select: title'/>.
|
|
</para>
|
|
|
|
<funcsynopsis id='XtSetMappedWhenManaged'>
|
|
<funcprototype>
|
|
<funcdef>void <function>XtSetMappedWhenManaged</function></funcdef>
|
|
<paramdef>Widget <parameter>w</parameter></paramdef>
|
|
<paramdef>Boolean <parameter>map_when_managed</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>w</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the widget. Must be of class Core or any subclass thereof.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>map_when_managed</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies a Boolean value that indicates the new value
|
|
that is stored into the widget's <emphasis remap='I'>map_when_managed</emphasis>
|
|
field.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<para>
|
|
If the widget is realized and managed,
|
|
and if <emphasis remap='I'>map_when_managed</emphasis> is
|
|
<function>True</function>,
|
|
<xref linkend='XtSetMappedWhenManaged' xrefstyle='select: title'/>
|
|
maps the window.
|
|
If the widget is realized and managed,
|
|
and if <emphasis remap='I'>map_when_managed</emphasis> is
|
|
<function>False</function>,
|
|
it unmaps the window.
|
|
<xref linkend='XtSetMappedWhenManaged' xrefstyle='select: title'/>
|
|
is a convenience function that is equivalent to (but slightly faster than)
|
|
calling
|
|
<xref linkend='XtSetValues' xrefstyle='select: title'/>
|
|
and setting the new value for the XtNmappedWhenManaged resource
|
|
then mapping the widget as appropriate.
|
|
As an alternative to using
|
|
<xref linkend='XtSetMappedWhenManaged' xrefstyle='select: title'/>
|
|
to control mapping,
|
|
a client may set <emphasis remap='I'>mapped_when_managed</emphasis> to
|
|
<function>False</function>
|
|
and use
|
|
<xref linkend='XtMapWidget' xrefstyle='select: title'/>
|
|
and
|
|
<xref linkend='XtUnmapWidget' xrefstyle='select: title'/>
|
|
explicitly.
|
|
</para>
|
|
|
|
<para>
|
|
To map a widget explicitly, use
|
|
<xref linkend='XtMapWidget' xrefstyle='select: title'/>.
|
|
</para>
|
|
|
|
<funcsynopsis id='XtMapWidget'>
|
|
<funcprototype>
|
|
<funcdef> <function>XtMapWidget</function></funcdef>
|
|
<paramdef>Widget <parameter>w</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>w</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the widget. Must be of class Core or any subclass thereof.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<para>
|
|
To unmap a widget explicitly, use
|
|
<xref linkend='XtUnmapWidget' xrefstyle='select: title'/>.
|
|
</para>
|
|
|
|
<funcsynopsis id='XtUnmapWidget'>
|
|
<funcprototype>
|
|
<funcdef> <function>XtUnmapWidget</function></funcdef>
|
|
<paramdef>Widget <parameter>w</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>w</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the widget. Must be of class Core or any subclass thereof.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="Constrained_Composite_Widgets">
|
|
<title>Constrained Composite Widgets</title>
|
|
<para>
|
|
The Constraint
|
|
widget class is a subclass of
|
|
<function>compositeWidgetClass</function>.
|
|
The name is derived from the fact that constraint widgets
|
|
may manage the geometry
|
|
of their children based on constraints associated with each child.
|
|
These constraints can be as simple as the maximum width and height
|
|
the parent will allow the child to occupy or can be as complicated as
|
|
how other children should change if this child is moved or resized.
|
|
Constraint
|
|
widgets let a parent define constraints as resources that are supplied for their children.
|
|
For example, if the
|
|
Constraint
|
|
parent defines the maximum sizes for its children,
|
|
these new size resources are retrieved for each child as if they were
|
|
resources that were defined by the child widget's class.
|
|
Accordingly,
|
|
constraint resources may be included in the argument list or resource file just
|
|
like any other resource for the child.
|
|
</para>
|
|
|
|
<para>
|
|
Constraint
|
|
widgets have all the responsibilities of normal composite widgets
|
|
and, in addition, must process and act upon the constraint information
|
|
associated with each of their children.
|
|
</para>
|
|
|
|
<para>
|
|
To make it easy for widgets and the Intrinsics to keep track of the
|
|
constraints associated with a child,
|
|
every widget has a <emphasis remap='I'>constraints</emphasis> field,
|
|
which is the address of a parent-specific structure that contains
|
|
constraint information about the child.
|
|
If a child's parent does not belong to a subclass of
|
|
<function>constraintWidgetClass</function>,
|
|
then the child's <emphasis remap='I'>constraints</emphasis> field is NULL.
|
|
</para>
|
|
|
|
<para>
|
|
Subclasses of
|
|
Constraint
|
|
can add constraint data to the constraint record defined by their superclass.
|
|
To allow this, widget writers should define the constraint
|
|
records in their private .h file by using the same conventions as used for
|
|
widget records.
|
|
For example, a widget class that needs to maintain a maximum
|
|
width and height for each child might define its constraint record as
|
|
follows:
|
|
</para>
|
|
<literallayout >
|
|
typedef struct {
|
|
Dimension max_width, max_height;
|
|
} MaxConstraintPart;
|
|
typedef struct {
|
|
MaxConstraintPart max;
|
|
} MaxConstraintRecord, *MaxConstraint;
|
|
</literallayout>
|
|
<para>
|
|
A subclass of this widget class that also needs to maintain a minimum size would
|
|
define its constraint record as follows:
|
|
</para>
|
|
<literallayout >
|
|
typedef struct {
|
|
Dimension min_width, min_height;
|
|
} MinConstraintPart;
|
|
typedef struct {
|
|
MaxConstraintPart max;
|
|
MinConstraintPart min;
|
|
} MaxMinConstraintRecord, *MaxMinConstraint;
|
|
</literallayout>
|
|
<para>
|
|
Constraints are allocated, initialized, deallocated, and otherwise maintained
|
|
insofar as possible by the Intrinsics.
|
|
The Constraint class record part has several entries that facilitate this.
|
|
All entries in
|
|
<function>ConstraintClassPart</function>
|
|
are fields and procedures that are defined and implemented by the parent,
|
|
but they are called whenever actions are performed on the parent's children.
|
|
</para>
|
|
|
|
<para>
|
|
The
|
|
<xref linkend='XtCreateWidget' xrefstyle='select: title'/>
|
|
function uses the <emphasis remap='I'>constraint_size</emphasis> field in the parent's class record
|
|
to allocate a constraint record when a child is created.
|
|
<xref linkend='XtCreateWidget' xrefstyle='select: title'/>
|
|
also uses the constraint resources to fill in resource fields in the
|
|
constraint record associated with a child.
|
|
It then calls the constraint initialize procedure so that the parent
|
|
can compute constraint fields that are derived from constraint resources
|
|
and can possibly move or resize the child to conform to the given constraints.
|
|
</para>
|
|
|
|
<para>
|
|
When the
|
|
<xref linkend='XtGetValues' xrefstyle='select: title'/>
|
|
and
|
|
<xref linkend='XtSetValues' xrefstyle='select: title'/>
|
|
functions are executed
|
|
on a child, they use the constraint resources to get the values or
|
|
set the values of constraints associated with that child.
|
|
<xref linkend='XtSetValues' xrefstyle='select: title'/>
|
|
then calls the constraint set_values procedures so that the parent can
|
|
recompute derived constraint fields and move or resize the child
|
|
as appropriate.
|
|
If a
|
|
Constraint
|
|
widget class or any of its superclasses have declared a
|
|
<function>ConstraintClassExtension</function>
|
|
record in the
|
|
<function>ConstraintClassPart</function>
|
|
<emphasis remap='I'>extension</emphasis>
|
|
fields with a record type of
|
|
<emphasis role='strong'>NULLQUARK</emphasis>
|
|
and the <emphasis remap='I'>get_values_hook</emphasis> field in
|
|
the extension record is non-NULL,
|
|
<xref linkend='XtGetValues' xrefstyle='select: title'/>
|
|
calls the get_values_hook
|
|
procedure(s) to allow the parent to return derived constraint fields.
|
|
</para>
|
|
|
|
<para>
|
|
The
|
|
<xref linkend='XtDestroyWidget' xrefstyle='select: title'/>
|
|
function calls the constraint destroy procedure to deallocate any
|
|
dynamic storage associated with a constraint record.
|
|
The constraint record itself must not be deallocated by the constraint
|
|
destroy procedure;
|
|
<xref linkend='XtDestroyWidget' xrefstyle='select: title'/>
|
|
does this automatically.
|
|
</para>
|
|
</sect1>
|
|
</chapter>
|