Provided by: perl-tk_804.033-2build1_amd64 bug

NAME

       Tk::TixGrid - Create and manipulate Tix Grid widgets

SYNOPSIS

           $tixgrid = $parent->TixGrid?(options)?;

DESCRIPTION

       This widget is intended as the basis of "spread sheet" like interfaces.  The widget
       displays its contents in a two dimensional "grid" of cells.  Each cell may contain one Tix
       display item, which may be in text, graphics or other formats. See Tk::DItem for more
       information about Tix display items. Because these "items" need not be "windows" large
       grids can be handled  without consuming excessive display system resources.

       Individual cells, or groups of cells, can be formatted with a wide range of attributes,
       such as its color, relief and border. However because the widget is intended to handle
       large grids the mechanisms to achieve these are lower level, and more callback oriented
       than for other widgets. The assumption is that to avoid storing display details of a large
       number of cells, the data will be re-computed as needed.

       The port of Tix C code and some of the bindings to perl/Tk is done but still need further
       work. In several places the intent of the Tix code is not yet understood. For example the
       'edit' interface is clearly intended for spread-sheet like cell content editing in an
       auxillary "entry" widget or similar, but how that should work is not yet clear.

       The TixGrid method creates a new TixGrid window and returns a blessed reference of this
       TixGrid widget.  Additional options, described below, may be specified on the command line
       or in the option database to configure aspects of the TixGrid widget.

STANDARD OPTIONS

       -background      -borderwidth      -cursor      -font      -foreground      -height
            -highlightbackground      -highlightcolor      -highlightthickness      -padx
            -pady      -relief      -selectbackground      -selectborderwidth
            -selectforeground      -state      -takefocus      -width      -xscrollcommand
            -yscrollcommand

       See Tk::options for details of the standard options.

WIDGET-SPECIFIC OPTIONS

       Name:     browseCmd
       Class:    BrowseCmd
       Switch:   -browsecmd
           If defined, gives a perl/Tk callback to be executed when the user browses a grid cell
           (This is normally the case when the user clicks on an entry).  When this callback is
           called, it is passed with two additional parameters: x y, where (x,y) is the location
           of the cell that has just been clicked.

       Name:     Command
       Class:    Command
       Switch:   -command
           If defined, gives a perl/Tk callback to be executed when the user double-clicks a grid
           cell.  When this callback is called, it is passed with two additional parameters: x y,
           where (x,y) is the location of the cell that has just been clicked.

       Name:     editDoneCmd
       Class:    EditDoneCmd
       Switch:   -editdonecmd
           If defined, gives a perl/Tk callback to be executed when the user has edited grid
           cell. When this callback is called, it is passed with two additional parameters: x y,
           where (x,y) is the location of the cell that has just been edited.

       Name:     editNotifyCmd
       Class:    EditNotifyCmd
       Switch:   -editnotifycmd
           If defined gives a perl/Tk callback to be executed when the user tries to edit a grid
           cell.  When this callback is called, it is passed with two additional parameters: x y,
           where (x,y,) is the location of the cell. This callback should return a boolean value:
           true indicates that the cell is editable and false otherwise.

       Name:     FloatingCols
       Class:    floatingCols
       Switch:   -floatingcols
           Defines the number of extra columns beyond the existing grid that can be brought into
           view by scrolling.

       Name:     FloatingRows
       Class:    floatingRows
       Switch:   -floatingrows
           Defines the number of extra rows beyond the the existing grid that can be brought into
           view by scrolling.

       Name:     formatCmd
       Class:    FormatCmd
       Switch:   -formatcmd
           If defined, gives a perl/Tk callback to be executed when the grid cells need to be
           displayed on the screen.  Its primary purpose is to draw the background of the region
           before the cells are rendered on top. This is normally achieved by calling formatGrid
           or formatBorder (see below).  However other uses can  be made of this low-level
           callback. For example it can be used to "lazily" populate the grid by calling the set
           method only as cells come into view.

           When this callback is called, it is passed with five additional parameters: type x1 y1
           x2 y2.

           x1 y1 x2 y2 gives the extent of the region that needs formatting.

           type gives the logical type of the region in the grid. It may be one of the following.

           x_margin
                   The horizontal margin.

           y_margin
                   The vertical margin.

           s_margin
                   The area in the top left corner where the horizontal and vertical margins are
                   joined.

           main    The main body i.e. all the cells that do not fall into the above three types.

       Name:     leftMargin
       Class:    LeftMargin
       Switch:   -leftmargin
           Gives the width of vertical margin in cells (columns).  A zero indicates that no
           vertical margin exists. A positive value N indicates that first N columns are "labels"
           and are always displayed and not scrolled.

       Name:     itemType
       Class:    ItemType
       Switch:   -itemtype
           Default item type for cells.

       Name:     selectMode
       Class:    SelectMode
       Switch:   -selectmode
           Specifies one of several styles for manipulating the selection.  The value of the
           option may be arbitrary, but the default bindings expect it to be either single,
           browse, multiple, or extended; the default value is single.

       Name:     selectUnit
       Class:    SelectUnit
       Switch:   -selectunit
           Specifies the selection unit. Valid values are cell, column or row.

       Name:     sizeCmd
       Class:    SizeCmd
       Switch:   -sizecmd
           Callback is called (with no extra arguments) when grid sizes are re-computed. For
           example if window changes size, a different font is specified etc.

           It is called just after scrollbars (if present) are updated.

       Name:     topMargin
       Class:    TopMargin
       Switch:   -topmargin
           Gives the width of horizontal margin in cells (rows).  A zero indicates that no
           horizontal margin exists. A positive value N indicates that first N rows are "labels"
           and are always displayed and not scrolled.

