xxx_gui.pro

IDL语言编写的用于天文自适应光学仿真的软件CAOS V6.0的第三部分。

;**
;********************************************************************************
;** HOW TO USE THIS TEMPLATE:                                                   *
;**                                                                             *
;** 0-PLEASE READ THE WHOLE TEMPLATE FIRST (AND AT LEAST ONCE) !!               *
;** 1-CHANGE EVERYWHERE THE STRINGS "XXX" INTO THE CHOSEN 3-CHAR MODULE NAME    *
;** 2-CHANGE EVERYWHERE THE STRINGS "XYZ" INTO THE NAME OF THE SOFTWARE PACKAGE *
;** 3-ADAPT THE TEMPLATE ONTO THE NEW MODULE CASE FOLLOWING THE EXAMPLES,       *
;**   RECOMMENDATIONS, AND ADVICES FOUND THROUGH THE TEMPLATE                   *
;**   (A SPECIAL ONE FOR THE GRAPHICAL USER INTERFACE IS TO FIRST ADAPT THE     *
;**    XXX_GUI FUNCTION THAT CREATES THE GUI, THEN ADAPT THE XXX_GUI_EVENT      *
;**    PROCEDURE THAT MANAGES THE EVENTS COMMING FROM EACH ACTIVE WIDGET OF     *
;**    THE GUI, AND EVENTUALLY ADAPT THE XXX_GUI_SET PROCEDURE THAT DEALS WITH  *
;**    THE SENSITIVE SETTING OF THE WIDGETS AND OTHER PARAMETER SETTINGS THAT   *
;**    HAVE TO BE MANAGED WHENEVER AN EVENT OCCURS -- I.E. WITHIN THE EVENT     *
;**    LOOP)                                                                    *
;** 4-DELETE ALL THE LINES OF CODE BEGINNING WITH ";**"                         *
;**                                                                             *
;********************************************************************************
;**
;**
;** here is the routine identification
;**
; $Id: xxx_gui.pro,v 5.0 2006/02/01 marcel.carbillet $
;**
;** put right version, date, and main author name of last update in the line
;** here above following the formats:
;** -n.m for the version (n=software release version, m=module update version).
;** -YYYY/MM/DD for the date (YYYY=year, MM=month, DD=day).
;** -first_name.last_name for the (last update) main author name.
;**
;
;**
;** here begins the header of the routine
;**
;+
; NAME:
;    xxx_gui
;
; PURPOSE:
;    xxx_gui generates the Graphical User Interface (GUI) for
;    setting the parameters of the [PUT HERE THE NAME] (XXX) module.
;    a parameter file called xxx_nnnnn.sav is created, where nnnnn
;    is the number n_module associated to the module instance.
;    the file is stored in the project directory proj_name located
;    in the working directory.
;    (see xxx.pro's header --or file xyz_help.html-- for details
;    about the module itself).
;
; CATEGORY:
;    module's Graghical User Interface routine
;
; CALLING SEQUENCE:
;    error = xxx_gui(n_module, $
;                    proj_name )
; 
; INPUTS:
;    n_module : number associated to the intance of the XXX module
;               [integer scalar -- n_module > 0].
;    proj_name: name of the current project [string].
;
; OUTPUTS:
;    error: error code [long scalar].
;
; COMMON BLOCKS:
;    none.
;
; CALLED NON-IDL FUNCTIONS:
;** describe here the non-IDL routines used by xxx_gui, if any.
;** these routines must be put either in the module's sub-folder
;** !caos_env.modules+"xxx/xxx_gui_lib/", or in the Software
;** Package library folder, or even in the
;** CAOS system library folder !caos_env.lib.
;
; ROUTINE MODIFICATION HISTORY:
;    routine written: date,
;                     author (institute) [email].
;    modifications  : date,
;                     author (institute) [email]:
;                    -description of the modifications.
;                   : date,
;                     author (institute) [email]:
;                    -description of the modifications.
;
;**
;** ROUTINE'S TEMPLATE MODIFICATION HISTORY:
;**    routine written: may 1998,
;**                     Armando Riccardi (OAA) [[e-mail]].
;**    modifications  : january 1999,
;**                     Marcel Carbillet (OAA) [[e-mail]]:
;**                    -completed (with more examples)
;**                    -adapted to version 1.0 regarding the initialisation and
;**                     calibration process.
;**                   : february 1999,
;**                     Marcel Carbillet (OAA) [[e-mail]]:
;**                    -a few other modifications for version 1.0.
;**                   : november 1999,
;**                     Marcel Carbillet (OAA) [[e-mail]]:
;**                    -enhanced and adapted to version 2.0 (CAOS), mainly
;**                     regarding the new calibration process.
;**                   : june 2001,
;**                     Marcel Carbillet (OAA) [[e-mail]]:
;**                    -enhanced for version 3.0 of CAOS (package-oriented).
;**                   : january 2003,
;**                     Marcel Carbillet (OAA) [[e-mail]]:
;**                    -simplified templates for the version 4.0 of the
;**                     whole CAOS system (no more use of the COMMON variable
;**                     "calibration" and no more use of the possible
;**                     initialisation file and, obviously, of the calibration
;**                     file as well).
;**                    -now use of the variable info.pack_name, and the
;**                     variable info.mod_type is changed into info.mod_name.
;**                    -(xxx_info()).help stuff added (instead of !caos_env.help).
;**                   : december 2004,
;**                     Marcel Carbillet (LUAN) [[e-mail]]:
;**                    -the lack of compatibility between the Software Package
;**                     version presently used within the CAOS Application Builder
;**                     and the Soft. Pack. version under which the parameter file
;**                     was created no longer provoke a crash but only a warning...
;**                     This account from version 5.0 of the Software Package CAOS,
;**                     version 3.0 of the Software Package AIRY, and version 1.0
;**                     of the Software Package MAOS (and any future Soft. Pack.).
;**                    : february 2006,
;**                     Marcel Carbillet (LUAN) [[e-mail]]:
;**                    -version-check warning stuff debugged.
;**
;-
;
;**
;** here begins the xxx_gui_set procedure: just eliminate it all if no
;** sensitive checking or other parameter setting is needed
;**
;;;;;;;;;;;;;;;;;;;;;;;;;;;;
; status setting procedure ;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;
pro xxx_gui_set, state

