PtFileSelection()

Create a file-selector dialog

Synopsis:

int PtFileSelection( PtWidget_t *parent, 
                     PhPoint_t const *pos,
                     char const *title, 
                     char const *root_dir, 
                     char const *file_spec, 
                     char const *btn1,
                     char const *btn2, 
                     char const *format, 
                     PtFileSelectionInfo_t *info, 
                     int flags );

Arguments:

parent

The dialog's parent, which can be NULL. It's used with the pos argument to position the dialog.

pos

A pointer to a PhPoint_t structure that's used with the parent to position the dialog.

If pos is NULL, the function centers the dialog on the screen; if parent is NULL, the function places the dialog at the absolute coordinates of pos; otherwise it places the dialog at the relative offset of pos within parent.

title

The dialog's title. If NULL, the function uses the string File Selector.

root_dir

The current directory for the file-selector widget. The default is / if this parameter is NULL.

You can pass a directory or a full path for a file. PtFileSelection() parses the string and uses the longest existing path as the root directory. The function uses rest of the string as a suggested path to be displayed in the Name field.

file_spec

The file specification to look for. The default is * if this argument is NULL.

btn1

The string for button 1 (the default is Open). This is the button that returns the selected-file information. When activated, it sets info->ret to Pt_FSDIALOG_BTN1.

If you want to have a hotkey for this button, place an ampersand (&) in front of the appropriate character in the string. For example, to have the string Select with s as a hotkey, pass &Select as btn1.

btn2

The string for button 2 (the default is Cancel). When activated, it sets info->ret to Pt_FSDIALOG_BTN2. If you want to have a hotkey for this button, place an ampersand (&) in front of the appropriate character in the string.

format

A string to be used with the Pt_ARG_FS_FORMAT resource of the widget. It indicates what information to display and in what order. If you don't want the divider shown, pass NULL for this argument; the function then displays only the filenames. See the description of for the format of this string.

info

This is a mandatory parameter. The function returns the selected file in the path portion of this structure. For more information, see “PtFileSelectionInfo_t structure,” below.

flags

Flags that affect the appearance and behavior of the dialog. The default is 0; you can OR together any of the following bits:

Pt_FSR_MULTIPLE: Let the user select more than one file or directory at a time.
Pt_FSR_NO_FCHECK: Permit nonexistent files/directories to be selected. (The path must exist.)
Pt_FSR_NO_FSPEC: Don't display the file specification.
Pt_FSR_NO_UP_BUTTON: Don't display the up-directory button.
Pt_FSR_NO_NEW: Disable new directory creation via the Insert key.
Pt_FSR_NO_NEW_BUTTON: Don't display the new-directory button.
Pt_FSR_NO_SELECT_FILES: Files aren't selectable.
Pt_FSR_SELECT_DIRS: Directories are selectable.
Pt_FSR_CREATE_PATH: Create directories as needed when typed in manually.
Pt_FSR_NO_CONFIRM_CREATE_PATH: Don't confirm directory creation.
Pt_FSR_NO_DELETE: Disable deletions via the Delete key.
Pt_FSR_NO_CONFIRM_DELETE: Don't confirm deletions.
Pt_FSR_RECURSIVE_DELETE: Enable the recursive deletion of directories.
Pt_FSR_CONFIRM_EXISTING: Confirm the selection of an existing file with an message.
The Pt_FSR_CONFIRM_EXISTING flag is ignored when you've set the Pt_FSR_MULTIPLE flag, however you can supply your own confirm_selection function as described later.

You can also OR in the following bits, which affect the appearance and behavior of the PtFileSel widget in the dialog. Each of these bits corresponds to a flag in the Pt_ARG_FS_FLAGS resource of the PtFileSel widget:

Pt_FSR_DONT_SHOW_DIRS: Don't display directories.
Pt_FSR_DONT_SHOW_FILES: Don't display files.
Pt_FSR_SHOW_HIDDEN: Show hidden directory entries (i.e. those whose names begin with a period).
Pt_FSR_SHOW_ERRORS: Display (with a special icon) directory entries that had a read error.
Pt_FSR_FREE_ON_COLLAPSE: Free items on every collapse. This means that every time a directory expands, its content is reread from the disk.
Pt_FSR_TREE: Display the directory entries in a tree. By default, entries are displayed in a single level.
Pt_FSR_NO_SEEK_KEY: Disable keyboard-seek in single-level mode. The default is to allow key-seeks by typing a single character.
Pt_FSR_NO_ROOT_DISPLAY: Don't display a root directory item in tree display mode. By default, when Pt_FSR_TREE is set, a root directory item is shown.
Pt_FSR_CASE_INSENSITIVE: Make the file-specification pattern-matching insensitive to case.
Pt_FSR_NO_ERROR_POPUP: Don't pop up an error dialog when unable to open a directory.

