Chapter 8. Extending Menu

Basic Concepts of Menu Extension

In order to provide ways for the user to call the Add-In functions, the StarUML™ menu system can be extended. For this, Add-In developers must provide menu extension files. This involves the following steps.

  1. Creating a menu extension file.
  2. Registering a menu extension file.

An Add-In menu extension file (*.mnu) is an XML-formatted text file. Each Add-In must provide one menu extension file. StarUML™ uses the definition contents of this menu file to extend the application's main and popup menus to add new menu items, to execute defined actions, or to send messages to related Add-In objects. StarUML™'s Add-In menu extension file can contain the following definitions.

A menu extension file is written in the XML format. It has to be a well-formed document and its contents must be valid. This chapter discusses the XML DTD (Document Type Definition), which has to be observed to ensure the validity of menu extension files, and the structure of menu extension files, and also provides related examples.

Note: Add-In menu extension file must have *.mnu extension file name and placed in the subdirectory of StarUML™ module directory(<insall-dir>\modules).

Creating Menu Extension File

DTD of Menu Extension File

StarUML™'s Add-In menu extension file must be a valid XML that conforms to the defined DTD. The following is the entire contents of the DTD defined for a menu extension file.

<?xml version="1.0" encoding="UTF-8"?>

<!ELEMENT NAME (#PCDATA)>
<!ELEMENT VERSION (#PCDATA)>
<!ELEMENT DESCRIPTION (#PCDATA)>
<!ELEMENT COMPANY (#PCDATA)>
<!ELEMENT COPYRIGHT (#PCDATA)>

<!ELEMENT MAINITEM (MAINITEM)*>
<!ATTLIST MAINITEM
          base (FILE|EDIT|FORMAT|MODEL|VIEW|TOOLS|HELP|UNITS|IMPORT|EXPORT|NEW_TOP) #IMPLIED
          caption CDATA #REQUIRED
          index CDATA #IMPLIED
          beginGroup CDATA #IMPLIED
          script CDATA #IMPLIED
          actionId CDATA #IMPLIED
          availableWhen (ALWAYS|PROJECT_OPENED|MODEL_SELECTED|VIEW_SELECTED|UNIT_SELECTED|DIAGRAM_ACTIVATED) ˇ°PROJECT_OPENEDˇ±
          iconFile CDATA #IMPLIED>

<!ELEMENT POPUPITEM (POPUPITEM)*>
<!ATTLIST POPUPITEM
          location (EXPLORER|DIAGRAM|BOTH) ˇ°BOTHˇ±
          caption CDATA #REQUIRED
          index CDATA #IMPLIED
          beginGroup CDATA #IMPLIED
          script CDATA #IMPLIED
          actionId CDATA #IMPLIED
          availableWhen (ALWAYS|PROJECT_OPENED|MODEL_SELECTED|VIEW_SELECTED|UNIT_SELECTED|DIAGRAM_ACTIVATED) ˇ°PROJECT_OPENEDˇ±
          iconFile CDATA #IMPLIED>

<!ELEMENT MAIMENU (MAINITEM)*>
<!ELEMENT POPUPMENU (POPUPITEM)*>

<!ELEMENT HEADER (NAME?, VERSION?, DESCRIPTION?, COMPANY?, COPYRIGHT?)>
<!ELEMENT BODY (MAINMENU?, POPUPMENU?)>

<!ELEMENT ADDINMENU (HEADER?, BODY)>
<!ATTLIST ADDINMENU addInID CDATA #REQUIRED>

Note: Names of all XML elements must be written in upper case letters, and names of all attributes start with lower case ones. Pre-defined symbol values are represented in upper case with '_' (underscores). Such conventions must be observed throughout the whole menu file, and the pre-defined symbol values must be used properly.

Overall Structure of Menu Extension File

Menu extension files follow the XML document conventions, and user-defined menu items are contained within the 'ADDINMENU' element.

<?xml version="1.0" encoding="..."?>

<ADDINMENU addInID="...">
  <HEADER>...</HEADER>
  <BODY>...</BODY>
</ADDINMENU>

Header Contents

The Header element of a menu extension file contains information for the Add-In and menu file. The contents in the Header section do not have any effect on the actual structure of the menu items. Although this section may be omitted, it is recommended to include it to provide menu extension files that are self-explanatory.

<HEADER>
  <NAME>...</NAME>
  <VERSION>...</VERSION>
  <DESCRIPTION>...</DESCRIPTION>
  <COMPANY>...</COMPANY>
  <COPYRIGHT>...</COPYRIGHT>
</HEADER>

BODY CONTENTS

The Body element of a menu extension file contains the actual menu items to add. Information in this section must be accurate.

<BODY>
  <MAINMENU>
    <MAINITEM>...</MAINITEM>
    <MAINITEM>...</MAINITEM>
  </MAINMENU>

  <POPUPMENU>
    <POPUPITEM>...</POPUPITEM>
    <POPUPITEM>...</POPUPITEM>
  </POPUPMENU>
</BODY>

The Body element can largely be divided into definitions of the main menu and definitions of the popup menu.

Main menu items and popup menu items are written separately. According to the functions provided by each Add-In, a menu item can be added to the main menu or to the popup menu. Either the MAINMENU element or the POPUPMENU element may be omitted, but not both. If a menu item of the same functionality needs to be added both to the main menu and to the popup menu, information should be entered appropriately in MAINMENU and POPUPMENU. In this case, the two items should have identical script or actionID properties. However, when adding a lower-level menu item to an StarUML™ basic menu item such as [Format] and [Unit], that is shared by both the main menu and the popup menu, the information should be contained in MAINMENU only.

MAINMENU

The MAINMENU element can contain multiple MAINITEM elements. Each MAINITEM element constitutes one main menu item. For defining a group menu item with sub menu items, the MAINITEM element can in turn contain multiple MAINITEM elements.

<MAINITEM base=ˇ±...ˇ± caption=ˇ±...ˇ± index=ˇ±...ˇ± beginGroup=ˇ±...ˇ± script=ˇ±...ˇ± actionId=ˇ±...ˇ± availableWhen=ˇ±...ˇ± iconFile=ˇ±...ˇ±>
  <MAINITEM>...</MAINITEM>
  <MAINITEM>...</MAINITEM>
</MAINITEM>
Property Description Range of Value Omission
base This is one of the StarUML™ basic menu items to which the new menu item will be added. This property has no effect if the MAINITEM element belongs to another upper-level MAINITEM element. Must be FILE, EDIT, FORMAT, MODEL, VIEW, TOOLS, HELP, UNITS, IMPORT, EXPORT, or NEW_TOP. * If omitted, the new menu item is added as a sub menu item under the [Tools] menu.
caption Specifies the display name for the menu item. This value may contain the hot-key. To define the hot-key, add '&amp;' and the hot-key character at the end of this value. Note that the StarUML™ program does not check for duplication of the hot-key with other menu items. String value Cannot be omitted.
index Specifies the order of this menu item under the upper-level menu. For instance, if this value is '0', the menu item becomes the first sub menu for the base menu item. If the value of this property conflicts with the values of other menu items, the menu may not be displayed accurately. An integer greater than 0. Generally omitted. If omitted, Add-Ins are added in the order they are registered.
beginGroup Determines whether to add the separator in front of the menu item. Must be TRUE or FALSE. FALSE if omitted.
script Specifies the pathname and filename of the script to run, if any. The pathname is relative to the location of the Add-In program. This value can also be a website URL. String value Can be omitted.
actionId Set this to an integer greater than 0 in order to process the menu command through a COM object. If the Add-In adds more than one menu item, each menu item can be distinguished by its unique actionId value. An integer greater than 0. Can be omitted.
availableWhen Specifies when the menu item becomes enabled. Must be ALWAYS, PROJECT_OPENED, MODEL_SELECTED, VIEW_SELECTED, UNIT_SELECTED, or DIAGRAM_ACTIVATED. ** PROJECT_OPENED is selected if omitted.
iconFile Specifies the pathname and filename for the menu item icon file, if any. The pathname is relative to the location of the Add-In program. String value Can be omitted.

Note: Unless the menu item groups its sub menu items, the property value for either script or actionId must be defined.

*  base property value range

**  availableWhen property value range

POPUPMENU

The POPUPMENU element can contain multiple POPUPITEM elements. Each POPUPITEM element constitutes one popup menu item. For defining a menu item with sub menu items, the POPUPITEM element can in turn contain multiple POPUPITEM items.

<POPUPITEM location=ˇ±...ˇ± caption=ˇ±...ˇ± index=ˇ±...ˇ± beginGroup=ˇ±...ˇ± script=ˇ±...ˇ± actionId=ˇ±...ˇ± availableWhen=ˇ±...ˇ± iconFile=ˇ±...ˇ±>
  <POPUPITEM>...</POPUPITEM>
  <POPUPITEM>...</POPUPITEM>
</POPUPITEM>
Property Description Range of Value Omission
location Specifies the popup menu system where the new popup menu item will be added. This property has no effect if the POPUPITEM belongs to another upper-level POPUPITEM element. Must be EXPLORER, DIAGRAM, or BOTH. * BOTH if omitted.
caption Specifies the display name for the menu item. This value may contain the hot-key. To define the hot-key, add '&amp;' and the hot-key character at the end of this value. Note that the StarUML™ program does not check for duplication of the hot-key with other menu items. String value Cannot be omitted.
index Specifies the order of this menu item under the upper-level menu. For instance, if this value is '0', the menu item becomes the first sub menu for the base menu item. If the value of this property conflicts with the values of other menu items, the menu may not be displayed accurately. An integer greater than 0. Generally omitted. If omitted, menu items are added in the order the Add-In is registered.
beginGroup Determines whether to add the separator in front of the menu item. Must be TRUE or FALSE. FALSE if omitted.
script Specifies the pathname and filename of the script to run, if any. The pathname is relative to the location of the Add-In program. This value can also be a website URL. String value Can be omitted.
actionId Set this to an integer greater than 0 in order to process the menu command through a COM object. If the Add-In adds more than one menu item, each menu item can be distinguished by its unique actionId value. An integer greater than 0. Can be omitted.
availableWhen Specifies when the menu item becomes enabled. Must be ALWAYS, PROJECT_OPENED, MODEL_SELECTED, VIEW_SELECTED, UNIT_SELECTED, or DIAGRAM_ACTIVATED ** Set to PROJECT_OPENED if omitted.
iconFile Specifies the pathname and filename for the menu item icon file, if any. The pathname is relative to the location of the Add-In program. String value Can be omitted.

Note: Unless the menu item is grouping its sub menu items, the property value for either script or actionId must be defined.

*  location property value range

**  availableWhen property value range - Same as the MAINMENU element.

Example of Menu Extension File

The following example is the complete menu file for the StarUML™ default extension pack that is installed together with the StarUML™ program.

<?xml version="1.0" encoding="UTF-8"?>

<ADDINMENU addInID="StarUML.StandardAddIn">
    <HEADER>
        <NAME>Default module of StarUML</NAME>
        <VERSION>1.0.0</VERSION>
        <DESCRIPTION>Default extension pack of Agora Plastic to convert diagram</DESCRIPTION>
        <COMPANY>Plastic Software, Inc.</COMPANY>
        <COPYRIGHT>Copyright (C) 2005 Plastic Software, Inc. All rights reserved.</COPYRIGHT>
    </HEADER>
    <BODY>
        <MAINMENU>
            <MAINITEM base="MODEL" caption="Convert Diagram" beginGroup="TRUE" availableWhen="MODEL_SELECTED">
            <MAINITEM caption="Convert Sequence(Role) to Collaboration(Role)" script="ConvSeq2Col.vbs"/>
            <MAINITEM caption="Convert Collaboration(Role) to Sequence(Role)" script="ConvCol2Seq.vbs"/>
        </MAINMENU>
    </BODY>
</ADDINMENU>

Registering Menu Extension File

To make a menu extension to be recognized automatically by StarUML, must place it in the subdirectory of StarUML module directory(<install-dir>\modules). StarUML searches and reads all menu extension files in the module directory and registers them at the program automatically when StarUML is initializing. If menu extension file is invalid or it's extension file name is not .mnu, StarUML will not read the menu extension file and ignore it. It is recommended that make a subdirectory in the StarUML module directory and place the profile in there to avoid modules being out of order.

Note: Delete the menu extension file from the StarUML module directory(<install-dir>\modules) not to use the menu extension any more.