Adams Basic Package > Adams View > Adams View > Customizing Adams View > Authoring Plugins > Section 4: Ribbon customization for plugins

Section 4: Ribbon customization for plugins

User-created plugins for Adams View support Ribbon customization. Ribbon customization information for a plugin is stored in the <basename>_plg.xml file associated with the plugin.

Adams View searches for the plugin files (.xml, .bin, .xpm and so on) in the standard plugin search order, as seen below:

1. Current working directory

2. MDI_USER_PLUGIN_DIR environment variable (recommended)

3. System path (that is, $PATH, %PATH%)

4. Installation path of Adams

5. Library path (that is, $SHLIB_PATH, LD_LIBRARY_PATH)

Example plugin xml file, containing Ribbon customization: <basename>_plg.xml

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

<kernel:Bibliography>

</kernel:Bibliography>

<Name>myown</Name>

<![CDATA[Allows you to perform myown analyses and <br>

postprocessing on linearized Adams models]]>

</Description>

<Author>MSC Software</Author>

<Type>Public</Type>

</Plugin>

<ribbon> 

<Tab Name="Plugins" Help=""> 

<Group Name="MyGroup1" > 

<Button Name=" Group1_b1" row="0" col="0"> 

<tip_text>Load my user Plugin</tip_text> 

<icon_name> C:\my_user\ribbon_myplugin.xpm</icon_name> 

<single_click_commands> 

plugin load plugin_name = myown 

</single_click_commands> 

</Button> 

<Button Name="Group1_b2" row="1" col="0"> 

<tip_text>Load some functionality</tip_text> 

<icon_name> ribbon_button2.xpm</icon_name> 

</Button> 

</Group> 

<Group Name="MyGroup2" numRows="2"> 

<Button Name="Group2_b1" row="0" > 

<tip_text>Load functionality 2</tip_text> 

<icon_name> ribbon_grp2_btn1.xpm</icon_name> 

<single_click_commands> 

…

</single_click_commands> 

</Button> 

<Button Name="Group2_b2"> 

<tip_text>Load Functionality 3</tip_text> 

<icon_name> ribbon_grp2_btn2.xpm</icon_name> 

</Button> 

</Group> 

</Tab> 

</ribbon> 

</MSCPlugin>

The text in blue in the above example describes Ribbon customization added to a standard plugin <basename>_plg.xml file. You must use 24×24-pixel X Bitmap (.xpm) files for the icons on the plugin. These image files should exist in the location defined by MDI_USER_PLUGIN_DIR or in the standard plugin search order which is described above. Syntax errors in the .xml file and missing icon files will not produce errors, but the icons will be missing in the ribbon.

Steps for Running Example

To add ribbon elements to an existing plugin named supertools, do the following:

1	Copy any existing plugin files (supertools_plg.xml, supertools.bin, others) and all new icon files (.xpm) to a "plugin directory" of your choice. Now set the environment variable MDI_USER_PLUGIN_DIR with this path (for example, "C:\Plugins").
2	The existing .xml file, supertools_plg.xml, residing in the 'plugin directory', should have the following <ribbon> element appended to it as below: <ribbon> <Tab Name="Plugins" Help=""> <Group Name="SuperTools"> <Button Name="Load Super Tools" row="0" col="0"> <tip_text>Load my Super Tools Plugin</tip_text> <icon_name>lightings.xpm</icon_name> <single_click_commands> if cond=(!DB_EXISTS(".mdi.plugins.supertools")) plugin load plugin_name = supertools else interface menu display menu_name= .gui.main.ribbon_plugin.supertools end </single_click_commands> </Button> </Group> </Tab> </ribbon>
3	The .xpm file must exist in the same folder as the 'plugin directory' or in the current Adams View working directory.
4	The plugin binary file (supertools.bin in this example) typically contains load and unload macros (see Section 1: The basic plugin). A typical role of the load macro is to create custom menus for this plugin. In the 'classic' Adams View interface the load macro would put new menus on the existing menu structure. In the modern (ribbon) interface of Adams View there exists a new container element named: .gui.main.ribbon_plugin You can add menu items, using the load macro, under .gui.main.ribbon_plugin and display this menu when a button is clicked on the ribbon. For example, the load macro for 'supertools' might contain these commands to create a menu and a button: interface menu create menu_name = .gui.main.ribbon_plugin.supertools label = "Super" interface push_button create push_button_name = .gui.main.ribbon_plugin.supertools.butt_1 label = "Push Me" commands = " view zoom auto_zoom = on" Now when the ribbon button is clicked (refer xml section), the Adams View menu named .gui.main.ribbon_plugin.supertools is displayed.
5	Rebuild (see Creating Partial Binary (.bin) Files) the plugin partial binary (supertools.bin in this example) if necessary. Ensure that the partial binary exists in the MDI_USER_PLUGIN_DIR location.
6	Ensure that MDI_USER_PLUGIN_DIR is set properly, then open Adams View.
7	The plugins tab should display a new icon for the plugin. A first click on the icon loads the plugin, subsequent clicks display the menu for the plugin.