1# See the file "license.terms" for information on usage and redistribution 2# of this file, and for a DISCLAIMER OF ALL WARRANTIES. 3# 4# 5 6 7 8=head1 NAME 9 10TableMatrix - Create and manipulate tables 11 12=head1 Synopsis 13 14I<$table> = I<$parent>-E<gt>B<TableMatrix>(?I<options>?); 15 16=head1 STANDARD OPTIONS 17 18B<-anchor -background -cursor 19 -exportselection -font -foreground -highlightbackground -highlightcolor 20 -highlightthickness -insertbackground -insertborderwidth -insertofftime 21 -insertontime -insertwidth -invertselected -relief -takefocus 22 -xscrollcommand -yscrollcommand> 23 24=head1 Widget-specific Options 25 26=over 1 27 28=item Switch: B<-autoclear> 29 30=item Name: B<autoClear> 31 32=item Class: B<AutoClear> 33 34A boolean value which specifies whether the first keypress in a cell will 35delete whatever text was previously there. Defaults to 0. 36 37=item Switch: B<-bordercursor> 38 39=item Name: B<borderCursor> 40 41=item Class: B<Cursor> 42 43Specifies the name of the cursor to show when over borders, a visual 44indication that interactive resizing is allowed (it is thus affect by 45the value of -resizeborders). Defaults to I<crosshair>. 46 47=item Switch: B<-borderwidth or -bd> 48 49=item Name: B<borderWidth> 50 51=item Class: B<BorderWidth> 52 53Specifies a non-negative pixel value or list of values indicating the width 54of the 3-D border to draw on interior table cells (if such a border is 55being drawn; the <Brelief> option typically determines this). If one 56value is specified, a rectangle of this width will be drawn. If two values 57are specified, then only the left and right edges of the cell will have 58borders. If four values are specified, then the values correspond to the 59{left right top bottom} edges. This can be overridden by the a tag's 60borderwidth option. It can also be affected by the defined 61B<-drawmode> for the table. Each value in the list must have one of 62the forms acceptable to B<Tk_GetPixels>. 63 64=item Switch: B<-browsecommand or -browsecmd> 65 66=item Name: B<browseCommand> 67 68=item Class: B<BrowseCommand> 69 70Specifies a command (callback) which will be evaluated 71anytime the active cell changes. The Previous Index and the Current index is passed to this 72command as arguments. 73 74=item Switch: B<-cache> 75 76=item Name: B<cache> 77 78=item Class: B<Cache> 79 80A boolean value that specifies whether an 81internal cache of the table contents should be kept. This greatly enhances 82speed performance when used with B<-command> but uses extra memory. Can maintain 83state when both B<-command> and B<-variable> are empty. The cache is automatically 84flushed whenever the value of B<-cache> or B<-variable> changes, otherwise you 85have to explicitly call B<clear> on it. Defaults to off. 86 87=item Switch: B<-colorigin> 88 89=item Name: B<colOrigin> 90 91=item Class: B<Origin> 92 93Specifies what column 94index to interpret as the leftmost column in the table. This value is used 95for user indices in the table. Defaults to 0. 96 97=item Switch: B<-cols> 98 99=item Name: B<cols> 100 101=item Class: B<Cols> 102 103Number of cols in the table. Defaults 104to 10. 105 106=item Switch: B<-colseparator> 107 108=item Name: B<colSeparator> 109 110=item Class: B<Separator> 111 112Specifies a separator character that will be interpreted 113as the column separator when cutting or pasting data in a table. By default, 114columns are separated as elements of a tcl list. 115 116=item Switch: B<-colstretchmode> 117 118=item Name: B<colStretchMode> 119 120=item Class: B<StretchMode> 121 122Specifies one 123of the following stretch modes for columns to fill extra allocated window 124space: 125 126=back 127 128=over 2 129 130=item B<none> 131 132Columns will not stretch to fill the assigned window space. 133If the columns are too narrow, there will be a blank space at the right 134of the table. This is the default. 135 136=item B<unset> 137 138Only columns that do not have 139a specific width set will be stretched. 140 141=item B<all> 142 143All columns will be stretched 144by the same number of pixels to fill the window space allocated to the 145table. This mode can interfere with interactive border resizing which 146tries to force column width. 147 148=item B<last> 149 150The last column will be stretched 151to fill the window space allocated to the table. 152 153=item B<fill> 154 155(only valid for 156B<-rowstretch> currently) 157 158The table will get more or less columns according 159to the window space allocated to the table. This mode has numerous quirks 160and may disappear in the future. 161 162=back 163 164=over 1 165 166=item Switch: B<-coltagcommand> 167 168=item Name: B<colTagCommand> 169 170=item Class: B<TagCommand> 171 172Provides the name of a 173procedure that will be evaluated by the widget to determine the tag to 174be used for a given column. When displaying a cell, the table widget will 175first check to see if a tag has been defined using the B<tag col> widget 176method. If no tag is found, it will evaluate the named procedure passing 177the column number in question as the sole argument. The procedure is expected 178to return the name of a tag to use, or a null string. Errors occuring during 179the evaluation of the procedure, or the return of an invalid tag name 180are silently ignored. 181 182The Current column number is passed as an argument to the col command. 183 184 185=item Switch: B<-colwidth> 186 187=item Name: B<colWidth> 188 189=item Class: B<ColWidth> 190 191Default column width, interpreted as characters 192in the default font when the number is positive, or pixels if it is negative. 193Defaults to 10. 194 195=item Switch: B<-command> 196 197=item Name: B<command> 198 199=item Class: B<Command> 200 201Specified a command to use as a procedural interface to 202cell values. If B<-usecommand> is true, this command will be used instead 203of any reference to the B<-variable> array. When retrieving cell values, 204the return value of the command is used as the value for the cell. 205 206Args passed to this callback: The Set Flag (=1 if setting, else retrieving), the current row, 207the current col, the cell value (if setting). 208 209=item Switch: B<-drawmode> 210 211=item Name: B<drawMode> 212 213=item Class: B<DrawMode> 214 215Sets 216the table drawing mode to one of the following options: 217 218=back 219 220=over 2 221 222=item B<slow> 223 224The table 225is drawn to an offscreen pixmap using the Tk bordering functions (double-buffering). 226This means there will be no flashing, but this mode is slow for larger 227tables. 228 229=item B<compatible> 230 231The table is drawn directly to the screen using the 232Tk border functions. It is faster, but the screen may flash on update. 233This is the default. 234 235=item B<fast> 236 237The table is drawn directly to the screen and 238the borders are done with fast X calls, so they are always one pixel wide 239only. As a side effect, it restricts B<-borderwidth> to a range of 0 or 1. 240This mode provides best performance for large tables, but can flash on 241redraw and is not 100% Tk compatible on the border mode. 242 243=item B<single> 244 245The table 246is drawn to the screen as in fast mode, but only single pixel lines are 247drawn (not square borders). 248 249=back 250 251=over 1 252 253=item Switch: B<-flashmode> 254 255=item Name: B<flashMode> 256 257=item Class: B<FlashMode> 258 259A boolean value which specifies whether 260cells should flash when their value changes. The table tag B<flash> will 261be applied to these cells for the duration specified by B<-flashtime>. Defaults 262to 0. 263 264=item Switch: B<-flashtime> 265 266=item Name: B<flashTime> 267 268=item Class: B<FlashTime> 269 270The amount of time, in 1/4 second increments, for which a cell 271should flash when its value has changed. B<-flashmode> must be on. Defaults 272to 2. 273 274=item Switch: B<-height> 275 276=item Name: B<height> 277 278=item Class: B<Height> 279 280Specifies the desired height for the window, in rows. If zero or less, 281then the desired height for the window is made just large enough to hold 282all the rows in the table. The height can be further limited by B<-maxheight 283>. 284 285=item Switch: B<-invertselected> 286 287=item Name: B<invertSelected> 288 289=item Class: B<InvertSelected> 290 291Specifies whether the foreground and background 292of an item should simply have their values swapped instead of merging 293the I<sel> tag options when the cell is selected. Defaults to 0 (merge I<sel> tag). 294 295=item Switch: B<-ipadx> 296 297=item Name: B<ipadX> 298 299=item Class: B<Pad> 300 301A pixel value specifying the internal offset X padding for text in a cell. 302This value does not grow the size of the cell, it just causes the text to 303be drawn further from the cell border. It only affects one side (depending 304on anchor). Defaults to 0. See B<-padx> for an alternate padding 305style. 306 307=item Switch: B<-ipady> 308 309=item Name: B<ipadY> 310 311=item Class: B<Pad> 312 313A pixel value specifying the internal offset Y padding for text in a cell. 314This value does not grow the size of the cell, it just causes the text to 315be drawn further from the cell border. It only affects one side (depending 316on anchor). Defaults to 0. See B<-pady> for an alternate padding 317style. 318 319=item Switch: B<-justify> 320 321=item Name: B<justify> 322 323=item Class: B<Justify> 324 325How to justify multi-line text in a cell. It must 326be one of B<left>, B<right>, or B<center>. Defaults to 327left. 328 329=item Switch: B<-maxheight> 330 331=item Name: B<maxHeight> 332 333=item Class: B<MaxHeight> 334 335The max height in pixels that the window will request. Defaults 336to 600. 337 338=item Switch: B<-maxwidth> 339 340=item Name: B<maxWidth> 341 342=item Class: B<MaxWidth> 343 344The max width in pixels that the window will request. Defaults 345to 800. 346 347=item Switch: B<-multiline> 348 349=item Name: B<multiline> 350 351=item Class: B<Multiline> 352 353Specifies the default setting for the multiline tag 354option. Defaults to 1. 355 356=item Switch: B<-pady> 357 358=item Name: B<padX> 359 360=item Class: B<Pad> 361 362A pixel value specifying the offset X padding for a cell. This value 363causes the default size of the cell to increase by two times the value (one 364for each side), unless a specific pixel size is chosen for the cell with 365the B<width> command. This will force an empty area on the left and 366right of each cell edge. This padding affects all types of data in the 367cell. Defaults to 0. See B<-ipadx> for an alternate padding style. 368 369=item Switch: B<-pady> 370 371=item Name: B<padY> 372 373=item Class: B<Pad> 374 375A pixel value specifying the offset Y padding for a cell. This value 376causes the default size of the cell to increase by two times the value (one 377for each side), unless a specific pixel size is chosen for the cell with 378the B<height> command. This will force an empty area on the top and 379bottom of each cell edge. This padding affects all types of data in the 380cell. Defaults to 0. See B<-ipadx> for an alternate padding style. 381 382=item Switch: B<-resizeborders> 383 384=item Name: B<resizeBorders> 385 386=item Class: B<ResizeBorders> 387 388Specifies what kind of interactive 389border resizing to allow, must be one of row, col, both (default) or none. 390 391=item Switch: B<-rowheight> 392 393=item Name: B<rowHeight> 394 395=item Class: 396 397B<RowHeight> Default row height, interpreted as lines in the default font 398when the number is positive, or pixels if it is negative. Defaults to 3991. 400 401=item Switch: B<-roworigin> 402 403=item Name: B<rowOrigin> 404 405=item Class: B<Origin> 406 407Specifies what row index to interpret as the topmost row in the 408table. This value is used for user indices in the table. Defaults to 0. 409 410=item Switch: B<-rows> 411 412=item Name: B<rows> 413 414=item Class: B<Rows> 415 416Number 417of rows in the table. Defaults to 10. 418 419=item Switch: B<-rowseparator> 420 421=item Name: B<rowSeparator> 422 423=item Class: B<Separator> 424 425Specifies a separator character 426that will be interpreted as the row separator when cutting or pasting 427data in a table. By default, rows are separated as tcl lists. 428 429=item Switch: B<-rowstretchmode> 430 431=item Name: B<rowStretchMode> 432 433=item Class: B<StretchMode> 434 435Specifies the stretch modes for rows to fill extra allocated window space. 436See B<-colstretchmode> for valid options. 437 438=item Switch: B<-rowtagcommand> 439 440=item Name: B<rowTagCommand> 441 442=item Class: B<TagCommand> 443 444Provides the 445name of a procedure that can evaluated by the widget to determine the 446tag to be used for a given row. The procedure must be defined by the user 447to accept a single argument (the row number), and return a tag name or 448null string. This operates in a similar manner as B<-coltagcommand>, except 449that it applies to row tags. 450 451The Current row number is passed as an argument to the row command. 452 453=item Switch: B<-selectioncommand or -selcmd> 454 455=item Name: B<selectionCommand> 456 457=item Class: B<SelectionCommand> 458 459Specifies 460a command (callback) to evaluate when the selection is retrieved from a table via 461the selection mechanism (ie: evaluating "B<selection get>"). The return value 462from this command will become the string passed on by the selection mechanism. 463The following arguments are passed to this callback: The number of rows in the 464selection, number of columns in the selection, the selection string, the number 465of cell in the selection. 466 467=item Switch: B<-selectmode> 468 469=item Name: B<selectMode> 470 471=item Class: B<SelectMode> 472 473Specifies one of several styles for manipulating the 474selection. The value of the option may be arbitrary, but the default bindings 475expect it to be either B<single>, B<browse>, B<multiple>, or B<extended>; the 476default value is B<browse>. These styles are like those for the Tk listbox, 477except expanded for 2 dimensions. 478 479=item Switch: B<-selecttitle> 480 481=item Name: B<selectTitles> 482 483=item Class: B<SelectTitles> 484 485Specifies whether title 486cells should be allowed in the selection. Defaults to 0 (disallowed). 487 488=item Switch: B<-selecttype> 489 490=item Name: B<selectType> 491 492=item Class: B<SelectType> 493 494Specifies one of several types of selection for the table. The value 495of the option may be one of B<row>, B<col>, B<cell>, or B<both> (meaning B<row && 496col>); the default value is B<cell>. These types define whether an entire 497row/col is affected when a cell's selection is changed (set or clear). 498 499=item Switch: B<-sparsearray> 500 501=item Name: B<sparseArray> 502 503=item Class: B<SparseArray> 504 505A boolean value that specifies whether an associated Tcl 506array should be kept as a sparse array (1, the default) or as a full array 507(0). If true, then cell values that are empty will be deleted from the 508array (taking less memory). If false, then all values in the array will 509be maintained. 510 511=item Switch: B<-state> 512 513=item Name: B<state> 514 515=item Class: B<State> 516 517Specifies one of two states for the entry: B<normal> or B<disabled>. 518If the table is disabled then the value may not be changed using widget 519commands and no insertion cursor will be displayed, even if the input 520focus is in the widget. Also, all insert or delete methods will be ignored. 521Defaults to B<normal>. 522 523=item Switch: B<-titlecols> 524 525=item Name: B<titleCols> 526 527=item Class: B<TitleCols> 528 529Number of columns to use as a title area. Defaults 530to 0. 531 532=item Switch: B<-titlerows> 533 534=item Name: B<titleRows> 535 536=item Class: B<TitleRows> 537 538Number of rows to use as a title area. Defaults to 0. 539 540=item Switch: B<-usecommand> 541 542=item Name: B<useCommand> 543 544=item Class: B<UseCommand> 545 546A boolean value which specifies whether to use the B<command> option. This 547value sets itself to zero if B<command> is used and returns an error. Defaults 548to 1 (will use B<command> if specified). 549 550=item Switch: B<-validate> 551 552=item Name: B<validate> 553 554=item Class: B<Validate> 555 556A boolean specifying whether 557validation should occur for the active buffer. Defaults to 0. 558 559=item Switch: B<-validatecommand or -vcmd> 560 561=item Name: B<validateCommand> 562 563=item Class: B<ValidateCommand> 564 565Specifies a command (callback) to execute when the active 566cell is edited. This command is expected to return a 1 or 0. If it 567returns 1, then it is assumed the new value is OK, otherwise the new 568value is rejected (the edition will not take place). Errors in this command 569are handled in the background. The following arguments are supplied to the callback: 570row, col, oldContents of cell, potential new contents of cell, Current Index in the cell. 571 572 573=item Switch: B<-variable> 574 575=item Name: B<variable> 576 577=item Class: B<Variable> 578 579Global Tcl array variable to attach 580to the table's C array. It will be created if it doesn't already exist or 581is a simple variable. Keys used by the table in the array are of the form 582I<row>,I<col> for cells and the special key I<active> which contains the value 583of the active cell buffer. The Tcl array is managed as a sparse array 584(the table doesn't require all valid indices have values). No stored value 585for an index is equivalent to the empty string, and clearing a cell will 586remove that index from the Tcl array, unless the B<-sparsearray> options 587is set to 0. 588 589=item Switch: B<-width> 590 591=item Name: B<width> 592 593=item Class: B<Width> 594 595Specifies the desired width for the window, in columns. If zero 596or less, then the desired width for the window is made just large enough 597to hold all the columns in the table. The width can be further limited 598by B<-maxwidth>. 599 600=item Switch: B<-wrap> 601 602=item Name: B<wrap> 603 604=item Class: B<Wrap> 605 606Specifies the default wrap value for tags. Defaults to 0. 607 608=back 609 610=head1 DESCRIPTION 611 612 613The B<TableMatrix> command creates a 2-dimensional grid of cells. The table can 614use a Tcl array variable or Tcl command for data storage and retrieval. 615The widget has an active cell, the contents of which can be edited (when 616the state is normal). The widget supports a default style for the cells 617and also multiple I<tags>, which can be used to change the style of a row, 618column or cell (see TAGS for details). A cell I<flash> can be set up so 619that changed cells will change color for a specified amount of time ("blink"). 620 Cells can have embedded images or windows, as described in L<Tags> and L<Embedded Windows> respectively. 621 622One or more cells may be selected as described below. 623 If a table is exporting its selection (see B<-exportselection> option), 624then it will observe the standard X11 protocols for handling the selection. 625 See L<the Selection> for details. It is not necessary for all the cells to 626be displayed in the table window at once; commands described below may 627be used to change the view in the window. Tables allow scrolling in both 628directions using the standard B<-xscrollcommand> and B<-yscrollcommand> options. 629 They also support scanning, as described below. 630 631In order to obtain good 632performance, the table widget supports multiple drawing modes, two of 633which are fully Tk compatible. 634 635=head1 Indices 636 637Many of the widget commands for tables take one or 638more indices as arguments. An index specifies a particular cell of the 639table, in any of the following ways: 640 641=over 1 642 643=item I<number,number> 644 645Specifies the cell 646as a numerical index of row,col which corresponds to the index of the 647associated Perl Hash, where B<-roworigin,-colorigin> corresponds to the first 648cell in the table (0,0 by default). The values for row 649and column will be constrained to actual values 650in the table, which means a valid cell is 651always found. 652 653=item B<active> 654 655Indicates the cell that has 656the location cursor. It is specified with the B<activate> widget command. 657 658=item B<anchor> 659 660Indicates the anchor point for the selection, which is set with 661the B<selection anchor> widget command. 662 663=item B<bottomright> 664 665Indicates the bottom-rightmost 666cell visible in the table. 667 668=item B<end> 669 670Indicates the bottom right cell of the 671table. 672 673=item B<origin> 674 675Indicates the top-leftmost editable cell of the table, not 676necessarily in the display. This takes into account the user specified 677origin and title area. 678 679=item B<topleft> 680 681Indicates the top-leftmost editable cell 682visible in the table (this excludes title cells). 683 684=item B<@x,y> 685 686Indicates the 687cell that covers the point in the table window specified by I<x> and I<y> 688(in pixel coordinates). If no cell covers that point, then the closest 689cell to that point is used. In the widget command descriptions below, arguments 690named I<index>, I<first>, and I<last> always contain text indices in one of 691the above forms. 692 693=back 694 695=head1 Tags 696 697A tag is a textual string that is associated with zero or more rows, 698columns or cells in a table. Tags may contain arbitrary characters, but it 699is probably best to avoid using names which look like indices to reduce 700coding confusion. There may be any number of tags in a table, but each 701row, column or cell can only have one tag associated with it at a time. 702There are several permanent tags in each table that can be configured by 703the user and will determine the attributes for special cells: 704 705=over 1 706 707=item B<active> 708 709This tag is given to the I<active> cell 710 711=item B<flash> 712 713If flash 714mode is on, this tag is given to any recently edited cells. 715 716=item B<sel> 717 718This 719tag is given to any selected cells. 720 721=item B<title> 722 723This tag is given to any cells 724in the title rows and columns. This tag has B<-state> I<disabled> by default. 725 726=back 727 728Tags control the way cells are displayed on the screen. Where appropriate, 729the default for displaying cells is determined by the options for the 730table widget. However, display options may be associated with individual 731tags using the L<tagConfigure> method. If a cell, row or column has been 732tagged, then the display options associated with the tag override the 733default display style. The following options are currently supported for 734tags: 735 736=over 1 737 738=item B<-anchor> I<anchor> 739 740Anchor for item in the cell space. 741 742=item B<-background> or B<-bg> I<color> 743 744Background color of the cell. 745 746=item B<-borderwidth> or B<-bd> I<pixel> 747 748Borderwidth of the cell, of the same format for the table, but may also 749be empty to inherit the default table borderwidth value (the default). 750 751=item B<-font> I<fontName> 752 753Font for text in the cell. 754 755=item B<-foreground> or B<-fg> I<color> 756 757Foreground color of the cell. 758 759=item B<-justify> I<justify> 760 761How to 762justify multi-line text in a cell. It must be one of B<left>, B<right>, or B<center>. 763 764=item B<-image> I<imageName> 765 766An image to display in the cell instead of text. 767 768=item B<-multiline> I<boolean> 769 770Whether to display text with newlines on multiple lines. 771 772=item B<-relief> 773 774The relief for the cell. May be the empty 775string to cause this tag to not disturb the 776value. 777 778=item B<-showtext> I<boolean> 779 780Whether to show the text over an image. 781 782=item B<-state> I<state> 783 784The state of the cell, to allow for certain cells 785to be disabled. This prevents the cell from being edited by the I<insert 786> or I<delete> methods, but a direct I<set> will not be prevented. 787 788=item B<-wrap> I<boolean> 789 790Whether characters should wrap in a cell that is not wide enough. 791 792=back 793 794A priority order is defined among tags based on creation order (first 795created tag has highest default priority), and this order is used in 796implementing some of the tag-related functions described below. When a cell 797is displayed, its properties are determined by the tags which are assigned 798to it. The priority of a tag can be modified by the I<tagLower> and the 799I<tagRaise> methods. 800 801If a cell has several tags associated with it that define the same display 802options (eg - a B<title> cell with specific B<row> and B<cell> 803tags), then the options of the highest priority tag are used. If a 804particular display option hasn't been specified for a particular tag, or if 805it is specified as an empty string, then that option will not be used; the 806next-highest-priority tag's option will be used instead. If no tag 807specifies a particular display option, then the default style for the 808widget will be used. 809 810Images are used for display purposes 811only. Editing in that cell will still be enabled and any querying of the 812cell will show the text value of the cell, regardless of the value of 813B<-showtext>. 814 815Note: There can be only one tag for a given tag type. ( Tag types = B<flash>, B<active>, B<sel>, B<title>, 816B<celltag> B<rowtag>, B<coltag>.) For example, you can't apply two cell tags to a single cell (or two row tags to a 817single row, etc) and expect the tag's properties to be merged. The last tag-type applied will be the one that 818is used. 819 820 821=head1 Embedded Windows 822 823There may be any number of embedded windows 824in a table widget (one per cell), and any widget may be used as an embedded 825window (subject to the usual rules for geometry management, which require 826the table window to be the parent of the embedded window or a descendant 827of its parent). The embedded window's position on the screen will be updated 828as the table is modified or scrolled, and it will be mapped and unmapped 829as it moves into and out of the visible area of the table widget. Each 830embedded window occupies one cell's worth of space in the table widget, 831and it is referred to by the index of the cell in the table. Windows associated 832with the table widget are destroyed when the table widget is destroyed. 833 834Windows are used for display purposes only. A value still exists for that 835cell, but will not be shown unless the window is deleted in some way. 836If the window is destroyed or lost by the table widget to another geometry 837manager, then any data associated with it is lost (the cell it occupied 838will no longer appear in B<window names>). 839 840When an embedded window is added 841to a table widget with the window configure widget command, several configuration 842options may be associated with it. These options may be modified with 843later calls to the window configure widget command. The following options 844are currently supported: 845 846=over 1 847 848=item B<-create> I<callback> 849 850NOT CURRENTLY SUPPORTED. Specifies 851a Tcl script that may be evaluated to create the window for the annotation. 852 If no -window option has been specified for this cell then this script 853will be evaluated when the cell is about to be displayed on the screen. 854 Script must create a window for the cell and return the name of that 855window as its result. If the cell's window should ever be deleted, the script 856will be evaluated again the next time the cell is displayed. 857 858=item B<-background> or B<-bg> I<color> 859 860Background color of the cell. If not specified, it uses 861the table's default background. 862 863=item B<-borderwidth> or B<-bd> I<pixelList> 864 865Borderwidth of the cell, of the same format for the table, but may also 866be empty to inherit the default table borderwidth value (the default). 867 868=item B<-padx> I<pixels> 869 870As defined in the Tk options 871man page. 872 873=item B<-pady> I<pixels> 874 875As defined in the Tk options man page. 876 877=item B<-relief> I<relief> 878 879The relief to use for the cell in which the window lies. If not specified, 880it uses the table's default relief. 881 882=item B<-sticky> I<sticky> 883 884Stickiness of the window 885inside the cell, as defined by the B<grid> command. 886 887=item B<-window> I<$widget> 888 889Specifies 890the a window to display in the annotation. It must exist before 891being specified here. 892 893=back 894 895=head1 the Selection 896 897Table selections are available as 898type STRING. By default, the value of the selection will be the values 899of the selected cells in nested Tcl list form where each row is a list 900and each column is an element of a row list. You can change the way this 901value is interpreted by setting the B<-rowseparator> and B<-colseparator> options. 902 For example, default Excel format would be to set B<-rowseparator> to "\n" 903and B<-colseparator> to "\t". Changing these values affects both how the table 904sends out the selection and reads in pasted data, ensuring that the table 905should always be able to cut and paste to itself. It is possible to change 906how pastes are handled by editing the table library procedure B<tk_tablePasteHandler 907>. This might be necessary if B<-selectioncommand> is set. 908 909=head1 Row/Col Spanning 910 911Individual cells can span multiple rows and/or columns. This is done via 912the B<spans> command (see below for exact arguments). Cells in the title 913area that span are not permitted to span beyond the title area, and will 914be constrained accordingly. If the title area shrinks during a configure, 915sanity checking will occur to ensure the above. You may set spans on regular 916cells that extend beyond the defined row/col area. These spans will not 917be constrained, so that when the defined row/col area expands, the span 918will expand with it. 919 920When setting a span, checks are made as to whether 921the span would overlap an already spanning or hidden cell. This is an 922error and it not allowed. Spans can affect the overall speed of table drawing, 923although not significantly. If spans are not used, then there is no performance 924loss. 925 926Cells I<hidden> by spanning cells still have valid data. This will 927be seen during cut and paste operations that involve hidden cells, or 928through direct access by a command like B<get> or B<set>. 929 930The drawing properties 931of spanning cells apply to only the visual area of the cell. For example, 932if a cell is center justified over 5 columns, then when viewing any portion 933of those columns, it will appear centered in the visible area. The non-visible 934column area will not be considered in the centering calculations. 935 936=head1 Command Substitution 937 938The various option based commands that the table supports 939all support the familiar Tk %-substitution model (see L<Tk::bind> for more details). 940 The following %-sequences are recognized and substituted by the table 941widget: 942 943=over 1 944 945=item B<%c> 946 947For B<SelectionCommand>, it is the maximum number of columns 948in any row in the selection. Otherwise it is the column of the triggered 949cell. 950 951=item B<%C> 952 953A convenience substitution for I<%r>,I<%c>. 954 955=item B<%i> 956 957For B<SelectionCommand>, it is the total number of cells in the selection. For B<Command>, it is 9580 for a read (get) and 1 for a write (set). Otherwise it is the current 959cursor position in the cell. 960 961=item B<%r> 962 963For B<SelectionCommand>, it is the number 964of rows in the selection. Otherwise it is the row of the triggered cell. 965 966=item B<%s> 967 968For B<ValidateCommand>, it is the current value of the cell being validated. 969For B<SelectionCommand>, it is the default value of the selection. For B<BrowseCommand 970>, it is the index of the last active cell. For B<Command>, it is empty for 971reads (get) and the current value of the cell for writes (set). 972 973=item B<%S> 974 975For 976B<ValidateCommand>, it is the potential new value of the cell being validated. 977For B<BrowseCommand>, it is the index of the new active cell. 978 979=item B<%W> 980 981The pathname 982to the window for which the command was generated. 983 984=back 985 986=head1 Widget Methods 987 988The 989B<$window->E<gt>B<TableMatrix> method creates a widget object. This object supports the B<configure> and B<cget> methods 990described in L<Tk::options> which can be used to enquire and 991modify the options described above. 992The widget also inherits all the methods provided by the generic 993L<Tk::Widget|Tk::Widget> class. 994 995 996The following additional methods are available for scale widgets: 997 998=over 1 999 1000=item I<$table>-E<gt>B<activate>(I<index>) 1001 1002Sets the active 1003cell to the one indicated by I<index>. 1004 1005=item I<$table>-E<gt>B<bbox>(I<first>, ?I<last>?) 1006 1007It 1008returns the bounding box for the specified cell (range) as a 4-tuple of 1009x, y, width and height in pixels. It clips the box to the visible portion, 1010if any, otherwise an empty string is returned. 1011 1012=item I<$table>-E<gt>B<border>(I<option, args>) 1013 1014This command is a voodoo hack to implement border sizing for tables. 1015This is normally called through bindings, with the following as valid 1016options: 1017 1018=back 1019 1020=over 2 1021 1022=item I<$table>-E<gt>B<borderMark>(I<x, y>, ?I<row|col>?) 1023 1024Records I<x> and I<y> and 1025the row and/or column border under that point in the table window, if 1026any; used in conjunction with later B<border dragto> commands. Typically 1027this command is associated with a mouse button press in the widget. If 1028I<row> or I<col> is not specified, it returns a tuple of both border indices 1029(an empty item means no border). Otherwise, just the specified item is 1030returned. 1031 1032=item I<$table>-E<gt>B<borderDragto>(I<x, y>) 1033 1034This command computes the difference 1035between its I<x> and I<y> arguments and the I<x> and I<y> arguments to the last 1036B<border mark> command for the widget. It then adjusts the previously marked 1037border by the difference. This command is typically associated with mouse 1038motion events in the widget, to produce the effect of interactive border 1039resizing. 1040 1041=back 1042 1043=over 1 1044 1045=item I<$table>-E<gt>B<cget>(I<option>) 1046 1047Returns the current value of the configuration 1048option given by I<option>. I<Option> may have any of the values accepted by 1049the B<table> command. 1050 1051=item I<$table>-E<gt>B<clear>(I<option>, ?I<first>?, ?I<last>?) 1052 1053This command 1054is a convenience routine to clear certain state information managed by 1055the table. I<first> and I<last> represent valid table indices. If neither 1056are specified, then the command operates on the whole table. The following 1057options are recognized: 1058 1059=back 1060 1061=over 2 1062 1063=item I<$table>-E<gt>B<clearCache>(?I<first>?, ?I<last>?) 1064 1065Clears 1066the specified section of the cache, if the table has been keeping one. 1067 1068=item I<$table>-E<gt>B<clearSizes>(?I<first>?, ?I<last>?) 1069 1070Clears the specified row and column 1071areas of specific height/width dimensions. When just one index is specified, 1072for example B<2,0>, that is interpreted as row 2 B<and> column 0. 1073 1074=item I<$table>-E<gt>B<clearTags>(?I<first>?, ?I<last>?) 1075 1076Clears the specified area of tags (all row, 1077column and cell tags). 1078 1079=item I<$table>-E<gt>B<clearAll>(?I<first>?, ?I<last>?) 1080 1081Performs all 1082of the above clear functions on the specified area. 1083 1084=back 1085 1086=over 1 1087 1088=item I<$table>-E<gt>B<colWidth>(?I<col>?, ?I<value, col, value, ...>?) 1089 1090If no I<col> is 1091specified, returns a list describing all cols for which a width has been 1092set. If B<col> is specified with no value, it prints out the width of that 1093col in characters (positive number) or pixels (negative number). If one 1094or more I<col-value> pairs are specified, then it sets each col to be that 1095width in characters (positive number) or pixels (negative number). If 1096I<value> is I<default>, then the col uses the default width, specified by 1097B<-colwidth>. 1098 1099 1100=over 1 1101 1102=item I<$table>-E<gt>B<configure>(?I<option>?, ?I<value, option, value, ...>?) 1103 1104Query or modify the configuration options 1105of the widget. If no I<option> is specified, returns a list describing all 1106of the available options for I<pathName> (see B<Tk_ConfigureInfo> for information 1107on the format of this list). If I<option> is specified with no I<value>, then 1108the command returns a list describing the one named option (this list 1109will be identical to the corresponding sublist of the value returned if 1110no I<option> is specified). If one or more I<option-value> pairs are specified, 1111then the command modifies the given widget option(s) to have the given 1112value(s); in this case the command returns an empty string. I<Option> may 1113have any of the values accepted by the B<table> command. 1114 1115=item I<$table>-E<gt>B<curselection>(?I<value>?) 1116 1117With no arguments, it returns the sorted indices of the currently 1118selected cells. Otherwise it sets all the selected cells to the given 1119value. The set has no effect if there is no associated Tcl array or the 1120state is disabled. 1121 1122=item I<$table>-E<gt>B<curvalue>(?I<value>?) 1123 1124If no value is given, the 1125value of the cell being edited (indexed by B<active>) is returned, else 1126it is set to the given value. 1127 1128=item I<$table>-E<gt>B<delete>(I<option, arg>, ?I<arg>?) 1129 1130This 1131command is used to delete various things in a table. It has several forms, 1132depending on the I<option>: 1133 1134=back 1135 1136=over 2 1137 1138=item I<$table>-E<gt>B<deleteActive>(I<index>, ?I<index>?) 1139 1140Deletes text from the active cell. If only one index is given, it deletes the 1141character after that index, otherwise it deletes from the first index 1142to the second. I<index> can be a number, B<insert> or B<end>. 1143 1144=item I<$table>-E<gt>B<deleteCols>(?I<switches>?, I<index>, ?I<count>?) 1145 1146Deletes I<count> cols starting at (and 1147including) col I<index>. The I<index> will be constrained to the limits of 1148the tables. If I<count> is negative, it deletes cols to the left. Otherwise 1149it deletes cols to the right. I<count> defaults to 1 (meaning just the column 1150specified). The selection will be cleared. At the moment, spans are not 1151adjusted with this action. Optional switches are: 1152 1153=back 1154 1155=over 3 1156 1157=item B<-holddimensions> 1158 1159Causes 1160the table cols to be unaffected by the deletion (empty cols may appear). 1161 By default the dimensions are adjusted by B<count>. 1162 1163=item B<-holdtags> 1164 1165Causes the 1166tags specified by the I<tag> method to not move along with the data. Also 1167prevents specific widths set by the I<width> method from being adjusted. 1168 By default, these tags are properly adjusted. 1169 1170=item B<-holdwindows> 1171 1172Causes the 1173embedded windows created with the I<window> method to not move along with 1174the data. By default, these windows are properly adjusted. 1175 1176=item B<-keeptitles> 1177 1178Prevents title area cells from being changed. Otherwise they are treated 1179just like regular cells and will move as specified. 1180 1181=back 1182 1183=over 2 1184 1185=item I<$table>-E<gt>B<deleteRows>(?I<switches>?, I<index>, ?I<count>?) 1186 1187Deletes B<count> rows starting at (and including) row B<index>. If B<count> is negative, 1188it deletes rows going up. Otherwise it deletes rows going down. The selection 1189will be cleared. The switches are the same as those for column deletion. 1190 1191=back 1192 1193=over 1 1194 1195=item I<$table>-E<gt>B<get>(I<first>, ?I<last>?) 1196 1197Returns the value of the cells specified 1198by the table indices I<first> and (optionally) I<last> in a list. 1199 1200 1201=item I<$table>-E<gt>B<hidden>(?I<index>?, ?I<index, ...>?) 1202 1203When called without args, it returns all the I<hidden> cells 1204(those cells covered by a spanning cell). If one index is specified, it 1205returns the spanning cell covering that index, if any. If multiple indices 1206are specified, it returns 1 if all indices are hidden cells, 0 otherwise. 1207 1208=item I<$table>-E<gt>B<icursor>(?I<arg>?) 1209 1210With no arguments, prints out the location of 1211the insertion cursor in the active cell. With one argument, sets the cursor 1212to that point in the string. 0 is before the first character, you can 1213also use B<insert> or B<end> for the current insertion point or the end of 1214the text. If there is no active cell, or the cell or table is disabled, 1215this will return -1. 1216 1217=item I<$table>-E<gt>B<index>(I<index>, ?I<row|col>?) 1218 1219Returns the integer 1220cell coordinate that corresponds to I<index> in the form row,col. If B<row 1221> or B<col> is specified, then only the row or column index is returned. 1222 1223=item I<$table>-E<gt>B<insert>(I<option, arg, arg>) 1224 1225This command is used to into various things into 1226a table. It has several forms, depending on the I<option>: 1227 1228=back 1229 1230=over 2 1231 1232=item I<$table>-E<gt>B<insertActive>(I<index, value>) 1233 1234The I<value> is a text string which is inserted at 1235the I<index> postion of the active cell. The cursor is then positioned after 1236the new text. I<index> can be a number, B<insert> or B<end>. 1237 1238=item I<$table>-E<gt>B<insertCols>(?I<switches>?, I<index>, ?I<count>?) 1239 1240Inserts B<count> cols starting at col B<index>. If B<count> is negative, it inserts before the specified col. Otherwise 1241it inserts after the specified col. The selection will be cleared. The 1242switches are the same as those for column deletion. 1243 1244=item I<$table>-E<gt>B<insertRows>(?I<switches>?, I<index>, ?I<count>?) 1245 1246Inserts B<count> rows starting at row B<index>. If B<count> is negative, it inserts before the specified row. Otherwise 1247it inserts after the specified row. The selection will be cleared. The 1248switches are the same as those for column deletion. 1249 1250=back 1251 1252=over 1 1253 1254=item I<$table>-E<gt>B<reread>() 1255 1256Rereads the old contents of the cell back into the editing buffer. Useful 1257for a key binding when <Escape> is pressed to abort the edit (a default 1258binding). 1259 1260=item I<$table>-E<gt>B<rowHeight>(?I<row>?, ?I<value, row, value, ...>?) 1261 1262If no I<row> is specified, returns a 1263list describing all rows for which a height has been set. If B<row> is specified 1264with no value, it prints out the height of that row in characters (positive 1265number) or pixels (negative number). If one or more I<row-value> pairs are 1266specified, then it sets each row to be that height in lines (positive 1267number) or pixels (negative number). If I<value> is I<default>, then the row 1268uses the default height, specified by B<-rowheight>. 1269 1270=item I<$table>-E<gt>B<scan>(I<option, args>) 1271 1272This command is used to implement 1273scanning on tables. It has two forms, depending on I<option>: 1274 1275=back 1276 1277=over 2 1278 1279=item I<$table>-E<gt>B<scanMark>(I<x, y>) 1280 1281Records I<x> and I<y> and the current view in the table window; 1282 used in conjunction with later B<scan dragto> commands. Typically this command 1283is associated with a mouse button press in the widget. It returns an empty 1284string. 1285 1286=item I<$table>-E<gt>B<scanDragto>(I<x, y>.) 1287 1288This command computes the difference 1289between its I<x> and I<y> arguments and the I<x> and I<y> arguments to the last 1290B<scan mark> command for the widget. It then adjusts the view by 5 times 1291the difference in coordinates. This command is typically associated with 1292mouse motion events in the widget, to produce the effect of dragging the 1293list at high speed through the window. The return value is an empty string. 1294 1295=back 1296 1297=over 1 1298 1299=item I<$table>-E<gt>B<see>(I<index>) 1300 1301Adjust the view in the table so that the cell given 1302by I<index> is positioned as the cell one off from top left (excluding title 1303rows and columns) if the cell is not currently visible on the screen. 1304The actual cell may be different to keep the screen full. 1305 1306=item I<$table>-E<gt>B<selection>(I<option, arg>) 1307 1308This command is used to adjust the selection within a table. 1309 It has several forms, depending on I<option>: 1310 1311=back 1312 1313=over 2 1314 1315=item I<$table>-E<gt>B<selectionAnchor>(I<index>) 1316 1317Sets the selection anchor to the cell given by I<index>. The selection 1318anchor is the end of the selection that is fixed while dragging out a 1319selection with the mouse. The index B<anchor> may be used to refer to the 1320anchor cell. 1321 1322=item I<$table>-E<gt>B<selectionClear>(I<first>?I<last>?) 1323 1324If any of the cells 1325between I<first> and I<last> (inclusive) are selected, they are deselected. 1326 The selection state is not changed for cells outside this range. I<first> may be specified as B<all> to remove the selection from all cells. 1327 1328=item I<$table>-E<gt>B<selectionIncludes>(I<index>) 1329 1330Returns 1 if the cell indicated by I<index> 1331is currently selected, 0 if it isn't. 1332 1333=item I<$table>-E<gt>B<selectionSet>(I<first>, ?I<last>?) 1334 1335Selects all of the cells in the range between I<first> and I<last>, inclusive, 1336without affecting the selection state of cells outside that range. 1337 1338=back 1339 1340perltk note this needs to be perlized 1341 1342=over 1 1343 1344=item I<$table>-E<gt>B<set>(?I<row|col>?, I<index>, ?I<value>?, ?I<index, value, ...>?) 1345 1346 1347 1348Sets the specified index 1349to the associated value. Table validation will not be triggered via this 1350method. If B<row> or B<col> precedes the list of index/value pairs, then the 1351value is assumed to be a Tcl list whose values will be split and set into 1352the subsequent columns (if B<row> is specified) or rows (for B<col>). For 1353example, B< set row 2,3 {2,3 2,4 2,5}> will set 3 cells, from 2,3 to 2,5. 1354The setting of cells is silently bounded by the known table dimensions. 1355 1356=item I<$table>-E<gt>B<spans>(?I<index>?, ?I<rows,cols, index, rows,cols, ...>?) 1357 1358This command is 1359used to manipulate row/col spans. When called with no arguments, all known 1360spans are returned as a list of tuples of the form {index span}. When 1361called with only the I<index>, the span for that I<index> only is returned, 1362if any. Otherwise an even number of I<index rows,cols> pairs are used to 1363set spans. A span starts at the I<index> and continues for the specified 1364number of rows and cols. Negative spans are not supported. A span of 0,0 1365unsets any span on that cell. See EXAMPLES for more info. 1366 1367=item I<$table>-E<gt>B<tag>(option, ?I<arg, arg, ...>?) 1368 1369This command is used to manipulate tags. The exact 1370behavior of the command depends on the I<option> argument that follows the 1371B<tag> argument. I<cget>, I<cell>, and I<row|col> complain about unknown tag names. 1372The following forms of the command are currently supported: 1373 1374=back 1375 1376=over 2 1377 1378=item I<$table>-E<gt>B<tagCell>(I<tagName, ?index, ...?>) 1379 1380With no arguments, prints out the list of cells that use the I<tag>. 1381Otherwise it sets the specified cells to use the named tag, replacing any 1382tag that may have been set using this method before. If I<tagName> is 1383'', the cells are reset to the default I<tag>. Tags added during 1384-*tagcommand evaluation do not register here. If I<tagName> does 1385not exist, it will be created with the default options. 1386 1387=item I<$table>-E<gt>B<tagCget>(I<tagName, option>) 1388 1389This command returns the current value of the option 1390named I<option> associated with the tag given by I<tagName>. I<Option> may have 1391any of the values accepted by the B<tag configure> widget command. 1392 1393=item I<$table>-E<gt>B<tagCol>(I<tagName, ?col, ...?>) 1394 1395With no arguments, prints out the list of cols that use the I<tag>. 1396Otherwise it sets the specified columns to use the named tag, replacing any 1397tag that may have been set using this method before. If <tagName> is 1398'', the cols are reset to the default I<tag>. Tags added during 1399-coltagcommand evaluation do not register here. If I<tagName> does 1400not exist, it will be created with the default options. 1401 1402=item I<$table>-E<gt>B<tagConfigure>(I<tagName>, ?I<option>?, ?I<value>?, ?I<option, value, ...>?) 1403 1404This command is similar 1405to the B<configure> widget command except that it modifies options associated 1406with the tag given by I<tagName> instead of modifying options for the overall 1407table widget. If no I<option> is specified, the command returns a list describing 1408all of the available options for I<tagName> (see B<Tk_ConfigureInfo> for information 1409on the format of this list). If I<option> is specified with no I<value>, then 1410the command returns a list describing the one named option (this list 1411will be identical to the corresponding sublist of the value returned if 1412no I<option> is specified). If one or more I<option-value> pairs are specified, 1413then the command modifies the given option(s) to have the given value(s) 1414in I<tagName>; in this case the command returns an empty string. See TAGS 1415above for details on the options available for tags. 1416 1417=item I<$table>-E<gt>B<tagDelete>(I<tagName>) 1418 1419Deletes a tag. No error if the tag does not exist. 1420 1421=item I<$table>-E<gt>B<tagExists>(I<tagName>) 1422 1423Returns 1 if the named tag exists, 0 otherwise. 1424 1425=item I<$table>-E<gt>B<tagIncludes>(I<tagName, index>) 1426 1427Returns 1 if the specified index has the 1428named tag, 0 otherwise. 1429 1430=item I<$table>-E<gt>B<tagLower>(I<tagName, ?belowThis?>) 1431 1432Lower the priority of the named tag. If I<belowThis> is not specified, 1433then the tag's priority is lowered to the bottom, otherwise it is lowered 1434to one below I<belowThis>. 1435 1436=item I<$table>-E<gt>B<tagNames>(?I<pattern>?) 1437 1438If no pattern is 1439specified, shows the names of all defined tags. Otherwise the I<pattern> 1440is used as a glob pattern to show only tags matching that pattern. 1441Tag names are returned in priority order 1442(highest priority tag first). 1443 1444=item I<$table>-E<gt>B<tagRaise>(I<tagName, ?aboveThis?>) 1445 1446Raise the priority of the named tag. If I<aboveThis> is not specified, 1447then the tag's priority is raised to the top, otherwise it is raised to 1448one above I<aboveThis>. 1449 1450 1451=item I<$table>-E<gt>B<tagRow>(I<tagName, ?row, ...?>) 1452 1453With no arguments, prints out the list of rows that use the I<tag>. 1454Otherwise it sets the specified columns to use the named tag, replacing any 1455tag that may have been set using this method before. If I<tagName> is 1456'', the rows are reset to use the default tag. Tags added during 1457-rowtagcommand evaluation do not register here. If I<tagName> does 1458not exist, it will be created with the default options. 1459 1460=back 1461 1462=over 1 1463 1464=item I<$table>-E<gt>B<validate>(I<index>) 1465 1466Explicitly validates the specified index based on the 1467current B<-validatecommand> and returns 0 or 1 based on whether the cell 1468was validated. 1469 1470 1471=item I<$table>-E<gt>B<window>(option, ?I<arg, arg, ...>?) 1472 1473This command is used to 1474manipulate embedded windows. The exact behavior of the command depends 1475on the I<option> argument that follows the B<window> argument. The following 1476forms of the command are currently supported: 1477 1478=back 1479 1480=over 2 1481 1482=item I<$table>-E<gt>B<windowCget>(I<index, option>) 1483 1484This command returns the current value of the option named I<option> associated with the window given by I<index>. I<Option> may have any of the 1485values accepted by the B<window configure> widget command. 1486 1487=item I<$table>-E<gt>B<windowConfigure>(I<index>, ?I<option>?, ?I<value>?, ?I<option, value, ...>?) 1488 1489This command is 1490similar to the B<configure> widget command except that it modifies options 1491associated with the embedded window given by I<index> instead of modifying 1492options for the overall table widget. If no I<option> is specified, the 1493command returns a list describing all of the available options for I<index 1494> (see B<Tk_ConfigureInfo> for information on the format of this list). If 1495I<option> is specified with no I<value>, then the command returns a list describing 1496the one named option (this list will be identical to the corresponding 1497sublist of the value returned if no I<option> is specified). If one or more 1498I<option-value> pairs are specified, then the command modifies the given 1499option(s) to have the given value(s) in I<index>; in this case the command 1500returns an empty string. See EMBEDDED WINDOWS above for details on the 1501options available for windows. 1502 1503=item I<$table>-E<gt>B<windowDelete>(I<index>, ?I<index, ...>?) 1504 1505Deletes an embedded window from the table. The associated window will 1506also be deleted. 1507 1508=item I<$table>-E<gt>B<windowMove>(I<indexFrom, indexTo>) 1509 1510Moves an embedded 1511window from one cell to another. If a window already exists in the target 1512cell, it will be deleted. 1513 1514=item I<$table>-E<gt>B<windowNames>(?I<pattern>?) 1515 1516If no pattern 1517is specified, shows the cells of all embedded windows. Otherwise the I<pattern> is used as a glob pattern to show only cells matching that pattern. 1518 1519=back 1520 1521=over 1 1522 1523=item I<$table>-E<gt>B<xview>(I<args>) 1524 1525This command is used to query and change the horizontal position 1526of the information in the widget's window. It can take any of the following 1527forms: 1528 1529=item I<$table>-E<gt>B<xview>() 1530 1531Returns a list containing two elements. Each element 1532is a real fraction between 0 and 1; together they describe the horizontal 1533span that is visible in the window. For example, if the first element is 1534.2 and the second element is .6, 20% of the table's text is off-screen to 1535the left, the middle 40% is visible in the window, and 40% of the text 1536is off-screen to the right. These are the same values passed to scrollbars 1537via the B<-xscrollcommand> option. 1538 1539=item I<$table>-E<gt>B<xview>(I<index>) 1540 1541Adjusts the view 1542in the window so that the column given by I<index> is displayed at the left 1543edge of the window. 1544 1545=item I<$table>-E<gt>B<xviewMoveto>(I<fraction>) 1546 1547Adjusts the view in 1548the window so that I<fraction> of the total width of the table text is off-screen 1549to the left. I<fraction> must be a fraction between 0 and 1. 1550 1551=item I<$table>-E<gt>B<xviewScroll>(I<number, what>) 1552 1553This command shifts the view in the window left or 1554right according to I<number> and I<what>. I<Number> must be an integer. I<What> 1555must be either B<units> or B<pages> or an abbreviation of one of these. If 1556I<what> is B<units>, the view adjusts left or right by I<number> cells 1557on the display; if it is B<pages> then 1558the view adjusts by I<number> screenfuls. If I<number> is negative then cells 1559farther to the left become visible; if it is positive then cells 1560farther to the right become visible. 1561 1562=item I<$table>-E<gt>B<yview>(I<?args>?) 1563 1564This command 1565is used to query and change the vertical position of the text in the widget's 1566window. It can take any of the following forms: 1567 1568=back 1569 1570=over 2 1571 1572=item I<$table>-E<gt>B<yview>() 1573 1574Returns 1575a list containing two elements, both of which are real fractions between 15760 and 1. The first element gives the position of the table element at 1577the top of the window, relative to the table as a whole (0.5 means it is 1578halfway through the table, for example). The second element gives the 1579position of the table element just after the last one in the window, relative 1580to the table as a whole. These are the same values passed to scrollbars 1581via the B<-yscrollcommand> option. 1582 1583=item I<$table>-E<gt>B<yview>(I<index>) 1584 1585Adjusts the view 1586in the window so that the row given by I<index> is displayed at the top 1587of the window. 1588 1589=item I<$table>-E<gt>B<yviewMoveto>(I<fraction>) 1590 1591Adjusts the view in the 1592window so that the element given by I<fraction> appears at the top of the 1593window. I<Fraction> is a fraction between 0 and 1; 0 indicates the first 1594element in the table, 0.33 indicates the element one-third the way through 1595the table, and so on. 1596 1597=item I<$table>-E<gt>B<yviewscroll>(I<number, what>) 1598 1599This command 1600adjusts the view in the window up or down according to I<number> and I<what>. I<Number> must be an integer. I<What> must be either B<units> or B<pages>. If 1601I<what> is B<units>, the view adjusts up or down by I<number> cells; if it is 1602B<pages> then the view adjusts by I<number> screenfuls. If I<number> is negative 1603then earlier elements become visible; if it is positive then later elements 1604become visible. 1605 1606=back 1607 1608=back 1609 1610=head1 Default Bindings 1611 1612The initialization creates class bindings 1613that give the following default behaviour: 1614 1615=over 1 1616 1617=item [1] 1618 1619Clicking Button-1 in a cell 1620activates that cell. Clicking into an already active cell moves the insertion 1621cursor to the character nearest the mouse. 1622 1623=item [2] 1624 1625Moving the mouse while Button-1 1626is pressed will stroke out a selection area. Exiting while Button-1 is pressed 1627causing scanning to occur on the table along with selection. 1628 1629=item [3] 1630 1631Moving 1632the mouse while Button-2 is pressed causes scanning to occur without any 1633selection. 1634 1635=item [4] 1636 1637Home moves the table to have the origin in view. 1638 1639=item [5] 1640 1641End 1642moves the table to have the B<end> cell in view. 1643 1644=item [6] 1645 1646Control-Home moves the 1647table to the origin and activates that cell. 1648 1649=item [7] 1650 1651Control-End moves the table 1652to the end and activates that cell. 1653 1654=item [8] 1655 1656Shift-Control-Home extends the selection 1657to the origin. 1658 1659=item [9] 1660 1661Shift-Control-End extends the selection to the end. 1662 1663=item [10] 1664 1665 1666The left, right, up and down arrows move the active cell. 1667 1668=item [11] 1669 1670Shift-<arrow> 1671extends the selection in that direction. 1672 1673=item [12] 1674 1675Control-leftarrow and Control-rightarrow 1676move the insertion cursor within the cell. 1677 1678=item [13] 1679 1680Control-slash selects all 1681the cells. 1682 1683=item [14] 1684 1685Control-backslash clears selection from all the cells. 1686 1687=item [15] 1688 1689 1690Backspace deletes the character before the insertion cursor in the active 1691cell. 1692 1693=item [16] 1694 1695Delete deletes the character after the insertion cursor in the 1696active cell. 1697 1698=item [17] 1699 1700Escape rereads the value of the active cell from the 1701specified data source, discarding any edits that have may been performed 1702on the cell. 1703 1704=item [18] 1705 1706Control-a moves the insertion cursor to the beginning 1707of the active cell. 1708 1709=item [19] 1710 1711Control-e moves the insertion cursor to the end 1712of the active cell. 1713 1714=item [20] 1715 1716Control-minus and Control-equals decrease and increase 1717the width of the column with the active cell in it. 1718 1719=item [21] 1720 1721Moving the mouse 1722while Button-3 (the right button on Windows) is pressed while you are over 1723a border will cause interactive resizing of that row and/or column to 1724occur, based on the value of B<-resizeborders>. Some bindings may have slightly 1725different behavior dependent on the B<-selectionmode> of the widget. If the 1726widget is disabled using the B<-state> option, then its view can still be 1727adjusted and cells can still be selected, but no insertion cursor will 1728be displayed and no cell modifications will take place. The behavior of 1729tables can be changed by defining new bindings for individual widgets 1730or by redefining the class bindings. The default bindings are either compiled 1731in the TableMatrix.pm file 1732 1733=back 1734 1735=head1 Performance Issues 1736 1737The number of rows 1738and columns or a table widget should not significantly affect the speed 1739of redraw. Recalculation and redraw of table parameters and cells is restricted 1740as much as possible. The display cell with the insert cursor is redrawn 1741each time the cursor blinks, which causes a steady stream of graphics 1742traffic. Set the B<-insertofftime> option to 0 avoid this. The use of a B<-command> 1743with the table without a cache can cause significant slow-down, as the 1744command is called once for each request of a cell value. 1745 1746 1747 1748=head1 Examples 1749 1750Set 1751the topleft title area to be one spanning cell. This overestimates both 1752row and column span by one, but the command does all the constraining 1753for us. B<$table span [$table cget -roworigin],[$table cget -colorigin] [$table 1754cget -titlerows],[$table cget -titlecols]> Force a table window refresh 1755(useful for the slight chance that a bug in the table is not causing proper 1756refresh): B<$table configure -padx [$table cget -padx]> 1757 1758 1759=head1 Keywords 1760 1761table, 1762widget, extension 1763