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

PtWindow

An application window that's managed by the Photon Window Manager

Class hierarchy:

PtWidget --> PtBasic --> PtContainer --> PtDisjoint --> PtWindow

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

PhAB icon:

None -- use PhAB's Window or Dialog module.

Public header:

<photon/PtWindow.h>

Description:

The PtWindow class provides a top-level container for your applications' widgets. It also provides a standard appearance for all windows. Windows are managed by the Photon Window Manager if it's present (PtForwardWindowEvent() sends window events to the Window Manager -- see the Photon Library Reference).


PtWindow


A PtWindow widget that contains an editor application.

The frame and title bar aren't part of the PtWindow widget; the window manager adds them. The value of the widget's Pt_ARG_DIM resource doesn't include the frame, but you can call PtWindowGetFrameSize() to determine the size of the frame.


Note:
  • Use PhAB's Window module instead of using this widget directly. See "Window modules" in the Working with Modules chapter of the Photon Programmer's Guide.
  • A PtWindow is the top-level widget of the application. If you try to use another class for the top-level widget (aside from a PtRegion), the behavior is undefined -- you'll likely get a fatal error.
  • In addition to the sections below, see the Window Management chapter of the Photon Programmer's Guide.

The PtWindow class handles the details of opening a Photon window and displaying the widget hierarchy in it. It also tells the Window Manager what controls to place in the frame around the application window. This gives a standard appearance to the windows of all applications using the Photon widget library.

Interacting with the Window Manager

Using resources, you can choose which elements of the window frame will be displayed. You can control which window management functions the Window Manager will perform, and whether they're invoked from the window menu or from one of the window controls. You can also have your application notified when the user has requested a window management function, regardless of whether or not the Window Manager will perform that function.

Setting the window's title

You can specify the string displayed in the window's title bar by setting the Pt_ARG_WINDOW_TITLE resource.

Controlling the decorations

You control the elements displayed in the window frame using the Pt_ARG_WINDOW_RENDER_FLAGS resource. Enable or disable a window-frame element by setting or clearing the appropriate bit.

The Pt_ARG_WINDOW_RENDER_FLAGS resource also has one of the following bits set to specify how the window and its frame are displayed and behave:

Controlling window resizing

If you need to control the maximum and minimum possible sizes for the window, use the Pt_ARG_MAXIMUM_DIM and Pt_ARG_MINIMUM_DIM resources defined by PtWidget.

The following resources also control the window's size:

Enabling Window Manager functions

You can control how the Window Manager operates on your window by setting Pt_ARG_WINDOW_MANAGED_FLAGS.

Every flag in the resource corresponds to an operation the Window Manager can perform on the window. If the flag is set, the Window Manager lets you perform that operation. If a flag isn't set, the Window Manager disables the operation.

Each operation is identified by the name of the flag that enables/disables it. Here are the operations the Window Manager lets you perform on a window:

Ph_WM_BACKDROP
Use the window as the backdrop for the workspace.
Ph_WM_CLOSE
Close the window. If the window is the main window for the application, the application itself is terminated.
Ph_WM_COLLAPSE
You can collapse the window to just the title bar.
Ph_WM_CONSWITCH
Move the window within the Photon coordinate space so that it remains in the same position on the screen when the workspace is moved in response to a console-switch request.
Ph_WM_FOCUS
Give focus to the window.
Ph_WM_HIDE
Minimize/hide the window. You can restore the window by clicking on its button in the running-tasks part of the shelf.
Ph_WM_MAX
Maximize the window (i.e. make it fill the entire screen).
Ph_WM_MOVE
Move the window to a new location.
Ph_WM_NO_FOCUS_LIST
Prevent you from cycling focus to the window by pressing Alt-Esc, Alt-Shift-Esc, or Alt-Tab.
Ph_WM_RESIZE
Change the size of the window.
Ph_WM_RESTORE
Restore the window to its state prior to an iconify or maximize operation.
Ph_WM_TASKBAR
Taskbar applications should include this window.
Ph_WM_TERMINATE
Terminate the application. This operation is used for graceful shutdown of the windowing system.
Ph_WM_TOBACK
Move the window to the back of the window stacking order.
Ph_WM_TOFRONT
Move the window to the front of the window stacking order.

Notifying the application

You may also tell the Window Manager to notify the application after it has done a Window Manager operation. This behavior is controlled by the Pt_ARG_WINDOW_NOTIFY_FLAGS resource. This resource consists of the same set of flags as the Pt_ARG_WINDOW_MANAGED_FLAGS resource.

