This is Info file pm.info, produced by Makeinfo version 1.68 from the input file bigpm.texi.  File: pm.info, Node: Tk/HTML/IO, Next: Tk/HistEntry, Prev: Tk/HList, Up: Module List Tk I/O routines for the LWP library *********************************** NAME ==== LWP::TkIO - Tk I/O routines for the LWP library SYNOPSIS ======== use Tk; require LWP::TkIO; require LWP::UserAgent; DESCRIPTION =========== This module provide replacement functions for the LWP::IO functions. Require this module if you use Tk and want non exclusive IO behaviour from LWP. See also *Note LWP/IO: LWP/IO,.  File: pm.info, Node: Tk/HistEntry, Next: Tk/IO, Prev: Tk/HTML/IO, Up: Module List Entry widget with history capability ************************************ NAME ==== Tk::HistEntry - Entry widget with history capability SYNOPSIS ======== use Tk::HistEntry; $hist1 = $top->HistEntry(-textvariable => \$var1); $hist2 = $top->SimpleHistEntry(-textvariable => \$var2); DESCRIPTION =========== `Tk::HistEntry' defines entry widgets with history capabilities. The widgets come in two flavours: `HistEntry' (in package `Tk::HistEntry::Browse') - with associated browse entry `SimpleHistEntry' (in package `Tk::HistEntry::Simple') - plain widget without browse entry The user may browse with the *Up* and *Down* keys through the history list. New history entries may be added either manually by binding the Return key to *historyAdd()* or automatically by setting the *-command* option. OPTIONS ======= *HistEntry* is an descendant of *BrowseEntry* and thus supports all of its standard options. *SimpleHistEntry* is an descendant of Entry and supports all of the Entry options. In addition, the widgets support following specific options: *-textvariable* or *-variable* Variable which is tied to the HistEntry widget. Either *-textvariable* (like in Entry) or *-variable* (like in BrowseEntry) may be used. *-command* Specifies a callback, which is executed when the Return key was pressed or the *invoke* method is called. The callback reveives three arguments: the reference to the HistEntry widget, the current textvariable value and a boolean value, which tells whether the string was added to the history list (e.g. duplicates and empty values are not added to the history list). *-dup* Specifies whether duplicate entries are allowed in the history list. Defaults to true. *-bell* If set to true, rings the bell if the user tries to move off of the history or if a search was not successful. Defaults to true. *-limit* Limits the number of history entries. Defaults to unlimited. *-match* Turns auto-completion on. *-case* If set to true a true value, then be case sensitive on auto-completion. Defaults to 1. METHODS ======= *historyAdd(*[string]) Adds string (or the current textvariable value if not set) manually to the history list. *addhistory* is an alias for *historyAdd*. Returns the added string or undef if no addition was made. *invoke(*[string]) Invokes the command specified with *-command*. *history(*[*arrayref*]) Without argument, returns the current history list. With argument (a reference to an array), replaces the history list. *historySave(*file) Save the history list to the named file. *historyMergeFromFile(*file) Merge the history list from the named file to the end of the current history list of the widget. historyReset Remove all entries from the history list. KEY BINDINGS ============ *Up*, *Control-p* Selects the previous history entry. *Down*, *Control-n* Selects the next history entry. *Meta-<*, *Alt-<* Selects first entry. *Meta->*, *Alt->* Selects last entry. Control-r The current content of the widget is searched backward in the history. Control-s The current content of the widget is searched forward in the history. Return If *-command* is set, adds current content to the history list and executes the associated callback. EXAMPLE ======= This is an simple example for Tk::HistEntry. More examples can be found in the t and examples directories of the source distribution. use Tk; use Tk::HistEntry; $top = new MainWindow; $he = $top->HistEntry(-textvariable => \$foo, -command => sub { # automatically adds $foo to history print STDERR "Do something with $foo\n"; })->pack; $b = $top->Button(-text => 'Do it', -command => sub { $he->invoke })->pack; MainLoop; If you like to not depend on the installation of Tk::HistEntry, you can write something like this: $Entry = "SimpleHistEntry"; eval { # try loading the module, otherwise $Entry is left to the value "Entry" require Tk::HistEntry; $Entry = "SimpleHistEntry"; }; $entry = $status_frame->$Entry(-textvariable => \$res)->pack; $entry->bind("" => sub { # check whether the historyAdd method is # known to the widget if ($entry->can('historyAdd')) { $entry->historyAdd; } }); BUGS/TODO ========= - C-s/C-r do not work as nice as in gnu readline - use -browsecmd from Tk::BrowseEntry - use Tie::Array if present AUTHOR ====== Slaven Rezic CREDITS ======= Thanks for Jason Smith and Benny Khoo for their suggestions. The auto-completion code is stolen from Tk::IntEntry by Dave Collins . COPYRIGHT ========= Copyright (c) 1997, 2000, 2001 Slaven Rezic. All rights reserved. This package is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: Tk/IO, Next: Tk/IconCanvas, Prev: Tk/HistEntry, Up: Module List high level interface to Tk's 'fileevent' mechanism ************************************************** NAME ==== Tk::IO - high level interface to Tk's 'fileevent' mechanism SYNOPSIS ======== my $fh = Tk::IO->new(-linecommand => callback, -childcommand => callback); $fh->exec("command") $fh->wait $fh->kill WARNING ======= INTERFACES TO THIS MODULE MAY CHANGE AS PERL'S IO EVOLVES AND WITH PORT OF TK4.1 DESCRIPTION =========== Tk::IO is now layered on perl's IO::Handle class. Interfaces have changed, and are still evolving. In theory C methods which enable non-blocking IO as in earlier Tk-b* release(s) are still there. I have not changed them to use perl's additional Configure information, or tested them much. Assumption is that exec is used to fork a child process and a callback is called each time a complete line arrives up the implied pipe. "line" should probably be defined in terms of perl's input record separator but is not yet. The -childcommand callback is called when end-of-file occurs. $fh->wait can be used to wait for child process while processing other Tk events. $fh->kill can be used to send signal to child process. BUGS ==== Still not finished. Idea is to use "exec" to emulate "system" in a non-blocking manner.  File: pm.info, Node: Tk/IconCanvas, Next: Tk/Image, Prev: Tk/IO, Up: Module List Canvas with dragable icon management ************************************ NAME ==== Tk::IconCanvas - Canvas with dragable icon management SYNOPSIS ======== use Tk; my $MainWindow = MainWindow->new(); Tk::MainLoop; DESCRIPTION =========== AUTHORS ======= Damion K. Wilson, dkw@rcm.bm HISTORY =cut ===============  File: pm.info, Node: Tk/Image, Next: Tk/InputO, Prev: Tk/IconCanvas, Up: Module List Create and manipulate images **************************** NAME ==== Tk::Image - Create and manipulate images *$image* = $widget->type(?*arg arg ...*?) *$image*->method(?*arg arg ...*?) DESCRIPTION =========== The image constructors and methods are used to create, delete, and query images. It can take several different forms, depending on the type. The constructors require a $widget to invoke them, this is used to locate a *MainWindow*. (This is because the underlying Tk code registers the images in the data structure for the *MainWindow*.) The legal forms are: $widget->type?(?name?,?option=>*value ...*)? Creates a new image and returns an object. type specifies the type of the image, which must be one of the types currently defined (e.g., Bitmap). name specifies the name for the image; if it is omitted then Tk picks a name of the form imagex, where x is an integer. There may be any number of option=>value pairs, which provide configuration options for the new image. The legal set of options is defined separately for each image type; see below for details on the options for built-in image types. If an image already exists by the given name then it is replaced with the new image and any instances of that image will redisplay with the new contents. *$image*->delete Deletes the image *$image* and returns an empty string. If there are instances of the image displayed in widgets, the image won't actually be deleted until all of the instances are released. However, the association between the instances and the image manager will be dropped. Existing instances will retain their sizes but redisplay as empty areas. If a deleted image is recreated (with the same name) the existing instances will use the new image. *$image*->height Returns a decimal string giving the height of image name in pixels. $widget->*imageNames* Returns a list containing all existing images for $widget's *MainWindow*. *$image*->type Returns the type of *$image* (the value of the type method when the image was created). $widget->*imageTypes* Returns a list whose elements are all of the valid image types (i.e., all of the values that may be supplied for the type to create an image). *$image*->width Returns a decimal string giving the width of image name in pixels. BUILT-IN IMAGE TYPES ==================== The following image types are defined by Tk so they will be available in any Tk application. Individual applications or extensions may define additional types. Bitmap Each pixel in the image displays a foreground color, a background color, or nothing. See *Note Tk/Bitmap: Tk/Bitmap, for more information. Pixmap Pixmap is slightly more general than Bitmap, each pixel can be any available color or "transparent" (rendered as background color of the widget image is displayed in). Pixmap is best used for icons and other simple graphics with only a few colors. Pixmap is derived from Tix. See *Note Tk/Pixmap: Tk/Pixmap, for more information. Photo Displays a variety of full-color images, using dithering to approximate colors on displays with limited color capabilities. See *Note Tk/Photo: Tk/Photo, documentation for more information. SEE ALSO ======== `Tk::Bitmap|Tk::Bitmap' in this node `Tk::Pixmap|Tk::Pixmap' in this node `Tk::Photo|Tk::Photo' in this node KEYWORDS ======== height, image, types of images, width  File: pm.info, Node: Tk/InputO, Next: Tk/Internals, Prev: Tk/Image, Up: Module List Create and manipulate TIX InputO widgets **************************************** NAME ==== Tk::InputO - Create and manipulate TIX InputO widgets *$inputonly* = *$parent*->*InputO*(?options?); STANDARD OPTIONS ================ Only the following three standard options are supported by *InputO*: cursor width height See *Note Tk/options: Tk/options, for details of the standard options. WIDGET-SPECIFIC OPTIONS ======================= *InputO* does not have any widget specific options. DESCRIPTION =========== The *InputO* method creates a new window (given by the $widget argument) and makes it into a *InputO* widget. Additional options, described above, may be specified on the command line or in the option database to configure aspects of the *InputO* such as its cursor or width. *InputO* widgets are not visible to the user. The only purpose of *InputO* widgets are to accept inputs from the user, which can be done with the bind method. WIDGET METHODS ============== The *InputO* 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. BINDINGS ======== *InputO* widgets have no default bindings.  File: pm.info, Node: Tk/Internals, Next: Tk/Item, Prev: Tk/InputO, Up: Module List what is Perl Tk interface doing when you call Tk functions. *********************************************************** NAME ==== CallingTk - what is Perl Tk interface doing when you call Tk functions. *This document is under construction. The information is believed to be pertinent to the version of* `portableTk' *available when it was created. All the details are subject to change.* DESCRIPTION =========== PreCompiling Before the actual compilation stage a script scans the source and extracts the subcommands of different commands. This information resides in the file `pTk/Methods.def'. Compilation During compilation the above file is included in the source of booting routine of dynamic (or static) library. More precisely, the booting code of module Tk calls the subroutine Boot_Glue() from the module `tkGlue.c', and this subroutine includes the file (with appropriate macro definitions). Inside `use Tk;' The module bootstraps the C code, then loads the Perl libraries. The heart of the Perl code is contained in the `Tk::Widget' library, all the widgets inherit from this module. Code for toplevels is loaded from `Tk::MainWindow'. During bootstrap of the C glue code the `Xevent::?' codes and a handful of `Tk::Widget' and Tk::Image routines are defined. (Much more XSUBs are created from `Tk.xs' code.) The widget subcommands are glued to Perl basing on the list included from `pTk/Methods.def'. In fact all the subcommands are glued to XSUBs that are related to the same C subroutine XStoWidget(), but have different data parts. During the Perl code bootstrap the method `Tk::Widget::import' is called. This call requires all the code from particular widget packages. Code from the widget packages calls an obscure command like (bless \"Text")->WidgetClass; This command (actually Tk::Widget::WidgetClass()) creates three routines: Tk::Widget::Text(), Tk::Widget::isText(), and Tk::Text::isText(). The first one is basically new of `Tk::Text', the other two return constants. It also puts the class into depository. Inside `$top = MainWindow->new;' This is quite intuitive. This call goes direct to `Tk::MainWindow::new', that calls XSUB `Tk::MainWindow::CreateMainWindow', that calls C subroutine Tk_CreateMainWindow(). It is a Tk subroutine, so here black magic ends (almost). The only remaining black magic is that the Tk initialization routine creates a lot of commands, but the subroutine for creation is usurped by *portableTk* and the commands are created in the package Tk. They are associated to XSUBs that are related to one of three C subroutines XStoSubCmd(), XStoBind(), or XStoTk(), but have different data parts. The result of the call is blessed into `Tk::MainWindow', as it should. Inside `$top->title('Text demo');' The package `Tk::Toplevel' defines a lot of subroutines on the fly on some list. All the commands from the list are converted to the corresponding subcommands of `wm' method of the widget. Here subcommand is a command with some particular second argument (in this case `"title"'). Recall that the first argument is $self. Now `Tk::Toplevel' @ISA `Tk::Widget', that in turn @ISA Tk. So a call to `$top->wm('title','Text demo')' calls `Tk::wm', that is defined during call to Tk_CreateMainWindow(). As it is described above, the XSUB associated to XStoSubCmd() is called. This C routine is defined in `tkGlue.c'. It gets the data part of XSUB, creates a SV with the name of the command, and calls Call_Tk() with the XSUB data as the first argument, and with the name of XSUB stuffed into the Perl stack in the place there tk expects it. (In fact it can also reorder the arguments if it thinks it is what you want). The latter procedure extracts name of tk procedure and `clientData' from the first argument and makes a call, using Perl stack as `argv' for the procedure. A lot of black magic is performed afterwards to convert result of the procedure to a Perl array return. Inside `$text = $top->Text(background => $txtBg);' Above we discussed how the command `Tk::Widget::Text' is created. The above command calls it via inheritance. It is translated to Tk::Text::new($top, background => $txtBg); The package `Tk::Text' has no method new, so the `Tk::Widget::new' is called. In turn it calls `Tk::Text->DoInit($top)', that is `Tk::Widget::DoInit(Tk::Text,$top)', that initializes the bindings if necessary. Then it creates the name for the widget of the form `.text0', and calls `Tk::text('.text0', background => $txtBg)' (note lowercase). The result of the call is blessed into `Tk::Text', and the method `bindtags' for this object is called. Now the only thing to discuss is who defines the methods text and `bindtags'. The answer is that they are defined in `tkWindow.c', and these commands are created in the package Tk in the same sweep that created the command `Tk::wm' discussed above. So the the same C code that corresponds to the processing of corresponding TCL commands is called here as well (this time via `XStoTk' interface). Inside `$text->insert('insert','Hello, world!');' As we discussed above, the subcommands of widget procedures correspond to XSUB `XStoWidget'. This XSUB substitutes the first argument $text (that is a hash reference) to an appropriate value from this hash, adds the additional argument after the first one that contains the name of the subcommand extracted from the data part of XSUB, and calls the corresponding Tk C subroutine via `Call_Tk'. Ilya Zakharevich  File: pm.info, Node: Tk/Item, Next: Tk/JPEG, Prev: Tk/Internals, Up: Module List Base class for Menu items ************************* NAME ==== Tk::Menu::Item - Base class for Menu items SYNOPSIS ======== require Tk::Menu::Item; my $but = $menu->Button(...); $but->configure(...); my $what = $but->cget(); package Whatever; require Tk::Menu::Item; @ISA = qw(Tk::Menu::Item); sub PreInit { my ($class,$menu,$info) = @_; $info->{'-xxxxx'} = ... my $y = delete $info->{'-yyyy'}; } DESCRIPTION =========== Tk::Menu::Item is the base class from which Tk::Menu::Button, Tk::Menu::Cascade, Tk::Menu::Radiobutton and Tk::Menu::Checkbutton are derived. There is also a Tk::Menu::Separator. Constructors are declared so that $menu->Button(...) etc. do what you would expect. The `-label' option is pre-processed allowing ~ to be prefixed to the character to derive a `-underline' value. Thus $menu->Button(-label => 'Goto ~Home',...) is equivalent to $menu->Button(-label => 'Goto Home', -underline => 6, ...) The `Cascade' menu item creates a sub-menu and accepts these options: *-menuitems* A list of items for the sub-menu. Within this list (which is also accepted by Menu and Menubutton) the first two elements of each item should be the "constructor" name and the label: -menuitems => [ [Button => '~Quit', -command => [destroy => $mw]], [Checkbutton => '~Oil', -variable => \$oil], ] *-postcommand* A callback to be invoked before posting the menu. *-tearoff* Specifies whether sub-menu can be torn-off or not. *-menuvar* Scalar reference that will be set to the newly-created sub-menu. The returned object is currently a blessed reference to an array of two items: the containing Menu and the 'label'. Methods configure and cget are mapped onto underlying `entryconfigure' and `entrycget'. The main purpose of the OO interface is to allow derived item classes to be defined which pre-set the options used to create a more basic item. BUGS ==== This OO interface is very new. Using the label as the "key" is a problem for separaror items which don't have one. The alternative would be to use an index into the menu but that is a problem if items are deleted (or inserted other than at the end). There should probably be a PostInit entry point too, or a more widget like defered 'configure'.  File: pm.info, Node: Tk/JPEG, Next: Tk/LabFrame, Prev: Tk/Item, Up: Module List JPEG loader for Tk::Photo ************************* NAME ==== Tk::JPEG - JPEG loader for Tk::Photo SYNOPSIS ======== use Tk; use Tk::JPEG; my $image = $widget->Photo('-format' => 'jpeg', -file => 'something.jpg'); DESCRIPTION =========== This is an extension for Tk800.015 and later which supplies JPEG format loader for Photo image type. JPEG access is via release 5 of the The Independent JPEG Group's (IJG) free JPEG software. AUTHOR ====== Nick Ing-Simmons  File: pm.info, Node: Tk/LabFrame, Next: Tk/Label, Prev: Tk/JPEG, Up: Module List labeled frame. ************** NAME ==== Tk::LabFrame - labeled frame. SYNOPSIS ======== *use Tk::LabFrame;* $f = *$parent*->*LabFrame*(?*-label*=>text, *-labelside*=>where, ...?); DESCRIPTION =========== *LabFrame* is exactly like Frame and additionaly allows to add a label to the frame. WIDGET-OPTIONS ============== *LabFrame* supports the same options as the `Frame|Tk::Frame' in this node widget. Additional options of *LabFrame* are: *-label* => text The text of the label to be placed with the Frame. *-labelside* => where Where can be one of left, right, top, *bottom* or *acrosstop*. The first four work as might be expected and place the label to the left, right, above or below the frame respectively. The *acrosstop* creates a grooved frame around the central frame and puts the label near the northwest corner such that it appears to "overwrite" the groove. EXAMPLE ======= Run the following test program to see this in action: use strict; use Tk; require Tk::LabFrame; require Tk::LabEntry; my $test = 'Test this'; my $mw = Tk::MainWindow->new; my $f = $mw->LabFrame(-label => "This is a label", -labelside => "acrosstop"); $f->LabEntry(-label => "Testing", -textvariable => \$test)->pack; $f->pack; Tk::MainLoop; BUGS ==== Perhaps *LabFrame* should be subsumed within the generic pTk labeled widget mechanism. AUTHOR ====== *Rajappa Iyer* rsi@earthling.net This code is derived from LabFrame.tcl and LabWidg.tcl in the Tix4.0 distribution by Ioi Lam. The code may be redistributed under the same terms as Perl.  File: pm.info, Node: Tk/Label, Next: Tk/Listbox, Prev: Tk/LabFrame, Up: Module List Create and manipulate Label widgets *********************************** NAME ==== Tk::Label - Create and manipulate Label widgets $label = *$parent*->Label(?options?); STANDARD OPTIONS ================ *-anchor* *-font* *-image* *-takefocus* *-background* *-foreground* -justify *-text* *-bitmap* *-highlightbackground* *-padx* *-textvariable* *-borderwidth* *-highlightcolor* *-pady* *-underline* *-cursor* *-highlightthickness* *-relief* *-wraplength* See *Note Tk/options: Tk/options, for details of the standard options. WIDGET-SPECIFIC OPTIONS ======================= Name: height Class: *Height* Switch: *-height* Specifies a desired height for the label. If an image or bitmap is being displayed in the label then the value is in screen units (i.e. any of the forms acceptable to *Tk_GetPixels*); for text it is in lines of text. If this option isn't specified, the label's desired height is computed from the size of the image or bitmap or text being displayed in it. Name: width Class: Width Switch: *-width* Specifies a desired width for the label. If an image or bitmap is being displayed in the label then the value is in screen units (i.e. any of the forms acceptable to *Tk_GetPixels*); for text it is in characters. If this option isn't specified, the label's desired width is computed from the size of the image or bitmap or text being displayed in it. DESCRIPTION =========== The Label method creates a new window (given by the $widget argument) and makes it into a label widget. Additional options, described above, may be specified on the command line or in the option database to configure aspects of the label such as its colors, font, text, and initial relief. The label command returns its $widget argument. At the time this command is invoked, there must not exist a window named $widget, but $widget's parent must exist. A label is a widget that displays a textual string, bitmap or image. If text is displayed, it must all be in a single font, but it can occupy multiple lines on the screen (if it contains newlines or if wrapping occurs because of the *wrapLength* option) and one of the characters may optionally be underlined using the underline option. The label can be manipulated in a few simple ways, such as changing its relief or text, using the commands described below. WIDGET METHODS ============== The Label 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. BINDINGS ======== When a new label is created, it has no default event bindings: labels are not intended to be interactive. KEYWORDS ======== label, widget  File: pm.info, Node: Tk/Listbox, Next: Tk/LockDisplay, Prev: Tk/Label, Up: Module List Create and manipulate Listbox widgets ************************************* NAME ==== Tk::Listbox - Create and manipulate Listbox widgets *$listbox* = *$parent*->Listbox(?options?); STANDARD OPTIONS ================ *-background* *-foreground* *-relief* *-takefocus* *-borderwidth* *-height* *-selectbackground* *-width* *-cursor* *-highlightbackground* *-selectborderwidth* *-xscrollcommand* *-exportselection* *-highlightcolor* *-selectforeground* *-yscrollcommand* *-font* *-highlightthickness* *-setgrid* See *Note Tk/options: Tk/options, for details of the standard options. WIDGET-SPECIFIC OPTIONS ======================= Name: height Class: *Height* Switch: *-height* Specifies the desired height for the window, in lines. If zero or less, then the desired height for the window is made just large enough to hold all the elements in the listbox. 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 browse. Name: width Class: Width Switch: *-width* Specifies the desired width for the window in characters. If the font doesn't have a uniform width then the width of the character "0" is used in translating from character units to screen units. If zero or less, then the desired width for the window is made just large enough to hold all the elements in the listbox. DESCRIPTION =========== The Listbox method creates a new window (given by the $widget argument) and makes it into a listbox widget. Additional options, described above, may be specified on the command line or in the option database to configure aspects of the listbox such as its colors, font, text, and relief. The listbox command returns its $widget argument. At the time this command is invoked, there must not exist a window named $widget, but $widget's parent must exist. A listbox is a widget that displays a list of strings, one per line. When first created, a new listbox has no elements. Elements may be added or deleted using methods described below. In addition, one or more elements may be selected as described below. If a listbox is exporting its selection (see *exportSelection* option), then it will observe the standard X11 protocols for handling the selection. Listbox selections are available as type STRING; the value of the selection will be the text of the selected elements, with newlines separating the elements. It is not necessary for all the elements to be displayed in the listbox window at once; commands described below may be used to change the view in the window. Listboxes allow scrolling in both directions using the standard *xScrollCommand* and *yScrollCommand* options. They also support scanning, as described below. INDICES ======= Many of the methods for listboxes take one or more indices as arguments. An index specifies a particular element of the listbox, in any of the following ways: number Specifies the element as a numerical index, where 0 corresponds to the first element in the listbox. active Indicates the element that has the location cursor. This element will be displayed with an underline when the listbox has the keyboard focus, and it is specified with the activate method. anchor Indicates the anchor point for the selection, which is set with the *selection anchor* method. end Indicates the end of the listbox. For most commands this refers to the last element in the listbox, but for a few commands such as index and insert it refers to the element just after the last one. *@*x*,*y Indicates the element that covers the point in the listbox window specified by x and y (in pixel coordinates). If no element covers that point, then the closest element to that point is used. In the method descriptions below, arguments named index, first, and last always contain text indices in one of the above forms. WIDGET METHODS ============== The Listbox 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 listbox widgets: *$listbox*->activate(index) Sets the active element to the one indicated by index. If index is outside the range of elements in the listbox then the closest element is activated. The active element is drawn with an underline when the widget has the input focus, and its index may be retrieved with the index active. *$listbox*->*bbox*(index) Returns a list of four numbers describing the bounding box of the text in the element given by index. The first two elements of the list give the x and y coordinates of the upper-left corner of the screen area covered by the text (specified in pixels relative to the widget) and the last two elements give the width and height of the area, in pixels. If no part of the element given by index is visible on the screen, or if index refers to a non-existent element, then the result is an empty string; if the element is partially visible, the result gives the full area of the element, including any parts that are not visible. *$listbox*->*curselection* Returns a list containing the numerical indices of all of the elements in the listbox that are currently selected. If there are no elements selected in the listbox then an empty string is returned. *$listbox*->delete(*first, *?last?) Deletes one or more elements of the listbox. First and last are indices specifying the first and last elements in the range to delete. If last isn't specified it defaults to first, i.e. a single element is deleted. *$listbox*->get(*first, *?last?) If last is omitted, returns the contents of the listbox element indicated by first, or an empty string if first refers to a non-existent element. If last is specified, the command returns a list whose elements are all of the listbox elements between first and last, inclusive. Both first and last may have any of the standard forms for indices. *$listbox*->index(index) Returns the integer index value that corresponds to index. If index is end the return value is a count of the number of elements in the listbox (not the index of the last element). *$listbox*->insert(*index, *?*element, element, ...*?) Inserts zero or more new elements in the list just before the element given by index. If index is specified as end then the new elements are added to the end of the list. Returns an empty string. *$listbox*->nearest(y) Given a y-coordinate within the listbox window, this command returns the index of the (visible) listbox element nearest to that y-coordinate. *$listbox*->scan(*option, args*) This command is used to implement scanning on listboxes. It has two forms, depending on option: *$listbox*->*scanMark*(*x, y*) Records x and y and the current view in the listbox window; used in conjunction with later *scan dragto* commands. Typically this command is associated with a mouse button press in the widget. It returns an empty string. *$listbox*->*scanDragto*(*x, y*.) This command computes the difference between its x and y arguments and the x and y arguments to the last *scan mark* command for the widget. It then adjusts the view by 10 times the difference in coordinates. This command is typically associated with mouse motion events in the widget, to produce the effect of dragging the list at high speed through the window. The return value is an empty string. *$listbox*->see(index) Adjust the view in the listbox so that the element given by index is visible. If the element is already visible then the command has no effect; if the element is near one edge of the window then the listbox scrolls to bring the element into view at the edge; otherwise the listbox scrolls to center the element. *$listbox*->selection(*option, arg*) This command is used to adjust the selection within a listbox. It has several forms, depending on option: *$listbox*->*selectionAnchor*(index) Sets the selection anchor to the element given by index. If index refers to a non-existent element, then the closest element is used. The selection anchor is the end of the selection that is fixed while dragging out a selection with the mouse. The index anchor may be used to refer to the anchor element. *$listbox*->*selectionClear*(*first, *?last?) If any of the elements between first and last (inclusive) are selected, they are deselected. The selection state is not changed for elements outside this range. *$listbox*->*selectionIncludes*(index) Returns 1 if the element indicated by index is currently selected, 0 if it isn't. *$listbox*->*selectionSet*(*first, *?last?) Selects all of the elements in the range between first and last, inclusive, without affecting the selection state of elements outside that range. *$listbox*->size Returns a decimal string indicating the total number of elements in the listbox. *$listbox*->*xview*(args) This command is used to query and change the horizontal position of the information in the widget's window. It can take any of the following forms: *$listbox*->*xview* Returns a list containing two elements. Each element is a real fraction between 0 and 1; together they describe the horizontal span that is visible in the window. For example, if the first element is .2 and the second element is .6, 20% of the listbox's text is off-screen to the left, the middle 40% is visible in the window, and 40% of the text is off-screen to the right. These are the same values passed to scrollbars via the *-xscrollcommand* option. *$listbox*->*xview*(index) Adjusts the view in the window so that the character position given by index is displayed at the left edge of the window. Character positions are defined by the width of the character 0. *$listbox*->*xview*(*moveto* => *fraction*) Adjusts the view in the window so that *fraction* of the total width of the listbox text is off-screen to the left. *fraction* must be a fraction between 0 and 1. *$listbox*->*xview*(scroll => *number, what*) This command shifts the view in the window left or right according to number and *what*. Number must be an integer. What must be either *units* or *pages* or an abbreviation of one of these. If *what* is *units*, the view adjusts left or right by number character units (the width of the 0 character) on the display; if it is *pages* then the view adjusts by number screenfuls. If number is negative then characters farther to the left become visible; if it is positive then characters farther to the right become visible. *$listbox*->*yview*(*?args*?) This command is used to query and change the vertical position of the text in the widget's window. It can take any of the following forms: *$listbox*->*yview* Returns a list containing two elements, both of which are real fractions between 0 and 1. The first element gives the position of the listbox element at the top of the window, relative to the listbox as a whole (0.5 means it is halfway through the listbox, for example). The second element gives the position of the listbox element just after the last one in the window, relative to the listbox as a whole. These are the same values passed to scrollbars via the *-yscrollcommand* option. *$listbox*->*yview*(index) Adjusts the view in the window so that the element given by index is displayed at the top of the window. *$listbox*->*yview*(*moveto* => *fraction*) Adjusts the view in the window so that the element given by *fraction* appears at the top of the window. *Fraction* is a fraction between 0 and 1; 0 indicates the first element in the listbox, 0.33 indicates the element one-third the way through the listbox, and so on. *$listbox*->*yview*(scroll => *number, what*) This command adjusts the view in the window up or down according to number and *what*. Number must be an integer. What must be either *units* or *pages*. If *what* is *units*, the view adjusts up or down by number lines; if it is *pages* then the view adjusts by number screenfuls. If number is negative then earlier elements become visible; if it is positive then later elements become visible. DEFAULT BINDINGS ================ Tk automatically creates class bindings for listboxes that give them Motif-like behavior. Much of the behavior of a listbox is determined by its *selectMode* option, which selects one of four ways of dealing with the selection. If the selection mode is single or browse, at most one element can be selected in the listbox at once. In both modes, clicking button 1 on an element selects it and deselects any other selected item. In browse mode it is also possible to drag the selection with button 1. If the selection mode is multiple or *extended*, any number of elements may be selected at once, including discontiguous ranges. In multiple mode, clicking button 1 on an element toggles its selection state without affecting any other elements. In *extended* mode, pressing button 1 on an element selects it, deselects everything else, and sets the anchor to the element under the mouse; dragging the mouse with button 1 down extends the selection to include all the elements between the anchor and the element under the mouse, inclusive. Most people will probably want to use browse mode for single selections and *extended* mode for multiple selections; the other modes appear to be useful only in special situations. In addition to the above behavior, the following additional behavior is defined by the default bindings: [1] In *extended* mode, the selected range can be adjusted by pressing button 1 with the Shift key down: this modifies the selection to consist of the elements between the anchor and the element under the mouse, inclusive. The un-anchored end of this new selection can also be dragged with the button down. [2] In *extended* mode, pressing button 1 with the Control key down starts a toggle operation: the anchor is set to the element under the mouse, and its selection state is reversed. The selection state of other elements isn't changed. If the mouse is dragged with button 1 down, then the selection state of all elements between the anchor and the element under the mouse is set to match that of the anchor element; the selection state of all other elements remains what it was before the toggle operation began. [3] If the mouse leaves the listbox window with button 1 down, the window scrolls away from the mouse, making information visible that used to be off-screen on the side of the mouse. The scrolling continues until the mouse re-enters the window, the button is released, or the end of the listbox is reached. [4] Mouse button 2 may be used for scanning. If it is pressed and dragged over the listbox, the contents of the listbox drag at high speed in the direction the mouse moves. [5] If the Up or Down key is pressed, the location cursor (active element) moves up or down one element. If the selection mode is browse or *extended* then the new active element is also selected and all other elements are deselected. In *extended* mode the new active element becomes the selection anchor. [6] In *extended* mode, Shift-Up and Shift-Down move the location cursor (active element) up or down one element and also extend the selection to that element in a fashion similar to dragging with mouse button 1. [7] The Left and Right keys scroll the listbox view left and right by the width of the character 0. Control-Left and Control-Right scroll the listbox view left and right by the width of the window. Control-Prior and Control-Next also scroll left and right by the width of the window. [8] The Prior and Next keys scroll the listbox view up and down by one page (the height of the window). [9] The Home and End keys scroll the listbox horizontally to the left and right edges, respectively. [10] Control-Home sets the location cursor to the the first element in the listbox, selects that element, and deselects everything else in the listbox. [11] Control-End sets the location cursor to the the last element in the listbox, selects that element, and deselects everything else in the listbox. [12] In *extended* mode, Control-Shift-Home extends the selection to the first element in the listbox and Control-Shift-End extends the selection to the last element. [13] In multiple mode, Control-Shift-Home moves the location cursor to the first element in the listbox and Control-Shift-End moves the location cursor to the last element. [14] The space and Select keys make a selection at the location cursor (active element) just as if mouse button 1 had been pressed over this element. [15] In *extended* mode, Control-Shift-space and Shift-Select extend the selection to the active element just as if button 1 had been pressed with the Shift key down. [16] In *extended* mode, the Escape key cancels the most recent selection and restores all the elements in the selected range to their previous selection state. [17] Control-slash selects everything in the widget, except in single and browse modes, in which case it selects the active element and deselects everything else. [18] Control-backslash deselects everything in the widget, except in browse mode where it has no effect. [19] The F16 key (labelled Copy on many Sun workstations) or Meta-w copies the selection in the widget to the clipboard, if there is a selection. The behavior of listboxes can be changed by defining new bindings for individual widgets or by redefining the class bindings. KEYWORDS ======== listbox, widget  File: pm.info, Node: Tk/LockDisplay, Next: Tk/MListbox, Prev: Tk/Listbox, Up: Module List Create modal dialog and wait for a password response. ***************************************************** NAME ==== Tk::LockDisplay - Create modal dialog and wait for a password response. SYNOPSIS ======== $lock = *$parent*->*LockDisplay*(*-option* => value, ... ); DESCRIPTION =========== This widget fills the display with a screensaver-like animation, makes a global grab and then waits for the user's authentication string, usually their password. Until the password is entered the display cannot be used: window manager commands are ignored, etcetera. Note, X server requests are not blocked. Password verification is perforemd via a callback passed during widget creation. While waiting for the user to respond, *LockDisplay* sets a global grab. This prevents the user from interacting with any application in any way except to type characters in the LockDisplay entry box. See the *Lock()* method. The following option/value pairs are supported: *-authenticate* Password verification subroutine - it's passed two positional parameters, the username and password, and should return 1 if success, else 0. *-animation* A string indicating what screensaver plugin to use, or 'none' to disable the screensaver. Supplied plugins are 'lines' (default), 'neko' and 'counter', which reside in the directory .../Tk/LockDisplay. You can drop a plugin of your own in that directory - see the section Plugin Format below for details. You can also supply your own animation subroutine by passing a CODE reference. The subroutine is passed a single parameter, the canvas widget reference, which you can draw upon as you please. *-animationinterval* The number of milliseconds between calls to the screen saver animation code. Default is 200 milliseconds. Plugins can specifiy their own interval by returning the number of milliseconds (> 1) during initialization. *-hide* How many seconds of display inactivity before hiding the password entry widget and canvas title text. Default is 10 seconds. *-text* Title text centered in canvas. *-foreground* Title text color. *-background* Canvas color. *-debug* Set to 1 allows a event to unlock the display. Used while debugging your authentication callback or plugin. METHODS ======= `$lock->*Lock*;' This method locks the display and waits for the user's authentication data. EXAMPLE ======= $lock = *$mw*->*LockDisplay*(-authenticate => \&check_pw); sub check_pw { # Perform AFS validation unless on Win32. my($user, $pw) = @_; if ($^O eq 'MSWin32') { ($pw eq $^O) ? exit(0) : return(0); } else { system "/usr/afsws/bin/klog $user " . quotemeta($pw) . " 2> /dev/null"; ($? == 0) ? exit(0) : return(0); } } # end check_pw PLUGIN FORMAT ============= Refer to the "counter" plugin file .../Tk/LockDisplay/counter.pm for details on the structure of a LockDisplay animation plugin. Basically, you create a ".pm" file that describes your plugin, "counter.pm" for instance. This file must contain a subroutine called Animate($canvas), where $canvas is the canvas widget reference passed to it. LockDisplay first require()s your plugin file, and, if that succeeds, calls it once to perform initialization. Animate() should return 0 for failure, 1 for success, and > 1 for success and to specifiy a private -animationinterval (in milliseconds). Subsequent calls to Animate() are for its "main loop" processing. As before, the return code should be 0 or 1 for failure or success, respectively. HISTORY ======= Version 1.0 Beta Release. Version 1.1 . Implement plugins and other fixes suggested by Achim Bohnet. Thanks! . Allow plugin name 'none' to disable screensaver. Thanks to Roderick Anderson! Version 1.2 . getlogin() fails on HPUX, so try getpwuid() as a fallback. Thanks to Paul Schinder for the CPAN-Testers bug report. . Plugins can return() their own -animationinterval value during preset. . Add 'neko' plugin. Version 1.3 . Fix value of pi in neko plugin! . Add Windows 95 support AUTHOR ====== Stephen.O.Lidie@Lehigh.EDU COPYRIGHT ========= Copyright (C) 1998 - 1998, Stephen O. Lidie. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. KEYWORDS ======== screeensaver, dialog, modal