Routines (alphabetical) > Routines: C > CW_FILESEL

# CW_FILESEL

The CW_FILESEL function is a compound widget for file selection.

This routine is written in the IDL language. Its source code can be found in the file `cw_filesel.pro` in the `lib` subdirectory of the IDL distribution.

## Examples

This example creates a CW_FILESEL widget that is used to select image files for display. Note how the DONE tag of the event structure returned by CW_FILESEL is used to determine which button was pressed, and how the VALUE tag is used to obtain the file that was selected:

PRO image_opener_event, event

WIDGET_CONTROL, event.top, GET_UVALUE=state, /NO_COPY

CASE event.DONE OF

0: BEGIN

state.file = event.VALUE

WIDGET_CONTROL, event.top, SET_UVALUE=state, /NO_COPY

END

1: BEGIN

IF (state.file NE '') THEN BEGIN

img = READ_IMAGE(state.file)

TV, img

ENDIF

WIDGET_CONTROL, event.top, SET_UVALUE=state, /NO_COPY

END

2: WIDGET_CONTROL, event.top, /DESTROY

ENDCASE

END

PRO image_opener

DEVICE, DECOMPOSED=0, RETAIN=2

base = WIDGET_BASE(TITLE ='Open Image', /COLUMN)

filesel = CW_FILESEL(base, /IMAGE_FILTER, FILTER='All Files')

file=''

state = {file:file}

WIDGET_CONTROL, base, /REALIZE

WIDGET_CONTROL, base, SET_UVALUE=state, /NO_COPY

XMANAGER, 'image_opener', base

END

This code opens the following dialog:

## Syntax

Result = CW_FILESEL ( Parent [, /FILENAME] [, FILTER=string array] [, /FIX_FILTER] [, /FRAME] [, /IMAGE_FILTER] [, /MULTIPLE | , /SAVE] [, PATH=string] [, TAB_MODE=value] [, UNAME=string] [, UVALUE=value] [, /WARN_EXIST] )

## Return Value

This function returns the widget ID of the newly-created file selection widget.

## Arguments

### Parent

The widget ID of the parent.

## Keywords

### FILENAME

Set this keyword to have the initial filename filled in the filename text area.

### FILTER

Set this keyword to an array of strings determining the filter types. If not set, the default is “All Files”. All files containing the chosen filter string will be displayed as possible selections. “All Files” is a special filter which returns all files in the current directory.

Note: You can use language catalogs to internationalize this value with strings in particular languages.

Example:

FILTER=["All Files", ".txt"]

Multiple filter types may be used per filter entry, using a comma as the separator.

Example:

FILTER=[".jpg, .jpeg", ".txt, .text"]

### FIX_FILTER

If set, the user can not change the file filter.

### FRAME

If set, a frame is drawn around the widget.

### IMAGE_FILTER

If set, the filter “Image Files” will be added to the end of the list of filters. If set, and FILTER is not set, “Image Files” will be the only filter displayed. Valid image files are determined from QUERY_IMAGE.

### MULTIPLE

If set, the file selection list will allow multiple filenames to be selected. The filename text area will not be editable in this case. It is illegal to specify both /SAVE and /MULTIPLE.

### PATH

Set this keyword to the initial path the widget is to start in. The default is the current directory.

### SAVE

Set this keyword to create a widget with a “Save” button instead of an “Open” button. It is illegal to specify both /SAVE and /MULTIPLE.

### TAB_MODE

Set this keyword to one of the values shown in the table below to determine how the widget hierarchy can be navigated using the Tab key. The TAB_MODE setting is inherited by lower-level bases and child widgets unless it is explicitly set on an individual widget.

Note: It is not possible to tab to disabled (SENSITIVE=0) or hidden (MAP=0) widgets.

Valid settings are:

Value | Description
0 | Disable navigation onto or off of the widget. This is the default. Child widgets automatically inherit the tab mode of the parent base as described in Inheriting the TAB_MODE Value.
1 | Enable navigation onto and off of the widget.
2 | Navigate only onto the widget.
3 | Navigate only off of the widget.

Note: In widget applications on the UNIX platform, the Motif library controls what widgets are brought into and released from focus using tabbing. The TAB_MODE keyword value is always zero, and any attempt to change it is ignored when running a widget application on the UNIX platform. Tabbing behavior may vary significantly between UNIX platforms; do not rely on a particular behavior being duplicated on all UNIX systems.

### UNAME

Set this keyword to a string that can be used to identify the widget in your code. You can associate a name with each widget in a specific hierarchy, and then use that name to query the widget hierarchy and get the correct widget ID.

To query the widget hierarchy, use the WIDGET_INFO function with the FIND_BY_UNAME keyword. The UNAME should be unique to the widget hierarchy because the FIND_BY_UNAME keyword returns the ID of the first widget with the specified name.

### UVALUE

The “user value” to be assigned to the widget.

### WARN_EXIST

Set this keyword to produce a question dialog if the user selects a file that already exists. This keyword is useful when creating a “write” dialog. The default is to allow any filename to be quietly accepted, whether it exists or not.

### Keywords to WIDGET_CONTROL

You can use the GET_UVALUE and SET_UVALUE keywords to WIDGET_CONTROL to obtain or set the user value of this widget. Use the command to read the currently selected filename (or filenames if MULTIPLE is set) including the full path:

WIDGET_CONTROL, id, GET_VALUE=filenames

To set the value of the filename, use the following command:

WIDGET_CONTROL, id, SET_VALUE=value

where value is a scalar string (or string array) containing the filenames, including the full path.

See Creating a Compound Widget for a more complete discussion of controlling compound widgets using WIDGET_CONTROL and WIDGET_INFO.

## Widget Events Returned by CW_FILESEL

CW_FILESEL generates an event that specifies the name of the selected file, whether the user completed the file selection operation, and the filename filter used. This widget generates event structures with the following definition:

Event = {FILESEL_EVENT, ID:0L, TOP:0L, HANDLER:0L,VALUE:'',

DONE:0L, FILTER:''}

The ID field is the widget ID of the CW_FILESEL widget. The TOP field contains the widget ID of the top-level widget. The HANDLER field is always set to zero. The VALUE field is a string containing the most recent filename selected, if any.

Note: Even if MULTIPLE is set, VALUE will only contain the most recently selected filename. To retrieve all of the currently selected filenames, use the GET_VALUE keyword to WIDGET_CONTROL.

The DONE field can be any of the following:

0 | User selected a file but didn’t double-click, or the user changed filters (in this case the VALUE field will be an empty string)
1 | User pressed “Open”/“Save” or double-clicked on a file
2 | User pressed “Cancel”

The FILTER field is a string containing the current filter.

## Version History

5.3 | Introduced
6.1 | Added TAB_MODE keyword

## See Also

DIALOG_PICKFILE, FILEPATH