summaryrefslogtreecommitdiff
path: root/Master/tlpkg/tlperl/lib/Tk/TixGrid.pod
diff options
context:
space:
mode:
Diffstat (limited to 'Master/tlpkg/tlperl/lib/Tk/TixGrid.pod')
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/TixGrid.pod539
1 files changed, 539 insertions, 0 deletions
diff --git a/Master/tlpkg/tlperl/lib/Tk/TixGrid.pod b/Master/tlpkg/tlperl/lib/Tk/TixGrid.pod
new file mode 100644
index 00000000000..93484db0076
--- /dev/null
+++ b/Master/tlpkg/tlperl/lib/Tk/TixGrid.pod
@@ -0,0 +1,539 @@
+# Copyright (c) 1996, Expert Interface Technologies
+# See the file "license.terms" for information on usage and
+# redistribution of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+# The file man.macros and some of the macros used by this file are
+# copyrighted: (c) 1990 The Regents of the University of California.
+# (c) 1994-1995 Sun Microsystems, Inc.
+# The license terms of the Tcl/Tk distribution are in the file
+# license.tcl.
+
+## TO CHECK:
+##
+## callback: checked for defined of code ref (compare -edit*cmd)
+##
+## option
+## formatcmd mentions format method but there is no format
+## method documented
+##
+## methods:
+## bdtype: what is it? no description given
+## see: not documented? Not implemented??
+##
+## todo: missing peaces marked by ????
+
+=head1 NAME
+
+Tk::TixGrid - Create and manipulate Tix Grid widgets
+
+=for pm TixGrid/TixGrid.pm
+
+=for category Tix Extensions
+
+=head1 SYNOPSIS
+
+S< >I<$tixgrid> = I<$parent>->B<TixGrid>?(I<options>)?;
+
+=head1 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 L<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 B<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 B<TixGrid> widget.
+
+=head1 STANDARD OPTIONS
+
+B<-background>
+ B<-borderwidth>
+ B<-cursor>
+ B<-font>
+ B<-foreground>
+ B<-height>
+ B<-highlightbackground>
+ B<-highlightcolor>
+ B<-highlightthickness>
+ B<-padx>
+ B<-pady>
+ B<-relief>
+ B<-selectbackground>
+ B<-selectborderwidth>
+ B<-selectforeground>
+ B<-state>
+ B<-takefocus>
+ B<-width>
+ B<-xscrollcommand>
+ B<-yscrollcommand>
+
+See L<Tk::options> for details of the standard options.
+
+=head1 WIDGET-SPECIFIC OPTIONS
+
+=over 4
+
+=item Name: B<browseCmd>
+
+=item Class: B<BrowseCmd>
+
+=item Switch: B<-browsecmd>
+
+If defined, gives a perl/Tk L<callback|Tk::callbacks> 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: I<x> I<y>, where (I<x>,I<y>) is the location of the cell that has
+just been clicked.
+
+=item Name: B<Command>
+
+=item Class: B<Command>
+
+=item Switch: B<-command>
+
+If defined, gives a perl/Tk L<callback|Tk::callbacks> to be executed when the
+user double-clicks a grid cell. When this callback is called, it is passed
+with two additional parameters: I<x> I<y>, where (I<x>,I<y>) is the location of
+the cell that has just been clicked.
+
+=item Name: B<editDoneCmd>
+
+=item Class: B<EditDoneCmd>
+
+=item Switch: B<-editdonecmd>
+
+If defined, gives a perl/Tk L<callback|Tk::callbacks>
+to be executed when the
+user has edited grid cell. When this callback is called, it is
+passed with two additional parameters: I<x> I<y>, where (I<x>,I<y>)
+is the location of the cell that has just been edited.
+
+=item Name: B<editNotifyCmd>
+
+=item Class: B<EditNotifyCmd>
+
+=item Switch: B<-editnotifycmd>
+
+If defined gives a perl/Tk L<callback|Tk::callbacks>
+to be executed when the user tries to edit a grid cell.
+When this callback is called, it is passed with two additional
+parameters: I<x> I<y>, where (I<x>,I<y>,) is the location
+of the cell. This callback should return a boolean value: B<true>
+indicates that the cell is editable and B<false> otherwise.
+
+=item Name: B<FloatingCols>
+
+=item Class: B<floatingCols>
+
+=item Switch: B<-floatingcols>
+
+Defines the number of extra columns beyond the existing grid
+that can be brought into view by scrolling.
+
+=item Name: B<FloatingRows>
+
+=item Class: B<floatingRows>
+
+=item Switch: B<-floatingrows>
+
+Defines the number of extra rows beyond the the existing grid
+that can be brought into view by scrolling.
+
+=item Name: B<formatCmd>
+
+=item Class: B<FormatCmd>
+
+=item Switch: B<-formatcmd>
+
+If defined, gives a perl/Tk L<callback|Tk::callbacks> 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 B<formatGrid> or B<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 B<set> method only as cells come
+into view.
+
+When this callback is called, it is passed with five additional
+parameters: I<type> I<x1> I<y1> I<x2> I<y2>.
+
+I<x1> I<y1> I<x2> I<y2> gives the extent of the region that needs
+formatting.
+
+I<type> gives the logical type of the region in the grid. It may be one of the
+following.
+
+=over 8
+
+=item B<x_margin>
+
+The horizontal margin.
+
+=item B<y_margin>
+
+The vertical margin.
+
+=item B<s_margin>
+
+The area in the top left corner where the horizontal and vertical margins
+are joined.
+
+=item B<main>
+
+The main body i.e. all the cells that do not fall into the above three types.
+
+=back
+
+=item Name: B<leftMargin>
+
+=item Class: B<LeftMargin>
+
+=item Switch: B<-leftmargin>
+
+Gives the width of vertical margin in cells (columns).
+A zero indicates that no vertical margin exists. A positive value I<N>
+indicates that first I<N> columns are "labels" and are always displayed
+and not scrolled.
+
+=item Name: B<itemType>
+
+=item Class: B<ItemType>
+
+=item Switch: B<-itemtype>
+
+Default item type for cells.
+
+=item Name: B<selectMode>
+
+=item Class: B<SelectMode>
+
+=item Switch: B<-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 B<single>, B<browse>, B<multiple>, or B<extended>;
+the default value is B<single>.
+
+=item Name: B<selectUnit>
+
+=item Class: B<SelectUnit>
+
+=item Switch: B<-selectunit>
+
+Specifies the selection unit. Valid values are B<cell>, B<column> or B<row>.
+
+=item Name: B<sizeCmd>
+
+=item Class: B<SizeCmd>
+
+=item Switch: B<-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.
+
+=item Name: B<topMargin>
+
+=item Class: B<TopMargin>
+
+=item Switch: B<-topmargin>
+
+Gives the width of horizontal margin in cells (rows).
+A zero indicates that no horizontal margin exists. A positive value
+I<N> indicates that first I<N> rows are "labels" and are always
+displayed and not scrolled.
+
+=back
+
+=head1 WIDGET METHODS
+
+The B<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:
+
+S< >I<$tixgrid>->B<method>?(I<arg, arg, ...>)?
+
+I<arg>s determine the exact behavior of the method.
+
+This object supports the B<configure> and B<cget> methods
+described in L<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
+L<Tk::Widget|Tk::Widget> class.
+
+The following additional methods are possible for B<TixGrid> widgets:
+
+=over 4
+
+=item I<$tixgrid>->B<anchorGet>(I<x>, I<y>)
+
+=item I<$tixgrid>->B<anchorSet>(I<x>, I<y>)
+
+=item I<$tixgrid>->B<anchorClear>
+
+Manipulates the B<anchor cell> of the B<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.
+
+=item ($bd,$col,$row) = I<$tixgrid>->B<bdtype>(I<x,y> ?,I<xDelta>,I<yDelta>?)
+
+Determines if the the screen (pixel) position I<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.
+
+=item I<$tixgrid>->B<delete>(I<dim>, I<from>?, I<to>?)
+
+=item I<$tixgrid>->B<deleteColumn>(I<from>?, I<to>?)
+
+=item I<$tixgrid>->B<deleteRow>(I<from>?, I<to>?)
+
+I<Dim> may be B<row> or B<column>. If I<to> is not given,
+deletes a single row (or column) at the position I<from>.
+If I<to> is given, deletes the range of rows (or columns)
+from position I<from> through I<to>.
+
+=item I<$tixgrid>->B<dragsite>(I<option>, I<x>, I<y>)
+
+=item I<$tixgrid>->B<dropsite>(I<option>, I<x>, I<y>)
+
+Tcl/Tix has (or was going to have) Drag&Drop support.
+Meaning for perl/Tk is not clear yet.
+
+=item I<$tixgrid>->B<editApply>
+
+If any cell is being edited, de-highlight the cell and
+applies the changes.
+
+=item I<$tixgrid>->B<editSet>(I<x>, I<y>)
+
+Highlights the cell at (I<x>,I<y>) for editing,
+if the B<-editnotify> callback returns true for this cell.
+
+=item I<$tixgrid>->B<entrycget>(I<x>, I<y>, 'I<-option>')
+
+=item I<$tixgrid>->B<entryconfigure>(I<x>, I<y>?, I<-option>??=>I<value>, I<-option>=>I<value>, I<...>?)
+
+Provide a configue interface to cells in the grid.
+The I<-option>s depend on the item type of the cell.
+
+=item I<$tixgrid>->B<formatBorder>(I<x1,y1>, I<x2,y2>, I<options>);
+
+=item I<$tixgrid>->B<formatGrid>(I<x1,y1>, I<x2,y2>, I<options>);
+
+The B<formatBorder> and B<formatBorder> methods can only be called by the
+B<-formatcmd> callback of the tixGrid widget. They draw the background of
+the region described by I<x1,y1>, I<x2,y2> according the the supplied
+I<options>. One call to B<-formatcmd> callback can make multiple
+calls to B<formatBorder> and/or B<formatBorder> for different
+sub-regions.
+
+B<formatBorder> draws the background using Tk relief style,
+B<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:
+
+=over 8
+
+=item -background / -bg
+
+=item -borderwidth / -bd
+
+=item -filled
+
+=item -relief
+
+=item -selectbackground
+
+=item -xoff
+
+=item -xon
+
+=item -yoff
+
+=item -yon
+
+=back
+
+The B<-xon/-xoff and -yon/-yoff> options are obscure. If anyone
+can figure out how to do something interesting given what
+F<pTk/tixGrFmt.c> is doing with them please let Nick know!.
+
+=item I<$tixgrid>->B<geometryinfo>(?I<width>, I<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 I<width> and I<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.
+
+=item I<$tixgrid>->B<index>(I<xcoord>, I<ycoord>)
+
+Retuns I<(x, y)> of entry at position (I<$coordx>, I<$coordy>).
+Either coordinate may be B<'max'> which is largest existing entry
+in that direction, B<'end'> which is one I<beyond> largest existing
+entry, or a number. (This is how you find out how big the grid is.)
+
+=item I<$tixgrid>->B<infoBbox>(I<x>,I<y>)
+
+Return the pixel bounding box of the cell at I<x,y>.
+
+=item I<$tixgrid>->B<infoExists>(I<x>,I<y>)
+
+Returns true if there is an item in the cell at I<x,y>.
+Throws an exception (dies) if I<x,y> is outside the
+grid - this may change (Nick doesn't like it).
+
+=item I<$tixgrid>->B<move>(I<dim>, I<from>, I<to>, I<offset>)
+
+=item I<$tixgrid>->B<moveColumn>(I<from>, I<to>, I<offset>)
+
+=item I<$tixgrid>->B<moveRow>(I<from>, I<to>, I<offset>)
+
+I<Dim> may be B<row> or B<column>. Moves the range of rows
+(or columns) from position I<from> through I<to> by the distance
+indicated by I<offset>. For example,
+I<$tixgrid>->B<moveRow>(B<2>, B<4>, B<1>) moves the rows 2,3,4
+to rows 3,4,5.
+
+=item I<$tixgrid>->B<nearest>(I<x>, I<y>)
+
+Screen pos (pixels) to entry (nx,ny) translation.
+
+=item I<$tixgrid>->B<selectionAdjust>(I<x1>, I<y1> ?,I<x2>, I<y2>?)
+
+=item I<$tixgrid>->B<selectionClear>(I<x1>, I<y1> ?,I<x2>, I<y2>?)
+
+=item I<$tixgrid>->B<selectionIncludes>(I<x1>, I<y1> ?,I<x2>, I<y2>?)
+
+=item I<$tixgrid>->B<selectionSet>(I<x1>, I<y1> ?,I<x2>, I<y2>?)
+
+=item I<$tixgrid>->B<selectionToggle>(I<x1>, I<y1> ?,I<x2>, I<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: I<selectionIncludes>: has no visible effect (as in Tix). Eh???
+
+BUG: I<selectionClear>: only works for 0, 0, max, max (as in Tix). Eh???
+
+When I<x2, y2> are not given they default to I<x1, y1>, respectively.
+
+=item I<$tixgrid>->B<set>(I<x>, I<y>?, B<-itemtype>=>I<type>??, I<-option>=>I<value>, I<...>?)
+
+Creates a new display item at the cell at (I<x>,I<y>). The optional
+B<-itemtype> parameter gives the type of the display item.
+An additional list of I<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.
+
+=item I<$tixgrid>->B<size>(I<dim>, I<index>?, I<-option>??=>I<value>, I<...>?)
+
+=item I<$tixgrid>->B<sizeColumn>(I<index>?, I<-option>??=>I<value>, I<...>?)
+
+=item I<$tixgrid>->B<sizeRow>(I<index>?, I<-option>??=>I<value>, I<...>?)
+
+Queries or sets the size of the row or column given by I<dim> and
+I<index>. I<Dim> may be B<row> or B<column>. I<Index> may be any
+non-negative integer that gives the position of a given row (or column).
+I<Index> can also be the string B<default>; in this case, this method
+queries or sets the default size of all rows (or columns).
+When no I<option-value> pair is given, this method returns
+a list containing the current size setting of the given row (or column).
+When I<option-value> pairs are given, the corresponding options
+of the size setting of the given row are changed. I<-option> may be
+one of the following:
+
+=over 8
+
+=item B<-pad0> => I<pixels>
+
+Specifies the paddings to the left of a column or the top of a row.
+
+=item B<-pad1> => I<pixels>
+
+Specifies the paddings to the right of a column or the bottom of a row.
+
+=item B<-size> => I<val>
+
+Specifies the width of a column or the height of a row.
+I<Val> may be: B<auto> -- the width of the column is set
+the widest cell in the column; a valid Tk screen distance
+unit (see B<Tk_GetPixels>); or a real number following by the
+word B<chars> (e.g. B<3.4chars>) that sets the width of the
+column to the given number of characters.
+
+=back
+
+=item I<$tixgrid>->B<sort>(I<dimension>, I<start>, I<end>, ?I<args ...>?)
+
+?docu here? (not supported on Win* OSs up to now)
+
+=item I<$tixgrid>->B<unset>(I<x>, I<y>)
+
+Clears the cell at (I<x>,I<y>) by removing its display item.
+
+=item I<$tixgrid>->B<xview>
+
+Normal horizontal scrollbar method.
+
+=item I<$tixgrid>->B<yview>
+
+Normal vertical scrollbar method.
+
+=back
+
+=head1 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.
+
+=head1 SEE ALSO
+
+L<Tk::DItem|Tk::DItem>
+L<Tk::callbacks|Tk::callbacks>
+L<Tk::FloatEntry|Tk::FloatEntry>
+
+=head1 BUGS
+
+Tcl/Tix was/is not finished and both C code and bindings of TixGrid
+have some bugs.
+
+=head1 KEYWORDS
+
+tix, tixgrid, table, display item, spreadsheet
+
+=cut
+