WARNING! This section is ``definitely advanced'' PaPCo!
The user can add his/her own slice definitions to the ``Mouse Action'' menu. and thus extend the functionality of his/her module. The maximum total slice functions are 16, so given the 5 PaPCo slices the user can define up to 11 slices of his/her own.
In addition the user can define what action is taken in the draw window for his slice type. This is defined as being the ``show-selection''. In keeping with PaPCo tradition there is a choice between specifying PaPCo supplied show-selections or writing your own.
Adding a new slice type is done by setting an environmental variable in
papco_set_variables.pro in the user's
The format of this string is
etc., no spaces allowed, individual slice names separated by a backslash.
PaPCo uses this environmental variable to extend the ``Mouse Action'' menu, and to construct the calls to the user's slice routine. The calls have the format
user_new_slice_1_plot_type, panelNr, seconds, yValue, CLOSE=CLOSE
where the name of the routine is a string made up out of the new slice name and the name of the module of the panel that the mouse is clicked in; panelNr is the No. of the panel the mouse was clicked in, seconds and yValue are the x and y coordinates of the plot in data coordinates. The keyword CLOSE is set by PaPCo when a new slice type is chosen, it is up to the user to take action on this and make sure that his slice widgets are closed at that point.
Knowing the panelNr allows you to get access to the structure defining the panel that the mouse was clicked in. This is the same structure that was defined with the panel editor for that panel. PaPCo keeps an array of all these structures in it's own internal main structure, which is put into a common block so that it accessible to the rest of PaPCo and to the user:
COMMON PLOT_COMPOSER, widgetData
You can interrogate this structure using the
help, widgetData, /stru
command on the IDL command line. You can always get at the current state of
widgetData when in PaPCo: Press the STOP button on the main widget,
that get's you to the IDL command line.
.con then resumes PaPCo.
The tag name in
widgetData containing the array of all currently
defined panelplots is called
plotsDrawn. To get access to this in your
slice routine, you need to include the common block
returns you the plot info structure of the panel you clicked in.
Often a slice function that you write needs to get at the data plotted in the
panel you clicked, and this data might not always be available in a common
block - so you need to know how to re-read the data. It is for this reason
that you defined the sting
get_data_call in your
procedure in the PaPCo interface file
papcoadd_plot_type. This string
is also available in the structure:
If you set up your
get_data_call correctly in your PaPCo interface
routine, then it should contain exactly the call you used to obtain the data
that was plotted in the panel, so you can re-read the data by executing that
IF NOT EXECUTE(widgetData.plotsDrawn(panelNr).get_data_call) THEN BEGIN dummy=messageBox(['I cannot read the data for the panel'], ['Ok']) RETURN ENDIF
This little bit of code tries to execute your data call, and pops up a message widget if it was not successful.
NB. Please, if you have written a user slice for your data, include some documentation on that slice in your module's help file (Thats the one that gets called up when you hit the help button in the panel editor for that module). Also, if your slice is another widget, make sure it has a help button too that explains its use!
The show-selection here is defined as the action taken in the current draw window for a given Mouse Action. For ZOOM, the show selection is drawing a box, for SLICE it's drawing a vertical line etc. These show-selections are now also available for User defined slices.
PAPCO provides routines for several built-in show-selection types. These types are identified by the following names:
|"vert_line"||-||draws a vertical line over all panels at mouse click|
|"horiz_line"||-||draws a horizontal line through panel at mouse click|
|"hair_cursor"||-||draws a hair cursor made up of "vert_line" and "horiz_line"|
|"box"||-||draws an inverted box in the panel when dragging the mouse|
The PaPCo mouse actions use these show-selection types and are pre-configured in the following way (and cannot be changed):
|VIEW SLICE||uses vert_line|
|ACCESS LEVEL ZERO||uses vert_line|
|WRITE PANELDATA||uses vert_line|
|HAIR CURSOR||uses hair_cursor|
While the user was able to add in his/her own USER slice type by setting the
USER_MOUSE_ACTIONS, the show-selection had been
hard-wired to vertical line only. This is still the default action when
USER_SHOW_ACTIONS is not defined.
The user can now also define an environmental variable
USER_SHOW_ACTIONS to select the show-selection for his/her User Mouse
Action. This is done be setting
USER_SHOW_ACTIONS to the show-selection
type names chosen. If you have added 3 mouse actions of your own, then you
USER_MOUSE_ACTIONS = new_slice_1/new_slice_2/new_slice_3
To specify which show selection type each user mouse action should use, set
USER_SHOW_ACTIONS = show_1/show_2/show_3
The association between Mouse Action and Show Action is by order in these two
system variables. Replace
show_1 etc by valid show-selection names (see
All the routines that implement the show-selection share a common block, which is available to the user:
||2-element float||Contains the last x y values of where the mouse was last clicked.|
|If you drag the mouse, values are from when the mouse was last|
|released. Normal coordinates.|
||2-element float||Contains the previous last clicked coordinates. When mouse was dragged,|
|contains the start of the drag. Normal coordinates.|
||an integer||The panel Nr where the mouse was clicked. Useful for getting at that|
|panels' plotinfo structure. All the plotted panels have their plotinfo|
|structures (thats the same structure as returned by that modules panel|
|editor) stored in an array in the main papco common block|
||2-element float||Contains the current mouse coordinates independent of what was clicked.|
These data are in normal coordinates as PaPCo doesn't know or care about your actual coordinates used. For drawing show-selections, you don't need data coordinates anyway.
Given the information in the common block above the user can write his/her own show-selection routine.
For this routine to interface into PaPCo , it MUST adhere to a naming
convention. Look a the built-in show-selection routines in
You'll have to give your own show-selection type a name. Lets assume you've called it "my_box", then you will need to write a routine called:
pro papco_cursor_showselection_my_box, ERASE=ERASE, DRAW=DRAW COMMON PLOT_COMPOSER, widgetData COMMON MOUSE_SELECT,old,click,pnlNr,n_x,n_y ; put in here what your show-selection does! end
I.e., papco will look for a routine whose name is made out of ``papco_cursor_showselection_'' + your selection name.
The best place for this is in your modules slice routines. In that way it'll get compiled up at startup automatically.
You can the select your show-selection type by setting
accordingly, as explained in Section 1.
Note: To keep with PaPCo philosophy any show-selection you write should ONLY
use the info supplied in the common block
MOUSE_SELECT, and should do
everything in normal coordinates, so that other mouse actions may also use
it! As more show-selections get written we can also include them in PaPCo
core to make them available outside your module.
While normal coordinates are all that's needed for drawing show-selections, you might want more information for actually constructing a user slice. When you have configured PaPCo with your USER slice, papco calls your slice with three parameter: the panel Nr and the data values for the x and y positions of the click, seconds and yvalue.
``seconds'' will be in whatever format you've chosen for the time axis. There is a papco_cursor utility routine that converts that to a verbose description of the time:
If MJDT is set, the time gets returned in mjdt format.
If your show-selection is a box-style, enclosing an area of the panel, you'll
need to get hold of the box coordinates. An example of this can be found the
papco_Cursor_Rect routine in
papco_cursor.pro. But the
important code to use is the following:
papco_get_data_box, starttime, endtime, startData, endData
which is a papco_cursor routine that returns to you, in data coordinates, the x and y start/end points (corresponding to the time and data axes) of the area enclosed by your mouse drag in the current panel.
IDL supports a three-button mouse, which is available on most systems and can be emulated if needed (under W95 pressing both buttons on an MS Mouse can emulate the third button).
Up to now, all mouse actions where controlled by the left button, and this is still the default mode. Pressing the left button in a panel will call up the selected Mouse Action and perform it, if that action is enabled for that panel.
Support has now been added for the other two mouse button. The configuration is hard-wired, at present it is not planned to make the mouse buttons configurable (although this is the logical extension and in principle not difficult!)
This is what is currently implemented:
|-||default mouse action as defined by Mouse Action in PaPCo|
|middle button||-||calls hair_cursor mouse action|
|right button||-||calls zoom mouse function.|
Whenever the middle or left button is pressed, that function is called, keeping the default action active too. Going back to the left mouse button returns you to the default action and erases the hair_cursor / zoom windows.
As PaPCo cannot know in advance what user slices will be added, and the user cannot know how many other user slices might be used together with his/hers, there needs to be a mechanism to interrogate PaPCo which slice number was assigned to a given user slice.
The first 5 slice types are preset with values 1, 2, 4, 8 and 16. User slices
are assigned consecutively (in powers of two) in the order they appear in the
USER_MOUSE_ACTIONS environmental variable. PaPCo provides a routine
which returns the slice value given the user slice name:
slice_assigned_value=PAPCO_slice_value('USER Slice Name')
USER Slice Name is specified exactly the way it appears in
the ``Mouse Action'' menu.
So, if you want to set up you module to use Zoom, Hair Cursor and your own
slice ``Do my own thing'' you need to set up
slice_type= 1 + 16 + PAPCO_slice_value('USER Do my own thing')
When designing your own slice function try and keep your code general and portable. If you set out from the beginning having the idea that other modules could also use your slide in mind, then there is no real extra effort involved.
PLEASE comment your code thoroughly and provide ample documentation about it it your modules help file (the one accessed from your panel editor) or provide your slice window with it's own help button.
Any user written slice that becomes useful to more than one module is a bonus and can then be easily included as a ``PaPCo slice'' in the next release.