This is Info file pm.info, produced by Makeinfo version 1.68 from the
input file bigpm.texi.


File: pm.info,  Node: Tk/Text/SuperText,  Next: Tk/TextANSIColor,  Prev: Tk/Text,  Up: Module List

An improved text widget for perl/tk
***********************************

NAME
====

   Tk::Text::SuperText - An improved text widget for perl/tk

SYNOPSIS
========

   *$super_text* = *$paren*->*SuperText*(?options?);

STANDARD OPTIONS
================

   *-background*	*-highlightbackground*	*-insertontime*	*-selectborderwidth*
*-borderwidth*	*-highlightcolor*	*-insertwidth*	*-selectforeground*
*-cursor*	*-highlightthickness*	*-padx*	*-setgrid*
*-exportselection*	*-insertbackground*	*-pady*	*-takefocus*
*-font*	*-insertborderwidth*	*-relief*	*-xscrollcommand*
*-foreground*	*-insertofftime*	*-selectbackground*	*-yscrollcommand*
*-ansicolor*

   See *Note Tk/options: Tk/options, for details of the standard options.

   *-height*	*-spacing1*	*-spacing2*	*-spacing3*
*-state*	*-tabs*	*-width*	*-wrap*

   See *Note Tk/Text: Tk/Text, for details of theis options.

WIDGET-SPECIFIC OPTIONS
=======================

Name:	*indentMode*
Class:	*IndentMode*
Switch:	*-indentmode*
     Specifies how to indent when a new line is inserted in the text.  The
     possible modes are none for no indent at all or *auto* for positioning
     the insertion cursor right below the first non-white space character
     of the previous line.

Name:	*undoDepth*
Class:	*UndoDepth*
Switch:	*-undodepth*
     Sets the maximum depth for the undo buffer:a number specifies the
     numbers of insert or delete operations that can be stored in the
     buffer before the oldest one is poped out and forgotten;0 stops the
     undo feature,undef sets unlimited depth.

Name:	*redoDepth*
Class:	*RedoDepth*
Switch:	*-redodepth*
     Sets the maximum depth for the redo buffer:a number specifies the
     numbers of undo operations that can be stored in the buffer before
     the oldest one is poped out and forgotten;0 stops the redo
     feature,undef sets unlimited depth.

Name:	*showMatching*
Class:	*ShowMatching*
Switch:	*-showmatching*
     With a value of 1 activates the matching parentheses feature.0
     deactivates it.

Name:	*matchHighlightTime*
Class:	*MatchHighlightTime*
Switch:	*-matchhighlighttime*
     Sets the number of milliseconds the match highlight stays visible;
     with a value of 0 the highlight stays on till next match.

Name:	*matchForeground*
Class:	*MatchForeground*
Switch:	*-matchforeground*
     Set the foreground color for the char hilighted by the
     match-parentheses command.

Name:	*matchBackground*
Class:	*MatchBackground*
Switch:	*-matchbackground*
     Set the background color for the char hilighted by the
     match-parentheses command.

Name:	*matchingCouples*
Class:	*MatchingCouples*
Switch:	*-matchingcouples*
     Sets the chars that are searched for a matching counterpart.  The
     format is a simple string with matching chars coupled in left-right
     order; here's an example: *{}[]()""* .  For double couples ("") the
     match is done only on the forwarding chars.

Name:	*insertMode*
Class:	*InsertMode*
Switch:	*-insertmode*
     Sets the default insert mode: insert or overwrite .

Name:	*ansiColor*
Class:	*AnsiColor*
Switch:	*-ansicolor*
     Enables or disables use of Tk-TextANSIColor module (by Tim Jenness
     <t.jenness@jach.hawaii.edu>).  This option was implemented by Jim
     Turner <turnerjw2@netscape.net> (THANKS for the support!)

DESCRIPTION
===========

   *Tk::Text::SuperText* implements many new features over the standard
