Volume 7A: XView Programming Manual

D.5 Modifying the Display List

There are several attributes that allow the client to modify the display of files in a file

chooser. A file chooser’s default values comply with the OPEN LOOK Application File

Choosing Specification. Note that the File Choosing Specification requires the client to pro-

vide an appropriate human interface to revert to the default behavior if the client changes the

default behavior (for example, the application should provide a toggle that turns off the dis-

play of dot files if the application displays dot files.)

D.5.1 Dot Files

Since most dot files are created by applications and not directly by the user, the file chooser

does not show dot files by default (also, user testing has shown that dot files often confuse

end-users). If an application needs to show dot files in the file list display, the attribute

FILE_CHOOSER_SHOW_DOT_FILES toggles their display.

D.5.2 Abbreviated View

Some applications may only need to show those files that are relevant to the application. In

this case, files that are not openable may be removed from the file list, rather than being

displayed as grayed out items. This functionality may be turned on by setting the

FILE_CHOOSER_ABBREV_VIEW

attribute to TRUE. Warning: use of this attribute is recom-

mended only for applications that expect very technical users who will understand that files

not being displayed is not a problem.

D.6 File Chooser Customization

The application has the option of adding permanent application-specific entries into the file

chooser Go To menu. The attribute FILE_CHOOSER_APP_DIR sets the values for these

entries.

Some applications may need to do use a non-standard configuration with the Go To menu.

This is achieved by creating a custom History_list object and attaching it to a file

chooser with the

FILE_CHOOSER_HISTORY_LIST attribute. Once installed, the

FILE_CHOOSER package will add “Recent Entries” to the installed list as the user navigates

the file system.

Other modifications for the Go To history list and menu can be accomplished using the HIS-

TORY_LIST

and HISTORY_MENU attributes. The last section of this chapter list the HISTORY

attributes. Refer to the XView Reference Manual for additional information on these attri-

butes.

Version 3.2 and

the File Chooser

Version 3.2 and the File Chooser 687

The Save and Save As FILE_CHOOSERs can include a default name in the field for the File

type in. You specify this default name using the FILE_CHOOSER_DOC_NAME attribute. For a

Save file chooser, the default document name should be Untitled1. For a Save As File

Chooser, the default document name should be “current document”.1.

In some circumstances, the application may wish to save more than one file to a directory.

The file chooser Save dialog does not provide for this very well, so there is an option to gray

out the Save typein while leaving the Save button available to the user. This is toggled with

the FILE_CHOOSER_SAVE_TO_DIR attribute.

Since the file chooser has elements that are public it is possible to get handles to the objects

that make up the file chooser, either by the FILE_CHOOSER_CHILD interface or by

PANEL_EACH_ITEM, etc. For example, the file chooser’s FILE_LIST object is available in

this manner. Keep in mind that values that are not gotten or set via the parent

FILE_CHOOSER API are not guaranteed to be compatible across releases of the XView

toolkit.

The attribute FILE_CHOOSER_AUTO_UPDATE modifies the action of a FILE_CHOOSER. This

attribute tells the FILE_CHOOSER to re-read its current directory only when

FILE_CHOOSER_UPDATE is explicitly called, or when the user performs some action to read

the directory.

D.7 Customizing the File Chooser Dialog

The OPEN LOOK Application File Choosing Specification defines two methods for

OPEN LOOK-Compliant file chooser customization. The first, and simplest, is to modify the

Open dialog and define a custom File Chooser, such as an “Import” or an “Include” File

Chooser. Using the attributes supplied for adding a custom button, this change is not difficult.

For example,

File_chooser open_chsr;

open_chsr = (File_chooser) xv_create(owner,

FILE_CHOOSER_OPEN_DIALOG,

FILE_CHOOSER_CUSTOMIZE_OPEN,

"Import",

"Select a file or folder and click Import",

FILE_CHOOSER_SELECT_FILES,

NULL);

The first argument supplied to the attribute FILE_CHOOSER_CUSTOMIZE_OPEN is the label for

the new custom button. The second argument is the line of text that is placed above the Scrol-

ling List. The third argument is an enum value that represents whether this custom operation

can deal with files (that is, if the item can only use files this argument is set to

FILE_CHOOSER_SELECT_FILES, otherwise, if both files and directories are valid it is set to

FILE_CHOOSER_SELECT_ALL).

The second way to customize the XView file chooser is to add custom controls to the file

chooser panel. Implementing this is a multi-step process.

688 Version 3.2 and the File Chooser

The OPEN LOOK Application File Choosing Specification mandates that custom controls be

placed under the Scrolling List (and below the Save typein), but above the buttons at the bot-

tom of the dialog. To implement this, the FILE_CHOOSER package reserves an area, called

the extension rectangle, in part of the dialog space. By default, the extension rectangle has a

height of 0 pixels; the client make may this area a specific size using the

FILE_CHOOSER_EXTEN_HEIGHT attribute.

The FILE_CHOOSER package leaves much of the responsibility for layout and sizing of cus-

tom controls in the hands of the client. The client has the responsibility of positioning cus-

tom controls within the extention rectangle area during layout and resizing. The callback

