PtDivider

A container that divides space among its children

Class hierarchy:

PtWidget --> PtBasic --> PtContainer --> PtCompound --> PtDivider

For more information, see the diagram of the widget hierarchy.

PhAB icon:

Public header:

<photon/PtDivider.h>

Description:

The PtDivider widget is a container that lays out its children like a one-row or one-column PtGroup widget, but allows the user to resize the children by dragging "handles" placed between the children.

Two PtDivider widgets: one contains a scroll area and two lists, the other contains some buttons.

The PtDivider class inherits resources from the PtGroup class. Access to these resources is controlled through PtDivider's exporting mechanism.

A blocking mechanism lets PtDivider block the inheritance of certain resources from its subordinate PtGroup widget. This prevents any actions that would negatively affect the look and behavior of a PtDivider widget. For more information, see the "Exported subordinate children" section.

New resources:

Pt_ARG_DIVIDER_FLAGS

Possible values:

Pt_DIVIDER_NORESIZE

Don't resize the children, just invoke the callback.

Pt_DIVIDER_RESIZE_BOTH

Resize both widgets: the one to the left and to the right (or above and below) the dragged handle. If this flag isn't set, only the left child will be resized and the right child will be moved.

Pt_DIVIDER_INVISIBLE

Never display the drag outline. This flag is useful mainly when Pt_DIVIDER_NORESIZE is also set.

Pt_ARG_DIVIDER_OFFSET

This number is added to positions of child widgets (relative to the position of the PtDivider widget) when the values for the Pt_ARG_DIVIDER_SIZES resource are calculated. By setting the Pt_ARG_DIVIDER_OFFSET resource you can make the Pt_ARG_DIVIDER_SIZES resource relative to any arbitrary point.

Pt_ARG_DIVIDER_SIZES (read-only)

The array of positions and sizes of realized children of the divider. Each PtDividerSizes_t structure contains:

short from

The left side or top of the child, depending on the divider's orientation.

short to

The right or bottom of the child, depending on the divider's orientation.

Pt_CB_DIVIDER_DRAG

A list of callbacks that are invoked after each drag event received by the widget.

If the widget has the Pt_CALLBACKS_ACTIVE bit set in its Pt_ARG_FLAGS resource, these callbacks are also invoked when the size of a child is changed by a call to PtSetResources().

Each callback is passed a PtCallbackInfo_t structure that contains at least the following members:

reason

The name of the callback resource that caused this callback to be invoked (Pt_CB_DIVIDER_DRAG in this case).

reason_subtype

The subtype of the drag event (see Ph_EV_DRAG in the description of the PhEvent_t structure in the Photon Library Reference), or Pt_CB_DIVIDER_SETRESOURCES if a child is being resized through PtSetResources() and the widget has the Pt_CALLBACKS_ACTIVE bit set in its Pt_ARG_FLAGS resource.

event

The received drag event, or NULL if a child is being resized through PtSetResources().

cbdata

A pointer to a PtDividerCallback_t structure that contains at least the following members:

PtWidget_t *left, *right;

The two widgets in the group separated by the divider.

int moved;

How far the widget on the right has been moved.

int resized;

The amount by which the widget on the left has been resized.

PtDividerSizes_t const *sizes;

The new value of the Pt_ARG_DIVIDER_SIZES resource.

int nsizes;

The number of items in the sizes array.

These callbacks should return Pt_CONTINUE.

Exported subordinate children:

Unless the resources are already defined in PtDivider, the PtDivider class uses the resources of its exported subordinate child, PtGroup.

Where PtDivider and PtGroup both define resources having the same name, the resource defined in PtDivider takes precedence.

Inherited resources:

If PtDivider modifies an inherited resource, the "Default override" column indicates the new value. If PtDivider inherits a resource from PtGroup, the default value assigned by PtGroup is inherited too; the "Default override" column shows this default value.

Pt_ARG_BANDWIDTH_THRESHOLD

Defines the "graphics bandwidth" threshold that determines whether the widget will resize the children after each received drag event or only once, when the drag is completed - see PtQuerySystemInfo().

Pt_ARG_GROUP_ORIENTATION

The value of this resource can only be Pt_GROUP_HORIZONTAL or Pt_GROUP_VERTICAL.