Warning: main(/www/www/htdocs/style/globals.php) [function.main]: failed to open stream: No such file or directory in /www/www/docs/6.4.1/photon/lib_ref/pt/ptfileselection.html on line 1
Warning: main() [function.include]: Failed opening '/www/www/htdocs/style/globals.php' for inclusion (include_path='.:/www/www/common:/www/www/php/lib/php') in /www/www/docs/6.4.1/photon/lib_ref/pt/ptfileselection.html on line 1
Warning: main(/www/www/htdocs/style/header.php) [function.main]: failed to open stream: No such file or directory in /www/www/docs/6.4.1/photon/lib_ref/pt/ptfileselection.html on line 8
Warning: main() [function.include]: Failed opening '/www/www/htdocs/style/header.php' for inclusion (include_path='.:/www/www/common:/www/www/php/lib/php') in /www/www/docs/6.4.1/photon/lib_ref/pt/ptfileselection.html on line 8
Create a file-selector dialog
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 );
- 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 PtFileSel 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
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.
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.
ph
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.
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.
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:
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
PtFileSel
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(). |
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.
- 0
- Success.
- -1
- An error occurred.
/*************************************
* 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;
}
Photon
Safety: | |
Interrupt handler |
No |
Signal handler |
No |
Thread |
No |
PhDim_t,
PtArg_t
PtFileSel
in the Photon Widget Reference
“Dialog modules”
in the Working with Modules chapter of the
Photon Programmer's Guide
Warning: main(/www/www/htdocs/style/footer.php) [function.main]: failed to open stream: No such file or directory in /www/www/docs/6.4.1/photon/lib_ref/pt/ptfileselection.html on line 850
Warning: main() [function.include]: Failed opening '/www/www/htdocs/style/footer.php' for inclusion (include_path='.:/www/www/common:/www/www/php/lib/php') in /www/www/docs/6.4.1/photon/lib_ref/pt/ptfileselection.html on line 850