1032 lines
31 KiB
Plaintext
1032 lines
31 KiB
Plaintext
.\" $Xorg: CH03,v 1.3 2000/08/17 19:42:44 cpqbld Exp $
|
|
.\" Copyright \(co 1985, 1986, 1987, 1988, 1991, 1994
|
|
.\" X Consortium
|
|
.\"
|
|
.\" Permission is hereby granted, free of charge, to any person obtaining
|
|
.\" a copy of this software and associated documentation files (the
|
|
.\" "Software"), to deal in the Software without restriction, including
|
|
.\" without limitation the rights to use, copy, modify, merge, publish,
|
|
.\" distribute, sublicense, and/or sell copies of the Software, and to
|
|
.\" permit persons to whom the Software is furnished to do so, subject to
|
|
.\" the following conditions:
|
|
.\"
|
|
.\" The above copyright notice and this permission notice shall be included
|
|
.\" in all copies or substantial portions of the Software.
|
|
.\"
|
|
.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
|
|
.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
|
.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
|
|
.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR
|
|
.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
|
|
.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
|
|
.\" OTHER DEALINGS IN THE SOFTWARE.
|
|
.\"
|
|
.\" Except as contained in this notice, the name of the X Consortium shall
|
|
.\" not be used in advertising or otherwise to promote the sale, use or
|
|
.\" other dealings in this Software without prior written authorization
|
|
.\" from the X Consortium.
|
|
.\"
|
|
.\" Copyright \(co 1985, 1986, 1987, 1988, 1991, 1994
|
|
.\" Digital Equipment Corporation, Maynard, Massachusetts.
|
|
.\"
|
|
.\" Permission to use, copy, modify and distribute this documentation for any
|
|
.\" purpose and without fee is hereby granted, provided that the above copyright
|
|
.\" notice appears in all copies and that both that copyright notice and this
|
|
.\" permission notice appear in supporting documentation, and that the name of
|
|
.\" Digital not be used in in advertising or publicity pertaining
|
|
.\" to distribution of the software without specific, written prior permission.
|
|
.\" Digital makes no representations about the suitability of the
|
|
.\" software described herein for any purpose.
|
|
.\" It is provided ``as is'' without express or implied warranty.
|
|
.\"
|
|
\&
|
|
.sp 1
|
|
.ce 3
|
|
\s+1\fBChapter 3\fP\s-1
|
|
|
|
\s+1\fBComposite Widgets and Their Children\fP\s-1
|
|
.sp 2
|
|
.nr H1 3
|
|
.nr H2 0
|
|
.nr H3 0
|
|
.nr H4 0
|
|
.nr H5 0
|
|
.LP
|
|
.XS
|
|
Chapter 3 \(em Composite Widgets and Their Children
|
|
.XE
|
|
.IN "Composite widgets"
|
|
Composite widgets (widgets whose class is a subclass of
|
|
.PN compositeWidgetClass )
|
|
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 \*(xI functions) include:
|
|
.IP \(bu 5
|
|
Overall management of children from creation to destruction.
|
|
.IP \(bu 5
|
|
Destruction of descendants when the composite widget is destroyed.
|
|
.IP \(bu 5
|
|
Physical arrangement (geometry management) of a displayable subset of
|
|
children (that is, the managed children).
|
|
.IP \(bu 5
|
|
Mapping and unmapping of a subset of the managed children.
|
|
.LP
|
|
Overall management is handled by the generic procedures
|
|
.PN XtCreateWidget
|
|
and
|
|
.PN XtDestroyWidget .
|
|
.PN XtCreateWidget
|
|
adds children to their parent by calling the parent's insert_child
|
|
procedure.
|
|
.PN XtDestroyWidget
|
|
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.
|
|
.LP
|
|
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 \*(xI.
|
|
.LP
|
|
Children are added to and removed from their parent's managed set by using
|
|
.PN XtManageChild ,
|
|
.PN XtManageChildren ,
|
|
.PN XtUnmanageChild ,
|
|
.PN XtUnmanageChildren ,
|
|
and
|
|
.PN XtChangeManagedSet ,
|
|
which notify the parent to recalculate the physical layout of its children
|
|
by calling the parent's change_managed procedure.
|
|
The
|
|
.PN XtCreateManagedWidget
|
|
convenience function calls
|
|
.PN XtCreateWidget
|
|
and
|
|
.PN XtManageChild
|
|
on the result.
|
|
.LP
|
|
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 \fImap_when_managed\fP field is
|
|
.PN False .
|
|
The default is
|
|
.PN True
|
|
and is changed by using
|
|
.PN XtSetMappedWhenManaged .
|
|
.LP
|
|
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:
|
|
.IP "Fixed boxes" 1.6i
|
|
Fixed boxes have a fixed number of children created by the parent.
|
|
All these children are managed,
|
|
and none ever makes geometry manager requests.
|
|
.IP "Homogeneous boxes" 1.6i
|
|
Homogeneous boxes treat all children equally and apply the same geometry
|
|
constraints to each child.
|
|
Many clients insert and delete widgets freely.
|
|
.IP "Heterogeneous boxes" 1.6i
|
|
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.
|
|
.IP "Shell boxes" 1.6i
|
|
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
|
|
.PN ConfigureNotify
|
|
events when the window size is changed by the window manager.
|
|
|
|
.NH 2
|
|
Addition of Children to a Composite Widget: The insert_child Procedure
|
|
.XS
|
|
\*(SN Addition of Children to a Composite Widget: The insert_child Procedure
|
|
.XE
|
|
.LP
|
|
.IN "insert_child procedure"
|
|
To add a child to
|
|
the parent's list of children, the
|
|
.PN XtCreateWidget
|
|
function calls the parent's class routine insert_child.
|
|
The insert_child procedure pointer in a composite widget is of type
|
|
.PN XtWidgetProc .
|
|
.LP
|
|
.IN "insert_child procedure" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
typedef void (*XtWidgetProc)(Widget);
|
|
.br
|
|
Widget \fIw\fP;
|
|
.FN
|
|
.IP \fIw\fP 1i
|
|
Passes the newly created child.
|
|
.LP
|
|
.eM
|
|
Most composite widgets inherit their superclass's operation.
|
|
The insert_child routine in
|
|
.PN CompositeWidgetClass calls the insert_position procedure
|
|
and inserts the child at the specified position
|
|
in the \fIchildren\fP list, expanding it if necessary.
|
|
.LP
|
|
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 Chapter 12) must specify a
|
|
.PN CompositeClassExtension
|
|
extension record as described
|
|
in Section 1.4.2.1 and set the \fIaccepts_objects\fP field in this record to
|
|
.PN True .
|
|
If the
|
|
.PN CompositeClassExtension
|
|
record is not specified or the
|
|
\fIaccepts_objects\fP field is
|
|
.PN False ,
|
|
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.
|
|
.LP
|
|
If there is not enough room to insert a new child in the \fIchildren\fP array
|
|
(that is, \fInum_children\fP is equal to \fInum_slots\fP),
|
|
the insert_child procedure must first reallocate the array
|
|
and update \fInum_slots\fP.
|
|
The insert_child procedure then places the child at the appropriate position
|
|
in the array and increments the \fInum_children\fP field.
|
|
|
|
.NH 2
|
|
Insertion Order of Children: The insert_position Procedure
|
|
.XS
|
|
\fB\*(SN Insertion Order of Children: The insert_position Procedure\fP
|
|
.XE
|
|
.LP
|
|
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.
|
|
.LP
|
|
An application controls the presentation order of a set of children by
|
|
supplying an
|
|
.IN XtNinsertPosition
|
|
XtNinsertPosition
|
|
resource.
|
|
The insert_position procedure pointer in a composite widget instance is of type
|
|
.PN XtOrderProc .
|
|
.LP
|
|
.IN "XtOrderProc" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
typedef Cardinal (*XtOrderProc)(Widget);
|
|
.br
|
|
Widget \fIw\fP;
|
|
.FN
|
|
.IP \fIw\fP 1i
|
|
Passes the newly created widget.
|
|
.LP
|
|
.eM
|
|
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 \fIchildren\fP 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.
|
|
.LP
|
|
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 \fInum_children\fP indicates that it should go after all other children.
|
|
The default insert_position function returns \fInum_children\fP
|
|
and can be overridden by a specific composite widget's resource list
|
|
or by the argument list provided when the composite widget is created.
|
|
|
|
.NH 2
|
|
Deletion of Children: The delete_child Procedure
|
|
.XS
|
|
\*(SN Deletion of Children: The delete_child Procedure
|
|
.XE
|
|
.LP
|
|
.IN "delete_child procedure"
|
|
.LP
|
|
To remove the child from the parent's \fIchildren\fP list, the
|
|
.PN XtDestroyWidget
|
|
function eventually causes a call to the Composite parent's class delete_child
|
|
procedure.
|
|
The delete_child procedure pointer is of type
|
|
.PN XtWidgetProc .
|
|
.LP
|
|
.IN "delete_child procedure" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
typedef void (*XtWidgetProc)(Widget);
|
|
.br
|
|
Widget \fIw\fP;
|
|
.FN
|
|
.IP \fIw\fP
|
|
Passes the child being deleted.
|
|
.LP
|
|
.eM
|
|
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.
|
|
|
|
.NH 2
|
|
Adding and Removing Children from the Managed Set
|
|
.XS
|
|
\fB\*(SN Adding and Removing Children from the Managed Set\fP
|
|
.XE
|
|
.LP
|
|
The \*(xI 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.
|
|
.IN "change_managed procedure"
|
|
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
|
|
.PN XtWidgetProc .
|
|
The widget argument specifies the composite widget whose managed child
|
|
set has been modified.
|
|
|
|
.NH 3
|
|
Managing Children
|
|
.XS
|
|
\fB\*(SN Managing Children\fP
|
|
.XE
|
|
.LP
|
|
To add a list of widgets to the geometry-managed (and hence displayable)
|
|
subset of their Composite parent, use
|
|
.PN XtManageChildren .
|
|
.LP
|
|
.IN "XtManageChildren" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
typedef Widget *WidgetList;
|
|
.sp
|
|
void XtManageChildren(\fIchildren\fP, \fInum_children\fP)
|
|
.br
|
|
WidgetList \fIchildren\fP;
|
|
.br
|
|
Cardinal \fInum_children\fP;
|
|
.FN
|
|
.IP \fIchildren\fP 1i
|
|
Specifies a list of child widgets. Each child must be of class
|
|
RectObj or any subclass thereof.
|
|
.IP \fInum_children\fP 1i
|
|
Specifies the number of children in the list.
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN XtManageChildren
|
|
function performs the following:
|
|
.IP \(bu 5
|
|
Issues an error if the children do not all have the same parent or
|
|
if the parent's class is not a subclass of
|
|
.PN compositeWidgetClass .
|
|
.IP \(bu 5
|
|
Returns immediately if the common parent is being destroyed;
|
|
otherwise, for each unique child on the list,
|
|
.PN XtManageChildren
|
|
ignores the child if it already is managed or is being destroyed,
|
|
and marks it if not.
|
|
.IP \(bu 5
|
|
If the parent is realized and after all children have been marked,
|
|
it makes some of the newly managed children viewable:
|
|
.RS
|
|
.IP \- 5
|
|
Calls the change_managed routine of the widgets' parent.
|
|
.IP \- 5
|
|
Calls
|
|
.PN XtRealizeWidget
|
|
on each previously unmanaged child that is unrealized.
|
|
.IP \- 5
|
|
Maps each previously unmanaged child that has \fImap_when_managed\fP
|
|
.PN True .
|
|
.RE
|
|
.LP
|
|
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 \fImanaged\fP field is
|
|
.PN True
|
|
and should ignore all other children.
|
|
Note that some composite widgets, especially fixed boxes, call
|
|
.PN XtManageChild
|
|
from their insert_child procedure.
|
|
.LP
|
|
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
|
|
.PN XtMoveWidget ,
|
|
which first updates the \fIx\fP and \fIy\fP fields and which then calls
|
|
.PN XMoveWindow .
|
|
.LP
|
|
If the composite widget wishes to change the size or border width of any of
|
|
its children, it calls
|
|
.PN XtResizeWidget ,
|
|
which first updates the
|
|
\fIwidth\fP, \fIheight\fP, and \fIborder_width\fP
|
|
fields and then calls
|
|
.PN XConfigureWindow .
|
|
Simultaneous repositioning and resizing may be done with
|
|
.PN XtConfigureWidget ;
|
|
see Section 6.6.
|
|
.sp
|
|
.LP
|
|
To add a single child to its parent widget's set of managed children, use
|
|
.PN XtManageChild .
|
|
.LP
|
|
.IN "XtManageChild" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
void XtManageChild(\fIchild\fP)
|
|
.br
|
|
Widget \fIchild\fP;
|
|
.FN
|
|
.IP \fIchild\fP 1i
|
|
Specifies the child. \*(rI
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN XtManageChild
|
|
function constructs a
|
|
.PN WidgetList
|
|
of length 1 and calls
|
|
.PN XtManageChildren .
|
|
.sp
|
|
.LP
|
|
To create and manage a child widget in a single procedure, use
|
|
.PN XtCreateManagedWidget
|
|
or
|
|
.PN XtVaCreateManagedWidget .
|
|
.LP
|
|
.IN "XtCreateManagedWidget" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
Widget XtCreateManagedWidget(\fIname\fP, \fIwidget_class\fP, \fIparent\fP, \
|
|
\fIargs\fP, \fInum_args\fP)
|
|
.br
|
|
String \fIname\fP;
|
|
.br
|
|
WidgetClass \fIwidget_class\fP;
|
|
.br
|
|
Widget \fIparent\fP;
|
|
.br
|
|
ArgList \fIargs\fP;
|
|
.br
|
|
Cardinal \fInum_args\fP;
|
|
.FN
|
|
.IP \fIname\fP 1i
|
|
Specifies the resource instance name for the created widget.
|
|
.IP \fIwidget_class\fP 1i
|
|
Specifies the widget class pointer for the created widget. \*(rC
|
|
.IP \fIparent\fP 1i
|
|
Specifies the parent widget. Must be of class Composite or any
|
|
subclass thereof.
|
|
.IP \fIargs\fP 1i
|
|
Specifies the argument list to override any other resource specifications.
|
|
.IP \fInum_args\fP 1i
|
|
Specifies the number of entries in the argument list.
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN XtCreateManagedWidget
|
|
function is a convenience routine that calls
|
|
.PN XtCreateWidget
|
|
and
|
|
.PN XtManageChild .
|
|
.sp
|
|
.LP
|
|
.IN "XtVaCreateManagedWidget" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
Widget XtVaCreateManagedWidget(\fIname\fP, \fIwidget_class\fP, \fIparent\fP, ...)
|
|
.br
|
|
String \fIname\fP;
|
|
.br
|
|
WidgetClass \fIwidget_class\fP;
|
|
.br
|
|
Widget \fIparent\fP;
|
|
.FN
|
|
.IP \fIname\fP 1i
|
|
Specifies the resource instance name for the created widget.
|
|
.IP \fIwidget_class\fP 1i
|
|
Specifies the widget class pointer for the created widget. \*(rC
|
|
.IP \fIparent\fP 1i
|
|
Specifies the parent widget. Must be of class Composite or any
|
|
subclass thereof.
|
|
.IP ... 1i
|
|
Specifies the variable argument list to override any other
|
|
resource specifications.
|
|
.LP
|
|
.eM
|
|
.PN XtVaCreateManagedWidget
|
|
is identical in function to
|
|
.PN XtCreateManagedWidget
|
|
with the \fIargs\fP and \fInum_args\fP parameters replaced
|
|
by a varargs list, as described in Section 2.5.1.
|
|
|
|
.NH 3
|
|
Unmanaging Children
|
|
.XS
|
|
\fB\*(SN Unmanaging Children\fP
|
|
.XE
|
|
.LP
|
|
To remove a list of children from a parent widget's managed list, use
|
|
.PN XtUnmanageChildren .
|
|
.LP
|
|
.IN "XtUnmanageChildren" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
void XtUnmanageChildren(\fIchildren\fP, \fInum_children\fP)
|
|
.br
|
|
WidgetList \fIchildren\fP;
|
|
.br
|
|
Cardinal \fInum_children\fP;
|
|
.FN
|
|
.IP \fIchildren\fP 1i
|
|
Specifies a list of child widgets. Each child must be of class
|
|
RectObj or any subclass thereof.
|
|
.IP \fInum_children\fP 1i
|
|
Specifies the number of children.
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN XtUnmanageChildren
|
|
function performs the following:
|
|
.IP \(bu 5
|
|
Returns immediately if the common parent is being destroyed.
|
|
.IP \(bu 5
|
|
Issues an error if the children do not all have the same parent
|
|
or if the parent is not a subclass of
|
|
.PN compositeWidgetClass .
|
|
.IP \(bu 5
|
|
For each unique child on the list,
|
|
.PN XtUnmanageChildren
|
|
ignores the child if it is unmanaged; otherwise it performs the following:
|
|
.RS
|
|
.IP \- 5
|
|
Marks the child as unmanaged.
|
|
.IP \- 5
|
|
If the child is realized and the \fImap_when_managed\fP field is
|
|
.PN True ,
|
|
it is unmapped.
|
|
.RE
|
|
.IP \(bu 5
|
|
If the parent is realized and if any children have become unmanaged,
|
|
calls the change_managed routine of the widgets' parent.
|
|
.LP
|
|
.PN XtUnmanageChildren
|
|
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,
|
|
.PN XtDestroyWidget
|
|
should be called instead;
|
|
see Section 2.9.
|
|
.sp
|
|
.LP
|
|
To remove a single child from its parent widget's managed set, use
|
|
.PN XtUnmanageChild .
|
|
.LP
|
|
.IN "XtUnmanageChild" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
void XtUnmanageChild(\fIchild\fP)
|
|
.br
|
|
Widget \fIchild\fP;
|
|
.FN
|
|
.IP \fIchild\fP 1i
|
|
Specifies the child. \*(rI
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN XtUnmanageChild
|
|
function constructs a widget list
|
|
of length 1 and calls
|
|
.PN XtUnmanageChildren .
|
|
.LP
|
|
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.
|
|
|
|
.NH 3
|
|
Bundling Changes to the Managed Set
|
|
.XS
|
|
\fB\*(SN Bundling Changes to the Managed Set\fP
|
|
.XE
|
|
.LP
|
|
A client may simultaneously unmanage and manage children
|
|
with a single call to the \*(xI. 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.
|
|
.\" .LP
|
|
.\" The composite widget class specifies how its change_managed method
|
|
.\" should be invoked by declaring a
|
|
.\" .PN CompositeClassExtension
|
|
.\" structure as described in section 1.4.2.1. If the
|
|
.\" \fIallows_change_managed_set\fP field in the
|
|
.\" .PN CompositeClassExtension
|
|
.\" record is
|
|
.\" .PN False ,
|
|
.\" the change_managed method will be invoked twice; once before any
|
|
.\" geometry changes are requested by the client callback and once
|
|
.\" after. If the \fIallows_change_managed_set\fP field is
|
|
.\" .PN True ,
|
|
.\" the change_managed method will be invoked just once after the
|
|
.\" specified children have been marked as unmanaged or managed and
|
|
.\" the client's callback has been invoked.
|
|
.\" If no
|
|
.\" .PN CompositeClassExtension
|
|
.\" record is found in the extension field of the
|
|
.\" composite class part with record type
|
|
.\" .PN \s-1NULLQUARK\s+1
|
|
.\" and version greater
|
|
.\" than 1 and if
|
|
.\" .PN XtInheritChangeManaged
|
|
.\" was specified in the class record during class initialization, the
|
|
.\" value of the \fIallows_change_managed_set\fP
|
|
.\" field will be inherited from the superclass.
|
|
.LP
|
|
To simultaneously remove from and add to the geometry-managed
|
|
set of children of a composite parent, use
|
|
.PN XtChangeManagedSet .
|
|
.LP
|
|
.IN "XtChangeManagedSet" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
void XtChangeManagedSet(\fIunmanage_children\fP, \fInum_unmanage_children\fP,
|
|
\fIdo_change_proc\fP, \fIclient_data\fP,
|
|
\fImanage_children\fP, \fInum_manage_children\fP)
|
|
.br
|
|
WidgetList \fIunmanage_children\fP;
|
|
.br
|
|
Cardinal \fInum_unmanage_children\fP;
|
|
.br
|
|
XtDoChangeProc \fIdo_change_proc\fP;
|
|
.br
|
|
XtPointer \fIclient_data\fP;
|
|
.br
|
|
WidgetList \fImanage_children\fP;
|
|
.br
|
|
Cardinal \fInum_manage_children\fP;
|
|
.FN
|
|
.IP \fIunmanage_children\fP 1.8i
|
|
Specifies the list of widget children to initially remove from the managed set.
|
|
.IP \fInum_unmanage_children\fP 1.8i
|
|
Specifies the number of entries in the \fIunmanage_children\fP list.
|
|
.IP \fIdo_change_proc\fP 1.8i
|
|
Specifies a procedure to invoke between unmanaging
|
|
and managing the children, or NULL.
|
|
.IP \fIclient_data\fP 1.8i
|
|
Specifies client data to be passed to the do_change_proc.
|
|
.IP \fImanage_children\fP 1.8i
|
|
Specifies the list of widget children to finally add to the managed set.
|
|
.IP \fInum_manage_children\fP 1.8i
|
|
Specifies the number of entries in the \fImanage_children\fP list.
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN XtChangeManagedSet
|
|
function performs the following:
|
|
.IP \(bu 5
|
|
Returns immediately if \fInum_unmanage_children\fP and
|
|
\fInum_manage_children\fP are both 0.
|
|
.IP \(bu 5
|
|
Issues a warning and returns if the widgets specified in the
|
|
\fImanage_children\fP and
|
|
the \fIunmanage_children\fP lists do not all have the same parent or if
|
|
that parent is not a subclass of
|
|
.PN compositeWidgetClass .
|
|
.IP \(bu 5
|
|
Returns immediately if the common parent is being destroyed.
|
|
.IP \(bu 5
|
|
If \fIdo_change_proc\fP is not NULL and the parent's
|
|
.PN CompositeClassExtension
|
|
\fIallows_change_managed_set\fP field is
|
|
.PN False ,
|
|
then
|
|
.PN XtChangeManagedSet
|
|
performs the following:
|
|
.RS
|
|
.IP \- 5
|
|
Calls
|
|
.PN XtUnmanageChildren
|
|
(\fIunmanage_children\fP, \fInum_unmanage_children\fP).
|
|
.IP \- 5
|
|
Calls the \fIdo_change_proc\fP.
|
|
.IP \- 5
|
|
Calls
|
|
.PN XtManageChildren
|
|
(\fImanage_children\fP, \fInum_manage_children\fP).
|
|
.RE
|
|
.IP \(bu 5
|
|
Otherwise, the following is performed:
|
|
.RS
|
|
.IP \- 5
|
|
For each child on the \fIunmanage_children\fP list; if the child is
|
|
already unmanaged it is ignored, otherwise it is marked as unmanaged,
|
|
and if it is realized and its \fImap_when_managed\fP field is
|
|
.PN True ,
|
|
it is unmapped.
|
|
.IP \- 5
|
|
If \fIdo_change_proc\fP is non-NULL, the procedure is invoked.
|
|
.IP \- 5
|
|
For each child on the \fImanage_children\fP list; if the child is already
|
|
managed or is being destroyed, it is ignored; otherwise it is
|
|
marked as managed.
|
|
.IP \- 5
|
|
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
|
|
.PN XtRealizeWidget
|
|
on each previously unmanaged child that is unrealized and
|
|
mapping each previously unmanaged child that has \fImap_when_managed\fP
|
|
.PN True .
|
|
.RE
|
|
.LP
|
|
If no
|
|
.PN CompositeClassExtension
|
|
record is found in the parent's composite class part \fIextension\fP field
|
|
with record type
|
|
.PN \s-1NULLQUARK\s+1
|
|
and version greater than 1, and if
|
|
.PN XtInheritChangeManaged
|
|
was specified in the parent's class record during class initialization,
|
|
the value of the \fIallows_change_managed_set\fP
|
|
field is inherited from the superclass. The value inherited from
|
|
.PN compositeWidgetClass
|
|
for the \fIallows_change_managed_set\fP field is
|
|
.PN False .
|
|
.LP
|
|
It is not an error to include a child in both the \fIunmanage_children\fP
|
|
and the \fImanage_children\fP lists. The effect of such a call is that
|
|
the child remains managed following the call, but the \fIdo_change_proc\fP is
|
|
able to affect the child while it is in an unmanaged state.
|
|
.sp
|
|
.LP
|
|
The \fIdo_change_proc\fP is of type
|
|
.PN XtDoChangeProc .
|
|
.LP
|
|
.IN "XtDoChangeProc" "" "@DEF"
|
|
.sM
|
|
.FD 0
|
|
typedef void (*XtDoChangeProc)(Widget, WidgetList, Cardinal*, WidgetList, Cardinal*, XtPointer);
|
|
.br
|
|
Widget \fIcomposite_parent\fP;
|
|
.br
|
|
WidgetList \fIunmange_children\fP;
|
|
.br
|
|
Cardinal *\fInum_unmanage_children\fP;
|
|
.br
|
|
WidgetList \fImanage_children\fP;
|
|
.br
|
|
Cardinal *\fInum_manage_children\fP;
|
|
.br
|
|
XtPointer \fIclient_data\fP;
|
|
.FN
|
|
.IP \fIcomposite_parent\fP 1.8i
|
|
Passes the composite parent whose managed set is being altered.
|
|
.IP \fIunmanage_children\fP 1.8i
|
|
Passes the list of children just removed from the managed set.
|
|
.IP \fInum_unmanage_children\fP 1.8i
|
|
Passes the number of entries in the \fIunmanage_children\fP list.
|
|
.IP \fImanage_children\fP 1.8i
|
|
Passes the list of children about to be added to the managed set.
|
|
.IP \fInum_manage_children\fP 1.8i
|
|
Passes the number of entries in the \fImanage_children\fP list.
|
|
.IP \fIclient_data\fP 1.8i
|
|
Passes the client data passed to
|
|
.PN XtChangeManagedSet .
|
|
.LP
|
|
.eM
|
|
The \fIdo_change_proc\fP procedure is used by the caller of
|
|
.PN XtChangeManagedSet
|
|
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
|
|
.PN XtChangeManagedSet
|
|
may take advantage of the fact that the \*(xI internally grant
|
|
geometry requests made by unmanaged children without invoking
|
|
the parent's geometry manager. To achieve this advantage, if
|
|
the \fIdo_change_proc\fP procedure
|
|
changes the geometry of a child or of a descendant of a child, then
|
|
that child should be included in the \fIunmanage_children\fP and
|
|
\fImanage_children\fP lists.
|
|
|
|
.NH 3
|
|
Determining if a Widget Is Managed
|
|
.XS
|
|
\fB\*(SN Determining if a Widget Is Managed\fP
|
|
.XE
|
|
.LP
|
|
To determine the managed state of a given child widget, use
|
|
.PN XtIsManaged .
|
|
.LP
|
|
.IN "XtIsManaged" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
Boolean XtIsManaged(\fIw\fP)
|
|
.br
|
|
Widget \fIw\fP\^;
|
|
.FN
|
|
.IP \fIw\fP 1i
|
|
Specifies the widget. \*(oI
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN XtIsManaged
|
|
function returns
|
|
.PN True
|
|
if the specified widget is of class RectObj or any subclass thereof
|
|
and is managed, or
|
|
.PN False
|
|
otherwise.
|
|
|
|
.NH 2
|
|
Controlling When Widgets Get Mapped
|
|
.XS
|
|
\fB\*(SN Controlling When Widgets Get Mapped\fP
|
|
.XE
|
|
.LP
|
|
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 \fImap_when_managed\fP field to
|
|
.PN False .
|
|
.sp
|
|
.LP
|
|
To change the value of a given widget's \fImap_when_managed\fP field, use
|
|
.PN XtSetMappedWhenManaged .
|
|
.LP
|
|
.IN "XtSetMappedWhenManaged" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
void XtSetMappedWhenManaged(\fIw\fP, \fImap_when_managed\fP)
|
|
.br
|
|
Widget \fIw\fP;
|
|
.br
|
|
Boolean \fImap_when_managed\fP;
|
|
.FN
|
|
.IP \fIw\fP 1i
|
|
Specifies the widget. \*(cI
|
|
.IP \fImap_when_managed\fP 1i
|
|
Specifies a Boolean value that indicates the new value
|
|
that is stored into the widget's \fImap_when_managed\fP
|
|
field.
|
|
.LP
|
|
.eM
|
|
If the widget is realized and managed,
|
|
and if \fImap_when_managed\fP is
|
|
.PN True ,
|
|
.PN XtSetMappedWhenManaged
|
|
maps the window.
|
|
If the widget is realized and managed,
|
|
and if \fImap_when_managed\fP is
|
|
.PN False ,
|
|
it unmaps the window.
|
|
.PN XtSetMappedWhenManaged
|
|
is a convenience function that is equivalent to (but slightly faster than)
|
|
calling
|
|
.PN XtSetValues
|
|
and setting the new value for the XtNmappedWhenManaged resource
|
|
then mapping the widget as appropriate.
|
|
As an alternative to using
|
|
.PN XtSetMappedWhenManaged
|
|
to control mapping,
|
|
a client may set \fImapped_when_managed\fP to
|
|
.PN False
|
|
and use
|
|
.PN XtMapWidget
|
|
and
|
|
.PN XtUnmapWidget
|
|
explicitly.
|
|
.sp
|
|
.LP
|
|
To map a widget explicitly, use
|
|
.PN XtMapWidget .
|
|
.LP
|
|
.IN "XtMapWidget" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
XtMapWidget(\fIw\fP)
|
|
.br
|
|
Widget \fIw\fP\^;
|
|
.FN
|
|
.IP \fIw\fP 1i
|
|
Specifies the widget. \*(cI
|
|
.LP
|
|
.eM
|
|
To unmap a widget explicitly, use
|
|
.PN XtUnmapWidget .
|
|
.LP
|
|
.IN "XtUnmapWidget" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
XtUnmapWidget(\fIw\fP)
|
|
.br
|
|
Widget \fIw\fP\^;
|
|
.FN
|
|
.IP \fIw\fP 1i
|
|
Specifies the widget. \*(cI
|
|
.LP
|
|
.eM
|
|
|
|
.NH 2
|
|
Constrained Composite Widgets
|
|
.XS
|
|
\*(SN Constrained Composite Widgets
|
|
.XE
|
|
.LP
|
|
The Constraint
|
|
widget class is a subclass of
|
|
.PN compositeWidgetClass .
|
|
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.
|
|
.LP
|
|
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.
|
|
.LP
|
|
To make it easy for widgets and the \*(xI to keep track of the
|
|
constraints associated with a child,
|
|
every widget has a \fIconstraints\fP 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
|
|
.PN constraintWidgetClass ,
|
|
then the child's \fIconstraints\fP field is NULL.
|
|
.LP
|
|
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:
|
|
.LP
|
|
.Ds
|
|
.TA .5i 3i
|
|
.ta .5i 3i
|
|
typedef struct {
|
|
Dimension max_width, max_height;
|
|
} MaxConstraintPart;
|
|
|
|
typedef struct {
|
|
MaxConstraintPart max;
|
|
} MaxConstraintRecord, *MaxConstraint;
|
|
.De
|
|
.LP
|
|
A subclass of this widget class that also needs to maintain a minimum size would
|
|
define its constraint record as follows:
|
|
.LP
|
|
.Ds
|
|
.TA .5i 3i
|
|
.ta .5i 3i
|
|
typedef struct {
|
|
Dimension min_width, min_height;
|
|
} MinConstraintPart;
|
|
|
|
typedef struct {
|
|
MaxConstraintPart max;
|
|
MinConstraintPart min;
|
|
} MaxMinConstraintRecord, *MaxMinConstraint;
|
|
.De
|
|
.LP
|
|
Constraints are allocated, initialized, deallocated, and otherwise maintained
|
|
insofar as possible by the \*(xI.
|
|
The Constraint class record part has several entries that facilitate this.
|
|
All entries in
|
|
.PN ConstraintClassPart
|
|
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.
|
|
.LP
|
|
The
|
|
.PN XtCreateWidget
|
|
function uses the \fIconstraint_size\fP field in the parent's class record
|
|
to allocate a constraint record when a child is created.
|
|
.PN XtCreateWidget
|
|
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.
|
|
.LP
|
|
When the
|
|
.PN XtGetValues
|
|
and
|
|
.PN XtSetValues
|
|
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.
|
|
.PN XtSetValues
|
|
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
|
|
.PN ConstraintClassExtension
|
|
record in the
|
|
.PN ConstraintClassPart
|
|
\fIextension\fP
|
|
fields with a record type of
|
|
.PN \s-1NULLQUARK\s+1
|
|
and the \fIget_values_hook\fP field in
|
|
.IN "get_values_hook procedure"
|
|
.IN "Constraint" "get_values_hook"
|
|
the extension record is non-NULL,
|
|
.PN XtGetValues
|
|
calls the get_values_hook
|
|
procedure(s) to allow the parent to return derived constraint fields.
|
|
.LP
|
|
The
|
|
.PN XtDestroyWidget
|
|
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;
|
|
.PN XtDestroyWidget
|
|
does this automatically.
|
|
.bp
|