Caution: This version of this document is no longer maintained. For the latest documentation, see http://www.qnx.com/developers/docs.

PtContainer

Layout and geometry management for all container widgets

Class hierarchy:

PtWidgetPtBasicPtContainer

Immediate subclasses:

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

PhAB icon:

PtContainer button in PhAB

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:

Resource C type Pt type Default
Pt_ARG_CONTAINER_FLAGS long Flag Pt_ENABLE_CUA | Pt_ENABLE_CUA_ARROWS
Pt_ARG_CURSOR_OVERRIDE int Boolean Pt_FALSE
Pt_ARG_FILL_LAYOUT_INFO PtFillLayoutInfo_t * Struct NULL
Pt_ARG_GRID_LAYOUT_INFO PtGridLayoutInfo_t * Struct NULL
Pt_ARG_LAYOUT PtLayoutDefinition_t * Struct NULL
Pt_ARG_LAYOUT_INFO void * Struct NULL
Pt_ARG_LAYOUT_TYPE int Scalar NULL
Pt_ARG_ROW_LAYOUT_INFO PtRowLayoutInfo_t * Struct NULL
Pt_ARG_TITLE char * String NULL
Pt_ARG_TITLE_FONT char * String "TextFont09"
Pt_CB_BALLOONS PtBalloonCallback_t * Link NULL
Pt_CB_CHILD_ADDED_REMOVED PtCallback_t * Link NULL
Pt_CB_CHILD_GETTING_FOCUS PtCallback_t * Link NULL
Pt_CB_CHILD_LOSING_FOCUS PtCallback_t * Link NULL
Pt_CB_LAYOUT PtCallback_t * Link NULL
Pt_CB_RESIZE PtCallback_t * Link NULL

Pt_ARG_CONTAINER_FLAGS

C type Pt type Default
long Flag Pt_ENABLE_CUA | Pt_ENABLE_CUA_ARROWS

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

C type Pt type Default
int Boolean Pt_FALSE

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

Pt_ARG_LAYOUT

C type Pt type Default
PtLayoutDefinition_t * Struct NULL

A generic resource that lets you set the active layout for the container, and the layout info structure at the same time. This is an alternative to setting Pt_ARG_LAYOUT_TYPE and Pt_ARG_*_LAYOUT_INFO separately.

This resource can be one of:

When you set this resource using PtSetResource() or PtSetArg(), you can optionally also set the Pt_ARG_*_LAYOUT_INFO resource for the appropriate layout type using the len argument. To do this, pass a pointer to layout information structure appropriate to the layout type as len. It can be one of:

For more information about using layouts and layout resources, see Using Layouts in Geometry Management in the Photon Programmer's Guide.

Pt_ARG_LAYOUT_INFO

C type Pt type Default
void * Struct NULL

A generic resource that lets you set the information structure for layouts. When you set this resource, you must set the len argument of PtSetResource() or PtSetArg() to the layout type, which is one of:

For more information about using layouts and layout resources, see Using Layouts in Geometry Management in the Photon Programmer's Guide.

Pt_ARG_LAYOUT_TYPE

C type Pt type Default
int Scalar NULL

An alternative way of setting or getting the active layout and layout information.

When you set this resource, the value argument of PtSetResource() or PtSetArg() can be one of:

You can optionally also set the information structure with this resource. To do this, set the len argument of PtSetResource() or PtSetArg() to the layout information structure, Pt*LayoutInfo_t. If you set len to NULL, the information structure for the current layout is set. In this case, make sure that the layout information structure you set matches the current layout type, or your application may crash.

For more information about using layouts and layout resources, see Using Layouts in Geometry Management in the Photon Programmer's Guide.

Pt_ARG_FILL_LAYOUT_INFO

C type Pt type Default
PtFillLayoutInfo_t Struct NULL

The information structure for the PtFillLayout layout type. You can set this resource directly, or via Pt_ARG_LAYOUT_INFO.

The PtFillLayoutInfo_t contains at least these members:

short type

Direction of layout:

short spacing

Distance between children, in pixels

There is no layout data for children for this layout type.