Setting a flag in this resource tells the Window Manager that it should send an event to the application whenever the corresponding operation is performed on the window widget. The event sent to the application is handled by the window's Pt_CB_WINDOW callbacks.

The callback data for these callbacks consists of a pointer to a window event structure, PhWindowEvent_t (described in the Photon Library Reference).

Creating subwindows

Some parts of the UI, such as toolbars, palettes, or dialogs, may reside outside the main application window in windows of their own. These windows are usually subwindows of the main application window.

A subwindow is obtained by creating a window widget as the child of another window widget. A subwindow can't be placed behind its parent. The subwindows associated with a window are also iconified as a group whenever the window itself is iconified.

New resources:

Resource C type Pt type Default
Pt_ARG_MAX_HEIGHT short Scalar 0 (See below)
Pt_ARG_MAX_WIDTH short Scalar 0 (See below)
Pt_ARG_MIN_HEIGHT short Scalar 0 (See below)
Pt_ARG_MIN_WIDTH short Scalar 0 (See below)
Pt_ARG_WINDOW_ACTIVE_COLOR PgColor_t Scalar See below
Pt_ARG_WINDOW_FLAGS unsigned short Flag See below
Pt_ARG_WINDOW_FRONT_WINDOW PhRid_t Scalar 0
Pt_ARG_WINDOW_HELP_ROOT char * String NULL
Pt_ARG_WINDOW_INACTIVE_COLOR PgColor_t Scalar See below
Pt_ARG_WINDOW_MANAGED_FLAGS unsigned long Flag See below
Pt_ARG_WINDOW_NOTIFY_FLAGS unsigned long Flag See below
Pt_ARG_WINDOW_RENDER_FLAGS unsigned long Flag See below
Pt_ARG_WINDOW_STATE unsigned long Flag See below
Pt_ARG_WINDOW_TITLE char * String "Untitled"
Pt_ARG_WINDOW_TITLE_COLOR PgColor_t Scalar See below
Pt_CB_WINDOW PtCallback_t * Link NULL
Pt_CB_WINDOW_CLOSING PtCallback_t * Link NULL
Pt_CB_WINDOW_OPENING PtCallback_t * Link NULL
Pt_CB_WINDOW_TRANSPORT PtCallback_t * Link NULL

Pt_ARG_MAX_HEIGHT

C type Pt type Default
short Scalar 0 (See below)

The maximum height of the window. If you set this resource to 0, the default value specified by the window manager is used.


Note: You should use Pt_ARG_MAXIMUM_DIM instead of this resource.

Pt_ARG_MAX_WIDTH

C type Pt type Default
short Scalar 0 (see below)

The maximum width of the widget. If you set this resource to 0, the default value specified by the window manager is used.


Note: You should use Pt_ARG_MAXIMUM_DIM instead of this resource.

Pt_ARG_MIN_HEIGHT

C type Pt type Default
short Scalar 0 (See below)

The minimum height of the widget. If you set this resource to 0, the default value specified by the window manager is used.


Note: You should use Pt_ARG_MINIMUM_DIM instead of this resource.

Pt_ARG_MIN_WIDTH

C type Pt type Default
short Scalar 0 (See below)

The minimum width of the widget. If you set this resource to 0, the default value specified by the window manager is used.


Note: You should use Pt_ARG_MINIMUM_DIM instead of this resource.

Pt_ARG_WINDOW_ACTIVE_COLOR

C type Pt type Default
PgColor_t Scalar Pg_DEFAULT_WM_COLOR

The color of the window's frame when the window has focus. This overrides the color specified by the window manager.

Pt_ARG_WINDOW_FLAGS

C type Pt type Default
unsigned short Flag Pt_WINDOW_FRAME_BLOCKABLE

This resource has a single bit, Pt_WINDOW_FRAME_BLOCKABLE. It controls whether the Window Manager knows that the window widget is blocked with the Pt_BLOCKED flag in Pt_ARG_FLAGS. If this bit is not set, a user can give the window focus and resize it, even if it's blocked.

Pt_ARG_WINDOW_FRONT_WINDOW

C type Pt type Default
PhRid_t Scalar 0

Specifies the region ID of the window that this window is to be positioned behind.

Pt_ARG_WINDOW_HELP_ROOT

C type Pt type Default
char * String NULL

Defines the root topic path for the window. For more information, see the PtHelp*() functions in the Photon Library Reference and the Context-Sensitive Help chapter of the Photon Programmer's Guide.