Library:

ph

Description:

This function creates a file-selector dialog that lets the user browse files and directories. The dialog allows the selection of a file and/or directory and fills a PtFileSelectionInfo_t structure with information about the selected item and the dialog.

Example of a File Selection dialog

An example of the dialog created by PtFileSelection().

Be sure to initialize the PtFileSelectionInfo_t structure pointed to by info before calling this function. This structure includes some pointers that must be set to NULL if you don't want to provide callback functions. For more information, see “PtFileSelectionInfo_t structure,” below.

You can specify the dimensions of the dialog by setting the info->dim field before calling this function.

This function can select directories as well as files. Enable directory selection with the Pt_FSR_SELECT_DIRS flag. Existing directories can be selected with btn1 (the Open button).

PtFileSelection() can create and delete directories and delete files. You can create new directories at any time by pressing the New button. When the PtFileSel widget has focus, these hotkeys are activated:

The Insert key creates a new directory, just like the New Directory button.
The Delete key removes the currently selected item. If you've set Pt_FSR_MULTIPLE in the flags argument, the Delete key tries to delete all the selected items. A separate delete-confirmation/delete-error dialog is presented for each selected item, and the dialog has four buttons: Cancel, Delete, Skip, and Delete All.

PtFileSelection() has its own event-processing loop.

`PtFileSelectionInfo_t` structure

The PtFileSelectionInfo_t structure includes at least the following members:

short ret

The return code; either Pt_FSDIALOG_BTN1 or Pt_FSDIALOG_BTN2.

char path[PATH_MAX + NAME_MAX + 1]

The full path of the selected item. This member isn't valid if you set Pt_FSR_MULTIPLE in the flags argument to PtFileSelection().

PtFileSelectorInfo_t *minfo

If you set Pt_FSR_MULTIPLE in the flags argument to PtFileSelection(), this member points to a PtFileSelectorInfo_t structure (see below) in which the following members are valid:

nitems — the number of selected items
multipath — an array of the full path for each selected item.

If you haven't set Pt_FSR_MULTIPLE, minfo is NULL, and the selected item's path is returned in the path member of PtFileSelectionInfo_t.

PhDim_t dim

A PhDim_t structure that defines the dimensions of the dialog when the selection was completed. You can specify the size of the dialog by setting this field before calling PtFileSelection().

PhPoint_t pos

The position of the dialog when the selection was completed.

char format[80]

The format string of the dialog when the selection was completed.

char fspec[80]

The file specification of the dialog when the selection was completed.

void *user_data

User data to pass as the data argument to the confirm_display, confirm_selection, and new_directory functions.

int (*confirm_display) ( PtWidget_t *widget, void *data, PtCallbackInfo_t *cbinfo)

A function to be called before an item is added to the file selector. If this member isn't NULL, it must point to a function.

The members of the PtCallbackInfo_t structure are used as follows:

reason — Pt_CB_FSR_DISPLAY
cbdata— a pointer to a PtFileSelectorInfo_t structure (see below).

This function should return Pt_CONTINUE or Pt_END to indicate whether or not the item should be displayed in the file selector.

int (*confirm_selection) ( PtWidget_t *widget, void *data, PtCallbackInfo_t *cbinfo)

A function that's called when the user has made a final selection of a directory item by double-clicking on an item in the file selector, pressing Enter in the Name box, or clicking on the Open button. If this member isn't NULL, it must point to a function.

The members of the PtCallbackInfo_t structure are used as follows:

reason — Pt_CB_FSR_SELECTION
reason_subtype — Pt_FSR_MULTIPLE if you've permitted multiple selections, 0 otherwise.
cbdata— a pointer to a PtFileSelectorInfo_t structure (see below).

If reason_subtype is Pt_FSR_MULTIPLE, the following members of the PtFileSelectorInfo_t structure are valid:

nitems — the number of items
items — the array items; items[n]->fullpath is the file specification of the nth selected item.

If confirm_selection returns Pt_CONTINUE, PtFileSelection() exits. If confirm_selection returns Pt_END, PtFileSelection() doesn't exit, the selector stays on the screen, and the user must choose another file or directory.

Applications can use this function to screen selections and avoid having to call PtFileSelection() repeatedly.

int (*new_directory) ( PtWidget_t *widget, void *data, PtCallbackInfo_t *cbinfo)

A function that's called whenever PtFileSelection() creates a new directory. If this member isn't NULL, it must point to a function.

The members of the PtCallbackInfo_t structure are used as follows:

reason — Pt_CB_FSR_DIRECTORY
reason_subtype — one of:

Pt_CB_FSR_DIR_AUTO

The directory was created automatically.

Pt_CB_FSR_DIR_MANUAL

The directory was created by an explicit command.
cbdata— a pointer to a PtFileSelectorInfo_t structure (see below).

The function should return Pt_CONTINUE.

