[Previous] [Contents] [Index] [Next]

PtWindow

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

Class hierarchy:

PtWidget --> PtBasic --> PtContainer --> 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 an application window and a standard appearance for all other windows. Windows are always managed by the Photon Window Manager (the PtForwardWindowEvent() function sends window events to the Window Manager).


PtWindow


A PtWindow widget.



Note:
  • Use PhAB's Window module instead of this widget. See "Window modules" in the Working with Modules chapter of the Photon Programmer's Guide.
  • A PtWindow widget is the top-level widget of the application. If you try to use another class for the top-level widget, the behavior will be 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.

Setting the window's icon

You can provide a window that will be displayed as the icon for the window whenever the window is iconified. This is controlled by the Pt_ARG_ICON_WINDOW resource. Set the value of the resource to a widget to be displayed as the icon window. If the widget doesn't belong to the PtIcon widget class or one of its subclasses, then the behavior when the user iconifies the window is undefined.

If you don't specify an icon window for the application, but you create a widget of the class PtIcon as a child of the application window, that widget will be used to display the icon for the application. Otherwise, an icon window will be created for the window automatically. The default icon window is a small beveled square in the Taskbar.

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 set the string displayed in the window's title bar with the Pt_ARG_WINDOW_TITLE resource. You should set the resource to the string to be displayed.

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:

Element Bit
Border Ph_WM_RENDER_BORDER
Resize handles Ph_WM_RENDER_RESIZE
Title bar Ph_WM_RENDER_TITLE
Window menu Ph_WM_RENDER_MENU
Minimize button Ph_WM_RENDER_MIN
Maximize Button Ph_WM_RENDER_MAX
Close Button Ph_WM_RENDER_CLOSE
Help Button Ph_WM_RENDER_HELP

The Pt_ARG_WINDOW_RENDER_FLAGS resource also has either of the following two bits set:

The value of these bits determines whether the window is displayed as an application window or an icon window. These windows differ in the window management functions included in the window menu.

By default, the value of the Pt_ARG_WINDOW_RENDER_FLAGS resource is set to the value of the manifest constant Ph_WM_APP_DEF_RENDER. This displays the window as an application window with a border, resize handles, a title bar, a minimize button, a maximize button, a window menu, and an icon representation.

Controlling window resizing

You can use the following four resources to control the minimum and maximum sizes that the Window Manager will allow the user to resize the window:

If these are set to 0, default values specified by the window manager are used.

Enabling Window Manager functions

The Window Manager can provide many operations on a window. You can control how the Window Manager operates on your windows by setting the Pt_ARG_WINDOW_MANAGED_FLAGS resource on the PtWindow widget.

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 allows the user to 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 the user perform on a window:

Ph_WM_CLOSE
Close the window. If the window is the main window for the application, the application itself is terminated.
Ph_WM_RESIZE
Change the size of the window.
Ph_WM_MOVE
Move the window to a new location.
Ph_WM_TOFRONT
Move the window to the front of the window stacking order.
Ph_WM_TOBACK
Move the window to the back of the window stacking order.
Ph_WM_HIDE
Minimize/hide the window. The window can be restored from the Taskbar button.
Ph_WM_MAX
Maximize the size of the window. The window is resized to fit the entire screen.
Ph_WM_BACKDROP
Use the window as the backdrop for the workspace.
Ph_WM_RESTORE
Restore the window to its state prior to an iconify or maximize operation.
Ph_WM_FOCUS
Give focus to the window.
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_TERMINATE
Terminate the application. This operation is used for graceful shutdown of the windowing system.

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 callback for the window widget.

The window callback list belongs to the Pt_CB_WINDOW resource. The callback data for this callback consists of a pointer to a window event structure, PhWindowEvent_t (described in the Photon Library Reference).

Application icons

The PtIcon class provides an icon widget, a specialized form of PtWindow widget. An icon is the same as a PtWindow widget in all regards except for the following:

If the application window is iconified and doesn't have an icon representation specified, a search will be made for an icon widget child to use as the icon representation.

Typically, icons are defined using a PtLabel widget with the Pt_IMAGE label flag set. The label widget also sets the Pt_ARG_LABEL_DATA resource to a PhImage_t structure, which is used to render the icon. For more information about the PhImage_t structure, see the Photon Library Reference.


Note:
  • You don't have to use PtLabel widgets for icons. They're mentioned here because they're a convenient way to display graphical images usually found in icons.
  • Set the flags member of the PhImage_t structure to:
    Ph_RELEASE_IMAGE | Ph_RELEASE_PALETTE |
    Ph_RELEASE_TRANSPARENCY_MASK | Ph_RELEASE_GHOST_BITMAP
      

    before providing the image to the widget. If you do this, the memory used for the image is released when the widget is unrealized or destroyed.


