FileListbox Control

A FILELISTBOX (file selection list box) will allow the user to select a file from any directory or drive on the system. The value of "variable" will be set to the selected filename; if you need to know what directory the file is in, use the DirGet function after the Dialog function exits.

Normally, when a dialog box opens, the FILELISTBOX displays files matching a file mask of "*.*" (i.e., all files). You can change this by assigning a different file mask value to the string variable before calling the Dialog function.

Normally, if a dialog contains a FILELISTBOX, you must select a file from the list box before you can exit the dialog. You can change this behavior by placing the statement IntControl (4, 0, 0, 0, 0) anywhere in your WIL program prior to the Dialog statement.

In combination with the FILELISTBOX, you can include an EDITBOX control which has the same variable name as the file list box. If you do, the user can type a file mask into the edit box (e.g., "*.TXT"), which will cause theFILELISTBOX to be redrawn to display only those files which match the specified file mask.

Also in combination with the FILELISTBOX, you can include a VARYTEXT control which has the same variable name as the FILELISTBOX. If you do, this control will show the name of the directory currently displayed in the FILELISTBOX. Text should be DEFAULT.

Note: You can have only one file list box in a dialog.

Return Value:

The FILELISTBOX control will return the selected filename in the variable you supply as the Variable attribute in the controls definition. If you need to know what directory the file is in, use the DirGet function after the Dialog function exits.

Control Definition:

<dlg-variable>nn =`x, y, width, height, type, control-name, variable, pre-selected item, value, tab-order, style, font, textcolor, backgroundcolor`

For Example:

MyDialog003=`005,005,108,058,FILELISTBOX,"FileListBox_1",flVariable1,"Pick Me",DEFAULT,30,DEFAULT,DEFAULT,DEFAULT,DEFAULT`

Attribute

Value

Meaning

dlg-variable

MyDialog

The name of the dialog box.

003

The ordinal position of the control in the dialog box (starting with 1).

005

The horizontal coordinate of the upper left corner of the control in Dialog Units.

005

The vertical coordinate of the upper left corner of the control in Dialog Units.

width

108

The width of the control in Dialog Units

height

058

The height of the control in Dialog Units.

type

FILELISTBOX

The type of control.

control-name

"FileListBox_1"

The name used to identify the control in a user defined callback procedure. The name cannot be more than 30 characters in length and MUST be unique. ( This attribute can only be used with 6.2 or later dialog formats. )

variable

flVariable1

The name of the variable affected by the control. Normally, when a dialog box opens, file list boxes display files matching a filemask of "*.*" (i.e., all files). You can change this by assigning a different filemask value to the string variable before calling the Dialog function.

pre-selected item

"Pick Me"

Indicate which item in a list or range is the default selected item for the control. In order for the Pre-selected Item to work properly it must be one of the items listed in the controls variable.

value

DEFAULT

Not applicable to this control.

tab-order

Allows you to specify a control's tab order independently of a control's position or name in the dialog template. Tab-order controls the order in which controls are accessed when the keyboard is used to navigate the dialog. It also influences which control is on top when controls have overlapping positions in the dialog. It can be any positive integer, but each control should have a unique number.

When you navigate through a dialog using the tab key, lower number controls will be given the keyboard focus before higher controls. Likewise, low-numbered overlapping controls will appear on top of higher numbered controls. If you specify the DEFAULT keyword for this attribute or if you give two controls the same tab order, a tab order will be arbitrarily assigned to the control.

Note: The dialog function, under certain circumstances, may change the tab order you specify. The GROUPBOX controls tab order may be adjusted so that it is smaller than any of the controls it contains. In addition, the tab order of the controls inside the GROUPBOX may be adjusted so that they are consecutive.

style

DEFAULT

Allows you to control the initial appearance and behavior of your control. Numbers represent each style and they can be combined, using the bit-wise OR (|) operator, to set multiple styles. The following table lists the style numbers, their meanings, and the controls that they have an effect on.

Style	Meaning
@csInvisible (1)	Control is invisible
@csDisabled (2)	Control has disabled appearance and does not accept any user input, it would otherwise accept input.
@csNoAdjust (256)	Turns off automatic height adjustment feature of item and file box controls. Normally, these controls adjust their height so that they do not display partial items. This style turns off this feature.

Note: Specifying 0 for this attribute is equivalent to using the DEFAULT keyword and means that the control will exhibit default behavior.

font

DEFAULT

The font used to display a control's text. The font description should be delimited by double quote (") marks unless the attribute is set to DEFAULT. If this attribute is set to DEFAULT, the font specified as the value of the main dialog font will be used. If the main dialog font is set to DEFAULT, the system font is used. You do not need to provide any value for this attribute unless you are also specifying text or background color. For details see the Dialog Fonts topic. WARNING: If a font is selected that doesn't exist on the user's system, a substitution will be made. We recommend using commonly available fonts.

