PapcoDoc/documents/moduleDefinition
From PapcoWiki
Contents |
PaPCo module definition
In the rawest sense, a papco module is a set of IDL routines that provide data products or software for data processing in a named package. Typically, a papco module provides a graphical user interface to control science graphics.
Module names uniquely identify the module, and should contain only lower-case letters and underscores. (This is because the module name is used to name IDL procedures.) PaPCo contains a set of "core" modules that are distributed along with papco, but generally a module is a directory and subdirectories.
PaPCo module interface
To include a module, papco adds the module directories to the IDL search path, and then invokes the script init_module.pro, which should compile routines needed to implement the module.
The module can declare a set of panels provided by the module at the top of papcoadd_<moduleName>.pro When papco attaches gui controls to the module by calling addplottype_<moduleName>, parentBase, geometryDescriptor, result, which should return a button or cw_pdmenu.
PaPCo 12 Module routines
init_module.pro
- IDL script that compiles the module.
- Note this should not contain any calls to procedures.
- Module setup should be done in <module>_reset.pro
- (Legacy modules call routines, but for support of IDL runtime, use <module>_reset.pro
- This script is called when compiling papco runtime, so it must at least contain the names of routines generated from the module name. Codes these modules use will be compiled implicitly via IDL's resolve_routine.
papcoadd_<moduleName>.pro
- first few lines are parsed to calculate panel kinds:
;****************************************************************************** ;* file papcoadd_plot_type ;* papcoadd_plot_type ;* end ...
- describes module and the panels it contains. module "plot type" contains just one panel kind, also called "plot type."
- the procedure "addPlotType_<moduleName>" creates a widget (a button or pull-down list) that is used to create panels.
- the procedure "addPanel_<moduleName>" receives the event created by this widget, and handles the event. Typically this is to create and install a new panel.
<panelKind>_new_panel.pro
- function returning a plotInfo with the default settings for the module. This is optional, and will be used when loading in product files.
Main utility of this function is to make products upwards and downward compatible. As plotinfo is modified/extended, or the module's control structure is modified or extended, this routine provides a full valid state of the module; and only the subset of the module's information in the "old" product file will be use to overwrite this information.
<moduleName>_reset.pro
- reset method for resetting internal state
This function is somewhat module specific, depending on how much of the papco functionality it supports. Typically, this function does the following:
- resets the file cache - often this is done my calling the module's cache routine with the keyword /reset
- resets any data in the data cache for this module
- re-initialize the module's common blocks, if any are used
<panelKind>_revalidate.pro
- revalidates a plotInfo.
This makes sure that all the "related" setting that go with a state of a modules as defined by plotinfo are set. This is normally done when a module's panel editor is called - but a correct state is also needed when a product is loaded in for the first time. Typically, this routine will dop the following:
- Recalculates filename based on settings.
- Sets plotInfo.dataCache and dataset id strings.
<moduleName>_dependence.pro
- returns a string or string array of modules this module depends on.
- Empty strings are okay too as a convenience to the developer.
- Interdependence and circular dependence are okay, but if the dependence is one-directional, then the required module will be compiled first.
