Session management allows users to log out, and any applications that are running at logout automatically restart when they log back in. The 4Dwm window manager keeps a list of the applications and desks that were previously running when the user last logged out and restarts them when the user logs in again.

For your application to be restarted via the 4Dwm session manager, the application must register its initial state with the session manager and make sure the current state is registered at all times.

Additionally, your application should restart in the same state it was in when the user logged out (for example, the same windows open, the same files open, and so on). To support this, you need to design your application so that when the 4Dwm session manager restarts it, it can redisplay any of its co-primary or support windows that were open when the user logged out, reopen any data files that were open, and so on. You can support this either by providing command-line options to your application or other mechanisms such as a state file that your application reads when it is launched.

The two types of session management include continuous session management and explicit session management. Continuous session management restarts the applications that were running when the user last logged out of the window manager. This is the default setting.

Explicit session management ignores the windows that were open when the user last logged out and always opens a particular set of windows that the user has chosen. Users can configure the windows on the desktop by using the Window Settings Control Panel. They can launch this panel via the Toolchest. From the Toolchest, open the Desktop menu, select “Customize,” and then select “Windows.” The Windows Settings dialog box appears (see Figure 5-1). The “Save Windows & Desks” item on the Window Settings Control Panel configures either continuous or explicit session management. A user can select explicit, and then press the “Set Home Session” button to save the (current) explicit window configuration. Also, users can launch this control panel from the Icon Catalog's Control Panel page.

Figure 5-1. Window Settings Control Panel

Applications can communicate with the window manager by setting properties on the top level window. The WM_COMMAND property gives the window manager the command line that can be used to re-invoke the application in its current state. The 4Dwm window manager sends a WM_SAVE_YOURSELF message to each window that subscribes to tell it to update its WM_COMMAND property and then reads in the value. If the user selects continuous session management, 4Dwm sends the message every 10 minutes and at logout. If the user selects explicit session management, the window manager only queries the applications when the user presses the “Set Home Session” button.

If you use ViewKit or XtAppInitialize(3Xt), the initial WM_COMMAND string is set for you when the top level window is realized. Use the xprop(1) command to make sure the WM_COMMAND string is set correctly for the top level window. For example:

WM_COMMAND(STRING) = { “webmagic”, “/usr/tmp/sgiLook.html” }

Even if WM_COMMAND is initially set by your toolkit, you need to keep WM_COMMAND updated if your program changes its state. For instance, if the user renames a data file or successfully opens a new data file, you need to change the WM_COMMAND string with the XSetCommand(3X11):

XSetCommand(Display *display, Window w,char **argv,int argc);

This can be done in the function that changes the state, and is simpler than responding to the window manager's WM_SAVE_YOURSELF message.

If your application already saves state information to a file instead of using the command line, this “state file” can also be used for session management. To work correctly with the user's Windows Control Panel setting, the application should update the file only in response to the window manager's WM_SAVE_YOURSELF message (see Example 5-1, saveyourself.c). This strategy does not work correctly if several instances of your application are able to run at the same time. Only applications that enforced a “Run Once” policy can rely on this strategy.

For more information, see the ViewKit reference page, VkRunOnce(3x), and XSetCommand(3X11).

When debugging:

“Handling the Window Manager Save Yourself Protocol” describes what your application needs to do to support session management. “Session Management” in Chapter 3 of the IRIX Interactive User Interface Guidelines provides further guidelines for handling session management.

For more information, see Inter-Client Communication Conventions Manual (ICCCM). The ICCCM is reprinted as an appendix in O'Reilly and Associates, X Protocol Reference Manual, Volume Zero.

Your application's main primary window must be an ApplicationShell. Typically, you use the ApplicationShell widget returned by XtAppInitialize() as your application's main primary window.

You should set the main primary window's XmNmwmFunctions resource to remove the “Close” option from the window menu. Also, if you don't want the user to be able to resize the window, you should set XmNmwmFunctions to remove the “Size” and “Maximize” options and set XmNmwmDecorations to remove the resize handles. Example 5-2 shows how you can create a main primary window and set the resource values appropriately.

“Main and Co-Primary Windows” in Chapter 6 of the IRIX Interactive User Interface Guidelines provides guidelines for using main primary windows.

#include <Xm/Xm.h>           /* Required by all Motif applications */
#include <Xm/MwmUtil.h>      /* Required to set window menu and decorations */
#include <X11/Shell.h>       /* Shell definitions */
 
