Skip to main content

This is documentation for Caché & Ensemble.

For information on converting to InterSystems IRIS, see the InterSystems IRIS Adoption Guide and the InterSystems IRIS In-Place Conversion Guide, both available on the WRC Distributions page (login required).

Previous sectionNext section

Client Side Menu Components

Note:

The style for more traditional menu components is defined with CSS and HTML, without the option for subsequent post-processing in JavaScript. For full information about those components, see the “Navigation Components” chapter of Using Zen Components.

Building Client Side Menus

The original <menu> component offers a simple HTML label in a box with all of its (limited) rendering done at the server with a little help from CSS preferences. It is perfectly serviceable as a menu, but its appearance has very little flexibility.

In contrast, the <csMenuBar> defers its rendering until it has actually been loaded by the client and has access to more information about the user’s machine (browser, operating system, available fonts, etc). The <csMenuBar> makes heavy use of JavaScript to do things that are difficult (or in some cases impossible) to do with CSS alone. It can render a menu that looks and acts more like a user might find in applications such as Microsoft Outlook or Word. This menu includes features such as icons, keyboard shortcuts, scrolling of long menus without scrollbars, and so on.

In general, the cs prefixed widgets such as <csMenuBar> form one set of tools, while the traditional menu widgets described in the “Navigation Components” chapter of Using Zen Components form another. These sets are not interchangeable. For example, a <csMenuBar> consists of <csMenuBarItem>, <contextMenu>, <csMenuItem>, and <csMenuSeparator> elements. A mixed specification in which <csMenuItem> elements are separated by <menuSeparator> elements causes the menu subsystem to break.

It is important to note that there is inconsistency in the naming conventions. Not all of the client side widget names start with cs. The cs prefix is used only when the newer, client side widget name conflicts with the older, original widget names. Unfortunately this means that <contextMenu>, the widget at the heart of the client side menu subsystem, does not use the cs prefix, but every element around it does.

The following is a summary of the nesting structure for the client side menu elements:

<csMenuBar>
    <csMenuBarItem>
        <contextMenu>
            <csMenuItem />
            <csMenuItem />
            <csMenuSeparator />
            <csMenuItem />
            <csMenuItem>
                <contextMenu>
                    <csMenuItem />
                    <csMenuItem />
                </contextMenu>
            </csMenuItem>
        </contextMenu>
    </csMenuBarItem>
</csMenuBar>
Copy code to clipboard

The next several sections describe how to work with client side menu components to provide:

For a syntax guide to specific components, see the later sections in this chapter:

Drop Down Menus

The following sample <csMenuBar> element defines a horizontal menu bar with two picks: File and Edit. Each of these picks displays a different <contextMenu>. The <csMenuItem> components in this example illustrate a variety of options for setting associated icons, alternate captions, keyboard shortcuts, and so on. The following figure illustrates the File pick from this menu.

