diff options
Diffstat (limited to 'libXt/specs/CH03.xml')
| -rw-r--r-- | libXt/specs/CH03.xml | 1406 |
1 files changed, 1406 insertions, 0 deletions
diff --git a/libXt/specs/CH03.xml b/libXt/specs/CH03.xml new file mode 100644 index 000000000..2b2e1d730 --- /dev/null +++ b/libXt/specs/CH03.xml @@ -0,0 +1,1406 @@ +<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> |