void main ( int argc, char **argv )
{
    Widget       mainWindow; /* Main window shell widget */
    XtAppContext app;        /* An application context, needed by Xt */
    Arg          args[10];   /* Argument list */
    int          n;          /* Argument count */
 
    /*
     * Initialize resource value flags to include all window menu options and
     * all decorations.
     */
 
    long functions = MWM_FUNC_ALL;
    long handleMask = MWM_DECOR_ALL;
    
    n = 0;
    
    /*
     * The following lines REMOVE items from the window manager menu.
     */
    
    functions  |= MWM_FUNC_CLOSE;        /* Remove "Close" menu option */
    
    /* Include the following two lines only if the window is *not* resizable */
 
    functions  |= MWM_FUNC_RESIZE;       /* Remove "Size" menu option */
    functions  |= MWM_FUNC_MAXIMIZE;     /* Remove "Maximize" menu option */
    
    XtSetArg(args[n], XmNmwmFunctions, functions); n++;
 
    /* Include the following two lines only if the window is *not* resizable */
 
    handleMask |= MWM_DECOR_RESIZEH;     /* Remove resize handles */
    
    XtSetArg(args[n], XmNmwmDecorations, handleMask); n++
    
    /*
     * Initialize Xt and create shell
     */
    
    mainWindow = XtAppInitialize ( &app, "WindowTest", NULL, 0, 
                                   &argc, argv, NULL, args, n );
 
    /* ... */
 
}

Your application's co-primary windows should be ApplicationShells or TopLevelShells. “Implementing an Application Model” describes which to choose depending on your application model. The easiest way to implement these windows are as pop-up children of the shell widget returned by XtAppInitialize() (which is typically your application's main primary window).

If the user can't quit the application from a co-primary window, you should set the window's XmNmwmFunctions resource to remove the “Exit” option from the window menu. Also, if you don't want the user to be able to resize the window, you should set XmNmwmFunctions to remove the “Size” and “Maximize” options and set XmNmwmDecorations to remove the resize handles. Example 5-3 shows how you can create a co-primary window and set the resource values appropriately.

---

Note: The default action when IRIS IM destroys an ApplicationShell is to quit your application. To avoid this if you are using ApplicationShells for your co-primary windows, you must set each window's XmNdeleteResponse resource to XmDO_NOTHING, and then explicitly handle the window manager's WM_DELETE_WINDOW protocol for each window. You might want to follow this approach even if you use TopLevelShells for co-primary windows so that you can simply popdown the window instead of deleting it. This can save time if you might redisplay the window later. “Handling the Window Manager Delete Window Protocol” describes how to implement these handlers.

---

“Main and Co-Primary Windows” in Chapter 6 of the IRIX Interactive User Interface Guidelines provides guidelines for using co-primary windows.

#include <Xm/Xm.h>       /* Required by all Motif applications */
#include <Xm/MwmUtil.h>  /* Required to set window menu and decorations */
#include <X11/Shell.h>   /* Shell definitions */
 
Widget       mainWindow; /* Main window shell widget */
Widget       coPrimary;  /* Co-primary window shell widget */
Arg          args[10];   /* Argument list */
int          n;          /* Argument count */
 
/*
 * Initialize resource value flags to include all window menu options and
 * all decorations.
 */
 
long functions = MWM_FUNC_ALL;
long handleMask = MWM_DECOR_ALL;
 
/* ... */

n = 0;
 
/*
 * The following lines REMOVE items from the  window manager menu.
 */
 
/* Remove the "Exit" window menu option if users can *not* quit from this window */
 
functions  |= MWM_FUNC_QUIT;
 
/* Include the following two lines only if the window is *not* resizable */
 
functions  |= MWM_FUNC_RESIZE;       /* Remove "Size" menu option */
functions  |= MWM_FUNC_MAXIMIZE;     /* Remove "Maximize" menu option */
    
XtSetArg(args, XmNmwmFunctions, functions); n++;
 
/* Include the following two lines only if the window is *not* resizable */
 
handleMask |= MWM_DECOR_RESIZEH;     /* Remove resize handles */
    
XtSetArg(args, XmNmwmDecorations, handleMask); n++;
 
/* You need the following line only if you use an ApplicationShell for the window */
 
XtSetArg(args, XmNdeleteResponse, XmDO_NOTHING); n++;
 
/* 
 * Assume that the application has already created a main window and assigned its widget
 * to the variable mainWindow
 */
 
coPrimary = XtCreatePopupShell( "coPrimary", applicationShellWidgetClass,
                                mainWindow, args, n );
 
/* ... */

Support windows are essentially custom dialogs. The easiest way to create a support window is to use XmCreateBulletinBoardDialog() to create a DialogShell containing a BulletinBoard widget, or use XmCreateFormDialog() to create a DialogShell containing a Form widget. You can then add appropriate controls and displays as children of the BulletinBoard or Form.

