Hugelist - Description

Hugelist

### ulis' Tcl code

#### français

### INDEX

INTRODUCTION
DESCRIPTION
INSTALLATION
USE
DOWNLOAD
RELEASE
BUGS

### INTRODUCTION

(My english is very bad, so I'll be happy if you correct it: mailto:ulis)

#### A versatile extension of the Tk listbox that can hogg more than 1,000,000 items, display images, hierarchical views, vary the font...

#### What is it?

It's a Tcl script megawidget.

### DESCRIPTION

#### What it does?

a(Huge)ListBox is a pure Tcl megawidget that is a direct replacement for the Tk 8.4 listbox.

##### Pros:

It adds fonctionalities as:
- alternate color for even lines,
- each item can change its image, its left offset, its font.
So it's possible to display lists with radio buttons, check boxes, hierachical views, files trees, the list of the fonts with its own font...
But its main interest is to accept a huge set of items without time or memory penalty
(with 1,000,000 items it's 1,000 times faster to load, scroll or resize than the standard listbox).
Being a Tcl script it's easy to enhance it.

##### Cons:

It's 10 times slower than the standard list box for tiny lists
(but loading time is not noticeable).

##### Known bugs:

- fonctionality for the -selectmode and -setgrid options is not implemented,
- minor deviations from the standard list box (active and selected items appearence,...).

#### How it does?

Items are virtual and consume quasi no memory and need quasi no loading time.
A canvas is used to display the visible part of the items. All the cinematic is simulated.
A limited number of canvas text items is used to display the items hitting the visible area.
All items sharing the same configuration share the same description.
A list of ranges permits to retrieve the configuration of an item.
Hugelist widgets are binded to the Listbox class.
Some design considerations are exposed at: http://mini.net/tcl/mass-widget.

### INSTALLATION

To install:
- download the file Hugelist.zip,
- unzip the file in a directory,
- move this directory in the lib directory of Tcl.
For Windows, the resulting tree should be:
.../Tcl
.../Tcl/bin
.../Tcl/doc
.../Tcl/lib
.../Tcl/lib/Hugelist

### USE

After declaring the package, the Hugelist widget use is the same as the listbox widget use:

`package require Hugelist`
`namespace import hugelist::hugelist`
`set ::listvar {one two three four}`
`hugelist .hl -listvar ::listvar`

#### Class operations

The hugelist command, with the usual syntax [hugelist pathName args], allows to create hugelists.
It allows two additional operations:

hugelist option | allows to get or set the widget default values or get the widget options description
hugelist version | returns the version of the Hugelist

`hugelist option`
This operation allows to get or set the default values of the items or the widget options:

hugelist option get | returns the list of the options with the default values
hugelist option get key | returns the default value of the option key
hugelist option set key | returns the description of the option key
hugelist option set key value... | sets the default value value to the option key

The defaut values of the options are applied during the creation of a Hugelist.
The default values of the Listbox are used during the class initialization, but not used after that.
(for the new options of the widget, see the section Widget new options)

`set descriptions [hugelist option get]`
`set default [hugelist option get -alternate]`
`hugelist option set -bg beige -alt linen`

`hugelist version`
This operation returns the version of the Hugelist.

`set version [hugelist version]`

#### The enhanced operation

`itemconfigure`
To deal with huge lists, this operation accepts now one or two indexes.
The first index indicates the first item.
The second index indicates the last item.
Without the second index, the only index indicates the only item.
`path itemconfigure first ?last? ?option-paire?...`

`.hl itemconfigure 0 end -left 10`

#### The new operation

`info`
This operation returns the values computed by the widget:

charheight | height of the effective font
charwidth | width of the character 0 (zero) of the effective font
colwidth | value of the column width used during scrolling
count | count of the items
font | effective font of the widget
rowheight | value of the row height used during scrolling

To know how these values are computed, see the description of the options -colwidth, -font, -ipadx, ipady et -rowheight.

`set rowheight [.hl info rowheight]`

#### Widget new options

`-alternatecolor`
This option defines an alternate color for the even rows.

`.hl configure -alternatecolor gray95`

`-font`
This standard option specifies the default value of the option -font for all the items.
When this value is empty, the effective font is the standard font of the listbox.
This value is also used when the value of the -rowheight option is empty or null.
In this case the row height is computed from the height of the effective font added to the value of the -ipady option.
This value is also used when the value of the -colwidth option is empty or null.
In this case the column width is computed from the width of the character 0 (zero) added to the value of the -ipadx option.

`.hl configure -font {-family Times -size -16}`

`-image (ou -img)`
This option defines the default value of the option of the items.
This value is used when the value of the option of an item is empty.
(see the section Items new options)

`.hl configure -image img_first`

`-ipadx`
This option defines the value to add to the width of the character 0 (zero) to compute the width of a column.
This value is used when the value of the -colwidth is empty or null.
In this case the column width is computed from the width of the character 0 (zero) added to the value of the -ipadx option.

`.hl configure -ipadx 0`

`-ipady`
This option defines the value to add to the height of the fontto compute the height of a row.
This value is used when the value of the -rowheight is empty or null.
In this case the row height is computed from the height of the effective font added to the value of the -ipady option.

`.hl configure -ipady 4`

`-left`
This option defines the default value of the option of the items.
This value is used when the value of the option of an item has not been defined.
(see the section Items new options)

`.hl configure -left 10`

`-rowheight`
This option defines the height of a row in a form accepted by Tk_GetPixels.
An empty value switches to the default height (font dependant).

`.hl configure -rowheight 20`

`-text`
This option defines the default value of the option of the items.
This value is used when the text of an item is empty.
(see the section Items new options)

`hugelist .hl -list ::list`
`.hl configure -text "(empty)"`
`set ::list [list $a $b $c $d]`

`-user`
This option is for the user.

`.hl configure -user {hugelist 4}`

`-values`
This option defines the list of the texts of the items.

`.hl configure -values {one two three four}`

`-xscrollcommand`
This option defines the prefix for a command used during the xset operation.
The command is generated by concatenating the prefix and two arguments:
- the fraction (between 0 and 1) defining the horizontal beginning of the visible area,
- the fraction (between 0 and 1) defining the horizontal end of the visible area.
Typically the command is a call to the set operation of a horizontal scrollbar widget.
The command is not called until it is defined. So defining the <*>scrollbar after defining this option is safe.

`.hl configure -xscrollcommand {.hs set}`

`-yscrollcommand`
This option defines the prefix for a command used during the yset operation.
The command is generated by concatenating the prefix and two arguments:
- the fraction (between 0 and 1) defining the vertical beginning of the visible area,
- the fraction (between 0 and 1) defining the vertical end of the visible area.
Typically the command is a call to the set operation of a vertical scrollbar widget.
The command is not called until it is defined. So defining the <*>scrollbar after defining this option is safe.

`.hl configure -yscrollcommand {.vs set}`

#### Items new options

`-font`
This option defines the font of the item.

`.hl itemconfigure 0 -font {-family Times -size -16}`

`-image (ou -img)`
This option defines an image displayed at the left of an item.

`.hl itemconfigure 0 -image img_first`

`-left`
This option defines a left margin for an item.

`.hl itemconfigure end-1 -left 10`

`-text`
This option defines the text of an item.

`.hl itemconfigure end -text "[.hl temcget end -text] (last)"`

### DOWNLOAD

Hugelist.zip

### DISTRIBUTION

#### Release

This release is 1.3 dated 2003-04-24.
It was tested under Windows 2000 with Tcl/Tk 8.4.
Hugelist passed 90% of the listbox tests (see the section Incompatibilities for the incompatibilities).
It should run on all Tcl/Tk supported platforms.

#### Licence

This version is distributed under the NOL licence (No Obligation Licence).
(C) 2003, ulis

#### Thanks

This work would not be without the original desing of Tcl and Tk by John Ousterhout, the great work of the Core Team and the support of all the Tcler's.
A big THANKS to them.
A special thank to Bernd Platzdasch which tested the beta version of Hugelist.

#### Bugs

Please, send bug reports and enhancement calls to: ulis.

### BUGS

#### Incompatibilities

The Hugelist passed 300 of the tests of the list box and failed on 30.
Here is a summary of the result:

Type of incompatibility | Number | Reason
items management | 6 | mass-configuration
scrolling | 6 | mass-scrolling
error messages | 6 | mass-diagnostic
"partial" oddity | 5 | to avoid
new options | 2 | new options
itemconfigure operation | 1 | extended syntax
anchor index management | 1 | no more pass the last item
X selection | 1 | selection is kept on focus out
list variable protection | 1 | how to do that?
activestyle option | 1 | partially implemented
binding class | 1 | different class name

The Hugelist doesn't use directly the Tk options database.
In fact, the Hugelist class is initialized from the default values of the Listbox class.
Then, you need to use the [hugelist option] to modify the default values.
(see the section Class operations)

#### Patches & Evolutions

Description | Detection | Correction
official release |  | v1.0 - 2002-12-08
new -left option for the items |  | v1.1 - 2003-02-09
new -rowheight option for the widget |  | v1.1 - 2003-02-09
dynamic resizing | Scott Gamon - 2003-02-27 | v1.2 - 2003-03-09
default values management |  | v1.2 - 2003-03-09
new -user option for the widget |  | v1.2 - 2003-03-13
new -image option for the widget |  | v1.2 - 2003-03-23
new -left option for the widget |  | v1.2 - 2003-03-23
new -text option for the widget |  | v1.2 - 2003-03-23
bug: -listvar option doesn't resize | ulis - 2003-03-29 | v1.2.1 - 2003-03-29
bug: insert & delete don't resize | ulis - 2003-03-30 | v1.2.2 - 2003-03-30
compatibility: bbox & scan | ulis - 2003-03-31 | v1.2.3 - 2003-04-01
new -ipadx widget option |  | v 1.3 - 2003-04-20
new -ipady widget option |  | v 1.3 - 2003-04-20
new -charwidth widget option |  | v 1.3 - 2003-04-20
new -font item option | Scott Gamon | v 1.3 - 2003-04-20
new info operation |  | v 1.3 - 2003-04-20