6.4 The papco_interface routines

These routines perform the actual interfacing to PaPCo. The consist of an input window for your plot data, and a series of small interfacing routines which are all called from PaPCo. The names for these routines are constructed internally in PaPCo, using your plot_type name plus the routine name: This is why it is so important to stick to the naming convention used.

All the templates for these interface routines reside in
papco_XX/PAPCO/papco_modules/plot_type/papco_interface.

   
6.4.1 Panel editor

The panel editor widget is a user supplied input widget for his module, and is used to pass parameters both to PaPCo and to the user's plot routine. The basic simple panel editor widget is supplied as a template in
papco_XX/papco_modules/plot_type/papco_interface/plot_type_panel.pro. This is a working panel editor.

6.4.1.1 Standard Panel Editor widget

This panel editor widget is shown in Figure 6.1. For a given data type not all the widgets included in this template must be used, you may add in all or leave out all the ones that PaPCo provides. For instance, the color bar widget makes no sense for a line plot!

  

Figure 6.1: Default panel editor widget

This widget provides some of the basic functionality of PaPCo. This is what each sub-window or button does:

Panel Height

: A slider to set the height of the panel in panel units. This is not an absolute measure, a height of 2 means double the size of all other panels, no matter how many panels there are.

User defined section

: At this point the user should set up his own widgets (buttons, sliders, text-entry etc.) to input the parameters needed for his plot. This is not shown here: Figure 6.1 shows the panel editor provided in the template only. The example here shows a slider that selects channel numbers.

Auxiliary file group