textcolor

DEFAULT

The color of text associated with a control. Color is specified by three vertical bar (|) delimited numbers ranging from 0 to 255 or a single hexadecimal number preceded by the letter 'h'. The numbers represent one of the RGB colors: red, green or blue, in that order. The complete color specification must be surrounded by double quotes (") unless the DEFAULT key word is used. If this attribute is set to DEFAULT, the color listed in the main dialog's textcolor will be used. If a color is not specified for the dialog, the system text color will be used.

backgroundcolor

DEFAULT

Used to change the color displayed behind a controls text. Color is specified by three vertical bar (|) delimited numbers ranging from 0 to 255 or a single hexadecimal number preceded by the letter 'h'. The numbers represent one of the RGB colors (red, green or blue, in that order). The complete color specification must be surrounded by double quotes (") unless the DEFAULT keyword is used. If no color is specified or the DEFAULT keyword is used the system background color will be used.

Event Options

Use the DialogProcOptions function to control when your User-Defined-Callback procedure is called by its associated dialog. You can also use it to control your dialog's behavior, while your procedure is executing. You usually establish callback events during the first call to the procedure i.e., event 0, but this can be done during any call.

Event-Option-Code Values	Meaning
@deFlSelect (6)	FILELISTBOX File Selected: User has selected a file in a FILELISTBOX control.

Dialog Callback Procedure Function Options

DialogControlGet function returns text and state information associated with a control.

Request	Meaning
@dcContents (5)	Tab delimited list of all the items currently in the control, or a file wildcard mask if a FILELISTBOX is specified (i.e., "c:\temp\.").
@dcSelect (6)	Tab delimited list of the currently selected item(s) in the control. An empty string, if no item is selected.
@dcScroll (10)	One based index of the first currently visible item in the list.
@dcBackColor (11)	Background color specified by three vertical bar (\|) delimited numbers ranging from 0 to 255. If the control is using the system default color, the string "DEFAULT" is returned.
@dcTextColor (13)	Text color specified by three vertical bar (\|) delimited numbers ranging from 0 to 255. If the control is using the dialog's default text color, the string "DEFAULT" is returned.
@dcPosition (17)	Space delimited list of a control's position and size in dialog units relative to the dialog's client area. The first two numbers are the horizontal and vertical location of the upper-left corner of the control while the third and fourth numbers are the width and height of the control.
@dcMenuNames (18)	Tab delimited list of menu item names associated with the control, menu item or menu bar.
@dchWnd (19)	Window handle of a dialog control.

DialogControlSet function changes the text or appearance of a control.

Request	Meaning
@dcContents (5)	File mask to change or modify the default of ".".
@dcSelect (6)	Tab delimited list one or more item you wish to be highlighted as selected. Use an empty string to cancel an existing selection. (Multiple item selection only applies to ITEMBOXs when multi-select is turned on. See IntControl (33, p1, 0, 0, 0) function documentation for information on multi-select ).
@dcScroll (10)	One based index of the list item to be scrolled to the top of the control's viewing area. If n is greater than the number of items in the list or less than 1, the list will be scrolled so that the last items in the list are in the control's viewing area.
@dcBackColor (11)	Background color. The color is specified by three vertical bar (\|) delimited numbers ranging from 0 to 255 or a single hexadecimal number preceded by the letter 'h'. To give the control the system default background color, use an empty string ""or the "DEFAULT "key string for this parameter.
@dcTextColor (13)	Text color. The color is specified by three vertical bar (\|) delimited numbers ranging from 0 to 255 or a single hexadecimal number preceded by the letter 'h'. To give the control the dialog's default text color, use an empty string ""or the "DEFAULT "key string for this parameter.
@dcAddItem (14)	Text added as an item to the list displayed by the control. If the items in the control are sorted, the new item will be inserted in sort order.
@dcRemItem (15)	Text of item to be removed from the list displayed by the control. The text need not match the list item's case but must otherwise be an exact match.
@dcPosition (17)	Space delimited list of a control's position and size in dialog units relative to the dialog's client area. The first two numbers are the horizontal and vertical location of the upper-left corner of the control while the third and fourth numbers are the width and height of the control.

DialogControlState function changes a control’s style or gives control input focus.

Style	Meaning
@csInvisible (1)	Control is invisible
@csDisabled (2)	Control has disabled appearance and does not accept any user input, it would otherwise accept input.
@csNoAdjust (256)	Turns off automatic height adjustment feature of item and file box controls. Normally, these controls adjust their height so that they do not display partial items. This style turns off this feature.