Commit | Line | Data |
---|---|---|
86530b38 AT |
1 | # Copyright (c) 1996, Expert Interface Technologies |
2 | # See the file "license.terms" for information on usage and | |
3 | # redistribution of this file, and for a DISCLAIMER OF ALL WARRANTIES. | |
4 | # The file man.macros and some of the macros used by this file are | |
5 | # copyrighted: (c) 1990 The Regents of the University of California. | |
6 | # (c) 1994-1995 Sun Microsystems, Inc. | |
7 | # The license terms of the Tcl/Tk distribution are in the file | |
8 | # license.tcl. | |
9 | ||
10 | ## TO CHECK: | |
11 | ## | |
12 | ## callback: checked for defined of code ref (compare -edit*cmd) | |
13 | ## | |
14 | ## option | |
15 | ## formatcmd mentions format method but there is no format | |
16 | ## method documented | |
17 | ## | |
18 | ## methods: | |
19 | ## bdtype: what is it? no description given | |
20 | ## see: not documented? Not implemented?? | |
21 | ## | |
22 | ## todo: missing peaces marked by ???? | |
23 | ||
24 | =head1 NAME | |
25 | ||
26 | Tk::TixGrid - Create and manipulate Tix Grid widgets | |
27 | ||
28 | =for pm TixGrid/TixGrid.pm | |
29 | ||
30 | =for category Tix Extensions | |
31 | ||
32 | =head1 SYNOPSIS | |
33 | ||
34 | S< >I<$tixgrid> = I<$parent>->B<TixGrid>?(I<options>)?; | |
35 | ||
36 | The port of C code and bindings is done but needs | |
37 | debugging. THERE ARE KNOWN BUGS. Work in progress ... | |
38 | ||
39 | =head1 STANDARD OPTIONS | |
40 | ||
41 | B<-background> | |
42 | B<-borderwidth> | |
43 | B<-cursor> | |
44 | B<-font> | |
45 | B<-foreground> | |
46 | B<-height> | |
47 | B<-highlightbackground> | |
48 | B<-highlightcolor> | |
49 | B<-highlightthickness> | |
50 | B<-padx> | |
51 | B<-pady> | |
52 | B<-relief> | |
53 | B<-selectbackground> | |
54 | B<-selectborderwidth> | |
55 | B<-selectforeground> | |
56 | B<-state> | |
57 | B<-takefocus> | |
58 | B<-width> | |
59 | B<-xscrollcommand> | |
60 | B<-yscrollcommand> | |
61 | ||
62 | See L<Tk::options> for details of the standard options. | |
63 | ||
64 | =head1 WIDGET-SPECIFIC OPTIONS | |
65 | ||
66 | =over 4 | |
67 | ||
68 | =item Name: B<browseCmd> | |
69 | ||
70 | =item Class: B<BrowseCmd> | |
71 | ||
72 | =item Switch: B<-browsecmd> | |
73 | ||
74 | ?docu here? Not in configure output but used in bindings ??!! | |
75 | ||
76 | If defined, gives a perl/Tk L<callback|Tk::callbacks> | |
77 | to be executed when the | |
78 | user browses a grid cell (This is normally the case when | |
79 | the user clicks on an entry). When this callback is called, it is | |
80 | passed with two additional parameters: I<x> I<y>, where (I<x>,I<y>) | |
81 | is the location of the cell that has just been clicked. | |
82 | ||
83 | =item Name: B<Command> | |
84 | ||
85 | =item Class: B<Command> | |
86 | ||
87 | =item Switch: B<-command> | |
88 | ||
89 | ?docu here? Not in configure output but used in bindings ??!! | |
90 | ||
91 | =item Name: B<editDoneCmd> | |
92 | ||
93 | =item Class: B<EditDoneCmd> | |
94 | ||
95 | =item Switch: B<-editdonecmd> | |
96 | ||
97 | If defined, gives a perl/Tk L<callback|Tk::callbacks> | |
98 | to be executed when the | |
99 | user has edited grid cell. When this callback is called, it is | |
100 | passed with two additional parameters: I<x> I<y>, where (I<x>,I<y>) | |
101 | is the location of the cell that has just been edited. | |
102 | ||
103 | =item Name: B<editNotifyCmd> | |
104 | ||
105 | =item Class: B<EditNotifyCmd> | |
106 | ||
107 | =item Switch: B<-editnotifycmd> | |
108 | ||
109 | If defined gives a perl/Tk L<callback|Tk::callbacks> | |
110 | to be executed when the user tries to edit a grid cell. | |
111 | When this callback is called, it is passed with two additional | |
112 | parameters: I<x> I<y>, where (I<x>,I<y>,) is the location | |
113 | of the cell. This callback should return a boolean value: B<true> | |
114 | indicates that the cell is editable and B<false> otherwise. | |
115 | ||
116 | =item Name: B<FloatingCols> | |
117 | ||
118 | =item Class: B<floatingCols> | |
119 | ||
120 | =item Switch: B<-floatingcols> | |
121 | ||
122 | Defines the number of columns that fixed when the widget | |
123 | is horizontally scrolled. These column(s) | |
124 | can be used as label(s) for the column(s). The floating column(s) | |
125 | can be configured in the B<-formatcmd> callback with the | |
126 | B<formatBorder> method. The default value is 0. | |
127 | ||
128 | =item Name: B<FloatingRows> | |
129 | ||
130 | =item Class: B<floatingRows> | |
131 | ||
132 | =item Switch: B<-floatingrows> | |
133 | ||
134 | Defines the number of rows that are fixed when the widget | |
135 | is vertically scrolled. These row(s) | |
136 | can be used as label(s) for the row(s). The floating row(s) | |
137 | can be configured in the B<-formatcmd> callback with the | |
138 | B<formatBorder> method. The default value is 0. | |
139 | ||
140 | =item Name: B<formatCmd> | |
141 | ||
142 | =item Class: B<FormatCmd> | |
143 | ||
144 | =item Switch: B<-formatcmd> | |
145 | ||
146 | If defined, gives a perl/Tk L<callback|Tk::callbacks> to be | |
147 | executed when the grid cells need to be formatted on the screen. | |
148 | Normally, this callback calls the B<format> method (see below). | |
149 | When this callback is called, it is passed with five additional | |
150 | parameters: I<type> I<x1> I<y1> I<x2> I<y2>. I<type> gives the | |
151 | logical type of the region in the grid. It may be one of the | |
152 | following. | |
153 | ||
154 | =over 8 | |
155 | ||
156 | =item B<x-region> | |
157 | ||
158 | the horizontal margin | |
159 | ||
160 | =item B<y-region> | |
161 | ||
162 | the vertical margin | |
163 | ||
164 | =item B<s-region> | |
165 | ||
166 | the area where the horizontal and vertical margins are joined | |
167 | ||
168 | =item B<main> | |
169 | ||
170 | all the cells that do not fall into the above three types | |
171 | ||
172 | =back | |
173 | ||
174 | I<x1> I<y1> I<x2> I<y2> gives the extent of the region that needs | |
175 | formatting. | |
176 | ||
177 | =item Name: B<leftMargin> | |
178 | ||
179 | =item Class: B<LeftMargin> | |
180 | ||
181 | =item Switch: B<-leftmargin> | |
182 | ||
183 | In the number of cells, gives the width of vertical margin. | |
184 | A zero indicates that no vertical should be drawn. | |
185 | ||
186 | =item Name: B<itemType> | |
187 | ||
188 | =item Class: B<ItemType> | |
189 | ||
190 | =item Switch: B<-itemtype> | |
191 | ||
192 | ?docu here? | |
193 | ||
194 | =item Name: B<selectMode> | |
195 | ||
196 | =item Class: B<SelectMode> | |
197 | ||
198 | =item Switch: B<-selectmode> | |
199 | ||
200 | Specifies one of several styles for manipulating the selection. | |
201 | The value of the option may be arbitrary, but the default bindings | |
202 | expect it to be either B<single>, B<browse>, B<multiple>, or B<extended>; | |
203 | the default value is B<single>. | |
204 | ||
205 | =item Name: B<selectUnit> | |
206 | ||
207 | =item Class: B<SelectUnit> | |
208 | ||
209 | =item Switch: B<-selectunit> | |
210 | ||
211 | Specifies the selection unit. Valid values are B<cell>, B<column> or B<row>. | |
212 | ||
213 | =item Name: B<sizeCmd> | |
214 | ||
215 | =item Class: B<SizeCmd> | |
216 | ||
217 | =item Switch: B<-sizecmd> | |
218 | ||
219 | ?docu here? | |
220 | ||
221 | =item Name: B<topMargin> | |
222 | ||
223 | =item Class: B<TopMargin> | |
224 | ||
225 | =item Switch: B<-topmargin> | |
226 | ||
227 | In the number of cells, gives the height of horizontal margin. | |
228 | A zero indicates that no horizontal should be drawn. | |
229 | ||
230 | =back | |
231 | ||
232 | =head1 DESCRIPTION | |
233 | ||
234 | The B<TixGrid> method creates a TixGrid new window and returns a | |
235 | blessed reference of this TixGrid widget. | |
236 | Additional options, | |
237 | described above, may be specified on the command line or in the | |
238 | option database to configure aspects of the B<TixGrid> widget | |
239 | such as its cursor and relief. | |
240 | ||
241 | A Grid widget displays its contents in a two dimensional grid of cells. | |
242 | Each cell may contain one Tix display item, which may be in text, | |
243 | graphics or other formats. See L<Tk::DItem> for more information | |
244 | about Tix display items. Individual cells, or groups of cells, | |
245 | can be formatted with a wide range of attributes, such as its color, | |
246 | relief and border. | |
247 | ||
248 | =head1 WIDGET METHODS | |
249 | ||
250 | The B<TixGrid> method creates a TixGrid widget and returns a blessed | |
251 | reference of this TixGrid widget. This reference may be used to | |
252 | invoke various operations on the widget. It has the following general | |
253 | form: | |
254 | ||
255 | S< >I<$tixgrid>->B<method>?(I<arg, arg, ...>)? | |
256 | ||
257 | I<arg>s determine the exact behavior of the method. The following | |
258 | methods are possible for B<TixGrid> widgets: | |
259 | ||
260 | =over 4 | |
261 | ||
262 | =item I<$tixgrid>->B<anchor>(I<action>, I<x>, I<y>) | |
263 | ||
264 | =item I<$tixgrid>->B<anchor>I<Action>(I<x>, I<y>) | |
265 | ||
266 | Manipulates the B<anchor cell> of the B<TixGrid> widget. | |
267 | The anchor cell is the end of the selection that is fixed | |
268 | while the user is dragging out a selection with the mouse. | |
269 | I<Action> can be B<clear>, B<get> or B<set>. If I<action> | |
270 | is B<clear>, I<x> and I<y> args are not accepted. | |
271 | ||
272 | =item I<$tixgrid>->B<bdtype>(I<x>, I<y> ?,I<xbdWidth>, I<ybdWidth>?) | |
273 | ||
274 | ???? | |
275 | ||
276 | =item I<$tixgrid>->B<cget>('I<-option>') | |
277 | ||
278 | Returns the current value of the configuration option given | |
279 | by I<-option>. I<-option> may have any of the values accepted | |
280 | by the B<TixGrid> constructor method. | |
281 | ||
282 | =item I<$tixgrid>->B<configure>(?I<-option>??=>I<value>, I<-option>=>I<value>, I<...>?) | |
283 | ||
284 | Query or modify the configuration options of the widget. | |
285 | If no I<-option> is specified, returns a list describing all | |
286 | of the available options for I<$tixgrid> (see B<Tk_ConfigureInfo> | |
287 | for information on the format of this list.) If I<-option> is | |
288 | specified with no I<value>, then the method returns a list describing | |
289 | the one named option (this list will be identical to the corresponding | |
290 | sublist of the value returned if no I<-option> is specified). | |
291 | If one or more I<option-value> pairs are specified, then the | |
292 | method modifies the given widget option(s) to have the given value(s); | |
293 | in this case the method returns an empty string. I<-option> may have | |
294 | any of the values accepted by the B<TixGrid> constructor method. | |
295 | ||
296 | =item I<$tixgrid>->B<delete>(I<dim>, I<from>?, I<to>?) | |
297 | ||
298 | =item I<$tixgrid>->B<deleteColumn>(I<from>?, I<to>?) | |
299 | ||
300 | =item I<$tixgrid>->B<deleteRow>(I<from>?, I<to>?) | |
301 | ||
302 | I<Dim> may be B<row> or B<column>. If I<to> is not given, | |
303 | deletes a single row (or column) at the position I<from>. | |
304 | If I<to> is given, deletes the range of rows (or columns) | |
305 | from position I<from> through I<to>. | |
306 | ||
307 | =item I<$tixgrid>->B<dragsite>(I<option>, I<x>, I<y>) | |
308 | ||
309 | ?docu here? not implemented :-( | |
310 | ||
311 | =item I<$tixgrid>->B<dropsite>(I<option>, I<x>, I<y>) | |
312 | ||
313 | ?docu here? not implemented :-( | |
314 | ||
315 | =item I<$tixgrid>->B<editApply> | |
316 | ||
317 | If any cell is being edited, de-highlight the cell and | |
318 | applies the changes. | |
319 | ||
320 | =item I<$tixgrid>->B<editSet>(I<x>, I<y>) | |
321 | ||
322 | Highlights the cell at (I<x>,I<y>) for editing, | |
323 | if the B<-editnotify> callback returns true for this cell. | |
324 | ||
325 | =item I<$tixgrid>->B<entrycget>(I<x>, I<y>, 'I<-option>') | |
326 | ||
327 | Returns the current value of the configuration option given by | |
328 | I<-option> of the cell at (I<x>,I<y>). I<-option> may have any | |
329 | of the values accepted by the B<set> method. | |
330 | ||
331 | =item I<$tixgrid>->B<entryconfigure>(I<x>, I<y>?, I<-option>??=>I<value>, I<-option>=>I<value>, I<...>?) | |
332 | ||
333 | Query or modify the configuration options of the cell at (I<x>,I<y>). | |
334 | If no I<-option> is specified, returns a list describing all of the | |
335 | available options for the cell (see B<Tk_ConfigureInfo> for information | |
336 | on the format of this list.) If I<-option> is specified with no | |
337 | I<value>, then the method returns a list describing the one named | |
338 | option (this list will be identical to the corresponding sublist | |
339 | of the value returned if no I<-option> is specified.) If one or | |
340 | more I<option-value> pairs are specified, then the method modifies | |
341 | the given widget option(s) to have the given value(s); in this case | |
342 | the method returns an empty string. I<Option> may have any of the | |
343 | values accepted by the B<set> method. | |
344 | ||
345 | =item I<$tixgrid>->B<format>(I<option>, ?I<args>, ...?) | |
346 | ||
347 | =item I<$tixgrid>->B<formatBorder>(I<x1,y1>, I<x2,y2>, I<options>); | |
348 | ||
349 | =item I<$tixgrid>->B<formatGrid>(I<x1,y1>, I<x2,y2>, I<options>); | |
350 | ||
351 | the B<format> method can only be called by the B<-formatcmd> callback | |
352 | of the tixGrid widget. | |
353 | ||
354 | ?docu complete? | |
355 | ||
356 | =item I<$tixgrid>->B<geometryinfo>(?I<width>, ?I<height>, ...?) | |
357 | ||
358 | ?docu here? Return a list of 4 floats! Currently "{first1 last1} {first2,last2}" :-( | |
359 | ||
360 | =item I<$tixgrid>->B<index>(I<$coordx>, I<$coordy>) | |
361 | ||
362 | ?docu here? | |
363 | ||
364 | retuns I<(nx, ny)> of entry at position (I<$coordx>, I<$coordy>). | |
365 | (??widget or screen offset??) | |
366 | ||
367 | =item I<$tixgrid>->B<info>(I<option>, ?I<args>, ...?) | |
368 | ||
369 | ?docu here? | |
370 | ||
371 | =item I<$tixgrid>->B<move>(I<dim>, I<from>, I<to>, I<offset>) | |
372 | ||
373 | =item I<$tixgrid>->B<moveColumn>(I<from>, I<to>, I<offset>) | |
374 | ||
375 | =item I<$tixgrid>->B<moveRow>(I<from>, I<to>, I<offset>) | |
376 | ||
377 | I<Dim> may be B<row> or B<column>. Moves the range of rows | |
378 | (or columns) from position I<from> through I<to> by the distance | |
379 | indicated by I<offset>. For example, | |
380 | I<$tixgrid>->B<moveRow>(B<2>, B<4>, B<1>) moves the rows 2,3,4 | |
381 | to rows 3,4,5. | |
382 | ||
383 | =item I<$tixgrid>->B<nearest>(I<x>, I<y>) | |
384 | ||
385 | ?docu here? screen pos (pixels) to entry (nx,ny) translation. | |
386 | ||
387 | =item I<$tixgrid>->B<selection>(I<option>, I<x1>, I<y1> ?,I<x2>, I<y2>?) | |
388 | ||
389 | =item I<$tixgrid>->B<selection>I<Option>(I<x1>, I<y1> ?,I<x2>, I<y2>?) | |
390 | ||
391 | Option one of: B<adjust>, B<clear>, B<includes>, B<set>, and B<toggle>. | |
392 | ||
393 | x1 (y1) has not to be greater than x2 (y2), but only x2 and y2 can be 'max'. | |
394 | ||
395 | BUG: I<selection includes>: has no visible effect (as in Tix). Eh??? | |
396 | ||
397 | BUG: I<selection clear>: only works for 0, 0, max, max (as in Tix). Eh??? | |
398 | ||
399 | When I<x2, y2> are not given they default to I<x1, y1>, respectively. | |
400 | ||
401 | =over 8 | |
402 | ||
403 | =item I<$tixgrid>->B<selectionAdjust>(I<x1>, I<y1> ?,I<x2>, I<y2>?) | |
404 | ||
405 | ?docu here? | |
406 | ||
407 | =item I<$tixgrid>->B<selectionClear>(I<x1>, I<y1> ?,I<x2>, I<y2>?) | |
408 | ||
409 | ?docu here? | |
410 | ||
411 | =item I<$tixgrid>->B<selectionIncludes>(I<x1>, I<y1> ?,I<x2>, I<y2>?) | |
412 | ||
413 | ?docu here? | |
414 | ||
415 | =item I<$tixgrid>->B<selectionSet>(I<x1>, I<y1> ?,I<x2>, I<y2>?) | |
416 | ||
417 | ?docu here? | |
418 | ||
419 | =item I<$tixgrid>->B<selectionToggle>(I<x1>, I<y1> ?,I<x2>, I<y2>?) | |
420 | ||
421 | ?docu here? | |
422 | ||
423 | =back | |
424 | ||
425 | =item I<$tixgrid>->B<set>(I<x>, I<y>?, B<-itemtype>=>I<type>??, I<-option>=>I<value>, I<...>?) | |
426 | ||
427 | Creates a new display item at the cell at (I<x>,I<y>). The optional | |
428 | B<-itemtype> parameter gives the type of the display item. | |
429 | An additional list of I<option-value> pairs specify options | |
430 | of the display item. If a display item already exists at this cell, | |
431 | the old item will be deleted automatically. | |
432 | ||
433 | =item I<$tixgrid>->B<size>(I<dim>, I<index>?, I<-option>??=>I<value>, I<...>?) | |
434 | ||
435 | =item I<$tixgrid>->B<sizeColumn>(I<index>?, I<-option>??=>I<value>, I<...>?) | |
436 | ||
437 | =item I<$tixgrid>->B<sizeRow>(I<index>?, I<-option>??=>I<value>, I<...>?) | |
438 | ||
439 | Queries or sets the size of the row or column given by I<dim> and | |
440 | I<index>. I<Dim> may be B<row> or B<column>. I<Index> may be any | |
441 | non-negative integer that gives the position of a given row (or column). | |
442 | I<Index> can also be the string B<default>; in this case, this method | |
443 | queries or sets the default size of all rows (or columns). | |
444 | When no I<option-value> pair is given, this method returns | |
445 | a list containing the current size setting of the given row (or column). | |
446 | When I<option-value> pairs are given, the corresponding options | |
447 | of the size setting of the given row are changed. I<-option> may be | |
448 | one of the following: | |
449 | ||
450 | =over 8 | |
451 | ||
452 | =item B<-pad0> => I<pixels> | |
453 | ||
454 | Specifies the paddings to the left of a column or the top of a row. | |
455 | ||
456 | =item B<-pad1> => I<pixels> | |
457 | ||
458 | Specifies the paddings to the right of a column or the bottom of a row. | |
459 | ||
460 | =item B<-size> => I<val> | |
461 | ||
462 | Specifies the width of a column or the height of a row. | |
463 | I<Val> may be: B<auto> -- the width of the column is set | |
464 | the widest cell in the column; a valid Tk screen distance | |
465 | unit (see B<Tk_GetPixels>); or a real number following by the | |
466 | word B<chars> (e.g. B<3.4chars>) that sets the width of the | |
467 | column to the given number of characters. | |
468 | ||
469 | =back | |
470 | ||
471 | =item I<$tixgrid>->B<sort>(I<dimension>, I<start>, I<end>, ?I<args ...>?) | |
472 | ||
473 | ?docu here? (not supported on Win* OSs up to now) | |
474 | ||
475 | =item I<$tixgrid>->B<unset>(I<x>, I<y>) | |
476 | ||
477 | Clears the cell at (I<x>,I<y>) by removing its display item. | |
478 | ||
479 | =item I<$tixgrid>->B<xview> | |
480 | ||
481 | ?docu here? | |
482 | ||
483 | =item I<$tixgrid>->B<yview> | |
484 | ||
485 | ?docu here? | |
486 | ||
487 | =back | |
488 | ||
489 | =head1 BINDINGS | |
490 | ||
491 | to be done. | |
492 | ||
493 | =head1 SEE ALSO | |
494 | ||
495 | L<Tk::DItem|Tk::DItem> | |
496 | L<Tk::callbacks|Tk::callbacks> | |
497 | L<Tk::FloatEntry|Tk::FloatEntry> | |
498 | ||
499 | =head1 BUGS | |
500 | ||
501 | C code and bindings of TixGrid have some bugs. | |
502 | ||
503 | =head1 KEYWORDS | |
504 | ||
505 | tix, tixgrid, table, display item, spreadsheet | |
506 | ||
507 | =cut | |
508 |