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

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.

---

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:

• Ph_WM_RENDER_ASAPP
• Ph_WM_RENDER_ASDIALOG
• Ph_WM_RENDER_ASICON
• Ph_WM_RENDER_ASPALETTE

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:

• Pt_ARG_MAX_HEIGHT
• Pt_ARG_MAX_WIDTH
• Pt_ARG_MIN_HEIGHT
• Pt_ARG_MIN_WIDTH

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:

Pt_ARG_MAX_HEIGHT

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

---

You should use Pt_ARG_MAXIMUM_DIM instead of this resource.

---

Pt_ARG_MAX_WIDTH

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

---

You should use Pt_ARG_MAXIMUM_DIM instead of this resource.

---

Pt_ARG_MIN_HEIGHT

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

---

You should use Pt_ARG_MINIMUM_DIM instead of this resource.

---

Pt_ARG_MIN_WIDTH

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

---

You should use Pt_ARG_MINIMUM_DIM instead of this resource.

---

Pt_ARG_WINDOW_ACTIVE_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

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

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

Pt_ARG_WINDOW_HELP_ROOT

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

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

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:

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

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:

• Ph_WM_FFRONT
• Ph_WM_NO_FOCUS_LIST
• Ph_WM_TASKBAR

Pt_ARG_WINDOW_RENDER_FLAGS

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

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.

---

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

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

Pt_ARG_WINDOW_TITLE_COLOR

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

Pt_CB_WINDOW

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

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.

---

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

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.

---

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

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.

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.