PtContainer

Anchoring, layout, and geometry management for all container widgets

Class hierarchy:

PtWidget --> PtBasic --> PtContainer

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 anchoring, layout, and geometry management for all container widgets. It also redirects certain events-such as button press, release, repeat, and keys-to the child that has focus.

New resources:

Pt_ARG_ANCHOR_FLAGS

This resource specifies how the container is anchored to its parent. The possible values are:

Pt_LEFT_ANCHORED_RELATIVE

Interpret the upper-left x component of Pt_ARG_ANCHOR_OFFSETS as 1/100 of a percent. A value of 10000, for example, would equal 1 percent.

Pt_RIGHT_ANCHORED_RELATIVE

Interpret the lower-right x component of Pt_ARG_ANCHOR_OFFSETS as 1/100 of a percent.

Pt_TOP_ANCHORED_RELATIVE

Interpret the upper-left y component of Pt_ARG_ANCHOR_OFFSETS as 1/100 of a percent.

Pt_BOTTOM_ANCHORED_RELATIVE

Interpret the lower-right y component of Pt_ARG_ANCHOR_OFFSETS as 1/100 of a percent.

Pt_LEFT_ANCHORED_RIGHT

Anchor the container's left extent to the right edge of its parent's canvas.

Pt_RIGHT_ANCHORED_RIGHT

Anchor the container's right extent to the right edge of its parent's canvas.

Pt_TOP_ANCHORED_BOTTOM

Anchor the container's top extent to the bottom edge of its parent's canvas.

Pt_BOTTOM_ANCHORED_BOTTOM

Anchor the container's bottom extent to the bottom edge of its parent's canvas.

Pt_LEFT_ANCHORED_LEFT

Anchor the container's left extent to the left edge of its parent's canvas.

Pt_RIGHT_ANCHORED_LEFT

Anchor the container's right extent to the left edge of its parent's canvas.

Pt_TOP_ANCHORED_TOP

Anchor the container's top extent to the top edge of its parent's canvas.

Pt_BOTTOM_ANCHORED_TOP

Anchor the container's bottom extent to the top edge of its parent's canvas.

Pt_BALLOONS_ON

If a child widget has been assigned a balloon, pop up the balloon as soon as the mouse pointer passes over the child widget; otherwise delay the pop up for 1.25 seconds.

Anchors override any Pt_ARG_RESIZE_FLAGS settings that conflict with Pt_ARG_ANCHOR_OFFSETS or Pt_ARG_ANCHOR_FLAGS settings. If there is no conflict, the Pt_ARG_RESIZE_FLAGS settings will be honored.

Pt_ARG_ANCHOR_OFFSETS

The four values in this structure determine the anchor offsets of each of the container's sides. (An anchor offset is the distance between the anchoring side of the parent and corresponding side of the child.) Depending on the anchor flags you specify, the offsets will be either absolute or relative.

The Pt_ARG_ANCHOR_OFFSETS resource isn't displayed in PhAB because PhAB sets it automatically.

If a side is anchored, its anchor offsets, if explicitly specified, will override the Pt_ARG_AREA and Pt_ARG_DIM resources.

Only offsets that have a corresponding bit set in the Pt_ARG_ANCHOR_FLAGS resource are applied. For example, let's say you have a Pt_ARG_ANCHOR_OFFSETS resource of (5,10,20,25) with absolute anchoring and a Pt_ARG_ANCHOR_FLAGS resource of Pt_LEFT_ANCHORED_LEFT | Pt_RIGHT_ANCHORED_RIGHT | Pt_TOP_ANCHORED_TOP | Pt_BOTTOM_ANCHORED_BOTTOM. In that case, the pane's extent will be:

• 5 pixels from its parent's left canvas edge
• 10 pixels from its parent's top canvas edge
• 20 pixels from its parent's right canvas edge
• and 25 pixels from its parent's bottom canvas edge

This will remain true even as the parent is resized.

Anchors override any Pt_ARG_RESIZE_FLAGS settings that conflict with Pt_ARG_ANCHOR_OFFSETS or Pt_ARG_ANCHOR_FLAGS settings. If there is no conflict, the Pt_ARG_RESIZE_FLAGS settings will be honored.

Pt_ARG_CONTAINER_FLAGS

This resource controls the look and behavior of the container. Valid bits include:

Pt_DISABLE_BALLOONS

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

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_HOTKEYS_FIRST

Key events that reach this container are processed as hotkeys before being passed 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_BLOCK_CUA_FOCUS

Prevent CUA from focusing on this container.

Pt_AUTO_EXTENT

Cause the container to reextent when any of its children are realized, moved, or resized.

Pt_ENABLE_CUA

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

Pt_ENABLE_CUA_ARROWS

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

Pt_CB_BALLOONS

A list of 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

A value of Pt_CB_BALLOONS.

reason_subtype

A value of Pt_INFLATE_BALLOON when the balloon should be displayed, or Pt_POP_BALLOON when the balloon should be removed.

cbdata

A value of NULL.

These callbacks should return Pt_CONTINUE.

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

• Pt_ARG_BITMAP_BALLOON (PtBitmap)
• 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 raw callback that's sensitive to Ph_EV_BOUNDARY, 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_FILTER

A list of raw callbacks invoked when an event that matches the provided event mask is to be passed to a child of the container.

These callbacks are invoked before the event is passed to the child. Contrast this resource with the Pt_CB_RAW resource defined for PtWidget.

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

reason

Pt_CB_FILTER

reason_subtype

0 (not used).

cbdata

A value of NULL.

These callbacks should return:

• Pt_CONTINUE to pass the event to the child

  Or

• Pt_END to prevent any child from seeing the event.

Here's some sample code that adds a Pt_CB_FILTER callback to a widget:

PtRawCallback_t cb;
PtArg_t arg;

cb.event_mask = Ph_EV_KEY;
cb.event_f = my_callback_function;
cb.data = whatever;
PtSetArg( &arg, Pt_CB_FILTER, &cb, 1 );
PtSetResources( widget, 1, &arg );

Pt_CB_RESIZE

A list of 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).

cbdata

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

PhRect_t old_size;

The extent of the container before the size has changed.

PhRect_t new_size;

The new extent of the container after the size has 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.

Pt_ARG_RESIZE_FLAGS

Anchors override any Pt_ARG_RESIZE_FLAGS settings that conflict with Pt_ARG_ANCHOR_OFFSETS or Pt_ARG_ANCHOR_FLAGS settings. If there is no conflict, the Pt_ARG_RESIZE_FLAGS settings will be honored.