NAME

RectObj widget class − fundamental object class with geometry. 

SYNOPSIS

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

Private Header:<X11/RectObjP.h>

Class Name:RectObj

Class Hierarchy:Object → RectObj

Class Pointer:rectObjClass

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

Functions/Macros:XtIsRectObj()

AVAILABILITY

Release 4 and later. 

DESCRIPTION

RectObj is a direct subclass of Object.  It does not have a window, but does have a width, height, and location, and encapsulates the mechanisms for geometry management. 

RectObj can be subclassed to provide widget-like objects (sometimes called "gadgets") that do not use windows and that do not have features often unused in simple widgets.  This can save memory resources both in the server and in applications. 

See the "Background" section below for more information on using RectObj objects. 

NEW RESOURCES

RectObj defines the following resources:

XtNancestorSensitive
Specifies whether the object has an insensitive ancestor. Default value is the bitwise AND of the XtNsensitive and XtNancestorSensitive resources of the parent.  See XtSetSensitive(1). 

XtNborderWidth
Width (in pixels) of the window’s border.

XtNheight
Window height (in pixels), excluding the border.

XtNsensitive
Specifies whether a gadget receives input (is sensitive). XtSetSensitive() can be used to change a widget’s sensitivity and to guarantee that if a parent has its XtNsensitive resource set to False, then its children will have their XtNancestorSensitive resource set to False.  See XtSetSensitive(1). 

XtNwidth
Window width (in pixels), excluding the border.

XtNx
The x-coordinate of the widget’s upper-left outer corner, relative to the upper-left inner corner of its parent.

XtNy
The y-coordinate of the widget’s upper-left outer corner, relative to the upper-left inner corner of its parent.

INHERITED RESOURCES

RectObj inherits the following resource. 

CLASS STRUCTURE

The RectObj class structure is shown below.  Because the RectObj class was defined after Core was already standardized, the fields of these two class structures must match.  Therefore, the fields named rectn below exist only to pad out the structure.  The use of each of the remaining fields is exactly as for the Core class.  typedef struct _RectObjClassPart {  WidgetClass superclass;  String class_name;  Cardinal widget_size;  XtProc class_initialize;  XtWidgetClassProc class_part_initialize;  XtEnum class_inited;  XtInitProc initialize;  XtArgsProc initialize_hook;  XtProc rect1;  XtPointer rect2;  Cardinal rect3;  XtResourceList resources;  Cardinal num_resources;  XrmClass xrm_class;  Boolean rect4;  XtEnum rect5;  Boolean rect6;  Boolean rect7;  XtWidgetProc destroy;  XtWidgetProc resize;  XtExposeProc expose;  XtSetValuesFunc set_values;  XtArgsFunc set_values_hook;  XtAlmostProc set_values_almost;  XtArgsProc get_values_hook;  XtProc rect9;  XtVersionType version;  XtPointer callback_private;  String rect10;  XtGeometryHandler query_geometry;  XtProc rect11;  XtPointer extension ; } RectObjClassPart;
 
typedef struct _RectObjClassRec { RectObjClassPart rect_class; } RectObjClassRec, ∗RectObjClass; There is no extension defined for this class, and the extension field in the class part structure should be NULL. 

INSTANCE STRUCTURE

The RectObj instance structure contains at least the fields shown below.  The fields need not be in the order shown, but because the RectObj class was defined after Core was standardized, the position of each of these fields must be the same for both classes.  typedef struct _RectObjPart {  Position x, y;  Dimension width, height;  Dimension border_width;  Boolean managed;  Boolean sensitive;  Boolean ancestor_sensitive; } RectObjPart;
 
typedef struct _RectObjRec { ObjectPart object; RectObjPart rectangle; } RectObjRec;

BACKGROUND

In the following discussion, "RectObj" refers only to objects that are a subclass of RectObj and that are not a subclass of Core. 

Composite widget classes that wish to accept RectObj children must set the accepts_objects field in the CompositeClassExtension extension structure to True.  XtCreateWidget() will otherwise generate an error if called to create a non-widget child. 

If gadgets are defined in an object set, the parent is responsible for much more than the parent of a widget.  The parent must request and handle input events that occur for the gadget. The parent is also responsible for making sure that when it receives an expose event, the gadget children get drawn correctly. Subclasses of RectObj have expose procedures, but the parent is free to ignore them, instead drawing the contents of the child itself.  This can potentially save graphics context switching.  The precise contents of the Expose event and Region arguments to the RectObj expose procedure are not specified by the Intrinsics; a particular rectangle object is free to define not only the coordinate system origin (self-relative or parent-relative) but also whether the rectangle, the Region, or both are assumed to have been intersected by the visible region of the object. 

Normally, a composite widget that accepts non-widget children documents those children it can handle, since a gadget, unlike a widget, cannot be viewed as a completely self-contained entity.  Since a particular composite widget class is usually designed to handle gadgets of only a limited set of classes, it should check the classes of newly added children in its insert_child() method to make sure that it can deal with them. 

The Intrinsics will clear areas of a parent window obscured by RectObj children, causing Expose events, under the following circumstances:

•A RectObj child is managed or unmanaged. 

•In a call to XtSetValues() on a RectObj child, one or more of the set_values() methods returns True. 

•In a call to XtConfigureWidget() on a RectObj child, areas will be cleared corresponding to both the old and the new child geometries, including the border, if the geometry changes. 

•In a call to XtMoveWidget() on a RectObj child, areas will be cleared corresponding to both the old and the new child geometries, including the border, if the geometry changes. 

•In a call to XtResizeWidget() on a RectObj child, an single rectangle will be cleared corresponding to the larger of the old and the new child geometries, if they are different. 

•In a call to XtMakeGeometryRequest() (or XtMakeResizeRequest()) on a RectObj, if the manager returns XtGeometryYes, two rectangles will be cleared corresponding to both the old and the new child geometries. 

Stacking order is not supported for RectObjs.  If the child geometries overlap, Composite widgets with RectObj children can define any semantics desired, including making this an error. 

When a RectObj is playing the role of a widget, developers must be reminded to avoid making assumptions about the object passed in the Widget argument to a callback procedure. 

The WidgetClass arguments to the following functions may be rectObjClass or any subclass:

•XtCreateManagedWidget(), XtVaCreateManagedWidget()

The Widget arguments to the following functions may be of class RectObj or any subclass:

•XtConfigureWidget(), XtMoveWidget(), XtResizeWidget()

•XtMakeGeometryRequest(), XtMakeResizeRequest()

•XtManageChildren(), XtManageChild(), XtUnmanageChildren(), XtUnmanageChild()

•XtQueryGeometry()

•XtSetSensitive()

•XtTranslateCoords()

The return value of the following functions will be of class RectObj or a subclass:

•XtCreateManagedWidget(), XtVaCreateManagedWidget()

SEE ALSO

CoreUNIX SYSTEM V/68 and V/88 Release 4, ObjectUNIX SYSTEM V/68 and V/88 Release 4.