NAME

hwtk::savefileentry - Pop up a dialog box for the user to select a file to save.

 

DESCRIPTION

A hwtk::savefileentry widget displays a one-line text string and allows that string to be edited by the user. The value of the string may be linked to a Tcl variable with the -textvariable option. Entry widgets support horizontal scrolling with the standard -xscrollcommand option and xview widget command. Combined with this entry widget is a browse button which when selected pops up a dialog box for the user to select a location and file name to save to.

 

CLASS DIAGRAM

SYNOPSIS

hwtk::savefileentry - pathName ?option value? ...

 

STANDARD OPTIONS

-clientdata, clientData, ClientData

-help, help, Text

-helpcommand, helpcommand, Command

-state, state, State

-textvariable, textVariable, Variable

-width, width, Width

 

WIDGET-SPECIFIC OPTIONS

 

Command-Line Name: -buttonpos

Database Name: buttonpos

Database Class: Buttonpos

The position of the file browse button in relation to the file entry. Valid values are e, w, left and right.

 

Command-Line Name: -command

Database Name: command

Database Class: Command

A script to evaluate when the widget is invoked.

 

Command-Line Name: -defaultextension

Database Name: defaultextension

Database Class: Defaultextension

Specifies a string that will be appended to the filename if the user enters a filename without an extension. The default value is the empty string, which means no extension will be appended to the filename in any case. This option is ignored on Mac OS X, which does not require extensions to filenames, and the UNIX implementation guesses reasonable values for this from the -filetypes option when this is not supplied.

 

Command-Line Name: -filetypes

Database Name: filetypes

Database Class: Filetypes

If a File types listbox exists in the file dialog on the particular platform, this option gives the filetypes in this listbox. When the user choose a filetype in the listbox, only the files of that type are listed. If this option is unspecified, or if it is set to the empty list, or if the File types listbox is not supported by the particular platform then all files are listed regardless of their types.

 

Command-Line Name: -initialdir

Database Name: initialdir

Database Class: Initialdir

Specifies that the directories in directory should be displayed when the dialog pops up. If this parameter is not specified, then the directories in the current working directory are displayed. If the parameter specifies a relative path, the return value will convert the relative path to an absolute path.

 

Command-Line Name: -initialfile

Database Name: initialfile

Database Class: Initialfile

Specifies a filename to be displayed in the dialog when it pops up.

 

Command-Line Name: -invalidcommand

Database Name: invalidCommand

Database Class: InvalidCommand

A script template to evaluate whenever the validateCommand returns 0. See Validation Options for more information.

 

Command-Line Name: -justify

Database Name: justify

Database Class: Justify

Specifies how the text is aligned within the entry widget. One of left, center, or right.

 

Command-Line Name: -parent

Database Name: parent

Database Class: Parent

Makes window the logical parent of the dialog. The dialog is displayed on top of its parent window. On Mac OS X, this turns the file dialog into a sheet attached to the parent window.

 

Command-Line Name: -title

Database Name: title

Database Class: Title

Specifies a string to display as the title of the dialog box. If this option is not specified, then a default title is displayed.

 

Command-Line Name: -typevariable

Database Name: typevariable

Database Class: Typevariable

The global variable variableName is used to preselect which filter is used from filterList when the dialog box is opened and is updated when the dialog box is closed, to the last selected filter. The variable is read once at the beginning to select the appropriate filter. If the variable does not exist, or its value does not match any filter typename, or is empty ({}), the dialog box will revert to the default behavior of selecting the first filter in the list. If the dialog is canceled, the variable is not modified.

 

Command-Line Name: -validate

Database Name: validate

Database Class: Validate

Specifies the mode in which validation should operate: none, focus, focusin, focusout, key, or all. Default is none, meaning that validation is disabled. See Validation Options for more information.

 

Command-Line Name: -validatecommand

Database Name: validateCommand

Database Class: ValidateCommand

A script template to evaluate whenever validation is triggered. If set to the empty string (the default), validation is disabled. The script must return a boolean value. See Validation Options for more information.

 

 

WIDGET COMMAND

In addition to the standard configure, cget, identify, instate, and state commands, savefileentry support the following additional widget commands:

 

pathName bbox index

Returns a list of four numbers describing the bounding box of the character given by index. The first two elements of the list give the x and y coordinates of the upper-left corner of the screen area covered by the character (in pixels relative to the widget) and the last two elements give the width and height of the character, in pixels. The bounding box may refer to a region outside the visible area of the window.

 

pathName delete first ?last?

Delete one or more elements of the entry. First is the index of the first character to delete, and last is the index of the character just after the last one to delete. If last isn’t specified it defaults to first+1, i.e. a single character is deleted. This command returns the empty string.

 

pathName get

Returns the entry’s string.

 

pathName icursor index

Arrange for the insert cursor to be displayed just before the character given by index. Returns the empty string.

 

pathName index string

Arrange for the insert cursor to be displayed just before the character given by index. Returns the empty string.

 

pathName insert index string

Insert string just before the character indicated by index. Returns the empty string.

 

pathName selection option arg

This command is used to adjust the selection within an entry. It has several forms, depending on option:

pathName selection clear

Clear the selection if it is currently in this widget. If the selection isn’t in this widget then the command has no effect. Returns the empty string.

pathName selection present

Returns 1 if there is are characters selected in the entry, 0 if nothing is selected.

pathName selection range start end

Sets the selection to include the characters starting with the one indexed by start and ending with the one just before end. If end refers to the same character as start or an earlier one, then the entry’s selection is cleared.

 

pathName set str

Sets the entry’s value to str.

 

pathName xview args

This command is used to query and change the horizontal position of the text in the widget’s window. It can take any of the following forms:

pathName xview

Returns a list containing two elements. Each element is a real fraction between 0 and 1; together they describe the horizontal span that is visible in the window. For example, if the first element is .2 and the second element is .6, 20% of the entry’s text is offscreen to the left, the middle 40% is visible in the window, and 40% of the text is offscreen to the right. These are the same values passed to scrollbars via the -xscrollcommand option.

pathName xview index

Adjusts the view in the window so that the character given by index is displayed at the left edge of the window.

pathName xview moveto fraction

Adjusts the view in the window so that the character fraction of the way through the text appears at the left edge of the window. Fraction must be a fraction between 0 and 1.

pathName xview scroll number what

This command shifts the view in the window left or right according to number and what. Number must be an integer. What must be either units or pages. If what is units, the view adjusts left or right by number average width characters on the display; if it is pages then the view adjusts by number screenfuls. If number is negative then characters farther to the left become visible; if it is positive then characters farther to the right become visible.

 

EXAMPLES

 

#::hwtk::savefileentry

 

::hwtk::dialog .d -title "::hwtk::savefileentry"

set f [.d recess]

 

hwtk::label $f.l1 -text "Enabled"

hwtk::savefileentry $f.e1

 

hwtk::label $f.l2 -text "Disabled"

hwtk::savefileentry $f.e2 -state "disabled"

 

grid columnconfigure $f 1 -weight 1

 

grid $f.l1 $f.e1 -sticky w;

grid $f.l2 $f.e2 -sticky w;

 

.d post