Pt_ARG_WINDOW_INACTIVE_COLOR

C type Pt type Default
PgColor_t Scalar Pg_DEFAULT_WM_COLOR

The color of the window's frame when the window doesn't have focus. This overrides the color specified by the window manager.

Pt_ARG_WINDOW_MANAGED_FLAGS

C type Pt type Default
unsigned long Flag Ph_WM_APP_DEF_MANAGED

Controls which actions the Window Manager performs for the application, but doesn't affect whether or not the Window Manager notifies the application of those actions (for that, use Pt_ARG_WINDOW_NOTIFY_FLAGS). You can set the following bits:

If you set this bit: the Window Manager:
Ph_WM_BACKDROP Allows the window to be the workspace backdrop
Ph_WM_CLOSE Closes the application
Ph_WM_COLLAPSE Collapses the window to just the title bar
Ph_WM_CONSWITCH Moves the window to keep it on the visible display whenever the virtual Photon console is switched
Ph_WM_FFRONT Allows the window to become force front. To make the base window force front, set Ph_WM_STATE_ISFRONT in the Pt_ARG_WINDOW_STATE resource.
Ph_WM_FOCUS Handles gaining and losing focus for this window
Ph_WM_HELP Provides context-sensitive help
Ph_WM_MAX Maximizes the window
Ph_WM_MENU Pops up the window menu
Ph_WM_MOVE Moves the window
Ph_WM_NO_FOCUS_LIST Doesn't let you cycle focus to the window when you press Alt-Esc, Alt-Shift-Esc, or Alt-Tab
Ph_WM_RESIZE Resizes the application
Ph_WM_RESTORE Restores the window after it has been iconified, maximized, or hidden
Ph_WM_TASKBAR Includes the window in its taskbar
Ph_WM_TOBACK Sends the window to the back
Ph_WM_TOFRONT Sends the window to the front
Ph_WM_HIDE Hides the window

The default is Ph_WM_APP_DEF_MANAGED, a convenience manifest that's defined in <PhWm.h> as:

#define Ph_WM_APP_DEF_MANAGED ( Ph_WM_CLOSE | \
                                Ph_WM_FOCUS | \
                                Ph_WM_MENU | \
                                Ph_WM_TOFRONT | \
                                Ph_WM_TOBACK | \
                                Ph_WM_RESIZE | \
                                Ph_WM_MOVE | \
                                Ph_WM_HIDE | \
                                Ph_WM_MAX | \
                                Ph_WM_RESTORE  | \
                                Ph_WM_TASKBAR | \
                                Ph_WM_COLLAPSE)

Pt_ARG_WINDOW_NOTIFY_FLAGS

C type Pt type Default
unsigned long Flag Ph_WM_RESIZE|Ph_WM_CLOSE| Ph_WM_HELP

This resource controls which events the Pt_CB_WINDOW callbacks are invoked for. This resource doesn't cause the window manager to perform actions (for that, use Pt_ARG_WINDOW_MANAGED_FLAGS). Pt_ARG_WINDOW_NOTIFY_FLAGS uses the same set of bits as Pt_ARG_WINDOW_MANAGED_FLAGS, but the following bits have no notification associated with them:

Pt_ARG_WINDOW_RENDER_FLAGS

C type Pt type Default
unsigned long Flag Ph_WM_APP_DEF_RENDER

Controls how the Window Manager renders components of the window. The value of this resource is one of the following bits, which determine how the window and its frame look and feel:

Ph_WM_RENDER_ASAPP
Render the window as an application.
Ph_WM_RENDER_ASDIALOG
Render it as a dialog.
Ph_WM_RENDER_ASICON
Render it as an icon.
Ph_WM_RENDER_ASPALETTE
Render it as a palette.

as well as any combination of the following bits:

Ph_WM_RENDER_BORDER
Put a border around the window.
Ph_WM_RENDER_CLOSE
If the window has a title bar, include a close button.
Ph_WM_RENDER_COLLAPSE
If the window has a title bar, add a collapse button.
Ph_WM_RENDER_HELP
If the window has a title bar, include a help button.
Ph_WM_RENDER_INLINE
Add a black line just inside the standard borders.
Ph_WM_RENDER_MAX
If the window has a title bar, include a maximize button.
Ph_WM_RENDER_MENU
If the window has a title bar, include a menu button.
Ph_WM_RENDER_MIN
If the window has a title bar, include a minimize button.
Ph_WM_RENDER_RESIZE
If the window has a border, add resize handles.
Ph_WM_RENDER_TITLE
If the window has a border, add a title bar.