Another advantage to using a DialogShell for support windows is that they automatically have the proper window menu options and decorations. If you don't want the user to be able to resize the window—and you implemented the support window as a customized dialog—you should set XmNnoResize to “TRUE” to remove the “Size” and “Maximize” options and to remove the resize handles. Example 5-4 shows how you can create a support window and set the resource values appropriately.

“Support Windows” in Chapter 6 of the IRIX Interactive User Interface Guidelines provides guidelines for using support windows.

#include <Xm/Xm.h>          /* Required by all Motif applications */
#include <Xm/MwmUtil.h>     /* Required to set window menu and decorations */
#include <X11/Form.h>       /* Form definitions */
 
Widget       parentWindow;  /* Parent window of support window */
Widget       supportWindow; /* Support window */
Arg          args[10];      /* Argument list */
int          n;             /* Argument count */
 
/* ... */
 
n = 0;
 
/* Include the following line only if the window is *not* resizable */
 
XtSetArg(args, XmNnoResize, TRUE); n++
 
supportWindow = XmCreateFormDialog( parentWindow, "supportWindow", args, n );
 
/* Create the window interface... */

The easiest way to create dialogs is to use the IRIS IM convenience functions such as XmCreateMessageDialog() and XmCreatePromptDialog(). These functions automatically set most of the window characteristics required for the IRIX Interactive Desktop environment.

Dialogs automatically have the proper window menu options and decorations. If you don't want the user to be able to resize the dialog, you should set XmNnoResize to “TRUE” to remove the “Size” and “Maximize” options and to remove the resize handles. Example 5-5 shows an example of creating a WarningDialog and setting the resource values appropriately.

Chapter 10, “Dialogs,” in the IRIX Interactive User Interface Guidelines provides guidelines for using dialogs.

#include <Xm/Xm.h>          /* Required by all Motif applications */
#include <Xm/MwmUtil.h>     /* Required to set window menu and decorations */
#include <Xm/MessageB.h>    /* Warning dialog definitions */
 
Widget       parentWindow;  /* Parent window of dialog */
Widget       dialog;        /* Dialog */
Arg          args[10];      /* Argument list */
int          n;             /* Argument count */
 
/* ... */
 
n = 0;
 
/* Include the following line only if the window is *not* resizable */
 
XtSetArg(args, XmNnoResize, TRUE); n++
 
dialog = XmCreateWarningDialog ( parentWindow, "warningDialog", args, n );

When a user selects the “Exit” option from a window menu, the window manager sends a Quit message to your application. You should install a callback routine to handle this event. Example 5-6 demonstrates installing such a callback for the window specified by mainWindow.

Example 5-6. Handling the Window Manager Quit Protocol

Atom WM_QUIT_APP = XmInternAtom( XtDisplay(mainWindow), "_WM_QUIT_APP", FALSE ); XmAddWMProtocolCallback( mainWindow, WM_QUIT_APP, quitCallback, NULL ); /* ... */ quitCallback( Widget w, XtPointer clientData, XmAnyCallbackStruct cbs ) { /* Quit application */ }

---

Note: You must install the quit callback for each window that contains an “Exit” option in its window menu. Often the only such window is your application's main primary window.

---

The operations performed by the callback function should be the same as those that occur when the user quits from within your application (for example, by selecting an “Exit” option from a File menu). Your application can prompt the user to save any files that are open, to perform any other cleanup, or even to abort the quit.

When a user selects the “Close” option from a window menu, the window manager sends a Delete Window message to your application. How to handle this message depends on whether the window is a co-primary window, a dialog, or support window. (A main primary window should not have a “Close” option on its window menu.)

To handle the Delete Window message with a co-primary window, you should make sure to set the window's XmNdeleteResponse resource to XmDO_NOTHING. Otherwise, IRIS automatically deletes the window and, if the window uses an ApplicationShell, quits the application.

The callback you install can ask for user confirmation and can decide to comply or not comply with the request. If it decides to comply, your application can either pop down or destroy the window. If you think that the user might want to redisplay the window later, popping down the window is usually the better choice because your application doesn't have to re-create it later. Example 5-7 shows an example of installing a callback to handle the Delete Window message.

Atom WM_DELETE_WINDOW = XmInternAtom( XtDisplay(window),
                                      "WM_DELETE_WINDOW", 
                                      FALSE);
XmAddWMProtocolCallback( window, WM_DELETE_WINDOW,
                         closeCallback, NULL );
 
/* ... */

closeCallback( Widget w, XtPointer clientData,
               XmAnyCallbackStruct cbs )
{
    /* Delete or pop down window */
}

