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 );

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.

This function has its own event-processing loop.

The arguments are as follows:

parent

The dialog's parent, which can be NULL (see below).

pos

The dialog's position, which can be NULL (see below).

title

The dialog's title. If NULL, the string File Selector is used.

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.

file_spec

The file specification to look for. The default is * if this parameter 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 PtFileSel widget. It determines what information is displayed and in what order. If you don't want the divider shown, pass NULL as this parameter, and only the filenames are be displayed. See the description of PtFileSel 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. 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.
• PhDim_t dim-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 spec of the dialog when the selection was completed.

flags

Flags for the dialog. The default is to show all information, and corresponds to a value of 0. The possible values are:

• Pt_FSDIALOG_NO_FCHECK-don't check files for validity. This is good for a Save dialog.
• Pt_FSDIALOG_NO_FSPEC-don't display the File Spec widget.
• Pt_FSDIALOG_NO_UP_BUTTON-disables the display of the Up Directory button.
• Pt_FSDIALOG_SHOW_HIDDEN- shown hidden files.

The PtFileSelection() function creates a dialog to simplify file and directory selection:

An example of the dialog created by PtFileSelection().

The dialog is positioned according to the pos parameter: if NULL, the dialog is centered on the screen; if parent is NULL, the dialog is placed at the absolute coordinates of pos; otherwise it's placed at the relative offset of pos within parent.

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

The dialog consists of:

Path text field

You can type a directory name to open or a full path to a file. It behaves in the following manner:

• If you enter a directory that exists, that directory is displayed.
• If you enter a path to a file that exists and you didn't set the Pt_FSDIALOG_NO_FCHECK flag, the file is automatically selected.
• If you enter a path to a file that doesn't exist and you didn't set the Pt_FSDIALOG_NO_FCHECK flag, the closest directory is selected and the Filename text field is cleared.
• If you enter a path to a file, the directory portion exists, and you've set the Pt_FSDIALOG_NO_FCHECK flag, the file is shown in the File text widget.
• If you enter a path to a file, the directory portion doesn't exist, and you've set the Pt_FSDIALOG_NO_FCHECK flag, the closest directory is selected and the Filename text field is cleared.
• Just like in the shell, a tilde (~) can be used to indicate a home directory.

Up Directory button

Clicking on this moves you up one directory level.

PtFileSel widget

Displays files and directories in single level mode.

Filename text field

Displays the selected file and allows you to enter your own. It behaves in the following manner:

• If you enter a file that exists in the current directory and you didn't set the Pt_FSDIALOG_NO_FCHECK flag, the file is automatically selected.
• If you enter a file that doesn't exist in the current directory and you didn't set the Pt_FSDIALOG_NO_FCHECK flag, the file widget is cleared.
• If you enter a file that does or doesn't exist in the current directory and you've set the Pt_FSDIALOG_NO_FCHECK flag, the file is automatically selected.
• If you type .., you'll move up one directory level

Pattern text field

Only the files whose names match this pattern are displayed. This pattern doesn't apply to directories.

Button 1

Used to select a file or directory. When this button is clicked, the dialog is destroyed and a PtFileSelectionInfo_t structure is filled in: ret is Pt_FSDIALOG_BTN1 and path contains the full path of the selected item.

Button 2

Used to cancel the selection. When this button is clicked, the dialog is destroyed and a PtFileSelectionInfo_t structure is filled in: ret is Pt_FSDIALOG_BTN2 and path contains nothing.

Returns:

0

Success.

-1

An error occurred.

Examples:

#include <Pt.h>
#include <photon/PtFileSel.h>
#include <sys/stat.h>
#include <string.h>
#include <stdio.h>

// global widget pointers
PtWidget_t *window, *sel_btn, *quit_btn, 
           *label, *sel_label;
// info structure for the dialog
PtFileSelectionInfo_t in;
// default position for the dialog
PhPoint_t pos = {100, 100};
// format string to be reused
char format[80];

int
make_fs( PtWidget_t *widget, 
         struct fs_dialog_modal *user,
         PtCallbackInfo_t *info)
{
    PtArg_t args[1];
    int err;

    // make the file selection dialog
    err = PtFileSelection(window, &pos, 
            NULL, "/", NULL, "&Select", 
            "&Done", format, &in, 
            Pt_FSDIALOG_NO_FCHECK);

    // save the position and format for making a future dialog
    pos.x = in.pos.x;
    pos.y = in.pos.y;
    strcpy(format, in.format);

    PtSetArg(&args[0], Pt_ARG_TEXT_STRING, 
             "The Selected file was:", 0);
    PtSetResources(label, 1, args);

    PtSetArg(&args[0], Pt_ARG_TEXT_STRING, in.path, 0);
    PtSetResources(sel_label, 1, args);

    return(Pt_CONTINUE);
}

void
quit( PtWidget_t *widget,
      struct fs_dialog_modal *user,
      PtCallbackInfo_t *info)
{
    exit (EXIT_SUCCESS);
}

main()
{
    PtArg_t     args[10];
    PhArea_t area;
    PhDim_t dim = { 300, 200 };

    in.dim.w = 0;
    in.dim.h = 0;

    // setup a default format string
    strcpy(format, "nsd");

    // make the main window
    PtSetArg( &args[0], Pt_ARG_WINDOW_TITLE, 
              "PtFileSelector Demo", 0 );
    PtSetArg( &args[1], Pt_ARG_DIM, &dim, 0 );
    window = PtAppInit( NULL, NULL, NULL, 2, args );

    // make a label 
    area.pos.x = 20;
    area.pos.y = 30;
    PtSetArg( &args[0], Pt_ARG_POS, &area.pos, 0 );
    PtSetArg( &args[1], Pt_ARG_TEXT_FONT, "helv12b", 0 );
    PtSetArg( &args[2], Pt_ARG_TEXT_STRING, 
              "There is no selected file", 0);
    label = PtCreateWidget( PtLabel, window, 3, args );

    // make a second label 
    area.pos.x = 30;
    area.pos.y = 60;
    PtSetArg( &args[0], Pt_ARG_POS, &area.pos, 0 );
    PtSetArg( &args[1], Pt_ARG_TEXT_FONT, "helv12b", 0 );
    sel_label = PtCreateWidget( PtLabel, window, 2, args );

    // make a button for selecting files
    area.size.w = 80;
    area.size.h = 20;
    area.pos.x = 120;
    area.pos.y = 170;
    PtSetArg( &args[0], Pt_ARG_AREA, &area, 0 );
    PtSetArg( &args[1], Pt_ARG_TEXT_STRING, "Select File", 0);
    sel_btn = PtCreateWidget( PtButton, window, 2, args );
    PtAddCallback(sel_btn, Pt_CB_ACTIVATE, &make_fs, NULL);

    // make a button for quitting
    area.size.w = 80;
    area.size.h = 20;
    area.pos.x = 210;
    area.pos.y = 170;
    PtSetArg( &args[0], Pt_ARG_AREA, &area, 0 );
    PtSetArg( &args[1], Pt_ARG_TEXT_STRING, "Quit", 0);
    quit_btn = PtCreateWidget( PtButton, window, 2, args );
    PtAddCallback(quit_btn, Pt_CB_ACTIVATE, &quit, NULL);

    PtRealizeWidget( window );

    PtMainLoop();
}

Classification:

Photon