*Note Tk/Text: Tk/Text, widget while supporting all it's standard
features.Its used simply as the *Note Tk/Text: Tk/Text, widget.  New
Features:

   * Unlimited undo/redo.

     So you can undo and redo whatever you deleted/inserted whenever you
     want.  To reset the undo and redo buffers call this method:
     *$w*->*resetUndo*;

   * Rectangular selections.

     Rectangular text zones can be selected,copied,deleted,shifted with
     the mouse or with the keyboard.

   * Selection right/left char and tab shift.

     Text selections can be shifted left/right of  one or more chars or a
     tabs.

   * Normal and 'inline' selection paste.

     The 'normal' paste is the normal text paste you know :

    Paste Buffer:
          line x

          line y

    Text Buffer:
          line 1

          line2

    Normal paste at line 1:
          *line x*

          *line y*

          line 1

          line 2

    The 'inline' paste work as this:
    Inline paste at line 1:
          *line x* line 1

          *line y* line 2

   * Parentheses matching.

     To help you inspect nested parentheses,brackets and other
     characters,*SuperText* has both an automatic parenthesis matching
     mode,and a find matching command.  Automatic parenthesis matching is
     activated when you type or when you move the insertion cursor after a
     parenthesis.It momentarily highlightsthe matching character if that
     character is visible in the window.To find a matching character
     anywhere in the file,position the cursor after the it,and call the
     find matching command.

   * Autoindenting.

     When you press the Return or Enter key,spaces and tabs are inserted
     to line up the insert point under the start of the previous line.

   * Control codes insertion.

     You can directly insert a non printable control character in the text.

   * Commands are managed via virtual events.

     Every *SuperText* command is binded to a virtual event,so to call it
     or to bind it to a key sequence use the *Note Tk/event: Tk/event,
     functions.  I used this format for key bind so there's no direct
     key-to-command bind,and this give me more flexibility;however you can
     use normal binds.

     Example:


     *$w*->*eventAdd*(*'Tk::Text::SuperText','<<SelectAll>>','<Control-a>'*);

     To set default events bindigs use this methos: *$w*->*bindDefault*;

   * Default key bindings are redefined (not really a feature :).

     Every virtual event has an associated public method with the same
     name of the event but with the firts char in lower case (eg:
     *<<MouseSelect>>* event has a corresponding
     *$super_text*->*mouseSelect* method).

     Virtual Event/Command		Default Key Binding

     *MouseSetInsert*			*<Button1>* *MouseSelect*			*<B1-Motion>*
     *MouseSelectWord*		*<Double-1>* *MouseSelectLine*		*<Triple-1>*
     *MouseSelectAdd*			*<Shift-1>* *MouseSelectAddWord*		*<Double-Shift-1>*
     *MouseSelectAddLine*		*<Triple-Shift-1>*
     *MouseSelectAutoScan*		*<B1-Leave>*
     *MouseSelectAutoScanStop*	*<B1-Enter>*,*<ButtonRelease-1>*
     *MouseMoveInsert*		*<Alt-1>* *MouseRectSelection*		*<Control-B1-Motion>*
     *MouseMovePageTo*		*<2>* *MouseMovePage*			*<B2-Motion>*
     *MousePasteSelection*		*<ButtonRelease-2>*

     *MoveLeft*				*<Left>* *SelectLeft*			*<Shift-Left>*
     *SelectRectLeft*			*<Shift-Alt-Left>* *MoveLeftWord*			*<Control-Left>*
     *SelectLeftWord*			*<Shift-Control-Left>* *MoveRight*				*<Right>*
     *SelectRight*			*<Shift-Right>* *SelectRectRight*		*<Shift-Alt-Right>*
     *MoveRightWord*			*<Control-Right>*
     *SelectRightWord*		*<Shift-Control-Right>* *MoveUp*				*<Up>*
     *SelectUp*				*<Shift-Up>* *SelectRectUp*			*<Shift-Alt-Up>*
     *MoveUpParagraph*		*<Control-Up>*
     *SelectUpParagraph*		*<Shift-Control-Up>*
     *MoveDown*				*<Down>* *SelectDown*			*<Shift-Down>*
     *SelectRectDown*			*<Shift-Alt-Down>*
     *MoveDownParagraph*		*<Control-Down>*
     *SelectDownParagraph*		*<Shift-Control-Down>*
     *MoveLineStart*			*<Home>* *SelectToLineStart*		*<Shift-Home>*
     *MoveTextStart*			*<Control-Home>*
     *SelectToTextStart*		*<Shift-Control-Home>* *MoveLineEnd*			*<End>*
     *SelectToLineEnd*		*<Shift-End>* *MoveTextEnd*			*<Control-End>*
     *SelectToTextEnd*		*<Shift-Control-End>* *MovePageUp*			*<Prior>*
     *SelectToPageUp*			*<Shift-Prior>* *MovePageLeft*			*<Control-Prior>*
     *MovePageDown*			*<Next>* *SelectToPageDown*		*<Shift-Next>*
     *MovePageRight*			*<Control-Next>*
     *SetSelectionMark*		*<Control-space>*,*<Select>*
     *SelectToMark*			*<Shift-Control-space>*,*<Shift-Select>*

     *SelectAll*				*<Control-a>* *SelectionShiftLeft*		*<Control-comma>*
     *SelectionShiftLeftTab*	*<Control-Alt-comma>*
     *SelectionShiftRight*		*<Control-period>*
     *SelectionShiftRightTab*	*<Control-Alt-period>*

     *Ins*					*<Insert>* Enter				*<Return>*
     *AutoIndentEnter*		*<Control-Return>*
     *NoAutoindentEnter*		*<Shift-Return>* Del					*<Delete>*
     *BackSpace*				*<BackSpace>* *DeleteToWordStart*		*<Shift-BackSpace>*
     *DeleteToWordEnd*		*<Shift-Delete>*
     *DeleteToLineStart*		*<Alt-BackSpace>*
     *DeleteToLineEnd*		*<Alt-Delete>* *DeleteWord*			*<Control-BackSpace>*
     *DeleteLine*			*<Control-Delete>*

     *InsertControlCode*		*<Control-Escape>*

     *FocusNext*				*<Control-Tab>* *FocusPrev*				*<Shift-Control-Tab>*

     *FlashMatchingChar*		*<Control-b>*
     *RemoveMatch*			*<Control-B>* *FindMatchingChar*		*<Control-j>*
     *JumpToMatchingChar*		*<Control-J>*

     Escape				*<Escape>*

     *Tab* 					*<Tab>*

     *LeftTab* 				*<Shift-Tab>*

     Copy 				*<Control-c>*

     *Cut* 					*<Control-x>*

     Paste 				*<Control-v>*

     *InlinePaste* 			*<Control-V>*

     Undo 				*<Control-z>*

     *Redo*					*<Control-Z>*

     *Destroy*				*<Destroy>*

     *MenuSelect*			*<Alt-KeyPress>*

   * Public methods.

     $widget->*mouseSetInsert*

     $widget->*museSelect*

     $widget->*mouseSelectWord*

     $widget->*mouseSelectLine*

     $widget->*mouseSelectAdd*

     $widget->*mouseSelectAddWord*

     $widget->*mouseSelectAddLine*

     $widget->*mouseSelectAutoScan*

     $widget->*mouseSelectAutoScanStop*

     $widget->*mouseMoveInsert*

     $widget->*mouseRectSelection*

     $widget->*mouseMovePageTo*

     $widget->*mouseMovePage*

     $widget->*mousePasteSelection*

     $widget->*moveLeft*

     $widget->*selectLeft*

     $widget->*selectRectLeft*

     $widget->*moveLeftWord*

     $widget->*selectLeftWord*

     $widget->*moveRight*

     $widget->*selectRight*

     $widget->*selectRectRight*

     $widget->*moveRightWord*

     $widget->*selectRightWord*

     $widget->*moveUp*

     $widget->*selectUp*

     $widget->*selectRectUp*

     $widget->*moveUpParagraph*

     $widget->*selectUpParagraph*

     $widget->*moveDown*

     $widget->*selectDown*

     $widget->*selectRectDown*

     $widget->*moveDownParagraph*

     $widget->*selectDownParagraph*

     $widget->*moveLineStart*

     $widget->*selectToLineStart*

     $widget->*moveTextStart*

     $widget->*selectToTextStart*

     $widget->*moveLineEnd*

     $widget->*selectToLineEnd*

     $widget->*moveTextEnd*

     $widget->*selectToTextEnd*

     $widget->*movePageUp*

     $widget->*selectToPageUp*

     $widget->*movePageLeft*

     $widget->*movePageDown*

     $widget->*selectToPageDown*

     $widget->*movePageRight*

     $widget->*setSelectionMark*

     $widget->*selectToMark*

     $widget->*selectAll*

     $widget->*selectionShiftLeft*

     $widget->*selectionShiftLeftTab*

     $widget->*selectionShiftRight*

     $widget->*selectionShiftRightTab*

     $widget->*ins*

     $widget->enter

     $widget->*autoIndentEnter*

     $widget-> *noAutoindentEnter*

     $widget->del

     $widget->*backSpace*

     $widget->*deleteToWordStart*

     $widget->*deleteToWordEnd*

     $widget->*deleteToLineStart*

     $widget->*deleteToLineEnd*

     $widget->*deleteWord*

     $widget->*deleteLine*

     $widget->*insertControlCode*

     $widget->*focusNext*

     $widget->*focusPrev*

     $widget->*flashMatchingChar*

     $widget->*removeMatch*

     $widget->*findMatchingChar*

     $widget->*jumpToMatchingChar*

     $widget->escape

     $widget->*tab*

     $widget->*leftTab*

     $widget->copy

     $widget->cut

     $widget->paste

     $widget->*inlinePaste*

     $widget->undo

     $widget->redo

     $widget->destroy

     $widget->*menuSelect*

