Copyright © 2008, 2009 Arndt Roger Schneider

Rtl_mlistbox
Prev Appendix A. Reference Next

Name

rtl_mlistbox — Create and manipulate rtl_mlistbox windows

Synopsis

          package require rtl_mlistbox
        
          rtl_mlistbox pathName ?options ?

Runtime Library Options

-creator

The RTL based option creator is used to instantiate the template rtl_mlistbox 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

-font, -foreground, -selectbackground, -xscrollcommand, -yscrollcommand, -highlightbackground, -highlightcolor, -highlightthickness, -height, -width, -selectBorderWidth, -selectforeground, -borderwidth, -relief, -takeFocus, -state, -background

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

Window-specific Options

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

Integer value, amount of listbox columns.

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

List of column dimensions.

Example A.6. Listbox Dimensions

rtl_mlistbox .mlistbox -columns 2 \
          -columnwidths {333 222}

The rtl_mlistbox in Example A.6, “Listbox Dimensions” has two columns the first column is 333 pixel and the last column 222 pixel width.

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

Call back command, this script is evaluated in response to a double-click event onto the rtl_mlistbox.

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

call back command. This script is evaluated, whenever a drag operation begins.

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

Call back command. This script is evaluated, whenever a drag operation commences.

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

call back command. This script is evaluated, whenever a drag operation ends.

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

List of strings. The string values of »-headings« is used for the header row. It contains the descriptions for the columns.

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

List of anchor definitions. Defines how the column headers are aligned. Possible values are »e«, »center« and »w«.

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

Boolean value. Allows to interactively resize the columns inside the rtl_mlistbox.

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

Call back Tcl Command,called each time a selection in the rtl_mlistbox is done. Calling rtl_mlistbox widget and selected line index are appended to call.

Example A.7. »-selectcommand« Signature

proc handleselection {rtl_mlistbox index} {}

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

Each column has a tag serving as handle for configuration. The tags of all columns may be set via this option. Default tags are the column numbers.

NOTE: duplicate tags are allowed but only first column with a duplicated tag is reachable via columnconfigure.

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

The font for the column descriptions.

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

Either »2D« or »3D«. Defines the visual appearance for the rtl_mlistbox header. A 2D fashioned windows uses a flat appearance, where the header row uses inverted foreground and background colors. A 3D fashioned a pseudo 3D appearance. The header row repeats the colors from their respective columns.

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 A.8. gistbox uses Rtl_mlistbox

gistbox .gistbox -listtype rtl_mlistbox

Example A.9. Rtl_mlistbox uses Hugelist

rtl_mlistbox .mlistbox \
    -listtype hugelist::create

Command-Line Name: -gridcolor, Database Name: gridColor, Database Class; -

A color. »-gridColor« is used for vertical and horizontal lines inside the window.

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: -dragable, Database Name: dragable, Database Class; -

Boolean value. This rtl_mlistbox accepts drag-and-drop for single selection.

Only rtl_mlistbox windows with »-selectMode« set to »single« support drag-and-drop.

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

Boolean value. A »-sortable« rtl_mlistbox allows the sorting of columns.

Sorting is not built-in the rtl_mlistbox, any sort operation is delegated to the registered »-sortcommand«.

Command-Line Name: -sortcommand, Database Name: sortCommand, Database Class; -

Call back command. Registers what command has to be evaluated in response to a sort operation.

Example A.10. Using Sort

proc sortnotifier {
    mlistbox sortedColumn sortby
    } { … }

# Register sorting and sort notifier.
rtl_mlistbox .mlistbox \
    -sortable 1 \
    -sortcommand sortnotifier ...

See also »-sortable«.

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

Menu window path name. This menu is posted in response to a right-click (context) on the header row.

Command-Line Name: -usecolumncolors, Database Name: useColumnColors, Database Class; -

Boolean value. Allows individual colors for the contained columns.

The specific column color is retrieved from the option database. The various option database entries are »color0« for the first column, »color1« for the second column, »color2« for the third column ...

Description

Figure A.2. rtl_mlistbox using hugelist


The »rtl_mlistbox« command creates a »rtl_mlistbox« window.

»rtl_mlistbox« is a multi-column listbox. The internal used »listbox« class can be replaced –before creation– via the »-listtype« property.

To-Do: checklength --lock using it until a map event arrived, so that out-of-order customization is possible ; or seek a mechanism which applies the properties in their correct order.

Should work, through the attributes list.

