Copyright © 2009 Arndt Roger Schneider

Gistbox
Prev Chapter 3. Listbox and Tree Templates Next

Name

gistbox — Create and manipulate gistbox windows

Synopsis

          ;; package require gistbox in Tcl/Tk.
          (with-ltk-gistbox
             (make-instance 'gistbox ?options ?))

Runtime Library Options

-creator

The RTL based option creator is used to instantiate the template gistbox with a Tk Window. The used creator window must have a -class property.

Acceptable Tk Windows are: toplevel for floating windows, and frame for embedded windows.

Standard Options

-background, -state, -disabledForeground, -disabledBackground, -highlightThickness, -highlightColor, -highlightBackground, -borderWidth, -relief

See the options manual entry for details on the standard options.

Window-specific Options

Command-Line Name: -ihighlightthickness, Database Name: ihighlightThickness, Database Class; -

»ihighlightTchickness« and »ihighlightBackground« create a frame around the internal listbox and entry.

»ihighlightThickness« is dedicated to AQUA®. The »solid« relief in Tcl/Tk is currently black and should be »gray57« under AQUA®.

set »ihighlightThickness« to »1« and »ihighlightBackground« to »gray57« under AQUA®; otherwise don’t use the ihighlight properties.

Command-Line Name: -ihighlightcolor, Database Name: ihighlightColor, Database Class; -

Not used.

Command-Line Name: -ihighlightbackground, Database Name: ihighlightBackground, Database Class; -

Set »ihighlightBackground« to »gray57« under AQUA®. Otherwise don’t use this property.

See also »ihighlightThickness«.

Command-Line Name: -variable, Database Name: variable, Database Class; Variable

Specifies the name of a variable. The value of the variable is a list to be displayed inside the widget; if the variable value changes then the widget will automatically update itself to reflect the new value. Attempts to assign a variable with an invalid list value to -variable will cause an error. Attempts to unset a variable in use as a -variable will fail but will not generate an error.

Command-Line Name: -pluscommand, Database Name: plusCommand, Database Class; -

»plusCommand« is usually mapped to the Gistbox »add« command.

Example 3.8. Standard »+« Command

gistbox .gistbox -plusCommand {.gistbox add}

Command-Line Name: -minuscommand, Database Name: minusCommand, Database Class; -

»minusCommand« is usually mapped to the Gistbox »delete« command.

Example 3.9. Standard »-« Command

gistbox .gistbox -minusCommand {.gistbox delete}

Command-Line Name: -notify, Database Name: notify, Database Class; -

A command. The »notify« command is called after the contents changed.

Example 3.10. Notify after modifications

gistbox .gistbox \
   -listtype listbox \
     -notify [list refresh .gistbox]
...

proc refresh {{notifier {}}} {
...
}

Command-Line Name: -iborderwidth, Database Name: iborderWidth, Database Class; -

»iborderWidth« and »irelief« define the internal border around the entry and listbox windows.

Specifies a non-negative value indicating the width of the pseudo 3-D border to draw around the outside of the widget (if such a border is being drawn; the relief option typically determines this). The value may also be used when drawing pseudo 3-D effects in the interior of the widget. The value may have any of the forms acceptable to Tk_GetPixels.

Command-Line Name: -irelief, Database Name: irelief, Database Class; -

The Gistbox is a composite window. »irelief« and »iborderWidth« control the internal border around the listbox and entry.

Specifies the pseudo 3-D 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.

Command-Line Name: -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, browse, multiple, or extended; the default value is browse.

Command-Line Name: -listtype, Database Name: listType, Database Class; -

The internal listbox. The kind of the internal listbox can be defined prior creation. listType is a static property.

The used list must conform to the Tk listbox interface.

Rtl_mlistbox, hugelist or listbox can be used.

Example 3.11. gistbox uses Rtl_mlistbox

gistbox .gistbox -listtype rtl_mlistbox

Example 3.12. Rtl_mlistbox uses Hugelist

rtl_mlistbox .mlistbox \
    -listtype hugelist::create

Command-Line Name: -single, Database Name: single, Database Class; -

Either '0' or '1'. If »single« is specified, the entire entry text is treated as a single item. Otherwise the entry text is broken into atoms and each atom is inserted as an item to the listbox.

Example 3.13. Single Entry Property

gistbox .gistbox -single 1

# Entry contents: »This is a single entry«.
# Becomes a single item inside the listbox
# after it was added.

Description

Figure 3.2. Gistbox


Figure 3.2, “Gistbox” displays a gistbox window containing a rtl_mlistbox with hugelist listboxes. These hugelists feature gradients for selected items.

gistbox is an edit able listbox. combobox is similar to gistbox. gistbox set the emphasis on the listbox content and not –as the combobox does– on the interaction.

gistbox itself is a typical container window. It can be used with any listbox-like window, such as rtl_mlistbox, hugelist, listbox, perhaps even tablelist...

The »-listtype« property predefines the listbox type.

gistboxes cannot be used inside of gistboxes!

An rtl_gridwin manages the scrollbars.

Notes on using gistbox

Entry: AQUA® has its own mind concerning disabled entries (perhaps Tk is the culprit). A disabled entry is always white, while an active one may have any color... On all other platforms the entry will follow the disable scheme as the listbox itself does.

Note 12/17/2007 - 11:24 : highlightthickness, iborderwidth & ihighlightthickness.

ihighlighthtickness is a workaround to get a gray57 border under AQUA®. Please, do not use it anywhere else! The normal way to get a border around a gistbox is iborderwidth and irelief. Do not combine iborderwidth and ihighlightthickness!

There is another borderwidth and relief defined for the outside of the gistbox. Use this border whenever you have a need for that –don’t think there is one.

Window Command

A Window created through the gistbox command exposes various functions. Using these functions has the following general form: 

(option object ?arg arg ...?)

PathName is the same as the window path name. Option and the args determine the exact behavior of the command. The following commands are possible for this window:

(cget object :option)

Returns the current value of the configuration option given by option. Option may have any of the values accepted by the gistbox command.

(configure object ?:option? ?value option value ...?)

Query or modify the configuration options of the window. If no option is specified, returns a list describing all of the available options for pathName (see Tk_ConfigureInfo for information on the format of this list). If option is specified with no value, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no option is specified). If one or more option-value pairs are specified, then the command modifies the given window option(s) to have the given value(s); in this case the command returns an empty string. Option may have any of the values accepted by the gistbox command.

(focusOut object )

Notifies the gistbox whenever the focus gets lost. The highlight frame is hidden in response. See also »focusIn«

(focus object wd )

Shows and hide the highlight (keyboard focus). wd can be negative – needed to hide highlight frames during resize operations.

(sizeOf object )

The length of the listbox contents.

(clearAll object )

Undocumented.

(delete object ?item? )

Remove each selected item in the listbox from the list.

(init object )

Stripes and refresh the »gistbox« after it was created.

(checkSelection object )

Test whether or not there is a current selection. The query depends on the current state of the gistbox.

Rewritten : 10/22/2007, Roger

(listbox object )

For alternate listbox types an access method is required: »rtl_mlistbox«, for example, requires further configuration.

(Elements object )

Query the gistbox, for all the elements inside the listbox.

(clearEdit object )

Undocumented.

(add object ... )

Add each item in the entry widget to the listbox.

(notify object )

Send a notification to the subscribing window –this is a command call.

(adjustBorders object borderWidth )

Internal used. Manipulates the surrounding white space, which belongs to the »gistbox«.

(overwriteElements object items )

Replace all items inside the listbox with those defined inside of list »items«. Revision : 10/23/2007, Roger

(pending object )

Return the content of the entry ... in order to process an external add.

(selection object )

Deliver the contents of the current selected listbox items. This is different to »curselection« from listbox. Here the content is returned.

(focusIn object )

Internal Focus manager showing synthetic highlight frames.

The »focusIn« function has two implementations: when »stripes« is being used for the gistbox, the highlight frame is a tkpath »prect«. Otherwise plain frames implement highlighting.

Two gstripes functions are used : focusframes or focuspathes.

focuspathes requires TkPath else focusframes is the fall back solution.

focusframes has two implementations inside of gstripes: One using vanilla Tk, and the other using »prect« from TkPath. Technically only the vanilla Tk version can be used by gistbox– because focuspathes takes precedence over focusframes.

(refresh object )

Forces a redraw of the entire gistbox.

Dependencies

  • rtl_gridwin

  • gstripes

  • rtl

Prev Up Next
Rtl_mlistbox Home Rtl_tree
SourceForge Logo Gestalt Items