PtContainer

Layout and geometry management for all container widgets

Class hierarchy:

PtWidget --> PtBasic --> PtContainer

Immediate subclasses:

• PtBkgd
• PtClient
• PtCompound
• PtDisjoint
• PtFlash
• PtFontSel
• PtGroup
• PtOSContainer
• PtPane
• PtPanelGroup
• PtPrintSel
• PtScrollArea
• PtTerminal
• PtToolbar
• PtToolbarGroup

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

PhAB icon:

None -- not normally instantiated.

Public header:

<photon/PtContainer.h>

Description:

The PtContainer superclass provides layout and geometry management for all container widgets. It also redirects certain events -- such as button presses, releases, repeats, and keys -- to the child that has focus.

New resources:

Pt_ARG_CONTAINER_FLAGS

Flags that control the look and behavior of the container:

Pt_AUTO_EXTENT

Cause the container to recalculate its preferred size when any of its children are realized, unrealized, moved, or resized.

Pt_BLOCK_CUA_FOCUS

Prevent Common User Access from moving focus into this container.

Pt_DISABLE_BALLOONS

Prevent balloons from being inflated in this or any child container.

Pt_ENABLE_CUA

Let CUA keys function in this container (and its children).

Pt_ENABLE_CUA_ARROWS

Permit arrow-key navigation in this container (and its children).

Pt_ETCH_TITLE_AREA

Display an etched line below the title given by Pt_ARG_TITLE, provided that Pt_SHOW_TITLE is also set.

Pt_GRADIENT_TITLE_AREA

Display a gradient behind the title given by Pt_ARG_TITLE, provided that Pt_SHOW_TITLE is also set.

Pt_HOTKEYS_FIRST

Process key events that reach this container as hotkeys before passing them to any children. If the key is a hotkey, the event is consumed and isn't passed to any children. Normally the key is passed to the children and, if not consumed, is processed as a hotkey.

Pt_HOTKEY_TERMINATOR

Prevent hotkey searches from going to parents of this container. Note that this flag works only if it's set in a disjoint container-class widget.

Pt_SHOW_TITLE

Display the title given by Pt_ARG_TITLE, using the font specified by Pt_ARG_TITLE_FONT.

Pt_ARG_CURSOR_OVERRIDE

Let the container's cursor override its children's cursors.

Pt_ARG_TITLE

The title to be displayed if Pt_SHOW_TITLE is set in Pt_ARG_CONTAINER_FLAGS.

Pt_ARG_TITLE_FONT

The font to use for the label's text string; see PgSetFont() in the Photon Library Reference.

Pt_CB_BALLOONS

A list of PtBalloonCallback_t structures that define balloon callbacks that the container invokes if the pointer remains motionless for 1.25 seconds over the widget specified in the callback structure.

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

reason

Pt_CB_BALLOONS

reason_subtype

Pt_INFLATE_BALLOON when the balloon should be displayed, or Pt_POP_BALLOON when it should be removed.

event

A pointer to a PhEvent_t structure that describes the event that caused the callback to be invoked.

cbdata

NULL

These callbacks (unlike other callbacks) return nothing.

By default, this callback list invokes the indicated widget's inflate function, which is specified by the following resources:

• Pt_ARG_LABEL_BALLOON (PtLabel and its subclasses)
• Pt_ARG_LIST_BALLOON (PtList)
• Pt_ARG_TREE_BALLOON (PtTree)

When a container has balloons registered, it becomes sensitive to Ph_EV_BOUNDARY events. When the container sees an enter event, it enables the balloon mechanism for that container. When a boundary event with a subtype of Ph_EV_PTR_STEADY is received and it's over a widget that has registered a balloon, the balloons are flagged as active and the widget's inflate function is called.

While the balloons are active, Ph_EV_PTR_MOTION_NOBUTTON events are used to determine when the cursor leaves a widget with an inflated balloon (its inflate function is called with a Pt_POP_BALLOON subtype). While the balloons are active, any widget that has a balloon that intersects with a Ph_EV_PTR_MOTION_NOBUTTON event has its balloon inflated.

Key events and pointer button events deactivate the balloons. Another Ph_EV_PTR_STEADY event over a widget with a balloon is required to reactivate the balloons.

If your application has a widget that obscures the container, the widget must have a region that consumes Ph_EV_BOUNDARY events to prevent the balloon mechanism for the container from becoming enabled and activated. This can be done by giving the overlapping widget a Pt_CB_RAW callback (see PtWidget) that's sensitive to Ph_EV_BOUNDARY events, or by giving the overlapping widget a cursor (which automatically sets Ph_FORCE_BOUNDARY in the flags for the widget's region, which means it's opaque to boundary events).

Pt_CB_CHILD_ADDED_REMOVED

A list of PtCallback_t structures that define the callbacks that are invoked when a widget is added or removed from a container:

• When a child is being added to the container, these callbacks are invoked after the child has been completely added to the widget family hierarchy and has been realized (if applicable).
• When a child is being removed from the container, these callbacks are invoked after the child has been unrealized. If the child is being destroyed, these callbacks are invoked before the child is freed (i.e. the pointer to the child is still valid, but the child has Pt_DESTROYED set in its Pt_ARG_FLAGS.

These callbacks are invoked only if: Pt_CALLBACKS_ACTIVE is set in the container's Pt_ARG_FLAGS. Pt_PROCREATED isn't set in the Pt_ARG_FLAGS of the child being added or removed.

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

reason

Pt_CB_CHILD_ADDED_REMOVED

reason_subtype

Pt_CHILD_ADDED or Pt_CHILD_REMOVED.

event

Not used (NULL).

cbdata

A pointer to the widget being added or removed (i.e. the new or former child widget).

Pt_CB_RESIZE

A list of PtCallback_t structures that define the callbacks that the container invokes when its size changes. Each callback is passed a PtCallbackInfo_t structure that contains at least the following members:

reason

Pt_CB_RESIZE

reason_subtype

0 (not used).

event

Not used (NULL).

cbdata

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

PhRect_t old_size;

A PhRect_t structure (see the Photon Library Reference that contains the extent of the container before the size changed.

PhRect_t new_size;

A PhRect_t structure that contains the new extent of the container after the size changed.

PhDim_t old_dim

A PhDim_t structure that contains the dimensions of the container before the size changed.

PhDim_t new_dim

A PhDim_t structure that contains the dimensions of the container after the size changed.

These callbacks should return Pt_CONTINUE.

Inherited resources:

If the widget modifies an inherited resource, the "Default override" column indicates the new value. This modification affects any subclasses of the widget.