Customising Tabbed Menus in Model

PML Customisation User Guide

PML functions in AVEVA E3D™ Model can be customised in the following ways:

•

Replace a standard product function invoked by a callback from a tabbed menu button or other tool with a customised version of that function

•

Remove a standard product function

•

Add a new function to a tab

•

Add a new tab containing buttons for user functions

•

Add a new add-in application (See PML add-ins section)

This section describes the processes to follow to customise a tabbed menu. Details on how to use the customisation tool can be found in the .NET Customisation User Guide. Detailed description of PML commands can be found in the PML Command Objects section and in the Software Customisation Reference Manual.

Replacing Standard Product Functions

Product functions written in PML can be replaced by simply changing the callback in a PML Command object. A PMLLIB search path (See Storing and Loading PML Files) can be used to override a standard product PML Command object with a user customised function.

A typical scenario may be to add some validation that is company or project specific to a menu button call, or to replace a standard product function by a company or project specific function.

The first step towards replacing a PML Command object is to find the name of the command object that is linked to the button to be customised. This can be done by using the Customisation tool to find the key linked to the button, and then search for the PML command that has that key. Alternatively PML tracing functions can be used to find out which command is executed when a button is clicked.

The next step is to take a copy of the command object and add it to a directory in the PMLLIB path.

Then modify PML code in the execute method which is the callback executed when the button is clicked.

If the command being modified has a refresh method then it has some context sensitive behaviour. It may initialise itself in some way when the module starts, or it may react to a context message, CE change or other events. It may be necessary to modify code in the refresh method if one has been implemented. The most common use of a refresh method is activation or deactivation a gadget, or to control the visibility of a gadget according to some criteria (e.g. user in a particular team or availability of a given resource such as a particular file). Another common use of refresh methods is to initialise the value of state buttons, combo boxes and other gadgets that have a value property.

Note:

If a button is defined on a tabbed menu by using a direct call to a PML macro, and not using a command object then the recommended way to customise the callback is to replace the function that is called with a customised function. The only way to customise the callback itself is to take a copy of the UIC file containing the button, add it to a UIC path and replace the callback.

Note:

If the command key referenced by a button cannot be found in the PML commands, then it is probably a command implemented in the core product.

Removing a Standard Product Function

There are various ways of removing a function from the product depending on the end users objective for removing it. The options are:

•

Leave the button visible and active, and replace the command object as described above with one that outputs a message to say that the function is not available.

•

Make the button visible but inactive

•

Make the button invisible

•

Remove button from the UIC file

To make the button visible but inactive the enabled method on a command object can be used, for example !!aCommand.enabled(false). This can be called at any time after a command is loaded and registered.

To make the button invisible the visible method on a command object can be used, for example !!aCommand.visible(false). This can be called at any time after a command is loaded and registered.

Another way to make a button invisible is to remove it from the UIC file by using the customisation tool. A button can be removed from all groups where it is shown, and the definition of the button can be removed. This requires a UIC path to be defined (refer to .NET Customisation User Guide), and a copy made of any UIC files defining groups containing the button. This is not a recommended way of working unless there is a requirement to prevent users from reactivating the button by using visible and enabled command methods.

Add a New Function to a Tabbed Menu

It is advisable to keep customisations separate from the standard product if possible. This minimises the amount of rework that is necessary when a new version of AVEVA E3D™ is released. Adding company or project specific functions to new tabs avoids the need to keep customised UIC files in step with standard product UIC files.

Details on UIC files and using the Customization tool can be found in the .NET Customisation User Guide.

Adding a New Tab

A new tab can be added to interface by creating a new directory to contain customisation files and reference this directory in a UIC path (CAF_UIC_PATH). Copy the file DesignCustomization.xml from the AVEVA E3D™ product directory to this directory. In this directory create a new empty UIC file and add it to the end of the list of UIC files declared in DesignCustomization.xml. Take care to provide a unique namespace for the new UIC file.

Restart AVEVA E3D™ and the UIC file will be available in the Active Customization File list at the top left corner of the customization tool.

Select the new UIC file and navigate to Ribbon > Tabs in the navigation panel. Right click on Tabs and select New Tab to create a new tab in the UIC file. Click on the new tab and fill in the tab properties in the Property Grid.

Add a group to the new tab by right clicking on the tab and selecting New Group. Set the group properties in the Property Grid.

Click OK on the customization tool to save changes to the UIC file.

The tab is now ready to have a new button added to it.

Adding a New PML Command

PML command objects are described in section PML Command Objects. Create a new PML Command object and add it to a directory in the PMLLIB path. Choose a unique command key for the new command object. The new command object must be added to the PML index before it can be used in AVEVA E3D™.

The new command must be loaded and registered before it can be accessed from a button tool on a tab. This should be done when the module starts. A PML function !!loadUserCommands() is called when the module starts. This file can be customised to load new commands. Alternatively, new commands can be loaded in a PML add-in (described in the PML Add-ins section).

Adding a New Button

Buttons and other command tools are described in the .NET Customisation User Guide. Start the system with the new command object loaded and registered. Create a button using the customisation tool. Link the button to the command by setting the button command property to the key for that command. The key will be listed on the command browser if the command has been loaded and registered.

The caption, tooltip and icon are set in the button properties.

Add the button to the new group by dragging and dropping the button onto the group. Set the properties of the button in that group by right-clicking on the instance of the button under the group (e.g. with or without caption, small or large ICON). Similarly, a button can be added to a menu by dragging it onto a menu tool in a group.

Once the button and the command are linked the button will appear and clicking on the button will call the execute method in the command object.

Note:

A button can make a direct call to a PML macro if required, although this has some limitations. If the tool being added is a state button (toggle) or a combo box then a command must be used to initialise the tool and get the current value of the tool.

Note:

A command can be passed a string argument from the UIC file. This allows a parameterised command to be shared by several functions. This is particularly useful for a collection of related functions that have different callbacks but all share a common context where they are activated or deactivated by the same condition. Arguments are set in the button Arguments property.

Adding a Button to a Standard Product Tab

If it is necessary to add a new button to a group or menu on an existing tab then the DesignCustomization.xml file and the UIC file must be copied to the UIC path directory. Commands and buttons are defined for the new functions. To add the buttons to an existing tab, open the customisation tool and select the UIC file containing the tab. Open the tab and its groups and menus. Drag and drop the new buttons onto the groups and menus.

Note:

When a new version of the product is installed, the content of the modified tab may have changed, so it will be necessary to repeat this process for each new version of the customised UIC file.

Controlling the Visibility of Custom Tabs

If there is a requirement for new tabs to be visible to only to particular users, for example, only when working on a given project, or only when you are in a given team, this can be done by creating a command object and linking it to the tab using the tab Command property. Once a command object is linked to a tab, its visibility can be controlled directly from another piece of code either by calling its visible method, or by implementing a refresh method on the tab command object and using the refresh event and refresh filters to listen for the INITIALISED event. The refresh method performs the test to determine the visible state of the tab and sets the visibility of the tab by using the command visible method.

Tab visibility can be changed at any time according to a context. For example, if a tab should only appear when a given state button is checked, then the command linked to that button can either control the visibility of the tab directly by calling its visible method, or use the !!CMSYS setApplicationContext method to send a message to the refresh method of the tab command.