File Drop Down Menu with Icons and Keyboard Shortcuts
generated description: csmenu file
<csMenuBar id="mainMenu" width="100%">
  <csMenuBarItem caption="File" contextKey="f" >
    <contextMenu id="fileMenu" >
      <csMenuItem icon="images/file.png" caption="New" key="Ctrl-N"
                  contextKey="n" onclick="alert('New requested');"  />
      <csMenuItem icon="/csp/broker/images/open.png" caption="Open..."
                  key="Ctrl-O" contextKey="o"
                  onclick="alert('Open requested');"  />
      <csMenuItem caption="Close" key="Ctrl-W"
                  contextKey="c" onclick="alert('Open requested');"  />
      <csMenuSeparator />
      <csMenuItem id="savePick" icon="/csp/broker/images/save.png"
                  iconDisabled="/csp/broker/user/images/save_g.png"
                  caption="Save" key="Ctrl-S" contextKey="s"
                  onclick="alert('Save requested');"  />
      <csMenuItem icon="/csp/broker/images/saveas.png" caption="Save as..."
                  contextKey="a" />
      <csMenuItem icon="/csp/broker/images/saveall.png" caption="Save All"
                  contextKey="l" />
      <csMenuSeparator />
      <csMenuItem icon="/csp/broker/images/print.png" caption="Print"
                  key="Ctrl-P" contextKey="p"
                  onclick="alert('Print requested');" />
      <csMenuItem caption="Print Preview..."  contextKey="v" />
      <csMenuItem caption="Print Setup..."  contextKey="r" />
      <csMenuSeparator />
      <csMenuItem caption="Recent Files"  contextKey="e" />
      <csMenuSeparator />
      <csMenuItem caption="Exit" contextKey="x" />
    </contextMenu>
  </csMenuBarItem>
  <csMenuBarItem caption="Edit" contextKey="e">
    <contextMenu id="editMenu" >
      <csMenuItem id="undoPick" icon="/csp/broker/images/undo.png"
                  caption="Undo" key="Ctrl-Z" altCaption="Can't undo"
                  contextKey="u" onclick="alert('undo');" />
      <csMenuItem id="redoPick" icon="/csp/broker/images/redo.png"
                  caption="Redo" key="Ctrl-Y" altCaption="Can't redo"
                  contextKey="r" onclick="alert('redo');" />
      <csMenuSeparator />
      <csMenuItem id="cutPick" icon="/csp/broker/images/cut.png"
                  caption="Cut" key="Ctrl-X" contextKey="t"
                  onclick="alert('cut');" />
      <csMenuItem id="copyPick" icon="/csp/broker/images/copy.png"
                  caption="Copy" key="Ctrl-C" contextKey="c"
                  onclick="alert('copy');"  />
      <csMenuItem id="pastePick" icon="/csp/broker/images/paste.png"
                  caption="Paste" key="Ctrl-V" contextKey="p"
                  onclick="alert('paste');"  />
      <csMenuSeparator />
      <csMenuItem caption="Fill" contextKey="i" onclick="alert('fill');" />
      <csMenuItem caption="Clear" contextKey="a" onclick="alert('clear');" />
      <csMenuItem caption="Delete..." key="delete"
                  contextKey="d" onclick="alert('delete');"  />
      <csMenuSeparator />
      <csMenuItem caption="Select all" key="Ctrl-A"
                  contextKey="l" onclick="alert('select all');" />
      <csMenuSeparator />
      <csMenuItem icon="/csp/broker/images/find.png" caption="Find..."
                  key="Ctrl-F" contextKey="f" onclick="alert('find');" />
      <csMenuItem caption="Find in Files" key="Ctrl-Shift-F"
                  onclick="alert('find next');" />
      <csMenuItem caption="Replace..." key="Ctrl-H" contextKey="e"
                  onclick="alert('replace');" />
      <csMenuItem icon="/csp/broker/images/goto.png" caption="Go to..."
                  key="ctrl-g" contextKey="g" onclick="alert('goto');" />
    </contextMenu>
  </csMenuBarItem>
</csMenuBar>
Copy code to clipboard

The following figure illustrates the Edit pick from this menu.

Edit Drop Down Menu with Icons and Keyboard Shortcuts
generated description: csmenu edit

Menu Picks or Choices

Zen client side menus support the following types of menu pick:

Type of Pick User Action Result
Regular menu Click
Zen invokes the callback specified by the onclick attribute.
You can define a regular menu pick with just a caption and an onclick callback, but you can also add an icon, or a keyboard shortcut using key or contextKey. For example:
For some images that you can use in menu picks, see the section “Icons.”
Cascading menu Roll over
Zen displays a submenu.
You can cascade menus by nesting <contextMenu> elements within <csMenuItem> elements. See the examples in the sections “Building Client Side Menus” and “Popup or Context Menus.”
Alternating caption Click
Zen invokes the callback specified by the onclick attribute. The toggleState property flips its value (from 0 to 1 or from 1 to 0) when the user clicks the menu pick. The caption label changes automatically, as in “Show” vs. “Hide.”
For an alternating caption pick, define both a caption and an alternate caption (altCaption) as shown in the following example:
Optionally, you can also specify an icon and altIcon so that the icon can be toggled along with the caption.
A toggleState of 0 displays the caption and icon; 1 displays the altCaption and altIcon. The toggleState changes only in response to user actions.

Popup or Context Menus

You can use client-side menu components to define a popup or context menu for a region. To accomplish this, wrap a <contextMenu> definition inside a group of some kind. The wrapper component can be nearly anything, but is most often a reasonably significant portion of the page: a <vgroup>, <hgroup>, <form>, etc. Define the <contextMenu> as a child of the wrapper component, and a sibling of other elements within the wrapper. You can optionally specify exact bounds, as for the <group> shown in the next example, but this is not required.

