PtContainer

`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.

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:

Resource	C type	Pt type	Default
Pt_ARG_ANCHOR_FLAGS	`unsigned`	Flag	0
Pt_ARG_ANCHOR_OFFSETS	`PhRect_t`	Struct	0, 0, 0, 0
Pt_ARG_CONTAINER_FLAGS	`long`	Flag	Pt_ENABLE_CUA
Pt_CB_BALLOONS	`PtBalloonCallback_t *`	Link	NULL
Pt_CB_FILTER	`PtRawCallback_t *`	Link	NULL
Pt_CB_RESIZE	`PtCallback_t *`	Link	NULL

Pt_ARG_ANCHOR_FLAGS

C type	Pt type	Default
`unsigned`	Flag	0

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

C type	Pt type	Default
`PhRect_t`	Struct	0, 0, 0, 0

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.

Pt_ARG_CONTAINER_FLAGS

C type	Pt type	Default
`long`	Flag	Pt_ENABLE_CUA

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

C type	Pt type	Default
`PtBalloonCallback_t *`	Link	NULL

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

C type	Pt type	Default
`PtRawCallback_t *`	Link	NULL

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

C type	Pt type	Default
`PtCallback_t *`	Link	NULL

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.

Resource	Inherited from	Default override
Pt_ARG_AREA	`PtWidget`
Pt_ARG_BANDWIDTH_THRESHOLD	`PtBasic`	Not used by this class.
Pt_ARG_BITMAP_CURSOR	`PtWidget`
Pt_ARG_BORDER_WIDTH	`PtWidget`	0
Pt_ARG_BOT_BORDER_COLOR	`PtBasic`
Pt_ARG_COLOR	`PtBasic`
Pt_ARG_CURSOR_COLOR	`PtWidget`
Pt_ARG_CURSOR_TYPE	`PtWidget`
Pt_ARG_DATA	`PtWidget`
Pt_ARG_DIM	`PtWidget`
Pt_ARG_EFLAGS	`PtWidget`	Pt_CONSUME_EVENTS
Pt_ARG_FILL_COLOR	`PtBasic`
Pt_ARG_FILL_PATTERN	`PtBasic`
Pt_ARG_FLAGS	`PtWidget`
Pt_ARG_HELP_TOPIC	`PtWidget`
Pt_ARG_HIGHLIGHT_ROUNDNESS	`PtBasic`
Pt_ARG_MARGIN_HEIGHT	`PtBasic`
Pt_ARG_MARGIN_WIDTH	`PtBasic`
Pt_ARG_POS	`PtWidget`
Pt_ARG_RESIZE_FLAGS	`PtWidget`	Pt_RESIZE_XY_AS_REQUIRED (see below)
Pt_ARG_TOP_BORDER_COLOR	`PtBasic`
Pt_ARG_TRANS_PATTERN	`PtBasic`
Pt_ARG_USER_DATA	`PtWidget`
Pt_CB_ACTIVATE	`PtBasic`
Pt_CB_ARM	`PtBasic`
Pt_CB_BLOCKED	`PtWidget`
Pt_CB_DESTROYED	`PtWidget`
Pt_CB_DISARM	`PtBasic`
Pt_CB_GOT_FOCUS	`PtBasic`
Pt_CB_HOTKEY	`PtWidget`
Pt_CB_LOST_FOCUS	`PtBasic`
Pt_CB_MENU	`PtBasic`
Pt_CB_RAW	`PtWidget`
Pt_CB_REALIZED	`PtWidget`
Pt_CB_REPEAT	`PtBasic`
Pt_CB_UNREALIZED	`PtWidget`

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.

QNX Community Resources

`PtContainer`

Class hierarchy:

PhAB icon:

Public header:

Description:

New resources:

Pt_ARG_ANCHOR_FLAGS

Pt_ARG_ANCHOR_OFFSETS

Pt_ARG_CONTAINER_FLAGS

Pt_CB_BALLOONS

Pt_CB_FILTER

Pt_CB_RESIZE

Inherited resources: