Next: User Function Help File Up: Graphical Interface Help File Previous: guihelp()   Contents

setmenubar()

Usage:
setmenubar(res,menuName) replaces the current menubar with that
described in the xml resource res with name menuName; both res and
menuName are CHARACTER scalars



Keywords: xml
All menus in Carapace versions of MacAnova, including the default
menus, are set using XML resources.  These resources are based on the
XRC system in wxWidgets, with some MacAnova-specific extensions.
The resource variable is a CHARACTER scalar in XML format:
<?xml version="1.0"?>
  <resource>
    ...
  </resource>

Of course, all the action is in the ... where the menus are actually
specified.  The resource is a collection of objects.  Each object
has a type given by its class, and an identifier given by its name.
Within the object, you can have parameters that describe or modify
the object, and other objects that are called children of the containing
object.  

To set up a menu bar, the resource contains one object of class
wxMenuBar.  The name for that menubar is the menuName used in the
setmenubar() call.  For example, setmenubar(resource,"sampleMenu")
based on this excerpted resource:
<?xml version="1.0"?>
  <resource>
    <object class="wxMenuBar" name="sampleMenu">
      ...
    </object>
  </resource>

The children of a menu bar are objects of class cpcMenu; these are the
menus seen on the menu bar.  The children of a menu are items (objects
of class cpcMenuItem), separators (objects of class separator), and/or
submenus (more objects of class cpcMenu).  Here is an example, with
comments and explanations interspersed in the XML.

      <object class="cpcMenu" name="File_menu">
        <label>File</label>
Start a menu. The name (File_menu) should be unique, but is otherwise
not used.  The label determines how the menu will be shown on the
menu bar; here we have the File menu.
          <object class="cpcMenuItem" name="CPC_FILE_OPEN">
            <label>Open\tCtrl+O</label>
            <accel>Ctrl+O</accel>
            <help>Open a text file</help>
          </object>
Here we have a menu item with name CPC_FILE_OPEN.  Many names that
begin CPC_ correspond to predetermined actions; here, CPC_FILE_OPEN 
opens a text file in a new output window.  A list of these known
names is given below.  The label parameter determines how the item
will appear on the menu.  The accel parameter determines a keyboard
combination that is equivalent to selecting the menu item, here,
control plus O.  Finally, the help parameter is a message displayed
in the status bar at the bottom of the frame.
          <object class="separator"/>
This is a separator to produce a gap in the menu.
          <object class="cpcMenuItem" name="SaveWorkspace">
            <label>Save workspace\tCtrl+K</label>
            <accel>Ctrl+K</accel>
            <help>Save the workspace in a file</help>
            <action>save()</action>
          </object>
Here is a menu item with an action.  When a menu item with
an action is selected, the action value is sent to MacAnova as a
command, just as if you had typed it at the command line.  Please
note, if you add an action to one of the standard CPC_... named
items, the action will be ignored.
          <object class="cpcMenu" name="CPC_WINDOWS_TEXTWINDOW">
            <label>Output windows</label>
            <help>Select output window</help>
            <object class="cpcMenuItem" name="fake window">
              <label>fake</label>
            </object>
          </object>
Here is object that is another menu.  In this case, the menu named
CPC_WINDOWS_TEXTWINDOW has only a single fake item in the resource.
The menu with this name is updated automatically by Carapace to
reflect the command windows present.
          <object class="cpcMenuItem" name="CPC_HELP_HELP">\
            <label>$Help\tCtrl+L</label>\
            <accel>Ctrl+L</accel>\
            <selectionlabel>$Help on selection</selectionlabel>\
            <help>Help on MacAnova</help>\
            <action>guihelp()</action>\
            <hidecommand>1</hidecommand>\
            <selectionaction>guihelp(%s)</selectionaction>\
          </object>\
        </object>
You can make menus change slightly depending on whether or not anything
in the window is selected.  If there is a selectionlabel parameter,
that label will be used whenever something in the window is selected.
Similarly, the selectionaction will be used instead of the action
whenever something is selected.  In this case, the selected text will
replace the %s in the selectionaction parameter.  One additional
twist here is hidecommand.  Ordinarily, any action or selectionaction
command is printed in the output pane.  If hidecommand is 1, the
command will not be printed.  It is not shown here, but there is also
a hideoutput parameter. If hideoutput is 1, then any printing that
the command would do is suppressed.

Here are the standard names and their corresponding actions:
 CPC_FILE_OPEN            Open a file in an output window
 CPC_FILE_SAVEWINDOW      Save the contents of the output pane
 CPC_FILE_SAVEWINDOWAS    Save the contents, but change the name
 CPC_FILE_PAGESETUP       Set up for printing
 CPC_FILE_PRINTSELECTION  Print
 CPC_FILE_INTERRUPT       Interrupt execution
 CPC_FILE_QUIT            Quit
 CPC_FILE_FASTQUIT        No fooling around, just quit now

 CPC_EDIT_UNDO            Undo last edit/typing
 CPC_EDIT_CUT             Cut selection
 CPC_EDIT_COPY            Copy selection
 CPC_EDIT_PASTE           Paste selection
 CPC_EDIT_COPYTOEND       Copy selection to command line
 CPC_EDIT_EXECUTE         Execute the command line
 CPC_EDIT_UPHISTORY       Go back in command history
 CPC_EDIT_DOWNHISTORY     Go forward in command history

 CPC_WINDOWS_HIDE         Hide this window
 CPC_WINDOWS_CLOSE        Close this window
 CPC_WINDOWS_FASTCLOSE    Close this window, no chance to save
 CPC_WINDOWS_NEWWINDOW    Open a new command window
 CPC_WINDOWS_GRAPH        Nothing happens, this is a submenu
 CPC_WINDOWS_TEXTWFONT    Select command window font
 CPC_WINDOWS_GOTOTOP      Scroll to top of output pane
 CPC_WINDOWS_GOTOEND      Scroll to bottom of output frame
 CPC_WINDOWS_GOTOCOMMANDPOINT  Move focus to end of command pane


Gary Oehlert 2005-06-14