PtArg_t *args

An array of PtArg_t structures that specify resource settings for the dialog's widget. For more information about the resources, see the Photon Widget Reference.

You can't use this field to set the widget's Pt_ARG_SELECTION_MODE resource. If you set Pt_FSR_MULTIPLE in the flags argument to PtFileSelection(), Pt_ARG_SELECTION_MODE is set to Pt_EXTENDED_MODE.

PtFileSelection() defines the following “pseudo resources” for PtFileSel:

Pt_ARG_FSR_LBL_DEL_ALL — the label of the Delete All button.
Pt_ARG_FSR_LBL_SKIP — the label of the Skip button.

int num_args

The number of entries in the args array.

When PtFileSelection() returns, you have to clean up the PtFileSelectionInfo_t structure because it can contain allocated members and strings. You can do the cleanup by calling:

int PtFSFreeInfo( PtFileSelectionInfo_t *fs );

If you haven't set Pt_FSR_MULTIPLE, you don't have to call PtFSFreeInfo().

`PtFileSelectorInfo_t` structure

PtFileSelection() passes the PtFileSelectorInfo_t structure as a parameter to the confirm_display, confirm_selection and new_directory functions.

Some of the members of PtFileSelectorInfo_t are valid in the confirm-selection callback, and others are valid when PtFileSelection() returns.

The PtFileSelectorInfo_t structure contains at least these members:

char *path: The full path of the directory item. This member is valid only if you haven't set Pt_FSR_MULTIPLE in the flags argument to PtFileSelection().
struct stat *statbuf: A pointer to the same buffer as lstatbuf if lstat() succeeded and the file isn't a symbolic link. If the file is a symbolic link according to lstat() (or, perhaps, if lstat() failed), stat() is called, and statbuf points to its results — or is NULL if stat() fails.
struct stat *lstatbuf: A pointer to the stat structure returned by lstat(), or NULL if lstat() failed. - when Pt_FSR_MULTIPLE is set, all selected items will be returned via three new members in the existing PtFileSelectorInfo_t structure:
int nitems: The number of selected items if you've set Pt_FSR_MULTIPLE in the flags argument to PtFileSelection().
char **multipath: The full path of each selected item if you've set Pt_FSR_MULTIPLE.
FileSelItem_t **items: An array of the selected items if you've set Pt_FSR_MULTIPLE.

Returns:

0: Success.
-1: An error occurred.

Examples:

/*************************************
 * fsel.c
 *
 * Sample program that illustrates usage of
 * the PtFileSelection() convenience function.
 *
 * Compile as follows:
 *    $ qcc -lph -o fsel fsel.c
 * 
 * Run as follows:
 *    $ ./fsel
 * 
 **************************************/

#include <stdio.h>
#include <stdlib.h>
#include <Ph.h>
#include <Pt.h>

int main(int argc, char **argv )
{
   PtFileSelectionInfo_t info;
   PtArg_t args[1];
   int k;
   
   /* Initialize the widget library and connect to Photon. */
   PtInit( NULL );
   
   /* Initialize the file-select info structure */
   memset( &info, 0x0, sizeof(PtFileSelectionInfo_t) );

   /* Change the name-column label of the PtFileSel widget
      in the filesel dialog from the default "Name" to "Nom" */

   PtSetArg( args, Pt_ARG_FS_LBL_NAME, "Nom:", 0 );
   info.args = args;
   info.num_args = 1;

   /* Invoke the convenience function. */
   k = PtFileSelection( NULL, /* parent */
               NULL, /* pos */
               "PtFileSelection Example", /* title */
               "~",  /*  root_dir, tilde is the home directory
                         specified by $HOME */
               NULL, /*  file_spec filter */
               NULL, /*  label of btn1, the Open button,
                         default is "Open" */
               NULL, /*  label of btn2, the Cancel button,
                         default is "Cancel" */
               NULL, /*  Pt_ARG_FS_FORMAT resource of the
                         PtFileSel widget, default is "nsd" */
               &info, /* PtFileSelectionInfo_t *info
                             structure, must be specified */
               Pt_FSR_CONFIRM_EXISTING | 
               Pt_FSR_SHOW_HIDDEN | 
               Pt_FSR_NO_FCHECK  /* PtFileSelection flags */
               );
   if ( k ) {
      fprintf( stderr, "\nPtFileSelection failed." );
      PtExit( -1 );
   }
   
   if ( info.ret == Pt_FSDIALOG_BTN1 )
     fprintf( stderr,
       "\nOpen button was pressed. The selected file is:\n\t%s\n",
       info.path );
   else
     fprintf( stderr, "\nCancel button was pressed.\n" );
   
   PtExit( 0 );
   return EXIT_SUCCESS;
}

Classification:

Photon

Safety:
Interrupt handler	No
Signal handler	No
Thread	No