installed with the attribute FILE_CHOOSER_EXTEN_FUNC handles resizing and layout.

Other responsibilities of the client when adding custom controls include adjusting the default

and minimum sizes for the Frame.

Example D-2 illustrates adding an extension item to a file chooser.

Example D-2. An extension item program

File_chooser fc;

Panel panel;

Panel_item item;

int item_width;

int item_height;

int frame_width;

int frame_height;

panel = xv_get(fc, FRAME_CMD_PANEL);

item = xv_create(panel, PANEL_CHOICE,

PANEL_LABEL_STRING, "Hidden Files:",

PANEL_CHOICE_STRINGS, "Hide", "Show", NULL,

PANEL_NOTIFY_PROC, my_show_dot_files_proc,

NULL);

item_width = (int) xv_get(item, XV_WIDTH);

item_height = (int) xv_get(item, XV_HEIGHT);

/*

* Adjust Frame default size to make room for the extension item.

*/

frame_width = (int) xv_get(fc, XV_WIDTH);

frame_height = (int) xv_get(fc, XV_HEIGHT);

xv_set(fc,

XV_WIDTH, MAX(frame_width, (item_width + xv_cols(panel, 4))),

XV_HEIGHT, frame_height + item_height,

NULL);

/*

* Adjust Frame Min Size. provide for at least 2

* columns on either side of the extension item.

*/

xv_get(fc, FRAME_MIN_SIZE, &frame_width, &frame_height);

xv_set(fc,

Version 3.2 and

the File Chooser

Version 3.2 and the File Chooser 689

Example D-2. An extension item program (continued)

FRAME_MIN_SIZE, MAX( frame_width, (item_width + xv_cols(panel, 4))),

frame_height + item_height,

NULL);

/* Tell file chooser to reserve layout space for it */

xv_set(fc,

FILE_CHOOSER_EXTEN_HEIGHT, item_height,

FILE_CHOOSER_EXTEN_FUNC, my_exten_func,

XV_KEY_DATA, EXTEN_ITEM_KEY, item,

NULL);

/* [.................] */

static int

my_exten_func( fc, frame_rect, exten_rect,

left_edge, right_edge, max_height )

File_chooser fc;

Rect *frame_rect;

Rect *exten_rect;

int left_edge;

int right_edge;

int max_height;

{

Panel_item item = (Panel_item) xv_get(fc,

XV_KEY_DATA, EXTEN_ITEM_KEY);

int item_width;

item_width = (int) xv_get(item, XV_WIDTH);

/*

* show item centered in frame.

*/

xv_set(item,

XV_X, (frame_rect->r_width - item_width) / 2,

XV_Y, exten_rect->r_top,

PANEL_PAINT, PANEL_NONE,

NULL);

return -1; /* (-1) means exten height didn’t change */

}

D.7.1 File Chooser Components

Internally, the file chooser is uses three high-level interfaces: the FILE_LIST package, the

PATH_NAME packge, and the HISTORY package. The FILE_LIST package is a subclass of

PANEL_LIST; it handles all of the navigation and display of the UNIX File System. The

PATH_NAME package is a subclass of PANEL_TEXT; it handles shell variable and tilde expan-

sion. The HISTORY package implements a shareable command history through the XView

690 Version 3.2 and the File Chooser

Menu and Menu_item packages (the Go To menus in the file chooser use this). If your file

manipulation needs do not fall within the scope of the OPEN LOOK Application File Choos-

ing Specification, you have the option of designing your own dialog with the same compo-

nents the File uses. Since the FILE_CHOOSER package implements a particular look and feel,

which may not suffice for all application needs, the component parts are made available.

[Generic] -> [Panel_item] -> [Panel_list_item] -> [File_list]

[Generic] -> [Panel_item] -> [Panel_text_item] -> [Path_name]

[Generic] -> [History_menu]

[Generic] -> [History_list]

D.8 Version 3.2 Additions

This section lists additional changes for available with XView Version 3.2 and new releases.

D.8.1 New Panel List Attributes for Version 3.2

Version 3.2 of XView offers a new and improved method for adding entries to a

PANEL_LIST. Version 3.2 offers the following new attributes for panel lists:

PANEL_LIST_INACTIVE

PANEL_LIST_DELETE_INACTIVE_ROWS

PANEL_LIST_DO_DBL_CLICK

PANEL_LIST_MASK_GLYPH

PANEL_LIST_MASK_GLYPHS

PANEL_LIST_ROW_VALUES

PANEL_LIST_EXTENSION_DATA

PANEL_LIST_EXTENSION_DATAS

D.8.1.1 Adding new list entries

The attribute

PANEL_LIST_ROW_VALUES

offers an improved performance method of get-

ting/setting row values in a PANEL_LIST. This attribute takes the row number, a pointer to a

Panel_list_row_values array, and a count of how many rows in the array. The enum

Panel_list_row_values is defined as shown below:

typedef struct {

char * string;

Server_image glyph;

Server_image mask_glyph;

Xv_font font;

Xv_opaque client_data;

Xv_opaque extension_data;

unsigned inactive : 1;

unsigned selected : 1;

} Panel_list_row_values;

Version 3.2 and

the File Chooser

Version 3.2 and the File Chooser 691