AUTHOR
======

   Alessandro Iob <*alexiob@dlevel.com*>.

SEE ALSO
========

   `Tk::Text|Tk::Text' in this node `Tk::ROText|Tk::ROText' in this node
`Tk::TextUndo|Tk::TextUndo' in this node

KEYWORDS
========

   text, widget


File: pm.info,  Node: Tk/TextANSIColor,  Next: Tk/TextUndo,  Prev: Tk/Text/SuperText,  Up: Module List

Tk::Text widget with support for ANSI color escape codes
********************************************************

NAME
====

   Tk::TextANSIColor - Tk::Text widget with support for ANSI color escape
codes

SYNOPSIS
========

     use Tk::TextANSIColor;

     $wid = $mw->TextANSIColor(?options,...?);

     $wid->insert($pos, $string, ?taglist, ?string, ?taglist);

     use Term::ANSIColor;
     $red = color('red');  # Retrieve color codes
     $bold = color('bold');
     $wid->insert('end', "$red red text $bold with bold\n");

DESCRIPTION
===========

   This widget extends the capabilities of the standard Tk::Text widget by
adding support for ANSI color escape codes. When these escape codes are
detected they are replaced by equivalent tags.

   This widget was developed to solve the problem associated with driving
a scrolling status display on a GUI as well as a status display going to
an Xterm without having to know whether an xterm or Tk window is receiving
the status information. Mainly used in conjunction with a tied filehandle:

     $text = $MW->TextANSIColor->pack;
     tie *TEXT, "Tk::TextANSIColor", $text;

     $info = colored("Some information\n", 'red');

     # Print information to all filehandles
     print TEXT $info
     print STDOUT $info

   Currently the Term::ANSIColor module is required in order to decode the
escape codes (and probably to generate them in the first place).

TAGS
====

   This widget uses the following tags internally:

     ANSIbd - bold
     ANSIul - underline
     ANSIfgCOL - foreground color
     ANSIbgCOL - background color

   where COL can be one of black, red, green, yellow, blue, magenta, cyan
or white.

   If required, the tags can be altered after the widget is created by
using the tagConfigure() method. e.g.:

     $widget->tagConfigure('ANSIfgred', -foreground => 'blue');

   in order to make 'red' appear 'blue'.

REQUIREMENTS
============

   This modules requires the Term::ANSIColor module.  The Tk module is
also required.

SEE ALSO
========

   *Note Tk/Text: Tk/Text,, *Note Term/ANSIColor: Term/ANSIColor,

AUTHOR
======

   Tim Jenness (<`t.jenness@jach.hawaii.edu'>)

COPYRIGHT
=========

   Copyright (c) 1999-2000 Tim Jenness. All rights reserved.  This program
is free software; you can redistribute it and/or modify it under the same
terms as Perl itself.


File: pm.info,  Node: Tk/TextUndo,  Next: Tk/TiedListbox,  Prev: Tk/TextANSIColor,  Up: Module List

perl/tk text widget with bindings to undo changes.
**************************************************

NAME
====

   Tk::TextUndo - perl/tk text widget with bindings to undo changes.

SYNOPSIS
========

       *use Tk::TextUndo;*

       *$testundo* = *$parent*->*TextUndo*(?*-option*=>value, ...?);

DESCRIPTION
===========

   This IS-A text widget with an unlimited 'undo' history but without a
re'undo' capability.

Bindings
--------

   The `TextUndo' widget has the same bindings as the `Text|Tk::Text' in
this node widget.  In addition there are the following bindings:

Event <L4> <<Undo>>
     undo the last change.  Pressing <L4> several times undo step by step
     the changes made to the text widget.

Methods
-------

   The `TextUndo' widget has the same methods as Text widget.  Additional
methods for the `TextUndo' widget are:

$text->Load($filename);
     Loads the contents of the $filename into the text widget. Load()
     delete the previous contents of the text widget as well as it's undo
     history of the previous file.

$text->Save(?$otherfilename?)
     Save contents of the text widget to a file. If the $otherfilename is
     not specified, the text widget contents writes the file of $filename
     used in the last Load() call.  If no file was previously Load()'ed an
     error message pops up.  The default filename of the last Load() call
     is not overwriten by $otherfilename.

$text->FileName(?$otherfilename?)
     If passed an argument sets the file name associated with the loaded
     document. Returns the current file name associated with the document.

KEYS
====

   widget, text, undo

SEE ALSO
========

   *Note Tk/Text: Tk/Text,, *Note Tk/ROText: Tk/ROText,


File: pm.info,  Node: Tk/TiedListbox,  Next: Tk/Tiler,  Prev: Tk/TextUndo,  Up: Module List

gang together Listboxes
***********************

NAME
====

   Tk::TiedListbox - gang together Listboxes

     use Tk::TiedListbox

     $l1 = $widget->Listbox(-exportselection => 0,...);
     $l2 = $widget->Listbox(-exportselection => 0,...);
     $l3 = $widget->Listbox(-exportselection => 0,...);
     $l1->tie([$l2,$l3]);

DESCRIPTION
===========

   TiedListbox causes two or more Listboxes to be operated in tandem.  One
application is emulating multi-column listboxes. The scrolling, selection,
or both mechanisms may be tied together. The methods tie and untie are
provided, along with overridden versions of some of the Listbox methods to
provide tandem operation.

   Scrollbars are fully supported. You can use either explicitly created
`Scrollbar|Tk::Scrollbar' in this nodes, the *ScrlListbox* widget, or the
`Scrolled|Tk::Scrolled' in this node super-widget. Tricks to "attach"
multiple tied listboxes to a single scrollbar are unnecessary and will
lead to multiple calls of the listbox methods (a bad thing).

   The configuration options, geometry, and items of the Listboxes are not
altered by tying them. The programmer will have to make sure that the
setup of the Listboxes make sense together. Here are some (unenforced)
guidelines:

   For listboxes with tied selection:

   * set *-exportselection* to 0 for all but possibly one Listbox

   * use identical *-selectmode* for all Listboxes

   * if items are added/deleted, they should be done all at once and at
     the same index, or the selection should be cleared

   * Listboxes should have the same number of items

   For listboxes with tied scrolling:

   * use the same window height and font for all Listboxes

   * Listboxes should have the same number of items

METHODS
=======

