1TixGrid(3) User Contributed Perl Documentation TixGrid(3)
2
6 Tk::TixGrid - Create and manipulate Tix Grid widgets
7
9 $tixgrid = $parent->TixGrid?(options)?;
10
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 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 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 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
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 See Tk::options for details of the standard options.
46
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 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 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 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 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 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 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 When this callback is called, it is passed with five additional
106 parameters: type x1 y1 x2 y2.
107 x1 y1 x2 y2 gives the extent of the region that needs formatting.
109 type gives the logical type of the region in the grid. It may be
111 one of the following.
112 x_margin
114 The horizontal margin.
115 y_margin
117 The vertical margin.
118 s_margin
120 The area in the top left corner where the horizontal and
121 vertical margins are joined.
122 main The main body i.e. all the cells that do not fall into the
124 above three types.
125 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 Name: itemType
135 Class: ItemType
136 Switch: -itemtype
137 Default item type for cells.
138 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 Name: selectUnit
148 Class: SelectUnit
149 Switch: -selectunit
150 Specifies the selection unit. Valid values are cell, column or row.
151 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 It is called just after scrollbars (if present) are updated.
160 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
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 $tixgrid->method?(arg, arg, ...)?
175 args determine the exact behavior of the method.
177 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 The following additional methods are possible for TixGrid widgets:
184 $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 ($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 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 If not in a border returns an empty list.
204 $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 $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 $tixgrid->editApply
218 If any cell is being edited, de-highlight the cell and applies the
219 changes.
220 $tixgrid->editSet(x, y)
222 Highlights the cell at (x,y) for editing, if the -editnotify
223 callback returns true for this cell.
224 $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 $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 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 The options allowed are:
244 -background / -bg
246 -borderwidth / -bd
247 -filled
248 -relief
249 -selectbackground
250 -xoff
251 -xon
252 -yoff
253 -yon
254 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 $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 Usage obscure.
269 $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 $tixgrid->infoBbox(x,y)
277 Return the pixel bounding box of the cell at x,y.
278 $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 $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 $tixgrid->nearest(x, y)
293 Screen pos (pixels) to entry (nx,ny) translation.
294 $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 x1 (y1) has not to be greater than x2 (y2), but only x2 and y2 can
303 be 'max'.
304 BUG: selectionIncludes: has no visible effect (as in Tix). Eh???
306 BUG: selectionClear: only works for 0, 0, max, max (as in Tix).
308 Eh???
309 When x2, y2 are not given they default to x1, y1, respectively.
311 $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 $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 -pad0 => pixels
334 Specifies the paddings to the left of a column or the top
335 of a row.
336 -pad1 => pixels
338 Specifies the paddings to the right of a column or the
339 bottom of a row.
340 -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 $tixgrid->sort(dimension, start, end, ?args ...?)
350 ?docu here? (not supported on Win* OSs up to now)
351 $tixgrid->unset(x, y)
353 Clears the cell at (x,y) by removing its display item.
354 $tixgrid->xview
356 Normal horizontal scrollbar method.
357 $tixgrid->yview
359 Normal vertical scrollbar method.
360
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
366 Tk::DItem Tk::callbacks Tk::FloatEntry
367
369 Tcl/Tix was/is not finished and both C code and bindings of TixGrid
370 have some bugs.
371
373 tix, tixgrid, table, display item, spreadsheet
374perl v5.32.1 2021-01-27 TixGrid(3)