Live Menu Specification Language (LMSL)

Panorama Live Menus are specified using a special language called LMSL (Live Menu Specification Language). Each line in this language controls a menu item, or an entire menu. Special characters in the line tell Panorama what style to use to display the menu item, how to attach submenus, what to do when a menu is chosen, and many more things.

Panorama includes a set of functions for easily generating LMSL text, including menu(, menuitem(, menuseparator(, arraymenuitems(, standardfilemenu(, standardeditmenu( and several more. There’s a function for anything you want to do to create a live menu, so for most users there is no reason to learn LMSL. However, it can be handy for advaced topics, and for debugging.

The basic component of LMSL is a line. Each line contains a complete description of a menu header or menu item. You can’t split the description of a single menu item over two or more lines, and you can’t pack descriptions of two or more menu items into a single line.

#### Menus

In LMSL, the first line is always the name of the entire menu, and you can include additional menus as well. The name must be surrounded with ( and ) characters, for example:

    (Action)
    (Color)
    (Appointments)

Note: The actual menu titles will not contain the parentheses, so (Action) will create the `Action` menu.

#### Menu Items

If a line is not surrounded with ( and ) characters, it is a menu item. In its simplest form, each line simply contains the name of the item. Here is a menu named Color with three menu items.

    (Color)
    Red
    Green
    Blue

In most examples, though, the menu item contains a prefix and/or a suffix. These components are separated by a tab character (represented by ⇢ in the examples on this page).

    prefix⇢title⇢suffix

The prefix controls whether or not the menu item is enabled, and whether or not the item is checked. The suffix controls the font, text size, style (italic, bold), color, indentation, key equivalent, action to perform, etc. The rest of this page will describe these suffixes and prefixes.

The prefix is optional, however, it’s a good idea to include it so that you don’t have to worry about special characters messing with your menu item title. For example, you might think that this line would create a menu item with a phone number:

    (800) 555-1212

However, since a leading `(` automatically disables the menu item (see below), this actually creates a disabled menu item of `800) 555-1212`. To fix this, add a tab character (empty prefix) at the front.

    ⇢(800) 555-1212

Adding a prefix to all menu items is a good habit to get into, whether you intend to use a prefix option or not.

#### Menu Action

Each menu item must be include a specification of what action to take if the user selects this menu item. You can either specify one or more procedure statements, or you can specify an objective-C method that is in the responder chain. If you don’t know what the responder chain is, you’ll probably want to stick with procedure statements, which work by wrapping the code with curly braces { and } and sticking the whole thing into the menu item suffix. (Note: the code you enter between the { and } characters must not contain any carriage returns, it all has to be on one line.)

In this example, when the user selects the Hello menu item, a dialog with a “Hello World” greeting will appear.

    ⇢Hello⇢{message |Hello World|}

Oh wait - you’re an Objective-C programmer and you want to know about using methods in the responder chain? It’s simple really, simply enclose the method name in square brackets, like this:

    ⇢Print Setup...⇢[runPageSetup:]

To find out what methods are available, look at the LMSL output of functions like standardfilemenu(, standardeditmenu(, etc.

Default Menu Action

If a menu item does not have a menu action or code assigned to it, it will be assigned a default menu action. If the menu is installed in the main menu bar (at the top of the screen), the default action is to call the .CustomMenu procedure in the current database. The info(“trigger”) function can be used to find out the menu name and item name, for example `Menu.Orders.New Invoice`.

If the menu is a context menu (right click) with no code assigned to it the .CustomMenu procedure is also invoked, however there is no menu name. So the result returned by info(“trigger”) will be something like `Menu..Do Something`.

If the menu is associated with a pop-up menu button, the default action is to invoke the code associated with the button. If the menu is associated with a popup statement, the default action is to resume the procedure after the popup statement.

#### Disabling a Menu Item

To disable any menu item, insert a `(` as the very first character of the line. For example, if the current invoice doesn’t contain a valid credit card, you might want to disable the option for charging the card.

    (⇢Charge Credit Card

If the menu item action is an Objective-C method in the responder chain, it will automatically disable itself if appropriate, even if you don’t include a `(` at the start. For example, a menu item that uses the `[copy:]` method will automatically disable itself if there is nothing to copy.

#### Menu Separator Item

To include a separator item in a menu, simply make a menu item of `(-`, as shown below:

    Red
    Green
    Blue
    (-
    Small
    Medium
    Large

#### Menu Key Equivalents

To add a menu key equivalent to a menu item, add `/` followed by the key to the menu item suffix. This example assigns the command key equivalent Command-B to the Open Book menu item.

    ⇢Open Book⇢/B

You can add one or more modifier keys to the command key equivalent:

    ⇧ SHIFT
    ⌃ CONTROL
    ⌥ OPTION.

This example assigns the command key equivalent Command-Shift-Option-P to the Print Invoice menu item.

    ⇢Print Invoice⇢/⇧⌥P

Note: The best way to type these special characters is to copy them from this page and paste them into your code. (Or even better, use the menuitem( function to generate the LMSL for you.)

    menuitem("Print Invoice","KEY","SHIFT-OPTION-P")

#### Alternate Menu Items

If the menu contains adjacent menu items that use the same command key equivalent with different modifier keys, you can specify that all but the first of these adjacent items are alternate menu items. Panorama will only display one of these menu items at a time – the others will be hidden until you press the appropriate modifier key. To specify that a menu is an alternate include the `&` character in front of the command key equivalent.

This example adds two alternate items to the menu. Normally when you click the menu, the Print menu item will appear. However, if you hold down the Option key, the Print menu item will change into “Print One Record”. (You can actually press and release the option key while holding down the mouse and see the menu change immediately.)

    ⇢Print⇢/P
    ⇢Print One Record⇢&/⌥P

Alternate menu items will only work if they are adjacent, and if all of them have the same key equivalent (in this case the letter `P`). If these conditions are not satisfied the menu items will not operate as alternates even if you include the `&` character.

#### Submenus

LMSL has the ability to specify that an entire menu is a submenu of another menu item. In fact, menus can be nested, 2, 3, or more levels deep.

A menu must be defined before it can be used as a submenu. To define a menu as a submenu, use a suffix of `*S` after the menu name (don’t forget the tab character to separate the menu name from the suffix). This tells Panorama to define the menu, but not to include the menu in the main menu bar.

    (Shippers)⇢*S
    ⇢Airborne
    ⇢Fedex
    ⇢US Postal Service
    ⇢UPS

Later in the menu definition you can attach this menu as a submenu to another menu item by including the menu name in parentheses in the suffix:

    ⇢Ship Via⇢(Shippers)

That’s all there is to it. When the menu is pulled down, Shippers will automatically appear as a submenu to the Ship Via menu item.

#### Menu Item Styles (Bold & Italic)

To specify that a menu item be bold or italic, add `<B` or `<I` to the suffix (or both):

    ⇢Bold Action⇢<B
    ⇢Slip Sideways⇢<I
    ⇢Super Important⇢<I<B

#### Menu Item Color

To specify a menu item color, insert `#` followed by a 6 digit hex representation of the color. This is identical to the way that colors are represented in HTML code.

This example displays the Launch menu item in green, the Abort menu item in red.

    ⇢Launch⇢#00FF00
    ⇢Abort⇢#FF0000

The `#` menu suffix can also be used in a menu definition. This changes the color of the entire menu (unless overridden for individual items). In this example all of the oceans listed in the menu will be blue.

    (Oceans)⇢#0000FF
    ⇢Pacific
    ⇢Atlantic
    ⇢Indian

#### Menu Item Font & Size

To specify a custom font and size for a menu item, insert `@` into the menu item suffix, followed by the name of the font, a colon, the size, and finally the semicolon (`;`) character.

    ⇢School⇢@Chalkduster:15;
    ⇢Wedding⇢@Snell Roundhand:24;
    ⇢Work⇢@Gill Sans:14;

If you want to use the standard font with a different size, you can leave the font name off.

    ⇢Big⇢@18;
    ⇢Biggest⇢@24;
    ⇢Huge⇢@36;

Or, you can specify only the font, using the standard size:

    ⇢Comments⇢@Noteworthy Light;

The `@` menu suffix can also be used in a menu definition. This changes the font of the entire menu (unless overridden for individual items). In this example all of the oceans listed in the menu will displayed using 18 point Optima ExtraBlack (and will also be blue).

    (Oceans)⇢#0000FF@Optima ExtraBlack:18;
    ⇢Pacific
    ⇢Atlantic
    ⇢Indian

#### Menu Item Indentation

To indent a menu item, insert `+` into the menu item suffix, followed by a digit from 1 to 9. The larger the number, the larger the indent.

    (Offices)
    ⇢California
    ⇢Los Angeles+1
    ⇢Downtown+2
    ⇢LAX+2
    ⇢San Francisco+1
    ⇢Sacramento+1
    ⇢Arizona
    ⇢Phoenix+1
    ⇢Tuscon+1
    ⇢Flagstaff+1

#### Menu Item Images

An image can be inserted at the left of a menu item by putting the image name in the menu item suffix between ɛ and ɜ characters (the best way to create these characters is to copy them from this page and paste them into your text.) This example displays a red circle with an exclamation mark next to the menu item, you might want to do this if the credit card number was invalid or missing (see cardvalidate().

    ⇢Charge Credit Card⇢ɛRedBangCircle14pxɜ

At this time, only images that are contained within Panorama itself can be displayed in a menu, you cannot supply your own images.

#### Menu Item State

If the first character of the menu item is √ or - the menu will be marked. In this example the Green menu item will be checked.

    ⇢Red
    √⇢Green
    ⇢Blue

In the example above the mark character was placed in the menu item prefix, which is the best practice. However, you can leave off the prefix and include the mark in the menu title, like this:

    Red
    √Green
    Blue

Panorama will automatically extract the checkmark from the Green menu item name.

#### Menu Item Identifier

To give a menu item an identifier, insert the identifier, surrounded by `$` and `ɜ` characters, into the menu item suffix.

    ⇢Red⇢$redColorɜ{call setColor}

The identifier does not change the appearance or operation of the menu item in any way, however, the procedure triggered by this menu item can use the info(“menuidentifier”) function to find out what the identifier is. This allows you to create procedures that don’t depend on the actual menu title. For example, you could translate the menu title into French or Spanish without breaking your menu procedure programming.

    ⇢Rouge⇢$redColorɜ{call setColor}
    ⇢Rojo⇢$redColorɜ{call setColor}

#### Combining Multiple Menu Options

Most of the examples above have shown menu item options used one at a time, but you can combine multiple options simply by concatenating them together.

    ⇢Void Invoice⇢{call VoidInvoice}#FF0000<B/⇧⌥V

This menu item has four options:

- call subroutine VoidInvoice if this menu item is chosen
- display menu title using red text
- display menu title in bold
- menu item has a command key equivalent of Command-Shift-Option-V

See Also

- Action Menu -- simple way to create your own menu items.
- arraymenuitems( -- converts a carriage return delimited array into a series of menu items.
- checkedarraymenuitems( -- converts a carriage return delimited array into a series of menu items, some of which may be checked.
- checkedmenuitem( -- creates a single menu item with an optional checkmark.
- Construct Menu -- used to automatically construct complex form applications, including calendars, lists, mailing labels, and more.
- Edit Menu -- edit text and data, to search (and replace), and to undo and recent actions.
- Field Menu -- manages fields, including adding and removing fields, setting field properties, sorting, morphing, hiding and showing.
- File Menu -- create, locate, open, close and save databases, import and export text, printing.
- filemenubar -- creates a custom menu bar or context menu for the current database (see Custom Menus).
- globalmenubar -- creates a custom menu bar or context menu for all windows (intended only for internal use by ProVUE Development).
- Help Menu -- contains items that will help you learn and use Panorama.
- info("menuidentifier") -- returns the identifier of the most recently chosen menu item (if any).
- Mark Menu -- allows you to set bookmarks in source code to help navigate to specific spots in a long program.
- menu( -- creates a menu (see Custom Menus).
- menuitem( -- creates a single menu item (see Custom Menus).
- menuitems( -- converts a semicolon separated array into a live menu specification.
- Menus -- overview of Panorama X menu bars.
- menuseparator( -- generates a menu item separator
- noactionmenu( -- suppresses the *Action* menu.
- noinstrumentationmenu( -- supresses the *Instrumentation* menu.
- nowizardmenu( -- suppresses the *Wizards* menu.
- Objects Menu -- used to select, modify and arrange graphics objects in a form.
- Panorama Menu -- get and set information about Panorama itself, including the version number, licensing information, and memory usage.
- popupatmouse -- displays a pop-up menu at the current mouse location.
- popupbelowbutton -- displays a pop-up menu in response to clicking on a button.
- popupclick -- displays a pop-up menu at the current mouse location.
- popupdoublefieldchoices -- displays a pop-up menu listing values in a specified field, with submenus containing values from a second field.
- popupfieldchoices -- displays a pop-up menu listing values in a specified field.
- Program Menu -- assists with running and debugging code, and with developing custom dialogs.
- Records Menu -- add and remove database records.
- Search Menu -- is used search for data, to select records, and to find and replace text within the current field.
- Source Menu -- used to assist in editing program code.
- standardactionmenu( -- generates a Custom Menu specification for Panorama's standard Action menu.
- standardclassicsetupmenu( -- generates a customizable Custom Menu specification for Panorama's classic Setup menu.
- standardconstructgraphicsmenu( -- generates a Custom Menu specification for Panorama’s standard Construct menu (in Graphics Mode).
- standardeditmenu( -- generates a customizable Custom Menu specification for Panorama's standard Edit menu.
- standardfieldsmenu( -- generates a customizable Custom Menu specification for Panorama's standard Fields menu.
- standardfilemenu( -- generates a customizable Custom Menu specification for Panorama's standard File menu.
- standardhelpmenu( -- generates a customizable Custom Menu specification for Panorama's standard Help menu.
- standardinstrumentationmenu( -- generates a Custom Menu specification for Panorama’s standard Instrumentation menu.
- standardpanoramamenu( -- generates a Custom Menu specification for Panorama's standard Panorama menu.
- standardrecordsmenu( -- generates a customizable Custom Menu specification for Panorama's standard Records menu.
- standardsearchmenu( -- generates a customizable Custom Menu specification for Panorama's standard Search menu.
- standardsetupmenu( -- generates a customizable Custom Menu specification for Panorama's standard Setup menu.
- standardsortmenu( -- generates a customizable Custom Menu specification for Panorama's standard Sort menu.
- standardtextmenu( -- generates a customizable Custom Menu specification for Panorama's standard Text menu.
- standardviewmenu( -- generates a Custom Menu specification for Panorama's standard View menu.
- standardwindowmenu( -- generates a customizable Custom Menu specification for Panorama's standard Window menu.
- submenu( -- creates a submenu (see Custom Menus).
- Window Menu -- controls the back to front arrangement of windows, it allows you to hide, show, or customize the toolbar (see Toolbar, and allows you minimize or zoom the window to full screen.
- windowmenubar -- creates a custom menu bar or context menu for the current window (see Custom Menus).

History

Version | Status | Notes
10.0 | Updated | Carried over from Panorama 6.0, but with many new features, including modifier masks on menu key equivalents, alternate menu items, menu actions, menu item color, font and text size, indentation, images, and menu item identifiers.