*$listbox*->tie?(?option?, [listbox,...])?
     Ties together *$listbox* and the list of Listboxes with the given
     option. Returns *$listbox*.

     If no arguments are given, returns a list containing two items: the
     tie option ("scroll", "selection", or "all") and the list of Listboxes
     to which *$listbox* is tied.

     option can be one of "scroll", "selection", or "all".  If omitted,
     "all" is assumed. "scroll" makes the tied Listboxes scroll together,
     "selection" makes selections occur simultaneously in all tied
     Listboxes, and "all" effects both actions.

     All the Listboxes are untied (if previously tied) before being tied
     to each other; hence a Listbox can only be in one "tie group" at a
     time. "Tiedness" is commutative.

     The tie method can be called with either Listbox or TiedListbox
     objects. All Listbox objects specified are reblessed to TiedListbox
     objects.

     Code such as below can be used to tie ScrlListboxes:

          $slb1=ScrlListbox(...); # or Scrolled('Listbox',...
          $slb2=ScrlListbox(...); # or Scrolled('Listbox',...
          $slb1->tie([$slb2->Subwidget('scrolled')]);

*$listbox*->*untie()*
     This function unties the Listbox from its "tie group". The other items
     in the "tie group" (if more than one) remain tied to each other.

     Returns a list containing two items: the old tie option ("scroll",
     "selection", or "all") and the list of Listboxes to which *$listbox*
     was tied.

OVERRIDDEN METHODS
==================

   You probably don't care about these. They are just details to tie
together the behaviors of the listboxes.

   All overriden methods take identical arguments as the corresponding
Listbox methods (see *Note Tk/Listbox: Tk/Listbox, for a full
description). All overridden methods that take an index interpret that
index in the context of the listbox object provided.

*$listbox*->activate(...)
*$listbox*->selection(...)
     To allow tied selection, these functions are overridden for listboxes
     tied together with the "selection" or "all" option. When an item is
     selected or activated in one listbox, the items with the same index
     (if present) are selected or activated in all tied listboxes.

     The selection('includes',...) submethod returns only information
     about the given *$listbox*.

*$listbox*->scan(...)
*$listbox*->see(...)
*$listbox*->*yview*(...)
     To allow tied scrolling, these functions are overridden for listboxes
     tied together with the "scroll" or "all" option. When one listbox is
     scrolled, all the other tied listboxes are scrolled by the same number
     of items (if possible). An attempt is made to keep items of the same
     index at the top of each tied listbox, while not interfering with the
     normal scrolling operations.

     The *yview* method with no arguments returns only information about
     the given *$listbox*.

     Horizontal scrolling (via *xview*) is not tied.

BUGS
====

   Reblessing the widgets to TiedListbox might be too weird. It will
disable any additional features for widgets in a class derived from
Listbox (none yet that I know of).

   The bindtags for reblessed widgets aren't updated. This is probably
wouldn't be a good thing to do automatically anyway.

AUTHOR
======

   Andrew Allen <ada@fc.hp.com>

   This code may be distributed under the same conditions as Perl.


File: pm.info,  Node: Tk/Tiler,  Next: Tk/TixGrid,  Prev: Tk/TiedListbox,  Up: Module List

Scrollable frame with sub-widgets arranged into rows
****************************************************

NAME
====

   Tk::Tiler - Scrollable frame with sub-widgets arranged into rows

SYNOPSIS
========

     use Tk::Tiler;

     my $tl = $parent->Scrolled('Tiler', -columns => n, -rows => n);

     my $a  = $tl->Xxxxx(...);
     my $b  = $tl->Xxxxx(...);
     my $c  = $tl->Xxxxx(...);

     $tl->Manage($a,$b,$c);

DESCRIPTION
===========

   Tiler is derived form Tk::Frame. It is a geometry managing widget which
accepts widgets to manage. It places the widgets in a grid with as many
widgets as possible in a row. All the "slots" in the grid are the same
size, which is determined by the largest managed widget.

   The grid may be scrolled vertically.


File: pm.info,  Node: Tk/TixGrid,  Next: Tk/TixWidget,  Prev: Tk/Tiler,  Up: Module List

Create and manipulate Tix Grid widgets
**************************************

NAME
====

   Tk::TixGrid - Create and manipulate Tix Grid widgets

SYNOPSIS
========

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

     The port of C code and bindings is done but needs
     debugging.  THERE ARE KNOWN BUGS. Work in progress ...

STANDARD OPTIONS
================

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

   See *Note Tk/options: Tk/options, for details of the standard options.

WIDGET-SPECIFIC OPTIONS
=======================

Name:	*browseCmd*
Class:	*BrowseCmd*
Switch:	*-browsecmd*
     ?docu here?  Not in configure output but used in bindings ??!!

     If defined, gives a perl/Tk `callback|Tk::callbacks' in this node 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*
     ?docu here?  Not in configure output but used in bindings ??!!

Name:	*editDoneCmd*
Class:	*EditDoneCmd*
Switch:	*-editdonecmd*
     If defined, gives a perl/Tk `callback|Tk::callbacks' in this node 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|Tk::callbacks' in this node 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 columns that fixed when the widget is
     horizontally scrolled.  These column(s) can be used as label(s) for
     the column(s).  The floating column(s) can be configured in the
     *-formatcmd* callback with the *formatBorder* method.  The default
     value is 0.

Name:	*FloatingRows*
Class:	*floatingRows*
Switch:	*-floatingrows*
     Defines the number of rows that are fixed when the widget is
     vertically scrolled.  These row(s) can be used as label(s) for the
     row(s).  The floating row(s) can be configured in the *-formatcmd*
     callback with the *formatBorder* method.  The default value is 0.