Version 3.0: Multi-selection is possible, now. Including browse, extended, single. Not tested is »multiple«. This various selection modes are only possible by using the real (emulated) listbox interface, introduced in this version. The drag-and-drop feature remains available in single select mode, only. Otherwise it is disabled as a side-effect of setting »selectMode«.

-state -dragable -selectmode -takefocus

The rtl_mlistbox version 3.0 allows cascading designs. A rtl_mlistbox may be used inside of another rtl_mlistbox, in truth there is no limit to how many cascading rtl_mlistboxes are being used. In addition Drag-and-Drop is isolated from normal bindings. this makes it possible to support other »selecMode« operations. Many bindings have been revised, too. The rtl_mlistbox behaves now like any other listbox. In consequence the interface is almost identical to a Tk listbox.

- headingsanchor Modified, synchronizes anchor and justify. Needed for SVG code generation.

pathName selection pathName see pathName scan pathName index

Many new interface elements for listbox compliance: selection (replaces select), see, scan, index.

aquamlistbox

--more specific see for the triangle color usage, this is currently not yet correct. Not a part of the RTL, there is a »aquahead« inside the »Gestalt Items«, which turns the rtl_mlistbox header row into an AQUA compliant header, including gradient, select color, triangle back color, activate and deactivate.

Version 2.0: -fashion -headerFont -sortable -sortCommand -listtype -gridColor -menu -useColumnColors

Sort & Reorder. These two functions are the missing ones to complete the multi-list-box implementation. Sort –as sort always should be done– is done where the data is stored. The multi-listbox is just a representation of this data. Therefore the multi-listbox is not allowed to sort it's listbox contents on its own. A call back mechanism is provided to notify the sorting type as well as what column is to be sorted. Second thought about TypeOf: In essence any abitrary window type could substitute the listboxes. This means rtl_mlistbox is in effect also a so-called paned window. New properties:

headerFont: allow a separate font for the header row, required for OSX –the AQUA header font is application 10 bold.

Added selectforeground to complement selectbackground.

New Color Schema: The Header Color should be the inverse color of the list boxes -foreground/background. There should be a single line separating listboxes.

New properties: fashion & listtype (internal as: fashion & typeOf).

Fashion allows to switch between a positive and negative header schema. The negative header schema is described above. The two fashions are defined as 2D & 3D –3D because there is a raised border between the listboxes and the header section.

Listtype: Provides the ability to replace the internal used listbox control with something else. Most likely a virtual listbox –lets call it vistbox.

Window Command

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

          pathName option ?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:

pathName cget option

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

pathName configure ?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 rtl_mlistbox command.

pathName sorted

Written : 2006, Roger

pathName drag-end widget x y

The last element of a drag and drop operation. Here the interactive dnd bindings must be eliminated again. Revision : 12/17/2008, Roger

pathName makelist alist

Reduce associative list $alist to sorted list according to column tags of rtl_mlistbox. For Column tags not contained as key within $alist, empty list elements are inserted.

pathName delete ...

Delete lines from listbox

pathName resize-end widget x y

See above

pathName tkCommand type command ...

Execute a given code sequence in the realm of Tk... usually a listbox command. Originates from an event handler.

Creates a backup of private Tk data and applies the same initial data before any window is invoked. This function does not work with cascading mlistboxes.

tkCommand is endangered. The mutlti-column-listbox has gained a full listbox interface. tkCommand is a crude way to bypass the implementation of such an interface. Rewritten : 12/17/2008, Roger

pathName command0 type command ...

Execute command on first column if specified widget exists. Revision : 08/20/2009, Roger -list & guarded

pathName do-yscroll widget ...

Scroll command interface- This is called from the scrollbars, and makes a detour through yview ... as yscrollcommand. Double values for PageDown and Up originate from hugelist, not from rtl_mlistbox.

fixme (Roger) 12/18/2008 : Hugelist, do-yscroll may be called n-times this can be identified by looking whether »widget« is a listbox_n and not listbox_0. Not possible here.

Has to be dealt with inside the event handler. There are real events such as B2-Motion which will be disrupted. Cause is inside hugelist. The scroll behavior is correct for »listbox«.

Issue solved inside »yview«. yview uses a semaphore to lock against recursive calls. This will have no effect on listbox, but prevents recurring yview calls originating from a hugelist.

Revision : 12/18/2008, Roger

pathName checklength vallist action

Check length of value list fixme (Roger) 12/13/2008 :checklength must be altered so that it is technically feasible to predefine any data needed to customize the given mlistbox. Test against »headeranchor«, »headings«, »columns« and »headerfont«.