The default value is Ph_WM_APP_DEF_RENDER, a convenience manifest that's defined in <PhWm.h> as:

#define Ph_WM_APP_DEF_RENDER ( Ph_WM_RENDER_ASAPP | \
                               Ph_WM_RENDER_BORDER | \
                               Ph_WM_RENDER_RESIZE | \
                               Ph_WM_RENDER_MOVE | \
                               Ph_WM_RENDER_CLOSE | \
                               Ph_WM_RENDER_TITLE | \
                               Ph_WM_RENDER_MENU | \
                               Ph_WM_RENDER_MIN | \
                               Ph_WM_RENDER_MAX | \
                               Ph_WM_RENDER_COLLAPSE)

Pt_ARG_WINDOW_STATE

C type Pt type Default
unsigned long Flag Ph_WM_STATE_ISFOCUS

This resource controls the window's state. You can set one of the following:

Ph_WM_STATE_ISALTKEY
Pass Alt function-key combinations to the application.
Ph_WM_STATE_ISBACKDROP
Open as the workspace backdrop. See Pt_ARG_WINDOW_MANAGED_FLAGS.
Ph_WM_STATE_ISBLOCKED
Block input to the window.
Ph_WM_STATE_ISCOLLAPSE
Display just the window's title bar.
Ph_WM_STATE_ISFOCUS
Grant focus to the window when it's opened if the cursor focus option to the Window Manager is disabled (default is enabled).
Ph_WM_STATE_ISFRONT
Open the base window in front of the windows of all applications. Child windows will open behind the last forced front window in the family. See Pt_ARG_WINDOW_MANAGED_FLAGS.
Ph_WM_STATE_ISHIDDEN
Open as a normal window but don't display it.
Ph_WM_STATE_ISICONIFIED
Open the window and iconify it.
Ph_WM_STATE_ISMAX
Open as a maximized window.

Note: You can get and set the state of the window at any time by using this resource, but you might get unexpected results if the user is changing the window state at the same time.

The safest time to use this resource to set the window state is before the window is realized. For example, you could set it when creating the PtWindow widget or in the window's Pt_CB_WINDOW_OPENING callback. The setting will be in effect when the window is realized.

You can set Pt_ARG_WINDOW_STATE after the window has been realized, basing your changes on what you think the current window state is, but it's safer to tell the window manager how you want to change the state, by calling:

PtForwardWindowEvent()
Change the state for the window associated with a given region ID
PtForwardWindowTaskEvent()
Change the state for a window associated with a given Photon connection ID

Pt_ARG_WINDOW_TITLE

C type Pt type Default
char * String "Untitled"

The string that the Window Manager displays in the title bar.

Pt_ARG_WINDOW_TITLE_COLOR

C type Pt type Default
PgColor_t Scalar Pg_DEFAULT_WM_COLOR

The color of the window's title (i.e. the text). This overrides the color specified by the window manager.

Pt_CB_WINDOW

C type Pt type Default
PtCallback_t * Link NULL

A list of PtCallback_t structures that define the callbacks that the widget invokes when it receives an event from the Window Manager. See Pt_ARG_WINDOW_NOTIFY_FLAGS.

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

reason
Pt_CB_WINDOW
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
A pointer to a PhWindowEvent_t (described in the Photon Library Reference).

These callbacks should return Pt_CONTINUE.

For an example of using this callback to verify that the user really wants to exit the application, see "Notification callback" in the Window Management chapter of the Photon Programmer's Guide.

Pt_CB_WINDOW_CLOSING

C type Pt type Default
PtCallback_t * Link NULL

A list of PtCallback_t structures that define the callbacks that the widget invokes when the window is being closed. It's invoked before the window's region is removed. These callbacks are invoked when the window is about to unrealize for any reason. This includes transporting to another Photon and explicit calls to PtDestroyWidget() or PtUnrealizeWidget(). If you want to make sure in a Window Closing callback that the window is actually being destroyed, check the Pt_DESTROYED flag in Pt_ARG_FLAGS. You can also use the Pt_CB_DESTROYED callback to know when a window is marked for destruction, or Pt_CB_IS_DESTROYED to know when it is being destroyed.


