# coyote: FSC_FILESELECT

- coyote/General Programming
- [Source code]

NAME

      FSC_FILESELECT

PURPOSE

      The purpose of this compound widget is to provide a means
      by which the user can type or select a file name. The
      program is written as an "object widget", meaning that
      the guts of the program is an object of class FSC_FILESELECT.
      This is meant to be an example of the obvious advantages of
      writing compound widget programs as objects.

AUTHOR

      FANNING SOFTWARE CONSULTING
      David Fanning, Ph.D.
      1645 Sheely Drive
      Fort Collins, CO 80526 USA
      Phone: 970-221-0438
      E-mail: david@idlcoyote.com
      Coyote's Guide to IDL Programming: http://www.idlcoyote.com/

CATEGORY

      General programming.

CALLING SEQUENCE

      filenameID = FSC_FileSelect(parent)

INPUT PARAMETERS

      parent -- The parent widget ID of the compound widget. Required.

INPUT KEYWORDS

      Event_Pro -- The event handler procedure for this compound widget.By default: "".
      Event_Func -- The event handler function for this compound widget. By default: "".
         If neither EVENT_PRO or EVENT_FUNC is defined, program events are handled internally by the compound widget.
      DirectoryName -- The initial name of the directory. By defaut: current directory.
      Filename -- The initial file name in the filename text widget.
      Filter -- The file filter. By default: "*".
      Frame -- Set this keyword for a frame around the compound widget.
      LabelFont -- The font for the label widget. By default: "".
      LabelName -- The text on the label widgt. By default: "Filename: ".
      LabelSize -- The X screen size of the label widget. By default: 0.
      MustExist -- A flag that indicates selected files must exist. By default: 0.
      NoMaxSize -- A flag to prohibit automatic text widget sizing. By default: 0.
        If this keyword is not set, the compound widget will automatically resize itself to
        the largest widget in its parent base widget. It will do this by changing the size of
        the text widgets holding the file and directory names.
      Read -- Set this keyword to have file selection for reading a file. By default: 1.
      SelectDirectory -- The default directory for file selection. In other words, this is the
        default directory for DIALOG_PICKFILE, which is accessed via the BROWSE buttons.
      SelectFont -- The font for the "Browse" button. By default: "".
      SelectTitle -- The title bar text on the file selection dialog. By default: "Select a File...".
      TextFont -- The font for the filename text widget. By default: "".
      UValue -- User value for any purpose.
      Write -- Set this keyword to open a file for writing. By default: 0.
      XSize -- The X size of the text widget holding the filename. By default: StrLen(filename) * 1.5 > 40.

OUTPUT KEYWORDS

      ObjectRef -- Assign this keyword to an output variable that will hold the internal object reference.
                   With the object reference you can call object methods to easily change many properties of
                   the compound widget.

COMMON BLOCKS

      None.

EVENT STRUCTURE

      All events are handled internally unless either the Event_Pro or Event_Func
      keywords are used to assign an event handler to the compound widget. All events
      generated by the text widgets are passed to the assigned event handler.
      event = { CW_FILESELECT, $     ; The name of the event structure.
                ID: 0L, $            ; The ID of the compound widget's top-level base.
                TOP: 0L, $           ; The widget ID of the top-level base of the hierarchy.
                HANDLER: 0L, $       ; The event handler ID. Filled out by IDL.
                Basename: "", $      ; The base filename without directory specifiers.
                Filename: "", $      ; The fully qualified filename.
                Directory: "", $     ; The name of the current file directory.
              }

EXAMPLE

      An example program is provided at the end of the FSC_FILESELECT code. To run it,
      type these commands:
         IDL> .Compile fsc_fileselect
         IDL> Example
      Or, if you want to obtain the object reference, type this:
         IDL> Example, theObject
      Now you can call the object's methods. For example:
         IDL theObject->SetProperty, XSize=150

GETTING and SETTING VALUES

      So as not to disrupt the accepted paradigm in using compound widgets, you
      can use the return value of the FSC_FILESELECT function with WIDGET_CONTROL to
      get and set the "value" of the widget.
          Widget_Control, filenameID, Set_Value='C:\RSI\IDL52\DATA\cyclone.dat'
      The program will automatically separate the file name portion of the value
      from the directory portion and put things in the correct text widgets.
      Similarly, you can get the "value" of the widget:
          Widget_Control, filenameID, Get_Value=theValue
          Print, theValue
              C:\RSI\IDL52\DATA\cyclone.dat
      The return value is the fully qualified file path to the file.

USING OBJECT METHODS to CHANGE PROGRAM PROPERTIES

      If you obtain the object reference, you have a great deal more control
      over the properties of the compound widget. You obtain the object reference
      by calling the function like this:
         filenameID = FSC_FILESELECT(parent, ObjectRef=theObject)

