This is Info file pm.info, produced by Makeinfo version 1.68 from the input file bigpm.texi.  File: pm.info, Node: Tk/CheckBox, Next: Tk/Checkbutton, Prev: Tk/Canvas, Up: Module List Another radio button style widget (with a check mark) ***************************************************** NAME ==== Tk::CheckBox - Another radio button style widget (with a check mark) SYNOPSIS ======== use Tk; my $MainWindow = MainWindow->new(); Tk::MainLoop; DESCRIPTION =========== A radio button style widget that uses a check mark in a box. Useful as a boolean field. AUTHORS ======= Damion K. Wilson, dkw@rcm.bm HISTORY =cut ===============  File: pm.info, Node: Tk/Checkbutton, Next: Tk/Clipboard, Prev: Tk/CheckBox, Up: Module List Create and manipulate Checkbutton widgets ***************************************** NAME ==== Tk::Checkbutton - Create and manipulate Checkbutton widgets *$checkbutton* = *$parent*->Checkbutton(?options?); STANDARD OPTIONS ================ *-activebackground* *-cursor* *-highlightthickness* *-takefocus* *-activeforeground* *-disabledforeground* *-image* *-text* *-anchor* *-font* -justify *-textvariable* *-background* *-foreground* *-padx* *-underline* *-bitmap* *-highlightbackground* *-pady* *-wraplength* *-borderwidth* *-highlightcolor* *-relief* See *Note Tk/options: Tk/options, for details of the standard options. WIDGET-SPECIFIC OPTIONS ======================= Name: command Class: Command Switch: *-command* Specifies a `Tk callback|Tk::callbacks', *Note Perl: (perl.info)perl, to associate with the button. This command is typically invoked when mouse button 1 is released over the button window. The button's global variable (*-variable* option) will be updated before the command is invoked. Name: height Class: *Height* Switch: *-height* Specifies a desired height for the button. If an image or bitmap is being displayed in the button 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 button's desired height is computed from the size of the image or bitmap or text being displayed in it. Name: *indicatorOn* Class: *IndicatorOn* Switch: *-indicatoron* Specifies whether or not the indicator should be drawn. Must be a proper boolean value. If false, the *relief* option is ignored and the widget's relief is always sunken if the widget is selected and raised otherwise. Name: *offValue* Class: Value Switch: *-offvalue* Specifies value to store in the button's associated variable whenever this button is deselected. Defaults to "0". Name: *onValue* Class: Value Switch: *-onvalue* Specifies value to store in the button's associated variable whenever this button is selected. Defaults to "1". Name: *selectColor* Class: Background Switch: *-selectcolor* Specifies a background color to use when the button is selected. If *indicatorOn* is true then the color applies to the indicator. Under Windows, this color is used as the background for the indicator regardless of the select state. If *indicatorOn* is false, this color is used as the background for the entire widget, in place of background or *activeBackground*, whenever the widget is selected. If specified as an empty string then no special color is used for displaying when the widget is selected. Name: *selectImage* Class: *SelectImage* Switch: *-selectimage* Specifies an image to display (in place of the image option) when the checkbutton is selected. This option is ignored unless the image option has been specified. Name: state Class: State Switch: *-state* Specifies one of three states for the checkbutton: normal, active, or disabled. In normal state the checkbutton is displayed using the *foreground* and background options. The active state is typically used when the pointer is over the checkbutton. In active state the checkbutton is displayed using the *activeForeground* and *activeBackground* options. Disabled state means that the checkbutton should be insensitive: the default bindings will refuse to activate the widget and will ignore mouse button presses. In this state the *disabledForeground* and background options determine how the checkbutton is displayed. Name: variable Class: Variable Switch: *-variable* Specifies reference to a variable to set to indicate whether or not this button is selected. Defaults to `\$widget->{'Value'}' member of the widget's hash. In general perl variables are undef unless specifically initialized which will not match either default *-onvalue* or default *-offvalue*. Name: width Class: Width Switch: *-width* Specifies a desired width for the button. If an image or bitmap is being displayed in the button 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 button's desired width is computed from the size of the image or bitmap or text being displayed in it. DESCRIPTION =========== The Checkbutton method creates a new window (given by the $widget argument) and makes it into a checkbutton widget. Additional options, described above, may be specified on the command line or in the option database to configure aspects of the checkbutton such as its colors, font, text, and initial relief. The *checkbutton* 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 checkbutton is a widget that displays a textual string, bitmap or image and a square called an *indicator*. 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. A checkbutton has all of the behavior of a simple button, including the following: it can display itself in either of three different ways, according to the state option; it can be made to appear raised, sunken, or flat; it can be made to flash; and it invokes a `Tk callback|Tk::callbacks', *Note Perl: (perl.info)perl, whenever mouse button 1 is clicked over the checkbutton. In addition, checkbuttons can be *selected*. If a checkbutton is selected then the indicator is normally drawn with a selected appearance, and a Tcl variable associated with the checkbutton is set to a particular value (normally 1). Under Unix, the indicator is drawn with a sunken relief and a special color. Under Windows, the indicator is drawn with a check mark inside. If the checkbutton is not selected, then the indicator is drawn with a deselected appearance, and the associated variable is set to a different value (typically 0). Under Unix, the indicator is drawn with a raised relief and no special color. Under Windows, the indicator is drawn without a check mark inside. By default, the name of the variable associated with a checkbutton is the same as the name used to create the checkbutton. The variable name, and the "on" and "off" values stored in it, may be modified with options on the command line or in the option database. Configuration options may also be used to modify the way the indicator is displayed (or whether it is displayed at all). By default a checkbutton is configured to select and deselect itself on alternate button clicks. In addition, each checkbutton monitors its associated variable and automatically selects and deselects itself when the variables value changes to and from the button's "on" value. WIDGET METHODS ============== The Checkbutton 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 checkbutton widgets: *$checkbutton*->*deselect* Deselects the checkbutton and sets the associated variable to its "off" value. *$checkbutton*->flash Flashes the checkbutton. This is accomplished by redisplaying the checkbutton several times, alternating between active and normal colors. At the end of the flash the checkbutton is left in the same normal/active state as when the command was invoked. This command is ignored if the checkbutton's state is disabled. *$checkbutton*->*invoke* Does just what would have happened if the user invoked the checkbutton with the mouse: toggle the selection state of the button and invoke the `Tk callback|Tk::callbacks', *Note Perl: (perl.info)perl, associated with the checkbutton, if there is one. The return value is the return value from the `Tk callback|Tk::callbacks', *Note Perl: (perl.info)perl,, or an empty string if there is no command associated with the checkbutton. This command is ignored if the checkbutton's state is disabled. *$checkbutton*->select Selects the checkbutton and sets the associated variable to its "on" value. *$checkbutton*->toggle Toggles the selection state of the button, redisplaying it and modifying its associated variable to reflect the new state. BINDINGS ======== Tk automatically creates class bindings for checkbuttons that give them the following default behavior: [1] On Unix systems, a checkbutton activates whenever the mouse passes over it and deactivates whenever the mouse leaves the checkbutton. On Mac and Windows systems, when mouse button 1 is pressed over a checkbutton, the button activates whenever the mouse pointer is inside the button, and deactivates whenever the mouse pointer leaves the button. [2] When mouse button 1 is pressed over a checkbutton, it is invoked (its selection state toggles and the command associated with the button is invoked, if there is one). [3] When a checkbutton has the input focus, the space key causes the checkbutton to be invoked. Under Windows, there are additional key bindings; plus (+) and equal (=) select the button, and minus (-) deselects the button. If the checkbutton's state is disabled then none of the above actions occur: the checkbutton is completely non-responsive. The behavior of checkbuttons can be changed by defining new bindings for individual widgets or by redefining the class bindings. KEYWORDS ======== checkbutton, widget  File: pm.info, Node: Tk/Clipboard, Next: Tk/Clock, Prev: Tk/Checkbutton, Up: Module List Manipulate Tk clipboard *********************** NAME ==== Tk::clipboard - Manipulate Tk clipboard $widget->*clipboard*Option?(args)? DESCRIPTION =========== This command provides an interface to the Tk clipboard, which stores data for later retrieval using the selection mechanism. In order to copy data into the clipboard, *clipboardClear* must be called, followed by a sequence of one or more calls to *clipboardAppend*. To ensure that the clipboard is updated atomically, all appends should be completed before returning to the event loop. The following methods are currently supported: $widget->*clipboardClear* Claims ownership of the clipboard on $widget's display and removes any previous contents. Returns an empty string. $widget->*clipboardAppend*(?*-format*=>format?,?*-type*=>type?,?-?,data) Appends data to the clipboard on $widget's display in the form given by type with the representation given by format and claims ownership of the clipboard on $widget's display. Type specifies the form in which the selection is to be returned (the desired "target" for conversion, in ICCCM terminology), and should be an atom name such as STRING or FILE_NAME; see the Inter-Client Communication Conventions Manual for complete details. Type defaults to STRING. The format argument specifies the representation that should be used to transmit the selection to the requester (the second column of Table 2 of the ICCCM), and defaults to STRING. If format is STRING, the selection is transmitted as 8-bit ASCII characters. See the `Tk::Selection' in this node documentation for explanation of what happens if format is not STRING. Note that arguments passed to *clipboardAppend* are concatenated before conversion, so the caller must take care to ensure appropriate spacing across string boundaries. All items appended to the clipboard with the same type must have the same format. A - argument may be specified to mark the end of options: the next argument will always be used as data. This feature may be convenient if, for example, data starts with a -. KEYWORDS ======== clear, format, clipboard, append, selection, type  File: pm.info, Node: Tk/Clock, Next: Tk/Cloth, Prev: Tk/Clipboard, Up: Module List Clock widget with analog and digital display ******************************************** NAME ==== Tk::Clock - Clock widget with analog and digital display SYNOPSIS ======== use Tk use Tk::Clock; $clock = $parent->Clock (?-option => ...?); $clock->config ( # These reflect the defaults useDigital => 1, useAnalog => 1, anaScale => 100, handColor => "Green4", secsColor => "Green2", tickColor => "Yellow4", tickFreq => 1, timeFont => "fixed", timeColor => "Red4", timeFormat => "HH.MM:SS", dateFont => "fixed", dateColor => "Blue4", dateFormat => "dd-mm-yy"); DESCRIPTION =========== Create a clock canvas with both an analog- and a digital display. Either can be disabled by setting useAnalog or useDigital to 0 resp. Legal dateFormat characters are d and dd for date, ddd and dddd for weekday, m, mm, mmm and mmmm for month, y and yy for year and any separators :, -, / or space. Legal timeFormat characters are H and HH for hour, h and hh for AM/PM hour, M and MM for minutes, S and SS for seconds, A for AM/PM indicator and any separators :, -, . or space. Meaningful values for tickFreq are 1, 5 and 15 showing all ticks, tick every 5 minutes or the four main ticks only, though any positive integer will do (put a tick on any tickFreq minute). The analog clock can be enlaged or reduced using anaScale for which the default of 100% is about 72x72 pixels. Future enhancement will include auto sizing for anaScale 0. BUGS ==== If the system load's too high, the clock might skip some seconds. Due to the fact that the year is expressed in 2 digit's, this widget is not Y2K compliant in the default configuration. There's no check if either format will fit in the given space. TODO ==== * Using POSIX' strftime () for dateFormat. Current implementation would probably make this very slow. * Auto sizing to fit (analog) clock in given space. AUTHOR ====== H.Merijn Brand Thanks to Larry Wall for inventing perl. Thanks to Nick Ing-Simmons for providing perlTk. Thanks to Achim Bohnet for introducing me to OO (and converting the basics of my clock.pl to Tk::Clock.pm). Thanks to Sriram Srinivasan for understanding OO though his Panther book.  File: pm.info, Node: Tk/Cloth, Next: Tk/CmdLine, Prev: Tk/Clock, Up: Module List An OO Tk Canvas *************** NAME ==== Tk::Cloth - An OO Tk Canvas SYNOPSIS ======== use Tk::Cloth; $cloth = $parent->Cloth; $cloth->pack(-fill => 'both', -expand => 1); $rect = $cloth->Rectangle( -coords => [ 0,0,100,100], -fill => 'red' ); $tag = $cloth->tag; $tag->Line( -coords => [10,10,100,100], -foreground => 'black' ); $tag->Line( -coords => [50,50,100,100], -foreground => 'black' ); $tag->move(30,30); $tag->bind("<1>", [ &button1 ]); DESCRIPTION =========== *Tk::Cloth* provides an object-orientated approach to a canvas and canvas items. SEE ALSO ======== `Tk::Canvas|Tk::Canvas' in this node AUTHOR ====== Graham Barr <`gbarr@pobox.com'> Current maintainer is Slaven Rezic <`eserte@cs.tu-berlin.de'>. COPYRIGHT ========= Copyright (c) 1997-1998 Graham Barr. 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/CmdLine, Next: Tk/ColorEditor, Prev: Tk/Cloth, Up: Module List Process standard X11 command line options and set initial resources ******************************************************************* NAME ==== Tk::CmdLine - Process standard X11 command line options and set initial resources SYNOPSIS ======== Tk::CmdLine::SetArguments([@argument]); my $value = Tk::CmdLine::cget([$option]); Tk::CmdLine::SetResources((\@resource | $resource) [, $priority]); Tk::CmdLine::LoadResources( [ -symbol => $symbol ] [ -file => $fileSpec ] [ -priority => $priority ] [ -echo => $fileHandle ] ); DESCRIPTION =========== Process standard X11 command line options and set initial resources. The X11R5 man page for X11 says: "Most X programs attempt to use the same names for command line options and arguments. All applications written with the X Toolkit Intrinsics automatically accept the following options: ...". This module processes these command line options for perl/Tk applications using the SetArguments function. This module can optionally be used to load initial resources explicitly via function SetResources, or from specified files (default: the standard X11 application-specific resource files) via function LoadResources. Command Line Options -------------------- *-background* Color | *-bg* Color Specifies the color to be used for the window background. *-class* Class Specifies the class under which resources for the application should be found. This option is useful in shell aliases to distinguish between invocations of an application, without resorting to creating links to alter the executable file name. *-display* Display | *-screen* Display Specifies the name of the X server to be used. *-font* *Font* | *-fn* *Font* Specifies the font to be used for displaying text. *-foreground* Color | *-fg* Color Specifies the color to be used for text or graphics. *-geometry* Geometry Specifies the initial size and location of the first `MainWindow|Tk::MainWindow' in this node. *-iconic* Indicates that the user would prefer that the application's windows initially not be visible as if the windows had been immediately iconified by the user. Window managers may choose not to honor the application's request. *-motif* Specifies that the application should adhere as closely as possible to Motif look-and-feel standards. For example, active elements such as buttons and scrollbar sliders will not change color when the pointer passes over them. *-name* Name Specifies the name under which resources for the application should be found. This option is useful in shell aliases to distinguish between invocations of an application, without resorting to creating links to alter the executable file name. *-synchronous* Indicates that requests to the X server should be sent synchronously, instead of asynchronously. Since Xlib normally buffers requests to the server, errors do do not necessarily get reported immediately after they occur. This option turns off the buffering so that the application can be debugged. It should never be used with a working program. *-title* *TitleString* This option specifies the title to be used for this window. This information is sometimes used by a window manager to provide some sort of header identifying the window. *-xrm* *ResourceString* Specifies a resource pattern and value to override any defaults. It is also very useful for setting resources that do not have explicit command line arguments. The *ResourceString* is of the form :, that is (the first) ':' is used to determine which part is pattern and which part is value. The (, ) pair is entered into the options database with *optionAdd* (for each `MainWindow|Tk::MainWindow' in this node configured), with interactive priority. Initial Resources ----------------- There are several mechanism for initializing the resource database to be used by an X11 application. Resources may be defined in a $HOME/.Xdefaults file, a system application defaults file (e.g. /usr/lib/X11/app-defaults/), or a user application defaults file (e.g. $HOME/). The Tk::CmdLine functionality for setting initial resources concerns itself with the latter two. Resource files contain data lines of the form :. They may also contain blank lines and comment lines (denoted by a ! character as the first non-blank character). Refer to `option|Tk::option' in this node for a description of :. System Application Defaults Files System application defaults files may be specified via environment variable $XFILESEARCHPATH which, if set, contains a colon-separated list of file patterns. User Application Defaults Files User application defaults files may be specified via environment variables $XUSERFILESEARCHPATH, $XAPPLRESDIR or $HOME. METHODS ======= SetArguments Extract the X11 options contained in a specified array (@ARGV by default). Tk::CmdLine::SetArguments([@argument]) The X11 options may be specified using a single dash - as per the X11 convention, or using two dashes - as per the POSIX standard (e.g. *-geometry* *100x100*, *-geometry* *100x100* or *-geometry=**100x100*). The options may be interspersed with other options or arguments. A - by itself terminates option processing. By default, command line options are extracted from @ARGV the first time a MainWindow is created. The Tk::MainWindow constructor indirectly invokes SetArguments to do this. cget Get the value of a configuration option specified via SetArguments. (cget first invokes SetArguments if it has not already been invoked.) Tk::CmdLine::cget([$option]) The valid options are: *-class*, *-name*, *-screen* and *-title*. If no option is specified, *-class* is implied. A typical use of cget might be to obtain the application class in order to define the name of a resource file to be loaded in via LoadResources. my $class = Tk::CmdLine::cget(); # process command line and return class SetResources Set the initial resources. Tk::CmdLine::SetResources((\@resource | $resource) [, $priority]) A single resource may be specified using a string of the form ':'. Multiple resources may be specified by passing an array reference whose elements are either strings of the above form, and/or anonymous arrays of the form [ , ]. The optional second argument specifies the priority, as defined in `option|Tk::option' in this node, to be associated with the resources (default: userDefault). Note that SetResources first invokes SetArguments if it has not already been invoked. LoadResources Load initial resources from one or more files. Tk::CmdLine::LoadResources( [ -symbol => $symbol ] [ -file => $fileSpec ] [ -priority => $priority ] [ -echo => $fileHandle ] ); [ *-symbol* => $symbol ] specifies the name of an environment variable that, if set, defines a colon-separated list of one or more directories and/or file patterns. $XUSERFILESEARCHPATH is a special case. If $XUSERFILESEARCHPATH is not set, $XAPPLRESDIR is checked instead. If $XAPPLRESDIR is not set, $HOME is checked instead. An item is identified as a file pattern if it contains one or more /%[A-Za-z]/ patterns. Only patterns *%L*, %T and *%N* are currently recognized. All others are replaced with the null string. Pattern *%L* is translated into $LANG. Pattern %T is translated into *app-defaults*. Pattern *%N* is translated into the application class name. Each file pattern, after substitutions are applied, is assumed to define a FileSpec to be examined. When a directory is specified, FileSpecs // and / are defined, in that order. [ *-file* => $fileSpec ] specifies a resource file to be loaded in. The file is silently skipped if if does not exist, or if it is not readable. [ *-priority* => $priority ] specifies the priority, as defined in `option|Tk::option' in this node, to be associated with the resources (default: userDefault). [ *-echo* => $fileHandle ] may be used to specify that a line should be printed to the corresponding FileHandle (default: \*STDOUT) everytime a file is examined / loaded. If no *-symbol* or *-file* options are specified, LoadResources processes symbol $XFILESEARCHPATH with priority startupFile and $XUSERFILESEARCHPATH with priority userDefault. (Note that $XFILESEARCHPATH and $XUSERFILESEARCHPATH are supposed to contain only patterns. $XAPPLRESDIR and $HOME are supposed to be a single directory. LoadResources does not check/care whether this is the case.) For each set of FileSpecs, LoadResources examines each FileSpec to determine if the file exists and is readable. The first file that meets this criteria is read in and SetResources is invoked. Note that LoadResources first invokes SetArguments if it has not already been invoked. NOTES ===== This module is an object-oriented module whose methods can be invoked as object methods, class methods or regular functions. This is accomplished via an internally-maintained object reference which is created as necessary, and which always points to the last object used. SetArguments, SetResources and LoadResources return the object reference. EXAMPLES ======== 1. @ARGV is processed by Tk::CmdLine at MainWindow creation. use Tk; # my $mw = MainWindow->new(); MainLoop(); 2. @ARGV is processed by Tk::CmdLine before MainWindow creation. An @ARGV of (-geometry=100x100 -opt1 a b c -bg red) is equal to (-opt1 a b c) after SetArguments is invoked. use Tk; Tk::CmdLine::SetArguments(); # Tk::CmdLine->SetArguments() works too # my $mw = MainWindow->new(); MainLoop(); 3. Just like 2) except that default arguments are loaded first. use Tk; Tk::CmdLine::SetArguments(qw(-name test -iconic)); Tk::CmdLine::SetArguments(); # my $mw = MainWindow->new(); MainLoop(); 4. @ARGV is processed by Tk::CmdLine before MainWindow creation. Standard resource files are loaded in before MainWindow creation. use Tk; Tk::CmdLine::SetArguments(); # Tk::CmdLine::LoadResources(); my $mw = MainWindow->new(); MainLoop(); 5. @ARGV is processed by Tk::CmdLine before MainWindow creation. Standard resource files are loaded in before MainWindow creation using non-default priorities. use Tk; Tk::CmdLine::SetArguments(); # Tk::CmdLine::LoadResources(-echo => \*STDOUT, -priority => 65, -symbol => 'XFILESEARCHPATH' ); Tk::CmdLine::LoadResources(-echo => \*STDOUT, -priority => 75, -symbol => 'XUSERFILESEARCHPATH' ); my $mw = MainWindow->new(); MainLoop(); 6. @ARGV is processed by Tk::CmdLine before MainWindow creation. Standard resource files are loaded in before MainWindow creation. Individual resources are also loaded in before MainWindow creation. use Tk; Tk::CmdLine::SetArguments(); # Tk::CmdLine::LoadResources(); Tk::CmdLine::SetResources( # set a single resource '*Button*background: red', 'widgetDefault' ); Tk::CmdLine::SetResources( # set multiple resources [ '*Button*background: red', '*Button*foreground: blue' ], 'widgetDefault' ); my $mw = MainWindow->new(); MainLoop(); ENVIRONMENT =========== HOME (optional) Home directory which may contain user application defaults files as $HOME/$LANG/ or $HOME/. LANG (optional) The current language (default: C). XFILESEARCHPATH (optional) Colon-separated list of FileSpec patterns used in defining system application defaults files. XUSERFILESEARCHPATH (optional) Colon-separated list of FileSpec patterns used in defining user application defaults files. XAPPLRESDIR (optional) Directory containing user application defaults files as $XAPPLRESDIR/$LANG/ or $XAPPLRESDIR/. SEE ALSO ======== `MainWindow|Tk::MainWindow' in this node `option|Tk::option' in this node HISTORY ======= * 1999.03.04 Ben Pavon Rewritten as an object-oriented module. Allow one to process command line options in a specified array (@ARGV by default). Eliminate restrictions on the format and location of the options within the array (previously the X11 options could not be specified in POSIX format and had to be at the beginning of the array). Added the SetResources and LoadResources functions to allow the definition of resources prior to MainWindow creation.  File: pm.info, Node: Tk/ColorEditor, Next: Tk/ColourChooser, Prev: Tk/CmdLine, Up: Module List a general purpose Tk widget Color Editor **************************************** NAME ==== Tk::ColorEditor - a general purpose Tk widget Color Editor SYNOPSIS ======== use Tk::ColorEditor; $cref = $mw->ColorEditor(-title => $title, -cursor => @cursor); $cref->Show; DESCRIPTION =========== ColorEditor is implemented as an object with various methods, described below. First, create your ColorEditor object during program initialization (one should be sufficient), and then configure it by specifying a list of Tk widgets to colorize. When it's time to use the editor, invoke the Show() method. ColorEditor allows some customization: you may alter the color attribute menu by adding and/or deleting menu items and/or separators, turn the status window on or off, alter the configurator's list of color widgets, or even supply your own custom color configurator callback. 1. Call the constructor to create the editor object, which in turn returns a blessed reference to the new object: use Tk::ColorEditor; $cref = $mw->ColorEditor( -title => $title, -cursor => @cursor, ); mw - a window reference, usually the result of a MainWindow->new call. As the default root of a widget tree, $mw and all descendant widgets at object-creation-time are configured by the default color configurator procedure. (You probably want to change this though or you might end up colorizing ColorEditor!) title - Toplevel title, default = ' '. cursor - a valid Tk '-cursor' specification (default is 'top_left_arrow'). This cursor is used over all ColorEditor "hot spots". 2. Invoke the configure() method to change editor characteristics: $cref->configure(-option => value, ..., -option-n => value-n); options: -command : a callback to a `set_colors' replacement. -widgets : a reference to a list of widget references for the color configurator. -display_status : TRUE IFF display the ColorEditor status window when applying colors. -add_menu_item : 'SEP', or a color attribute menu item. -delete_menu_item : 'SEP', a color attribute menu item, or color attribute menu ordinal. For example: $cref->configure(-delete_menu_item => 3, -delete_menu_item => 'disabledforeground', -add_menu_item => 'SEP', -add_menu_item => 'New color attribute', -widgets => [$ce, $qu, $f2b2], -widgets => [$f2->Descendants], -command => [\&my_special_configurator, some, args ] ); 3. Invoke the Show() method on the editor object, say, by a button or menu press: $cref->Show; 4. The cget(-widgets) method returns a reference to a list of widgets that are colorized by the configurator. Typically, you add new widgets to this list and then use it in a subsequent configure() call to expand your color list. $cref->configure( -widgets => [ @{$Filesystem_ref->cget(-widgets)}, @{$cref->cget(-widgets)}, ] ); 5. The delete_widgets() method expects a reference to a list of widgets which are then removed from the current color list. $cref->delete_widgets($OBJTABLE{$objname}->{'-widgets'}) AUTHORS ======= Stephen O. Lidie, Lehigh University Computing Center. 95/03/05 lusol@Lehigh.EDU Many thanks to Guy Decoux (decoux@moulon.inra.fr) for doing the initial translation of tcolor.tcl to TkPerl, from which this code has been derived.  File: pm.info, Node: Tk/ColourChooser, Next: Tk/Columns, Prev: Tk/ColorEditor, Up: Module List Perl/Tk module providing a Colour selection dialogue box. ********************************************************* NAME ==== ColourChooser - Perl/Tk module providing a Colour selection dialogue box. SYNOPSIS ======== use Tk::ColourChooser ; my $col_dialog = $Window->ColourChooser ; my $colour = $col_dialog->Show ; if( $colour ) { # They pressed OK and the colour chosen is in $colour - could be # transparent which is 'None' unless -transparent is set. } else { # They cancelled. } # May optionally have the colour initialised. my $col_dialog = $Window->ColourChooser( -colour => 'green' ) ; my $col_dialog = $Window->ColourChooser( -colour => '#0A057C' ) ; # The title may also be overridden; and we can insist that only hex values # are returned rather than colour names. We can disallow transparent. my $col_dialog = $Window->ColourChooser( -language => 'en', # Or 'de' or 'fr'. -title => 'Select a colour', -colour => '0A057C', -transparent => 0, -hexonly => 1, -showhex => 1, ) ; DESCRIPTION =========== ColourChooser is a dialogue box which allows the user to pick a colour from the list in rgb.txt (supplied with X Windows), or to create a colour by setting RGB (red, green, blue) values with slider controls. You can scroll through all the named colours by using the and arrow keys on the keyboard or by clicking the mouse on the scrollbar and then clicking the colour list. Options ------- `-language' This is optional. Default is `en'. This option allows you to set the language for the title and labels. Valid values are `en' (english), `de' (german), `fr' (french) and `english' (for backward compatibility) which is also the default. Translations are by Babelfish. Other languages will be added if people provide translations. `-title' This is optional and allows you to set the title. Default is 'Colour Chooser' in the `-language' specified. `-colour' This is optional and allows you to specify the colour that is shown when the dialogue is invoked. It may be specified as a colour name from rgb.txt or as a six digit hex number with an optional leading hash, i.e. as 'HHHHHH' or '#HHHHHH'. Default is 'black'. `-hexonly' This is optional. If set to 1 it forces the ColourChooser to only return colours as hex numbers in Tk format ('#HHHHHH'); if set to 0 it returns colours as names if they are named in rgb.txt, and as hex numbers if they have no name. Transparent is always returned as 'None' however. Default is 0. `-transparent' This is optional. If set to 0 it stops ColourChooser offering the Transparent button so that only valid colours may be chosen - or cancel. Default is 1. `-showhex' This is optional. If set to 1 it shows the hex value of the colour in the title bar. Default is 0. The user has three options: OK -- Pressing OK will return the selected colour, as a name if it has one or as an RGB value if it doesn't. (Colours which do not have names are listed as 'Unnamed' in the colour list box.) If the `-hexonly' option has been specified the colour is always returned as a Tk colour hex value, i.e. in the form '#HHHHHH' except if Transparent is chosen in which case 'None' is returned. OK is pressed by a mouse click or or or or . Transparent ----------- Pressing Transparent will return the string 'None' which is xpm's name for transparent. Transparent is pressed by a mouse click or or or . Cancel ------ Pressing Cancel will return an empty string. Cancel is pressed by a mouse click or or or or . (Note that if the language is not english then the letter to press will be the first letter of the translation of the word 'Cancel'. INSTALLATION ============ ColourChooser.pm should be placed in any Tk directory in any lib directory in Perl's %INC path, for example, '/usr/lib/perl5/Tk'. ColourChooser looks for the file rgb.txt on your system - if it can't find it you will only be able to specify colours by RGB value. BUGS ==== Does almost no error checking. Can be slow to load because rgb.txt is large; however we now load a single instance of the colour names when the module is first used and these names are then shared. If you scroll the list by keyboard or use the mouse to move the colour sliders the colour updates as you go; but if you use the mouse on the scrollbar you must click the colour name box for the colour to update. I don't know why this is and any advice on how to fix it would be welcome. AUTHOR ====== Mark Summerfield. I can be contacted as - please include the word 'colourchooser' in the subject line. The code draws from Stephen O. Lidie's work. COPYRIGHT ========= Copyright (c) Mark Summerfield 1999-2000. All Rights Reserved. This module may be used/distributed/modified under the LGPL.  File: pm.info, Node: Tk/Columns, Next: Tk/ComboEntry, Prev: Tk/ColourChooser, Up: Module List A multicolumn list widget with sortable & sizeable columns ********************************************************** NAME ==== Tk::Columns - A multicolumn list widget with sortable & sizeable columns SYNOPSIS ======== use Tk::Columns; $Columns = $parent->B ( '-columnlabels' => [qw (column1 column2)] '-listbackground' => 'white', '-listforeground' => 'black', '-buttonforeground' => 'black', '-buttonbackground' => 'blue', ); $ColumnHeader = $Columns->B ( '-listfont' => '-adobe-new century schoolbook-medium-r-normal--14-*-*-*-*-*-*-*', '-buttoncolor' => 'beige', '-text' => 'column3', '-width' => 15, '-trimcount' => 2, '-listbackground' => 'white', '-listforeground' => 'black', '-buttonforeground' => 'black', '-buttonbackground' => 'blue', '-sort' => 'true', '-sortcommand' => '$a cmp $b', '-image' => $icon_image, '-buttoncommand' => sub {...}, '-selectcommand' => sub {...} ); $Columns->insert ('end', ['List', 'Row', 'Contents']); $Columns->insert ('end', {'column1' => 'List', 'column2' => 'Row', 'column3' => 'Contents'}); $Columns->insert ('end', 'List', 'Row', 'Contents'); $Columns->delete (0, 'end'); ... Tk::MainLoop; DESCRIPTION =========== Implements a multicolumn list with resizeable, scrollable columns and configurable sorting by column. Other features include column selection callbacks and row selection callbacks, global and per-column color and font selection, and column insertion data specified by column label (hash) or by index (list). STANDARD OPTIONS ================ Columns *-background -foreground -font -bg* ColumnButton *-font -image -foreground -background -borderwidth -relief -text -width -bg* See Tk for details of the standard options. WIDGET-SPECIFIC OPTIONS ======================= Name: *buttonbackground* Class: *ButtonBackground* Switch: *-buttonbackground* Aliases: *-buttoncolor* *-color* Specifies the background (surface) color for all existing buttons Name: *buttoncommand* Class: *ButtonCommand* Switch: *-buttoncommand* Specifies a callback to be executed when a column header is clicked. The callback is passed the list index. When specified, this callback is registered for every existing listbox and sets the default for new ones. If the *-sort* option is turned on, it overrides this option but does not negate it, allowing it to return when the *-sort* option is turned off. Name: *buttonfont* Class: *ButtonFont* Switch: *-buttonfont* Specifies the font to use for all the existing column header labels Name: columns Class: Columns Switch: *-columns* Aliases: *-columnlabels* This option takes a reference to a list of options. If the list consists of scalar values, these are assumed to be the labels for column headers. These elements are created with default options which should normally be alright. If the list consists of references to arrays, then these are assumed to be key => value pairs specifying the options to pass to $Columns->addcolumn. Name: image Class: Image Switch: *-image* Setting this to a reference to a Tk::Image causes that image to be set for all of the column labels and sets the default for all future columns. By default column headers are displayed without icons. See *Note Tk/Label: Tk/Label, Name: *listbackground* Class: *ListBackground* Switch: *-listbackground* Aliases: *-listcolor* *-background* *-bg* Specifies the background (surface) color for all existing listboxes and sets the default for all new ones. Default is 'white' Name: *listfont* Class: *ListFont* Switch: *-listfont* Alias: *-font* Specifies the font for all existing listboxes and sets the default for all new ones. The default is to use the system default font. Name: *listforeground* Class: *ListForeground* Switch: *-listforeground* Specifies the foreground (writing) color for all existing listboxes and sets the default for all new ones. Default is 'black' Name: *selectcommand* Class: *SelectCommand* Switch: *-selectcommand* Aliases: *-command* Specifies a callback to be executed when a list entry is double-clicked. The callback is passed the list index. When specified, this callback is registered for every existing listbox and sets the default for new ones. Name: *selectmode* Class: *SelectMode* Switch: *-selectmode* Sets the selection mode for all existing listboxes and sets the default to use for new ones. The default is 'browse'. Name: *trimcount* Class: *TrimCount* Switch: *-trimcount* Specifies the number of button trim 'handles' for all existing buttons. Name: zoom Class: *Zoom* Switch: *-zoom* This option takes a boolean argument. When set to 1, all the existing columns are 'zoomed', that is, reduced to their smallest width. When set to 0, all the columns are returned to the original widths WIDGET METHODS ============== $Button = *$Columns*->ColumnButton (option => value, ...) $Button = *$Columns*->addcolumn (option => value, ...) $Button = *$Columns*->Column (option => value, ...) $Button = *$Columns*->Button (option => value, ...) $Button = *$Columns*->column (option => value, ...) Creates a column header and an attached listbox. The listbox is 'tied' to any preexisting ones. The new listbox is padded with empty rows to match its siblings. This method really invokes an instantiation of the ColumnButton class. All the options given apply to the ColumnButton. The widget reference returned can be used to alter the column's behaviour later. The following options are available :- *-background* => color *-buttonbackground* => color *-bg* => color *-buttoncolor* => color *-color* => color Specifies the button's background (surface) color. *-buttoncommand* => callback Specifies a callback to be executed when a column header is clicked. The callback is passed the list index. If the *-sort* option is turned on, it overrides this option but does not negate it, allowing it to return when the *-sort* option is turned off. *-font* => *fontspec* *-buttonfont* => *fontspec* Specifies the font for the text in the button label. *-foreground* => color *-buttonforeground* => color *-fg* => color Specifies the button's foreground (text) color. Defaults to black. *-image* => image Setting this to a reference to a Tk::Image causes that image to be displayed in the column label. See *Note Tk/Label: Tk/Label, *-listbackground* => color *-slavecolor* => color Sets the background color for the attached listbox *-listfont* => *fontspec* Specifies the font for the text in the attached listbox. *-listforeground* => color Sets the foreground (text) color for the attached listbox. *-listselectmode* => mode Sets the selection mode for the attached listbox. *-selectcommand* => callback *-command* => callback Specifies a callback to be executed when a list entry is double-clicked. The callback is passed the list index. *-slave* => widget DO NOT USE ! This option is use to inform the button which widget it must manage. It is provided here only for completeness. *-sort* => boolean Setting this to boolean 'true' allows all columns to be sorted by this column when the button is pressed. Each invocation reverses the sort order. The sort method can be specified with *-sortcommand*. Setting this to boolean false (0) disables the sorting. When active, this option overrides any existing *-buttoncommand*. When inactive, any preexisting *-buttoncommand* is re-enabled. *-sortcommand* => string *-sortfunction* => string *-sortmethod* => string This specifies the sort function to pass to the sort Perl function for sorting of this column. The default is '{lc ($a) cmp lc ($b)}' for (caseless) alphanumeric comparison. Read the *perlfunc* documentation for more details on sort. *-trimcount* => integer Specifies the number of trim 'handles' for the button. It defaults to 2. Setting it to 0 makes the column unresizeable. *-width* => integer Set this to the desired width of the column, in characters. The default is the natural width of the text and image parts combined. *-zoom* => boolean This option takes a boolean argument. When set to 1, the column is 'zoomed', that is, its width is reduced to the smallest possible setting. When set to 0, the column is returned to its original width. *$Columns*->activate(index) Sets the row 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. See listbox for more details. *$Columns*->*bbox*(index, *[columnspec]*) Returns a list of four numbers describing the bounding box of the text in the element given by index in the listbox specified by column or the first listbox in the composite. 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. See listbox for more details. *$Columns*->*buttonhash*() Returns a hash of column buttons keyed by column label *$Columns*->*buttons*() Returns an ordered list of the column buttons *$Columns*->*buttonwidth*(*columnspec*, *?newwidth?*) *$Columns*->*columnwidth*(*columnspec*, *?newwidth?*) *$Columns*->width(*columnspec*, *?newwidth?*) This uses the numeric or textual *columnspec* to locate a column header and sets the width to *newwidth* if present, or returns the current width of that column. It the column doesn't exist then the return value 0 is quietly returned. *$Columns*->*columnlabels*(*array reference*) *$Columns*->columns(*array reference*) This invokes *$Columns*->configure (*-columnlabels* => *array reference*). See *-columnlabels* for details as this is a convenience method. *$Columns*->*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. See listbox for more details. *$Columns*->delete(where, where) This has identical behaviour to listbox->delete. See listbox for more details. *$Columns*->get(from, to) Retrieves the rows in the range from .. to. This method is an analog of the listbox->get method. The data returned is an array of references to the row lists specified. See listbox for more details. *$Columns*->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). See listbox for more details. *$Columns*->*indexedbutton*(*columnspec*) Returns the column button associated with the numeric column index or the textual column name. *$Columns*->*indexedlist*(*columnspec*) Returns the listbox associated with the numeric column index or the textual column name. *$Columns*->insert(where, ?