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 con‐
35 figure aspects of the TixGrid widget.
36
38 -background -borderwidth -cursor -font -foreground
39 -height -highlightbackground -highlightcolor -high‐
40 lightthickness -padx -pady -relief -selectback‐
41 ground -selectborderwidth -selectforeground -state
42 -takefocus -width -xscrollcommand -yscrollcommand
43 See Tk::options for details of the standard options.
45
47 Name: browseCmd
48 Class: BrowseCmd
49 Switch: -browsecmd
50 If defined, gives a perl/Tk callback to be executed when the user
51 browses a grid cell (This is normally the case when the user clicks
52 on an entry). When this callback is called, it is passed with two
53 additional parameters: x y, where (x,y) is the location of the cell
54 that has just been clicked.
55 Name: Command
57 Class: Command
58 Switch: -command
59 If defined, gives a perl/Tk callback to be executed when the user
60 double-clicks a grid cell. When this callback is called, it is
61 passed with two additional parameters: x y, where (x,y) is the
62 location of the cell that has just been clicked.
63 Name: editDoneCmd
65 Class: EditDoneCmd
66 Switch: -editdonecmd
67 If defined, gives a perl/Tk callback to be executed when the user
68 has edited grid cell. When this callback is called, it is passed
69 with two additional parameters: x y, where (x,y) is the location of
70 the cell that has just been edited.
71 Name: editNotifyCmd
73 Class: EditNotifyCmd
74 Switch: -editnotifycmd
75 If defined gives a perl/Tk callback to be executed when the user
76 tries to edit a grid cell. When this callback is called, it is
77 passed with two additional parameters: x y, where (x,y,) is the
78 location of the cell. This callback should return a boolean value:
79 true indicates that the cell is editable and false otherwise.
80 Name: FloatingCols
82 Class: floatingCols
83 Switch: -floatingcols
84 Defines the number of extra columns beyond the existing grid that
85 can be brought into view by scrolling.
86 Name: FloatingRows
88 Class: floatingRows
89 Switch: -floatingrows
90 Defines the number of extra rows beyond the the existing grid that
91 can be brought into view by scrolling.
92 Name: formatCmd
94 Class: FormatCmd
95 Switch: -formatcmd
96 If defined, gives a perl/Tk callback to be executed when the grid
97 cells need to be displayed on the screen. Its primary purpose is
98 to draw the background of the region before the cells are rendered
99 on top. This is normally achieved by calling formatGrid or format‐
100 Border (see below). However other uses can be made of this low-
101 level callback. For example it can be used to "lazily" populate the
102 grid by calling the set method only as cells come into view.
103 When this callback is called, it is passed with five additional
105 parameters: type x1 y1 x2 y2.
106 x1 y1 x2 y2 gives the extent of the region that needs formatting.
108 type gives the logical type of the region in the grid. It may be
110 one of the following.
111 x_region
113 The horizontal margin.
114 y_region
116 The vertical margin.
117 s_region
119 The area in the top left corner where the horizontal and
120 vertical margins are joined.
121 main The main body i.e. all the cells that do not fall into the
123 above three types.
124 Name: leftMargin
126 Class: LeftMargin
127 Switch: -leftmargin
128 Gives the width of vertical margin in cells (columns). A zero
129 indicates that no vertical margin exists. A positive value N indi‐
130 cates that first N columns are "labels" and are always displayed
131 and not scrolled.
132 Name: itemType
134 Class: ItemType
135 Switch: -itemtype
136 Default item type for cells.
137 Name: selectMode
139 Class: SelectMode
140 Switch: -selectmode
141 Specifies one of several styles for manipulating the selection.
142 The value of the option may be arbitrary, but the default bindings
143 expect it to be either single, browse, multiple, or extended; the
144 default value is single.
145 Name: selectUnit
147 Class: SelectUnit
148 Switch: -selectunit
149 Specifies the selection unit. Valid values are cell, column or row.
150 Name: sizeCmd
152 Class: SizeCmd
153 Switch: -sizecmd
154 Callback is called (with no extra arguments) when grid sizes are
155 re-computed. For example if window changes size, a different font
156 is specified etc.
157 It is called just after scrollbars (if present) are updated.
159 Name: topMargin
161 Class: TopMargin
162 Switch: -topmargin
163 Gives the width of horizontal margin in cells (rows). A zero indi‐
164 cates that no horizontal margin exists. A positive value N indi‐
165 cates that first N rows are "labels" and are always displayed and
166 not scrolled.
167
169 The TixGrid method creates a TixGrid widget and returns a blessed ref‐
170 erence of this TixGrid widget. This reference may be used to invoke
171 various operations on the widget. It has the following general form:
172 $tixgrid->method?(arg, arg, ...)?
174 args determine the exact behavior of the method.
176 This object supports the configure and cget methods described in
178 Tk::options which can be used to enquire and modify the options
179 described above. The widget also inherits all the methods provided by
180 the generic Tk::Widget class.
181 The following additional methods are possible for TixGrid widgets:
183 $tixgrid->anchorGet(x, y)
185 $tixgrid->anchorSet(x, y)
186 $tixgrid->anchorClear
187 Manipulates the anchor cell of the TixGrid widget. The anchor cell
188 is the end of the selection that is fixed while the user is drag‐
189 ging out a selection with the mouse.
190 ($bd,$col,$row) = $tixgrid->bdtype(x,y ?,xDelta,yDelta?)
192 Determines if the the screen (pixel) position x,y is in a border.
193 This is useful for changing the mouse cursor when the user points
194 at a border - e.g. to indicate that the border can be adjusted
195 interactively.
196 If in a border returns a list of three elements. First element is
198 'xy', 'x' or 'y', second two elements are integers. (Value of
199 these are not understood, seem to indicate which column and row of
200 the border the screen position corresponds to?)
201 If not in a border returns an empty list.
203 $tixgrid->delete(dim, from?, to?)
205 $tixgrid->deleteColumn(from?, to?)
206 $tixgrid->deleteRow(from?, to?)
207 Dim may be row or column. If to is not given, deletes a single row
208 (or column) at the position from. If to is given, deletes the
209 range of rows (or columns) from position from through to.
210 $tixgrid->dragsite(option, x, y)
212 $tixgrid->dropsite(option, x, y)
213 Tcl/Tix has (or was going to have) Drag&Drop support. Meaning for
214 perl/Tk is not clear yet.
215 $tixgrid->editApply
217 If any cell is being edited, de-highlight the cell and applies the
218 changes.
219 $tixgrid->editSet(x, y)
221 Highlights the cell at (x,y) for editing, if the -editnotify call‐
222 back returns true for this cell.
223 $tixgrid->entrycget(x, y, '-option')
225 $tixgrid->entryconfigure(x, y?, -option??=>value, -option=>value, ...?)
226 Provide a configue interface to cells in the grid. The -options
227 depend on the item type of the cell.
228 $tixgrid->formatBorder(x1,y1, x2,y2, options);
230 $tixgrid->formatGrid(x1,y1, x2,y2, options);
231 The formatBorder and formatBorder methods can only be called by the
232 -formatcmd callback of the tixGrid widget. They draw the background
233 of the region described by x1,y1, x2,y2 according the the supplied
234 options. One call to -formatcmd callback can make multiple calls to
235 formatBorder and/or formatBorder for different sub-regions.
236 formatBorder draws the background using Tk relief style, formatGrid
238 also draws grid lines between the cells. It only makes sense to
239 call one or the other for a particular sub-region as one will over-
240 write the other.
241 The options allowed are:
243 -background / -bg
245 -borderwidth / -bd
246 -filled
247 -relief
248 -selectbackground
249 -xoff
250 -xon
251 -yoff
252 -yon
253 The -xon/-xoff and -yon/-yoff options are obscure. If anyone can
255 figure out how to do something interesting given what pTk/tix‐
256 GrFmt.c is doing with them please let Nick know!.
257 $tixgrid->geometryinfo(?width, height?)
259 Returns list of four values - two sets of two floating point num‐
260 bers. First set is the scrollbar fractions for x direction, second
261 set is scrollbar fractions for y direction. If width and height are
262 specified then fractions are based on as if window size was of
263 specified size (in pixels, but not allowing normal GetPixels
264 units). Otherwise fractions are based on current size of the win‐
265 dow.
266 Usage obscure.
268 $tixgrid->index(xcoord, ycoord)
270 Retuns (x, y) of entry at position ($coordx, $coordy). Either
271 coordinate may be 'max' which is largest existing entry in that
272 direction, 'end' which is one beyond largest existing entry, or a
273 number. (This is how you find out how big the grid is.)
274 $tixgrid->infoBbox(x,y)
276 Return the pixel bounding box of the cell at x,y.
277 $tixgrid->infoExists(x,y)
279 Returns true if there is an item in the cell at x,y. Throws an
280 exception (dies) if x,y is outside the grid - this may change (Nick
281 doesn't like it).
282 $tixgrid->move(dim, from, to, offset)
284 $tixgrid->moveColumn(from, to, offset)
285 $tixgrid->moveRow(from, to, offset)
286 Dim may be row or column. Moves the range of rows (or columns) from
287 position from through to by the distance indicated by offset. For
288 example, $tixgrid->moveRow(2, 4, 1) moves the rows 2,3,4 to rows
289 3,4,5.
290 $tixgrid->nearest(x, y)
292 Screen pos (pixels) to entry (nx,ny) translation.
293 $tixgrid->selectionAdjust(x1, y1 ?,x2, y2?)
295 $tixgrid->selectionClear(x1, y1 ?,x2, y2?)
296 $tixgrid->selectionIncludes(x1, y1 ?,x2, y2?)
297 $tixgrid->selectionSet(x1, y1 ?,x2, y2?)
298 $tixgrid->selectionToggle(x1, y1 ?,x2, y2?)
299 Selection support methods - probably buggy.
300 x1 (y1) has not to be greater than x2 (y2), but only x2 and y2 can
302 be 'max'.
303 BUG: selectionIncludes: has no visible effect (as in Tix). Eh???
305 BUG: selectionClear: only works for 0, 0, max, max (as in Tix).
307 Eh???
308 When x2, y2 are not given they default to x1, y1, respectively.
310 $tixgrid->set(x, y?, -itemtype=>type??, -option=>value, ...?)
312 Creates a new display item at the cell at (x,y). The optional
313 -itemtype parameter gives the type of the display item. An addi‐
314 tional list of option-value pairs specify options of the display
315 item. If a display item already exists at this cell, the old item
316 will be deleted automatically.
317 $tixgrid->size(dim, index?, -option??=>value, ...?)
319 $tixgrid->sizeColumn(index?, -option??=>value, ...?)
320 $tixgrid->sizeRow(index?, -option??=>value, ...?)
321 Queries or sets the size of the row or column given by dim and
322 index. Dim may be row or column. Index may be any non-negative
323 integer that gives the position of a given row (or column). Index
324 can also be the string default; in this case, this method queries
325 or sets the default size of all rows (or columns). When no option-
326 value pair is given, this method returns a list containing the cur‐
327 rent size setting of the given row (or column). When option-value
328 pairs are given, the corresponding options of the size setting of
329 the given row are changed. -option may be one of the following:
330 -pad0 => pixels
332 Specifies the paddings to the left of a column or the top
333 of a row.
334 -pad1 => pixels
336 Specifies the paddings to the right of a column or the bot‐
337 tom of a row.
338 -size => val
340 Specifies the width of a column or the height of a row.
341 Val may be: auto -- the width of the column is set the
342 widest cell in the column; a valid Tk screen distance unit
343 (see Tk_GetPixels); or a real number following by the word
344 chars (e.g. 3.4chars) that sets the width of the column to
345 the given number of characters.
346 $tixgrid->sort(dimension, start, end, ?args ...?)
348 ?docu here? (not supported on Win* OSs up to now)
349 $tixgrid->unset(x, y)
351 Clears the cell at (x,y) by removing its display item.
352 $tixgrid->xview
354 Normal horizontal scrollbar method.
355 $tixgrid->yview
357 Normal vertical scrollbar method.
358
360 To be done - only most obvious basic bindings work. The Tcl/Tix code
361 was coded as a "state machine" which is not easy to follow.
362
364 Tk::DItem Tk::callbacks Tk::FloatEntry
365
367 Tcl/Tix was/is not finished and both C code and bindings of TixGrid
368 have some bugs.
369
371 tix, tixgrid, table, display item, spreadsheet
372perl v5.8.8 2008-02-05 TixGrid(3)