1TixGrid(3)            User Contributed Perl Documentation           TixGrid(3)
2
3
4

NAME

6       Tk::TixGrid - Create and manipulate Tix Grid widgets
7

SYNOPSIS

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

DESCRIPTION

12       This widget is intended as the basis of "spread sheet" like interfaces.
13       The widget displays its contents in a two dimensional "grid" of cells.
14       Each cell may contain one Tix display item, which may be in text,
15       graphics or other formats. See Tk::DItem for more information about Tix
16       display items. Because these "items" need not be "windows" large grids
17       can be handled  without consuming excessive display system resources.
18
19       Individual cells, or groups of cells, can be formatted with a wide
20       range of attributes, such as its color, relief and border. However
21       because the widget is intended to handle large grids the mechanisms to
22       achieve these are lower level, and more callback oriented than for
23       other widgets. The assumption is that to avoid storing display details
24       of a large number of cells, the data will be re-computed as needed.
25
26       The port of Tix C code and some of the bindings to perl/Tk is done but
27       still need further work. In several places the intent of the Tix code
28       is not yet understood. For example the 'edit' interface is clearly
29       intended for spread-sheet like cell content editing in an auxillary
30       "entry" widget or similar, but how that should work is not yet clear.
31
32       The TixGrid method creates a new TixGrid window and returns a blessed
33       reference of this TixGrid widget.  Additional options, described below,
34       may be specified on the command line or in the option database to
35       configure aspects of the TixGrid widget.
36

STANDARD OPTIONS

38       -background      -borderwidth      -cursor      -font      -foreground
39            -height      -highlightbackground      -highlightcolor
40            -highlightthickness      -padx      -pady      -relief
41            -selectbackground      -selectborderwidth      -selectforeground
42            -state      -takefocus      -width      -xscrollcommand
43            -yscrollcommand
44
45       See Tk::options for details of the standard options.
46

WIDGET-SPECIFIC OPTIONS

48       Name:     browseCmd
49       Class:    BrowseCmd
50       Switch:   -browsecmd
51           If defined, gives a perl/Tk callback to be executed when the user
52           browses a grid cell (This is normally the case when the user clicks
53           on an entry).  When this callback is called, it is passed with two
54           additional parameters: x y, where (x,y) is the location of the cell
55           that has just been clicked.
56
57       Name:     Command
58       Class:    Command
59       Switch:   -command
60           If defined, gives a perl/Tk callback to be executed when the user
61           double-clicks a grid cell.  When this callback is called, it is
62           passed with two additional parameters: x y, where (x,y) is the
63           location of the cell that has just been clicked.
64
65       Name:     editDoneCmd
66       Class:    EditDoneCmd
67       Switch:   -editdonecmd
68           If defined, gives a perl/Tk callback to be executed when the user
69           has edited grid cell. When this callback is called, it is passed
70           with two additional parameters: x y, where (x,y) is the location of
71           the cell that has just been edited.
72
73       Name:     editNotifyCmd
74       Class:    EditNotifyCmd
75       Switch:   -editnotifycmd
76           If defined gives a perl/Tk callback to be executed when the user
77           tries to edit a grid cell.  When this callback is called, it is
78           passed with two additional parameters: x y, where (x,y,) is the
79           location of the cell. This callback should return a boolean value:
80           true indicates that the cell is editable and false otherwise.
81
82       Name:     FloatingCols
83       Class:    floatingCols
84       Switch:   -floatingcols
85           Defines the number of extra columns beyond the existing grid that
86           can be brought into view by scrolling.
87
88       Name:     FloatingRows
89       Class:    floatingRows
90       Switch:   -floatingrows
91           Defines the number of extra rows beyond the the existing grid that
92           can be brought into view by scrolling.
93
94       Name:     formatCmd
95       Class:    FormatCmd
96       Switch:   -formatcmd
97           If defined, gives a perl/Tk callback to be executed when the grid
98           cells need to be displayed on the screen.  Its primary purpose is
99           to draw the background of the region before the cells are rendered
100           on top. This is normally achieved by calling formatGrid or
101           formatBorder (see below).  However other uses can  be made of this
102           low-level callback. For example it can be used to "lazily" populate
103           the grid by calling the set method only as cells come into view.
104
105           When this callback is called, it is passed with five additional
106           parameters: type x1 y1 x2 y2.
107
108           x1 y1 x2 y2 gives the extent of the region that needs formatting.
109
110           type gives the logical type of the region in the grid. It may be
111           one of the following.
112
113           x_margin
114                   The horizontal margin.
115
116           y_margin
117                   The vertical margin.
118
119           s_margin
120                   The area in the top left corner where the horizontal and
121                   vertical margins are joined.
122
123           main    The main body i.e. all the cells that do not fall into the
124                   above three types.
125
126       Name:     leftMargin
127       Class:    LeftMargin
128       Switch:   -leftmargin
129           Gives the width of vertical margin in cells (columns).  A zero
130           indicates that no vertical margin exists. A positive value N
131           indicates that first N columns are "labels" and are always
132           displayed and not scrolled.
133
134       Name:     itemType
135       Class:    ItemType
136       Switch:   -itemtype
137           Default item type for cells.
138
139       Name:     selectMode
140       Class:    SelectMode
141       Switch:   -selectmode
142           Specifies one of several styles for manipulating the selection.
143           The value of the option may be arbitrary, but the default bindings
144           expect it to be either single, browse, multiple, or extended; the
145           default value is single.
146
147       Name:     selectUnit
148       Class:    SelectUnit
149       Switch:   -selectunit
150           Specifies the selection unit. Valid values are cell, column or row.
151
152       Name:     sizeCmd
153       Class:    SizeCmd
154       Switch:   -sizecmd
155           Callback is called (with no extra arguments) when grid sizes are
156           re-computed. For example if window changes size, a different font
157           is specified etc.
158
159           It is called just after scrollbars (if present) are updated.
160
161       Name:     topMargin
162       Class:    TopMargin
163       Switch:   -topmargin
164           Gives the width of horizontal margin in cells (rows).  A zero
165           indicates that no horizontal margin exists. A positive value N
166           indicates that first N rows are "labels" and are always displayed
167           and not scrolled.
168

