The MainWindow Widget and Menus

   

When designing a GUI, care must be taken in the presentation of the application's primary window. This window is important as it is likely to be the major focus of the application -- the most visible and most used window in the application. In order to facilitate consistency amongst many different applications, Motif provides a general framework: the MainWindow Widget, for an application developer to work with. The Motif Style Guide  (Chapter 18) recommends that, whenever applicable, the MainWindow window should be used. It should be noted, however, that the general framework of the MainWindow is not always applicable to every application front end GUI. A text editor application front end is an example that might easily map into the MainWindow framework, a simple calculator application most certainly would not fit the prescribed framework.

A MainWindow widget can manage up to five specialised child widgets (Fig 8.1):

  

Figure 8.1: The MainWindow Widget with its Specialised Child Widgets

• The menu bar   -- to which a number of pull down menus can be attached.
• The work area   -- the primary widget is placed here to perform the applications main functions.
• Vertical and Horizontal scroll bars   -- for the work area.
• The command area   -- where single-line commands can be entered by the user.
• The message area   -- where the application can report back to the user.

The MainWindow basically provides an efficient method of managing widgets as recommended by the Motif Style Guide (Chapter 18). In particular, the provision of a menu bar and work area is a convenient mechanism with which to drive many applications. It should be noted that the work area can be any widget (or composite hierarchy of widgets). The scrollbars, command and message area are optional.

In this Chapter, we will mainly concentrate our study on the relationship between the MainWindow and certain types of menus. We will also see how to put widgets in the work area MainWindow. We will see further applications of the MainWindow widget in the remainder of the book. The MainWindow will be used as a container widget in many example programs throughout the book.

The MainWindow widget

  

As we have previously stated, the MainWindow is typically used as the top level container for an application's child widgets. The simplest functional MainWindow may consist of a menu bar along the top of the application and some work area below, this is illustrated in Fig. 8.2. We omit the scroll bars and command and message areas for the time being.

 

Fig. 8.2 menu_cascade.c output

Menu bar items are placed within the menu bar  . You can use menu bar items to perform selections directly. However, more usually a PullDown menu is attached to a menu bar item allowing greater selection opportunities.

The function of the work area is to perform the main application's functions. The work area can be any widget class. We will look at aspects of this in later sections when we have studied more widget classes.

Initially, we will concentrate on how to create menus in a MainWindow.

The MenuBar

  

The creation of a fully functional pulldown MenuBar typical of most MainWindow based applications is fairly complex. We will, therefore, break it down into two stages.

1.

We will we create a simple MenuBar that lets us select actions directly from the bar (MenuBar items).

2.

Having created simple MenuBar items we will attach pulldown menus to them.

A simple MenuBar

A MenuBar widget is really a RowColumn widget under another name. The way we create a MenuBar is to use one of the (several) XmCreate$\ldots$ or XtVaCreate$\ldots$ Menu options. For most of our applications, we will use the XmCreateMenuBar()  function.

Having created a MenuBar we create MenuBar items by attaching widgets to the MenuBar in exactly the same fashion as described for the RowColumn widget (Chapter 7). The widgets we usually attach are CascadeButton widgets   since we can hang pull down menus off these widgets.

Fig. 8.2 shows the output of the menu_cascade.c  program that simply creates a simple MenuBar widget and attaches two CascadeButton widgets - help and quit. Minimal callback functions are associated with each CascadeButton.

The full program listing of menu_cascade.c is:

 
#include <Xm/Xm.h>
#include <Xm/MainW.h>
#include <Xm/CascadeB.h>

/* Prototype callbacks */
void quit_call(void), help_call(void); 

main(int argc, char **argv)

{
    Widget top_wid, main_w, menu_bar, quit, help;
    XtAppContext app;
    Arg arg[1];
    
    /* create application, main and menubar widgets */
    
    top_wid = XtVaAppInitialize(&app, "menu_cascade",
        NULL, 0, &argc, argv, NULL, NULL);

    main_w = XtVaCreateManagedWidget("main_window",
        xmMainWindowWidgetClass,   top_wid,
        NULL);

    menu_bar = XmCreateMenuBar(main_w, "main_list", 
        NULL, 0);        
    XtManageChild(menu_bar);
    
    
     /* create quit widget + callback */
        
    quit = XtVaCreateManagedWidget( "Quit",
        xmCascadeButtonWidgetClass, menu_bar,
        XmNmnemonic, 'Q',
        NULL);
        
    
    XtAddCallback(quit, XmNactivateCallback, quit_call, NULL);

    /* create help widget + callback */
        
    help = XtVaCreateManagedWidget( "Help",
        xmCascadeButtonWidgetClass, menu_bar,
        XmNmnemonic, 'H',
        NULL);
        
    
    XtAddCallback(help, XmNactivateCallback, help_call, NULL);

    /* Tell the menubar which button is the help menu  */

    XtSetArg(arg[0],XmNmenuHelpWidget,help);
    XtSetValues(menu_bar,arg,1);
    
        
    XtRealizeWidget(top_wid);
    XtAppMainLoop(app);
}


