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