Customising Tabbed Menus in Model

PML Customisation User Guide

PML Add-ins : Customising Tabbed Menus in Model

User defined add-ins can be used to add a new application, or to add controls for utility functions.

A user defined add-in application in a tabbed menu is added to the application selector in the quick access toolbar at the top left hand corner of the application window. Normally one or more new tabs are added for a new application (described in Customising Tabbed Menus in Model).

A user defined add-in for utility functions provides the ability to plug in initialisation code which is run when the module starts, or when you switch application. The Control object can be used as the controller and event handler for the add-in functions.

Careful use of add-ins can help to manage the case where there are several add-ins to a module, which may differ for different projects within the same organisation. This can cause problems if more than one add-in customises the same standard product files (for example, module and application initialisation files). Encapsulating the control and initialisation of add-ins in control objects can help to avoid these conflicts.

For both add-in applications and add-in utility functions the Control object is a convenient place to load and register command objects used by the add-in.

Add-in Applications

The application controller adds new add-in applications to the Application Selector in the quick access toolbar. When an add-in application is selected the system sends out a context change event that application tab command objects subscribe to. They use this event to show or hide the tab and to set focus on a tab if required.

The example below is taken from the tab command object used to control the equipment tab. An equipment tab is shown when the equipment, piping or HVAC applications are selected.

The refresh method responds to an application change context event, and sets tab visibility according to the content of the context message.

define method .refresh(!args is ARRAY)

-- check that this message is for Application tabs

!message = !args[2]

if( !message.subString(1,12) neq 'Application:' ) then

return

endif

!message = !message.after('Application:')

if (!message eq 'EQUI') then

-- Equipment Application selected - show tab and select it

!this.visible(true)

!this.select()

elseif (!message inset ('PIPE','HVACADV','HVAC')) then

-- Pipe or HVAC Application selected - show tab

!this.visible(true)

else

-- Equipment tab not required - Hide the tab

!this.visible(false)

endif

endmethod

We only want this refresh method to be called for CONTEXT events, so the command object constructor must set a context filter as follows:

define method .equipmentContextTab()

-- initialise events and command key

!this.key = 'AVEVA.Equipment.CommandContextTab'

!this.execute = 'execute'

!this.refresh = 'refresh'

  !filters      = object ARRAY()

  !filters[1]   = 'CONTEXT'

  !this.refreshFilters = !filters

endmethod

The execute method for the tab command object is empty.

The message sent by a user add-in application is the key word 'Application:' followed immediately by the name of the add-in application as defined in the Name: declaration.

The following add-in file is an example of an add-in with name MYADDIN. MYADDIN will appear in the Application Selector because the showOnMenu: declaration is set to true. You have supplied an object of type MYADDINCONTROL as the control object in myaddincontrol.pmlobj which implements methods moduleStartup() and startup().

Method moduleStartup() will be called when the module starts, and it could contain PML LOAD COMMAND statements and command registration for any new functions defined for this add-in.

Method startup() is called when the application is selected in the Application Selector. This method could contain code that initialises the application.

# Description: Add-in application definition

# ---------------------------------------------------------

name: MYADDIN

CONTROL: MYADDINCONTROL

title: MYADDIN

showOnMenu: TRUE

modulestartup: !!MYADDINCONTROL.moduleStartup()

startUp: !!MYADDINCONTROL.startup()

Load User Commands

In order to add a PML add-in to the system:

Create PMLLIB and PMLUI paths to contain the user customised files.

Put the PML command files in the PMLLIB path

Create a new PML addin control object in the PMLLIB path. In the module startup event callback, add the names of pml commands to be loaded and registered to an array and use PMLCOMMANDMANGER to load and register them.

Do a PML rehash before introducing the PML addin definition file.

Create a PML addin folder in the PMLUI path and create an addin definition file to that folder. Set the name of the control object in that file to match with the name of the PML addin control object.