For support windows and dialogs, you typically want to dismiss the window when the user selects “Close.” Therefore, the default value of XmNdeleteResponse, XmDESTROY, is appropriate. Additionally, you should perform whatever other actions are appropriate for when that support window or dialog is dismissed. Typically, you can accomplish this by invoking the callback associated with the Cancel button, if it exists. Example 5-8 shows an example of this.

Atom WM_DELETE_WINDOW = XmInternAtom( XtDisplay(dialog),
                                      "WM_DELETE_WINDOW", 
                                      FALSE);
XmAddWMProtocolCallback( dialog, WM_DELETE_WINDOW,
                         cancelCallback, NULL );
 
/* ... */
 
cancelCallback( Widget w, XtPointer clientData,
                XmAnyCallbackStruct cbs )
{
    /* Perform cancel operations */
}

The “Save Yourself” protocol is part of the session management mechanism. The session manager sends a Save Yourself message to allow your application to update the command needed to restart itself in its current state. Currently, the session manager sends Save Yourself messages before ending a session (that is, logging out) and periodically while a session is active.

Your application doesn't need to subscribe to the Save Yourself protocol. Instead, your application can simply update the XmNargv and XmNargc resources on one of its ApplicationShells whenever it changes state, for example, when it opens or closes a file. The session manager re-saves its state information whenever your application changes these resources. (Actually, the session manager monitors the WM_COMMAND and WM_MACHINE properties, which are set by the ApplicationShell whenever you change its XmNargv and XmNargc resources.)

If you decide to use Save Yourself for session management, you can handle the protocol on any realized ApplicationShell. Don't use Save Yourself with the unrealized main window of the “Multiple Document, No Visible Main” application model. When the window manager sends a Save Yourself message to your application, your application must update the value of the XmNargv and XmNargc resources to specify the command needed to restart the application in its current state. Once you've updated the XmNargv and XmNargc resources, the session manager assumes that it can safely kill your application. Example 5-9 shows how to handle Save Yourself messages.

---

Note: Your application shouldn't prompt the user for input when it receives a Save Yourself message.

---

/* saveyourself.c                                       */
/*                                                     */
/* Example code for handling the window manager's        */
/* WM_SAVE_YOURSELF Protocol                            */
/*                                                     */
/* cc -o saveyourself saveyourself.c -lXm -lXt          */
 
#include <Xm/Protocols.h>
#include <Xm/Label.h>
 
void saveYourSelfCallback(Widget w,  XtPointer client_data, 
                             XtPointer call_data)
{
    printf(“Update WM_COMMAND or state file\n”);
}
 
void main(int argc, char** argv)
{
   Widget toplevel, label;
   XtAppContext app_context;
   Atom WM_SAVE_YOURSELF;
 
   toplevel = XtAppInitialize(&app_context, “SaveYourSelf”,
                              NULL, 0, &argc, argv, NULL, NULL, 0);
 
   label = XmCreateLabel(toplevel, “saveme”, NULL, 0);
   XtManageChild(label);
 
   WM_SAVE_YOURSELF = XmInternAtom( XtDisplay(toplevel),
                                      “WM_SAVE_YOURSELF”,
                                      FALSE);
 
   XmAddWMProtocolCallback( toplevel, WM_SAVE_YOURSELF,
                            saveYourSelfCallback, NULL );
 
   XtRealizeWidget(toplevel);
   XtAppMainLoop(app_context);
}

Your application might not be able to fully specify its state using command line options. In that case, you can design your application to create a state file to save its state and to read the state file when it restarts.

You should provide initial values for the window shell's x and y resources before mapping the window to specify its default location. The window manager ignores these values if the user requests interactive window placement or specifies a location using the -geometry option when invoking your application. You should not use the window's XmNgeometry resource to control initial window placement, either in your application's source code or its app-default file.

“Window Placement” in Chapter 3 of the IRIX Interactive User Interface Guidelines provides guidelines for controlling window placement.

If the user doesn't specify a window size and you don't explicitly set the window size in your application, the initial size of the window is determined by geometry management negotiations of the shell widget's descendents. Typically, the resulting size is just large enough for all of the descendent widget to fit “comfortably.” Optionally, you can specify a default initial size for a window by providing initial values for the window's width and height resources before mapping the window. You should not use the window's XmNgeometry resource to control initial window size, either in your application's source code or its app-default file.

You can also set several shell resources to specify minimum and maximum window sizes, minimum and maximum aspect ratios, and resizing increments for a window:

“Window Size” in Chapter 3 of the IRIX Interactive User Interface Guidelines provides guidelines for controlling window size.