MLColumn Package Info
Tutorial | FAQ | Changes/Bug fixes
Version:1.10
DSLIP:bdpOp
Author:Hans J. Helgesen
Maintainer:Rob Seegel
Package:MListbox
Platforms:Linux
Unix
Windows

HEIRARCHY

Widget // Frame // MLColumn


DESCRIPTION

MLColumn is a composite widget used to display the contents of one column of data (including the header) within the MListbox widget. This widget is not meant to be used outside of the MListbox widget, and it should never be instatiated by itself. The tight coupling between the two prevents it from being useful in any other capacity. It is documented here only because it can be accessed and returned by some MListbox's methods, and it and it's subwidgets can be configured directly if necessary.


COMPONENTS

  Subwidgets:
Name:frame
Class:Frame
Name:heading
Class:HButton
Name:listbox
Class:CListbox
 
Name:separator
Class:Frame


OPTIONS

  MListbox defined:
-background
-columns
-configurecommand
-font
-foreground
-moveable
-resizeable
-selectbackground
-selectforeground
-selectmode
-separatorcolor
-separatorwidth
-sortable
-takefocus
-yscrollcommand

  Inherited from Frame:
-borderwidth
-height
-highlightbackground
-highlightcolor
-highlightthickness
-relief
-width

Name:background
Class:Background
Switch:-background
Alias:-bg
Sets the background color for the base widget, the internal Pane, and the default background color for all columns. If configured after initial construction, this option will override the background options for all columns.
Switch:-columns
Defines the columns in the widget. This option takes an array reference as its value and can only be used during widget creation. After creation, methods can be used to modify each columns' configuration. Refer to the adding columns section in the tutorial.
Switch:-configurecommand
Alias:-configcmd
The callback which is passed to this option will be called whenever the layout of the widget has changed due to user interaction (ie. a user resizing a column by dragging separator or moving a column by dragging a column header would trigger this callback
Switch:-font
sets the default font to be used throughout the MListbox. This font is used as a default at creation time and can be overridden. If set after creation, then this value overrides all other fonts used within MListbox.
Switch:-foreground
Aliases:-foreground
Sets the default foreground (font) color for MListbox and all the columns when set at creation time. When set after creation time, it overrides any variant settings within any of the columns.
Name:moveable
Class:Moveable
Switch:-moveable
Boolean value which enables or disables moveable columns. A value of 1 enables all columns to be reordered by allowing drag-and-drop of column headers. A value of 0 disables this feature.
Name:resizeable
Class:Resizeable
Switch:-resizeable
Boolean value that determines whether or not individual columns can be resized by dragging on their separator. A setting of 1 enables resizing for all columns, and setting of 0 disables it.
Name:selectBackground
Class:SelectBackground
Switch:-selectbackground
Alias:-selectbg
Specifies background color used for rows that have been selected.
Name:selectForeground
Class:SelectForeground
Switch:-selectforeground
Alias:-selectfg
Sets a foreground (font) color used for rows that have been selected. Defaults to Black for Unix and SystemHighlightText for Win32.
Name:selectMode
Class:SelectMode
Switch:-selectmode
Determines the type of selection allowed within MListbox. Valid choices include: single, browse, multiple, and extended. To get a description of each of these modes, refer to the Tk::Listbox documentation. The default setting is browse.
Name:separatorColor
Class:SeparatorColor
Switch:-separatorcolor
Sets the default color to be used for the separator bar (the bar that is dragged by the user to resize a column) when set at widget creation time. If set after creation time, it will replace the separator color for all columns.
Name:separatorWidth
Class:SeparatorWidth
Switch:-separatorwidth
Name:sortable
Class:Sortable
Switch:-sortable
Name:takeFocus
Class:TakeFocus
Switch:-takefocus
Name:yScrollCommand
Class:ScrollCommand
Switch:-yscrollcommand


METHODS

  MListbox defined:
void activate( index )
void bindColumns( sequence, callback )
void bindRows( sequence, callback )
void bindSeparators( sequence, callback )
arrayref columnConfigure( index, ?option => value, ... )
(MLColumn) columnGet( first, ?last )
void columnHide( first, ?last )
integer columnIndex( index )
MLColumn columnInsert( index, ?option => value, ... )
void columnPack( array )
array columnPackInfo()
void columnShow( index, ?option => value, ... )
array curselection()
void delete( first, ?last )
arrayref get( first, ?last )
arrayref getRow( index )
void index( descending, index, ... )
void sort( descending, index, ... )


addItem( string, ?option => value, ... )

Appends a new List item to be used in the Popup Listbox. string is a scalar variable that is displayed in the Listbox. This method takes two options: -selected and -value.

Options:

-selected => selected
Where selected is a boolean value (true/yes/1) and determines whether or not the list item is the select item within the JComboBox. The default value for this is false and any subsequent call that uses this option, overrides previous ones.

-value => value
where value is an alternate string associated with the List Item for times when it's desirable to have a value other than the one displayed (I find it to be useful for database applications)

Example:

$jcb->addItem('ALASKA', -value => 'AK', -selected => 1);


clearSelection()

Clears the currently selected item in the JComboBox if one is selected


getItemIndex( string, ?option => value, ... )

Searches the JCombobox for the first item that matches the given string and returns that item's index. If no match is found, the method returns undef. This method has two optional parameters: -mode and -type.

Options:

-type => type
Where type is either name, the displayed text, or value, the alternate value associated with the item. If an item in the JComboBox does not have a value defined, then that item's name is used. The default type is name.

-mode => mode
where mode affects the how the given string is compared to a list item. Values include: exact, usecase, and ignorecase. In the exact mode, the string must completely match a list item, including it's case. In usecase mode, the string must match the beginning of the list item, including it's case, and in ignorecase mode, the string must match the beginning of the list item, but doesn't care about the case. The default mode is exact.

Example:

The following would return the index of the first matching list item where AK completely matched that item's value.
my $index = $jcb->getItemIndex('AK', -type => 'value');


getItemCount()

Returns the number of list items stored in the JComboBox.


getSelectedIndex()

Returns the index of the current selected item or undef if there isn't one selected.


getSelectedValue()

Returns the value of the current selected item or undef if there isn't one selected. In the case of an editable JComboBox, if no items are selected, then the text in the entry is returned.


getItemNameAt( index )

Returns the string displayed in the listbox at the given index.


getItemValueAt( index )

Returns the alternate text associated with the list item at the given index if it's set. Otherwise, will return the the displayed item.


hidePopup()

Causes the popup listbox to be withdrawn from the screen, unmapping it. Hiding and showing the popup listbox is generally handled by various event handlers, but is available for use in custom handlers or other use.


index( index )

Returns the integer index value that corresponds to index. If index is end then return value is a count of the number of elements in the listbox (not the index of the last element).


insertItemAt( index, string, ?option => value, ... )

Inserts a new list item into the JComboBox at the specified index. string is a scalar variable that is displayed in the Listbox. This method takes two options: -selected and -value. Refer to this section on indices in the Listbox documention.

Options:

-selected => selected
Where selected is a boolean value (true/yes/1) and determines whether or not the list item is the select item within the JComboBox. The default value for this is false and any subsequent call that uses this option, overrides previous ones.

-value => value
where value is an alternate string associated with the List Item for times when it's desirable to have a value other than the one displayed (I find it to be useful for database applications)

Example:

The following example produces exactly the same result as the example given for addItem
$jcb->insertItemAt('end', 'ALASKA', -value => 'AK', -selected => 1);

popupIsVisible()

Returns 1 if the popup is mapped, 0 if it isn't


removeAllItems()

Completely removes all list items from the JComboBox, and clears any selected item if present.


removeItemAt( index )

Deletes a single list item from the JCombobox at the specified index.


see( index )

Adjusts the JComboBox so that the list item indicated by the given index is visible. If the Listbox is hidden, it will be made visible, and the the list will shift so that the item is viewable as necessary.


setSelectedIndex( index )

Selects the list item that exists at the given index.


showPopup()

Displays the popup listbox ( normally triggered by the JComboBox button )


This document was updated by Rob Seegel on 2 Jun 2001