Name:	*formatCmd*
Class:	*FormatCmd*
Switch:	*-formatcmd*
     If defined, gives a perl/Tk `callback|Tk::callbacks' in this node to
     be executed when the grid cells need to be formatted on the screen.
     Normally, this callback calls the format method (see below).  When
     this callback is called, it is passed with five additional
     parameters: type x1 *y1* x2 *y2*. type gives the logical type of the
     region in the grid. It may be one of the following.

    *x-region*
          the horizontal margin

    *y-region*
          the vertical margin

    *s-region*
          the area where the horizontal and vertical margins are joined

    main
          all the cells that do not fall into the above three types

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

Name:	leftMargin
Class:	LeftMargin
Switch:	*-leftmargin*
     In the number of cells, gives the width of vertical margin.  A zero
     indicates that no vertical should be drawn.

Name:	*itemType*
Class:	*ItemType*
Switch:	*-itemtype*
     ?docu here?

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*
     ?docu here?

Name:	*topMargin*
Class:	TopMargin
Switch:	*-topmargin*
     In the number of cells, gives the height of horizontal margin.  A
     zero indicates that no horizontal should be drawn.

DESCRIPTION
===========

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

   A Grid 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 *Note Tk/DItem: Tk/DItem, for more information about
Tix display items. Individual cells, or groups of cells, can be formatted
with a wide range of attributes, such as its color, relief and border.

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, ...*)?

   *arg*s determine the exact behavior of the method. The following
methods are possible for *TixGrid* widgets:

*$tixgrid*->anchor(action, x, y)
*$tixgrid*->anchorAction(x, y)
     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.  Action can be clear, get or
     set.  If action is clear, x and y args are not accepted.

*$tixgrid*->*bdtype*(x, y ?,*xbdWidth*, *ybdWidth*?)
     ????

*$tixgrid*->cget('*-option*')
     Returns the current value of the configuration option given by
     *-option*. *-option* may have any of the values accepted by the
     *TixGrid* constructor method.

*$tixgrid*->configure(?*-option*??=>value, *-option*=>value, ...?)
     Query or modify the configuration options of the widget.  If no
     *-option* is specified, returns a list describing all of the
     available options for *$tixgrid* (see *Tk_ConfigureInfo* for
     information on the format of this list.) If *-option* is specified
     with no value, then the method returns a list describing the one
     named option (this list will be identical to the corresponding
     sublist of the value returned if no *-option* is specified).  If one
     or more *option-value* pairs are specified, then the method modifies
     the given widget option(s) to have the given value(s); in this case
     the method returns an empty string. *-option* may have any of the
     values accepted by the *TixGrid* constructor method.

*$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)
     ?docu here? not implemented :-(

*$tixgrid*->*dropsite*(option, x, y)
     ?docu here? not implemented :-(

*$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*')
     Returns the current value of the configuration option given by
     *-option* of the cell at (x,y).  *-option* may have any of the values
     accepted by the set method.

*$tixgrid*->*entryconfigure*(x, y?, *-option*??=>value, *-option*=>value, ...?)
     Query or modify the configuration options of the cell at (x,y).  If
     no *-option* is specified, returns a list describing all of the
     available options for the cell (see *Tk_ConfigureInfo* for information
     on the format of this list.)  If *-option* is specified with no
     value, then the method returns a list describing the one named option
     (this list will be identical to the corresponding sublist of the
     value returned if no *-option* is specified.) If one or more
     *option-value* pairs are specified, then the method modifies the
     given widget option(s) to have the given value(s); in this case the
     method returns an empty string.  Option may have any of the values
     accepted by the set method.

*$tixgrid*->format(option, ?args, ...?)

*$tixgrid*->*formatBorder*(*x1,y1*, *x2,y2*, options);

*$tixgrid*->*formatGrid*(*x1,y1*, *x2,y2*, options);
     the format method can only be called by the *-formatcmd* callback of
     the tixGrid widget.

     ?docu complete?

*$tixgrid*->*geometryinfo*(?width, ?height, ...?)
     ?docu here?  Return a list of 4 floats! Currently "{first1 last1}
     {first2,last2}" :-(

*$tixgrid*->index(*$coordx*, *$coordy*)
     ?docu here?

     retuns *(nx, ny)* of entry at position (*$coordx*, *$coordy*).
     (??widget or screen offset??)

*$tixgrid*->info(option, ?args, ...?)
     ?docu here?

*$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)
     ?docu here?  screen pos (pixels) to entry (nx,ny) translation.

*$tixgrid*->selection(option, x1, *y1* ?,x2, *y2*?)

*$tixgrid*->selectionOption(x1, *y1* ?,x2, *y2*?)
     Option one of: *adjust*, clear, *includes*, set, and toggle.

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

     BUG: *selection includes*: has no visible effect (as in Tix). Eh???

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

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

    *$tixgrid*->*selectionAdjust*(x1, *y1* ?,x2, *y2*?)
          ?docu here?

    *$tixgrid*->*selectionClear*(x1, *y1* ?,x2, *y2*?)
          ?docu here?

    *$tixgrid*->*selectionIncludes*(x1, *y1* ?,x2, *y2*?)
          ?docu here?

    *$tixgrid*->*selectionSet*(x1, *y1* ?,x2, *y2*?)
          ?docu here?

    *$tixgrid*->*selectionToggle*(x1, *y1* ?,x2, *y2*?)
          ?docu here?

*$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*
     ?docu here?

*$tixgrid*->*yview*
     ?docu here?

BINDINGS
========

   to be done.

SEE ALSO
========

   `Tk::DItem|Tk::DItem' in this node `Tk::callbacks|Tk::callbacks' in
this node `Tk::FloatEntry|Tk::FloatEntry' in this node

BUGS
====

   C code and bindings of TixGrid have some bugs.

KEYWORDS
========

   tix, tixgrid, table, display item, spreadsheet


File: pm.info,  Node: Tk/TixWidget,  Next: Tk/Toplevel,  Prev: Tk/TixGrid,  Up: Module List

methods for Tix widgets
***********************

NAME
====

   Tk::TixWidget - methods for Tix widgets

SYNOPSIS
========

     use Tk::TixWidget;
     @ISA = qw(Tk::Widget Tk::TixWidget);

DESCRIPTION
===========

   `Tk::TixWidget' provides methods that emulate the those used by Tcl/Tix
widgets.  There are currently only two methods supported: `tixEvent' and
`tixGetimage'.

tixGetimage( name )
===================

   Given name, look for an image file with that base name and return a
Tk::Image.  File extensions are tried in this order: `xpm', gif, `ppm',
`xbm' until a valid iamge is found.  If no image is found, try a builtin
image with that name.

tixEvent( option, ?value? )
===========================

   Return or set the tixEvent variable option.  Currently, the only option
used is "type".

AUTHOR
======

   Chris Dean <`ctdean@cogit.com'>


File: pm.info,  Node: Tk/Toplevel,  Next: Tk/Tree,  Prev: Tk/TixWidget,  Up: Module List

Create and manipulate Toplevel widgets
**************************************

NAME
====

   Tk::Toplevel - Create and manipulate Toplevel widgets

       *$toplevel* = *$parent*->Toplevel(?options?);

STANDARD OPTIONS
================


*-borderwidth*	*-highlightbackground*	*-highlightthickness*	*-takefocus*
*-class*	*-highlightcolor*	*-relief* *-cursor*

   See *Note Tk/options: Tk/options, for details of the standard options.

WIDGET-SPECIFIC OPTIONS
=======================

Name:	background
Class:	Background
Switch:	*-background*
     This option is the same as the standard background option except that
     its value may also be specified as an undefined value.  In this case,
     the widget will display no background or border, and no colors will
     be consumed from its colormap for its background and border.

