Hugecombo

ulis' Tcl code


français


INDEX

  INTRODUCTION
  DESCRIPTION
  INSTALLATION
  USE
  DOWNLOAD
  DISTRIBUTION
  BUGS
 

   INTRODUCTION

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

A Combobox widget hogging 1,000,000 items

What is it?

It's a Tcl script megawidget.
 

   DESCRIPTION

What it does?

a(Huge)ComboBox is a pure Tcl megawidget replacing the entry widget of Tk 8.4.
It augments the entry widget with a pick-list and its calling-button.
This pick-list is the famous Hugelist which allows to choose among more than 1,000,000 items without time or memory penalty.
The search is based on the [string match] patterns.
Pros
- it is compatible with the Tk 8.4 entry widget,
- it is based on the Hugelist,
- each subwidget component is configurable,
- it knows to display images,
- it allows a easy search (pattern search, fast smooth scrolling),
- as a Tcl script it is easy to modify.
Cons
- it is a Tcl megawidget (but loading time is not noticeable).
Known bugs
It is a new widget.

How it does?

Pressing the button or sending a navigating key opens a toplevel window that shows a pick-list (a Hugelist and a scrollbar).
Selecting an item updates the entry widget with the item. A grab on the toplevel allows to detect the focus out and closes the toplevel window.
 

   INSTALLATION

To install the Hugecombo package:
- dowload the file Hugecombo.zip,
- unzip the file in a directory,
- copy this directory in the lib directory of the installed Tcl.
 
For Windows, the resulting tree should be:
.../Tcl
.../Tcl/bin
.../Tcl/doc
.../Tcl/lib
.../Tcl/lib/Hugecombo
 

   USE

The Hugecombo widget and the standard entry widget are closely related.
Differences are :
- the declaration of the package,
- the pick-list related options,
- the pick-list related operations,
- the pick-list related bindings.
 
    package require Hugecombo
    namespace import ::hugecombo::hugecombo
    hugecombo .hc -values {one two three four}
    .hc list find Huge*

Class operations

The hugecombo command, with the usual syntax [hugecombo pathName args], allows to create hugecombos.
It allows three additional operations:
 
 hugecombo option  allows to get or set the widget default values or get the widget options description
 hugecombo parms  allows to get or set the class parameters default values
 hugecombo version  return the version of the Hugecombo

  hugecombo option
 
This operation allows to get or set the default values of the items or the widget options:
 
 hugecombo option get  returns the list of the options with the default values
 hugecombo option get key  returns the default value of the option key
 hugecombo option set key  returns the description of the option key
 hugecombo 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 Hugecombo.
The default values of the Entry and 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)
 
    hugecombo option get
    set default [hugecombo option get -alternate]
    hugecombo option set -bg beige -alt linen

  hugecombo parms
 
This operation allows to get or set the default values of the items or the widget options:
 
 hugecombo parms get key  returns the default value of the parameter key
 hugecombo parms set key value...  sets the default value value to the parameter key

The allowed parameters are:
 
  parameter name   default value   description
 TAG1  HugeCombo  megawidget binding class (frame)
 TAG2  ComboList  entry subwidget binding class
 TAG3  HugeEntry  hugelist subwidget binding class
 b:borderwidth  2  button subwidget borderwidth option
 b:highlightthickness  0  button subwidget highlightthickness option
 b:image  _hugecombo_  button subwidget image option
 b:relief  raised  button subwidget relief option
 b:width  16  button subwidget width option
 e:borderwidth  0  entry subwidget borderwidth option
 e:highlightthickness  0  entry subwidget highlightthickness option
 e:relief  flat  entry subwidget relief option
 e:selectborderwidth  0  entry subwidget selectborderwidth option
 l:activestyle  none  hugelist subwidget activestyle option
 l:borderwidth  0  hugelist subwidget borderwidth option
 l:highlightthickness  0  hugelist subwidget highlightthickness option
 l:relief  flat  hugelist subwidget relief option
 t:relief  raised  toplevel subwidget relief option
 
    set default [hugecombo parms get b:relief]
    hugecombo parms set b:image button_image

  hugecombo version
 
This operation returns the version of the Hugecombo.
 
    set version [hugecombo version]

Added or modified options

-alternatecolor
 
This option specifies an alternate color for the even rows of the pick-list.
 
    hugecombo .hc -alternatecolor gray95 -values {one two three four}

  -compound
 
This option allows to preserve to the left of the entry the room for an image. It takes the values 0 or 1.
 
 1  the image associated with the selected item is copied to the left of the text (default)
 0  the room is not preserved and the image is not copied
 
    Hugecombo .hc -compound 1 -values {top left right bottom}
    foreach i {0 1 2 3} \
    {
      set text [.hc itemcget $i -text]
      image create photo img_$text -file $text.gif
      .hc itemconfig $i -image img_$text
    }

  -height
 
This option defines the count of visible rows in the pick-list.
 
    hugecombo .hc -height 4 -values {one two three four}

  -image (or -img)
 
This option defines or deletes the image displayed at the left of the text.
An empty value delete the image.
The option value is updated at each selection in the pick-list.
The image is not displayed as long as the value of the compound option remains 0
 
    image create photo img -file img.gif
    hugecombo .hc -image img

  -listvariable
 