OBJECT PROCEDURE METHODS

      GetProperty -- This method allows various properties of the widget to be
          returned via output keywords. The keywords that are available are:
         DirectoryName -- The current directory.
         Event_Func -- The name of the event handler function for this compound widget.
         Event_Pro -- The name of the event handler procedure for this compound widget.
         Filename -- The current base filename.
         Filter -- The current file filter.
         LabelName -- The text on the label widget.
         LabelSize -- The X screen size of the label widget.
         MustExist -- A flag that indicates selected files must exist to be selected.
         Parent -- The parent widget of the compound widget.
         Read=read -- The file selection for reading flag.
         SelectTitle -- The title bar text on the file selection dialog.
         TLB -- The top-level base of the compound widget.
         UValue -- The user value of the compound widget.
         Write -- The file selection for writing flag.
         XSize -- The X size of the text widget holding the filename.
      LabelSize -- This method makes sure that the directory name and file name labels
         are the same size. Normally, this procedure is called internally. No parameters.
      MatchSize -- This method resizes the compound widget so that it is as long as the
         the longest widget in the parent base widget. This is done automatically upon
         realization unless the NOMAXSIZE keyword is set. The method aids in writing
         resizeable widget programs.
      SetProperty -- This method allows various properties of the widget to be
          set via input keywords. The keywords that are available are:
         DirectoryName -- The current directory.
         Event_Func -- The name of the event handler function for this compound widget.
         Event_Pro -- The name of the event handler procedure for this compound widget.
         Filename -- The current base filename.
         Filter -- The current file filter.
         LabelName -- The text on the label widget.
         LabelSize -- The X screen size of the label widget.
         MustExist -- A flag that indicates selected files must exist to be selected.
         Read -- The file selection for reading flag.
         SelectTitle -- The title bar text on the file selection dialog.
         UValue -- The user value of the compound widget.
         Write -- The file selection for writing flag.
         XSize -- The X size of the text widget holding the filename.
      TextSelect - Allows you to create a selection in filename text widget. See the
                   documentation for the SET_TEXT_SELECT keyword to Widget_Control.
         selection -- A two-element array containing the starting position and selection length.

OBJECT FUNCTION METHODS

      GetFileName -- Returns the fully qualified filename. No parameters.
      GetTLB -- Returns the top-level base ID of the compound widget. No Parameters.
      Inspect_DirectoryName -- Inspects the directory name for correctness. Requires one positional parameter.
        directoryName -- The name of the directory from the directory text widget.
        textSelection -- The current text selection position.
        At the moment all this does is remove any blank characters from either
        end of the directory name and makes sure the last character of the directory
        name does not end in a subdirectory specifier (except for VMS).
      nspect_Filename -- Inspects the file name for correctness. Requires one positional parameter.
        filename -- The name of the file from the filename text widget.
        textSelection -- The current text selection position.
        At the moment all this does is remove any blank characters from either
        end of the file name

MODIFICATION HISTORY

      Written by: David W. Fanning, 21 NOV 1999.
      Fixed bug in File Name selection button. 18 MAR 2000. DWF.
      Fixed an error in which directory the Browse buttons should start
          searching. 29 SEP 2000. DWF.
      Previously returned events only for typing in text widgets. Now
          Browse button events are also returned. 29 SEP 2000. DWF.
      Fixed a bug in setting the file filter. 29 SEP 2000. DWF.
      Removed the Directory Browse button 10 AUG 2002. DWF.
      Added cgErrorMsg to error handling. 10 AUG 2002. DWF.
      Changed the ability to specify a file filter as a string array, instead
          of just as a scalar string. This required the use of a pointer, which
          meant that I had to remove the FILTER field from the CW_FILESELECT
          event structure to avoid likely memory leakage. This is a dangerous
          change because it means programs that relied on this (I expect there
          are very, very few) will break and it goes against my philosopy of
          keeping my programs backward compatible. Let me know if you have
          problems. In testing, I discoved no problems in my own code. 31 OCT 2002. DWF.
      Fixed a problem with DIALOG_PICKFILE that sometimes allowed users to change
          directories without selecting a file. 3 Nov 2002. DWF.
      Fixed a problem with widget resizing with the help of Bob Portman that had plagued
          me from the beginning. Thanks, Bob! 5 August 2003. DWF
      Added TEXTSELECT method. 5 Aug 2003. DWF.
      Had to add FORWARD_FUNCTION statement to get error handler compiled when using
          DIRECTORY keyword. 24 Nov 2003. DWF.
      Fixed a problem with too many events going to an event handler specified with
          the EVENT_PRO or EVENT_FUNC keyword from the text widget. Now only Carriage
          Return events are passed on to the user-specified event handler. 8 July 2004. DWF.
      Replace all "\" characters with "/" characters in directory names. 8 Januay 2006. DWF.
      Set the default fonts to be the current widget font, rather than the default widget font. 4 Oct 2008. DWF.