There are two ways to associate the PtIcon widget with a window. You can either:

If you create a PtWindow widget but don't define a PtIcon widget for it, then the PtWindow widget will automatically create two default icons for you.

The default icon is a single label that matches the window's title. Unless the window's title is short, the icon text will get clipped.

The default small icon is a 15*15 3-D rectangle.

The following code shows how to create a window containing two icons:

  int         n;
  PtWidget_t  *window, *icon;
  PhArea_t    area;
  PtArg_t     args[6];

  /* setup window resources */
  /* ... */
  PtSetArg( &args[n], Pt_ARG_WINDOW_RENDER_FLAGS,
            Ph_WM_RENDER_ASICON, Ph_WM_RENDER_ASICON );
  n++;
  window = PtCreateWidget( PtWindow, NULL, n, args );

  memset(&area, 0, sizeof(area));
  area.size.w = 14;
  area.size.h = 14;
  PtSetArg( &args[0], Pt_ARG_DIM, &area.size, 0 );
  PtSetArg( &args[1], Pt_ARG_FILL_COLOR, Pg_GREY, 0 );
  icon = PtCreateWidget( PtIcon, window, 2, args );

  /* widget is taskbar icon */
  area.pos.x  =  0;
  area.pos.y  =  0;
  area.size.w = 14;
  area.size.h = 14;
  PtSetArg( &args[0], Pt_ARG_AREA, &area, 0 );
  PtSetArg( &args[1], Pt_ARG_BORDER_WIDTH, 1, 0);
  PtSetArg( &args[2], Pt_ARG_TOP_BORDER_COLOR, Pg_DGREY, 0 );
  PtCreateWidget( PtButton, icon, 3, args );

  PtRealizeWidget( window );

Layout and sizing

The window widget will position each of its children at the location specified by their Pt_ARG_AREA or Pt_ARG_POS resources. This is known as absolute positioning.

The size of the window widget is initially determined to be the minimum size needed to contain all its children at their requested locations, with a margin maintained around the children. This calculation is performed when the window is realized.

Most applications will normally have a menu bar and a work area. The menu bar should be a group widget with its right side anchored to the right side of the main window. The work area may be the main window itself, but you may want to place another widget such as a scroll area beneath the menu bar. As with the menu bar, this widget should have its right side anchored to the right side of the main window. The bottom of the widget should also be anchored to the bottom of the main window.

The geometry management issues of layout, sizing, and anchoring of children are discussed in more detail in the Photon Programmer's Guide.

Creating subwindows

Some parts of the UI such as tool bars, 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 cannot 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_ICON_WINDOW PtWidget_t Pointer See below
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_CURSOR_OVERRIDE int Boolean Pt_FALSE
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 short Flag See below.
Pt_ARG_WINDOW_NOTIFY_FLAGS unsigned short Flag See below.
Pt_ARG_WINDOW_RENDER_FLAGS unsigned short Flag See below.
Pt_ARG_WINDOW_STATE unsigned short 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_ICON_WINDOW

C type Pt type Default
PtWidget_t Pointer See below

The widget ID of the icon that the window is to display. If this resource is NULL, the window will search its children for a PtIcon widget; if none is found, a default icon is used.

Pt_ARG_MAX_HEIGHT

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

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

Pt_ARG_MAX_WIDTH

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

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

Pt_ARG_MIN_HEIGHT

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

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

Pt_ARG_MIN_WIDTH

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

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

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_CURSOR_OVERRIDE

C type Pt type Default
int Boolean Pt_FALSE

Allows this window's cursor to override the cursors of the window's children.

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 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 PxHelp*() 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 short 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_CONSWITCH Moves the window to keep it on the visible display whenever the virtual Photon console is switched
Ph_WM_FFRONT Allow the window to become force front
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_RESIZE Resizes the application
Ph_WM_RESTORE Restores the window after it has been iconified, maximized, or hidden
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 combines some of these flags. For more information, see <PhWm.h>.

Pt_ARG_WINDOW_NOTIFY_FLAGS

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

Controls for which events the Pt_CB_WINDOW callbacks are invoked. This resource doesn't cause the window manager to perform actions (for that, use Pt_ARG_WINDOW_MANAGED_FLAGS). You can set any of the bits listed for Pt_ARG_WINDOW_MANAGED_FLAGS.

Pt_ARG_WINDOW_RENDER_FLAGS

