`PtContainer`

Layout and geometry management for all container widgets

Class hierarchy:

PtWidget --> PtBasic --> PtContainer

Immediate subclasses:

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

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:

PtFillLayout
PtRowLayout
PtGridLayout
NULL (equivalent to PtAnchorLayout, the default layout type)

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:

PtFillLayoutInfo_t
PtRowLayoutInfo_t
PtGridLayoutInfo_t

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:

PtFillLayout
PtRowLayout
PtGridLayout

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:

Pt_FILL_LAYOUT
Pt_ROW_LAYOUT
PT_GRID_LAYOUT
Pt_ANCHOR_LAYOUT

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:

Pt_LAYOUT_HORIZONTAL -- layout children in a row
Pt_LAYOUT_VERTICAL -- layout children in a column

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:

Pt_LAYOUT_HORIZONTAL -- layout children in rows
Pt_LAYOUT_VERTICAL -- layout children in columns

short flags

A combination of the following flags:

Pt_ROW_JUSTIFY -- distribute extra space between children when the container grows
Pt_ROW_PACK -- leave children widgets their preferred size. If this flag is not set, child widgets are all the same size.
Pt_ROW_WRAP -- enable wrapping

PhRect_t margins

Container margins in pixels, where:

ul.x is the left
ul.y is the top
lr.x is the right
lr.y is the bottom

short h_spacing

Horizontal spacing distance between children, in pixels

short v_spacing

Vertical spacing between children, in pixels

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:

Pt_EQUAL_COLS -- Force all columns to be the same width.
Pt_EQUAL_ROWS -- Force all rows to be the same height.

PhRect_t margins

Container margins in pixels, where:

ul.x is the left
ul.y is the top
lr.x is the right
lr.y is the bottom

short h_spacing

Horizontal spacing between columns, in pixels.

short v_spacing

Vertical spacing between rows, in pixels.

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

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

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:

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_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_CONTINUE to relinquish focus
Or:
Pt_END to keep it (for example, if the user has to type something in a text widget).

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_CONTINUE to relinquish focus
Or:
Pt_END to keep it (for example, if the user has to type something in a text widget).

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

Pt_LAYOUT_INIT -- starting to lay out children.
Pt_LAYOUT_DONE -- finished laying out children.

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`

QNX Developer Support

`PtContainer`

Class hierarchy:

PhAB icon:

Public header:

Description:

New resources:

Pt_ARG_CONTAINER_FLAGS

Pt_ARG_CURSOR_OVERRIDE

Pt_ARG_LAYOUT

Pt_ARG_LAYOUT_INFO

Pt_ARG_LAYOUT_TYPE

Pt_ARG_FILL_LAYOUT_INFO

Pt_ARG_ROW_LAYOUT_INFO

Pt_ARG_GRID_LAYOUT_INFO

Pt_ARG_TITLE

Pt_ARG_TITLE_FONT

Pt_CB_BALLOONS

Pt_CB_CHILD_ADDED_REMOVED

Pt_CB_CHILD_GETTING_FOCUS

Pt_CB_CHILD_LOSING_FOCUS

Pt_CB_LAYOUT

Pt_CB_RESIZE

Inherited resources: