1TixGrid(3) User Contributed Perl Documentation TixGrid(3)
2
3
4
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
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 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
44 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
56 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
64 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
72 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
81 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
87 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
93 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
104 When this callback is called, it is passed with five additional
105 parameters: type x1 y1 x2 y2.
106
107 x1 y1 x2 y2 gives the extent of the region that needs formatting.
108
109 type gives the logical type of the region in the grid. It may be
110 one of the following.
111
112 x_region
113 The horizontal margin.
114
115 y_region
116 The vertical margin.
117
118 s_region
119 The area in the top left corner where the horizontal and
120 vertical margins are joined.
121
122 main The main body i.e. all the cells that do not fall into the
123 above three types.
124
125 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
133 Name: itemType
134 Class: ItemType
135 Switch: -itemtype
136 Default item type for cells.
137
138 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
146 Name: selectUnit
147 Class: SelectUnit
148 Switch: -selectunit
149 Specifies the selection unit. Valid values are cell, column or row.
150
151 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
158 It is called just after scrollbars (if present) are updated.
159
160 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
173 $tixgrid->method?(arg, arg, ...)?
174
175 args determine the exact behavior of the method.
176
177 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
182 The following additional methods are possible for TixGrid widgets:
183
184 $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
191 ($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
197 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
202 If not in a border returns an empty list.
203
204 $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
211 $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
216 $tixgrid->editApply
217 If any cell is being edited, de-highlight the cell and applies the
218 changes.
219
220 $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
224 $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
229 $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
237 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
242 The options allowed are:
243
244 -background / -bg
245 -borderwidth / -bd
246 -filled
247 -relief
248 -selectbackground
249 -xoff
250 -xon
251 -yoff
252 -yon
253
254 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
258 $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
267 Usage obscure.
268
269 $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
275 $tixgrid->infoBbox(x,y)
276 Return the pixel bounding box of the cell at x,y.
277
278 $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
283 $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
291 $tixgrid->nearest(x, y)
292 Screen pos (pixels) to entry (nx,ny) translation.
293
294 $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
301 x1 (y1) has not to be greater than x2 (y2), but only x2 and y2 can
302 be 'max'.
303
304 BUG: selectionIncludes: has no visible effect (as in Tix). Eh???
305
306 BUG: selectionClear: only works for 0, 0, max, max (as in Tix).
307 Eh???
308
309 When x2, y2 are not given they default to x1, y1, respectively.
310
311 $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
318 $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
331 -pad0 => pixels
332 Specifies the paddings to the left of a column or the top
333 of a row.
334
335 -pad1 => pixels
336 Specifies the paddings to the right of a column or the bot‐
337 tom of a row.
338
339 -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
347 $tixgrid->sort(dimension, start, end, ?args ...?)
348 ?docu here? (not supported on Win* OSs up to now)
349
350 $tixgrid->unset(x, y)
351 Clears the cell at (x,y) by removing its display item.
352
353 $tixgrid->xview
354 Normal horizontal scrollbar method.
355
356 $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
372
373
374
375perl v5.8.8 2008-02-05 TixGrid(3)