TList(3pm)

📦
version 804.036 · 15 versions
, in debian trixie, ubuntu questing

💖 TList(3pm) — the Tk::TList glow-up 💖

okay bestie, gather round because we're doing the TList page today, and it is long — so this is part 1 of 3, and yes there's more coming, don't go anywhere 💅

This is from the User Contributed Perl Documentation, and the manual name is TList(3pm). Got it? Good. Let's go 🦋

✨ NAME ✨

Tk::TList — Create and manipulate Tix Tabular List widgets 👑

🌸 SYNOPSIS 🌸

    $tlist = $parent->TList(?options?);

that's it. that's the whole vibe. one line and you're a list-making icon ✨

🎀 SUPER-CLASS 🎀

None.

literally no parent class. self-made. no nepotism. main character energy fr fr 💅

🦋 STANDARD OPTIONS 🦋

these are the standard ones, the classics, the ones that come with the territory:

  • -background
  • -borderwidth
  • -class
  • -cursor
  • -foreground
  • -font
  • -height
  • -highlightcolor
  • -highlightthickness
  • -relief
  • -selectbackground
  • -selectforeground
  • -xscrollcommand
  • -yscrollcommand
  • -width
ngl if you want the deets on any of these, go read Tk::options. that's where the standard-option lore lives 📖

💜 WIDGET-SPECIFIC OPTIONS 💜

these are the ones that are hers. TList exclusives. the signature scent 🌸

  • -browsecmd — Name: browsecmd, Class: BrowseCmd. tells TList which perl/Tk callback to run when the user browses through the entries in the widget. it's the lil "she's looking 👀" notification.
  • -command — Name: command, Class: Command. the perl/Tk callback that fires when the user invokes a list entry. and by "normally" they mean: double-click it, or hit the Return key. that's the moment. that's the ✨invocation✨.
  • -foreground — Name: foreground, Class: Foreground, Alias: -fg. sets the default foreground color for the list entries. the ink of your whole situation 🖊️
  • -height — Name: height, Class: Height. how tall you want the window, measured in number of characters. yes, characters. it's giving vintage.
  • -itemtype — Name: itemType, Class: ItemType. the default type of display item for this TList widget. so when you call the insert methods, items get created in this type — unless you pass -itemtype yourself, in which case you're the boss 💅
  • -orient — Name: orient, Class: Orient. sets the order of tabularizing the list entries. two modes bestie:
    • set it to "vertical" and the entries go in a column, top to bottom. if they don't all fit in one column, the leftovers spill into the next column, and so on.
    • set it to "horizontal" and the entries go in a row, left to right. if they don't all fit in one row, the leftovers spill into the next row, and so on.
  • -padx — Name: padX, Class: Pad. the default horizontal padding for list entries. personal space, but sideways 🫶
  • -padx — Name: padY, Class: Pad. the default vertical padding for list entries.
okay so, real talk — the switch listed for padY is also -padx in this manual. we are reporting it exactly as it appears. no, we did not typo it. yes, we noticed. moving on 🙈
  • -selectbackground — Name: selectBackground, Class: SelectBackground. the background color for the selected list entries. the highlight reel 🎬
  • -selectborderwidth — Name: selectBorderWidth, Class: BorderWidth. a non-negative value saying how wide the 3-D border around selected items should be. the value can take any of the forms that Tk_GetPixels finds acceptable. non-negative, bestie. we do not do negative borders here 💀
  • -selectforeground — Name: selectForeground, Class: SelectForeground. the foreground color for the selected list entries. the chosen ones get the good text color 👑
  • -selectmode — Name: selectMode, Class: SelectMode. picks one of several styles for manipulating the selection. the value can technically be arbitrary, but the default bindings expect it to be one of single, browse, multiple, or extended. the default value is single. (single, and unbothered 💅)
  • -sizecmd — Name: sizeCmd, Class: SizeCmd. a perl/Tk callback that gets called whenever the TList widget changes its size. this one is genuinely useful — it's how you build those "user scroll bars when needed" features 🧚
  • -state — Name: state, Class: State. decides whether the TList command reacts to user actions at all.
    • "normal" — reacts to user actions in the normal way, everything works, slay.
    • "disabled" — it can only be scrolled. entries cannot be selected or activated. look, don't touch 🚫
  • -width — Name: width, Class: Width. how wide you want the window, in characters. width queen 👑