Subsequently, when the user right-clicks the mouse anywhere within the wrapper component, Zen displays and activates the <contextMenu> child component, rather than the browser’s default right-click menu.

<group width="400" height="800" enclosingStyle="background:#aaffaa;" >
  <contextMenu id="rightPopUp" >
    <csMenuItem caption="Fido Cascade" >
      <contextMenu >
        <csMenuItem caption="Sit" />
        <csMenuItem caption="Stay" />
        <csMenuItem caption="Play dead" />
      </contextMenu>
    </csMenuItem>
    <csMenuItem caption="Scout Cascade" >
      <contextMenu >
        <csMenuItem caption="Whoa" />
        <csMenuItem caption="Giddy Up" />
      </contextMenu>
    </csMenuItem>
    <csMenuItem caption="Kitty Cascade" >
      <contextMenu >
        <csMenuItem caption="Ignore me" />
        <csMenuItem caption="Do as you please" />
      </contextMenu>
    </csMenuItem>
  </contextMenu>
</group>
Copy code to clipboard

The following figure displays the popup menu that the previous example defines.

Popup Menu with Submenus
generated description: csmenu rightclick

Cascading Menus

You can cascade menus by nesting <contextMenu> elements within <csMenuItem> elements. This cascading technique works for regular menus as well as for popup or context menus. See the examples in the opening section of this chapter, “Building Client Side Menus,” and in the previous section, “Popup or Context Menus.”

Button Bars

<hgroup id="bbArea" >
  <buttonBar id="editStuff" >
    <buttonBarItem icon="images/cut.png" caption="Cut"
                   onclick="alert('Cut requested');"  />
    <buttonBarItem icon="images/copy.png" caption="Copy"
                   onclick="alert('Copy requested');"  />
    <buttonBarItem icon="images/paste.png" caption="Paste"
                   onclick="alert('Paste requested');"  />
  </buttonBar>
</hgroup>
Copy code to clipboard

The style for this bar is defined in the XData Style section as follows:

#bbArea {
  background:#bbbbbb;
  background-image: url(images/grad-halfgray-10x30.png);
  background-repeat:repeat-x;
}
Copy code to clipboard

The following figure displays the button bar that this example defines.

Button Bar with Icons
generated description: csbuttonbar

For some image files that you can use as icons in button bars, see the section “Icons.”

Icons

The following table lists the icons that are available in the csp/broker/images directory, which is a subdirectory of the Caché installation directory. The gray background color shown for icons in the table is just an example; the icons display over whatever background color the designer chooses for the containing component.

Icon images may be referenced using the icon, altIcon, or disabledIcon attributes in Zen components such as <buttonBarItem> or <csMenuItem>. When you reference these images, the prefix csp/broker is automatically implied. Reference them using this syntax:

images/filename

For example:

altIcon="images/cut.png"

