FSC_FILESELECT 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.
Restrictions
Requires the folling files from the Coyote Library:
http://www.idlcoyote.com/programs/error_message.pro
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).
Inspect_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 ERROR_MESSAGE 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.