🌈 DESCRIPTION 🌈

The TList method makes a brand new window — the one given by the $widget argument — and turns it into a TList widget. you can pass the extra options we just went through on the command line, or stick them in the option database, to configure stuff like the cursor and the relief. customization era ✨

So what's the point of a TList? tabular data. displaying it. that's the whole gig. the list entries are honestly very similar to the entries in the Tk listbox widget — same family, different font. the main differences are:

  1. the TList widget can display its list entries in a two dimensional format, and
  2. you can use graphical images as well as multiple colors and fonts for the list entries.

so like… listbox but she went to art school 🎨

Every list entry is identified by an index, which can come in these forms:

index forms 🎀

  • number — an integer showing the position of the entry in the list. 0 means the first position, 1 means the second position, and so on. zero-indexed bestie, we know 💀
  • end — indicates the end of the listbox. careful though: for some commands this means just after the last entry, and for other commands it means the last entry. context is everything.
  • @x,y — indicates the element that covers the point in the listbox window specified by x and y (in pixel coordinates). and if no element covers that point? then the closest element to that point gets used. it's giving "nearest neighbor" but make it cute.

🧚 DISPLAY ITEMS 🧚

Every list entry in a TList widget is associated with a display item. that display item is what decides which visual information gets shown for that list entry. for the full roster of display items, go see Tk::DItem 📋

And when a list entry gets created by the insert command, the type of its display item is determined by the -itemtype option you pass to those commands. if you omit the -itemtype, then by default the type specified by this TList widget's own -itemtype option is used. so it always has a fallback, she's prepared 💅

✨ WIDGET METHODS ✨

okay so the TList method is what actually births a widget object for you 💖. That's the whole origin story.

Once you've got one, it plays nice with the configure and cget methods from Tk::options — those two are how you peek at and mess with all the options we listed above. Your widget also inherits every single method that the generic Tk::Widget class hands out, so you're not starting from zero, bestie 🫶.

And here's the extra menu — these are the methods that are specifically for TList widgets:

  • $tlist->anchorSet(index) — locks the anchor onto the list entry that index points at. The anchor is literally just the end of the selection that stays put while you're dragging a selection out with the mouse. One end moves, one end is the anchor. That's the vibe 💅
  • $tlist->anchorClear — yeets the anchor (if there even is one) out of this TList widget. Important, bestie: this only strips the surrounding highlights off the anchor entry. It does not touch whether that entry is selected. Two totally different things, don't get it twisted 🙈
  • $tlist->delete(from, ?to?) — deletes one or more list entries between the two entries given by the indices from and to. If you don't pass to, it just deletes the single entry named by from. bye felicia 💀
  • $tlist->dragsiteSet(index) — sets the dragsite to the list entry identified by index. The dragsite is what marks the source of a drag-and-drop action. ngl though: drag-and-drop functionality has not been implemented in Tix yet. So it's giving very much "coming soon" energy 😭
  • $tlist->dragsiteClear — removes the dragsite, if any, from this TList widget. Again, this only removes the surrounding highlights of the dragsite entry and does not affect its selection status. Same rule as the anchor, fr fr.
  • $tlist->dropsiteSet(index) — sets the dropsite to the list entry identified by index. The dropsite marks the target of a drag-and-drop action. And yeah… same sad story: drag-and-drop functionality has not been implemented in Tix yet 🫠
  • $tlist->dropsiteClear — removes the dropsite, if any, from this TList widget. Yep, only the surrounding highlights go; selection status stays exactly where it was. periodt.
  • $tlist->entrycget(index, option) — hands you back the current value of the configuration option named by option, for the entry identified by index. option can be any of the values that the insert method accepts, so go wild ✨
  • $tlist->entryconfigure(index, ?option?, ?value, option, value, ...?) — the query-or-modify queen for the config options of the list entry identified by index 👑
    • No option at all? You get a list describing every available option for index — see Tk_ConfigureInfo for how that list is formatted.
    • option given but no value? You get a list describing just that one named option, and it'll be identical to the matching sublist of the big "no option" return.
    • One or more option-value pairs? Then it modifies the given option(s) to have the given value(s), and the method returns an empty string.
    • option can be any of the values the insert method accepts. And here's the tea: the exact set of options depends on the value of the -itemtype option that was passed to the insert method back when this list entry was created. So it's not one-size-fits-all 🦋
  • $tlist->insert(index, ?option, value, ...?) — creates a brand new list entry at the position indicated by index. These are the configuration options you can feed it:
    • -itemtype => type — says what type of display item gets displayed for this new list entry. type has to be a valid display item type. Currently the available display item types are image, imagetext, text, and $widget. Skip this option and it just defaults to whatever type this TList widget's own -itemtype option says 💫
    • -state => state — says whether this entry can be selected or invoked by the user. Must be either normal or disabled. That's the whole menu, no substitutions.
    • -data => data — arbitrary data to be associated with the entry (a perl scalar value). It's your lil secret pocket 🎀

