SysMenu AddItem

New to Analytica 6.5

This describes an esoteric and experimental built-in function, which means it is not officially supported and the specifics are subject to change in future releases.

Function SysMenu_AddItem( parentMenu, menuItem, position )

Adds a button to the main Analytica menu or toolbar. It is specific desktop Analytica, and is a no-op in ACP or ADE.

Parameters:

«parentMenu»
Specifies which menu the button should be added to. Must be one of
  • 'File'
  • 'Edit'
  • 'Object'
  • 'Definition'
  • 'Result'
  • 'Diagram'
  • 'Window'
  • 'Help'
  • 'Toolbar'
«menuItem»
This must be the identifier of a Button. When the user selects the menu item (or clicks the Toolbar button), it runs OnClick of this button. The button title displays as the menu text, and its Help attribute text or Description text is used for the tool tip. For a toolbar button, the button must have an image, ideally 32 pixels wide by 24 pixels high, displayed in the toolbar button.
«position» (optional)
Either a numeric position for the new item, or the text of the existing menu item immediately preceding the item being added. If omitted, it adds the option at the end of the menu. A value of 1 adds the item as the first item of the menu. When adding to a toolbar, it accepts only a numeric position.

The menu item is removed when the associated button is deleted. The menu text automatically adjusts to changes to the button's title.

How to use

This function exists so as to make it possible to create a library that adds functionality to the Analytica UI. This is something only the most advanced library creators should even consider.

To use, you would create a button (or buttons) in your library to process your new menu options(s). Write their OnClick expressions to perform the desired action. Then add yet another button to install these in the menus. Configure that button to run when the model is loaded (you can do that from the right-mouse context menu for the button). That way, when you library loads, it installs its menu items.

Because the menu item is removed from the menu when the button is deleted, your menu option will go away when the model is closed, or a new model loaded (which closes the model), since that deletes the button from memory.

For some types of functionality, your button may need to know what window was in focus and what objects were selected. This information is not directly provided to OnClick, but your library can track these using a Selection tracker. This can track object selections, but there isn't a way to get information about cell selections in a table.

It is also possible to use this to install menu items into desktop Analytica that are present when Analytica starts up, and are permanent. By permanent we mean that they persist even after closing a model. These must be defined from within either Analytica.ini or SysLibraries.ini. The key is to place your menu item buttons in a special system module named SysLib_Customizations. You can can then call SysMenu_AddItem directly from within the script.

Limitations

Here are some current limitations.

  • Your OnClick expression can't get information about which window is in focus or which objects are selected when the button is pressed. However, your library tocan track object selections and window focus separately using a Selection tracker.
  • Options in menus
    • You can't add a separator.
    • You can't remove an item except by deleting the corresponding button.
    • There is no mechanism to disable or hide an option, for example, in response to various context changes. (one exception: menu items disable while a calculation is in progress). For example, you can't enable your item only when the diagram is in focus, but disable it when the user is working in a different window type.
  • Toolbar buttons
    • A button must have an image (you can't add a purely textual button).
    • A toolbar image does not "gray out" or display an alternate image when a calculation is in-progress. However, it doesn't respond to clicks until the current calculation has completed.
    • The toolbar won't dynamically adopt a new button image when you change your button's image after the option has already been added.

Some of these may be addressed in future releases.

See also

Comments


You are not allowed to post comments.