void quit_call()

{   printf("Quitting program\n");
    exit(0);
}

void help_call()

{   printf("Sorry, I'm Not Much Help\n");
}

The first steps of the main function should now be familiar -- we initialise the application and create the top_wid top level widget.

A MainWindow widget , main_win, is then created as is a MenuBar  , menu_bar. The menu_bar widget is a child of main_win. Finally, we attach two CascadeButton   widgets, quit and help, as children of menu_bar. Note there is no work area created in this program.

A CascadeButton   widget is usually used to attach a pulldown menu to the MenuBar. This CascadeButton widget is similar to the PushButton widget and can have callback functions attached to its activateCallback  function -- illustrated in the menu_cascade.c program. However, it should be noted, that the main use of CascadeButton is to link a menu bar with a menu.

The program above simply attaches callback functions to the CascadeButtons. The callback functions do not do much except quit the program and print to standard output.

You can also associate a mnemonic  to a particular menu selection. This means that you can use ``hot keys'' on the keyboard as a short cut to selection. You need to press Meta key  plus the key in question.

In this program, we allow Meta-Q and Meta-H for the selection of Quit and Help. Note that Motif displays the appropriate Meta key by underlining the letter concerned on the menu bar (or menu item). The XmNmnemonic  resource is used to select the appropriate keyboard short cut.

Apart from prescribing the use of the Meta key for the selection of menu items, the Motif Style Guide  also insists that the Help MenuBar widget should always be placed on the right most side of the MenuBar (Fig. 8.2). This makes for easy location and selection of the help facility, should it exist.

The MenuBar resource, XmNmenuHelpWidget , is used to store the ID of the the appropriate widget (help in the above program).

PullDown Menus

  

Let us now develop things a little further by adding pulldown menus to our MenuBar. A pulldown menu looks like this:

 

Fig. 8.3 menu_pull.c output

In order to see how we create and use pulldown menu items we will develop a program, menu_pull.c  that will create two pulldown menus:

• Quit which will contain a single item that lets us terminate our program.
• Menu which has 5 options that change the XmNlabelString of a label widget attached to the MainWindow as the work area.

We also attach the Help Cascade button as in the previous menu_cascade.c program.

We should now be familiar with the first few steps of this program: We create the top level widget hierarchy as usual, with the MainWindow widget being a child of the application and a MenuBar widget a child of the MainWindow.

The complete listing of menu_pull.c is as follows:

 

#include <Xm/Xm.h>
#include <Xm/MainW.h>
#include <Xm/CascadeB.h>
#include <Xm/Label.h>

/* prototype functions */

void quit_call(Widget , int), 
       menu_call(Widget , int),
       help_call(void);


Widget label;
String food[] = { "Chicken",  "Beef", "Pork", "Lamb", "Cheese"};



main(int argc, char **argv)