Zen Icon Library
Icon File Name Meaning
generated description: icon buildall buildall.png Build all or compile all files
generated description: icon compile compile.png Compile current file
generated description: icon copy copy.png Copy
generated description: icon cut cut.png Cut
generated description: icon downarrow DownArrow.png Down arrow, larger size, for light background colors
generated description: icon downarrowinv DownArrowInv.png Down arrow, larger size, for dark background colors
generated description: icon smdownarrow SmDownArrow.png Down arrow, smaller size, for light background colors
generated description: icon smdownarrowinv SmDownArrowInv.png Down arrow, smaller size, for dark background colors
generated description: icon file file.png File or document
generated description: icon find find.png Find or search
generated description: icon goto goto.png Go to
generated description: icon inspect inspect.png Inspect
generated description: icon smleftarrow SmLeftArrow.png Left arrow, smaller size, for light background colors
generated description: icon smleftarrowinv SmLeftArrowInv.png Left arrow, smaller size, for dark background colors
generated description: icon open open.png Open file, folder, or document
generated description: icon output output.png Output
generated description: icon paste paste.png Paste
generated description: icon print print.png Print
generated description: icon redo redo.png Redo previous operation
generated description: icon redo g redo_g.png Redo previous operation, grayed out
generated description: icon reload reload.png Reload
generated description: icon rtarrow RtArrow.png Right arrow, larger size, for light background colors
generated description: icon rtarrowinv RtArrowInv.png Right arrow, larger size, for dark background colors
generated description: icon smrightarrow SmRightArrow.png Right arrow, smaller size, for light background colors
generated description: icon smrightarrowinv SmRightArrowInv.png Right arrow, smaller size, for dark background colors
generated description: icon save save.png Save file, folder, or document
generated description: icon save g save_g.png Save file, folder, or document, grayed out
generated description: icon saveall saveall.png Save all files or documents
generated description: icon saveas saveas.png Save current file or document to a new file
generated description: icon undo undo.png Undo previous operation
generated description: icon undo g undo_g.png Undo previous operation, grayed out
generated description: icon uparrow UpArrow.png Up arrow, larger size, for light background colors
generated description: icon uparrowinv UpArrowInv.png Up arrow, larger size, for dark background colors
generated description: icon smuparrow SmUpArrow.png Up arrow, smaller size, for light background colors
generated description: icon smuparrowinv SmUpArrowInv.png Up arrow, smaller size, for dark background colors
generated description: icon viewother viewother.png View other, such as the compiled routine for a class
generated description: icon watch watch.png Watch
generated description: icon workspace workspace.png Workspace
generated description: icon world world.png World, as in World Wide Web

The nameInv.png images are used automatically in place of their name.png counterparts when Zen detects that it is rendering the icon against a dark background color. name.png icons are intended for use against light background colors. This behavior can be seen in the system default color scheme for Zen, as follows:

  1. The dark arrow over the light background:

    generated description: csmenu rightclick before

  2. ...automatically changes to a light arrow when it is over a dark background:

    generated description: csmenu rightclick inv

  3. ...and changes back to a dark arrow when it is over a light background:

    generated description: csmenu rightclick

The switch to using light or dark icons happens automatically, as long as you define the foreground and background colors of both <csMenuItem> and <csActiveMenuItem> using CSS. This allows Zen to calculate which icon yields optimum contrast with the current color. This is important even if the foreground or background color is being created using an image to create a gradient effect, as seen in the dark blue selected items in the previous examples.

<csMenuBar>

<csMenuBar> has the following attributes.

Attribute Description
Zen group attributes <csMenuBar> has the same style and layout attributes as other Zen groups. For descriptions, see “Group Layout and Style Attributes” in the “Zen Layout” chapter of Using Zen.

<csMenuBarItem>

<csMenuBarItem> has the following attributes.

<contextMenu>

The group may contain other elements besides <contextMenu>, but to allow other elements to appear inside the group along with <contextMenu> you must set the containing group’s layout attribute to "none". In the following example, a <button> appears in addition to the <contextMenu>, so the <form> has layout set to "none":

<form height="600" width="400" layout="none" > 
  <button caption="MyButton"/>
  <contextMenu id="cm1">
    <csMenuItem caption="context"/>
    <csMenuItem caption="menu"/>
    <csMenuItem caption="1"/>
  </contextMenu>
</form>
Copy code to clipboard

To understand more about how <contextMenu> may be used to specify various types of menus, see the examples in the sections “Building Client Side Menus” and “Popup or Context Menus.”

A <contextMenu> component may contain as many sibling <csMenuItem> and <csMenuSeparator> components as are required to define and organize the individual choices on the menu.

<contextMenu> has the following attributes.

Attribute Description
Zen group attributes <contextMenu> has the same style and layout attributes as other Zen groups. For descriptions, see “Group Layout and Style Attributes” in the “Zen Layout” chapter of Using Zen.

<csMenuItem>

<csMenuItem> has the following attributes.

<csMenuSeparator>

The <csMenuSeparator> component has no attributes. For example:

<csMenuSeparator />
Copy code to clipboard

For more detailed examples, see the section “Drop Down Menus.”

<buttonBar>

<buttonBar> has the following attributes.

Attribute Description
Zen group attributes <buttonBar> has the same style and layout attributes as other Zen groups. For descriptions, see “Group Layout and Style Attributes” in the “Zen Layout” chapter of Using Zen.

<buttonBarItem>

<buttonBarItem> has the following attributes.