TixGrid(3pm)

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

💖 Tk::TixGrid — the TixGrid era 💖

okay bestie, sit down, hydrate, because we're about to talk about Tk::TixGrid, from the TixGrid(3pm) page (User Contributed Perl Documentation, iykyk). This is part 1 and it's giving main character widget energy.

✨ NAME ✨

Tk::TixGrid — create and manipulate Tix Grid widgets. that's the whole vibe. 🫶

🌸 SYNOPSIS 🌸

$tixgrid = $parent->TixGrid?(options)?;

that's it. that's the whole spell. look at her go ✨

🦋 DESCRIPTION 🦋

so basically this widget is the blueprint for "spread sheet"-coded interfaces — the whole point is that it shows its content in a two-dimensional "grid" of cells, like a little spreadsheet situation but make it Perl/Tk. 🔥

every single cell can hold one Tix display item, and that item can be in text, graphics, or other formats. if you wanna know more about Tix display items, go read Tk::DItem — she has the lore. because these "items" don't have to be "windows", you can handle huge grids without devouring all of your display system resources. no cap. it's actually so efficient of her. 💅

individual cells, or whole groups of cells, can be formatted with a wide range of attributes — color, relief, border, the whole glam routine. BUT. and this is the tea ☕ — because the widget is built to handle large grids, the mechanisms to pull that off are lower level and way more callback-oriented than other widgets. the assumption here is that to avoid storing display details for a giant number of cells, the data gets re-computed as needed. so it's lazy in the most iconic way possible. ✨

now, real talk: the port of the Tix C code and some of the bindings to perl/Tk is done, but it still needs further work. 🚧 in several places the intent of the Tix code isn't understood yet — like, for example, the 'edit' interface is clearly intended for spread-sheet-like cell content editing in an auxillary "entry" widget or similar, but how that should actually work is not yet clear. so we're all just vibing with the mystery. 🙈

the TixGrid method creates a new TixGrid window and returns a blessed reference of this TixGrid widget. extra options (described below, keep scrolling bestie) may be specified on the command line or in the option database to configure aspects of the TixGrid widget. 💖

👑 STANDARD OPTIONS 👑

here's the classic lineup, the standard-issue queens:

-background      -borderwidth      -cursor      -font      -foreground
     -height      -highlightbackground      -highlightcolor
     -highlightthickness      -padx      -pady      -relief
     -selectbackground      -selectborderwidth      -selectforeground
     -state      -takefocus      -width      -xscrollcommand
     -yscrollcommand

for the details of these standard options, go peek at Tk::options. she explains all of them, slay. 🎀

💅 WIDGET-SPECIFIC OPTIONS 💅

these are the options that make TixGrid her. 🌈

  • Name: browseCmd — Class: BrowseCmd — Switch: -browsecmd

