`AwFileSelect`

A PhAB file-selector widget

Class hierarchy:

PtWidget --> AwFileSelect

For more information, see the diagram of the widget hierarchy.

PhAB icon:

None - instantiated by PhAB's File Selector module.

Description:

The AwFileSelect widget displays itself as a dialog to provide basic file open/save functionality for an application.

AwFileSelect widget

An AwFileSelect widget.

AwFileSelect is a PhAB widget. A PhAB widget uses one or more PhAB modules files as input and can be used only in an application built with PhAB. It's accessible in the Other module list when creating modules for your application.

PtFileSel is more versatile than this widget. You should use it instead.

AwFileSelect shows a directory in two lists. One list shows the files and the other list shows the folders. The initial starting directory is taken from the Aw_ARG_DIRECTORY_PATH resource. You can set this value in the pre-realize setup function for the module. You can also filter the types of files being shown in the file list by setting the Aw_ARG_FILE_SPEC resource. For example, the following code sets up the file selector to display all files with the extension .c in the user's home directory:

open_setup( PtWidget_t *link_instance, ApInfo_t *apinfo, 
            PtCallbackInfo_t *cbinfo )

{
    char    *home_dir;
    PtArg_t args[2];

    if ( !( home_dir = getenv( "HOME" ) ) )
        home_dir = "/";

    PtSetArg( &args[0], Aw_ARG_DIRECTORY_PATH, home_dir, 0 );
    PtSetArg( &args[1], Aw_ARG_FILE_SPEC, "*.c", 0 );
    PtSetResources( ABW_file_selector, 2, args );

    return( Pt_CONTINUE );
}

If you're using the widget to save a file, you can also specify the filename to use by setting the Aw_ARG_FILE_NAME resource.

The dialog contains two action buttons to give the user an indication of what the dialog is going to do:

Button	Meaning	Default text
Action	activate the file selection	`Open`
Cancel	cancel it	`Cancel`

You can change the text for the buttons by setting the Aw_ARG_ACTION_TEXT or Aw_ARG_CANCEL_TEXT resources. For example, if the dialog is being used to save a file, you should change Aw_ARG_ACTION_TEXT to Save.

When the user activates the file selection by clicking on the Action button, the Aw_CB_FS_ACTION callback is invoked. This callback passes widget data to indicate the directory, filename and filespec values at the time the file selection was activated. You can access this data in the callback by casting the callback data as follows:

    AwFileSelectCallback_t *fs = cbinfo->cbdata;

    strcpy( folder, fs->dirpath );
    strcpy( fname,  fs->filename );
    strcpy( fspec,  fs->filespec );

Typically this information is saved globally in the application so that the next time the dialog is displayed it shows the last values entered by the user.

The Aw_CB_FS_CANCEL callback is invoked if the user cancels the dialog in any way without making a selection.

New resources:

Resource	C type	Pt type	Default
Aw_ARG_ACTION_TEXT	`char *`	String	`"Open"`
Aw_ARG_CANCEL_TEXT	`char *`	String	`"Cancel"`
Aw_ARG_DIRECTORY_PATH	`char *`	String	`"/"`
Aw_ARG_FILE_NAME	`char *`	String	NULL
Aw_ARG_FILE_SPEC	`char *`	String	`"*"`
Aw_CB_FS_ACTION	`PtCallback_t *`	Link	NULL
Aw_CB_FS_CANCEL	`PtCallback_t *`	Link	NULL

Aw_ARG_ACTION_TEXT

C type	Pt type	Default
`char *`	String	`"Open"`

The text to appear on the Action button.

Aw_ARG_CANCEL_TEXT

C type	Pt type	Default
`char *`	String	`"Cancel"`

The text to appear on the Cancel button.

Aw_ARG_DIRECTORY_PATH

C type	Pt type	Default
`char *`	String	`"/"`

The initial directory path before the dialog is displayed. The widget uses this value to open the directory and display the files and folders in the appropriate lists.

Aw_ARG_FILE_NAME

C type	Pt type	Default
`char *`	String	NULL

Use this resource to set a default file name. It can also be used to extract the file name in the action callback.

Aw_ARG_FILE_SPEC

C type	Pt type	Default
`char *`	String	`"*"`

A filter that limits the files displayed in the file list. It's typically used when an application wants to show certain types of files. For example, a graphical file viewer might set the file specification to *.gif to limit the files to GIF files. The file specification has no effect on the folder display list.

Aw_CB_FS_ACTION

C type	Pt type	Default
`PtCallback_t *`	Link	NULL

A list of callbacks invoked when the user clicks on the action button or double-clicks on a file in the file list. The application should use these callbacks to perform the selected file operation.

Each callback is passed a PtCallbackInfo_t structure that contains at least the following members:

reason

Aw_CB_FS_ACTION

reason_subtype

0 (not used)

cbdata

A pointer to a AwFileSelectCallback_t structure:

char *dirpath - the current directory path for the filename being acted upon.
char *filename - the name of the file.
char *filespec - the current file specification (which may have been changed by the user).

The dirpath and filename fields can be concatenated to give you a full path to the selected file. The filespec can be saved in a global variable to restore the file specification if the dialog is displayed again.

These callbacks should return Pt_CONTINUE.

Aw_CB_FS_CANCEL

C type	Pt type	Default
`PtCallback_t *`	Link	NULL

A list of callbacks invoked when the user cancels the dialog in any way. This includes clicking on the Cancel button or closing the dialog.