For more information about using layouts and layout resources, see Using Layouts in Geometry Management in the Photon Programmer's Guide.

Pt_ARG_ROW_LAYOUT_INFO

C type Pt type Default
PtRowLayoutInfo_t Struct NULL

The information structure for the PtRowLayout layout type. You can set this resource directly, or via Pt_ARG_LAYOUT_INFO.

PtRowLayoutInfo_t contains at least these members:

short type

Direction of layout:

short flags

A combination of the following flags:

PhRect_t margins
Container margins in pixels, where:
short h_spacing
Horizontal spacing distance between children, in pixels
short v_spacing
Vertical spacing between children, in pixels

Note:

You can use PtRowLayoutInfoDflts to initialize your copy of PtRowLayoutInfo_t. It has the following values:

type = Pt_LAYOUT_HORIZONTAL

flags = Pt_ROW_PACK | Pt_ROW_WRAP

margin.ul.x = margin.ul.y = margin.lr.x = margin.lr.y = 3

h_spacing = v_spacing = 3


For more information about using layouts and layout resources, see Using Layouts in Geometry Management in the Photon Programmer's Guide.

Pt_ARG_GRID_LAYOUT_INFO

C type Pt type Default
PtGridLayoutInfo_t Struct NULL

The information structure for the PtGridLayout layout type. You can set this resource directly, or via Pt_ARG_LAYOUT_INFO.

PtGridLayoutInfo_t contains at least these members:

unsigned n_cols
The number of columns in the grid.
unsigned flags
Combination of the following flags:
PhRect_t margins
Container margins in pixels, where:
short h_spacing
Horizontal spacing between columns, in pixels.
short v_spacing
Vertical spacing between rows, in pixels.

Note:

You can use PtGridLayoutInfoDflts to initialize your copy of PtGridLayoutInfo_t. It has the following values:

  • n_cols = 1
  • flags = 0
  • margin.ul.x = margin.ul.y = margin.lr.x = margin.lr.y = 2
  • h_spacing = v_spacing = 2

For more information about using layouts and layout resources, see Using Layouts in Geometry Management in the Photon Programmer's Guide.

Pt_ARG_TITLE

C type Pt type Default
char * String NULL

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

Pt_ARG_TITLE_FONT

C type Pt type Default
char * String "TextFont09"

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

Pt_CB_BALLOONS

C type Pt type Default
PtBalloonCallback_t * Link NULL

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

Note: 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:

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.


Note: 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

C type Pt type Default
PtCallback_t * Link NULL

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


Note: 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_CHILD_GETTING_FOCUS

C type Pt type Default
PtCallback_t * Link NULL

A list of PtCallback_t structures that define the callbacks invoked when a child widget (or child of a child and so on) is getting focus. You can call PtIsFocused() to find the current focus state of any widget.

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

reason
Pt_CB_CHILD_GETTING_FOCUS
reason_subtype
0 (not used).
event
A pointer to a PhEvent_t structure that describes the event that caused the callback to be invoked.
cbdata
NULL, or a pointer to a PtFocusInfo_t. PtFocusInfo_t contains at least:
PtWidget_t *src
A pointer to the widget which is losing focus. This pointer could be NULL.
PtWidget_t *dst
A pointer to the widget which is intended to get the focus. This pointer could be NULL, for example if PtContainerNullFocus() was invoked.
PtWidget_t *child
A pointer to the immediate child of the called container callback.

These callbacks should return:

Pt_CB_CHILD_LOSING_FOCUS

C type Pt type Default
PtCallback_t * Link NULL

A list of PtCallback_t structures that define the callbacks invoked when a child widget (or child of a child and so on) is losing focus. You can call PtIsFocused() to find the current focus state of any widget.

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

reason
Pt_CB_CHILD_LOSING_FOCUS
reason_subtype
0 (not used).
event
A pointer to a PhEvent_t structure that describes the event that caused the callback to be invoked.
cbdata
NULL, or a pointer to a PtFocusInfo_t. PtFocusInfo_t contains at least:
PtWidget_t *src
A pointer to the widget which is losing focus. This pointer could be NULL.
PtWidget_t *dst
A pointer to the widget which is intended to get the focus. This pointer could be NULL, for example if PtContainerNullFocus() was invoked.
PtWidget_t *child
A pointer to the immediate child of the called container callback.