WIDGET METHODS

       The TixGrid method creates a TixGrid widget and returns a blessed reference of this
       TixGrid widget.  This reference may be used to invoke various operations on the widget.
       It has the following general form:

           $tixgrid->method?(arg, arg, ...)?

       args determine the exact behavior of the method.

       This object supports the configure and cget methods described in Tk::options which can be
       used to enquire and modify the options described above.  The widget also inherits all the
       methods provided by the generic Tk::Widget class.

       The following additional methods are possible for TixGrid widgets:

       $tixgrid->anchorGet(x, y)
       $tixgrid->anchorSet(x, y)
       $tixgrid->anchorClear
           Manipulates the anchor cell of the TixGrid widget.  The anchor cell is the end of the
           selection that is fixed while the user is dragging out a selection with the mouse.

       ($bd,$col,$row) = $tixgrid->bdtype(x,y ?,xDelta,yDelta?)
           Determines if the the screen (pixel) position x,y is in a border.  This is useful for
           changing the mouse cursor when the user points at a border - e.g. to indicate that the
           border can be adjusted interactively.

           If in a border returns a list of three elements. First element is 'xy', 'x' or 'y',
           second two elements are integers.  (Value of these are not understood, seem to
           indicate which column and row of the border the screen position corresponds to?)

           If not in a border returns an empty list.

       $tixgrid->delete(dim, from?, to?)
       $tixgrid->deleteColumn(from?, to?)
       $tixgrid->deleteRow(from?, to?)
           Dim may be row or column. If to is not given, deletes a single row (or column) at the
           position from.  If to is given, deletes the range of rows (or columns) from position
           from through to.

       $tixgrid->dragsite(option, x, y)
       $tixgrid->dropsite(option, x, y)
           Tcl/Tix has (or was going to have) Drag&Drop support.  Meaning for perl/Tk is not
           clear yet.

       $tixgrid->editApply
           If any cell is being edited, de-highlight the cell and applies the changes.

       $tixgrid->editSet(x, y)
           Highlights the cell at (x,y) for editing, if the -editnotify callback returns true for
           this cell.

       $tixgrid->entrycget(x, y, '-option')
       $tixgrid->entryconfigure(x, y?, -option??=>value, -option=>value, ...?)
           Provide a configue interface to cells in the grid.  The -options depend on the item
           type of the cell.

       $tixgrid->formatBorder(x1,y1, x2,y2, options);
       $tixgrid->formatGrid(x1,y1, x2,y2, options);
           The formatBorder and formatBorder methods can only be called by the -formatcmd
           callback of the tixGrid widget. They draw the background of the region described by
           x1,y1, x2,y2 according the the supplied options. One call to -formatcmd callback can
           make multiple calls to formatBorder and/or formatBorder for different sub-regions.

           formatBorder draws the background using Tk relief style, formatGrid also draws grid
           lines between the cells.  It only makes sense to call one or the other for a
           particular sub-region as one will over-write the other.

           The options allowed are:

           -background / -bg
           -borderwidth / -bd
           -filled
           -relief
           -selectbackground
           -xoff
           -xon
           -yoff
           -yon

           The -xon/-xoff and -yon/-yoff options are obscure. If anyone can figure out how to do
           something interesting given what pTk/tixGrFmt.c is doing with them please let Nick
           know!.

       $tixgrid->geometryinfo(?width, height?)
           Returns list of four values - two sets of two floating point numbers.  First set is
           the scrollbar fractions for x direction, second set is scrollbar fractions for y
           direction. If width and height are specified then fractions are based on as if window
           size was of specified size (in pixels, but not allowing normal GetPixels units).
           Otherwise fractions are based on current size of the window.

           Usage obscure.

       $tixgrid->index(xcoord, ycoord)
           Retuns (x, y) of entry at position ($coordx, $coordy).  Either coordinate may be 'max'
           which is largest existing entry in that direction, 'end' which is one beyond largest
           existing entry, or a number. (This is how you find out how big the grid is.)

       $tixgrid->infoBbox(x,y)
           Return the pixel bounding box of the cell at x,y.

       $tixgrid->infoExists(x,y)
           Returns true if there is an item in the cell at x,y.  Throws an exception (dies) if
           x,y is outside the grid - this may change (Nick doesn't like it).

       $tixgrid->move(dim, from, to, offset)
       $tixgrid->moveColumn(from, to, offset)
       $tixgrid->moveRow(from, to, offset)
           Dim may be row or column. Moves the range of rows (or columns) from position from
           through to by the distance indicated by offset. For example, $tixgrid->moveRow(2, 4,
           1) moves the rows 2,3,4 to rows 3,4,5.

       $tixgrid->nearest(x, y)
           Screen pos (pixels) to entry (nx,ny) translation.

       $tixgrid->selectionAdjust(x1, y1 ?,x2, y2?)
       $tixgrid->selectionClear(x1, y1 ?,x2, y2?)
       $tixgrid->selectionIncludes(x1, y1 ?,x2, y2?)
       $tixgrid->selectionSet(x1, y1 ?,x2, y2?)
       $tixgrid->selectionToggle(x1, y1 ?,x2, y2?)
           Selection support methods - probably buggy.

           x1 (y1) has not to be greater than x2 (y2), but only x2 and y2 can be 'max'.

           BUG: selectionIncludes: has no visible effect (as in Tix). Eh???

           BUG: selectionClear: only works for 0, 0, max, max (as in Tix). Eh???

           When x2, y2 are not given they default to x1, y1, respectively.

       $tixgrid->set(x, y?, -itemtype=>type??, -option=>value, ...?)
           Creates a new display item at the cell at (x,y). The optional -itemtype parameter
           gives the type of the display item.  An additional list of option-value pairs specify
           options of the display item. If a display item already exists at this cell, the old
           item will be deleted automatically.

       $tixgrid->size(dim, index?, -option??=>value, ...?)
       $tixgrid->sizeColumn(index?, -option??=>value, ...?)
       $tixgrid->sizeRow(index?, -option??=>value, ...?)
           Queries or sets the size of the row or column given by dim and index. Dim may be row
           or column.  Index may be any non-negative integer that gives the position of a given
           row (or column).  Index can also be the string default; in this case, this method
           queries or sets the default size of all rows (or columns).  When no option-value pair
           is given, this method returns a list containing the current size setting of the given
           row (or column).  When option-value pairs are given, the corresponding options of the
           size setting of the given row are changed. -option may be one of the following:

           -pad0 => pixels
                   Specifies the paddings to the left of a column or the top of a row.

           -pad1 => pixels
                   Specifies the paddings to the right of a column or the bottom of a row.

           -size => val
                   Specifies the width of a column or the height of a row.  Val may be: auto --
                   the width of the column is set the widest cell in the column; a valid Tk
                   screen distance unit (see Tk_GetPixels); or a real number following by the
                   word chars (e.g. 3.4chars) that sets the width of the column to the given
                   number of characters.

       $tixgrid->sort(dimension, start, end, ?args ...?)
           ?docu here? (not supported on Win* OSs up to now)

       $tixgrid->unset(x, y)
           Clears the cell at (x,y) by removing its display item.

       $tixgrid->xview
           Normal horizontal scrollbar method.

       $tixgrid->yview
           Normal vertical scrollbar method.

BINDINGS

       To be done - only most obvious basic bindings work. The Tcl/Tix code was coded as a "state
       machine" which is not easy to follow.

SEE ALSO

       Tk::DItem Tk::callbacks Tk::FloatEntry

BUGS

       Tcl/Tix was/is not finished and both C code and bindings of TixGrid have some bugs.

KEYWORDS

       tix, tixgrid, table, display item, spreadsheet