: This is a general sub-widget that is widely used in PaPCo (in the Write Paneldata slice (Section 6.5.5), the papco_event and papco_text Standard Modules (Chapter 7). The user can specify or browse for a text file, and then edit that file. Can be used for any auxiliary information needed for a given panel.

Color Bar group

: PaPCo provides the user with four color sub-tables which can be displayed at the same time. The lower three are user definable (see Section 5.4). Shown here are the currently loaded color sub-tables, and the buttons chose one of them for your plot.

Plot Style group

: Useful for line-plots only, normally deleted from color spectrogram panels. Allows the user to control line style and color of his plot.

Y-scale group

: Here, either automatic or manual y-scaling is set. For manual y-scaling the text entry fields become active and allow the user to enter lower and upper y-limits. Once the plot has been drawn, the automatic values are shown here.

Z-scale group

: Here, either automatic or manual z-scaling is set. For manual z-scaling the text entry fields become active and allow the user to enter lower and upper z-limits. Once the plot has been drawn, the automatic values are shown here. The z-scale is normally the color scale for a spectrogram.

The action buttons

: These are at the bottom of the panel, and change when the panel editor is used to edit an existing panel. The last two buttons are then replaced by update plot_type.

Help

: Calls the help file used to describe your module.

Config

: Calls up the module configuration widget. This is used to set environmental variables used by the module, e.g. data paths to your local site.

Cancel

: Closes the panel editor window and does nothing.

Add plot_type and continue

: Closes the panel editor window, adds the plot to the composer (right side of main PaPCo widget), and re-enters the panel editor where it left off (preserving all previous settings) and allows you to add a further panel with possibly another choice of parameters.

Add plot_type and close

: Adds the plot to the composer (right side of main PaPCo widget) and closes the panel editor window.

   
6.4.1.2 Panel Editor Config Widget

Each panel-editor can make use of the config functionality. The idea here is to be able to customize the module via environmental variables - to set up data paths and such like.

Each module should contain a file YOUR_MODULE/plot_read/defaults.config. The Panel Editor Config Widget first looks for a YOUR_MODULE.config file under your papco_user\papco_modules_defaults directory, and if it can't find one it read the defaults file from the module directory itself.

You can then change these defaults to adapt to your site, the result will then be written to your papco_user\papco_modules_defaults directory.

An example of the Panel Editor Config Widget (for the plot_type template module) is given in figure 6.2.

  

Figure 6.2: Module Configure widget

This is what this widget does:

Current Environmental Variables

: A list of the currently used environmental variables and what they are set to (usually data paths). Clicking on an entry causes the set value to appear in the ``set'' section for editing.

Set Environmental Variable section

: Here you may manually edit the setting of a chosen entry, or use the Browse button to search for a path. The Set button then sets the new value in the list above.

The action buttons

:

Done

: Sets the environmental variables as currently defined in the widget. Exists the widget.

Save

: Sets the environmental variables as currently defined in the widget, re-writes the user defaults file in papco_user/papco_module_defaults. Exits the widget.

Cancel

: Does nothing. Exits the widget.

Revert

: Re-reads the config file from the papco_user\papco_modules_defaults directory.

Default

: Re-reads the original defaults.config file supplied with the module in the module directory.

Help

: A description of this widget.

To enable or disable this feature you need to make a small change to the plot_type_panel.pro function as described in the next section.

6.4.1.3 What you need to do

To generate your own panel editor follow these steps:

1.

Rename all occurrences of plot_type in the file name and in the file to the actual name.

2.

Compile the file and test it (see below), you should see the default panel editor.

3.

You now need to add your own selection widgets (buttons, sliders, etc ). If you're not too sure about IDL widget programming, just re-use and edit some of the widgets in the panel editors of other modules. The way you pass information from the panel editor to your plot routine is through the panel editor structure ``PlotInfo''. The panel editor is called by PaPCo with this structure as parameter. You modify this structure and pass it back to PaPCo which passes it to your draw interface routine later (see below, Section 6.4.3). Some of the tags in this structure are used by PaPCo, some are for the user:
There are currently three user tags: typeVector, switch and options. The first two are there for historical reasons. We suggest that new modules are written using the options tag, which is a 20 element float array which should suffice for most uses.
These structures are the same for ALL modules. If you absolutely cannot get by with the tags provided in this structure and need more tags added, this can be done. Contact the author of this manual for more information on this.

4.

Testing: A useful thing to do is to test your panel before you proceed to see if all the input variable you set are also passed along. You can call up any of the panel editors in PaPCo (which are all functions) by passing it a default PLOTINFO structure:
a=papco_getPlotInfoStruct()
a=plot_type_panel(a)
Panel editors are passed a structure containing plot information, modify and/or add to this structure, and then pass it back. So by examining a (help,a,/struct) you can test if your widget works.

5.

Enable or disable the config functionality. By default it is enabled. In the file
papco_XX/papco_modules/plot_type/papco_interface/plot_type_panel.pro
find the line
widgets=papco_panel_AddActionButtons(panel_base, Action, aPlotInfo,/CONFIG)
The /CONFIG keyword enables the config button, setting this keyword to zero or deleting it disables the config button.

The testing of panels requires some built in functions of PaPCo, so you need to have started up IDL and initialized the package. The documentation in the template will lead you through what you need to do (Section B.1.1). Once your panel editor works and is tested, you can proceed to add it to PaPCo.

There are currently three such tags for the user: typeVector, switch and options. The first two are there for historical reasons. We suggest that new modules are written using the options tag, which is a 20 element float array which should suffice for most uses.

These structures are the same for ALL modules. If you absolutely cannot get by with the tags provided in this structure and need more tags added, this can be done. Contact the author of this manual for more information on this.

6.4.2 data_type_panel.help

This file is called by your panel editor's help button. In here you describe your data, your own widgets that you have added, and list the PaPCo functionality that your module supports. Use the template provided here (it is a simple text file, see Section B.1.4) and edit it.

   
6.4.3 PAPCOADD interface routines

Adding your panel editor to PaPCo is done through the file papcoadd_plot_type.pro, for which there is also a template. This file is the main interfacing file between modules and PaPCo, and contains all the routines that PaPCo needs to call specifically for your plot type. All these routines are short and simple. The main problems are encountered when the naming convention is not adhered to, since PaPCo uses the plot_type name you supply to construct all the calls to the procedures in this file. This is what you do:

1.

Rename all occurrences of plot_type in the file name and in the file to the actual name. Compile the file, there should be no errors, as long as your panel editor in step 1. is called plot_type_panel - otherwise there is a ``function not found'' error.

2.

Most changes which need to be made are taken care of by the global name change from plot_type to your actual name. But there are further user choices which need to be made: read through each procedure and follow the instructions in the comments.

3.

The last procedure in this file is the actual bit that does the work; here your data is read and the plot call is issued.

Your read and plot routines need not exist at this time for you to test if your module works with PaPCo. Assuming your papcoadd module compiles correctly:

1.

Add both files to the compile list in YOUR_MODULE_DIR\init_module.pro

2.

Exit IDL and start-up again (idl idl_startup_papco). This is required since you cannot add a module to a running session of IDL which had already run a session of PaPCo: adding a module expands some of the internal structures, and IDL does not allow you to do this dynamically.

3.

Make sure from the compile messages that the new module files are compiled.

4.

Now start up PaPCo. Your new module should be automatically recognized and the associated button placed with the other modules at the top left of the main widget.

5.

You should now have all the functionality of PaPCo available for your module (panel editor, compose window, etc.), but if you haven't got a working read or plot routine, don't try to draw anything, as PaPCo will crash.

Remember that you'll have to configure PaPCo to use your new module through the configuration widget (see Section 3.4). You'll need to exit idl for this as you cannot add a module to a running PaPCo setup.

Try out your module even if you can't plot data yet. In this way modules may be prepared ahead of time, maybe while someone else writes the read and plot routines. The documentation in the template will lead you through what you need to do (Section 6.4.3).