NCLaunch User Guide

3

Customizing NCLaunch with Plug-Ins

This section describes how to add plug-ins to your NCLaunch window. This allows you to add customized buttons to the tool bar.

Creating Plug-Ins

A plug-in should reside in its own directory, either in your home directory in

.nclaunch/plug-ins, or <CDS_INST_DIR>/share/cdssetup/nclaunch/plugins.

The directory for a plug-in must contain at least a file named plugIndex. This file defines the plug-in’s name, version, and an initialization procedure.

plugIndex File

The plugIndex file contains basic information about a plug-in.

The plugIndex file must define the plug-in’s name, version number, and initialization script. In addition, the plugIndex file can optionally specify a short description of the plug-in, and the author and contact information for a plug-in.

The plugIndex file can contain the following entries:

author author

Defines the person or company who produced this plug-in.

contact contact

Defines a way for the users of a plug-in to contact its author or distributor. This information is shown if there is a problem with the plug-in.

description description (optional)

Defines a short description of the plug-in. This is often presented to the user as an aid in determining if they would like to use the plug-in in the main application.

NCLaunch User Guide

Customizing NCLaunch with Plug-Ins

name name (required)

Define the name of a plug-in. Many applications will expose this name to the user, so it should be short and descriptive.

script script (required)

Defines a command to be invoked when a plug-in is started. This script can contain any valid Tcl commands. Usually, the script will simply source another file or load a C library.

version version (required)

Define the version of a plug-in. It is possible to define multiple versions of a plug-in with the same name. The application can choose to use a plug-in based on its version or ask for the latest version available. Versions should be in the form major.minor.sub, for example, “2.3.4”. Larger numbers correspond to later versions of a plug-in, and missing fields are equivalent to zeroes: version 1.3 is the same as version 1.3.0 and 1.3.0.0.

The Initialization Script

The initialization script is invoked every time a plug-in is started. It is possible for NCLaunch to initialize and shut down a plug-in multiple times. The plug-in operates in its own Tcl interpreter and communicates with the application through a set of defined programming interfaces.

The purpose of the initialization script is two-fold. The first is to load any Tcl packages, or libraries that will be used later by the plug-in; the second is to lay the groundwork for the interaction between a plug-in and NCLaunch.

Plug-in Variables

A subset of Tcl commands considered “safe” is allowed in the plugIndex file and is available to the plug-in. In general, safe Tcl commands do not load libraries or have access to the file system. However, for convenience, Tcl’s file command is accessible in the plugIndex file. See the Tcl documentation about safe interpreters for more detailed information. The following variables are defined in the context of the plugIndex file:

■dir — The directory where the plugIndex file resides.

■ncl_appname — The name of the application. In this case, “NCLaunch”.

■ncl_version — The version number of NCLaunch. For example, “3.20”.

■ncl_patchLevel — The minor version number of NCLaunch. For example, “p1”.

NCLaunch User Guide

Customizing NCLaunch with Plug-Ins

Plug-in Commands

The following commands are available for use in the plug-in initialization script:

addlistener event script

Registers the script to be invoked whenever event occurs. Valid events are refresh, select, and shutdown. More events may be defined in the future.

ncl_addpopuplistener script

Registers a script that is called whenever a pop-up menu is about to be posted in the main application. The command ncl_addtopopop is appended to the script. Because the script modifies the pop-up, the command can not be reproduced with addlistener.

ncl_addselectlistener script

Registers a script that is called whenever selection changes in the main application. The script can have the following values substituted:

%n – name of object selected

%t – type of object selected

%s – type of selection made

The command, ncl_addselectlistener foo, is equivalent to addlistener select foo. However, ncl_addselectlistener [list foo %n %t %s] cannot be replicated with the addlistener command.

ncl_addtopopup subcommand arg ...

Adds entries to a pop-up menu which will be shown in NCLaunch. This command is only valid in the context of a script registered by ncl_registerpopup. Calling this command does not exist at any other time and will not work. The command has two forms:

ncl_addpopup separator adds a separator to the pop-up menu.

ncl_addpopup command-label-script adds an entry to the pop-up menu which invokes a script in the plug-ins interpreter.

ncl_docommand arg arg ...

Evaluates the concatenation of the arguments in the I/O region of NCLaunch.

NCLaunch User Guide

Customizing NCLaunch with Plug-Ins

ncl_exit

Shuts down the plug-in. This does not exit the application.

ncl_fullsearch fileToFind

Returns all instances of fileToFind following the Cadence search rules. See setup.loc documention for more details. By convention, plug-ins should prefix any

filenames with “nclaunch/”.

For example, ncl_fullsearch nclaunch/mydatafile.

ncl_loadtk

Provides a convenience routine for loading Tk into a plug-in and initializing colors and bindings. This should be used instead of load {} Tk.

ncl_mainmenu label

Adds a menu to NCLaunchs main menu. This command returns a restricted menu command.

An error returns if the menu already exists. The label may be in the format: Plug-in &Menu, where & indicates that a request should be made to underline the following character. A restricted menu command is returned. The menu command allows for simple modifications to the menu created by ncl_mainmenu.

ncl_removepopuplistener script

Removes the script from the list of scripts that are invoked whenever a pop-up menu is about to be posted. The script should be exactly the same as the one that was added.

ncl_removeselectlistener script

Removes the script from the list of scripts that are invoked whenever a selection event occurs. The script should be exactly the same as the one that was added.

ncl_search fileToFind

Returns the first instance of fileToFind, following the Cadence search rules. Plug-ins should prefix any file names with “nclaunch/”.

For example, ncl_search nclaunch/mydatafile.

ncl_select name type selection

Notifies NCLaunch that a selection event occurred in the plug-in. The name of the selected object and its type are required. The selection event defaults to replace.