This is Info file pm.info, produced by Makeinfo version 1.68 from the input file bigpm.texi.  File: pm.info, Node: Time/Zone, Next: Time/gmtime, Prev: Time/Warp, Up: Module List miscellaneous timezone manipulations routines ********************************************* NAME ==== Time::Zone - miscellaneous timezone manipulations routines SYNOPSIS ======== use Time::Zone; print tz2zone(); print tz2zone($ENV{'TZ'}); print tz2zone($ENV{'TZ'}, time()); print tz2zone($ENV{'TZ'}, undef, $isdst); $offset = tz_local_offset(); $offset = tz_offset($TZ); DESCRIPTION =========== This is a collection of miscellaneous timezone manipulation routines. `tz2zone()' parses the TZ environment variable and returns a timezone string suitable for inclusion in `date' in this node-like output. It opionally takes a timezone string, a time, and a is-dst flag. `tz_local_offset()' determins the offset from GMT time in seconds. It only does the calculation once. `tz_offset()' determines the offset from GMT in seconds of a specified timezone. `tz_name()' determines the name of the timezone based on its offset AUTHORS ======= Graham Barr David Muir Sharnoff Paul Foley  File: pm.info, Node: Time/gmtime, Next: Time/localtime, Prev: Time/Zone, Up: Module List by-name interface to Perl's built-in gmtime() function ****************************************************** NAME ==== Time::gmtime - by-name interface to Perl's built-in gmtime() function SYNOPSIS ======== use Time::gmtime; $gm = gmtime(); printf "The day in Greenwich is %s\n", (qw(Sun Mon Tue Wed Thu Fri Sat Sun))[ gm->wday() ]; use Time::gmtime w(:FIELDS; printf "The day in Greenwich is %s\n", (qw(Sun Mon Tue Wed Thu Fri Sat Sun))[ gm_wday() ]; $now = gmctime(); use Time::gmtime; use File::stat; $date_string = gmctime(stat($file)->mtime); DESCRIPTION =========== This module's default exports override the core gmtime() function, replacing it with a version that returns "Time::tm" objects. This object has methods that return the similarly named structure field name from the C's tm structure from `time.h'; namely sec, min, hour, mday, mon, year, wday, yday, and isdst. You may also import all the structure fields directly into your namespace as regular variables using the :FIELDS import tag. (Note that this still overrides your core functions.) Access these fields as variables named with a preceding `tm_' in front their method names. Thus, `$tm_obj->mday()' corresponds to $tm_mday if you import the fields. The gmctime() function provides a way of getting at the scalar sense of the original CORE::gmtime() function. To access this functionality without the core overrides, pass the use an empty import list, and then access function functions with their full qualified names. On the other hand, the built-ins are still available via the `CORE::' pseudo-package. NOTE ==== While this class is currently implemented using the Class::Struct module to build a struct-like class, you shouldn't rely upon this. AUTHOR ====== Tom Christiansen  File: pm.info, Node: Time/localtime, Next: Time/tm, Prev: Time/gmtime, Up: Module List by-name interface to Perl's built-in localtime() function ********************************************************* NAME ==== Time::localtime - by-name interface to Perl's built-in localtime() function SYNOPSIS ======== use Time::localtime; printf "Year is %d\n", localtime->year() + 1900; $now = ctime(); use Time::localtime; use File::stat; $date_string = ctime(stat($file)->mtime); DESCRIPTION =========== This module's default exports override the core localtime() function, replacing it with a version that returns "Time::tm" objects. This object has methods that return the similarly named structure field name from the C's tm structure from `time.h'; namely sec, min, hour, mday, mon, year, wday, yday, and isdst. You may also import all the structure fields directly into your namespace as regular variables using the :FIELDS import tag. (Note that this still overrides your core functions.) Access these fields as variables named with a preceding `tm_' in front their method names. Thus, `$tm_obj->mday()' corresponds to $tm_mday if you import the fields. The ctime() function provides a way of getting at the scalar sense of the original CORE::localtime() function. To access this functionality without the core overrides, pass the use an empty import list, and then access function functions with their full qualified names. On the other hand, the built-ins are still available via the `CORE::' pseudo-package. NOTE ==== While this class is currently implemented using the Class::Struct module to build a struct-like class, you shouldn't rely upon this. AUTHOR ====== Tom Christiansen  File: pm.info, Node: Time/tm, Next: Tk, Prev: Time/localtime, Up: Module List internal object used by Time::gmtime and Time::localtime ******************************************************** NAME ==== Time::tm - internal object used by Time::gmtime and Time::localtime SYNOPSIS ======== Don't use this module directly. DESCRIPTION =========== This module is used internally as a base class by Time::localtime And Time::gmtime functions. It creates a Time::tm struct object which is addressable just like's C's tm structure from `time.h'; namely with sec, min, hour, mday, mon, year, wday, yday, and isdst. This class is an internal interface only. AUTHOR ====== Tom Christiansen  File: pm.info, Node: Tk, Next: Tk/Adjuster, Prev: Time/tm, Up: Module List a graphical user interface toolkit for Perl ******************************************* NAME ==== Tk - a graphical user interface toolkit for Perl SYNOPSIS ======== use Tk; $top = new MainWindow; MainLoop; DESCRIPTION =========== The Perl/Tk manual is split up into a number of sections: Introduction ------------ * `Tk::overview|Tk::overview' in this node * `Tk::UserGuide|Tk::UserGuide' in this node Tk Geometry Management ---------------------- * `Tk::Adjuster|Tk::Adjuster' in this node * `Tk::form|Tk::form' in this node * `Tk::grid|Tk::grid' in this node * `Tk::pack|Tk::pack' in this node * `Tk::place|Tk::place' in this node * `Tk::Table|Tk::Table' in this node * `Tk::Tiler|Tk::Tiler' in this node * `Tk::Wm|Tk::Wm' in this node Binding Events and Callbacks ---------------------------- * `Tk::After|Tk::After' in this node * `Tk::bind|Tk::bind' in this node * `Tk::bindtags|Tk::bindtags' in this node * `Tk::callbacks|Tk::callbacks' in this node * `Tk::Error|Tk::Error' in this node * `Tk::event|Tk::event' in this node * `Tk::exit|Tk::exit' in this node * `Tk::fileevent|Tk::fileevent' in this node * `Tk::IO|Tk::IO' in this node Tk Image Classes ---------------- * `Tk::Animation|Tk::Animation' in this node * `Tk::Bitmap|Tk::Bitmap' in this node * `Tk::Compound|Tk::Compound' in this node * `Tk::Image|Tk::Image' in this node * `Tk::Photo|Tk::Photo' in this node * `Tk::Pixmap|Tk::Pixmap' in this node Tix Extensions -------------- * `Tk::Balloon|Tk::Balloon' in this node * `Tk::BrowseEntry|Tk::BrowseEntry' in this node * `Tk::DialogBox|Tk::DialogBox' in this node * `Tk::DirTree|Tk::DirTree' in this node * `Tk::DItem|Tk::DItem' in this node * `Tk::InputO|Tk::InputO' in this node * `Tk::LabFrame|Tk::LabFrame' in this node * `Tk::Mwm|Tk::Mwm' in this node * `Tk::NoteBook|Tk::NoteBook' in this node * `Tk::TixGrid|Tk::TixGrid' in this node * `Tk::tixWm|Tk::tixWm' in this node * `Tk::TList|Tk::TList' in this node * `Tk::Tree|Tk::Tree' in this node Tk Widget Classes ----------------- * `Tk::Button|Tk::Button' in this node * `Tk::Canvas|Tk::Canvas' in this node * `Tk::Checkbutton|Tk::Checkbutton' in this node * `Tk::Entry|Tk::Entry' in this node * `Tk::Frame|Tk::Frame' in this node * `Tk::HList|Tk::HList' in this node * `Tk::Label|Tk::Label' in this node * `Tk::Listbox|Tk::Listbox' in this node * `Tk::Menu|Tk::Menu' in this node * `Tk::Menubutton|Tk::Menubutton' in this node * `Tk::Message|Tk::Message' in this node * `Tk::Optionmenu|Tk::Optionmenu' in this node * `Tk::Radiobutton|Tk::Radiobutton' in this node * `Tk::Scale|Tk::Scale' in this node * `Tk::Scrollbar|Tk::Scrollbar' in this node * `Tk::Text|Tk::Text' in this node * `Tk::Toplevel|Tk::Toplevel' in this node Tk Generic Methods ------------------ * `Tk::Font|Tk::Font' in this node * `Tk::send|Tk::send' in this node * `Tk::tkvars|Tk::tkvars' in this node * `Tk::Widget|Tk::Widget' in this node * `Tk::X11Font|Tk::X11Font' in this node User Interaction ---------------- * `Tk::DropSite|Tk::DropSite' in this node * `Tk::Clipboard|Tk::Clipboard' in this node * `Tk::focus|Tk::focus' in this node * `Tk::grab|Tk::grab' in this node * `Tk::selection|Tk::selection' in this node Creating and Configuring Widgets -------------------------------- * `Tk::CmdLine|Tk::CmdLine' in this node * `Tk::MainWindow|Tk::MainWindow' in this node * `Tk::option|Tk::option' in this node * `Tk::options|Tk::options' in this node * `Tk::palette|Tk::palette' in this node * `Tk::Xrm|Tk::Xrm' in this node Popups and Dialogs ------------------ * `Tk::chooseColor|Tk::chooseColor' in this node * `Tk::ColorEditor|Tk::ColorEditor' in this node * `Tk::Dialog|Tk::Dialog' in this node * `Tk::Dialog|Tk::Dialog' in this node * `Tk::FileSelect|Tk::FileSelect' in this node * `Tk::getOpenFile|Tk::getOpenFile' in this node * `Tk::messageBox|Tk::messageBox' in this node Derived Widgets --------------- * `Tk::composite|Tk::composite' in this node * `Tk::configspec|Tk::configspec' in this node * `Tk::Derived|Tk::Derived' in this node * `Tk::mega|Tk::mega' in this node * `Tk::ROText|Tk::ROText' in this node * `Tk::Scrolled|Tk::Scrolled' in this node * `Tk::TextUndo|Tk::TextUndo' in this node * `Tk::Reindex|Tk::Reindex' in this node * `Tk::Pane|Tk::Pane' in this node * `Tk::ProgressBar|Tk::ProgressBar' in this node C Programming ------------- * Internals * pTk * 3DBorder * BackgdErr * BindTable * CanvPsY * CanvTkwin * CanvTxtInfo * Clipboard * ClrSelect * ConfigWidg * ConfigWind * CoordToWin * CrtErrHdlr * CrtGenHdlr * CrtImgType * CrtItemType * CrtMainWin * CrtPhImgFmt * CrtSelHdlr * CrtWindow * DeleteImg * DoOneEvent * DoWhenIdle * DrawFocHlt * EventHndlr * EventInit * FileHndlr * FindPhoto * FontId * FreeXId * GeomReq * GetAnchor * GetBitmap * GetCapStyl * GetClrmap * GetColor * GetCursor * GetFont * GetFontStr * GetGC * GetImage * GetJoinStl * GetJustify * GetOption * GetPixels * GetPixmap * GetRelief * GetRootCrd * GetScroll * GetSelect * GetUid * GetVisual * GetVRoot * HandleEvent * IdToWindow * ImgChanged * InternAtom * MainLoop * MaintGeom * MainWin * ManageGeom * MapWindow * MeasureChar * MoveToplev * Name * NameOfImg * OwnSelect * ParseArgv * Preserve * QWinEvent * Restack * RestrictEv * SetAppName * SetClass * SetGrid * SetVisual * Sleep * StrictMotif * TextLayout * TimerHndlr * Tk_Init * WindowId Implementation -------------- * `Tk::Eventloop|Tk::Eventloop' in this node * `Tk::Item|Tk::Item' in this node * `Tk::Submethods|Tk::Submethods' in this node * `Tk::WidgetDemo|Tk::WidgetDemo' in this node * `Tk::widgets|Tk::widgets' in this node Experimental Modules -------------------- * `Tk::Common|Tk::Common' in this node * `Tk::SunConst|Tk::SunConst' in this node * `Tk::WinPhoto|Tk::WinPhoto' in this node Other Modules and Languages --------------------------- * `Tk::Compile|Tk::Compile' in this node * `Tk::Tcl-perl|Tk::Tcl-perl' in this node * `Tk::X|Tk::X' in this node AUTHOR ====== Nick Ing-Simmons SEE ALSO ======== `perl(1)|perl' in this node, `wish(1)|wish' in this node.  File: pm.info, Node: Tk/Adjuster, Next: Tk/After, Prev: Tk, Up: Module List Allow size of packed widgets to be adjusted by user *************************************************** NAME ==== Tk::Adjuster - Allow size of packed widgets to be adjusted by user SYNOPSIS ======== use Tk::Adjuster; *$adjuster* = $widget->*Adjuster**(?options?)*; WIDGET-SPECIFIC OPTIONS ======================= Name: restore Class: Restore Switch: *-restore* Specifies a boolean value that determines whether the Adjuster should forcibly attempt to make room for itself (by reducing the size of its managed widget) when it is unmapped (for example, due to a size change in a top level window). The default value is 1. Name: *side* Class: Side Switch: *-side* Specifies the side on which the managed widget lies relative to the Adjuster. In conjunction with the pack geometry manager, this relates to the side of the master against which the managed widget and the Adjuster are packed. Must be left, right, top, or *bottom*. Defaults to top. Name: widget Class: *Widget* Switch: *-widget* Specifies the widget which is to be managed by the Adjuster. DESCRIPTION =========== *Tk::Adjuster* is a Frame containing a "line" and a "blob". Dragging with Mouse Button-1 results in a line being dragged to indicate new size. Releasing Button-1 submits GeometryRequests on behalf of the managed widget which will cause the packer to change the widget's size. If Drag is done with Shift button down, then GeometryRequests are made in "real time" so that text-flow effects can be seen, but as a lot more work is done behaviour may be sluggish. If widget is packed with -side => left or -side => right then width is adjusted. If packed -side => top or -side => bottom then height is adjusted. *packPropagate* is turned off for the master window to prevent adjustment changing overall window size. Similarly *packPropagate* is turned off for the managed widget if it has things packed inside it. This is so that the GeometryRequests made by *Tk::Adjuster* are not overridden by pack. In addition, the managed widget is made non-expandable to prevent the geometry manager reallocating freed space in the master back to the managed widget. Note however that expansion is turned off only after the Adjuster is mapped, which allows the managed widget to expand naturally on window creation. The Tk::Widget method, *packAdjust*, calls pack on the widget, then creates an instance of *Tk::Adjuster*, and packs that "after" the widget. Its use has two disadvantages however: the Adjuster widget is not made available to the caller, and options cannot be set on the Adjuster. For these reasons, the Tk::Adjuster method, *packAfter* is preferred, but *packAdjust* is retained for backwards compatibility. WIDGET METHODS ============== *$adjuster*->*packAfter*(*managed_widget, ?pack_options?*) This command configures the Adjuster's *-widget* and *-side* options respectively to *managed_widget* and the *-side* value specified in *pack_options* (top if not specified). It then packs the Adjuster after *managed_widget*, with *-fill* set to x or y as appropriate. *$adjuster*->*packForget**?(boolean)?* This command calls *Tk::Widget::packForget* on the Adjuster. If a parameter is provided and it has a true boolean value, then *packForget* is also called on the managed widget. *$adjuster*->slave This command returns the value *$adjuster*->*cget('-widget')*, ie. the reference to the managed widget. EXAMPLES ======== *Using an Adjuster to separate two widgets, whereby the left widget is managed, and right widget expands to fill space on a window resize* a) Using packAfter (preferred interface) use Tk; use Tk::Adjuster; my $f = MainWindow->new; my $lst1 = $f->Listbox(); my $adj1 = $f->Adjuster(); my $lst2 = $f->Listbox(); my $side = 'left'; $lst1->pack(-side => $side, -fill => 'both', -expand => 1); $adj1->packAfter($lst1, -side => $side); $lst2->pack(-side => $side, -fill => 'both', -expand => 1); MainLoop; b) Using packAdjust use Tk; use Tk::Adjuster; my $f = MainWindow->new; my $lst1 = $f->Listbox(); my $lst2 = $f->Listbox(); my $side = 'left'; $lst1->packAdjust(-side => $side, -fill => 'both'); $lst2->pack (-side => $side, -fill => 'both', -expand => 1); MainLoop; c) Using the standard Tk::Widget::pack use Tk; use Tk::Adjuster; my $f = MainWindow->new; my $side = 'left'; my $lst1 = $f->Listbox(); my $adj = $f->Adjuster(-widget => $lst1, -side => $side); my $lst2 = $f->Listbox(); $lst1->pack(-side => $side, -fill => 'both', -expand => 1); $adj->pack (-side => $side, -fill => 'y'); $lst2->pack(-side => $side, -fill => 'both', -expand => 1); MainLoop; Changing the above examples so that $side has the value 'right' means the left widget expands to fill space on a window resize. Changing the above examples so that $side has the value 'top' produces a testcase with a horizontal Adjuster. Here the bottom widget expands to fill space on a window resize. Packing to the 'bottom' makes the top widget expand to fill space on window resize. *Using -restore => 0 for multiple columns* In the case of multiple columns (or rows) the "restore" functionality of the Adjuster can be inconvenient. When the user adjusts the width of one column and thereby pushes the Adjuster of another column off the window, this adjuster tries to restore itself by reducing the size of its managed widget. This has the effect that column widths shrink; and the original size is not restored when the user reverses the originating change. The *-restore* option can be used to turn off this functionality. (It makes some sense, however, to leave *-restore* turned on for the first-packed Adjuster, so that at least one Adjuster always remains visible.) use Tk; use Tk::Adjuster; my $f = MainWindow->new; my $lst1 = $f->Listbox(); my $adj1 = $f->Adjuster(); my $lst2 = $f->Listbox(); my $adj2 = $f->Adjuster(-restore => 0); my $lst3 = $f->Listbox(); my $side = 'left'; $lst1->pack(-side => $side, -fill => 'both', -expand => 1); $adj1->packAfter($lst1, -side => $side); $lst2->pack(-side => $side, -fill => 'both', -expand => 1); $adj2->packAfter($lst2, -side => $side); $lst3->pack(-side => $side, -fill => 'both', -expand => 1); MainLoop; BUGS ==== It is currently not possible to configure the appearance of the Adjuster. It would be nice to be able to set the width and relief of the Adjuster "line" and the presence/absence of the "blob" on the Adjuster. Tk::Adjuster works theoretically with the grid geometry manager but there are currently some problems which seem to be due to bugs in grid: a) There's never an Unmap event for the adjuster, so the "restore" functionality has no effect. b) After adjusting, widgets protrude into the border of the master. c) grid('Propagate', 0) on MainWindow has no effect - window shrinks/grows when widgets are adjusted. d) Widgets shuffle to correct position on startup  File: pm.info, Node: Tk/After, Next: Tk/Animation, Prev: Tk/Adjuster, Up: Module List Execute a command after a time delay ************************************ NAME ==== Tk::after - Execute a command after a time delay $widget->after(*ms*) $id = $widget->after(*ms*?,callback?) $id = $widget->repeat(*ms*?,callback?) $widget->*afterCancel*($id) $id = $widget->*afterIdle*(callback) $widget->*afterInfo*?($id)? DESCRIPTION =========== This method is used to delay execution of the program or to execute a callback in background sometime in the future. In perl/Tk $widget->after is implemented via the class `Tk::After', and callbacks are associated with $widget, and are automatically cancelled when the widget is destroyed. An almost identical interface, but without automatic cancel, and without repeat is provided via Tk::after method. The internal Tk::After class has the following synopsis: $id = Tk::After->new($widget,$time,'once',callback); $id = Tk::After->new($widget,$time,'repeat',callback); $id->cancel; The after method has several forms as follows: $widget->after(*ms*) The value *ms* must be an integer giving a time in milliseconds. The command sleeps for *ms* milliseconds and then returns. While the command is sleeping the application does not respond to events. $widget->after(*ms*,callback) In this form the command returns immediately, but it arranges for callback be executed *ms* milliseconds later as an event handler. The callback will be executed exactly once, at the given time. The command will be executed in context of $widget. If an error occurs while executing the delayed command then the `Tk::Error|Tk::Error' in this node mechanism is used to report the error. The after command returns an identifier (an object in the perl/Tk case) that can be used to cancel the delayed command using *afterCancel*. $widget->repeat(*ms*,callback) In this form the command returns immediately, but it arranges for callback be executed *ms* milliseconds later as an event handler. After callback has executed it is re-scheduled, to be executed in a futher *ms*, and so on until it is cancelled. $widget->*afterCancel*($id) $id->cancel Cancels the execution of a delayed command that was previously scheduled. $id indicates which command should be canceled; it must have been the return value from a previous after command. If the command given by $id has already been executed (and is not scheduled to be executed again) then *afterCancel* has no effect. $widget->*afterCancel*(callback) *This form is not robust in perl/Tk - its use is deprecated.* This command should also cancel the execution of a delayed command. The callback argument is compared with pending callbacks, if a match is found, that callback is cancelled and will never be executed; if no such callback is currently pending then the *afterCancel* has no effect. $widget->*afterIdle*(callback) Arranges for callback to be evaluated later as an idle callback. The script will be run exactly once, the next time the event loop is entered and there are no events to process. The command returns an identifier that can be used to cancel the delayed command using *afterCancel*. If an error occurs while executing the script then the `Tk::Error|Tk::Error' in this node mechanism is used to report the error. $widget->*afterInfo*?($id)? This command returns information about existing event handlers. If no $id argument is supplied, the command returns a list of the identifiers for all existing event handlers created by the after command for this MainWindow. If $id is supplied, it specifies an existing handler; $id must have been the return value from some previous call to after and it must not have triggered yet or been cancelled. In this case the command returns a list with two elements. The first element of the list is the callback associated with $id, and the second element is either idle or timer to indicate what kind of event handler it is. The after(*ms*) and *afterIdle* forms of the command assume that the application is event driven: the delayed commands will not be executed unless the application enters the event loop. In applications that are not normally event-driven, the event loop can be entered with the *vwait* and update commands. SEE ALSO ======== `Tk::Error|Tk::Error' in this node `Tk::callbacks|Tk::callbacks' in this node KEYWORDS ======== cancel, delay, idle callback, sleep, time  File: pm.info, Node: Tk/Animation, Next: Tk/Axis, Prev: Tk/After, Up: Module List Display sequence of Tk::Photo images ************************************ NAME ==== Tk::Animation - Display sequence of Tk::Photo images SYNOPSIS ======== use Tk::Animation my $img = $widget->Animation('-format' => 'gif', -file => 'somefile.gif'); $img->start_animation($period); $img->stop_animation; $img->add_frames(@images); DESCRIPTION =========== In the simple case when `Animation' is passed a GIF89 style GIF with multiple 'frames', it will build an internal array of Photo images. `start_animation($period)' then initiates a repeat with specified *$period* to sequence through these images. `stop_animation' cancels the repeat and resets the image to the first image in the sequence. The `add_frames' method adds images to the sequence. It is provided to allow animations to be constructed from separate images. All images must be Photos and should all be the same size. BUGS ==== The 'period' should probably be a property of the Animation object rather than specified at 'start' time. It may even be embedded in the GIF.  File: pm.info, Node: Tk/Axis, Next: Tk/BLT/Table, Prev: Tk/Animation, Up: Module List Canvas with Axes **************** NAME ==== Axis - Canvas with Axes SYNOPSIS ======== $mw = MainWindow->new; $t = $mw->Axis(-xmax => 10, -ymax => 10); $t->create('line',$t->plx(2),$t->ply(3.1),$t->plx(4),$t->ply(4)); DESCRIPTION =========== This is an improved version of the axis widget. Changes with respect to the previous version are : * the 'pack' has been moved out the widget. One has to do his own packing * it is now possible to work in the coordinates of the axis. The following piece of code draws a line between the points (2 , 3.1) (4 , 4). AUTHOR ====== Kris Boulez (Kris.Boulez@rug.ac.be) Biomolecular NMR unit University of Ghent, Belgium  File: pm.info, Node: Tk/BLT/Table, Next: Tk/Balloon, Prev: Tk/Axis, Up: Module List geometry manager **************** NAME ==== BLT Table - geometry manager SYNOPSIS ======== use Tk::BLT::Table; $table = $frame->Table(-relief => 'ridge'); $table->configure(-border => 5); $entry = $table->Entry; $table->put(0, 0, $entry); $table->Create(0, 1, 'Button', -text => "Button 1", -command => \&foo); DESCRIPTION =========== The blt_table command is a geometry manager for Tk. It arranges windows tabularly. The table consists of individual rows and columns whose spacing define its layout. Windows, called slaves, are positioned in the table by specifying the row and column. Only one slave can be specified at a single position in the table. But slaves may span multiple rows and columns. By default, blt_table tries to arrange all its slaves in the minimum space required. It determines this by querying each slave window for its requested size. The maximum requested height all slaves spanning a particular row is the row's normal size. Similarly, the maximum requested width of all slaves spanning a particular column is the column's normal size. This, in turn, specifies the table's size, which is the sum of the normal sizes of the rows and columns. The number of rows and columns a table contains is determined by the indices specified. Creating a table ================ Tables are created by invoking the blt_table command. $table = $frame->Table(%options); `$frame' is the pathname of a window which must already exist. Blt_table will arrange its slave windows inside of `$table'. Slave windows are added by designating the slave window's pathname and table position. The following arguments are available for the blt_table (all frame arguments are also available) : -height Specifies a desired window height that the table widget should request from its geometry manager. -width Specifies a desired window width that the table widget should request from its geometry manager. -row the rows of the table specified in argument will have the same heigth than the rows of the table. -col the columns of the table specified in argument will have the same width than the columns of the table. -xscrollincrement -yscrollincrement -xscrollcommand -yscrollcommand Creating a cell =============== The 2 possibilities are : ($cell) = $table->Create($row, $column, 'name_of_Widget', %options); or : $widget = $table->What_you_want; $table->put($row, $column, $widget); Cell configuration ------------------ $table->Cell('configure', [$row, $column], %options); $table->Cell('configure', $widget, %options); Possible options are : -anchor Specifies how the slave window will be arranged if there is extra space in the span surrounding the window. may have any of the forms accepted by Tk_GetAnchor. For example, if is center then the window is centered in the rows and columns it spans; if is w then the window will be drawn such it touches the leftmost edge of the span. This option defaults to center. -columnspan Specifies the number of columns spanned by the slave. The default span is 1. -fill Indicates if the slave should be expanded to occupy any extra space in the span. must be one of the following: none, x, y, both. If is x, the width slave window is expanded. If is y, the height is expanded. The default is none. -ipadx Specifies an extra padding in addition to the width requested by the slave window. can be any value accepted by Tk_GetPixels. The default is 0. -ipady Specifies an extra padding in addition to the height requested by the slave window. can be any value accepted by Tk_GetPixels. The default is 0. -padx Specifies an extra padding to the width of the span occupying the slave window. can be any value accepted by Tk_GetPixels. The default is 0. -pady Specifies an extra padding to the height of the span occupying the slave window. can be any value accepted by Tk_GetPixels. The default is 0. -reqheight Specifies limits for the requested height of the slave window. These limits also constrain the amount of internal padding given to the slave. is a list of bounding values. See the section BOUNDING LIST FORMAT for a description of this list. By default there are no constraints. -reqwidth Specifies the limits of the width which a slave may request. These limits also affect the amount of internal padding given to the slave. is a list of bounding values. See the section BOUNDING LIST FORMAT for a description of this list. By default there are no constraints. -rowspan Specifies the number of rows spanned by the slave window. The default span is 1. Columns and rows configuration ============================== $table->Row('configure', $row, %options); $table->Columns('configure', $columns, %options); Valid options are : -padx Specifies an extra padding to the normal width of the column. can be any value accepted by Tk_GetPixels. The default padding is 0. -resize Indicates that the column can expand or shrink from its normal width when the table is resized. must be one of the following: none, expand, shrink, or both. If is expand the width of the column is expanded if there is extra space in the master window. If is shrink its width may be reduced beyond its normal width if there is not enough space in the master. The default is none. -width Specifies the limits within which the width of the column may expand or shrink. is a list of bounding values. See the section BOUNDING LIST FORMAT for a description of this list. By default there are no constraints. Other commands ============== Row and Column -------------- size : $table->Row('sizes', $row); $table->Column('sizes', $column); Returns the sizes of the given column (row) in the table. forget : $table->Cell('forget', [$row, $column]); $table->Cell('forget', $widget); $table->Row('forget', $row); $table->Column('forget', $column); Requests that cell (row, column) no longer have its geometry managed. The window will be unmapped so that it no longer appears on the screen. If slave is not currently managed by any table, an error message is returned, otherwise the empty string. configure $table->Cell('configure'); $table->Row('configure'); $table->Column('configure'); Table ----- $table->get($row, $column); return the slave in the cell ($row, $column). $table->under($x, $y); return the slave located at $x, $y $table->dimension; return the number of rows and columns of the table. $table->tablex($x); Given a screen x-coordinate $x this command returns the table x-coordinate that is displayed at that location. $table->tabley($y); Given a screen y-coordinate `$y' this command returns the table y-coordinate that is displayed at that location. $table->layout Forces layout of the table geometry manager. This is useful to get the geometry manager to calculate the normal width and height of each row and column. Bounding list format ==================== Constraints for various options (-reqheight, -reqwidth, -height, and -width) are specified by supplying a bounding list of values. Each value must be in a form accepted by Tk_GetPixels. The interpretation of this list is based upon the number of values it contains: [] empty list. No bounding is performed. [ $x ] Set the size of the window or partition at $x. The size of the partition or window cannot grow or shrink. [ $min, $max ] Bound the size of the window or partition between `$min' and `$max'. [ $min, $max, $nom ] Bound the size of the window or partition between `$min' and `$max'. In addition, set the normal size to `$nom'. The maximum bound max can also be specified as `"Inf"' to indicate a unlimited maximum bound. This can be useful when you wish only to set the minimum or nominal size of a window or partition. Example ======= #!/usr/local/bin/perl BEGIN { unshift (@INC,qw(./blib .)) } use Tk; use Tk::BLT::Table; %attribx = (-fill => 'x', -border => 1, -relief => 'sunken'); $top = new MainWindow; $table = Table $top -relief => 'ridge'; configure $table -border => 5; $entry = Entry $table; put $table 0, 0, $entry; Create $table 0, 1, 'Button', -text => "Button 1", -command => \&foo, 0, 2, 'Entry', 1, 2, 'Button', -text => "Button 3", 2, 0, 'Entry', 2, 1, 'Button', -text => "Button 5", 2, 2, 'Entry'; Cell $table 'configure',[1, 2], -anchor => "se"; # $table->Row('forget', 0); # $table->Column('forget', 1); # $table->Column('configure', 1); ($table1) = Create $table 1, 0, 'Table', -anchor => 'nw',-border => 5, -relief => 'raised'; Create $table1 0, 0, 'Button', -text => "But 1", -columnspan => 2, -fill => 'both', 0, 2, 'Button', -text => "But 2", -rspan => 2, -fill => 'both', 1, 0, 'Button', -text => "But 4", -rspan => 2, -fill => 'both', 2, 1, 'Button', -text => "But 3", -cspan => 2, -fill => 'both', 1, 1, 'Button', -text => "But 5", -fill => 'both'; ($table0) = Create $table 1, 1, 'Table', -border => 10, -relief => 'sunken', -fill => 'both'; ($tablet) = Create $table0 0, 1, 'Table',-fill => 'x'; Create $tablet 0, 0, 'Label', -text => '1', %attribx, 0, 1, 'Label', -text => '2', %attribx; ($tables) = Create $table0 2, 1, 'Table',-fill => 'x'; Create $tables 0, 0, 'Label', -text => '4', -fill => 'x', -border => 1, -relief => 'sunken', 0, 1, 'Label', -text => '3', -fill => 'x', -border => 1, -relief => 'sunken'; ($table3, $scrollv1, $scrollv2) = Create $table0 1, 1, 'Table', -height => 200, 1, 0, 'Scrollbar', -orient => 'vertical', -fill => 'y', 1, 2, 'Scrollbar', -orient => 'vertical', -fill => 'y'; configure $scrollv1 -command => ['yview', $table3]; configure $scrollv2 -command => ['yview', $table3]; configure $table3 -yscrollcommand => sub { $scrollv1->set(@_); $scrollv2->set(@_); }, -col => [$tablet, $tables]; Create $table3 0, 0, 'Text', -width => 6, -height => 8, 5, 1, 'Button', -text => "Button 3", -command => sub {$table3->under(50, 50);}, 1, 0, 'Button', -text => "Button 4", 1, 1, 'Entry', 2, 0, 'Entry', 2, 1, 'Button', -text => "Button 5", 3, 0, 'Button', -text => "Button 6", 3, 1, 'Entry', 4, 0, 'Entry', 4, 1, 'Button', -text => "Button 7", 5, 0, 'Button', -text => "Button 8"; ($table4) = Create $table3 0, 1, 'Table', -border => 2, -relief => 'groove'; Create $table4 1, 0, 'Button', -text => "Button 4", 1, 1, 'Entry', 2, 0, 'Entry', 2, 1, 'Button', -text => "Button 5", 3, 0, 'Button', -text => "Button 6", 3, 1, 'Entry', 4, 0, 'Entry'; $table->pack(-fill => 'both', -expand => 1); # print $table->tablex(20)," ",$table->tabley(20),"\n"; MainLoop; sub foo { @dim = $table->dimension; $, = ' '; for($i=0; $i<$dim[0];$i++) { print "$i : ",$table->Row('size', $i)," ", $table->Column('size',$i),"\n"; } }  File: pm.info, Node: Tk/Balloon, Next: Tk/Bitmap, Prev: Tk/BLT/Table, Up: Module List pop up help balloons. ********************* NAME ==== Tk::Balloon - pop up help balloons. SYNOPSIS ======== use Tk::Balloon; ... $b = $top->Balloon(-statusbar => $status_bar_widget); # Normal Balloon: $b->attach($widget, -balloonmsg => "Balloon help message", -statusmsg => "Status bar message"); # Balloon attached to entries in a menu widget: $b->attach($menu, -state => 'status', -msg => ['first menu entry', 'second menu entry', ... ], ); # Balloon attached to individual items in a canvas widget: $b->attach($canvas, -balloonposition => 'mouse', -msg => {'item1' => 'msg1', 'tag2' => 'msg2', ... }, ); DESCRIPTION =========== *Balloon* provides the framework to create and attach help balloons to various widgets so that when the mouse pauses over the widget for more than a specified amount of time, a help balloon is popped up. Balloons and Menus ------------------ If the balloon is attached to a Menu widget and the message arguments are array references, then each element in the array will be the message corresponding to a menu entry. The balloon message will then be shown for the entry which the mouse pauses over. Otherwise it is assumed that the balloon is to be attached to the Menu as a whole. You can have separate status and balloon messages just like normal balloons. Balloons and Canvases --------------------- If the balloon is attached to a Canvas widget and the message arguments are hash references, then each hash key should correspond to a canvas item ID or tag and the associated value will correspond to the message for that canvas item. The balloon message will then be shown for the current item (the one at the position of the mouse). Otherwise it is assumed that the balloon is to be attached to the Canvas as a whole. You can have separate status and balloon messages just like normal balloons. OPTIONS ======= *Balloon* accepts all of the options that the Frame widget accepts. In addition, the following options are also recognized. *-initwait* Specifies the amount of time to wait without activity before popping up a help balloon. Specified in milliseconds. Defaults to 350 milliseconds. This applies to both the popped up balloon and the status bar message. *-state* Can be one of *'balloon'*, *'status'*, *'both'* or *'none'* indicating that the help balloon, status bar help, both or none respectively should be activated when the mouse pauses over the client widget. Default is *'both'*. *-statusbar* Specifies the widget used to display the status message. This widget should accept the *-text* option and is typically a Label. If the widget accepts the *-textvariable* option and that option is defined then it is used instead of the *-text* option. *-balloonposition* Can be one of *'widget'* or *'mouse'*. It controls where the balloon will popup. *'widget'* makes the balloon appear at the lower right corner of the widget it is attached to (default), and *'mouse'* makes the balloon appear below and to the right of the current mouse position. *-postcommand* This option takes a CODE reference which will be executed before the balloon and statusbar messages are displayed and should return a true or false value to indicate whether you want the balloon to be displayed or not. This also lets you control where the balloon is positioned by returning a true value that looks like *X,Y* (matches this regular expression: `/^(\d+),(\d+)$/'). If the postcommand returns a value that matches that re then those coordinates will be used as the position to post the balloon. Warning: this subroutine should return quickly or the balloon response will appear slow. *-cancelcommand* This option takes a CODE reference which will be executed before the balloon and statusbar messages are canceled and should return a true or false value to indicate whether you want the balloon to be canceled or not. Warning: this subroutine should return quickly or the balloon response will appear slow. *-motioncommand* This option takes a CODE reference which will be executed for any motion event and should return a true or false value to indicate whether the currently displayed balloon should be canceled (deactivated). If it returns true then the balloon will definitely be canceled, if it returns false then it may still be canceled depending the internal rules. Note: a new balloon may be posted after the *-initwait* time interval, use the *-postcommand* option to control that behavior. Warning: the subroutine should be extremely fast or the balloon response will appear slow and consume a lot of CPU time (it is executed every time the mouse moves over the widgets the balloon is attached to). METHODS ======= The *Balloon* widget supports only three non-standard methods: *attach(*widget, options) ------------------------- Attaches the widget indicated by widget to the help system. The allowed options are: *-statusmsg* The argument is the message to be shown on the status bar when the mouse pauses over this client. If this is not specified, but *-msg* is specified then the message displayed on the status bar is the same as the argument for *-msg*. If you give it a scalar reference then it is dereferenced before being displayed. Useful if the postcommand is used to change the message. *-balloonmsg* The argument is the message to be displayed in the balloon that will be popped up when the mouse pauses over this client. As with *-statusmsg* if this is not specified, then it takes its value from the *-msg* specification if any. If neither *-balloonmsg* nor *-msg* are specified, or they are the empty string then no balloon is popped up instead of an empty balloon. If you give it a scalar reference then it is dereferenced before being displayed. Useful if the postcommand is used to change the message. *-msg* The catch-all for *-statusmsg* and *-balloonmsg*. This is a convenient way of specifying the same message to be displayed in both the balloon and the status bar for the client. *-initwait* *-state* *-statusbar* *-balloonposition* *-postcommand* *-cancelcommand* *-motioncommand* These options allow you to override the balloon's default value for those option for some of the widgets it is attached to. It accepts the same values as above and will default to the *Balloon*'s value. *detach(*widget) ---------------- Detaches the specified widget from the help system. destroy ------- Destroys the specified balloon. EXAMPLES ======== See the balloon demo included with the widget demo script that came with the distribution for examples on various ways to use balloons. NOTES ===== Because of the overhead associated with each balloon you create (from tracking the mouse movement to know when to activate and deactivate them) you will see the best performance (low CPU consumption) if you create as few balloons as possible and attach them to as many widgets as you can. In other words, don't create a balloon for each widget you want to attach one to. CAVEATS ======= Pressing any button will deactivate (cancel) the current balloon, if one exists. You can usually make the balloon reappear by moving the mouse a little. Creative use of the 3 command options can help you out also. If the mouse is over the balloon when a menu is unposted then the balloon will remain until you move off of it. BUGS ==== Hopefully none, probably some. AUTHORS ======= *Rajappa Iyer* rsi@earthling.net did the original coding. *Jason A. Smith* added support for menus and made some other enhancements. *Slaven Rezic* added support for canvas items. HISTORY ======= The code and documentation was derived from Balloon.tcl from the Tix4.0 distribution by Ioi Lam and modified by the above mentioned authors. This code may be redistributed under the same terms as Perl.  File: pm.info, Node: Tk/Bitmap, Next: Tk/BrowseEntry, Prev: Tk/Balloon, Up: Module List Images that display two colors ****************************** NAME ==== Tk::Bitmap - Images that display two colors *$image* = $widget->Bitmap?(name??,options?) DESCRIPTION =========== A bitmap is an image whose pixels can display either of two colors or be transparent. A bitmap image is defined by four things: a background color, a foreground color, and two bitmaps, called the source and the mask. Each of the bitmaps specifies 0/1 values for a rectangular array of pixels, and the two bitmaps must have the same dimensions. For pixels where the mask is zero, the image displays nothing, producing a transparent effect. For other pixels, the image displays the foreground color if the source data is one and the background color if the source data is zero. CREATING BITMAPS ================ Bitmaps are created using $widget->Bitmap. Bitmaps support the following options: *-background* => color Specifies a background color for the image in any of the standard ways accepted by Tk. If this option is set to an empty string then the background pixels will be transparent. This effect is achieved by using the source bitmap as the mask bitmap, ignoring any *-maskdata* or *-maskfile* options. *-data* => string Specifies the contents of the source bitmap as a string. The string must adhere to X11 bitmap format (e.g., as generated by the bitmap program). If both the *-data* and *-file* options are specified, the *-data* option takes precedence. *-file* => name name gives the name of a file whose contents define the source bitmap. The file must adhere to X11 bitmap format (e.g., as generated by the bitmap program). *-foreground* => color Specifies a foreground color for the image in any of the standard ways accepted by Tk. *-maskdata* => string Specifies the contents of the mask as a string. The string must adhere to X11 bitmap format (e.g., as generated by the bitmap program). If both the *-maskdata* and *-maskfile* options are specified, the *-maskdata* option takes precedence. *-maskfile* => name name gives the name of a file whose contents define the mask. The file must adhere to X11 bitmap format (e.g., as generated by the bitmap program). IMAGE METHODS ============= When a bitmap image is created, Tk also creates a new 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. SEE ALSO ======== `Tk::Image|Tk::Image' in this node `Tk::Pixmap|Tk::Pixmap' in this node `Tk::Photo|Tk::Photo' in this node KEYWORDS ======== bitmap, image  File: pm.info, Node: Tk/BrowseEntry, Next: Tk/Button, Prev: Tk/Bitmap, Up: Module List entry widget with popup choices. ******************************** NAME ==== Tk::BrowseEntry - entry widget with popup choices. SYNOPSIS ======== use Tk::BrowseEntry; $b = $frame->BrowseEntry(-label => "Label", -variable => \$var); $b->insert("end", "opt1"); $b->insert("end", "opt2"); $b->insert("end", "opt3"); ... $b->pack; DESCRIPTION =========== BrowseEntry is a poor man's ComboBox. It may be considered an enhanced version of LabEntry which provides a button to popup the choices of the possible values that the Entry may take. BrowseEntry supports all the options LabEntry supports except *-textvariable*. This is replaced by *-variable*. Other options that BrowseEntry supports. *-listwidth* Specifies the width of the popup listbox. *-variable* Specifies the variable in which the entered value is to be stored. *-browsecmd* Specifies a function to call when a selection is made in the popped up listbox. It is passed the widget and the text of the entry selected. This function is called after the entry variable has been assigned the value. *-listcmd* Specifies the function to call when the button next to the entry is pressed to popup the choices in the listbox. This is called before popping up the listbox, so can be used to populate the entries in the listbox. *-arrowimage* Specifies the image to be used in the arrow button beside the entry widget. The default is an downward arrow image in the file cbxarrow.xbm *-choices* Specifies the list of choices to pop up. This is a reference to an array of strings specifying the choices. *-state* Specifies one of three states for the widget: normal, readonly, or disabled. If the widget is disabled then the value may not be changed and the arrow button won't activate. If the widget is readonly, the entry may not be edited, but it may be changed by choosing a value from the popup listbox. normal is the default. METHODS ======= *insert(*index, string) Inserts the text of string at the specified index. This string then becomes available as one of the choices. delete(*index1*, *index2*) Deletes items from *index1* to *index2*. BUGS ==== BrowseEntry should really provide more of the ComboBox options. AUTHOR ====== *Rajappa Iyer* rsi@earthling.net *Chris Dean* ctdean@cogit.com made additions. This code was inspired by ComboBox.tcl in Tix4.0 by Ioi Lam and bears more than a passing resemblance to ComboBox code. This may be distributed under the same conditions as Perl.