;**
;** show an hourglass if the setting calculus could be a bit long...
;**
widget_control, /HOURGLASS

;**
;** example of sensitive setting/unsetting of sub-bases of the GUI in function
;** of the option chosen in a group of buttons.
;**
case state.par.choice of
    0: begin
        widget_control, state.id.choice0_base, /SENSITIVE
        widget_control, state.id.choice1_base, SENSITIVE=0
    end
    1: begin
        widget_control, state.id.choice0_base, SENSITIVE=0
        widget_control, state.id.choice1_base, /SENSITIVE
    end
endcase

;**
;** example of updating of a widget that gives an indicative parameter
;** (in this simple example twice the value of the parameter needed by
;** "choice0")
;**
dummy = 2*state.par.choice0_param
widget_control, state.id.choice0_test, SET_VALUE=dummy

end

;**
;** here is the event handler procedure xxx_gui_event
;**
;;;;;;;;;;;;;;;;;;;
; GUI events loop ;
;;;;;;;;;;;;;;;;;;;
;
pro xxx_gui_event, event

; xxx_gui error management block
common error_block, error

; read the GUI state structure
widget_control, event.top, GET_UVALUE=state

; handle a kill request (considered as a cancel event).
;**
;** the right error returning is guaranteed only if GROUP_LEADER keyword
;** is set to a valid parent id in the xxx_gui call.
;**
if tag_names(event, /STRUCTURE_NAME) eq 'WIDGET_KILL_REQUEST' then begin
   error = !caos_error.cancel
   widget_control, event.top, /DESTROY
endif

; handle all the other events
widget_control, event.id, GET_UVALUE=uvalue
case uvalue of

   ;**
   ;** the first following cases (before the time integration and delay events
   ;** management) are only a consequence of the examples taken here. take it
   ;** as a widget tutorial.
   ;**

   ;**
   ;** chosen "choice" event management (choice0 or choice1)
   ;** (case of a cw_bgroup widget)
   ;**
   'choice': state.par.choice = event.value

   ;**
   ;** choice0's integer parameter event management
   ;** (case of an editable cw_field widget with an integer value)
   ;**
   'choice0_param': state.par.choice0_param = event.value

   ;**
   ;** choice1's parameter event management
   ;** (case of a cw_fslider widget)
   ;**
   'choice1_param': state.par.choice1_param = event.value

   ;**
   ;** choice1's type event management
   ;** (case of a droplist widget)
   ;**
   'choice1_type': state.par.choice1_type = event.index

   ;**
   ;** the two following event management cases are necessary if time
   ;** integration and/or delay is required for the module. otherwise
   ;** just eliminate this part.
   ;**
   'time_integ': state.par.time_integ = event.value

   'time_delay': state.par.time_delay = event.value

   ;**
   ;** the four following event management are for the standard buttons.
   ;** as a consequence, this part must not be eliminated !!
   ;**
   ; handle event from standard save button
   'save': begin

      ;**
      ;** put in the following cross-check controls among the parameters.
      ;** here are just some examples...
      ;**
      ; cross-check controls among the parameters

      if state.par.choice0_param eq 0 then begin
         dummy = dialog_message(["choice 0 parameter cannot be 0"], $
                                DIALOG_PARENT=event.top,            $
                                TITLE='XXX error',                  $
                                /ERROR                              )
         ;**
         ;** return without saving if the test failed
         ;**
         return
      endif
        
      if state.par.choice1_param eq 0 then begin
         dummy = dialog_message(["choice 1 parameter cannot be 0"], $
                                DIALOG_PARENT=event.top,            $
                                TITLE='XXX error',                  $
                                /ERROR                              )
         ;**
         ;** return without saving if the test failed
         ;**
         return
      endif

      ;**
      ;** end of the cross-check controls
      ;**
 
      ; check before saving the parameter file if filename already exists
      check_file = findfile(state.sav_file)
      if check_file[0] ne "" then begin
         answ = dialog_message(['file '+state.sav_file+' already exists.', $
                                'do you want to overwrite it ?'],          $
                               DIALOG_PARENT=event.top,                    $
                               TITLE='XXX warning',                        $
                               /QUEST)
         ; return without saving if the user doesn't want to overwrite the
         ; existing parameter file
         if strlowcase(answ) eq "no" then return
      endif else begin
         answ = dialog_message(['file '+state.sav_file+' will be saved.'], $
                               DIALOG_PARENT=event.top,                    $
                               TITLE='XXX information',                    $
                               /INFO                                       )
         ; inform were the parameters will be saved
      endelse

      ; save the parameter data file
      par = state.par
      save, par, FILENAME = state.sav_file

      ; kill the GUI returning a null error
      error = !caos_error.ok