Tk::TextList - Create and manipulate TextList widgets

SUPPORTED PLATFORMS
HEIRARCHY
SYNOPSIS
OPTIONS
- Widget-specifc
- Inherited
DESCRIPTION
METHODS
TAGGING
DEFAULT BINDINGS
KNOWN BUGS/ISSUES
AUTHORS
VERSION

SUPPORTED PLATFORMS

Linux
Solaris
Windows

HEIRARCHY

Tk::Widget   
  |
  +--Tk::Text
        |
        +--Tk::ROText
              |
              +--Tk::TextList

SYNOPSIS

use Tk::TextList;
...
$textList = $mw->TextList(?options, ...?)

OPTIONS

-height -justify -selectmode -width

Name:	height
Class:	Height
Switch:	-height

Specifies the desired height for the window, in lines. If zero or less, then the height for the window is dynamically sized to show all the elements in the listbox. If unspecified, then the height defaults to 10.

Name:	justify
Class:	Justify
Switch:	-justify

Specifies how to justify the text within the TextList. Valid values include left, right, and center. Default value is left.

Name:	selectMode
Class:	SelectMode
Switch:	-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. For more information on the different modes, refer to the Listbox docs under DEFAULT BINDINGS

Name:	width
Class:	Width
Switch:	-width

Specifies the desired width for the window in characters. If the font doesn't have a uniform width then the width of the character '0' is used in translating from character units to screen units. If zero or less, then the desired width for the window is made just large enough to hold all the elements in the listbox. If not specified, then width defaults to 20

Options inherited from Text widget:
-background -borderwidth -cursor -exportselection -foreground -font -foreground -highlightbackground, -highlightcolor -highlightthickness -insertbackground -insertborderwidth -insertofftime -insertontime -insertwidth -padx -pady -relief -selectbackground -selectborderwidth -setgrid -spacing1 -spacing2 -spacing3 -state -tabs -takefocus -wrap -xscrollcommand -yscrollcommand

Note: Because TextList is derived from ROText (which is derived from Text), it is possible to use any option which Text does. This is not always a good idea. In some cases, setting some of these options may damage the Listbox "look-and-feel" that was intended. Those options which are set to different defaults are listed below:

-cursor	the default cursor is left_ptr, instead of xterm in Text
-selectborderwidth	the default value is 1 instead of 0
-spacing3	the default value for spacing3 is 2 instead of 0
-state	the default value for state is disabled instead of normal. This is disabled so that the text cursor in the Listbox will not be visible, and is toggled during insert/delete methods. Keep this in mind if you are using the base class's methods to do inserts/deletes.
-wrap	the default value for wrap is none instead of word

(Refer to Tk::Text Documentation for more information on Text options)

DESCRIPTION

The TextList method creates a new window which mimics the look, feel, and functionality of a Listbox, but IS A ROText Widget. The end result is a Listbox which does everything a normal Listbox does, plus the ability to justify text, and change the appearance of individual list elements using tags

Because TextList was designed to be Listbox clone, all of it's methods use an indexing scheme which begins with 0, unlike the Text widget which starts at "1.0". To enhance Listbox, a few Text methods have also been overridden to take advantage of the 0-based indexing scheme, but most have not. The idea is that the text methods are all there, IF you require them, but they should only be used if there is some functionality you need which TextList does not already provide. If you should happen to need them, then use the following syntax:

  $textList->SUPER::method(...)

(In the case of Scrolled being used, you will need to extract a reference to the TextList in order to call the base class methods.)

In this way, you can treat the TextList as either a Listbox, with it's associated numbering scheme, or as a Text widget with Text widget-associated numbering scheme. As an example, the following code snippets are roughly equivalent:

  $textList->insert(1, $newElement);

  $textList->configure(-state => 'normal');
  $textList->SUPER::insert("2.0", $newElement . "\n");
  $textList->configure(-state => 'disabled');

