6.9 USER defined slices

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.

6.9.1 Interfacing your own User Slice

Adding a new slice type is done by setting an environmental variable in papco_set_variables.pro in the user's papco_user_XX directory:

papco_setenv, 'USER_MOUSE_ACTIONS=View_Polar_Slice/View_Ephemeris'

The format of this string is new_slice_1/new_slice_2/new_slice_3 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 PLOT_COMPOSER, then

thisplotinfo=widgetData.plotsDrawn(panelNr)

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 draw_plot_type procedure in the PaPCo interface file papcoadd_plot_type. This string is also available in the structure:

get_data_call=thisplotinfo.get_data_call

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 string again:

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!

6.9.2 Selecting the show-selection type for your User Slice

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):

ZOOM	uses box
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 environmental variable 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 have set

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 above).

6.9.3 Getting at information

All the routines that implement the show-selection share a common block, which is available to the user:

COMMON MOUSE_SELECT,old,click,pnlNr,n_x,n_y

where

click	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.
old	2-element float	Contains the previous last clicked coordinates. When mouse was dragged,
		contains the start of the drag. Normal coordinates.
pnlNr	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
		COMMON PLOT_COMPOSER, widgetData. This array is under
		widgetdata.plotsdrawn, use pnlNr to get at that panel's plotinfo:
		myplotinfo=widgetdata.plotsdrawn(pnlNr)
n_x,n_y	2-element float	Contains the current mouse coordinates independent of what was clicked.
		Normal coordinates.

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.

6.9.4 Writing your own show-selection

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 papco_cursor.pro.

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 USER_SHOW_ACTIONS 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.

6.9.5 Getting more info for your USER slices

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:

FUNCTION papco_cursor_time,user_time,panelNr,MJDT=MJDT

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 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.

6.9.6 Multiple mouse button support

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:

left button	-	default mouse action as defined by Mouse Action in PaPCo
	-	main Window.
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.

6.9.7 Assigning slice option numbers

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')

Note that 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 as:

slice_type= 1 + 16 + PAPCO_slice_value('USER Do my own thing')

6.9.8 Keeping things general

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.