Name:	colormap
Class:	*Colormap*
Switch:	*-colormap*
     Specifies a colormap to use for the window.  The value may be either
     new, in which case a new colormap is created for the window and its
     children, or the name of another window (which must be on the same
     screen and have the same visual as $widget), in which case the new
     window will use the colormap from the specified window.  If the
     colormap option is not specified, the new window uses the default
     colormap of its screen.  This option may not be changed with the
     configure method.

Name:	container
Class:	Container
Switch:	*-container*
     The value must be a boolean.  If true, it means that this window will
     be used as a container in which some other application will be
     embedded (for example, a Tk toplevel can be embedded using the *-use*
     option).  The window will support the appropriate window manager
     protocols for things like geometry requests.  The window should not
     have any children of its own in this application.  This option may
     not be changed with the configure method.

Name:	height
Class:	*Height*
Switch:	*-height*
     Specifies the desired height for the window in any of the forms
     acceptable to *Tk_GetPixels*.  If this option is less than or equal
     to zero then the window will not request any size at all.

Name:	menu
Class:	Menu
Switch:	*-menu*
     Specifies a menu widget to be used as a menubar. On the Macintosh, the
     menubar will be displayed accross the top of the main monitor. On
     Microsoft Windows and all UNIX platforms, the menu will appear accross
     the toplevel window as part of the window dressing maintained by the
     window manager.

Name:	""
Class:	""
Switch:	*-screen*
     Specifies the screen on which to place the new window.  Any valid
     screen name may be used, even one associated with a different display.
     Defaults to the same screen as its parent.  This option is special in
     that it may not be specified via the option database, and it may not
     be modified with the configure method.

Name:	use
Class:	Use
Switch:	*-use*
     This option is used for embedding. If the value isn't an empty string,
     it must be the the window identifier of a container window, specified
     as a hexadecimal string like the ones returned by the *winfo id*
     command. The toplevel widget will be created as a child of the given
     container instead of the root window for the screen.  If the container
     window is in a Tk application, it must be a frame or toplevel widget
     for which the *-container* option was specified.  This option may not
     be changed with the configure method.

Name:	*visual*
Class:	*Visual*
Switch:	*-visual*
     Specifies visual information for the new window in any of the forms
     accepted by *Tk_GetVisual*.  If this option is not specified, the new
     window will use the default visual for its screen.  The *visual*
     option may not be modified with the configure method.

Name:	width
Class:	Width
Switch:	*-width*
     Specifies the desired width for the window in any of the forms
     acceptable to *Tk_GetPixels*.  If this option is less than or equal
     to zero then the window will not request any size at all.

DESCRIPTION
===========

   The Toplevel method creates a new toplevel widget (given by the $widget
argument).  Additional options, described above, may be specified on the
command line or in the option database to configure aspects of the
toplevel such as its background color and relief.  The toplevel command
returns the path name of the new window.

   A toplevel is similar to a frame except that it is created as a
top-level window:  its X parent is the root window of a screen rather than
the logical parent from its path name.  The primary purpose of a toplevel
is to serve as a container for dialog boxes and other collections of
widgets.  The only visible features of a toplevel are its background color
and an optional 3-D border to make the toplevel appear raised or sunken.

WIDGET METHODS
==============

   The Toplevel method creates a widget object.  This object supports the
configure and cget methods described in *Note Tk/options: 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|Tk::Widget' in this node class, and the `Tk::Wm|Tk::Wm' in
this node class.

BINDINGS
========

   When a new toplevel is created, it has no default event bindings:
toplevels are not intended to be interactive.

SEE ALSO
========

   `Tk::Widget|Tk::Widget' in this node `Tk::Wm|Tk::Wm' in this node

KEYWORDS
========

   toplevel, widget


File: pm.info,  Node: Tk/Tree,  Next: Tk/TreeGraph,  Prev: Tk/Toplevel,  Up: Module List

Create and manipulate Tree widgets
**********************************

NAME
====

   Tk::Tree - Create and manipulate Tree widgets

SYNOPSIS
========

       *use Tk::Tree;*

       $tree = *$parent*->Tree(?options?);

SUPER-CLASS
===========

   The Tree class is derived from the `HList|Tk::HList' in this node class
and inherits all the methods, options and subwidgets of its super-class.
A Tree widget is not scrolled by default.

STANDARD OPTIONS
================

   Tree supports all the standard options of an HList widget.  See *Note
Tk/options: Tk/options, for details on the standard options.

WIDGET-SPECIFIC OPTIONS
=======================

Name:		*browseCmd*
Class:		*BrowseCmd*
Switch:		*-browsecmd*
     Specifies a `callback|Tk::callbacks' in this node to call whenever
     the user browses on an entry (usually by single-clicking on the
     entry). The callback is called with one argument, the pathname of the
     entry.

Name:		*closeCmd*
Class:		*CloseCmd*
Switch:		*-closecmd*
     Specifies a `callback|Tk::callbacks' in this node to call whenever an
     entry needs to be closed (See `"BINDINGS"' in this node below). This
     method is called with one argument, the pathname of the entry. This
     method should perform appropriate actions to close the specified
     entry. If the *-closecmd* option is not specified, the default
     closing action is to hide all child entries of the specified entry.