{   Widget top_wid, main_w, help;
    Widget  menubar, menu, widget;
    XtAppContext app;
    XColor back, fore, spare;
    XmString  quit, menu_str,  help_str, chicken, beef, pork, 
              lamb, cheese, label_str;
    
    int n = 0;
    Arg args[2];

    /* Initialize toolkit */
    top_wid = XtVaAppInitialize(&app, "Demos",
        NULL, 0, &argc, argv, NULL, NULL);
        
    

    /* main window will contain a MenuBar and a Label  */
    main_w = XtVaCreateManagedWidget("main_window",
        xmMainWindowWidgetClass,   top_wid,
        XmNwidth, 300,         
        XmNheight, 300,
        NULL);

    /* Create a simple MenuBar that contains three menus */
    quit = XmStringCreateLocalized("Quit");
    menu_str = XmStringCreateLocalized("Menu");
    help_str = XmStringCreateLocalized("Help");

    
    menubar = XmVaCreateSimpleMenuBar(main_w, "menubar",
        XmVaCASCADEBUTTON, quit, 'Q',
        XmVaCASCADEBUTTON, menu_str, 'M',
        XmVaCASCADEBUTTON, help_str, 'H',
        NULL);
        
        
    XmStringFree(menu_str); /* finished with this so free */
    XmStringFree(help_str);
    
    /* First menu is the quit menu -- callback is quit_call() */
    
    XmVaCreateSimplePulldownMenu(menubar, "quit_menu", 0, quit_call,
        XmVaPUSHBUTTON, quit, 'Q', NULL, NULL,
        NULL);
    XmStringFree(quit);

    /* Second menu is the food menu -- callback is menu_call() */
    chicken = XmStringCreateLocalized(food[0]);
    beef = XmStringCreateLocalized(food[1]);
    pork = XmStringCreateLocalized(food[2]);
    lamb = XmStringCreateLocalized(food[3]);
    cheese = XmStringCreateLocalized(food[4]);
    
    menu = XmVaCreateSimplePulldownMenu(menubar, "edit_menu", 1, 
        menu_call,
        XmVaRADIOBUTTON, chicken, 'C', NULL, NULL,
        XmVaRADIOBUTTON, beef, 'B', NULL, NULL,
        XmVaRADIOBUTTON, pork, 'P', NULL, NULL,
        XmVaRADIOBUTTON, lamb, 'L', NULL, NULL,
        XmVaRADIOBUTTON, cheese, 'h', NULL, NULL,
        /* RowColumn resources to enforce */
        XmNradioBehavior, True,    
        /* select radio behavior in Menu */ 
        XmNradioAlwaysOne, True,   
        NULL);
    XmStringFree(chicken);
    XmStringFree(beef);
    XmStringFree(pork);
    XmStringFree(lamb);
    XmStringFree(cheese);


    /* Initialize menu so that "chicken" is selected. */
    if (widget = XtNameToWidget(menu, "button_1"))
       { XtSetArg(args[n],XmNset, True);
         n++; 
         XtSetValues(widget, args, n);
       }

    n=0; /* reset n */

     /* get help widget ID to add callback */
        
    help = XtVaCreateManagedWidget( "Help",
        xmCascadeButtonWidgetClass, menubar,
        XmNmnemonic, 'H',
        NULL);
     
    XtAddCallback(help, XmNactivateCallback, help_call, NULL);

     /* Tell the menubar which button is the help menu  */

     XtSetArg(args[n],XmNmenuHelpWidget,help);
     n++;
     XtSetValues(menubar,args,n);
     n=0; /* reset n */
   


    
    XtManageChild(menubar);
    
   /* create a label text widget that will be "work area" 
      selections from "Menu"  menu change label
      default label is item 0 */

    label_str = XmStringCreateLocalized(food[0]);
    
    label = XtVaCreateManagedWidget("main_window",
        xmLabelWidgetClass,   main_w,
        XmNlabelString, label_str,
        NULL);
        
     XmStringFree(label_str);
      
    /* set the label as the "work area" of the main window */
    XtVaSetValues(main_w,
        XmNmenuBar,    menubar,
        XmNworkWindow, label,
        NULL);
        
         
    XtRealizeWidget(top_wid);
    XtAppMainLoop(app);
}

/* Any item the user selects from the File menu calls this function.
   It will "Quit" (item_no == 0).  */

void
quit_call(Widget w, int item_no)

   /* w = menu item that was selected 
      item_no = the index into the menu */

{
    

    if (item_no == 0) /* the "quit" item */
        exit(0);

   }


/* Called from any of the food "Menu" items.  
   Change the XmNlabelString of the label widget. 
   Note: we have to use dynamic setting with setargs().
 */

void  menu_call(Widget w, int item_no)
                          

{
    int n =0;
    Arg args[1];
    
    XmString   label_str;     
    
    label_str = XmStringCreateLocalized(food[item_no]);
           
    XtSetArg(args[n],XmNlabelString, label_str);      
    ++n;
    XtSetValues(label, args, n);
  
}

 

void help_call()

{   printf("Sorry, I'm Not Much Help\n");
}

In this program we create the MenuBar widget with the convenience function XmVaCreateSimpleMenuBar() :

• The first two arguments of this function specify the parent widget (The MainWindow, main_w, in this case) and the name of the widget, respectively.
• The following arguments are a NULL terminated variable length list of resource name/value pairs.

  In menu_pull.c, we set up two CascadeButtons   by setting the
  XmVACASCADEBUTTON  resource. Two arguments are associated with this resource:

  • A label specified by an XmString.
  • The mnemonic  or Meta key  associated with the CascadeButton.

  Note: we convert a String to an XmString with the
  XmStringCreateLocalized() function.

  It is good practice to free an XmString as soon as you have finished using it with the XmStringFree() command. Several ``open'' XmStrings can occupy a significant amount of application memory.

