hwtk::listbox

Create and manipulate listbox widgets.

Format

hwtk::listbox - pathName ?option value? …

Description

Creates and manipulates a listbox widget.

Standard Options

-clientdata
Database name: clientData
Database class: ClientData
Acts as a data storage for a widgets. User can store any data and this will not have any effect on widget property.
-height
Database name: height
Database class: Height
If specified, the widget’s requested height in pixels.
-helpcommand
Database name: helpcommand
Database class: Command
Dynamic help which calls an assigned -helpcommand when the user moves the mouse on the widget. The text which is returned by the -helpcommand will be in turn be displayed on the tooltip.
-relief
Database name: relief
Database class: Relief
Specifies the 3D effect desired for the widget. Acceptable values are raised, sunken, flat, ridge, solid, and groove. The value indicates how the interior of the widget should appear relative to its exterior; for example, raised means the interior of the widget should appear to protrude from the screen, relative to the exterior of the widget.
-width
Database name: width
Database class: Width
Specifies the width of a widget.

Widget Specific Options

-backgroundimage
Database name: backgroundImage
Database class: BackgroundImage
Specifies the name of an image to draw as the list background.
-closeeditor
Database name: closeEditor
Database class: CloseEditor
Boolean option when set to true, the editor unposts upon successful set value. Default is set to false.
-headermenu
Database name: headermenu
Database class: Menu
Column specific header context menu.
-headertext
Database name: headertext
Database class: Text
Specifies a text string to be displayed as the title.
-listener
Database name: listener
Database class: ActionListener
Action listener object. You can derive hwtk::interface::HWTreectrllistener and create a class where you can overwrite the methods for all actions, such as events like Selection, ButtonPress, KeyPressetc...
-menu
Database name: menu
Database class: Menu
Context menu posted for RMB (Right Mouse Button) on Listbox.
-selectcommand
Database name: selectcommand
Database class: Command
Tcl script executed on selection in the Listbox
%-char substitutions are
  • %W - widget path
  • %S - selected items
  • %c - count (number of items selected)
-selectindicator
Database name: selectindicator
Database class: SelectIndicator
Checkbutton will be displayed against each item in the Listbox. You can select an item by clicking on checkbutton. This can be configured as auto, show, or hide; defaults to hide.
-selectmode
Database name: selectmode
Database class: SelectMode
Specifies one of several styles for manipulating the selection. The value of the option may be arbitrary, but the default bindings expect it to be either single, or multiple; the default value is multiple.
-showheader
Database name: showHeader
Database class: ShowHeader
Specifies a boolean value that determines whether this widget should display the header line with the headertext at the top of the widget. The default value is true.
-sort
Database name: sort
Database class: Sort
Specifies the boolean value that determines whether this widget should sort the items in the list; defaults to true.
-stripes
Database name: stripes
Database class: Stripes
Specifies the boolean value that determines whether this widget should draw background stripes for this widget; defaults to true.
-unique
Database name: unique
Database class: Unique
Specifies the boolean value that determines whether this widget should have all unique items or not.
-wrap
Database name: wrap
Database class: Wrap
Specifies whether items are arranged in a 1- or 2-dimensional layout. It accepts window or ""; defaults to "".

Widget Commands

pathName add tag ?value? *...?
This command creates items in the listbox. The arguments should be pair of item tag and its display value.
pathName cget option
Returns the current value of the configuration option given by option.
pathName configure ?option? ?value option value …?
Query or modify the configuration options of the widget. If one or more option-value pairs are specified, then the command modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. If option is specified with no value, then the command returns a list describing the named option: the elements of the list are the option name, database name, database class, default value, and current value. If no option is specified, returns a list describing all of the available options for pathName.
pathName delete ?tags?
Deletes the listbox items specified by tag. all tag deletes all the items in the listbox.
pathName exists ?tag?
Returns 1 if the specified item exists, and 0 if not.
pathName get ?arg arg ...?
Returns listbox content (only text for all items).
pathName identify element x y
Returns the name of the element under the point given by x and y, or an empty string if the point does not lie within any element. x and y are pixel coordinates relative to the widget. Some widgets accept other identify subcommands.
pathName index tag
Returns the index (item order) for a given tag.
pathName insert pos tag value
Inserts the new item at a given position. Position is decimal value and it is item order.
pathName instate statespec ?script?
Test the widget’s state. If script is not specified, returns 1 if the widget state matches statespec and 0 otherwise. If script is specified, equivalent to 
if{[pathNameinstatestateSpec]}script
pathName itemcget item option
To get the configuration properties of a item.
pathName itemconfigure item ?arg arg …?
If no option is specified, returns a list describing all of the available options for the item given by tag. If option is specified with no value, then the command returns a list describing the one named option. If one or more option-value pairs are specified, then the command modifies the given item option(s) to have the given value(s); in this case the command returns an empty string.
-text
displaytext
-image
display image
pathName move scrItem tarItem
Move the given item to the target position.
pathName position tag
Returns the position in the listbox of the given tag.
pathName see itemDesc
Updates the listbox so that the item specified by itemDesc is visible. If the item is already visible in the listbox, this command has no effect; if the item is not visible, the listbox will scroll appropriately.
pathName selection command ?arg arg ...?
This command is used to adjust the selection within a treectrl. It has several forms, depending on option:
pathName selection add tag
Adds the given tag to the selection in the widget and the selection command will be executed.
pathName selection clear tag
Deselects the given tag from the selection. If all supplied all the items will be deselected.
pathName selection get
Returns the list of items which are in the selection.
pathName state ?stateSpec?
Modify or inquire widget state. If stateSpec is present, sets the widget state: for each flag in stateSpec, sets the corresponding flag or clears it if prefixed by an exclamation point. Returns a new state spec indicating which flags were changed: 
setchanges[pathNamestatespec]
pathNamestate$changes
will restore pathName to the original state. If stateSpec is not specified, returns a list of the currently-enabled state flags.
pathName typelist
Displays a list of available editor types.

Example

::hwtk::dialog .dlg -title "::hwtk::listbox"
set recess [.dlg recess] 

set lstbox [::hwtk::listbox $recess.lb -headertext "Header text"]
pack $1stBox -fill both -expand true;

set i 0;
foreach f [glob -nocomplain -types {d f} -directory [pwd] *] {
    $1stBox add files$i "[file tail $f]"
    set image "file-16.png"
    if {[file isdirectory $f]} {
        set image "folder-16.png"
    }
    $1stBox itemconfigure file$i -image $image
    incr i;
}

.dlg post