The insert method also accepts additional configuration options, and those are for configuring the display item that's tied to this list entry. Which set of extra options you get depends on the type of display item given by the -itemtype option. Please see Tk::DItem for the list of configuration options for each of the display item types — that's where the receipts live 🧚

  • $tlist->info(option, arg, ...) — queries info about the TList widget. option can be one of these:
    • $tlist->info(anchor, index) — returns the index of the current anchor, if there is one, of the TList widget. If the anchor isn't set, you get the empty string back. no anchor, no answer 🙈
    • $tlist->info(dragsite, index) — returns the index of the current dragsite, if any, of the TList widget. If the dragsite isn't set, empty string.
    • $tlist->info(dropsite, index) — returns the index of the current dropsite, if any, of the TList widget. If the dropsite isn't set, empty string.
    • $tlist->info(selection) — returns a list of the selected elements in the TList widget. If nothing is selected, you get an empty string. #nobodyselected 💀
  • $tlist->nearest(x, y) — you hand it an (x,y) coordinate that lives inside the TList window, and it hands you back the index of the TList element nearest to that coordinate. It's a proximity detector, bestie 📍
  • $tlist->see(index) — adjusts the view in the TList so that the entry given by index is visible. If that entry is already visible then the command does absolutely nothing; otherwise TList scrolls to bring the element into view at the edge it's nearest to. It's not extra, it's just helpful 💅
  • $tlist->selection(option, arg, ...) — this is the command for adjusting the selection inside a TList widget. It's got several forms depending on option:
    • $tlist->selectionClear(?from?, ?to?) — no extra arguments at all? It deselects all of the list entrie(s) in this TList widget. Only from given? Only the list entry identified by from gets deselected. Both from and to given? It deselects all the list entrie(s) between from and to, inclusive, without touching the selection state of entries outside that range. precise, not messy ✨
    • $tlist->selectionIncludes(index) — returns 1 if the list entry indicated by index is currently selected; returns 0 otherwise. simple math, slay.
    • $tlist->selectionSet(from, ?to?) — selects all the list entrie(s) between from and to, inclusive, without affecting the selection state of entries outside that range. When only from is given, only the list entry identified by from is selected. 🫶
  • $tlist->xview(args) — this one queries and changes the horizontal position of the information in the widget's window. It can take any of these forms:
    • $tlist->xview — returns a list with two elements. Each element is a real fraction between 0 and 1, and together they describe the horizontal span that's visible in the window. Like, if the first element is 0.2 and the second is 0.6, then 20% of the TList entry is off-screen to the left, the middle 40% is visible in the window, and 40% of the entry is off-screen to the right. These are the exact same values that get passed to scrollbars via the -xscrollcommand option 🔥
    • $tlist->xview(index) — adjusts the view in the window so the list entry identified by index is aligned to the left edge of the window. snap it into place.
    • $tlist->xviewMoveto(fraction) — adjusts the view so that fraction of the total width of the TList is off-screen to the left. fraction must be a fraction between 0 and 1.
    • $tlist->xviewScroll(number, what) — shifts the view left or right according to number and what. number must be an integer. what must be either units or pages, or an abbreviation of one of those. If what is units, the view adjusts left or right by number character units (that's the width of the 0 character) on the display; if it's pages, the view adjusts by number screenfuls. If number is negative, characters farther to the left become visible; if it's positive, characters farther to the right become visible. directions matter, bestie ⭐
  • $tlist->yview(?args?) — the vertical sibling 🦋. This command queries and changes the vertical position of the entries in the widget's window. Forms:
    • $tlist->yview — returns a list with two elements, both real fractions between 0 and 1. The first element gives the position of the list element at the top of the window, relative to the TList as a whole (so 0.5 means it's halfway through the TList, for example). The second element gives the position of the list entry just after the last one in the window, relative to the TList as a whole. Same values that get passed to scrollbars via the -yscrollcommand option 💖
    • $tlist->yview(index) — adjusts the view so the list entry given by index is displayed at the top of the window.
    • $tlist->yviewMoveto(fraction) — adjusts the view so the list entry given by fraction appears at the top of the window. fraction is a fraction between 0 and 1; 0 indicates the first entry in the TList, 0.33 indicates the entry one-third of the way through the TList, and so on. math but make it cute ✨
    • $tlist->yviewScroll(number, what) — adjusts the view up or down according to number and what. number must be an integer. what must be either units or pages. If what is units, the view adjusts up or down by number lines; if it's pages, the view adjusts by number screenfuls. If number is negative then earlier entries become visible; if it's positive then later entries become visible. scroll responsibly 💅

💖 BINDINGS 💖

Okay bestie, here's the tea on how mouse stuff works in this widget, and it's all about what you set -selectmode to. Let's go number by number, no skips. 🫶

  1. [1] — If the -selectmode is "browse", when the user drags the mouse pointer over the list entries, the entry under the pointer gets highlighted, and the -browsecmd procedure gets called with one parameter: the index of the highlighted entry. Only one entry can be highlighted at a time. The -command procedure gets called when the user double-clicks on a list entry. 🖱️✨
  2. [2] — If the -selectmode is "single", the entries only get highlighted by mouse <ButtonRelease-1> events. When a new list entry is highlighted, the -browsecmd procedure gets called with one parameter indicating the highlighted list entry. The -command procedure gets called when the user double-clicks on a list entry. 💅
  3. [3] — If the -selectmode is "multiple", when the user drags the mouse pointer over the list entries, all the entries under the pointer get highlighted. However, only a contiguous region of list entries can be selected. When the highlighted area changes, the -browsecmd procedure gets called with an undefined parameter. It is the responsibility of the -browsecmd procedure to find out the exact highlighted selection in the TList. The -command procedure gets called when the user double-clicks on a list entry. 🔥
  4. [4] — If the -selectmode is "extended", when the user drags the mouse pointer over the list entries, all the entries under the pointer get highlighted. The user can also make disjointed selections using <Control-ButtonPress-1>. When the highlighted area changes, the -browsecmd procedure gets called with an undefined parameter. It is the responsibility of the -browsecmd procedure to find out the exact highlighted selection in the TList. The -command procedure gets called when the user double-clicks on a list entry. 👑

🌈 EXAMPLE 🌈

This example demonstrates how to use an TList to store a list of numbers: 🍓

use strict;
use Tk ();
use Tk::TList;

my $mw = Tk::MainWindow->new();
my $image = $mw->Getimage('folder');
my $tlist = $mw->TList(-orient => 'vertical');
for my $text ( qw/one two three four five six seven eight nine/ ) {
    $tlist->insert('end',
             -itemtype=>'imagetext', -image=>$image, -text=>$text);
}

$tlist->pack(-expand=>'yes', -fill=>'both');

Tk::MainLoop;

🦋 SEE ALSO 🦋

  • Tk::options
  • Tk::Widget
  • Tk::DItem
  • Tk::HList
  • Tk::TixGrid

⭐ KEYWORDS ⭐

  • Tix(n)
  • Tabular Listbox
  • Display Items

And that's the whole vibe, bestie 💖 this page is from perl v5.40.1, dated 2025-04-13, and it's TList(3pm) — periodt. ✨

📦 where this page comes from