pathName button-motion-cb widget x y time

Restart of a drag and drop operation. Similar to »button-press-cb«, a underway drag and drop operation is violated. And a new one gets started. Revision : 12/17/2008, Roger

pathName drag-start widget x y

Drag'n'Drop. This section is only valid for single selected listboxes, hence the property dragable.

Whenever selectmode is altered and not equal to »single« »dragable« is turned off.

DND bindings are applied on a special bindgroup. This allows temporary dnd operations on a single rtl_mlistbox without interfering with other usages. Revision : 12/17/2008, Roger

pathName rtl_mlistbox ...

Undocumented.

pathName resize-start widget x y

procedures for column width resize per drag-and-drop

pathName nextsort column

Iterate over the sort indicators for the given »column«. Written : 2006, Roger

pathName sort sender column state

Tells the rtl_mlistbox to sort »column«. Written : 2006, Roger

pathName see index

Propagate see to each contained listbox. Written : 11/19/2008, Roger

pathName foreachcol type w idx body

Undocumented.

pathName makeassoc vallist

Build associative list from $vallist. $vallist usually looks like result from method 'get'.

pathName get first ?last?

Get specified lines from listboxes

pathName activate index

Activate line

pathName adapt

Resize canvas when frame was resized. Revision : 06/12/2008, Roger –Added troughColor adjust.

pathName yview ...

Set visible interval in y-direction.

A semaphore is used to block recursive calls, initiated from a hugelist array. See also comment on »do-yscroll«.

Position retrievable is still allowed.

Affected events: B2-Motion, PageUp, PageDown, Multi -Down and -Up such as generated by a Wacom tabloid scrollwheel. Possibly affected ScrollWheel.

Tested for cascading designs, too. Revision : 12/18/2008, Roger

pathName search tag pattern

Search column specified by $tag for pattern $pattern.

pathName command type command ...

Execute same command on specified component in each column of mlb.

pathName foreachrow col w body

pathName hidecol tag

pathName curselection

Get line indices of current selection

pathName select ?index?

Select line (not existing for single listbox)

OBSOLETE

The listbox interface (selection set is used), replaces this event handler... it exists only for backward compatibly. DO NOT USE ANYMORE

See event handler <1>. Revision : 12/17/2008, Roger

pathName size

Get line count of rtl_mlistbox, that is the 'size' of the first listbox.

pathName dragstart

See set-dragstart

pathName indicator canvas

Undocumented.

pathName scan ...

Propagate scan to each contained listbox. Written : 12/17/2008, Roger

pathName insert index ...

Insert lines to listbox

COMMENT: Collecting the items for the columns instead of inserting them row wise may slow down the process because 'eval' is needed to perform the insertion operation. On Windows systems, for which this procedure is optimized, this version is faster.

pathName itemconfigure ...

Undocumented.

pathName destroy

Clear up data storage for widget instance and destroy widget. fixme (Roger) 12/13/2008 :inject the trace for aqua headers into this procedure ...

pathName setcol tag data

Set content of column specified by tag.

pathName dragmotion

See set-dragmotion

pathName resize-drag widget x y

See above

pathName dragend

See set-dragend

pathName selection ...

Missing selection interface. This interface is used for any sort of selection. Most definite by browse and extended selectMode It is also needed in case of cascading listboxes. That is, whenever rtl_mlistboxes are deployed by rtl_mlistboxes... can be multiple levels! Written : 11/06 + 12/17/2008, Roger

pathName colresize column width

Comfortable resize of width of specific column. Revision : 09/07/2009, Roger- ResIn.

pathName index type

Missing interface element. Written : 11/06/2008, Roger

pathName columnconfigure tag ...

pathName getoption type option

pathName init

Secondary constructor for widgets of type mlistbox. Initialize instance specific variable. Revision : 12/17/2008, Roger

pathName sortDisplay sender column fashion

Undocumented.

pathName drag-motion widget x y

A drag and drop operation is underway and the visual feedback --a simple toplevel window-- gets moved according to the current position. Revision : 12/17/2008, Roger

pathName xview ...

Undocumented.

pathName execute

Call back »-command« is evaluated, whenever a double-click happened inside a listbox. Rewritten : 12/18/2008, Roger–Simplified.

pathName setoption type option vallist

pathName triangle canvas ?color? ?orient?

Undocumented.

pathName getcol tag

Get content of column specified by tag.

pathName showcol tag

Dependencies

  • rtl

Prev Up Next
Rtl_tabset Home Rtl_tree
SourceForge Logo Gestalt Items