WIDGET METHODS

170       The TixGrid method creates a TixGrid widget and returns a blessed
171       reference of this TixGrid widget.  This reference may be used to invoke
172       various operations on the widget.  It has the following general form:
173
174           $tixgrid->method?(arg, arg, ...)?
175
176       args determine the exact behavior of the method.
177
178       This object supports the configure and cget methods described in
179       Tk::options which can be used to enquire and modify the options
180       described above.  The widget also inherits all the methods provided by
181       the generic Tk::Widget class.
182
183       The following additional methods are possible for TixGrid widgets:
184
185       $tixgrid->anchorGet(x, y)
186       $tixgrid->anchorSet(x, y)
187       $tixgrid->anchorClear
188           Manipulates the anchor cell of the TixGrid widget.  The anchor cell
189           is the end of the selection that is fixed while the user is
190           dragging out a selection with the mouse.
191
192       ($bd,$col,$row) = $tixgrid->bdtype(x,y ?,xDelta,yDelta?)
193           Determines if the the screen (pixel) position x,y is in a border.
194           This is useful for changing the mouse cursor when the user points
195           at a border - e.g. to indicate that the border can be adjusted
196           interactively.
197
198           If in a border returns a list of three elements. First element is
199           'xy', 'x' or 'y', second two elements are integers.  (Value of
200           these are not understood, seem to indicate which column and row of
201           the border the screen position corresponds to?)
202
203           If not in a border returns an empty list.
204
205       $tixgrid->delete(dim, from?, to?)
206       $tixgrid->deleteColumn(from?, to?)
207       $tixgrid->deleteRow(from?, to?)
208           Dim may be row or column. If to is not given, deletes a single row
209           (or column) at the position from.  If to is given, deletes the
210           range of rows (or columns) from position from through to.
211
212       $tixgrid->dragsite(option, x, y)
213       $tixgrid->dropsite(option, x, y)
214           Tcl/Tix has (or was going to have) Drag&Drop support.  Meaning for
215           perl/Tk is not clear yet.
216
217       $tixgrid->editApply
218           If any cell is being edited, de-highlight the cell and applies the
219           changes.
220
221       $tixgrid->editSet(x, y)
222           Highlights the cell at (x,y) for editing, if the -editnotify
223           callback returns true for this cell.
224
225       $tixgrid->entrycget(x, y, '-option')
226       $tixgrid->entryconfigure(x, y?, -option??=>value, -option=>value, ...?)
227           Provide a configue interface to cells in the grid.  The -options
228           depend on the item type of the cell.
229
230       $tixgrid->formatBorder(x1,y1, x2,y2, options);
231       $tixgrid->formatGrid(x1,y1, x2,y2, options);
232           The formatBorder and formatBorder methods can only be called by the
233           -formatcmd callback of the tixGrid widget. They draw the background
234           of the region described by x1,y1, x2,y2 according the the supplied
235           options. One call to -formatcmd callback can make multiple calls to
236           formatBorder and/or formatBorder for different sub-regions.
237
238           formatBorder draws the background using Tk relief style, formatGrid
239           also draws grid lines between the cells.  It only makes sense to
240           call one or the other for a particular sub-region as one will over-
241           write the other.
242
243           The options allowed are:
244
245           -background / -bg
246           -borderwidth / -bd
247           -filled
248           -relief
249           -selectbackground
250           -xoff
251           -xon
252           -yoff
253           -yon
254
255           The -xon/-xoff and -yon/-yoff options are obscure. If anyone can
256           figure out how to do something interesting given what
257           pTk/tixGrFmt.c is doing with them please let Nick know!.
258
259       $tixgrid->geometryinfo(?width, height?)
260           Returns list of four values - two sets of two floating point
261           numbers.  First set is the scrollbar fractions for x direction,
262           second set is scrollbar fractions for y direction. If width and
263           height are specified then fractions are based on as if window size
264           was of specified size (in pixels, but not allowing normal GetPixels
265           units).  Otherwise fractions are based on current size of the
266           window.
267
268           Usage obscure.
269
270       $tixgrid->index(xcoord, ycoord)
271           Retuns (x, y) of entry at position ($coordx, $coordy).  Either
272           coordinate may be 'max' which is largest existing entry in that
273           direction, 'end' which is one beyond largest existing entry, or a
274           number. (This is how you find out how big the grid is.)
275
276       $tixgrid->infoBbox(x,y)
277           Return the pixel bounding box of the cell at x,y.
278
279       $tixgrid->infoExists(x,y)
280           Returns true if there is an item in the cell at x,y.  Throws an
281           exception (dies) if x,y is outside the grid - this may change (Nick
282           doesn't like it).
283
284       $tixgrid->move(dim, from, to, offset)
285       $tixgrid->moveColumn(from, to, offset)
286       $tixgrid->moveRow(from, to, offset)
287           Dim may be row or column. Moves the range of rows (or columns) from
288           position from through to by the distance indicated by offset. For
289           example, $tixgrid->moveRow(2, 4, 1) moves the rows 2,3,4 to rows
290           3,4,5.
291
292       $tixgrid->nearest(x, y)
293           Screen pos (pixels) to entry (nx,ny) translation.
294
295       $tixgrid->selectionAdjust(x1, y1 ?,x2, y2?)
296       $tixgrid->selectionClear(x1, y1 ?,x2, y2?)
297       $tixgrid->selectionIncludes(x1, y1 ?,x2, y2?)
298       $tixgrid->selectionSet(x1, y1 ?,x2, y2?)
299       $tixgrid->selectionToggle(x1, y1 ?,x2, y2?)
300           Selection support methods - probably buggy.
301
302           x1 (y1) has not to be greater than x2 (y2), but only x2 and y2 can
303           be 'max'.
304
305           BUG: selectionIncludes: has no visible effect (as in Tix). Eh???
306
307           BUG: selectionClear: only works for 0, 0, max, max (as in Tix).
308           Eh???
309
310           When x2, y2 are not given they default to x1, y1, respectively.
311
312       $tixgrid->set(x, y?, -itemtype=>type??, -option=>value, ...?)
313           Creates a new display item at the cell at (x,y). The optional
314           -itemtype parameter gives the type of the display item.  An
315           additional list of option-value pairs specify options of the
316           display item. If a display item already exists at this cell, the
317           old item will be deleted automatically.
318
319       $tixgrid->size(dim, index?, -option??=>value, ...?)
320       $tixgrid->sizeColumn(index?, -option??=>value, ...?)
321       $tixgrid->sizeRow(index?, -option??=>value, ...?)
322           Queries or sets the size of the row or column given by dim and
323           index. Dim may be row or column.  Index may be any non-negative
324           integer that gives the position of a given row (or column).  Index
325           can also be the string default; in this case, this method queries
326           or sets the default size of all rows (or columns).  When no option-
327           value pair is given, this method returns a list containing the
328           current size setting of the given row (or column).  When option-
329           value pairs are given, the corresponding options of the size
330           setting of the given row are changed. -option may be one of the
331           following:
332
333           -pad0 => pixels
334                   Specifies the paddings to the left of a column or the top
335                   of a row.
336
337           -pad1 => pixels
338                   Specifies the paddings to the right of a column or the
339                   bottom of a row.
340
341           -size => val
342                   Specifies the width of a column or the height of a row.
343                   Val may be: auto -- the width of the column is set the
344                   widest cell in the column; a valid Tk screen distance unit
345                   (see Tk_GetPixels); or a real number following by the word
346                   chars (e.g. 3.4chars) that sets the width of the column to
347                   the given number of characters.
348
349       $tixgrid->sort(dimension, start, end, ?args ...?)
350           ?docu here? (not supported on Win* OSs up to now)
351
352       $tixgrid->unset(x, y)
353           Clears the cell at (x,y) by removing its display item.
354
355       $tixgrid->xview
356           Normal horizontal scrollbar method.
357
358       $tixgrid->yview
359           Normal vertical scrollbar method.
360

BINDINGS

362       To be done - only most obvious basic bindings work. The Tcl/Tix code
363       was coded as a "state machine" which is not easy to follow.
364

SEE ALSO

366       Tk::DItem Tk::callbacks Tk::FloatEntry
367

BUGS

369       Tcl/Tix was/is not finished and both C code and bindings of TixGrid
370       have some bugs.
371

KEYWORDS

373       tix, tixgrid, table, display item, spreadsheet
374
375
376
377perl v5.32.1                      2021-01-27                        TixGrid(3)
Impressum