PtContainer

Layout and geometry management for all container widgets

Class hierarchy:

PtWidget → PtBasic → PtContainer

Immediate subclasses:

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

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

PhAB icon:

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_LAYOUT

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

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

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

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

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

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

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_CHILD_GETTING_FOCUS

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

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

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

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.