Note that with any decision to use the base class methods comes the responsibility to deal with any complexity which TextList's native methods hide. In the above example, I added a carriage return, otherwise it would have appeared as though the 'new element' was prepended to any existing element at TextList position 1 (Text position 2.0).

METHODS

TextList supports all Listbox methods, so refer to the Listbox documents for information on those. The methods should work as described in the docs.

In addition, TextList supports a few Text methods set up to work with Listbox indexing, and a few other convenience methods. These methods are:

$textList->justify( value )

This method corresponds to the -justify option, and can be used as an alternative to the configure method to specify how the text in the TextList should be justified. Valid values are left, right, or center

$testList->selected( option )

Convenience method which performs operations on the set of elements which have been selected. Exact behavior depends on the option submitted. Currently, two forms are supported:

$textList ->selectedGet() => ( selected_element_array ) Returns an array of all the selected items
$textList ->selectedDelete() Deletes all the selected items from the list

$textList->setList( element_array )

This method is an alternative way of setting the list elements. It first deletes any elements which might be present then repopulates widget with newly submitted ones.

$textList->tag( option, ?tagName, index1, ?index2 )

This method is a Listbox version of the Text method tag, it uses the Listbox indexing scheme which starts at 0, instead of the Text index. The exact behavior of tag depends on the option submitted. Currently the following forms of tag are supported:

$textList->tagAdd( tagName, index1, ?index2 ) Associates the element at index1, and up to index2 (if specified), with the given tagname.
$textList->tagAddChar( tagName, element, index1, ?index2 ) Applies a tag to a specified list element, starting at char index1 and (optionally) until char index2. If index1 is not specified then the tag will only be applied to one character. Note: char indices begin with 0.
$textList->tagRemove( tagName, index1, ?index2 ) Removes tag name starting at index1, and up to index2 (if specified). This method is the oposite of tagAdd.
$textList->tagRemoveChar( tagName, element, index1, ?index2 ) Removes tag name at specified list element, starting at char index1, and up to index2 (if specified). This method is the oposite of tagAddChar.
Refer to the section on tagging for more details on usage.

TAGGING

Before looking at this section, refer to the Tagging section under Text. This explains the concept of tagging, and also provides the options available. In the TextList context, tags allow you to define styles for individual TextList elements. Events can be bound to tags as well, so this opens a wealth of new possibilities. Instead of repeating everything which is stated in clear terms in the Text docs, I'll provide an example of how TextList might make use of tags

use Tk;
use Tk::TextList;

my $mw = new MainWindow;

## Create a new TextList
my $textList = $mw->TextList(
    -height => 0,
    -width   => 0
)->pack;

## Add some elements to the TextList
$textList->insert('end', (qw/apples oranges cherries bananas grapes pears/));

##  Configure a tag to use and set a style. Note that you 
##  don't HAVE to define a tag or style before using it. You
##  can configure it at any time.
$textList->configure( 'myStyle', 
    -background => 'blue', 
    -foreground => 'white',
    -justify => 'center'
);

## OK, now Let's add two buttons to test the tagAdd 
## and tagRemove methods on the 'grape' element
$mw->Button(
    -text => 'add',
    -command => sub {
        $textList->tagAdd( 'myStyle', 4);
    }
)->pack;

$mw->Button(
    -text => 'remove',
    -command => sub {
        $textList->tagRemove('myStyle', 4);
    }
)->pack;

MainLoop;

DEFAULT BINDINGS

The default bindings for TextList are identical to those for Listbox. Refer to Listbox docs.

KNOWN BUGS/ISSUES

For some reason -exportselection doesn't seem to work correctly for TextList. In Listbox, this option allows there to be multiple listboxes on screen with selected item. This isn't handled directly in TextList - it's inherited from the Text widget. Unsure of how to proceed for now.

AUTHORS

Greg London
Rob Seegel < RobSeegel@aol.com>

VERSION

This documentation is applicable to the 3.53 version of TextList.

This document was written by Rob Seegel on 17 Oct 2000