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

A PtWindow widget.

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:

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

• Ph_WM_RENDER_ASAPP
• Ph_WM_RENDER_ASICON

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:

• Pt_ARG_MAX_HEIGHT
• Pt_ARG_MAX_WIDTH
• Pt_ARG_MIN_HEIGHT
• Pt_ARG_MIN_WIDTH

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:

• rendering - the icon window is rendered as an icon (i.e. Ph_WM_RENDER_ASICON)
• icon representation - an icon widget may be automatically used as the icon representation for its parent.

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.

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:

• Create the PtIcon widget as a child widget to the window widget

  Or:

• Create the PtIcon widget by itself and use the PtIcon instance pointer as a resource value for the Pt_ARG_ICON_WINDOW, which you can set for the window at any time. You'll also need to set the Ph_WM_RENDER_ASICON flag in the window's render flags.

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:

Pt_ARG_ICON_WINDOW

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

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

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

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

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

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

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

Pt_ARG_WINDOW_FRONT_WINDOW

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

Pt_ARG_WINDOW_HELP_ROOT

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

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 combines some of these flags. For more information, see <PhWm.h>.

Pt_ARG_WINDOW_NOTIFY_FLAGS

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

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

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.

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

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

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

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.

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

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.

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

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.

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

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.