if you define this, it gives you a perl/Tk callback that fires when the user browses a grid cell (normally that's when the user clicks on an entry). when this callback gets called, it's passed two additional parameters: x y, where (x,y) is the location of the cell that just got clicked. so you always know exactly which little cell caught the vibe. 👀

  • Name: Command — Class: Command — Switch: -command

if you define this, it gives you a perl/Tk callback that fires when the user double-clicks a grid cell. when it's called, it gets two additional parameters: x y, where (x,y) is the location of the cell that just got clicked. double-click behavior, unlocked. 🔥

  • Name: editDoneCmd — Class: EditDoneCmd — Switch: -editdonecmd

if you define this, it gives you a perl/Tk callback that fires when the user has edited a grid cell. when it's called, it gets two additional parameters: x y, where (x,y) is the location of the cell that just got edited. so it's the little "ok done, edited ✍️" notification of your dreams.

  • Name: editNotifyCmd — Class: EditNotifyCmd — Switch: -editnotifycmd

if you define this, it gives you a perl/Tk callback that fires when the user tries to edit a grid cell. when it's called, it gets two additional parameters: x y, where (x,y,) is the location of the cell. this callback should return a boolean value: true means the cell is editable, false means it is not. yes, she's asking permission first. consent queen. 🫶

  • Name: FloatingCols — Class: floatingCols — Switch: -floatingcols

defines the number of extra columns beyond the existing grid that can be brought into view by scrolling. extra columns, on demand. ✨

  • Name: FloatingRows — Class: floatingRows — Switch: -floatingrows

defines the number of extra rows beyond the the existing grid that can be brought into view by scrolling. yes, the original says "the the". we don't fix, we stan. 💜

  • Name: formatCmd — Class: FormatCmd — Switch: -formatcmd

if you define this, it gives you a perl/Tk callback that fires when the grid cells need to be displayed on the screen. its primary purpose is to draw the background of the region before the cells get rendered on top. normally you'd achieve that by calling formatGrid or formatBorder (see below, bestie). but other uses can be made of this low-level callback — for example, it can be used to "lazily" populate the grid by calling the set method only as cells come into view. lazy-populate icon behavior, honestly. 🌸

when this callback is called, it's passed five additional parameters: type x1 y1 x2 y2.

x1 y1 x2 y2 gives the extent of the region that needs formatting.

type gives the logical type of the region in the grid. it may be one of the following:

  • x_margin — the horizontal margin.
  • y_margin — the vertical margin.
  • s_margin — the area in the top left corner where the horizontal and vertical margins are joined.
  • main — the main body, i.e. all the cells that do not fall into the above three types.
  • Name: leftMargin — Class: LeftMargin — Switch: -leftmargin

gives the width of vertical margin in cells (columns). a zero indicates that no vertical margin exists. a positive value N indicates that the first N columns are "labels" and are always displayed and not scrolled. they're the frozen-header queens, they never leave. 👑

  • Name: itemType — Class: ItemType — Switch: -itemtype

default item type for cells. simple, clean, iconic.

  • 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 single. pick your fighter. 💅

  • Name: selectUnit — Class: SelectUnit — Switch: -selectunit

specifies the selection unit. valid values are cell, column or row. so you can select like a little individual cell, or go full column, or full row. range of drama available. 🎀

  • Name: sizeCmd — Class: SizeCmd — Switch: -sizecmd

callback is called (with no extra arguments) when grid sizes are re-computed. for example if the window changes size, a different font is specified, etc. it's called just after scrollbars (if present) are updated. so the order is: scrollbars get their glow-up first, then this callback. noted, bestie. 📝

  • Name: topMargin — Class: TopMargin — Switch: -topmargin

gives the width of horizontal margin in cells (rows). a zero indicates that no horizontal margin exists. a positive value N indicates that the first N rows are "labels" and are always displayed and not scrolled. frozen top rows, forever holding it down. ⭐

okay that's part 1 and there's still more coming, so don't go anywhere — the rest of the glow-up is on the way. 💖✨

💖 WIDGET METHODS 💖

okay so the TixGrid method makes a TixGrid widget and hands you back a blessed reference to it. 🎀 That reference is literally your key to doing stuff to the widget, and it's got one general shape:

$tixgrid->method?(arg, arg, ...)?

the args decide exactly how the method behaves, bestie. no cap.

This object also supports the configure and cget methods from Tk::options, which you can use to peek at and change the options we talked about earlier. It also inherits everything from the generic Tk::Widget class. 🫶

And here are the extra methods you get with TixGrid widgets:

  • $tixgrid->anchorGet(x, y)
  • $tixgrid->anchorSet(x, y)
  • $tixgrid->anchorClear — these three mess with the anchor cell of the TixGrid widget. The anchor cell is the end of the selection that stays fixed while the user drags out a selection with the mouse. 📌
  • ($bd,$col,$row) = $tixgrid->bdtype(x,y ?,xDelta,yDelta?) — figures out whether the screen (pixel) position x,y is sitting in a border. super useful for changing the mouse cursor when the user points at a border — like, to hint that the border can be adjusted interactively. 💅

If you are in a border, you get back a list of three elements. The first one is 'xy', 'x' or 'y', and the next two are integers. (What those values actually mean is not understood — they seem to indicate which column and row of the border the screen position corresponds to?)

If you're not in a border, you get an empty list. 🙈

  • $tixgrid->delete(dim, from?, to?)
  • $tixgrid->deleteColumn(from?, to?)
  • $tixgrid->deleteRow(from?, to?) — dim can be row or column. If to isn't given, it deletes a single row (or column) at position from. If to is given, it deletes the whole range of rows (or columns) from position from through to. 💀 gone. deleted.
  • $tixgrid->dragsite(option, x, y)
  • $tixgrid->dropsite(option, x, y) — Tcl/Tix has (or was going to have) Drag&Drop support. What this means for perl/Tk is not clear yet. 😭
  • $tixgrid->editApply — if any cell is being edited, it de-highlights the cell and applies the changes. ✨
  • $tixgrid->editSet(x, y) — highlights the cell at (x,y) for editing, but only if the -editnotify callback returns true for this cell.
  • $tixgrid->entrycget(x, y, '-option')
  • $tixgrid->entryconfigure(x, y?, -option??=>value, -option=>value, ...?) — these give you a configure-style interface to cells in the grid. The -options you can use depend on the item type of the cell. 🦋
  • $tixgrid->formatBorder(x1,y1, x2,y2, options);
  • $tixgrid->formatGrid(x1,y1, x2,y2, options); — the formatBorder and formatBorder methods can only be called by the -formatcmd callback of the tixGrid widget. They draw the background of the region described by x1,y1, x2,y2 according to the options you supply. One call to the -formatcmd callback can make multiple calls to formatBorder and/or formatBorder for different sub-regions. 🎨

formatBorder draws the background using Tk relief style; formatGrid also draws grid lines between the cells. It only makes sense to call one or the other for a particular sub-region, since one will over-write the other.

The options allowed are:

  • -background / -bg
  • -borderwidth / -bd
  • -filled
  • -relief
  • -selectbackground
  • -xoff
  • -xon
  • -yoff
  • -yon

The -xon/-xoff and -yon/-yoff options are obscure. If anyone can figure out how to do something interesting given what pTk/tixGrFmt.c is doing with them please let Nick know!. 😭

  • $tixgrid->geometryinfo(?width, height?) — returns a list of four values — two sets of two floating point numbers. First set is the scrollbar fractions for the x direction, second set is the scrollbar fractions for the y direction. If width and height are specified then the fractions are based on as if the window size was of the specified size (in pixels, but not allowing normal GetPixels units). Otherwise the fractions are based on the current size of the window.

Usage obscure. 💀

  • $tixgrid->index(xcoord, ycoord) — returns (x, y) of the entry at position ($coordx, $coordy). Either coordinate may be 'max', which is the largest existing entry in that direction; 'end', which is one beyond the largest existing entry; or a number. (This is how you find out how big the grid is.) 👑
  • $tixgrid->infoBbox(x,y) — returns the pixel bounding box of the cell at x,y.
  • $tixgrid->infoExists(x,y) — returns true if there's an item in the cell at x,y. It throws an exception (dies 💀) if x,y is outside the grid — this may change (Nick doesn't like it).
  • $tixgrid->move(dim, from, to, offset)
  • $tixgrid->moveColumn(from, to, offset)
  • $tixgrid->moveRow(from, to, offset) — dim may be row or column. Moves the range of rows (or columns) from position from through to by the distance indicated by offset. For example, $tixgrid->moveRow(2, 4, 1) moves the rows 2,3,4 to rows 3,4,5. 🚚
  • $tixgrid->nearest(x, y) — screen pos (pixels) to entry (nx,ny) translation.
  • $tixgrid->selectionAdjust(x1, y1 ?,x2, y2?)
  • $tixgrid->selectionClear(x1, y1 ?,x2, y2?)
  • $tixgrid->selectionIncludes(x1, y1 ?,x2, y2?)
  • $tixgrid->selectionSet(x1, y1 ?,x2, y2?)
  • $tixgrid->selectionToggle(x1, y1 ?,x2, y2?) — selection support methods — probably buggy. 😭

