;+ ;Procedure: ; yyy_ui_plugin ; ;Purpose: ; A basic example menu plugin for the SPEDAS GUI API. ; ;Calling Sequence: ; See instructions in spedas/gui/resources/spd_ui_plugin_config.txt ; to enable the plugin in the GUI. ; ;Input: ; gui_id: The widget ID of the top level GUI base. ; loaded_data: The GUI loaded data object. This object stores all ; data and corresponding metadata currently loaded ; into the GUI. ; call_sequence: The GUI call sequence object. This object stores ; a list of calls to external routines. These calls ; are replicated when a GUI document is opened to ; reproduce those operations. ; history_window: The GUI history window object. This object ; provides a viewable textual history of GUI ; operations and error reports. ; status_bar: The GUI status bar object. This object displays ; informational messages at the bottom of the main ; GUI window. ; data_tree: The GUI data tree object. This object provides a ; graphical tree of all loaded data variables. ; A copy of this object can be used to create a ; tree display within the plugin. ; time_trange: The GUI's main time range object. This object ; stores the current time range for the GUI and ; may be used/modified by the plugin. ; ;Input/Output: ; data_structure: This keyword may be used to return a data structure ; that will be saved by the GUI and passed back to ; the plugin the next time it is called. This can be ; used to save any information that could be needed ; on subsequent calls (e.g. time ranges, previous ; operations, plugin specific option selections, etc.) ; ;API Requirements: ; -Plugins must accept the GUI top widget ID, loaded data object, ; call sequence object, history window object, and status bar object ; (in that order) and must include the _extra keyword. ; -The GUI data tree and time range objects may also be accessed ; via the corresponding keywords, but are not required. ; -Information for subsequent calls can be stored using the ; data_structure keyword (described above). ; -All operations performed by a plugin must be executed in separate ; helper routines to be compatible with GUI document files. See ; yyy_ui_plugin_add, yyy_ui_plugin_delete, and yyy_ui_plugin_randomize ; for examples. ; ;Notes: ; ; ;$LastChangedBy: egrimes $ ;$LastChangedDate: 2015-05-22 15:25:24 -0700 (Fri, 22 May 2015) $ ;$LastChangedRevision: 17678 $ ;$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_3_2/spedas_gui/api_examples/plugin_menu/yyy_ui_plugin.pro $ ;- ;+ ;Purpose: ; Get the names of all currently selected variables from the tree widget. ; ;- function yyy_ui_plugin_getselection, state compile_opt idl2, hidden ;get current selectrion from data tree variables = state.data_tree->getvalue() if ~ptr_valid(variables[0]) then begin state.status_bar->update, 'No valid selection.' return, '' endif ;loop over selected variables to get list for i=0, n_elements(variables)-1 do begin names = array_concat( (*variables[i]).groupname, names) endfor return, names end ;+ ;Purpose: ; Example plugin event handler. ; ;- pro yyy_ui_plugin_event, event compile_opt idl2, hidden ;Extract structure holding important object references and widget IDs. ;------------------------------------------------------------ ; If /no_copy is used the uvalue must be re-set before ; the event handler returns. widget_control, event.top, get_uval=state, /no_copy ;Error catch block ;------------------------------------------------------------ catch, error if error ne 0 then begin catch, /cancel ;notify user help, /last_message dummy = dialog_message('An unexpected error occured, see console output.', $ /error, /center, title='Unknown Error') ;close plugin if state structure is no longer defined, ;otherwise attempt to continue running if is_struct(state) then begin widget_control, event.top, set_uval=state, /no_copy return endif else begin print, '**FATAL PLUGIN ERROR - Closing window**' if widget_valid(event.top) then begin widget_control, event.top, /destroy endif return endelse endif ;catch kill requests if tag_names(event, /structure_name) eq 'WIDGET_KILL_REQUEST' then begin widget_control, event.top, /destroy return endif ;process the event based on which widget generated it ;------------------------------------------------------------ uname = strlowcase(widget_info(event.id, /uname)) if ~is_string(uname) then uname = '' case uname of ;exit ;---------------------------------- 'ok': begin state.status_bar->update, 'Closing test plugin.' widget_control, event.top, set_uval=state, /no_copy ;necessary? widget_control, event.top, /destroy return end ;add test variable ; -demostrates adding a new variable to loaded data object ;---------------------------------- 'add': begin ;call helper routine yyy_ui_plugin_add, loaded_data=state.loaded_data, $ history_window=state.history_window, $ status_bar = state.status_bar ;Add to call sequence for GUI document replay ; -specify name of routine that was just called ; -specify any non-API keywords (none for this example) state.call_sequence->addPluginCall, 'yyy_ui_plugin_add' end ;multiply data by scaled random factor ; -demonstrates retrieving a variable from loaded data object and ; storing modified variable with identical metadata ;---------------------------------- 'randomize': begin ;get selected names from tree names = yyy_ui_plugin_getselection(state) if ~is_string(names) then break ;get time range from object trange = [ state.time_range->getstarttime(), $ state.time_range->getendtime() ] ;call helper routine yyy_ui_plugin_randomize, loaded_data=state.loaded_data, $ history_window=state.history_window, $ status_bar = state.status_bar, $ names=names, trange=trange ;non-API keywords ;Add to call sequence for GUI document replay ; -specify name of routine that was just called ; -specify any non-API keywords state.call_sequence->addPluginCall, 'yyy_ui_plugin_randomize', $ names=names, trange=trange end ;delete selected data ;---------------------------------- 'delete': begin ;get selected names from tree names = yyy_ui_plugin_getselection(state) if ~is_string(names) then break ;call helper routine yyy_ui_plugin_delete, loaded_data=state.loaded_data, $ status_bar = state.status_bar, $ names=names ;non-API keywords ;Add to call sequence for GUI document replay ; -specify name of routine that was just called ; -specify any non-API keywords state.call_sequence->addPluginCall, 'yyy_ui_plugin_delete', $ names=names end else: ;ignore other widgets' events endcase ;update data tree for all non-tree events if uname ne 'tree' then begin state.data_tree->update endif ;re-set state structure widget_control, event.top, set_uval=state, /no_copy end pro yyy_ui_plugin, gui_id=gui_id, $ loaded_data=loaded_data, $ call_sequence=call_sequence, $ data_tree=data_tree, $ time_range=time_range, $ data_structure=data_structure, $ history_window=history_window, $ status_bar=status_bar, $ _extra=_extra compile_opt idl2, hidden ;top level base ;------------------------------------------------------- ; IMPORTANT: The top level base should always be modal and have its ; group leader set to GUI_ID. This will keep events from ; the main gui from conflicting with those from the plugin. main_base = widget_base(title='Example Plugin.', /col, /base_align_center, $ group_leader=gui_id, /modal, /tlb_kill_request_events, tab_mode=1) ;time widget ; -allows user to modify the current GUI time range ;------------------------------------------------------- time_base = widget_base(main_base, /row) ;create new time widget using time range from GUI time = spd_ui_time_widget(time_base, status_bar, history_window, $ timerangeobj=time_range, uname='time', suppressoneday=1) ;data tree ; -allows user to select loaded data variables ;------------------------------------------------------- tree_base = widget_base(main_base, /row) ;The data tree requires a reference to the loaded data object ;and a copy of the GUI data tree. Here we also specify the ;widget's size, allow for multiple selections, and set the ;widget to display each variable's time range. tree = obj_new('spd_ui_widget_tree', tree_base, 'tree', loaded_data, $ uname='tree', xsize=440, ysize=330, /multi, /showdatetime, $ from_copy=long(*data_tree)) ;buttons ;------------------------------------------------------- button_base = widget_base(main_base, /row) ok = widget_button(button_base, value=' OK ', uname='ok', $ tooltip='Exit test widget.') add = widget_button(button_base, value='Add', uname='add', $ tooltip='Add test variable.') randomize = widget_button(button_base, value='Randomize', uname='randomize', $ tooltip='Multiply selected data within the current time range by scaled random factor.') delete = widget_button(button_base, value='Delete', uname='delete', $ tooltip='Delete all selected variables') ;finalize & start ;------------------------------------------------------- ;Store important objects and widget IDs in a structure ;that can be retreived while processing widget events. state = { $ gui_id:gui_id, $ loaded_data:loaded_data, $ data_tree:tree, $ time_range:time_range, $ call_sequence:call_sequence, $ history_window:history_window, $ status_bar:status_bar $ } ;Create/update output structure. In general this structure can ;contain any information that the plugin may need on subsequent calls. ;For the purpose of this example it will simply store the number of ;times the plugin has been opened. if is_struct(data_structure) then begin data_structure.count++ endif else begin data_structure = {count:1} endelse status_bar->update, 'This plugin has been opened '+strtrim(data_structure.count,2)+' times.' ;center the window centertlb, main_base ;store state structure and realize widgets widget_control, main_base, set_uval=state, /no_copy widget_control, main_base, /realize ;keep windows in X11 from snaping back to center during tree widget events if !d.NAME eq 'X' then begin widget_control, main_base, xoffset=0, yoffset=0 endif ;start IDL event manager xmanager, 'yyy_ui_plugin', main_base, /no_block return end