C type Pt type Default
unsigned short 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_ASICON
Render it as an icon.

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_HELP
If the window has a title bar, include a help button.
Ph_WM_RENDER_MAX
If the window has a title bar, include a maximize button.
Ph_WM_RENDER_MIN
If the window has a title bar, include a minimize button.
Ph_WM_RENDER_MENU
If the window has a title bar, include a menu 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_TITLE | \
                               Ph_WM_RENDER_MENU | \
                               Ph_WM_RENDER_MIN | \
                               Ph_WM_RENDER_MAX )

Pt_ARG_WINDOW_STATE

C type Pt type Default
unsigned short Flag Ph_WM_STATE_ISFOCUS

Controls what state the window will appear in when it is opened. 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_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_ISICONIFIED
Open the window and iconify it.
Ph_WM_STATE_ISHIDDEN
Open as a normal window but don't display it.
Ph_WM_STATE_ISMAX
Open as a maximized window.
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_ISBLOCKED
Block input to the window.

Note: You can change the state by setting Pt_ARG_WINDOW_STATE before the window is realized. After it's been realized, you'll need to call PtForwardWindowEvent() or PtForwardWindowTaskEvent().

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

The list of 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 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

The list of 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.


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
Not supplied.
cbdata
Not supplied.

These callbacks should return Pt_CONTINUE.

Pt_CB_WINDOW_OPENING

C type Pt type Default
PtCallback_t * Link NULL

The list of 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
An empty event structure.
cbdata
NULL

These callbacks should return Pt_CONTINUE.

Pt_CB_WINDOW_TRANSPORT

C type Pt type Default
PtCallback_t * Link NULL

The list of 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
Not used
event
The Ph_EV_WM event that triggered this callback.
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.


Note: A window can't have a border or margins, so the following inherited resources aren't supported:
  • Pt_ARG_BORDER_WIDTH
  • Pt_ARG_BOT_BORDER_COLOR
  • Pt_ARG_MARGIN_HEIGHT
  • Pt_ARG_MARGIN_WIDTH
  • Pt_ARG_TOP_BORDER_COLOR

Resource Inherited from Default override
Pt_ARG_ANCHOR_FLAGS PtContainer Not used by this class.
Pt_ARG_ANCHOR_OFFSETS PtContainer Not used by this class.
Pt_ARG_AREA PtWidget
Pt_ARG_BANDWIDTH_THRESHOLD PtBasic Not used by this class.
Pt_ARG_BITMAP_CURSOR PtWidget
Pt_ARG_BORDER_WIDTH PtWidget Not used by this class.
Pt_ARG_BOT_BORDER_COLOR PtBasic Not used by this class.
Pt_ARG_COLOR PtBasic
Pt_ARG_CONTAINER_FLAGS PtContainer
Pt_ARG_CURSOR_COLOR PtWidget
Pt_ARG_CURSOR_TYPE PtWidget
Pt_ARG_DATA PtWidget
Pt_ARG_DIM PtWidget
Pt_ARG_EFLAGS PtWidget Pt_CONSUME_EVENTS
Pt_ARG_FILL_COLOR PtBasic
Pt_ARG_FILL_PATTERN PtBasic
Pt_ARG_FLAGS PtWidget
Pt_ARG_HELP_TOPIC PtWidget
Pt_ARG_HIGHLIGHT_ROUNDNESS PtBasic
Pt_ARG_MARGIN_HEIGHT PtBasic Not used by this class.
Pt_ARG_MARGIN_WIDTH PtBasic Not used by this class.
Pt_ARG_POS PtWidget
Pt_ARG_RESIZE_FLAGS PtWidget |=Pt_RESIZE_XY_AS_REQUIRED
Pt_ARG_TOP_BORDER_COLOR PtBasic Not used by this class.
Pt_ARG_TRANS_PATTERN PtBasic
Pt_ARG_USER_DATA PtWidget
Pt_CB_ACTIVATE PtBasic
Pt_CB_ARM PtBasic
Pt_CB_BALLOONS PtContainer
Pt_CB_BLOCKED PtWidget
Pt_CB_DESTROYED PtWidget
Pt_CB_DISARM PtBasic
Pt_CB_FILTER PtContainer
Pt_CB_GOT_FOCUS PtBasic
Pt_CB_HOTKEY PtWidget
Pt_CB_LOST_FOCUS PtBasic
Pt_CB_MENU PtBasic
Pt_CB_RAW PtWidget
Pt_CB_REALIZED PtWidget
Pt_CB_REPEAT PtBasic
Pt_CB_RESIZE PtContainer
Pt_CB_UNREALIZED PtWidget

Convenience functions:

The PtWindow widget defines the following convenience functions:

PtWindowFocus()
Gives a window focus.
PtWindowGetState()
Returns the current state of a window.
PtWindowToBack()
Moves a window to the back of the workspace.
PtWindowToFront()
Brings a window to the front and gives it focus.

[Previous] [Contents] [Index] [Next]