NAME

Constraint widget class − a widget that provides constraint resources for its children. 

SYNOPSIS

Public Headers:<X11/StringDefs.h>
<X11/Constraint.h>

Private Header:<X11/ConstraintP.h>

Class Name:Constraint

Class Hierarchy:Core → Composite → Constraint

Class Pointer:constraintWidgetClass

Instantiation:Constraint is an Intrinsics meta-class, and is not normally instantiated. 

Functions/Macros:XtIsConstraint()

DESCRIPTION

Constraint widgets are a subclass of compositeWidgetClass.  Their name is derived from the fact that they 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 as complicated as how other children should change if this child is moved or resized.  Constraint widgets let a parent define 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.  Accordingly, constraint resources may be included in the argument list or resource file just like any other resource for the child. 

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. 

To make it easy for widgets and the Intrinsics to keep track of the constraints associated with a child, every widget has a constraints field, which is the address of a parent-specific structure that contains constraint information about the child.  If a child’s parent is not a subclass of constraintWidgetClass, then the child’s constraints field is NULL. 

Note that the constraint data structures are transparent to the child; that is, when a child is managed by a parent that is a subclass of a constraint widget, there is no difference, as far as the child is concerned, from being managed by a normal composite widget. 

See the "Background" section below for more information on Constraint and constraint resources. 

NEW RESOURCES

Constraint defines no new resources. 

INHERITED RESOURCES

Constraint inherits the following resources.  The resources are listed alphabetically, along with the superclass that defines them. 

CLASS STRUCTURE

The Constraint class record is defined as follows: typedef struct {  XtResourceList resources; /∗ constraint resource list ∗/  Cardinal num_resources; /∗ number of constraints in list ∗/  Cardinal constraint_size; /∗ size of constraint record ∗/  XtInitProc initialize; /∗ constraint initialization ∗/  XtWidgetProc destroy; /∗ constraint destroy proc ∗/  XtSetValuesFunc set_values; /∗ constraint set_values proc ∗/  XtPointer extension; /∗ pointer to extension record ∗/ } ConstraintClassPart;
 
typedef struct { CoreClassPart core_class;  CompositeClassPart composite_class;  ConstraintClassPart constraint_class; } ConstraintClassRec, ∗ConstraintWidgetClass; The fields of the Constraint class part have the following meanings:

resources
An array of XtResource, each of which defines a single constraint resource for the widget class.  See XtGetApplicationResources() for an explanation of how to define resources and declare an XtResourceList. 

num_resources
The number of element in the resources array. 

constraint_size
The size of the constraint instance record for this widget class.  A block this size will be automatically allocated for each child of an instance of this widget class, and will be pointed to by that child’s Core constraints instance field.  Use sizeof to initialize this field. 

initialize()
The constraint initialize() method, called to initialize the part of constraint instance record added by this widget class.  See the reference page in Section 4.  This is a chained method and cannot be inherited.  Use NULL if the constraint part defined by this class does not need any initialization. 

destroy()
The constraint destroy() method, called to deallocate any memory or other resources associated with the part of the constraint instance record added by this widget class when a child widget is destroyed.  See the reference page in Section 4.  This is a chained method and cannot be inherited.  Use NULL if the constraint part defined by this class does not need any special deallocation. 

set_values()
The constraint set_values() method, called when XtSetValues() is called on a child widget.  See the reference page in Section 4.  This is a chained method and cannot be inherited.  Use NULL if the constraint part defined by this class does not have any resources. 

extension
A linked list of extension records, or NULL.  There is currently one extension defined for Constraint which adds a get_values_hook() method; see below. 

EXTENSION STRUCTURE

The Intrinsics define one extension to Constraint: typedef struct {  XtPointer next_extension;    /∗ next record is linked list, or NULL ∗/  XrmQuark record_type;        /∗ NULLQUARK ∗/  long version;                /∗ XtConstraintExtensionVersion ∗/  Cardinal record_size;        /∗ use sizeof() ∗/  XtArgsProc get_values_hook; } ConstraintClassExtensionRec, ∗ConstraintClassExtension; The record_type field should be NULLQUARK, the version field should be XtConstraintExtensionVersion, and the get_values_hook() field should be the get_values_hook() method for the constraint resources.  See Constraint get_values_hook(4). 

INSTANCE STRUCTURE

The Constraint instance structure defines no new fields: typedef struct _ConstraintPart {  XtPointer dummy; /∗ No new fields, keep C compiler happy ∗/ } ConstraintPart;
 
typedef struct { CorePart core;  CompositePart composite;  ConstraintPart constraint; } ConstraintRec, ∗ConstraintWidget;

BACKGROUND

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 ConstraintClassPart are information and procedures that are defined and implemented by the parent, but they are called whenever actions are performed on the parent’s children. 

The XtCreateWidget() function uses the constraint_size field to allocate a constraint record when a child is created.  The constraint_size field gives the number of bytes occupied by a constraint record.  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() methods 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. 

The XtGetValues() and XtSetValues() functions use the constraint resources to get the values or set the values of constraint associated with a child.  XtSetValues() then calls the constraint set_values() methods so that a parent can recompute derived constraint fields and move or resize the child as appropriate. 

If the Constraint widget or any of its superclasses have declared a ConstraintClassExtension record in the constraint class part extension fields with a record type of NULLQUARK, and if the get_values_hook() field in the extension record is non-NULL, then XtGetValues() calls the get_values_hook() method(s) to allow the parent to return derived constraint fields. 

The XtDestroyWidget() function calls the constraint destroy method to deallocate any dynamic storage associated with a constraint record.  The constraint record itself must not be deallocated by the constraint destroy method; XtDestroyWidget() does this automatically. 

SEE ALSO

CoreUNIX SYSTEM V/68 and V/88 Release 4, CompositeUNIX SYSTEM V/68 and V/88 Release 4,
Constraint destroyUNIX SYSTEM V/68 and V/88 Release 4, Constraint get_values_hookUNIX SYSTEM V/68 and V/88 Release 4, Constraint initializeUNIX SYSTEM V/68 and V/88 Release 4, Constraint set_valuesUNIX SYSTEM V/68 and V/88 Release 4.