Note: The Pt_CB_WINDOW_CLOSING callbacks are invoked when the window is already closing. To be notified before the window is closed, use the Ph_WM_CLOSE bit in Pt_ARG_WINDOW_NOTIFY_FLAGS and the Pt_CB_WINDOW callback.

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

reason
Pt_CB_WINDOW_CLOSING
reason_subtype
0 (not used).
event
NULL (not supplied).
cbdata
NULL (not supplied).

These callbacks should return Pt_CONTINUE.

Pt_CB_WINDOW_OPENING

C type Pt type Default
PtCallback_t * Link NULL

A list of PtCallback_t structures that define the callbacks that the widget invokes when the window is being opened. If you want to resize the window and want anchoring to be in effect, do it in this type of callback.


Note: The window hasn't been completely realized when the Pt_CB_WINDOW_OPENING callbacks are invoked; don't change the window's widget family hierarchy in these callbacks. If you need to adjust the widgets' stacking order, do it in the Pt_CB_REALIZED callbacks.

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

reason
Pt_CB_WINDOW_OPENING
reason_subtype
0 (not used)
event
A pointer to a PhEvent_t structure filled with NULLs.
cbdata
NULL

These callbacks should return Pt_CONTINUE.

Pt_CB_WINDOW_TRANSPORT

C type Pt type Default
PtCallback_t * Link NULL

A list of PtCallback_t structures that define the callbacks that the widget invokes when the window is being transported through a Jump Gate.

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

reason
Pt_CB_WINDOW_TRANSPORT
reason_subtype
0 (not used)
event
A pointer to a PhEvent_t structure that describes the Ph_EV_WM event that caused the callback to be invoked.
cbdata
Internal use only

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 Not used by this class.
Pt_ARG_ANCHOR_OFFSETS PtWidget Not used by this class.
Pt_ARG_AREA PtWidget
Pt_ARG_BANDWIDTH_THRESHOLD PtBasic Not used by this class.
Pt_ARG_BASIC_FLAGS PtBasic
Pt_ARG_BEVEL_WIDTH PtWidget Not used by this class.
Pt_ARG_BITMAP_CURSOR PtWidget
Pt_ARG_BEVEL_COLOR PtBasic
Pt_ARG_BEVEL_CONTRAST PtBasic
Pt_ARG_COLOR PtBasic
Pt_ARG_CONTAINER_FLAGS PtContainer
Pt_ARG_CONTRAST PtBasic
Pt_ARG_CURSOR_COLOR PtWidget
Pt_ARG_CURSOR_OVERRIDE PtContainer
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_ARG_EXTENT PtWidget
Pt_ARG_FILL_COLOR PtBasic
Pt_ARG_FILL_LAYOUT_INFO PtContainer
Pt_ARG_FILL_PATTERN PtBasic
Pt_ARG_FLAGS PtWidget
Pt_ARG_GRID_LAYOUT_DATA PtWidget
Pt_ARG_GRID_LAYOUT_INFO PtContainer
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_LAYOUT_INFO PtContainer
Pt_ARG_LIGHT_BEVEL_COLOR PtBasic
Pt_ARG_LIGHT_FILL_COLOR PtBasic
Pt_ARG_MARGIN_HEIGHT PtBasic Not used by this class.
Pt_ARG_MARGIN_WIDTH PtBasic Not used by this class.
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_RESIZE_XY_AS_REQUIRED
Pt_ARG_ROW_LAYOUT_DATA PtWidget
Pt_ARG_ROW_LAYOUT_INFO PtContainer
Pt_ARG_STYLE PtBasic
Pt_ARG_SYSINFO PtDisjoint
Pt_ARG_TITLE PtContainer
Pt_ARG_TITLE_FONT PtContainer
Pt_ARG_TRANS_PATTERN PtBasic
Pt_ARG_USER_DATA PtWidget
Pt_ARG_WIDTH PtWidget
Pt_CB_ACTIVATE PtBasic
Pt_CB_ARM PtBasic
Pt_CB_BALLOONS PtContainer
Pt_CB_BLOCKED PtWidget
Pt_CB_CHILD_ADDED_REMOVED PtContainer
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_RESIZE PtContainer
Pt_CB_SYSINFO PtDisjoint
Pt_CB_UNREALIZED PtWidget

Convenience functions:

The PtWindow widget defines the following convenience functions:

PtWindowFocus()
Give a window focus.
PtWindowGetState()
Return the current state of a window.
PtWindowToBack()
Move a window to the back of the workspace.
PtWindowToFront()
Bring a window to the front and give it focus.