x1 (y1) has not to be greater than x2 (y2), but only x2 and y2 can be 'max'.

BUG: selectionIncludes: has no visible effect (as in Tix). Eh???
BUG: selectionClear: only works for 0, 0, max, max (as in Tix). Eh???

When x2, y2 are not given they default to x1, y1, respectively.

  • $tixgrid->set(x, y?, -itemtype=>type??, -option=>value, ...?) — creates a new display item at the cell at (x,y). The optional -itemtype parameter gives the type of the display item. An additional list of option-value pairs specify options of the display item. If a display item already exists at this cell, the old item will be deleted automatically. 🌸
  • $tixgrid->size(dim, index?, -option??=>value, ...?)
  • $tixgrid->sizeColumn(index?, -option??=>value, ...?)
  • $tixgrid->sizeRow(index?, -option??=>value, ...?) — queries or sets the size of the row or column given by dim and index. Dim may be row or column. Index may be any non-negative integer that gives the position of a given row (or column). Index can also be the string default; in this case, this method queries or sets the default size of all rows (or columns). When no option-value pair is given, this method returns a list containing the current size setting of the given row (or column). When option-value pairs are given, the corresponding options of the size setting of the given row are changed. -option may be one of the following:
    • -pad0 => pixels — Specifies the paddings to the left of a column or the top of a row.
    • -pad1 => pixels — Specifies the paddings to the right of a column or the bottom of a row.
    • -size => val — Specifies the width of a column or the height of a row. Val may be: auto — the width of the column is set the widest cell in the column; a valid Tk screen distance unit (see Tk_GetPixels); or a real number following by the word chars (e.g. 3.4chars) that sets the width of the column to the given number of characters. 🎀
  • $tixgrid->sort(dimension, start, end, ?args ...?) — ?docu here? (not supported on Win* OSs up to now)
  • $tixgrid->unset(x, y) — clears the cell at (x,y) by removing its display item. 🧹
  • $tixgrid->xview — Normal horizontal scrollbar method.
  • $tixgrid->yview — Normal vertical scrollbar method.

🌈 BINDINGS 🌈

To be done — only the most obvious basic bindings work. The Tcl/Tix code was coded as a "state machine" which is not easy to follow. 💀 iykyk.

🦋 SEE ALSO 🦋

Tk::DItem Tk::callbacks Tk::FloatEntry

💅 BUGS 💅

Tcl/Tix was/is not finished and both the C code and the bindings of TixGrid have some bugs. 😭 periodt.

⭐ KEYWORDS ⭐

tix, tixgrid, table, display item, spreadsheet

okay bestie that's the whole thing!! 💖 this page ships with perl v5.40.1 and is dated 2025-04-13, so go forth and grid responsibly, you absolute icon 👑✨🫶

📦 where this page comes from