This option declares the name of a variable holding the list of values.
 
    set ::listvar {one two three four}
    Hugecombo .hc -listvariable ::listvar

  -rowheight
 
This option defines the height of a row in the pick-list in any form accepted by Tk_GetPixels.
 
    hugecombo .hc -rowheight 20 -values {one two three four}

  -state
 
This option has a new value.
Following the value of this option it is possible to edit the text of the widget, select a part of the text, and/or pick a value in the list.
The widget colors are dependant of this option.
 
  valeur   edition   selection   choice   color
 disabled  no  no  no  disabled
 normal  yes  yes  yes  normal
 picklist  no  yes  yes  normal
 readonly  no  yes  no  readonly

With the normal value, the pick-list values can be accessed thru patterns.
With the picklist value, the pick-list values can be accessed thru their first letter.
(see the section Added bindings)
 
    hugecombo .hc -state picklist

  -values
 
This option declares the list of values.
 
    Hugecombo .hc -values {one two three four}

Added operations

component
 
This operation returns the path of the megawidget subwidgets.
Its parameter is the type of the desired subwidget.
 
 button  returns the path of the button subwidget
 canvas  returns the path of the canvas subwidget
 entry  returns the path of the entry subwidget
 hugelist  returns the path of the hugelist subwidget
 listbox  returns the path of the hugelist subwidget
 scrollbar  returns the path of the scrollbar subwidget
 
    set hl [.hc component list]
    $hl configure -alternate azure

  itemconfig
 
This operation configures the Hugelist items.
Its parameters are these of the itemconfig operation of the Hugelist.
That is:
- all the Tk listbox parameters,
- a second index to configure an items slice,
- the new -image (or -img) option allows to define an image to the left of the item text,
- the new -text option allows to redefine the text of the item.
 
    .hc itemconfig 0 end -image i_down
    .hc itemconfig 4 -image i_left
    .hc itemconfig 4 -text "[.hc itemcget 4 -text] (externe)"

  itemcget
 
This operation returns the values of the Hugelist items.
Its parameters are these of the itemcget operation of the Hugelist.
That is:
- all the Tk listbox parameters,
- the new -image (or -img) option that returns the item image,
- the new -text option that returns the text of the item.
 
    set img [.hc itemcget 4 -image]
    set text [.hc itemcget 4 -text]

  list
 
This operation allows to manage the pick-list.
 
Options are:
 
 close  closes the pick-list
 curselection  returns the index of the selected row (or nothing)
 find pattern  selects the next item corresponding to the pattern (or do nothing)
 open  opens the pick-list
 select rowindex  selects the row
 
    .hc list open
    set cur [.hc list cursel]
    .hc list find Huge*
    .hc list open
    .hc list select end-1

  load
 
This operation loads in the entry widget the item associated to the index. If the index is omitted, the selected item is loaded.
 
    .hc load end-1

  send
 
This operation sends a symbolic key to the Hugecombo.
 
Defined symbolic keys are:
 
 <Escape>  closes the list
 <Return>  copies the selected item and close the list
 <Control-Return>  selects the next item corresponding to the pattern
 <Control-Home>  selects the first item of the list
 <Prior>  selects the last item of the previous page
 <Up>  selects the previous item in the list
 <Down>  selects the next item in the list
 <Next>  selects the first item of the next page
 <Control-End>  selects the last item of the list
 
    .hc send <Control-Return>

Added bindings

New bindings select an item in the list :
 
 <Control-Home>  selects the first item of the list
 <Prior>  selects the last item of the previous page
 <Up>  selects the previous item in the list
 <Down>  selects the next item in the list
 <Next>  selects the first item of the next page
 <Control-End>  selects the last item of the list

New bindings allow to acces the values of the pick-list.
With the normal value of the state option, <Control-Return> matches an item with a string match pattern holded by the entry widget.
Repeating the <Control-Return> matches the next matching item (if exists).
With the picklist value of the state option, any key press matches an item with a corresponding first letter.
Repeating the key matches the next matching item (if exists).
 
 <Control-Return>  select the next item corresponding to the pattern
 <KeyPress>  select the next item corresponding to the key

New bindings copy the selected item into the entry widget:
 
 <Return>  copies the selected item and close the list
 <Double-1>
inside the list
 copies the selected item and close the list
 

   DOWNLOAD

Hugecombo.zip
 

   DISTRIBUTION

Version

This release is the version 1.1 dated 2003-03-29.
It was tested under Windows 2000 with Tcl/Tk 8.4.
It passed 98% of the entry standard tests (see section 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.

Bugs

Please, send bug reports and enhancement requests to ulis.

   BUGS

Incompatibilities with the entry widget

The Hugecombo passed 247 of the tests of the entry widget, skipped 25 specific tests (fonts, UNIX) and failed on 6.
Summary:
 
  Type of incompatibility   Number   Reason
 X selection based test  1  non hidden subwidgets
 bgerror based test  1  non hidden subwidgets
 binding class name  1  different class name
 list of operations  2  added operations
 list of options  1  added options

Patches & Evolutions

  Description   Detection   Correction
 official release     v1.0 - 2003-02-04
 dynamic resizing  Jorge Suit Perez Ronda - 2003-02-27  v1.0.1 - 2003-03-01
 -state picklist  Jorge Suit Perez Ronda - 2003-03-12  v1.1 - 2003-03-29