The creation of a pulldown menu is now relatively straightforward:

• We create a PullDownMenu   widget
• Attach the PullDownMenu widget to a MenuBar item by simply making the PullDownMenu Widget a child of the MenuBar's CascadeButton.

Let us now look at how we create  the Quit menu:

 
quit_w = XmVaCreateSimplePulldownMenu(menubar, "quit_menu", 
             0, quit_call,
             XmVaPUSHBUTTON, quit, 'Q', NULL, NULL,
             NULL);

We have used the Motif convenience function XmVaCreateSimplePulldownMenu()  to return a PulldownMenu widget. This function has several arguments:

• The first argument is the parent widget (MenuBar in this example).
• The second is the name given to the widget for resource lookup.
• The third argument is the integer ID that specifies which CascadeButton (from the MenuBar) the PulldownMenu is attached to.

  Thus, in this program an integer ID of 0 is attached to the Quit button and an ID of 1 would be attached to the Menu button.

• The fourth argument specifies the callback  function associated with a menu choice.

  Note: We do not specify a callback with an XtAddCallback() call in this instance.

• A NULL terminated resource name/value list . The list specifies the type and values of PulldownMenu items. Many possible classes area allowed, including further CascadeButtons, RadioButtons, CheckButtons. This program creates PushButton Menu items:

  To specify a PushButton menu item, set a XmVaPUSHBUTTON resource list item and corresponding XmString label and Meta key accordingly for the list entry. XmVaPUSHBUTTON actually takes four arguments, the last two are only needed for advanced Motif use, so are not considered here -- they are just set to NULL.

  The Menu menu is created in a similar way except that we have 5 menu items.

  We may have one, minor, problem when assigning Meta keys. This is illustrated for the Menu items since we cannot have the same Meta key for two menu selections. So Meta-B is chosen for Beef and Meta-L for Lamb, etc. However, Chicken and Cheese must be assigned different Meta keys, so we allocate Meta-C for Chicken and Meta-h for cheese selections.

The last thing we need to look at is how we find out which selection has been made in our program.

Each PulldownMenu has an associated callback function . The callback function of a pulldown has two parameters, which we must define.

• The widget that called the function.
• An index to the menu item selected (starts at 0).

So, in the Quit callback, quit_call(), we only have one possible selection (item_no must equal zero).

In the Menu callback, menu_call(), the index corresponds to a food item setting of Chicken, Beef, $\ldots$ etc..

Chapter 18 discusses aspects of the Motif Style guidelines for menus which also incorporate some general menu design issues.

Tear-off menus

  

Tear-off menus allow the user to remove (or tear) a menu off the MenuBar and keep it displayed in a small dialog window on the screen until the user closes it from the window menu. The Motif Style Guide  (Chapter 18) prescribes this for menus that are frequently used in order to ease menu selection In order to make a menu a tear-off variety the XmNtearOffModel  resource for a PullDownMenu widget needs to set to XmTEAR_OFF_ENABLED. If a menu is XmTEAR_OFF_ENABLED then its appearance is modified to include a small perforated line at the top of the menu.

Other MainWindow children

  So far in this Chapter we have concentrated on the MenuBar and work area parts of the MainWindow. In this section we will develop a simple program, test_for_echo.c , which creates and uses the command and message areas of the MainWindow. We create a minimal MenuBar that simply allows you to quit the program. The work area created is a Label widget that does not perform any useful task in this example. The command and message areas created are both TextField   widgets (see Chapter 10 for a complete description of the TextField widget). The command area receives (String) input and echoes it to the message area (Fig 8.4). The message area is not usually allowed to receive any user input. In this example we set the XmNeditable resource for the message area to be False

TextField, Label or Command widgets are typically employed as the command and message areas.

 

Fig. 8.4 The test_for_echo.c program output The test_for_echo.c program achieves this by:

• Creating a Menubar, Label   and 2 TextField   widgets and assigning their IDs to the MainWindow resources XmNmenuBar, XmNworkWindow, XmNcommandWindow    and XmNmessageWindow  respectively to form the complete Mainwindow widget (Fig 8.4).
• A callback, cmd_cbk, is attached to the XmNactivateCallback  event for the command area widget.
• The cmd_cbk callback parses the input command area widget, cmd_widget, for the input string and replaces the message area widget, msg_wid, with this string.
• Section 8.3 in the following Chapter explains the text handling part of this program further.