These callbacks should return:

Pt_CB_LAYOUT

C type Pt type Default
PtCallback_t * Link NULL

A list of PtCallback_t structures that define the callbacks invoked when the widget is about to start laying out children, and when the widget is finished laying out children.

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

reason
Pt_CB_LAYOUT
reason_subtype
event
A pointer to a PhEvent_t structure filled with NULLs
cbdata
NULL

These callbacks should return Pt_CONTINUE.

Pt_CB_RESIZE

C type Pt type Default
PtCallback_t * Link NULL

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.

Resource Inherited from Default override
Pt_ARG_ANCHOR_FLAGS PtWidget
Pt_ARG_ANCHOR_OFFSETS PtWidget
Pt_ARG_AREA PtWidget
Pt_ARG_BANDWIDTH_THRESHOLD PtBasic Not used by this class.
Pt_ARG_BASIC_FLAGS PtBasic
Pt_ARG_BEVEL_WIDTH PtWidget 0
Pt_ARG_BITMAP_CURSOR PtWidget
Pt_ARG_BEVEL_COLOR PtBasic
Pt_ARG_BEVEL_CONTRAST PtBasic
Pt_ARG_COLOR PtBasic
Pt_ARG_CONTRAST PtBasic
Pt_ARG_CURSOR_COLOR PtWidget
Pt_ARG_CURSOR_TYPE PtWidget
Pt_ARG_DARK_BEVEL_COLOR PtBasic
Pt_ARG_DARK_FILL_COLOR PtBasic
Pt_ARG_DATA PtWidget
Pt_ARG_DIM PtWidget
Pt_ARG_EFLAGS PtWidget Pt_CONSUME_EVENTS
Pt_ARG_EXTENT PtWidget
Pt_ARG_FILL_COLOR PtBasic
Pt_ARG_FILL_PATTERN PtBasic
Pt_ARG_FLAGS PtWidget
Pt_ARG_GRID_LAYOUT_DATA PtWidget
Pt_ARG_HEIGHT PtWidget
Pt_ARG_HELP_TOPIC PtWidget
Pt_ARG_HIGHLIGHT_ROUNDNESS PtBasic
Pt_ARG_INLINE_COLOR PtBasic
Pt_ARG_LAYOUT_DATA PtWidget
Pt_ARG_LIGHT_BEVEL_COLOR PtBasic
Pt_ARG_LIGHT_FILL_COLOR PtBasic
Pt_ARG_MARGIN_HEIGHT PtBasic
Pt_ARG_MARGIN_WIDTH PtBasic
Pt_ARG_MAXIMUM_DIM PtWidget
Pt_ARG_MINIMUM_DIM PtWidget
Pt_ARG_OUTLINE_COLOR PtBasic
Pt_ARG_POINTER PtWidget
Pt_ARG_POS PtWidget
Pt_ARG_RESIZE_FLAGS PtWidget
Pt_ARG_ROW_LAYOUT_DATA PtWidget
Pt_ARG_STYLE PtBasic
Pt_ARG_TRANS_PATTERN PtBasic
Pt_ARG_USER_DATA PtWidget
Pt_ARG_WIDTH PtWidget
Pt_CB_ACTIVATE PtBasic
Pt_CB_ARM PtBasic
Pt_CB_BLOCKED PtWidget
Pt_CB_DESTROYED PtWidget
Pt_CB_DISARM PtBasic
Pt_CB_DND PtWidget
Pt_CB_FILTER PtWidget
Pt_CB_GOT_FOCUS PtBasic
Pt_CB_HOTKEY PtWidget
Pt_CB_IS_DESTROYED PtWidget
Pt_CB_LOST_FOCUS PtBasic
Pt_CB_MENU PtBasic
Pt_CB_OUTBOUND PtWidget
Pt_CB_RAW PtWidget
Pt_CB_REALIZED PtWidget
Pt_CB_REPEAT PtBasic
Pt_CB_UNREALIZED PtWidget