This is Info file pm.info, produced by Makeinfo version 1.68 from the input file bigpm.texi.  File: pm.info, Node: Tk/FileEntry, Next: Tk/FileSelect, Prev: Tk/FileDialog, Up: Module List FileEntry widget with optional file selection box ************************************************* NAME ==== Tk::FileEntry - FileEntry widget with optional file selection box SYNOPSIS ======== use Tk::FileEntry; $fileentry = $parent->FileEntry( -filebitmap => BITMAP, -command => CALLBACK, -variable => SCALARREF, ); DESCRIPTION =========== WIDGET-SPECIFIC OPTIONS ======================= Option: *-filebitmap* Name: *fileBitmap* Class: *FileBitmap* Specifies the bitmap to be used for the button that invokes the File Dialog. *-command* ... *-variable* ... BUGS ==== If *FileEntry* is resized to a value smaller than at creation time the Openfile Bitmap vanishes. FileSelection of alpha release Tk800.003 does not work (my fault!). So FileEntrys FileSelction dialog will not work with this release. SEE ALSO ======== `Tk|Tk' in this node `Tk::Entry|Tk::Entry' in this node `Tk::FileSelect|k::FileSelect' in this node KEYWORDS ======== fileentry, tix, widget, file selector AUTHOR ====== Achim Bohnet <`ach@mpe.mpg.de'> This code is inspired by the documentation of FileEntry.n of the Tix4.1.0 distribution by Ioi Lam. The bitmap data are also from Tix4.1.0. For everything else: Copyright (c) 1997-1998 Achim Bohnet. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: Tk/FileSelect, Next: Tk/FireButton, Prev: Tk/FileEntry, Up: Module List a widget for choosing files *************************** NAME ==== Tk::FileSelect - a widget for choosing files SYNOPSIS ======== use Tk::FileSelect; $FSref = $top->FileSelect(-directory => $start_dir); $top - a window reference, e.g. MainWindow->new $start_dir - the starting point for the FileSelect $file = $FSref->Show; Executes the fileselector until either a filename is accepted or the user hits Cancel. Returns the filename or the empty string, respectively, and unmaps the FileSelect. $FSref->configure(option => value[, ...]) Please see the Populate subroutine as the configuration list changes rapidly. DESCRIPTION =========== This Module pops up a Fileselector box, with a directory entry on top, a list of directories in the current directory, a list of files in the current directory, an entry for entering/modifying a file name, an accept button and a cancel button. You can enter a starting directory in the directory entry. After hitting Return, the listboxes get updated. Double clicking on any directory shows you the respective contents. Single clicking on a file brings it into the file entry for further consideration, double clocking on a file pops down the file selector and calls the optional command with the complete path for the selected file. Hitting return in the file selector box or pressing the accept button will also work. *NOTE* the file selector box will only then get destroyed if the file name is not zero length. If you want yourself take care of it, change the if(length(.. in sub accept_file. AUTHORS ======= Based on original FileSelect by Klaus Lichtenwalder, Lichtenwalder@ACM.org, Datapat GmbH, Munich, April 22, 1995 adapted by Frederick L. Wagner, derf@ti.com, Texas Instruments Incorporated, Dallas, 21Jun95 HISTORY ======= 950621 - The following changes were made: ----------------------------------------- * Rewrote Tk stuff to take advantage of new Compound widget module, so FileSelect is now composed of 2 LabEntry and 2 ScrlListbox2 subwidgets. * Moved entry labels (from to the left of) to above the entry fields. * Caller is now able to control these aspects of widget, in both FileSelect (new) and configure : (Please see subroutine Populate for details, as these options change rapidly!) * I changed from Double-Button-1 to Button-1 in the Files listbox, to work with multiple mode in addition to browse mode. I also made some name changes (LastPath -> saved_path, ...). * The show method is not yet updated. * The topLevel stuff is not done yet. I took it out while I toy with the idea of FileSelect as a subwidget. Then the 'normal' topLevel thing with Buttons along the bottom could be build on top of it. * By request of Henry Katz , I added the functionality of using the Directory entry as a filter. So, if you want to only see the *.c files, you add a .c (the *'s already there :) and hit return. 95/10/17, SOL, LUCC. lusol@Lehigh.EDU -------------------------------------- * Allow either file or directory names to be accepted. * Require double click to move into a new directory rather than a single click. This allows a single click to select a directory name so it can be accepted. * Add -verify list option so that standard Perl file test operators (like -d and -x) can be specified for further name validation. The default value is the special value '!-d' (not a directory), so any name can be selected as long as it's not a directory - after all, this IS FileSelect! For example: $fs->configure(-verify => ['-d', [\&verify_code, $P1, $P2, ... $Pn]]); ensures that the selected name is a directory. Further, if an element of the list is an array reference, the first element is a code reference to a subroutine and the remaining optional elements are it's parameters. The subroutine is called like this: &verify_code($cd, $leaf, $P1, $P2, ... $Pn); where $cd is the current directory, $leaf is a directory or file name, and $P1 .. $Pn are your optional parameters. The subroutine should return TRUE if success or FALSE if failure. 961008 - derf@ti.com : ---------------------- By request of Jim Stern and Brad Vance , I updated the Accept and Show functions to support selection of multiple files. I also corrected a typo in the -verify code.  File: pm.info, Node: Tk/FireButton, Next: Tk/Font, Prev: Tk/FileSelect, Up: Module List Button that keeps invoking callback when pressed ************************************************ NAME ==== Tk::FireButton - Button that keeps invoking callback when pressed SYNOPSIS ======== use Tk::FireButton; $fire = $parent->FireButton( ... ); # May/should change: $w->Whatever(... -bitmap => $Tk::FireButton::INCBITMAP, ...); $w->Whatever(... -bitmap => $Tk::FireButton::DECBITMAP, ...); $w->Whatever(... -bitmap => $Tk::FireButton::HORIZINCBITMAP, ...); $w->Whatever(... -bitmap => $Tk::FireButton::HORIZDECBITMAP, ...); DESCRIPTION =========== *FireButton* is-a Button widget (see *Note Tk/Button: Tk/Button,) that keeps invoking the callback bound to it as long as the is pressed. Four suitable bitmaps are predefined in this package: $INCBITMAP and $DECBITMAP for vertical increment and decrement buttons, and $HORIZINCBITMAP and $HORIZDECBITMAP for horizontal increment and decrement buttons. See below for methods accessing these bitmaps. SUPER-CLASS =========== The *FireButton* widget-class is derived from the Button widget-class and inherits all the methods and options its super-class (see *Note Tk/Button: Tk/Button,). STANDARD OPTIONS ================ *FireButton* supports all the standard options of a Button widget. See *Note Tk/options: Tk/options, for details on the standard options. WIDGET-SPECIFIC OPTIONS ======================= Name: *repeatDelay* Class: *RepeatDelay* Switch: *-repeatdelay* Fallback: *300* (milliseconds) Specifies the amount of time before the callback is first invoked after the Button-1 is pressed over the widget. Name: *repeatInterval* Class: *RepeatInterval* Switch: *-repeatinterval* Fallback: 100 (milliseconds) Specifies the amount of time between invokations of the callback bound to the widget with the command option. CHANDED OPTION FALLBACK VALUES ============================== The fallback values of the following options as different from the Button widget: -padx => 0, -pady => 0, METHODS ======= Same as for `Button|Tk::Button' in this node widget. Additionally, there are four methods returning the names of the standard increment and decrement bitmaps: INCBITMAP, HORIZINCBITMAP, DECBITMAP, and HORIZDECBITMAP. Subclasses of FireButton may override these methods to supply different increment and decrement bitmaps. ADVERTISED WIDGETS ================== None. HISTORY ======= The code was extracted from Tk::NumEntry and slightly modified by Achim Bohnet >ach@mpe.mpg.de>. Tk::NumEntry's author is Graham Barr >gbarr@pobox.com>. The current maintainer is Slaven Rezic >eserte@cs.tu-berlin.de>.  File: pm.info, Node: Tk/Font, Next: Tk/FontDialog, Prev: Tk/FireButton, Up: Module List Create and inspect fonts. ************************* NAME ==== font - Create and inspect fonts. $widget->*Font*(option?, *arg, arg, ...*?) $font->Option?(*arg, arg, ...*)? DESCRIPTION =========== The *Font* method provides several facilities for dealing with fonts, such as defining named fonts and inspecting the actual attributes of a font. The command has several different forms, determined by the first argument. The following forms are currently supported: $font->*actual*(*-option*?) $widget->*fontActual*(font?, *-option*?) Returns information about the actual attributes that are obtained when font is used on $font's display; the actual attributes obtained may differ from the attributes requested due to platform-dependant limitations, such as the availability of font families and pointsizes. font is a font description; see `"FONT DESCRIPTION"' in this node below. If option is specified, returns the value of that attribute; if it is omitted, the return value is a list of all the attributes and their values. See `"FONT OPTIONS"' in this node below for a list of the possible attributes. $font->configure(*-option*??=>value, *-option*=>value, ...?) Query or modify the desired attributes for $font. If no *-option* is specified, returns a list describing all the options and their values for fontname. If a single *-option* is specified with no value, then returns the current value of that attribute. If one or more *option-value* pairs are specified, then the method modifies the given named font to have the given values; in this case, all widgets using that font will redisplay themselves using the new attributes for the font. See `"FONT OPTIONS"' in this node below for a list of the possible attributes. Note: the above behaviour differs in detail to configure on widgets, images etc. $font = $widget->*Font*(*-option*=>value, ...>?) $font = $widget->*fontCreate*(?fontname??, *-option*=>value, ...>?) Creates a new font object and returns a reference to it. fontname specifies the name for the font; if it is omitted, then Tk generates a new name of the form fontx, where x is an integer. There may be any number of *option-value* pairs, which provide the desired attributes for the new named font. See `"FONT OPTIONS"' in this node below for a list of the possible attributes. Note: the created font is not shared between widgets of different `MainWindow|Tk::MainWindow' in this nodes. $font->delete $widget->*fontDelete*(fontname?, fontname, ...?) Delete the specified named fonts. If there are widgets using the named font, the named font won't actually be deleted until all the instances are released. Those widgets will continue to display using the last known values for the named font. If a deleted named font is subsequently recreated with another call to *fontCreate*, the widgets will use the new named font and redisplay themselves using the new attributes of that font. $widget->*fontFamilies* The return value is a list of the case-insensitive names of all font families that exist on $widget's display. $font->*measure*(text) $widget->*fontMeasure*(font, text) Measures the amount of space the string text would use in the given font when displayed in $widget. font is a font description; see `"FONT DESCRIPTION"' in this node below. The return value is the total width in pixels of text, not including the extra pixels used by highly exagerrated characters such as cursive "f". If the string contains newlines or tabs, those characters are not expanded or treated specially when measuring the string. $font->*metrics*(*-option*?) $widget->*fontMetrics*(font?, *-option*?) Returns information about the metrics (the font-specific data), for font when it is used on $widget's display. font is a font description; see `"FONT DESCRIPTION"' in this node below. If option is specified, returns the value of that metric; if it is omitted, the return value is a list of all the metrics and their values. See `"FONT METRICS"' in this node below for a list of the possible metrics. $widget->*fontNames* The return value is a list of all font objects that are currently defined for $widget's MainWindow. FONT DESCRIPTION ================ The following formats are accepted as a font description anywhere font is specified as an argument above; these same forms are also permitted when specifying the *-font* option for widgets. [1] fontname The name of a named font, created using the *fontCreate* method. When a widget uses a named font, it is guaranteed that this will never cause an error, as long as the named font exists, no matter what potentially invalid or meaningless set of attributes the named font has. If the named font cannot be displayed with exactly the specified attributes, some other close font will be substituted automatically. [1a] $font A font object created using the *Font* method. This is essentially the same as using a named font. The object is a reference to the name, and carries additional information e.g. which MainWindow it relates to in an manner peculiar to perl/Tk. [3] *systemfont* The platform-specific name of a font, interpreted by the graphics server. This also includes, under X, an XLFD (see `[4]|' in this node) for which a single "*" character was used to elide more than one field in the middle of the name. See `"PLATFORM-SPECIFIC ISSUES"' in this node for a list of the system fonts. [3] [family,?size,??style,??*style ...*?] A properly formed list whose first element is the desired font family and whose optional second element is the desired size. The interpretation of the size attribute follows the same rules described for `-size|' in this node in `"FONT OPTIONS"' in this node below. Any additional optional arguments following the size are font styles. Possible values for the style arguments are as follows: normal bold roman italic underline overstrike [4] X-font names (XLFD) A Unix-centric font name of the form *-foundry-family-weight-slant-setwidth-addstyle-pixel-point-resx-resy-spacing-width-charset-encoding*. The "*" character may be used to skip individual fields that the user does not care about. There must be exactly one "*" for each field skipped, except that a "*" at the end of the XLFD skips any remaining fields; the shortest valid XLFD is simply "*", signifying all fields as defaults. Any fields that were skipped are given default values. For compatibility, an XLFD always chooses a font of the specified pixel size (not point size); although this interpretation is not strictly correct, all existing applications using XLFDs assumed that one "point" was in fact one pixel and would display incorrectly (generally larger) if the correct size font were actually used. [5] *option value *?*option value ...*? A properly formed list of *option-value* pairs that specify the desired attributes of the font, in the same format used when defining a named font; see `"FONT OPTIONS"' in this node below. When font description font is used, the system attempts to parse the description according to each of the above five rules, in the order specified. Cases [1] and [2] must match the name of an existing named font or of a system font. Cases [3], [4], and [5] are accepted on all platforms and the closest available font will be used. In some situations it may not be possible to find any close font (e.g., the font family was a garbage value); in that case, some system-dependant default font is chosen. If the font description does not match any of the above patterns, an error is generated. FONT METRICS ============ The following options are used by the *metrics*/*fontMetrics* method to query font-specific data determined when the font was created. These properties are for the whole font itself and not for individual characters drawn in that font. In the following definitions, the "baseline" of a font is the horizontal line where the bottom of most letters line up; certain letters, such as lower-case "g" stick below the baseline. *-ascent* The amount in pixels that the tallest letter sticks up above the baseline of the font, plus any extra blank space added by the designer of the font. ($font-*ascent* is provided for compatibility.) *-descent* The largest amount in pixels that any letter sticks down below the baseline of the font, plus any extra blank space added by the designer of the font. ($font-*descent* is provided for compatibility.) *-linespace* Returns how far apart vertically in pixels two lines of text using the same font should be placed so that none of the characters in one line overlap any of the characters in the other line. This is generally the sum of the ascent above the baseline line plus the descent below the baseline. *-fixed* Returns a boolean flag that is "1" if this is a fixed-width font, where each normal character is the the same width as all the other characters, or is "0" if this is a proportionally-spaced font, where individual characters have different widths. The widths of control characters, tab characters, and other non-printing characters are not included when calculating this value. FONT OPTIONS ============ The following options are supported on all platforms, and are used when constructing a named font or when specifying a font using style [5] as above: *-family* => name The case-insensitive font family name. Tk guarantees to support the font families named *Courier* (a monospaced "typewriter" font), *Times* (a serifed "newspaper" font), and *Helvetica* (a sans-serif "European" font). The most closely matching native font family will automatically be substituted when one of the above font families is used. The name may also be the name of a native, platform-specific font family; in that case it will work as desired on one platform but may not display correctly on other platforms. If the family is unspecified or unrecognized, a platform-specific default font will be chosen. *-size* => size The desired size of the font. If the size argument is a positive number, it is interpreted as a size in points. If size is a negative number, its absolute value is interpreted as a size in pixels. If a font cannot be displayed at the specified size, a nearby size will be chosen. If size is unspecified or zero, a platform-dependent default size will be chosen. The original Tcl/Tk authors believe sizes should normally be specified in points so the application will remain the same ruler size on the screen, even when changing screen resolutions or moving scripts across platforms. While this is an admirable goal it does not work as well in practice as they hoped. The mapping between points and pixels is set when the application starts, based on alleged properties of the installed monitor, but it can be overridden by calling the `scaling|Tk::Widget' in this node command. However this can be problematic when system has no way of telling if (say) an 11" or 22" monitor is attached, also if it can tell then some monitor sizes may result in poorer quality scaled fonts being used rather than a "tuned" bitmap font. In addition specifying pixels is useful in certain circumstances such as when a piece of text must line up with respect to a fixed-size bitmap. At present the Tcl/Tk scheme is used unchanged, with "point" size being returned by *actual* (as an integer), and used internally. Suggestions for work-rounds to undesirable behaviour welcome. *-weight* => weight The nominal thickness of the characters in the font. The value normal specifies a normal weight font, while bold specifies a bold font. The closest available weight to the one specified will be chosen. The default weight is normal. *-slant* => *slant* The amount the characters in the font are slanted away from the vertical. Valid values for slant are *roman* and italic. A roman font is the normal, upright appearance of a font, while an italic font is one that is tilted some number of degrees from upright. The closest available slant to the one specified will be chosen. The default slant is *roman*. *-underline* => boolean The value is a boolean flag that specifies whether characters in this font should be underlined. The default value for underline is false. *-overstrike* => boolean The value is a boolean flag that specifies whether a horizontal line should be drawn through the middle of characters in this font. The default value for overstrike is false. PLATFORM-SPECIFIC ISSUES ======================== The following named system fonts are supported: X Windows: All valid X font names, including those listed by xlsfonts(1), are available. MS Windows: system ansi device systemfixed ansifixed oemfixed Macintosh: system application COMPATIBILITY WITH PREVIOUS VERSIONS ==================================== In prior versions of perl/Tk the $widget->*Font* method was a perl wrapper on the original "[4] X-font names (XLFD)" style as described above (which was the only form supported by versions of core tk prior to version tk8.0). This module is provided in its original form (it has just been renamed) via: use Tk::X11Font; I<$widget>-Greater_Than_Special_SequenceB(...) However the methods of the old scheme have been mimiced as closely as possible with the new scheme. It is intended that code should work without modification, except for the case of using : @names = $font->Name; i.e. the Name method in an array/list context. This now returns one element on all platforms (as it did on Win32), while previously on X systems it returned a list of fonts that matched an under-specified pattern. Briefly the methods supported for compatibilty are as follows: $newfont = $font->Clone(*-option*=>value, ...>?) Returns a new font object $newfont related to the original $font by changing the values of the specified *-option*s. $font->Family - maps to -family $font->Weight - maps to -weight $font->Slant - maps to -slant $font->Pixel and Point - map to -size New code should use $font->configure to achieve same effect as last four items above. Foundry, Swidth, Adstyle, Xres, Yres, Space, Avgwidth, Registry, Encoding Are all ignored if set, and return '*' if queried. $font->Name Returns the name of a named font, or a string representation of an unnamed font. Using $font in a scalar context does the same. Note this is distinctly different from behaviour of `X11Font's Name|Tk::X11Font' in this node in a list context. $font->Pattern Returns a XLFD string for the font based on *actual* values, and some heuristics to map Tk's forms to the "standard" X conventions. SEE ALSO ======== `Tk::options|Tk::options' in this node `Tk::X11Font|Tk::X11Font' in this node KEYWORDS ======== font  File: pm.info, Node: Tk/FontDialog, Next: Tk/Frame, Prev: Tk/Font, Up: Module List a font dialog widget for perl/Tk ******************************** NAME ==== Tk::FontDialog - a font dialog widget for perl/Tk SYNOPSIS ======== use Tk::FontDialog; $font = $top->FontDialog->Show; DESCRIPTION =========== Tk::FontDialog implements a font dialog widget. XXX WIDGET-SPECIFIC OPTIONS ======================= -font The dialog font. -initfont The initial font. -fontsizes A list of font sizes. The default contains sizes from 0 to 72 points (XXX or pixels?). -nicefont If set, font names are displayed in its font style. This may be slow, especially if you have many fonts or 16 bit fonts (e.g. Asian fonts). -nicefontsbutton If set to false, then the "Nice fonts" button is not displayed. -fixedfont If set, proportional font families are not listed, leaving only the fixed fonts. This is slow, as each font must be checked to see if it is fixed or proportional. -fixedfontsbutton If set to false, then the "Fixed fonts" button is not displayed. -sampletext The sample text which should contain all letters. The default is "The Quick Brown Fox Jumps Over The Lazy Dog" German readers may probably use "Franz jagt im komplett verwahrlosten Taxi quer durch Bayern". INTERNATIONALIZATION ==================== There are a couple of options to change the labels of the dialog. Note that you can prepend a tilde (`~') to get an accelerator key with `Alt'. Here is a list of these options with the default (English) setting: -familylabel (Family:) -sizelabel (Size:) -weightlabel (Bold) -slantlabel (Italic) -underlinelabel (Underline) -overstrikelabel (Overstrike) -oklabel (OK) -applylabel (Apply) -cancellabel (Cancel) -altsamplelabel (Alt sample) -nicefontslabel (Nicefonts) -fixedfontslabel (Fixed Only) BUGS/TODO ========= - better POD - XXX - ConfigSpecs handling is poor put at least -font into configspecs - run test, call dialog for 2nd time: immediate change of font? - better name for nicefont - restrict on charsets and encodings (xlsfonts? X11::Protocol::ListFonts?) difficult because core Tk font handling ignores charsets and encodings SEE ALSO ======== `Tk::font|Tk::font' in this node AUTHOR ====== Slaven Rezic Suggestions by Michael Houghton . COPYRIGHT ========= Copyright (c) 1998,1999 Slaven Rezic. All rights reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: Tk/Frame, Next: Tk/Getopt, Prev: Tk/FontDialog, Up: Module List Create and manipulate Frame widgets *********************************** NAME ==== Tk::Frame - Create and manipulate Frame widgets *$frame* = *$parent*->Frame(?options?); STANDARD OPTIONS ================ *-borderwidth* *-highlightbackground* *-highlightthickness* *-takefocus* *-class* *-highlightcolor* *-relief* *-cursor* See *Note Tk/options: Tk/options, for details of the standard options. WIDGET-SPECIFIC OPTIONS ======================= Name: background Class: Background Switch: *-background* This option is the same as the standard background option except that its value may also be specified as an undefined value. In this case, the widget will display no background or border, and no colors will be consumed from its colormap for its background and border. Name: colormap Class: *Colormap* Switch: *-colormap* Specifies a colormap to use for the window. The value may be either new, in which case a new colormap is created for the window and its children, or the name of another window (which must be on the same screen and have the same visual as $widget), in which case the new window will use the colormap from the specified window. If the colormap option is not specified, the new window uses the same colormap as its parent. This option may not be changed with the configure method. Name: container Class: Container Switch: *-container* The value must be a boolean. If true, it means that this window will be used as a container in which some other application will be embedded (for example, a Tk toplevel can be embedded using the *-use* option). The window will support the appropriate window manager protocols for things like geometry requests. The window should not have any children of its own in this application. This option may not be changed with the configure method. Name: height Class: *Height* Switch: *-height* Specifies the desired height for the window in any of the forms acceptable to *Tk_GetPixels*. If this option is less than or equal to zero then the window will not request any size at all. Name: *visual* Class: *Visual* Switch: *-visual* Specifies visual information for the new window in any of the forms accepted by *Tk_GetVisual*. If this option is not specified, the new window will use the same visual as its parent. The *visual* option may not be modified with the configure method. Name: width Class: Width Switch: *-width* Specifies the desired width for the window in any of the forms acceptable to *Tk_GetPixels*. If this option is less than or equal to zero then the window will not request any size at all. DESCRIPTION =========== The Frame method creates a new window (given by the $widget argument) and makes it into a frame widget. Additional options, described above, may be specified on the command line or in the option database to configure aspects of the frame such as its background color and relief. The frame command returns the path name of the new window. A frame is a simple widget. Its primary purpose is to act as a spacer or container for complex window layouts. The only features of a frame are its background color and an optional 3-D border to make the frame appear raised or sunken. WIDGET METHODS ============== The Frame 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 frame is created, it has no default event bindings: frames are not intended to be interactive. KEYWORDS ======== frame, widget  File: pm.info, Node: Tk/Getopt, Next: Tk/Ghostscript, Prev: Tk/Frame, Up: Module List User configuration window for Tk with interface to Getopt::Long *************************************************************** NAME ==== Tk::Getopt - User configuration window for Tk with interface to Getopt::Long SYNOPSIS ======== use Tk::Getopt; @opttable = (['opt1', '=s', 'default'], ['opt2', '!', 1], ...); $opt = new Tk::Getopt(-opttable => \@opttable, -options => \%options, -filename => "$ENV{HOME}/.options"); $opt->set_defaults; # set default values $opt->load_options; # configuration file $opt->get_options; # command line $opt->process_options; # process callbacks, check restrictions ... print $options->{'opt1'}, $options->{'opt2'} ...; ... $top = new MainWindow; $opt->option_editor($top); or using a `Getopt::Long|Getopt::Long' in this node-like interface $opt = new Tk::Getopt(-getopt => ['help' => \$HELP, 'file:s' => \$FILE, 'foo!' => \$FOO, 'num:i' => \$NO, ]); or an alternative Getopt::Long interface %optctl = ('foo' => \$foo, 'bar' => \$bar); $opt = new Tk::Getopt(-getopt => [\%optctl, "foo!", "bar=s"]); DESCRIPTION =========== `Tk::Getopt' provides an interface to access command line options via `Getopt::Long|Getopt::Long' in this node and editing with a graphical user interface via a Tk window. Unlike Getopt::Long, this package uses a object oriented interface, so you have to create a new `Tk::Getopt' object with new. Unlike other packages in the Tk hierarchy, this package does not define a Tk widget. The graphical interface is calles by the method *option_editor*. After creating an object with new, you can parse command line options by calling get_options. This method calls itself *Getopt::Long::GetOptions*. METHODS ======= *new Tk::Getopt(**arg_hash*) Constructs a new object of the class `Tk::Getopt'. Arguments are passed in a hash (just like Tk widgets and methods). There are many variants to specify the option description. You can use an interface similar to *Getopt::Long::GetOptions* by using *-getopt* or a more powerful interface by using *-opttable*. Internally, the option description will be converted to the *-opttable* interface. One of the arguments *-getopt* or *-opttable* are mandatory. The arguments for new are: -getopt *-getopt* should be a reference to a hash or an array. This hash has the same format as the argument to the *Getopt::Long::GetOptions* function. Look at *Note Getopt/Long: Getopt/Long, for a detailed description. Note also that not all of GetOptions is implemented, see `"BUGS"' in this node for further information. Example: new Tk::Getopt(-getopt => [\%options, "opt1=i", "opt2=s" ...]); -opttable *-opttable* provides a more powerful interface. The options are stored in variables named *$opt_XXX* or in a hash when *-options* is given (see below). *-opttable* should be a reference to an array containing all options. Elements of this array may be strings, which indicate the beginning of a new group, or array references describing the options. The first element of this array is the name of the option, the second is the type (`=s' for string, `=i' for integer, ! for boolean, `=f' for float etc., see *Note Getopt/Long: Getopt/Long,) for a detailed list. The third element is optional and contains the default value (otherwise the default is undefined). Further elements are optional too and describe more attributes. For a complete list of these attributes refer to `"OPTTABLE ARGUMENTS"' in this node. If an option has no name, then the third element in the description array will be used as an global message for the current option page. This message can be multi-line. Example: [", ", 'This is an explanation for this option group.'] Here is an example for a simple opttable: @opttable = ('First section', ['', '', 'Section description'], ['debug', '!', 0], ['age', '=i', 18], 'Second section', ['', '', 'Description for 2nd section'], ['browser', '=s', 'tkweb'], ['foo', '=f', undef], ); new Tk::Getopt(-opttable => \@opttable, -options => \%options); -options This argument should be a reference to an (empty) hash. Options are set into this hash. If this argument is missing, options will be stored in variables named *$opt_XXX*. -filename This argument is optional and specifies the filename for loading and saving options. -nosafe If set to true, do not use a safe compartment when loading options (see *load_options*). set_defaults Sets default values. This only applies if the *-opttable* variant is used. *load_options(*filename) Loads options from file filename, or, if not specified, from object's filename as specified in new. The loading is done in a safe compartment ensure security.The loaded file should have a reference to a hash named *$loadoptions*. *save_options(*filename) Writes options to file filename, or, if not specified, from object's filename as specified in new. The saving is done with `Data::Dumper|Data::Dumper' in this node. Since saving may fail, you should call this method inside of `eval {}' and check *$@*. Possible exceptions are `No Data::Dumper' (cannot find the Data::Dumper module) and `Writing failed' (cannot write to file). get_options Gets options via GetOptions. Returns the same value as GetOptions, i.e. 0 indicates that the function detected one or more errors. If you want to process options which does not appear in the GUI, you have two alternatives: * Use the *-opttable* variant of the new constructor and mark all non-GUI options with nogui, e.g. new Tk::Getopt(-opttable => ['not-in-gui', '!', undef, nogui => 1], ...) * Use *Getopt::Long::passthrough* and process non-GUI options directly with *Getopt::Long::GetOptions*. The remaining args can be passed to get_options. Example: use Tk::Getopt; use Getopt::Long; $Getopt::Long::passthrough = 1; GetOptions('options!' => \$preloadopt); $Getopt::Long::passthrough = 0; $opt = new Tk::Getopt( ... ); $opt->get_options; usage Generates an usage string from object's opttable. The usage string is constructed from the option name, default value and help entries. *process_options(*[*undo_hash*]) Checks wheather given values are valid (if strict is set) and calls any callbacks specified by the sub option. If *undo_hash* is given and the new value of an option did not change, no sub is called. *option_editor(*widget, [*arguments ...*]) Pops the option editor up. The editor provides facilitied for editing options, undoing, restoring to their default valued and saving to the default options file. The first argument is the parent widget. Further optional arguments are passed as a hash: -callback Execute additional callback after creating the option editor. Arguments passed to this callback are: reference to the `Tk::Getopt' object and a reference to the option editor window. -nosave Disable saving of options. -buttons Specify, which buttons should be drawn. It is advisable to draw at least the OK and Cancel buttons. The default set looks like this: -buttons => [qw/ok apply cancel undo lastsaved save defaults/] -toplevel Use another widget class instead of Toplevel for embedding the option editor, e.g. Frame to embed the editor into another toplevel widget (do not forget to pack the frame!). See also the `-pack' option below. -pack If using `-toplevel' with a non-Toplevel widget (e.g. Frame) and using the `-wait' option, then packing have to be done through the `-pack' option. The argument to this option is a array reference of pack options, e.g. $opt->option_editor(-toplevel => "Frame", -wait => 1, -pack => [-fill => "both", -expand => 1]); -statusbar Use an additional status bar for help messages. -string Change button labels and title. This argument should be a hash reference with following keys: `optedit', undo, `lastsaved', save, defaults, ok, `cancel', `helpfor'. -wait Do not return immediately, but rather wait for the user pressing OK or Cancel. Since the option editor uses the `NoteBook' widget, options may be grouped in several pages. Grouping is only possible if using the `-opttable' variant of new. Help messages are shown in balloons and, if specified, in a statusbar. *option_editor* returns a reference to the created window. Note: this method returns immediately to the calling program. Buttons in the option editor window: OK Accept options and close option editor window. Cancel Set old values and close option editor window. Undo Set old values. Further selections toggle between new and old values. Last saved Set last saved options. This button is not displayed if no filename was given in new. Save Save options to file. This button is not displayed if no filename was given in new. The option types are translated to following widgets: Boolean Checkbutton (*_boolean_widget*) Integer and Float Scale, if range is set, otherwise either *BrowseEntry* or Entry (*_integer_widget*, *_float_widget*). String *BrowseEntry* if choices is set, otherwise entry (*_string_widget*). *FileDialog* if subtype is set to file. OPTTABLE ARGUMENTS ================== Additional attributes in an option description have to be key-value pairs with following keys: alias An array of aliases also accepted by Getopt::Long. label A label to be displayed in the GUI instead of the option name. help A short help string used by usage and the Balloon help facility in *option_editor*. longhelp A long help string used by *option_editor*. choices An array of additional choices for the option editor. range An array with the beginning and end of a range for an integer or float value. strict Must be used with choices or range. When set to true, options have to match either the choices or the range. subtype The only permitted subtypes are file and dir to be used with string options. The GUI interface will pop up a file dialog for this option (either for selecting files or directories). var Use variable instead of *$options->{optname}* or *$opt_optname* to store the value. nogui This option will not have an entry in the GUI. widget This should be a reference to a subroutine for creating an own widget. Folowing arguments will be passed to this subroutine: a reference to the `Tk::Getopt' object, Frame object, options entry. The subroutine should create a widget in the frame (packing is not necessary!) and should return a reference to the created widget. Here is an example for using a complex opttable description: @opttable = ('Misc', # Head of first group ['debug', # name of the option (--debug) '!', # type boolean, accept --nodebug 0, # default is 0 (false) callback => sub { $^W = 1 if $options->{'debug'}; } # additional attribute: callback to be called if # you set or change the value ], ['age', '=i', # option accepts integer value 18, strict => 1, # value must be in range range => [0, 100], # allowed range alias => ['year', 'years'] # possible aliases ], 'External', # Head of second group ['browser', '=s', # option accepts string value 'tkweb', choices => ['mosaic', 'netscape', 'lynx', 'chimera'], # choices for the list widget in the GUI label => 'WWW browser program' # label for the GUI instead of 'browser' ], ['foo', '=f', # option accepts float value undef, # no default value help => 'This is a short help', # help string for usage() and the help balloon longhelp => 'And this is a slightly longer help' # longer help displayed in the GUI's help window ]); REQUIREMENTS ============ You need at least: * perl5.004 (perl5.003 near 5.004 may work too, e.g perl5.003_26) * Tk400.202 (better: Tk800.007) (only if you want the GUI) * Data-Dumper-2.07 (only if you want to save options and it's anyway standard in perl5.005) BUGS ==== Be sure to pass a real hash reference (not a uninitialized reference) to the -options switch in `new Tk::Getopt'. Use either: my %options; my $opt = new Tk::Getopt(-options => \%options ...) or my $options = {}; my $opt = new Tk::Getopt(-options => $options ...) Note the initial assignement for $options in the second example. Not all of Getopt::Long is supported (array and hash options, <>, abbrevs). The option editor probably should be a real widget. The option editor window may grow very large if NoteBook is not used (should use a scrollable pane). If the user resizes the window, the buttons at bottom may disappear. This is confusing and it is advisable to disallow the resizing: $opt_editor = $opt->option_editor; $opt_editor->resizable(0,0); The API will not be stable until version 1.00. This manual is confusing. In fact, the whole module is confusing. Setting variables in the editor should not set immediately the real variables. This should be done only by Apply and Ok buttons. AUTHOR ====== Slaven Rezic This package is free software; you can redistribute it and/or modify it under the same terms as Perl itself. SEE ALSO ======== `perl|perl' in this node `Getopt::Long|Getopt::Long' in this node `Data::Dumper|Data::Dumper' in this node `Tk|Tk' in this node `Tk::FileDialog|Tk::FileDialog' in this node `Tk::NoteBook|Tk::NoteBook' in this node `Tk::Tiler|Tk::Tiler' in this node `Safe|Safe' in this node  File: pm.info, Node: Tk/Ghostscript, Next: Tk/HList, Prev: Tk/Getopt, Up: Module List Beginings of a lowlevel PostScript viewing widget ************************************************* NAME ==== Ghostscript - Beginings of a lowlevel PostScript viewing widget SYNOPSIS ======== my $gs= $parent->Ghostscript( 'x_pixels_per_inch' => $scale, 'y_pixels_per_inch' => $scale, 'BoundingBox' => [ 0,0, $width, $height] ); $gs->Postscript("...."); DESCRIPTION =========== Tested with gs3 via `pgs' and `Ghostview.pm'. Aim is to have both GS and "Display Postscript" widgets which present same interface to higher level document viewers.  File: pm.info, Node: Tk/HList, Next: Tk/HTML/IO, Prev: Tk/Ghostscript, Up: Module List Create and manipulate Tix Hierarchial List widgets ************************************************** NAME ==== Tk::HList - Create and manipulate Tix Hierarchial List widgets *$hlist* = *$parent*->*HList*(?options?); STANDARD OPTIONS ================ *-background* *-borderwidth* *-cursor* *-exportselection* *-foreground* *-font* *-height* *-highlightcolor* *-highlightthickness* *-relief* *-selectbackground* *-selectforeground* *-xscrollcommand* *-yscrollcommand* *-width* See *Note Tk/options: Tk/options, for details of the standard options. WIDGET-SPECIFIC OPTIONS ======================= Name: *browsecmd* Class: *BrowseCmd* Switch: *-browsecmd* Specifies a perl/Tk `callback|Tk::callbacks' in this node to be executed when the user browses through the entries in the HList widget. Name: columns Class: Columns Switch: *-columns* Specifies the number of columns in this HList widget. This option can only be set during the creation of the HList widget and cannot be changed subsequently. Name: command Class: Command Switch: *-command* Specifies the perl/Tk `callback|Tk::callbacks' in this node to be executed when the user invokes a list entry in the HList widget. Normally the user invokes a list entry by double-clicking it or pressing the Return key. Name: *drawBranch* Class: *DrawBranch* Switch: *-drawbranch* A Boolean value to specify whether branch line should be drawn to connect list entries to their parents. Name: *foreground* Class: *Foreground* Switch: *-foreground* Alias: *-fg* *[OBSOLETE]* Specifies the default foreground color for the list entries. Name: gap Class: *Gap* Switch: *-gap* *[OBSOLETE]* The default distance between the bitmap/image and the text in list entries. Name: header Class: Header Switch: *-header* A Boolean value specifying whether headers should be displayed for this HList widget (see the header method below). Name: height Class: *Height* Switch: *-height* Specifies the desired height for the window in number of characters. Name: indent Class: *Indent* Switch: *-indent* Specifies the amount of horizontal indentation between a list entry and its children. Must be a valid screen distance value. Name: *indicator* Class: *Indicator* Switch: *-indicator* Specifies whether the indicators should be displayed inside the HList widget. See the *indicator* method below. Name: *indicatorCmd* Class: *IndicatorCmd* Switch: *-indicatorcmd* Specifies a perl/Tk `callback|Tk::callbacks' in this node to be executed when the user manipulates the indicator of an HList entry. The *-indicatorcmd* is triggered when the user press or releases the mouse button over the indicator in an HList entry. By default the perl/Tk callback specified by *-indicatorcmd* is executed with two additional arguments, the entryPath of the entry whose indicator has been triggered and additional information about the event. The additional information is one of the following strings: **, **, and **. Name: *itemType* Class: *ItemType* Switch: *-itemtype* Specifies the default type of display item for this HList widget. When you call the *itemCreate*, add and *addchild* methods, display items of this type will be created if the *-itemtype* option is not specified . Name: *padX* Class: *Pad* Switch: *-padx* *[OBSOLETE]* The default horizontal padding for list entries. Name: *padY* Class: *Pad* Switch: *-padx* *[OBSOLETE]* The default vertical padding for list entries. Name: *selectBackground* Class: *SelectBackground* Switch: *-selectbackground* Specifies the background color for the selected list entries. Name: *selectBorderWidth* Class: *BorderWidth* Switch: *-selectborderwidth* Specifies a non-negative value indicating the width of the 3-D border to draw around selected items. The value may have any of the forms acceptable to *Tk_GetPixels*. Name: *selectForeground* Class: *SelectForeground* Switch: *-selectforeground* Specifies the foreground color for the selected list entries. Name: *selectMode* Class: *SelectMode* Switch: *-selectmode* Specifies one of several styles for manipulating the selection. The value of the option may be arbitrary, but the default bindings expect it to be either single, browse, multiple, or *extended*; the default value is single. Name: *sizeCmd* Class: *SizeCmd* Switch: *-sizecmd* Specifies a perl/Tk `callback|Tk::callbacks' in this node to be called whenever the HList widget changes its size. This method can be useful to implement "*user scroll bars when needed*" features. Name: separator Class: Separator Switch: *-separator* Specifies the character to used as the separator character when intepreting the path-names of list entries. By default the character "." is used. Name: width Class: Width Switch: *-width* Specifies the desired width for the window in characters. DESCRIPTION =========== The *HList* method creates a new window (given by the $widget argument) and makes it into a HList widget. Additional options, described above, may be specified on the command line or in the option database to configure aspects of the HList widget such as its cursor and relief. The HList widget can be used to display any data that have a hierarchical structure, for example, file system directory trees. The list entries are indented and connected by branch lines according to their places in the hierachy. Each list entry is identified by an *entryPath*. The entryPath is a sequence of *entry names* separated by the separator charactor (specified by the *-separator* option). An *entry name* can be any string that does not contain the separator charactor, or it can be the a string that contains only one separator charactor. For example, when "." is used as the separator charactor, "one.two.three" is the entryPath for a list entry whose parent is "one.two", whose parent is "one", which is a toplevel entry (has no parents). Another examples: ".two.three" is the entryPath for a list entry whose parent is ".two", whose parent is ".", which is a toplevel entry. DISPLAY ITEMS ============= Each list entry in an HList widget is associated with a display item. The display item determines what visual information should be displayed for this list entry. Please see *Note Tk/DItem: Tk/DItem, for a list of all display items. When a list entry is created by the *itemCreate*, add or *addchild* widget methods, the type of its display item is determined by the *-itemtype* option passed to these methods. If the *-itemtype* is omitted, then by default the type specified by this HList widget's *-itemtype* option is used. WIDGET METHODS ============== The *HList* 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 HList widgets: *$hlist*->add(*$entryPath* ?,option=>value, ...?) Creates a new list entry with the pathname *$entryPath*. A list entry must be created after its parent is created (unless this entry is a top-level entry, which has no parent). See also `"BUGS"' in this node below. This method returns the entryPath of the newly created list entry. The following configuration options can be given to configure the list entry: *-at* => position Insert the new list at the position given by position. position must be a valid integer. The position 0 indicates the first position, 1 indicates the second position, and so on. *-after* => *afterWhich* Insert the new list entry after the entry identified by *afterWhich*. *afterWhich* must be a valid list entry and it mush have the same parent as the new list entry *-before* => *beforeWhich* Insert the new list entry before the entry identified by *beforeWhich*. *beforeWhich* must be a valid list entry and it mush have the same parent as the new list entry *-data* => string Specifies a string to associate with this list entry. This string can be queried by the info method. The application programmer can use the *-data* option to associate the list entry with the data it represents. *-itemtype* => type Specifies the type of display item to be display for the new list entry. type must be a valid display item type. Currently the available display item types are *imagetext*, text, and $widget. If this option is not specified, then by default the type specified by this HList widget's *-itemtype* option is used. *-state* => state Specifies whether this entry can be selected or invoked by the user. Must be either normal or disabled. The add method accepts additional configuration options to configure the display item associated with this list entry. The set of additional configuration options depends on the type of the display item given by the *-itemtype* option. Please see *Note Tk/DItem: Tk/DItem, for a list of the configuration options for each of the display item types. *$hlist*->*addchild*(*$parentPath, *?*option, value, ..., *?) Adds a new child entry to the children list of the list entry identified by *$parentPath*. Or, if *$parentPath* is set to be the empty string, then creates a new toplevel entry. The name of the new list entry will be a unique name automatically generated by the HList widget. Usually if *$parentPath* is foo, then the entryPath of the new entry will be *foo.0*, *foo.1*, ... etc. This method returns the entryPath of the newly created list entry. option can be any option for the add method. See also `"BUGS"' in this node below. *$hlist*->*anchorSet*(*$entryPath*) Sets the anchor to the list entry identified by *$entryPath*. The anchor is the end of the selection that is fixed while the user is dragging out a selection with the mouse. *$hlist*->*anchorClear* Removes the anchor, if any, from this HList widget. This only removes the surrounding highlights of the anchor entry and does not affect its selection status. *$hlist*->*columnWidth*(*$col*?, *-char*?, ?width?) Querys or sets the width of a the column *$col* in the HList widget. The value of *$col* is zero-based: 0 stands for the first column, 1 stands for the second, and so on. If no further parameters are given, returns the current width of this column (in number of pixels). Additional parameters can be given to set the width of this column: *$hlist*->*columnWidth*(*$col*, ") An empty string indicates that the width of the column should be just wide enough to display the widest element in this column. In this case, the width of this column may change as a result of the elements in this column changing their sizes. *$hlist*->*columnWidth*(*$col, *width) width must be in a form accepted by *Tk_GetPixels*. *$hlist*->*columnWidth*(*$col, **-char, **nChars*) The width is set to be the average width occupied by *nChars* number of characters of the font specified by the *-font* option of this HList widget. *$hlist*->delete(option, *$entryPath*) Delete one or more list entries. option may be one of the following: all Delete all entries in the HList. In this case the *$entryPath* does not need to be specified. entry Delete the entry specified by *$entryPath* and all its offsprings, if any. offsprings Delete all the offsprings, if any, of the entry specified by *$entryPath*. However, *$entryPath* itself is not deleted. siblings Delete all the list entries that share the same parent with the entry specified by *$entryPath*. However, *$entryPath* itself is not deleted. *$hlist*->*dragsiteSet*(*$entryPath*) Sets the dragsite to the list entry identified by *$entryPath*. The dragsite is used to indicate the source of a drag-and-drop action. Currently drag-and-drop functionality has not been implemented in Tix yet. *$hlist*->*dragsiteClear* Remove the dragsite, if any, from the this HList widget. This only removes the surrounding highlights of the dragsite entry and does not affect its selection status. *$hlist*->*dropsiteSet*(*$entryPath*) Sets the dropsite to the list entry identified by *$entryPath*. The dropsite is used to indicate the target of a drag-and-drop action. Currently drag-and-drop functionality has not been implemented in Tix yet. *$hlist*->*dropsiteClear* Remove the dropsite, if any, from the this HList widget. This only removes the surrounding highlights of the dropsite entry and does not affect its selection status. *$hlist*->*entrycget*(*$entryPath*, option) Returns the current value of the configuration option given by option for the entry indentfied by *$entryPath*. Option may have any of the values accepted by the add method. *$hlist*->*entryconfigure*(*$entryPath* ?,option?, ?value=>option, ...?) Query or modify the configuration options of the list entry indentfied by *$entryPath*. If no option is specified, returns a list describing all of the available options for *$entryPath* (see *Note Tk/options: Tk/options, for information on the format of this list.) If option is specified with no value, then the method returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no option is specified). If one or more *option-value* pairs are specified, then the method modifies the given option(s) to have the given value(s); in this case the method returns an empty string. Option may have any of the values accepted by the add or *addchild* method. The exact set of options depends on the value of the *-itemtype* option passed to the the add or *addchild* method when this list entry is created. *$hlist*->header(option, *$col* ?,args, ...?) Manipulates the header items of this HList widget. If the *-header* option of this HList widget is set to true, then a header item is displayed at the top of each column. The *$col* argument for this method must be a valid integer. 0 indicates the first column, 1 the second column, ... and so on. This method supports the following options: *$hlist*->header(cget, *$col*, option) If the *$col*-th column has a header display item, returns the value of the specified option of the header item. If the header doesn't exist, returns an error. *$hlist*->header(*configure, **$col, *?option?, *?value, option, value, ...*?) Query or modify the configuration options of the header display item of the *$col*-th column. The header item must exist, or an error will result. If no option is specified, returns a list describing all of the available options for the header display item (see *Note Tk/options: Tk/options, for information on the format of this list.) If option is specified with no value, then the method returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no option is specified). If one or more *option-value* pairs are specified, then the method modifies the given option(s) to have the given value(s); in this case the method returns an empty string. Option may have any of the values accepted by the *header create* method. The exact set of options depends on the value of the *-itemtype* option passed to the the header create method when this display item was created. *$hlist*->header(*create, **$col, *?*-itemtype type*? ?*option value ...*? Creates a new display item as the header for the *$col*-th column. See also `"BUGS"' in this node below. If an header display item already exists for this column, it will be replaced by the new item. An optional parameter *-itemtype* can be used to specify what type of display item should be created. If the *-itemtype* is not given, then by default the type specified by this HList widget's *-itemtype* option is used. Additional parameters, in *option-value* pairs, can be passed to configure the appearance of the display item. Each *option-value* pair must be a valid option for this type of display item or one of the following: *-borderwidth* => color Specifies the border width of this header item. *-headerbackground* => color Specifies the background color of this header item. *-relief* => type Specifies the relief type of the border of this header item. *$hlist*->header(*delete, **$col*) Deletes the header display item for the *$col*-th column. *$hlist*->header(*exists, **$col*) Return true if an header display item exists for the *$col*-th column; return false otherwise. *$hlist*->header(size, *$entryPath*) If an header display item exists for the *$col*-th column , returns its size in pixels in a two element list *(width, height)*; returns an error if the header display item does not exist. *$hlist*->hide(option ?,*$entryPath*?) Makes some of entries invisible without deleting them. Option can be one of the following: entry Hides the list entry identified by *$entryPath*. Currently only the entry option is supported. Other options will be added in the next release. *$hlist*->*indicator*(option, *$entryPath*, ?*args, ...*?) Manipulates the indicator on the list entries. An indicator is usually a small display item (such as an image) that is displayed to the left to an entry to indicate the status of the entry. For example, it may be used to indicate whether a directory is opened or closed. Option can be one of the following: *$hlist*->*indicator*(cget, *$entryPath*, option) If the list entry given by *$entryPath* has an indicator, returns the value of the specified option of the indicator. If the indicator doesn't exist, returns an error. *$hlist*->*indicator*(configure, *$entryPath*, ?option?, *?value, option, value, ...*?) Query or modify the configuration options of the indicator display item of the entry specified by *$entryPath*. The indicator item must exist, or an error will result. If no option is specified, returns a list describing all of the available options for the indicator display item (see *Note Tk/options: Tk/options, for information on the format of this list). If option is specified with no value, then the method returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no option is specified). If one or more *option-value* pairs are specified, then the method modifies the given option(s) to have the given value(s); in this case the method returns an empty string. Option may have any of the values accepted by the *indicator create* method. The exact set of options depends on the value of the *-itemtype* option passed to the the *indicator create* method when this display item was created. *$hlist*->*indicator*(*create, **$entryPath, *?, *-itemtype type*? ?*option value ...*?) Creates a new display item as the indicator for the entry specified by *$entryPath*. If an indicator display item already exists for this entry, it will be replaced by the new item. An optional parameter *-itemtype* can be used to specify what type of display item should be created. If the *-itemtype* is not given, then by default the type specified by this HList widget's *-itemtype* option is used. Additional parameters, in *option-value* pairs, can be passed to configure the appearance of the display item. Each *option-value* pair must be a valid option for this type of display item. *$hlist*->*indicator*(delete, *$entryPath*) Deletes the indicator display item for the entry given by *$entryPath*. *$hlist*->*indicator*(exists, *$entryPath*) Return true if an indicator display item exists for the entry given by *$entryPath*; return false otherwise. *$hlist*->*indicator*(size, *$entryPath*) If an indicator display item exists for the entry given by *$entryPath*, returns its size in a two element list of the form {*width height*}; returns an error if the indicator display item does not exist. *$hlist*->info(option, *arg, ...*) Query information about the HList widget. option can be one of the following: *$hlist*->info(anchor) Returns the entryPath of the current anchor, if any, of the HList widget. If the anchor is not set, returns the empty string. *$hlist*->*infoBbox*(*$entryPath*) Returns a list of four numbers describing the visible bounding box of the entry given *$entryPath*. 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 entry (specified in pixels relative to the widget) and the last two elements give the lower-right corner of the area, in pixels. If no part of the entry given by index is visible on the screen then the result is an empty string; if the entry is partially visible, the result gives the only the visible area of the entry. *$hlist*->info(children ?,*$entryPath*?) If *$entryPath* is given, returns a list of the entryPath's of its children entries. Otherwise returns a list of the toplevel entryPath's. *$hlist*->info(data ?,*$entryPath*?) Returns the data associated with *$entryPath*. *$hlist*->info(*dragsite*) Returns the entryPath of the current dragsite, if any, of the HList widget. If the dragsite is not set, returns the empty string. *$hlist*->info(*dropsite*) Returns the entryPath of the current dropsite, if any, of the HList widget. If the dropsite is not set, returns the empty string. *$hlist*->info(exists, *$entryPath*) Returns a boolean value indicating whether the list entry *$entryPath* exists. *$hlist*->info(hidden, *$entryPath*) Returns a boolean value indicating whether the list entry *$entryPath* is hidden or not. *$hlist*->info(next, *$entryPath*) Returns the entryPath of the list entry, if any, immediately below this list entry. If this entry is already at the bottom of the HList widget, returns an empty string. *$hlist*->info(parent, *$entryPath*) Returns the name of the parent of the list entry identified by *$entryPath*. If *entryPath* is a toplevel list entry, returns the empty string. *$hlist*->info(prev, *$entryPath*) Returns the entryPath of the list entry, if any, immediately above this list entry. If this entry is already at the top of the HList widget, returns an empty string. *$hlist*->info(selection) Returns a list of selected entries in the HList widget. If no entries are selected, returns an empty string. *$hlist*->item(*option, *?*args, ...*?) Creates and configures the display items at individual columns the entries. The form of additional of arguments depends on the choice of option: *$hlist*->*itemCget*(*$entryPath*, *$col*, option) Returns the current value of the configure option of the display item at the column designated by *$col* of the entry specified by *$entryPath*. *$hlist*->*itemConfigure*(*$entryPath*, *$col* ?,option?, *?value, option, value, ...*?) Query or modify the configuration options of the display item at the column designated by *$col* of the entry specified by *$entryPath*. If no option is specified, returns a list describing all of the available options for *$entryPath* (see *Note Tk/options: Tk/options, for information on the format of this list). If option is specified with no value, then the method returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no option is specified). If one or more *option-value* pairs are specified, then the method modifies the given option(s) to have the given value(s); in this case the method returns an empty string. Option may have any of the values accepted by the item create method. The exact set of options depends on the value of the *-itemtype* option passed to the the item create method when this display item was created. *$hlist*->*itemCreate*(*$entryPath*, *$col* ?,*-itemtype*=>type? ?,*option value ...*?) Creates a new display item at the column designated by *$col* of the entry specified by *$entryPath*. An optional parameter *-itemtype* can be used to specify what type of display items should be created. If the *-itemtype* is not specified, then by default the type specified by this HList widget's *-itemtype* option is used. Additional parameters, in *option-value* pairs, can be passed to configure the appearance of the display item. Each *option- value* pair must be a valid option for this type of display item. *$hlist*->*itemDelete*(*$entryPath*, *$col*) Deletes the display item at the column designated by *$col* of the entry specified by *$entryPath*. *$hlist*->*itemExists*(*$entryPath*, *$col*) Returns true if there is a display item at the column designated by *$col* of the entry specified by *$entryPath*; returns false otherwise. *$hlist*->nearest(y) *$hlist*->nearest(y) Given a y-coordinate within the HList window, this method returns the entryPath of the (visible) HList element nearest to that y-coordinate. *$hlist*->see(*$entryPath*) Adjust the view in the HList so that the entry given by *$entryPath* is visible. If the entry is already visible then the method has no effect; if the entry is near one edge of the window then the HList scrolls to bring the element into view at the edge; otherwise the HList widget scrolls to center the entry. *$hlist*->selection(option, *arg*, ...) *$hlist*->selectionOption(*arg*, ...) This method is used to adjust the selection within a HList widget. It has several forms, depending on option: *$hlist*->*selectionClear*(?from?, ?to?) When no extra arguments are given, deselects all of the list entrie(s) in this HList widget. When only from is given, only the list entry identified by from is deselected. When both from and to are given, deselects all of the list entrie(s) between between from and to, inclusive, without affecting the selection state of elements outside that range. *$hlist*->*selectionGet* This is an alias for the *infoSelection* method. *$hlist*->*selectionIncludes*(*$entryPath*) Returns 1 if the list entry indicated by *$entryPath* is currently selected; returns 0 otherwise. *$hlist*->*selectionSet*(from?, to?) Selects all of the list entrie(s) between between from and to, inclusive, without affecting the selection state of entries outside that range. When only from is given, only the list entry identified by from is selected. *$hlist*->show(option ?,*$entryPath*?) Show the entries that are hidden by the hide method, option can be one of the following: entry Shows the list entry identified by *$entryPath*. Currently only the entry option is supported. Other options will be added in future releases. *$hlist*->*xview*(args) This method 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: *$hlist*->*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 HList entry is off-screen to the left, the middle 40% is visible in the window, and 40% of the entry is off-screen to the right. These are the same values passed to scrollbars via the *-xscrollcommand* option. *$hlist*->*xview*(*$entryPath*) Adjusts the view in the window so that the list entry identified by *$entryPath* is aligned to the left edge of the window. *$hlist*->*xview*(*moveto* => *fraction*) Adjusts the view in the window so that *fraction* of the total width of the HList is off-screen to the left. *fraction* must be a fraction between 0 and 1. *$hlist*->*xview*(scroll => *number, what*) This method 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. *$hlist*->*yview*(*?args*?) This method is used to query and change the vertical position of the entries in the widget's window. It can take any of the following forms: *$hlist*->*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 list element at the top of the window, relative to the HList as a whole (0.5 means it is halfway through the HList, for example). The second element gives the position of the list entry just after the last one in the window, relative to the HList as a whole. These are the same values passed to scrollbars via the *-yscrollcommand* option. *$hlist*->*yview*(*$entryPath*) Adjusts the view in the window so that the list entry given by *$entryPath* is displayed at the top of the window. *$hlist*->*yview*(*moveto* => *fraction*) Adjusts the view in the window so that the list entry given by *fraction* appears at the top of the window. *Fraction* is a fraction between 0 and 1; 0 indicates the first entry in the HList, 0.33 indicates the entry one-third the way through the HList, and so on. *$hlist*->*yview*(scroll => *number, what*) This method adjust 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 entries become visible; if it is positive then later entries become visible. BINDINGS ======== [1] If the *-selectmode* is "browse", when the user drags the mouse pointer over the list entries, the entry under the pointer will be highlighted and the *-browsecmd* callback will be called with one parameter, the entryPath of the highlighted entry. Only one entry can be highlighted at a time. The *-command* callback will be called when the user double-clicks on a list entry. [2] If the *-selectmode* is "single", the entries will only be highlighted by mouse events. When a new list entry is highlighted, the *-browsecmd* callback will be called with one parameter indicating the highlighted list entry. The *-command* callback will be called when the user double-clicks on a list entry. [3] If the *-selectmode* is "multiple", when the user drags the mouse pointer over the list entries, all the entries under the pointer will be highlighted. However, only a contiguous region of list entries can be selected. When the highlighted area is changed, the *-browsecmd* callback will be called with an undefined parameter. It is the responsibility of the *-browsecmd* callback to find out the exact highlighted selection in the HList. The *-command* callback will be called when the user double-clicks on a list entry. [4] If the *-selectmode* is "extended", when the user drags the mouse pointer over the list entries, all the entries under the pointer will be highlighted. The user can also make disjointed selections using . When the highlighted area is changed, the *-browsecmd* callback will be called with an undefined parameter. It is the responsibility of the *-browsecmd* callback to find out the exact highlighted selection in the HList. The *-command* callback will be called when the user double-clicks on a list entry. [5] *Arrow key bindings:* arrow key moves the anchor point to the item right on top of the current anchor item. arrow key moves the anchor point to the item right below the current anchor item. arrow key moves the anchor to the parent item of the current anchor item. moves the anchor to the first child of the current anchor item. If the current anchor item does not have any children, moves the anchor to the item right below the current anchor item. EXAMPLE ======= This example demonstrates how to use an HList to store a file directory structure and respond to the user's browse events: use strict; use Tk; use Tk::Label; use Tk::HList; my $mw = MainWindow->new(); my $label = $mw->Label(-width=>15); my $hlist = $mw->HList( -itemtype => 'text', -separator => '/', -selectmode => 'single', -browsecmd => sub { my $file = shift; $label->configure(-text=>$file); } ); foreach ( qw(/ /home /home/ioi /home/foo /usr /usr/lib) ) { $hlist->add($_, -text=>$_); } $hlist->pack; $label->pack; MainLoop; BUGS ==== The fact that the display item at column 0 is implicitly associated with the whole entry is probably a design bug. This was done for backward compatibility purposes. The result is that there is a large overlap between the item method and the add, *addchild*, *entrycget* and *entryconfigure* methods. Whenever multiple columns exist, the programmer should use ONLY the item method to create and configure the display items in each column; the add, *addchild*, *entrycget* and *entryconfigure* should be used ONLY to create and configure entries. KEYWORDS ======== Hierarchical Listbox SEE ALSO ======== `Tk::DItem|Tk::DItem' in this node