Name:		command
Class:		Command
Switch:		*-command*
     Specifies a `callback|Tk::callbacks' in this node to call whenever
     the user activates an entry (usually by double-clicking on the
     entry). The callback is called with one argument, the pathname of the
     entry.

Name:		*ignoreInvoke*
Class:		*IgnoreInvoke*
Switch:		*-ignoreinvoke*
     A Boolean value that specifies when a branch should be opened or
     closed. A branch will always be opened or closed when the user presses
     the (+) and (-) indicators. However, when the user invokes a branch
     (by doublc-clicking or pressing <Return>), the branch will be opened
     or closed only if *-ignoreinvoke* is set to false (the default
     setting).

Name:		*openCmd*
Class:		*OpenCmd*
Switch:		*-opencmd*
     Specifies a `callback|Tk::callbacks' in this node to call whenever an
     entry needs to be opened (See `"BINDINGS"' in this node below). This
     method is called with one argument, the pathname of the entry. This
     method should perform appropriate actions to open the specified
     entry. If the *-opencmd* option is not specified, the default opening
     action is to show all the child entries of the specified entry.

DESCRIPTION
===========

   The Tree method creates a new window and makes it into a Tree widget
and return a reference to it.  Additional options, described above, may be
specified on the command line or in the option database to configure
aspects of the Tree widget such as its cursor and relief.

   The Tree widget can be used to display hierarchical data in a tree
form. The user can adjust the view of the tree by opening or closing parts
of the tree.

   To display a static tree structure, you can add the entries into the
Tree widget and hide any entries as desired. Then you can call the
*autosetmode* method. This will set up the Tree widget so that it handles
all the open and close events automatically.  the demonstration program
`Tixish/examples/perl-tix-tree').

   The above method is not applicable if you want to maintain a dynamic
tree structure, i.e, you do not know all the entries in the tree and you
need to add or delete entries subsequently. To do this, you should first
create the entries in the Tree widget. Then, use the setmode method to
indicate the entries that can be opened or closed, and use the *-opencmd*
and *-closecmd* options to handle the opening and closing events. (Please
see the demonstration program `Tixish/examples/perl-tix-dyntree').

   Use either

       *$parent*->*Scrolled*(*'Tree'*, ... );

   or

       *$parent*->*ScrlTree*( ... );

   to create a scrolled Tree. See *Note Tk/Scrolled: Tk/Scrolled, for
details.

WIDGET METHODS
==============

   The Tree method creates a widget object.  This object supports the
configure and cget methods described in *Note Tk/options: 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|Tk::Widget' in this node class.

   The following additional methods are available for Tree widgets:

$tree->*autosetmode*
     This method calls the setmode method for all the entries in this Tree
     widget: if an entry has no child entries, its mode is set to none.
     Otherwise, if the entry has any hidden child entries, its mode is set
     to open; otherwise its mode is set to close.

$tree->close(*entryPath*)
     Close the entry given by *entryPath* if its mode is close.

$tree->*getmode*(*entryPath*)
     Returns the current mode of the entry given by *entryPath*.

$tree->open(*entryPath*)
     Open the entry given by *entryPath* if its mode is open.

$tree->setmode(*entryPath, mode*)
     This method is used to indicate whether the entry given by
     *entryPath* has children entries and whether the children are
     visible. mode must be one of open, close or none. If mode is set to
     open, a (+) indicator is drawn next the the entry. If mode is set to
     close, a (-) indicator is drawn next the the entry. If mode is set to
     none, no indicators will be drawn for this entry. The default mode is
     none. The open mode indicates the entry has hidden children and this
     entry can be opened by the user. The close mode indicates that all
     the children of the entry are now visible and the entry can be closed
     by the user.

BINDINGS
========

   The basic mouse and keyboard bindings of the Tree widget are the same
as the `bindings of the HList|Tk::HList' in this node widget.  In
addition, the entries can be opened or closed under the following
conditions:

[1]
     If the mode of the entry is open, it can be opened by clicking on its
     (+) indicator.

[2]
     If the mode of the entry is close, it can be closed by clicking on
     its (-) indicator.

SEE ALSO
========

   `Tk::HList|Tk::HList' in this node

AUTHOR
======

   Perl/TK version by Chris Dean <ctdean@cogit.com>.  Original Tcl/Tix
version by Ioi Kim Lam.

ACKNOWLEDGEMENTS
================

   Thanks to Achim Bohnet <ach@mpe.mpg.de> for all his help.


File: pm.info,  Node: Tk/TreeGraph,  Next: Tk/UserGuide,  Prev: Tk/Tree,  Up: Module List

Tk widget to draw a tree in a Canvas
************************************

NAME
====

   Tk::TreeGraph - Tk widget to draw a tree in a Canvas

SYNOPSIS
========

     use Tk ;
     use Tk::TreeGraph ;

     use strict ;

     my $mw = MainWindow-> new ;

     my $tg = $mw -> Scrolled('TreeGraph') ->pack(-expand => 1, -fill => 'both');

     $tg -> addLabel (text => 'some tree');

     my $ref = [qw/some really_silly text/];

     $tg -> addNode
      (
       nodeId => '1.0',
       text => $ref
      ) ;

     # EITHER add the arrow and the node
     $tg -> addDirectArrow
      (
       from => '1.0',
       to => '1.1'
      ) ;

     $tg->addNode
      (
       nodeId => '1.1',
       text => ['some','text']
      ) ;

     # OR add a node after another one, in this case the widget
     # will draw the arrow
     $tg->addNode
      (
       after =>'1.0',
       nodeId => '1.1',
       text => ['some','text']
      );

     $tg->arrowBind
      (
       button => '<1>',
       color => 'orange',
       command =>  sub{my %h = @_;
                       warn "clicked 1 arrow $h{from} -> $h{to}\n";}
      );

     $tg->nodeBind
      (
       button => '<2>',
       color => 'red',
       command => sub {my %h = @_;
                       warn "clicked 2 node $h{nodeId}\n";}
      );

     $tg->command( on => 'arrow', label => 'dummy 2',
                     command => sub{warn "arrow menu dummy2\n";});

     $tg->arrowBind(button => '<3>', color => 'green',
                  command => sub{$tg->popupMenu(@_);});

     $tg->command(on => 'node', label => 'dummy 1',
                     command => sub{warn "node menu dummy1\n";});

     $tg->nodeBind(button => '<3>', color => 'green',
                  command => sub{$tg->popupMenu(@_);});

     # adjust scrolled area with some margin
     my @array = $tg->bbox("all") ;
     $tg->configure(-scrollregion => [0, 0, $array[2] + 50, $array[3] + 50 ]);

     MainLoop ; # Tk's

DESCRIPTION
===========

   Tk::TreeGraph is a Canvas specialized to draw trees on a Canvas using
arrows and nodes. A node is simply some text imbedded in a rectangular
shape.

   TreeGraph is able to draw the following items:

   * node: some text in a rectangular shape.

   * direct arrow: an arrow to go from one node to the following one.

   * slanted arrow: an arrow to make a new branch.

   * shortcuts arrow: an arrow to represent a shortcut between 2 nodes from
     different branches.

   TreeGraph also provides :

   * a binding on nodes on button 1 to 'select' them.

   * Methods to bind nodes and arrows on user's call-back.

CAVEATS
=======

   You might say that the tree is a weird tree since it is drawn downward
and assymetric and adding branches leaves a some void between them.

   You'd be right. I'm not a specialist in tree drawing algorithms but the
crude algorithm used here works quite fine with drawing id trees for VCS
system. But as usual, I'm always listening for suggestions or even better,
patches ;-) .

   Note that the tree MUST be drawn from top to bottom and from left to
right. Unless you may get a very confusing drawing of a tree.

About Scrolling
===============

   First versions of TreeGraph used to tinker with a -scrollregion option
each time addNode was called. This was not consistent since the scrollbars
are added by the user when calling TreeGraph (using
Scrolled('TreeGraph')). Hence from now on, it will be the responsability
of the user to set a satisfying -scrollregion.

   The user may write this after all nodes are drawn to set the
scrollregion :

     my @array = $tg->bbox("all") ;
     $tg->configure(-scrollregion => [0, 0, $array[2] + 50, $array[3] + 50 ]);

   Furthermore, since configure will called only once, the resulting code
will be faster.

Widget Options
==============

   * -nodeColor: Color of the node rectangle.

   * -nodeTextColor: Color of the text within the nodes

   * -labelColor

   * -arrowColor

   * -shortcutColor: Color of the shortcut arrow (default 'orange')

   * -shortcutStyle: Style of the shortcut arrow. The arrow can be drawn as
     a 'straight' arrow or a 'spline'. (default 'straight')

   * -nodeTag: boolean. By default the nodeId is added at the beginning of
     the node text.

   * -arrowDeltaY: length of direct arrows (downward). default 40

   * -branchSeparation: minimum width between 2 branches of the tree
     (default 120)

   * -x_start: x coordinate of the root of the tree. (default 100)

   * -y_start: y coordinate of the root of the tree.(default 100)

Drawing Methods added to Canvas
===============================

   You draw the tree node after node with addNode using the 'after'
parameter. Then the object will infer the kind of arrow needed between the
2 nodes. Using the 'after' parameter, you no longer need to call youself
the addSlantedArrow or addDirectArrow methods.

addNode(...)
------------

   * nodeId: string to identify this node.

   * text: text string or array ref. This text will be written inside the
     rectangle

   * after: Either a [x,y] array ref setting the coordinate of the root of
     the tree (this can be used to draw the a first tree in the canvas
     and/or to draw a second tree in the canvas). If after is a nodeId, an
     arrow (direct or slanted) will be drawn from the 'after' node to this
     new node.

   Will add a new node (made of a rectangle with the text inside).

   Note that this method will add the nodeId on top of the passed text
('text' parameter).

modifyNode(...)
---------------

   * nodeId: string to identify the node to modify (mandatory).

   * text: text string or array ref. This text will be overwritten inside
     the rectangle. Note that modifyNode will refuse to change the text if
     the new text has more lines than the older text (because the text
     would not fit in the rectangle).

   * nodeColor: new color of the outline of the rectangle.

   * nodeTextColor: new color of the text of the node.

   * nodeFill: new color filling the rectangle.

   Will modify an existing node. Note that the geometry of the node will
not be changed.

flashNode(...)
--------------

   * nodeId: string to identify the node to modify (mandatory).

   * time: time in ms between each flash (default 500 ms)

   * nodeColor: new color of the outline of the rectangle.

   * nodeTextColor: new color of the text of the node.

   * nodeFill: new color filling the rectangle.

   Will make an existing node flash. Calling a second time this method on
a node will make the flashing stop.

addDirectArrow(...)
-------------------

   You can use this method if you want to change the default aspect of the
direct arrow. In this case do not use the 'after' parameter of the
addNode() method.

   * from: node id where the arrow starts

   * to: node id where the arrow ends

   Add a new straight (i.e. vertical) arrow starting from a node. Note that
the 'from' nodeId must be defined. The 'to' nodeId must NOT be defined.
(Remember that you must draw the tree from top to bottom)

addSlantedArrow(...)
--------------------

   You can use this method if you want to change the default aspect of the
slanted arrow. In this case do not use the 'after' parameter of the
addNode() method.

   Parameters are:

   * from: node id where the arrow starts

   * to: node id where the arrow ends

   Add a new branch connecting node 'id' to node 'id2'.  Note that the
'from' nodeId must be defined. The 'to' nodeId must NOT be defined.
(Remember that you must draw the tree from left to right)

addLabel(...)
-------------

   Put some text on the top of the graph.

   * text: text to be inserted on the top of the graph.

addShortcutInfo(...)
--------------------

   * from: node id where the arrow starts

   * to: node id where the arrow ends

   Declare that a shortcut arrow will be drawn from node 'arrow_start' and
'arrow_end'.

addAllShortcuts()
-----------------

   This method is to be called once all nodes, direct arrow and branch
arrows are drawn and all relevant calls to addShortcutInfo are done.

   It will draw shortcut arrows between the ids declared with the
addShortcutInfo method.

clear()
-------

   Clear the graph.

Management methods
==================

nodeBind(...)
-------------

   * button: button name to bind (e.g. '<1>')

   * color: color of the node when it is clicked on.

   * command: sub ref

   Bind the 'button' on all nodes. When 'button' is clicked, the node text
color will change to 'color' and the callback sub will be called with
these parameters:

     (on => 'node', nodeId => $nodeId)

arrowBind(...)
--------------

   * button: button name to bind (e.g. '<1>')

   * color: color of the node when it is clicked on.

   * command: sub ref

   Bind the 'button' on arrows. When 'button' is clicked, the arrow color
will change to 'color' and the callback sub will be called with these
parameters:

     (
       on   => 'arrow',
       from => nodeId_on_arrow_start,
       to   => nodeId_on_arrow_tip
     )

unselectAllNodes()
------------------

   Unselect all previously selected nodes (see button <1> binding)

getSelectedNodes()
------------------

   Return an array containing nodeIds of all nodes currently selected.

getNodeRectangle(...)
---------------------

   Returns the rectangle reference of the passed nodeId or of the node
selected by the user.

   Parameters are :

   * nodeId: nodeId attached to the rectangle

command(...)
------------

   This will add a new entry on a Popup menu which can be raised on a node
or an arrow.

   Parameters are :

   * on: either 'node' or 'arrow'

   * label: Label of the Popup menu entry

   * command: sub ref runned when the menu is invoked

   The callback will be invoked with these parameters when the command is
set for *nodes* :

     (on => 'node', nodeId => $nodeId)

   The callback will be invoked with these parameters when the command is
set for *arrows* :

     (
       on   => 'arrow',
       from => nodeId_on_arrow_start,
       to   => nodeId_on_arrow_tip
     )

Private methods
===============

   These functions are documented only for people wanting to improve or
inherit this widget.

setArrow(...)
-------------

   * color: color of the arrow when selected.

   Reset any previously selected arrow to default color and set the current
arrow to the color. This function should be used with a bind.

   Returns (from => $endNodeId, to => $tipNodeId) to specify the nodes the
arrow is attached to.

setNode()
---------

   * color: color of the arrow when selected.

   * nodeId: nodeId to select (optional, default to the node under the
     mouse pointer)

   Set node either from passed nodeId or from the mouse pointer.  When a
node is set, only the text is highlighted

   Returns the nodeId of the current node (i.e. the node clicked by the
user if this function was used in a bind)

toggleNode(...)
---------------

   * color: color of the arrow when selected.

   * nodeId: nodeId to select (optional, default to the node under the
     mouse pointer)

   Will toggle the node rectangle between 'color' and default.

AUTHOR
======

   Dominique Dumont, Dominique_Dumont@grenoble.hp.com

   Copyright (c) 1998-2000 Dominique Dumont. All rights reserved.  This
program is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.

SEE ALSO
========

   perl(1), Tk(3), Tk::Canvas(3)