The complete program listing for test_for_echo.c is as follows:

#include <Xm/MainW.h>
#include <Xm/Label.h>
#include <Xm/Command.h>
#include <Xm/TextF.h>

#include <stdio.h>  
#include <string.h> /* For String Handling */

#define MAX_STR_LEN 30 /* Max Char length of Text Field */

/* Callback function prototypes */

void   cmd_cbk(), quit_cbk();

Widget   msg_wid;

char *cmd_label  = "Command Area: ";
char *msg_label  =  "Message Area: ";

int cmd_label_length;
int msg_label_length;


main(int argc,  char **argv)

{
    Widget        top_wid, main_win, menubar, menu,   
                  label, cmd_wid;
    XtAppContext  app;
    XmString      label_str, quit;

    cmd_label_length = strlen(cmd_label);
    msg_label_length = strlen(msg_label);

    /* initialize toolkit and create top_widlevel shell */
    top_wid = XtVaAppInitialize(&app, "Main Window",
        NULL, 0, &argc, argv, NULL, NULL);


    /* Create MainWindow */    

   main_win = XtVaCreateWidget("main_w",
        xmMainWindowWidgetClass, top_wid,
        XmNcommandWindowLocation, XmCOMMAND_BELOW_WORKSPACE,
        NULL);

    /* Create a simple MenuBar that contains one menu */
    quit = XmStringCreateLocalized("Quit");
    menubar = XmVaCreateSimpleMenuBar(main_win, "menubar",
        XmVaCASCADEBUTTON, quit, 'Q',
        NULL);


    menu = XmVaCreateSimplePulldownMenu(menubar, "file_menu", 0, 
        quit_cbk,
        XmVaPUSHBUTTON, quit, 'Q', NULL, NULL,
        NULL);

    XmStringFree(quit);

    /*  Manage Menubar */

    XtManageChild(menubar);

    /* create a label text widget that wil be work area  */
    label_str = XmStringCreateLocalized("Work Area");
    
    label = XtVaCreateManagedWidget("main_window",
        xmLabelWidgetClass,   main_win,
        XmNlabelString, label_str,
        XmNwidth, 1000,         
        XmNheight, 800,
        NULL);
        
     XmStringFree(label_str);


    /* Create the command area  */

   
    cmd_wid = XtVaCreateWidget(  "Command",
        xmTextFieldWidgetClass,  main_win,
        XmNmaxLength, MAX_STR_LEN,
       NULL);


    XmTextSetString(cmd_wid,cmd_label);
    XmTextSetInsertionPosition(cmd_wid, cmd_label_length);

    XtAddCallback(cmd_wid, XmNactivateCallback, cmd_cbk);

    XtManageChild(cmd_wid);  


 /* Create the message area  */
   
    msg_wid= XtVaCreateWidget(  "Message:",
        xmTextFieldWidgetClass,   main_win,
        XmNeditable, False,
        XmNmaxLength, MAX_STR_LEN,
        NULL);

    XmTextSetString(msg_wid,msg_label);
  
    XtManageChild(msg_wid);

/* set the label as the work, command and message areas
   of the main window */

    XtVaSetValues(main_win,
        XmNmenuBar,    menubar,
        XmNworkWindow, label,
        XmNcommandWindow, cmd_wid,
        XmNmessageWindow,msg_wid,
        NULL);

    XtManageChild(main_win);
    XtRealizeWidget(top_wid);
    XtAppMainLoop(app);
}

/* execute the command and redirect message area */

void cmd_cbk(Widget cmd_widget, XtPointer *client_data, 
            XmAnyCallbackStruct  *cbs)
{
    char cmd[MAX_STR_LEN],msg[MAX_STR_LEN];
                         									                  
    XmTextGetSubstring(cmd_widget,cmd_label_length, 
            MAX_STR_LEN - cmd_label_length, MAX_STR_LEN ,cmd);        
        
    /* Append input message to Message area */
    
    XmTextReplace(msg_wid,msg_label_length, MAX_STR_LEN,cmd);

    /* Reset Command Area label  and insertion point*/  

    XmTextSetString(cmd_widget, cmd_label);
    XmTextSetInsertionPosition(cmd_widget, cmd_label_length);    
}

void  quit_cbk(Widget w, int item_no)

{    if (item_no == 0) /* the "quit" item */
        exit(0);
}