This is Info file pm.info, produced by Makeinfo version 1.68 from the input file bigpm.texi.  File: pm.info, Node: Tk/messageBox, Next: Tk/option, Prev: Tk/mega, Up: Module List pop up a message window and wait for user response. *************************************************** NAME ==== messageBox - pop up a message window and wait for user response. *$response* = $widget->*messageBox*(*-option* => value, ... ); DESCRIPTION =========== This method uses `Tk::Dialog|Tk::Dialog' in this node to quickly create several common dialog boxes. A dialog widget consists of a message, an icon and a set of buttons (see the *-type* option). After the message window is popped up, *messageBox* waits for the user to select one of the buttons and return the button text. NOTE: unlike *Tk::Dialog* which creates its widget once and can be used many times, the *messageBox* window is created every time it's used. The following option/value pairs are supported: *-default* The case-sensitive symbolic name of the default button for this message window ('OK', 'Cancel' and so on). See *-type* for a list of the symbolic names. If the message box has just one button it will automatically be made the default, otherwise if this option is not specified, there won't be any default button. *-icon* Specifies an icon to display. Any of the builtin Tk bitmaps can specified. *-message* Specifies the message to display. *-title* Specifies a string to display as the title. *-type* Specifies a predefined set of buttons to be displayed. The following values are possible: 'AbortRetryIgnore', 'OK', 'OKCancel', 'RetryCancel', 'YesNo' or 'YesNoCancel'. EXAMPLE ======= *$repsonse* = *$mw*->*messageBox*(-icon => 'questhead', -message => 'Hello World!', -title => 'My title', -type => 'AbortRetryIgnore', -default => 'Retry'); AUTHOR ====== Stephen.O.Lidie@Lehigh.EDU. 98/05/25  File: pm.info, Node: Tk/option, Next: Tk/options, Prev: Tk/messageBox, Up: Module List Using the option database in Perl/Tk ************************************ NAME ==== option - Using the option database in Perl/Tk $widget->*widgetClass*(Name=>name, *-class*=>class); $widget->*PathName*; $widget->*optionAdd*(pattern=>*value * ?,priority?); $widget->*optionClear*; $widget->*optionGet*(*name, class*); $widget->*optionReadfile*(*fileName* ?,priority?); DESCRIPTION =========== The option database (also known as the *resource database* or the *application defaults database*) is a set of rules for applying default options to widgets. Users and system administrators can set up these rules to customize the appearance of applications without changing any application code; for example, a user might set up personal foreground and background colors, or a site might use fonts associated with visual or language preferences. Different window managers (and implementations of them) have implemented the database differently, but most Xt-based window managers use the *.Xdefaults* file or the *xrdb* utility to manage user preferences; some use both, and/or implement a more complex set of site, user and application databases. Check your site documentation for these topics or your window manager's *RESOURCE_MANAGER* property. Being a good citizen -------------------- For most applications, the option database "just works." The *option...* methods are for applications that need to do something unusual, such as add new rules or test an option's default. Even in such cases, the application should provide for user preferences. Do not hardcode widget options without a *very* good reason. All users have their own tastes and they are all different. They choose a special font in a special size and have often spend a lot of time working out a color scheme that they will love until death. When you respect their choices they will enjoy working with your applications much more. Don't destroy the common look and feel of a personal desktop. Option rules and widget identification -------------------------------------- All widgets in an application are identified hierarchically by *pathname*, starting from the *MainWindow* and passing through each widget used to create the endpoint. The path elements are *widget names*, much like the elements of a file path from the root directory to a file. The rules in the option database are patterns that are matched against a widget's *pathname* to determine which defaults apply. When a widget is created, the Name option can be used to assign the widget's name and thus create a distinctive path for widgets in an application. If the Name option isn't given, Perl/Tk assigns a default name based on the type of widget; a *MainWindow*'s default name is the *appname*. These defaults are fine for most widgets, so don't feel you need to find a meaningful name for every widget you create. A widget must have a distinctive name to allow users to tailor its options independently of other widgets in an application. For instance, to create a Text widget that will have special options assigned to it, give it a name such as: $text = $mw->Text(Name => 'importantText'); You can then tailor the widget's attributes with a rule in the option database such as: *importantText*foreground: red The class attribute identifies groups of widgets, usually within an application but also to group similar widgets among different applications. One typically assigns a class to a *TopLevel* or Frame so that the class will apply to all of that widget's children. To extend the example, we could be more specific about the importantText widget by giving its frame a class: $frame = $mw->Frame(-class => 'Urgent'); $text = $frame->Text(Name => 'importantText'); Then the resource pattern can be specified as so: *Urgent*importantText*foreground: red Similarly, the pattern `*Urgent*background: cyan' would apply to all widgets in the frame. METHODS ======= $widget->*widgetClass*(Name=>name, *-class*=>class); Identify a new widget with name and/or class. Name specifies the path element for the widget; names generally begin with a lowercase letter. *-class* specifies the class for the widget and its children; classes generally begin with an uppercase letter. If not specified, Perl/Tk will assign a unique default name to each widget. Only *MainWindow* widgets have a default class, made by uppercasing the first letter of the application name. $widget->*PathName*; The *PathName* method returns the widget's *pathname*, which uniquely identifies the widget within the application. $widget->*optionAdd*(pattern=>*value *?, priority?); The *optionAdd* method adds a new option to the database. Pattern contains the option being specified, and consists of names and/or classes separated by asterisks or dots, in the usual X format. Value contains a text string to associate with pattern; this is the value that will be returned in calls to the *optionGet* method. If priority is specified, it indicates the priority level for this option (see below for legal values); it defaults to interactive. This method always returns an empty string. $widget->*optionClear*; The *optionClear* method clears the option database. Default options (from the *RESOURCE_MANAGER* property or the *.Xdefaults* file) will be reloaded automatically the next time an option is added to the database or removed from it. This method always returns an empty string. $widget->*optionGet*(*name,class*); The *optionGet* method returns the value of the option specified for $widget under name and class. To look up the option, *optionGet* matches the patterns in the resource database against $widget's *pathname* along with the class of $widget (or its parent if $widget has no class specified). The widget's class and name are options set when the widget is created (not related to class in the sense of `bless' in this node); the *MainWindow*'s name is the *appname* and its class is (by default) derived from the name of the script. If several entries in the option database match $widget's *pathname*, name, and class, then the method returns whichever was created with highest priority level. If there are several matching entries at the same priority level, then it returns whichever entry was *most recently entered* into the option database. If there are no matching entries, then the empty string is returned. $widget->*optionReadfile*(*fileName*?,priority?); The *optionReadfile* method reads *fileName*, which should have the standard format for an X resource database such as *.Xdefaults*, and adds all the options specified in that file to the option database. If priority is specified, it indicates the priority level at which to enter the options; priority defaults to interactive. The priority arguments to the option methods are normally specified symbolically using one of the following values: widgetDefault Level 20. Used for default values hard-coded into widgets. startupFile Level 40. Used for options specified in application-specific startup files. userDefault Level 60. Used for options specified in user-specific defaults files, such as *.Xdefaults*, resource databases loaded into the X server, or user-specific startup files. interactive Level 80. Used for options specified interactively after the application starts running. If priority isn't specified, it defaults to this level. Any of the above keywords may be abbreviated. In addition, priorities may be specified numerically using integers between 0 and 100, inclusive. The numeric form is probably a bad idea except for new priority levels other than the ones given above. BUGS ==== The priority scheme used by core Tk is not the same as used by normal Xlib routines. In particular is assumes that the order of the entries is defined, but user commands like *xrdb -merge* can change the order. SEE ALSO ======== `Tk::Xrm|Tk::Xrm' in this node KEYWORDS ======== database, option, priority, retrieve  File: pm.info, Node: Tk/options, Next: Tk/overview, Prev: Tk/option, Up: Module List Standard options supported by widgets and their manipulation ************************************************************ NAME ==== Tk::options - Standard options supported by widgets and their manipulation $value = $widget->cget('*-option*'); $widget->configure(*-option*=>value ?,*-option*=>value ...?); *@list* = $widget->configure('*-option*'); *@lol* = $widget->configure; DESCRIPTION =========== All widgets, and images have a standard mechanism for setting and querying attibutes or options. The mechanism is based on two methods configure and cget. The behaviour of these methods is as follows: $widget->configure(*-option*=>value ?,*-option*=>value ...?); Sets the values of *-option* to value for each *-option*=>value pair. The internal new method does an implicit configure in this form with options passed in at widget create time. $widget->configure('*-option*') In array context returns a list of five or two elements. If *-option* is an alias for another options it return a list consisting of the alias option and the name for the option is is an alias for, e.g., `('-bg', 'background')'. If *-option* is not an alias the returned list has the following five elements: *Option Name* The value of *-option*, e.g., *-background*. Name The option's name in the option database, e.g., background. Class The option's class value in the option database, e.g., Background. Default The default value for the option if not specified or in the option database, e.g., `grey'. Value The current value (as returned by cget), e.g., `white'. $widget->configure Returns a list of lists for all the options supported by $widget. Each sub-list is in the form returned by configure('*-option*'). (This mechanism is used by the *Tk::Derived* class to determine the options available from base class.) $widget->cget('*-option*') Returns the current value of *-option* for $widget. cget('*-option*') is clumsy with the need for " due to perl's parsing rules. Something more subtle using `tie|perlfunc' in this node might look better. The following paragraphs describe the common configuration options supported by widgets in the Tk toolkit. Every widget does not necessarily support every option (see the the documentation entries for individual widgets for a list of the standard options supported by that widget), but if a widget does support an option with one of the names listed below, then the option has exactly the effect described below. In the descriptions below, "Name" refers to the option's name in the option database. "Class" refers to the option's class value in the option database. "Switch" refers to the switch used in widget-creation and configure widget methods to set this value. For example, if an option's configure option is *-foreground* and there exists a widget $widget, then the call: $widget->configure(*-foreground*=>*'black'*) may be used to specify the value *black* for the option in the widget $widget. Configure options may be abbreviated, as long as the abbreviation is unambiguous (abbreviation is deprecated in perl/Tk). Creation options: Widget Name and Class --------------------------------------- The Name and *-class* options can only be specified when a widget is created, and cannot be changed with configure. These options determine the widget's identity and how Tk applies resource values from the option database (see *Note Tk/option: Tk/option,) and so they cannot be assigned by the options database. Name: name Switch: Name Specifies the path element for the widget. Names generally begin with a lowercase letter. Each widget has a unique *pathname* that follows the hierarchy from the *MainWindow* to the widget itself. Since the widget's *PathName* is used to assign options from the options database, it is important to specify a distinctive Name for any widget that will have non-default options. See *Note Tk/option: Tk/option, for details. Name: class Switch: *-class* Specifies a class for the window. Classes generally begin with an uppercase letter. This class will be used when querying the option database for the window's other options (see Tk::options), and it will also be used later for other purposes such as bindings. One typically assigns a class to a *TopLevel* or Frame so that the class will apply to all of that widget's children. Reconfigurable options ---------------------- These options can be set at widget creation or changed later via configure. Name: *activeBackground* Class: *Foreground* Switch: *-activebackground* Specifies background color to use when drawing active elements. An element (a widget or portion of a widget) is active if the mouse cursor is positioned over the element and pressing a mouse button will cause some action to occur. If strict Motif compliance has been requested by setting the $Tk::strictMotif variable, this option will normally be ignored; the normal background color will be used instead. For some elements on Windows and Macintosh systems, the active color will only be used while mouse button 1 is pressed over the element. Name: *activeBorderWidth* Class: *BorderWidth* Switch: *-activeborderwidth* Specifies a non-negative value indicating the width of the 3-D border drawn around active elements. See above for definition of active elements. The value may have any of the forms acceptable to *Tk_GetPixels*. This option is typically only available in widgets displaying more than one element at a time (e.g. menus but not buttons). Name: *activeForeground* Class: Background Switch: *-activeforeground* Specifies foreground color to use when drawing active elements. See above for definition of active elements. Name: *activetile* Class: *Tile* Switch: *-activetile* Specifies image used to display inside active elements of the widget. See above for definition of active elements. Name: anchor Class: Anchor Switch: *-anchor* Specifies how the information in a widget (e.g. text or a bitmap) is to be displayed in the widget. Must be one of the values n, ne, e, *se*, s, sw, w, *nw*, or center. For example, *nw* means display the information such that its top-left corner is at the top-left corner of the widget. Name: background Class: Background Switch: *-background* Alias: *-bg* Specifies the normal background color to use when displaying the widget. Name: bitmap Class: Bitmap Switch: *-bitmap* Specifies a bitmap to display in the widget, in any of the forms acceptable to *Tk_GetBitmap*. The exact way in which the bitmap is displayed may be affected by other options such as *-anchor* or -justify. Typically, if this option is specified then it overrides other options that specify a textual value to display in the widget; the *-bitmap* option may be reset to an empty string to re-enable a text display. In widgets that support both *-bitmap* and *-image* options, *-image* will usually override *-bitmap*. Name: *borderWidth* Class: *BorderWidth* Switch: *-borderwidth* Alias: *-bd* Specifies a non-negative value indicating the width of the 3-D border to draw around the outside of the widget (if such a border is being drawn; the *relief* option typically determines this). The value may also be used when drawing 3-D effects in the interior of the widget. The value may have any of the forms acceptable to *Tk_GetPixels*. Name: cursor Class: Cursor Switch: *-cursor* Specifies the mouse cursor to be used for the widget. The value may have any of the forms acceptable to *Tk_GetCursor*. Name: *dash* Class: *Dash* Switch: *-dash* The value may have any of the forms accepted by *Tk_GetDash*, such as 4, *[6,4]*, ., -, *-.*, or *-..*. Name: *dashoffset* Class: *Dashoffset* Switch: *-dashoffset* Specifies the offset in the dash list where the drawing starts. Name: *disabledForeground* Class: *DisabledForeground* Switch: *-disabledforeground* Specifies foreground color to use when drawing a disabled element. If the option is specified as an empty string (which is typically the case on monochrome displays), disabled elements are drawn with the normal foreground color but they are dimmed by drawing them with a stippled fill pattern. Name: *disabledtile* Class: *Tile* Switch: *-disabledtile* Specifies image to use when drawing a disabled element. Name: *exportSelection* Class: *ExportSelection* Switch: *-exportselection* Specifies whether or not a selection in the widget should also be the X selection. The value may have any of the forms accepted by *Tcl_GetBoolean*, such as *true*, false, 0, 1, *yes*, or no. If the selection is exported, then selecting in the widget deselects the current X selection, selecting outside the widget deselects any widget selection, and the widget will respond to selection retrieval requests when it has a selection. The default is usually for widgets to export selections. Name: font Class: *Font* Switch: *-font* Specifies the font to use when drawing text inside the widget. Name: *foreground* Class: *Foreground* Switch: *-foreground* Alias: *-fg* Specifies the normal foreground color to use when displaying the widget. Name: *highlightBackground* Class: *HighlightBackground* Switch: *-highlightbackground* Specifies the color to display in the traversal highlight region when the widget does not have the input focus. Name: *highlightColor* Class: *HighlightColor* Switch: *-highlightcolor* Specifies the color to use for the traversal highlight rectangle that is drawn around the widget when it has the input focus. Name: *highlightThickness* Class: *HighlightThickness* Switch: *-highlightthickness* Specifies a non-negative value indicating the width of the highlight rectangle to draw around the outside of the widget when it has the input focus. The value may have any of the forms acceptable to *Tk_GetPixels*. If the value is zero, no focus highlight is drawn around the widget. Name: image Class: Image Switch: *-image* Specifies an image to display in the widget, which must have been created with an image create. (See *Note Tk/Image: Tk/Image, for details of image creation.) Typically, if the *-image* option is specified then it overrides other options that specify a bitmap or textual value to display in the widget; the *-image* option may be reset to an empty string to re-enable a bitmap or text display. Name: *insertBackground* Class: *Foreground* Switch: *-insertbackground* Specifies the color to use as background in the area covered by the insertion cursor. This color will normally override either the normal background for the widget (or the selection background if the insertion cursor happens to fall in the selection). Name: *insertBorderWidth* Class: *BorderWidth* Switch: *-insertborderwidth* Specifies a non-negative value indicating the width of the 3-D border to draw around the insertion cursor. The value may have any of the forms acceptable to *Tk_GetPixels*. Name: *insertOffTime* Class: *OffTime* Switch: *-insertofftime* Specifies a non-negative integer value indicating the number of milliseconds the insertion cursor should remain "off" in each blink cycle. If this option is zero then the cursor doesn't blink: it is on all the time. Name: *insertOnTime* Class: *OnTime* Switch: *-insertontime* Specifies a non-negative integer value indicating the number of milliseconds the insertion cursor should remain "on" in each blink cycle. Name: *insertWidth* Class: *InsertWidth* Switch: *-insertwidth* Specifies a value indicating the total width of the insertion cursor. The value may have any of the forms acceptable to *Tk_GetPixels*. If a border has been specified for the insertion cursor (using the *insertBorderWidth* option), the border will be drawn inside the width specified by the *insertWidth* option. Name: jump Class: *Jump* Switch: *-jump* For widgets with a slider that can be dragged to adjust a value, such as scrollbars, this option determines when notifications are made about changes in the value. The option's value must be a boolean of the form accepted by *Tcl_GetBoolean*. If the value is false, updates are made continuously as the slider is dragged. If the value is true, updates are delayed until the mouse button is released to end the drag; at that point a single notification is made (the value "jumps" rather than changing smoothly). Name: justify Class: Justify Switch: -justify When there are multiple lines of text displayed in a widget, this option determines how the lines line up with each other. Must be one of left, center, or right. *Left* means that the lines' left edges all line up, center means that the lines' centers are aligned, and right means that the lines' right edges line up. Name: offset Class: Offset Switch: *-offset* Specifies the offset of tiles (see also *-tile* option). It can have two different formats *-offset x,y* or *-offset side*, where side can be n, ne, e, *se*, s, sw, w, *nw*, or center. In the first case the origin is the origin of the toplevel of the current window. For the canvas itself and canvas objects the origin is the canvas origin, but putting *#* in front of the coordinate pair indicates using the toplevel origin in stead. For canvas objects, the *-offset* option is used for stippling as well. For the line and polygon canvas items you can also specify an index as argument, which connects the stipple or tile origin to one of the coordinate points of the line/polygon. Name: orient Class: *Orient* Switch: *-orient* For widgets that can lay themselves out with either a horizontal or vertical orientation, such as scrollbars, this option specifies which orientation should be used. Must be either *horizontal* or *vertical* or an abbreviation of one of these. Name: *padX* Class: *Pad* Switch: *-padx* Specifies a non-negative value indicating how much extra space to request for the widget in the X-direction. The value may have any of the forms acceptable to *Tk_GetPixels*. When computing how large a window it needs, the widget will add this amount to the width it would normally need (as determined by the width of the things displayed in the widget); if the geometry manager can satisfy this request, the widget will end up with extra internal space to the left and/or right of what it displays inside. Most widgets only use this option for padding text: if they are displaying a bitmap or image, then they usually ignore padding options. Name: *padY* Class: *Pad* Switch: *-pady* Specifies a non-negative value indicating how much extra space to request for the widget in the Y-direction. The value may have any of the forms acceptable to *Tk_GetPixels*. When computing how large a window it needs, the widget will add this amount to the height it would normally need (as determined by the height of the things displayed in the widget); if the geometry manager can satisfy this request, the widget will end up with extra internal space above and/or below what it displays inside. Most widgets only use this option for padding text: if they are displaying a bitmap or image, then they usually ignore padding options. Name: *relief* Class: *Relief* Switch: *-relief* Specifies the 3-D effect desired for the widget. Acceptable values are *raised*, *sunken*, flat, *ridge*, solid, and *groove*. The value indicates how the interior of the widget should appear relative to its exterior; for example, *raised* means the interior of the widget should appear to protrude from the screen, relative to the exterior of the widget. Name: *repeatDelay* Class: *RepeatDelay* Switch: *-repeatdelay* Specifies the number of milliseconds a button or key must be held down before it begins to auto-repeat. Used, for example, on the up- and down-arrows in scrollbars. Name: *repeatInterval* Class: *RepeatInterval* Switch: *-repeatinterval* Used in conjunction with *repeatDelay*: once auto-repeat begins, this option determines the number of milliseconds between auto-repeats. Name: *selectBackground* Class: *Foreground* Switch: *-selectbackground* Specifies the background color to use when displaying selected items. 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: Background Switch: *-selectforeground* Specifies the foreground color to use when displaying selected items. Name: *setGrid* Class: *SetGrid* Switch: *-setgrid* Specifies a boolean value that determines whether this widget controls the resizing grid for its top-level window. This option is typically used in text widgets, where the information in the widget has a natural size (the size of a character) and it makes sense for the window's dimensions to be integral numbers of these units. These natural window sizes form a grid. If the *setGrid* option is set to true then the widget will communicate with the window manager so that when the user interactively resizes the top-level window that contains the widget, the dimensions of the window will be displayed to the user in grid units and the window size will be constrained to integral numbers of grid units. See `"GRIDDED GEOMETRY MANAGEMENT"', *Note Tk/Wm: Tk/Wm, for more details. Name: *takeFocus* Class: *TakeFocus* Switch: *-takefocus* Determines whether the window accepts the focus during keyboard traversal (e.g., Tab and Shift-Tab). Before setting the focus to a window, the traversal scripts consult the value of the *takeFocus* option. A value of 0 means that the window should be skipped entirely during keyboard traversal. 1 means that the window should receive the input focus as long as it is viewable (it and all of its ancestors are mapped). An empty value for the option means that the traversal scripts make the decision about whether or not to focus on the window: the current algorithm is to skip the window if it is disabled, if it has no key bindings, or if it is not viewable. If the value has any other form, then the traversal scripts take the value, append the name of the window to it (with a separator space), and evaluate the resulting string as a Callback. The script must return 0, 1, or an empty string: a 0 or 1 value specifies whether the window will receive the input focus, and an empty string results in the default decision described above. Note: this interpretation of the option is defined entirely by the Callbacks that implement traversal: the widget implementations ignore the option entirely, so you can change its meaning if you redefine the keyboard traversal scripts. Name: text Class: Text Switch: *-text* Specifies a string to be displayed inside the widget. The way in which the string is displayed depends on the particular widget and may be determined by other options, such as anchor or justify. Name: *textVariable* Class: Variable Switch: *-textvariable* Specifies the name of a variable. The value of the variable is a text string to be displayed inside the widget; if the variable value changes then the widget will automatically update itself to reflect the new value. The way in which the string is displayed in the widget depends on the particular widget and may be determined by other options, such as anchor or justify. Name: *troughColor* Class: Background Switch: *-troughcolor* Specifies the color to use for the rectangular trough areas in widgets such as scrollbars and scales. Name: *troughTile* Class: *Tile* Switch: *-troughtile* Specifies image used to display in the rectangular trough areas in widgets such as scrollbars and scales. Name: underline Class: *Underline* Switch: *-underline* Specifies the integer index of a character to underline in the widget. This option is used by the default bindings to implement keyboard traversal for menu buttons and menu entries. 0 corresponds to the first character of the text displayed in the widget, 1 to the next character, and so on. Name: *wrapLength* Class: *WrapLength* Switch: *-wraplength* For widgets that can perform word-wrapping, this option specifies the maximum line length. Lines that would exceed this length are wrapped onto the next line, so that no line is longer than the specified length. The value may be specified in any of the standard forms for screen distances. If this value is less than or equal to 0 then no wrapping is done: lines will break only at newline characters in the text. Name: *xScrollCommand* Class: *ScrollCommand* Switch: *-xscrollcommand* Specifies a callback used to communicate with horizontal scrollbars. When the view in the widget's window changes (or whenever anything else occurs that could change the display in a scrollbar, such as a change in the total size of the widget's contents), the widget will make a callback passing two numeric arguments in addition to any specified in the callback. Each of the numbers is a fraction between 0 and 1, which indicates a position in the document. 0 indicates the beginning of the document, 1 indicates the end, .333 indicates a position one third the way through the document, and so on. The first fraction indicates the first information in the document that is visible in the window, and the second fraction indicates the information just after the last portion that is visible. Typically the *xScrollCommand* option consists of the scrollbar widget object and the method "set" i.e. [set => *$sb*]: this will cause the scrollbar to be updated whenever the view in the window changes. If this option is not specified, then no command will be executed. Name: *yScrollCommand* Class: *ScrollCommand* Switch: *-yscrollcommand* Specifies a calback used to communicate with vertical scrollbars. This option is treated in the same way as the *xScrollCommand* option, except that it is used for vertical scrollbars and is provided by widgets that support vertical scrolling. See the description of *xScrollCommand* for details on how this option is used. SEE ALSO ======== `Tk::option|Tk::option' in this node `Tk::callbacks|Tk::callbacks' in this node `Tk::configspec|Tk::configspec' in this node `Tk_GetPixels|Tk::pTk::GetPixels' in this node KEYWORDS ======== class, name, standard option, switch  File: pm.info, Node: Tk/overview, Next: Tk/pTk, Prev: Tk/options, Up: Module List An overview of an Object Oriented Tk8.0 extension for perl5 *********************************************************** NAME ==== Tk - An overview of an Object Oriented Tk8.0 extension for perl5 use Tk; $main = MainWindow->new(); $widget = $main->*Widget*(...); $widget->pack(...); ... MainLoop; DESCRIPTION =========== In writing the perl Tk extension, the goals were to provide a complete interface to the latest production version of John Ousterhout's Tk, while providing an Object Oriented interface to perl code. CONTENTS ======== The package is composed of three loosely connected parts: pTk - Converted Tk source The pTk sub-directory is a copy of the C code of Tk4.0, modified to allow use by languages other than the original Tcl. (The pTk can be read as 'perl' Tk or 'portable' Tk, depending on your sensibilities.) Tk to Perl 'Glue' The top level directory provides *Tk.xs* and *tkGlue.c* which provide the perl-callable interfaces to pTk Perl code for 'Widget' Classes The *Tk/Tk* sub-directory contains the various perl modules that comprise the "Classes" that are visible to Tk applications. The "major" widgets such as *Tk::Text* are actually in separate directories at the top level (e.g. *Text/** for *Tk::Text*) and are dynamically loaded as needed on platforms which support perl5's DynaLoader. CLASS HIERARCHY =============== *package Tk;* - the 'base class' All the "command names" documented in Tcl/Tk are made to look like perl sub's and reside in the Tk package. Their names are all lower case. Typically there are very few commands at this level which are called directly by applications. *package Tk::Widget;* - the 'Widget class' There are no actual objects of the *Tk::Widget* class; however all the various Tk window "widgets" inherit from it, and it in turn inherits all the core Tk functions from Tk. *Tk::Widget* provides various functions and interfaces which are common to all Widgets. A widget is represented to perl as a blessed reference to a hash. There are some members of the hash which are private to Tk and its tkGlue code. Keys starting with *'.'* and of the form */_[A-Z][A-Za-z_]+_/* (i.e. starting and ending in _ and with first char after _ being upper case) should be considered reserved to Tk. *Tk::Button*, *Tk::Entry*, *Tk::Text* ... There is one class for each of the "Tk" widget item types. Some of them like *Tk::Frame* do very little indeed, and really only exist so that they can be derived from or so that focus or menu traversal can discover the "kind" of window being processed. Other classes, *Tk::Text* for example, provide a lot of methods used with Tk's "bind" to provide a rich keyboard/mouse interface to the widgets' data. These widget classes also include conversions of the Tcl code for event bindings, keyboard focus traversal, menu bars, and menu keyboard traversal. All the Tcl functions have been converted, but the names have changed (systematically) and they have been split up between the various classes in what I hope is an appropriate manner. Name changes are normally: dropping initial tk_ as the Tk-ness is implicit in the *Tk::* prefix, and similarly dropping say Menu from the name if it has been moved the Tk::Menu class. Thus 'proc tkMenuNextEntry' becomes 'sub NextEntry' in the Tk::Menu package. Tk::Image This does for Tk4.0's "images" what *Tk::Widget* does for widgets. Images are new to Tk4.0 and the class structure is not mature either. There are three sub-classes *Tk::Bitmap*, *Tk::Pixmap* and *Tk::Photo*. It is expected that Tk::Image hierarchy will evolve during the "beta" phase of Tk to allow dynamic or auto-loaded image types or photo formats (e.g. support for JPEG format for photos). Composite Widgets A composite is some kind of 'frame' with subwidgets which give it useful behaviour. *Tk::Dialog* is an example of a composite widget classes built from the basic Tk ones. It is intended that user code should not need to be aware that a particular class is a composite, and create and configure such widgets in the same manner as any other kind. The configure mechanism and the methods of the class manipulate the subwidgets as required. Composite widgets are implemented via *Tk::Frame* and multiple inheritance. The two 'frame' base classes *Tk::Frame* and *Tk::Toplevel* include the additional class *Tk::Derived* in their inheritance. *Tk::Derived* provides methods to allow additional configure options to be defined for a widget. A Composite widget is typically defined as derived from *Tk::Frame* or *Tk::Toplevel* (e.g. *Tk::Dialog*).  File: pm.info, Node: Tk/pTk, Next: Tk/pack, Prev: Tk/overview, Up: Module List how to make your Tk source portable to other interpreted languages. ******************************************************************* NAME ==== Tk2portableTk - how to make your Tk source portable to other interpreted languages. Ilya Zakharevich has contributed most of this document. Many thanks. DESCRIPTION =========== *PortableTk* is an attempt to make Tk useful from other languages. Currently tk4.0 runs under Perl using this approach. Below, *Lang* is the notation for an external language to which *PortableTk* glues Tk code. The main problem with using the code developed for *TCL* with different languages is the absence of data types: almost anything is `char*'. It makes automatic translation hopeless. However, if you `typedef' several new symbols to be `char*', you can still use your code in *TCL*, and it will make the automatic translation possible. Another problem with the approach that "everything is a string" is impossibility to have a result that says "NotApplicable" without setting an error. Thus different Tk command return different string values that mean "error happened", like "", `" "' or `"??"'. Other languages can be more flexible, so in *portableTk* you should inform the compiler that what you want to return means "error" (see `Setting variables' in this node). Currently *PortableTk* uses several different approachs to simplify translation: several *TCL* functions that are especially dangerous to use are undefined, so you can easily find places that need to be updated to use Language-independent functions based on compiler warnings. Eventually a way to use these Language-independent functions under proper *TCL* will be also provided. The end of this document provides a starting point for such a project. Structure of pTk, porting your code =================================== pTk, that is a port of Tk, is very special with respect to porting of other code to *portableTk*. The problem is that currently there is very little hope to merge the modifications back into Tk, so a special strategy is needed to maintain this port. Do not use this strategy to port your own code. pTk is produced from Tk via a two-step process: first, some manual editing (the result is in the subdirectory `mTk'), and second, automatic conversion by the munge script (written in Perl). Thus the subdirectory `pTk/mTk' contains code with minimal possible difference from the virgin Tk code, so it is easier to merge(1) the differences between Tk versions into modified code. It looks like the strategy for a portable code should be exactly opposite: starting from *TCL*-based code, apply munge, and then hand-edit the resulting code. Probably it is also possible to target your code to *portableTk* from scratch, since this will make it possible to run it under a lot of *Lang*uages. The only reason anyone would like to look into contents of `pTk/mTk' directory is to find out which constructs are not supported by munge. On the other hand, pTk directory contains code that is conformant to *portableTk*, so you can look there to find example code. munge is the script that converts most common Tk constructs to their `portableTk' equivalent. For your code to qualify, you should follow Tk conventions on indentation and names of variables, in particular, the array of arguments for the `...CmdProc' should be called `argv'. For details on what munge can do, see `Translation of some TCL functions' in this node. *PortableTk* API ================ Checking what you are running under ----------------------------------- *PortableTk* provides a symbol `????'. If this symbol is defined, your source is compiled with it. New types of configuration options ---------------------------------- *PortableTk* defines several new types of configuration options: TK_CONFIG_CALLBACK TK_CONFIG_LANGARG TK_CONFIG_SCALARVAR TK_CONFIG_HASHVAR TK_CONFIG_ARRAYVAR TK_CONFIG_IMAGE You should use them instead of TK_CONFIG_STRING whenever appropriate. This allows your application to receive a direct representation of the corresponding resource instead of the string representation, if this is possible under given language. ???? It looks like `TK_CONFIG_IMAGE' and `TK_CONFIG_SCALARVAR' set variables of type `char*'. Language data ------------- The following data types are defined: Arg is the main datatype of the language. This is a type that your C function gets pointers to for arguments when the corresponding *Lang* function is called. The corresponding config type is `TK_CONFIG_LANGARG'. This is also a type that keeps information about contents of *Lang* variable. Var Is a substitute for a `char *' that contains name of variable. In *Lang* it is an object that contains reference to another *Lang* variable. `LangResultSave' ???? `LangCallback' `LangCallback*' a substitute for a `char *' that contains command to call. The corresponding config type is `TK_CONFIG_CALLBACK'. `LangFreeProc' It is the type that the `Lang_SplitList' sets. Before you call it, declare Args *args; LangFreeProc *freeProc = NULL; ... code = Lang_SplitList(interp, value, &argc, &args, &freeProc); After you use the split values, call if (args != NULL && freeProc) (*freeProc)(argc,args); It is not guaranteed that the args can survive deletion of value. Conversion ---------- The following macros and functions are used for conversion between strings and the additional types: LangCallback * LangMakeCallback(Arg) Arg LangCallbackArg(LangCallback *) char * LangString(Arg) After you use the result of LangCallbackArg(), you should free it with `freeProc' `LANG_DYNAMIC' (it is not guaranteed that any change of Arg will not be reflected in , so you cannot do LangSet...() in between, and you should reset it to NULL if you want to do any further assignments to this Arg). The following function returns the Arg that is a reference to Var: Arg LangVarArg(Var) ???? It is very anti-intuitive, I hope the name is changed. int LangCmpCallback(LangCallback *a,Arg b) (currently only a stub), and, at last, LangCallback * LangCopyCallback(LangCallback *) Callbacks --------- Above we have seen the new datatype `LangCallback' and the corresponding *Config option* `TK_CONFIG_CALLBACK'. The following functions are provided for manipulation of `LangCallback's: void LangFreeCallback(LangCallback *) int LangDoCallback(Tcl_Interp *,LangCallback *, int result,int argc, char *format,...) The argument format of `LangDoCallback' should contain a string that is suitable for sprintf with optional arguments of `LangDoCallback'. result should be false if result of callback is not needed. int LangMethodCall(Tcl_Interp *,Arg,char *method, int result,int argc,...) ???? Conceptually, `LangCallback*' is a substitute for ubiquitous `char *' in *TCL*. So you should use `LangFreeCallback' instead of `ckfree' or free if appropriate. Setting variables ----------------- void LangFreeArg (Arg, Tcl_FreeProc *freeProc) Arg LangCopyArg (Arg); void Tcl_AppendArg (Tcl_Interp *interp, Arg) void LangSetString(Arg *, char *s) void LangSetDefault(Arg *, char *s) These two are equivalent unless s is an empty string. In this case `LangSetDefault' behaves like `LangSetString' with `s==NULL', i.e., it sets the current value of the *Lang* variable to be false. void LangSetInt(Arg *,int) void LangSetDouble(Arg *,double) The *Lang* functions separate uninitialized and initialized data comparing data with NULL. So the declaration for an Arg should look like Arg arg = NULL; if you want to use this `arg' with the above functions. After you are done, you should use `LangFreeArg' with `TCL_DYNAMIC' as `freeProc'. Language functions ------------------ Use `int LangNull(Arg)' to check that an object is false; `int LangStringMatch(char *string, Arg match)' ???? `void LangExit(int)' to make a proper shutdown; `int LangEval(Tcl_Interp *interp, char *cmd, int global)' to call *Lang* eval; `void Lang_SetErrorCode(Tcl_Interp *interp,char *code)' `char *Lang_GetErrorCode(Tcl_Interp *interp)' `char *Lang_GetErrorInfo(Tcl_Interp *interp)' `void LangCloseHandler(Tcl_Interp *interp,Arg arg,FILE *f,Lang_FileCloseProc *proc)' currently stubs only; `int LangSaveVar(Tcl_Interp *,Arg arg,Var *varPtr,int type)' to save the structure `arg' into *Lang* variable `*varPtr'; `void LangFreeVar(Var var)' to free the result; `int LangEventCallback(Tcl_Interp *,LangCallback *,XEvent *,KeySym)' ???? `int LangEventHook(int flags)' `void LangBadFile(int fd)' `int LangCmpConfig(char *spec, char *arg, size_t length)' unsupported????; `void Tcl_AppendArg (Tcl_Interp *interp, Arg)' Another useful construction is Arg variable = LangFindVar(interp, Tk_Window tkwin, char *name); After using the above function, you should call LangFreeVar(Var variable); ???? Note discrepancy in types! If you want to find the value of a variable (of type Arg) given the variable name, use `Tcl_GetVar(interp, varName, flags)'. If you are interested in the string value of this variable, use `LangString(Tcl_GetVar(...))'. To get a C array of Arg of length n, use Arg *args = LangAllocVec(n); ... LangFreeVec(n,args); You can set the values of the Args using `LangSet...' functions, and get string value using `LangString'. If you want to merge an array of Args into one Arg (that will be an array variable), use result = Tcl_Merge(listLength, list); Translation of some TCL functions --------------------------------- We mark items that can be dealt with by munge by *Autoconverted*. `Tcl_AppendResult' does not take `(char*)NULL', but NULL as delimiter. *Autoconverted*. `Tcl_CreateCommand', `Tcl_DeleteCommand' `Tk_CreateWidget', `Tk_DeleteWidget', the second argument is the window itself, not the pathname. *Autoconverted*. `sprintf(interp->result, "%d %d %d %d",...)' `Tcl_IntResults(interp,4,0,...)'. *Autoconverted*. `interp->result = "1";' `Tcl_SetResult(interp,"1", TCL_STATIC)'. *Autoconverted*. Reading `interp->result' `Tcl_GetResult(interp)'. *Autoconverted*. `interp->result = Tk_PathName(textPtr->tkwin);' `Tk_WidgetResult(interp,textPtr->tkwin)'. *Autoconverted*. Sequence `Tcl_PrintDouble, Tcl_PrintDouble, ..., Tcl_AppendResult' Use a single command void Tcl_DoubleResults(Tcl_Interp *interp, int append, int argc,...); append governs whether it is required to clear the result first. A similar command for int arguments is `Tcl_IntResults'. `Tcl_SplitList' Use `Lang_SplitList' (see the description above). Translation back to TCL ======================= To use your *portableTk* program with *TCL*, put #include "ptcl.h" before inclusion of `tk.h', and link the resulting code with `ptclGlue.c'. These files currently implement the following: Additional config types: TK_CONFIG_CALLBACK TK_CONFIG_LANGARG TK_CONFIG_SCALARVAR TK_CONFIG_HASHVAR TK_CONFIG_ARRAYVAR TK_CONFIG_IMAGE Types: Var, Arg, LangCallback, LangFreeProc. Functions and macros: Lang_SplitList, LangString, LangSetString, LangSetDefault, LangSetInt, LangSetDouble Tcl_ArgResult, LangCallbackArg, LangSaveVar, LangFreeVar, LangFreeSplitProc, LangFreeArg, Tcl_DoubleResults, Tcl_IntResults, LangDoCallback, Tk_WidgetResult, Tcl_CreateCommand, Tcl_DeleteCommand, Tcl_GetResult. Current implementation contains enough to make it possible to compile `mTk/tkText*.[ch]' with the virgin Tk. New types of events ???? ------------------------ PortableTk defines following new types of events: TK_EVENTTYPE_NONE TK_EVENTTYPE_STRING TK_EVENTTYPE_NUMBER TK_EVENTTYPE_WINDOW TK_EVENTTYPE_ATOM TK_EVENTTYPE_DISPLAY TK_EVENTTYPE_DATA and a function char * Tk_EventInfo(int letter, Tk_Window tkwin, XEvent *eventPtr, KeySym keySym, int *numPtr, int *isNum, int *type, int num_size, char *numStorage) Checking for trouble ==================== If you start with working TCL code, you can start convertion using the above hints. Good indication that you are doing is OK is absence of sprintf and sscanf in your code (at least in the part that is working with interpreter). Additional API ============== What is described here is not included into base *portableTk* distribution. Currently it is coded in *TCL* and as Perl macros (core is coded as functions, so theoretically you can use the same object files with different interpreted languages). `ListFactory' ------------- Dynamic arrays in *TCL* are used for two different purposes: to construct strings, and to construct lists. These two usages will have separate interfaces in other languages (since list is a different type from a string), so you should use a different interface in your code. The type for construction of dynamic lists is `ListFactory'. The API below is a counterpart of the API for construction of dynamic lists in *TCL*: void ListFactoryInit(ListFactory *) void ListFactoryFinish(ListFactory *) void ListFactoryFree(ListFactory *) Arg * ListFactoryArg(ListFactory *) void ListFactoryAppend(ListFactory *, Arg *arg) void ListFactoryAppendCopy(ListFactory *, Arg *arg) ListFactory * ListFactoryNewLevel(ListFactory *) ListFactory * ListFactoryEndLevel(ListFactory *) void ListFactoryResult(Tcl_Interp *, ListFactory *) The difference is that a call to `ListFactoryFinish' should precede the actual usage of the value of `ListFactory', and there are two different ways to append an Arg to a `ListFactory': ListFactoryAppendCopy() guarantees that the value of `arg' is copied to the list, but ListFactoryAppend() may append to the list a reference to the current value of `arg'. If you are not going to change the value of `arg' after appending, the call to ListFactoryAppend may be quicker. As in *TCL*, the call to ListFactoryFree() does not free the `ListFactory', only the objects it references. The functions ListFactoryNewLevel() and ListFactoryEndLevel() return a pointer to a `ListFactory' to fill. The argument of ListFactoryEndLevel() cannot be used after a call to this function. DStrings -------- Production of strings are still supported in *portableTk*. Accessing Args -------------- The following functions for getting a value of an Arg may be provided: double LangDouble(Arg) int LangInt(Arg) long LangLong(Arg) int LangIsList(Arg arg) The function LangIsList() is supported only partially under *TCL*, since there is no data types. It checks whether there is a space inside the string `arg'. Assigning numbers to Args ------------------------- While LangSetDouble() and LangSetInt() are supported ways to assign numbers to assign an integer value to a variable, for the sake of efficiency under *TCL* it is supposed that the destination of these commands was massaged before the call so it contains a long enough string to sprintf() the numbers inside it. If you are going to immediately use the resulting Arg, the best way to do this is to declare a buffer in the beginning of a block by dArgBuffer; and assign this buffer to the Arg by void LangSetDefaultBuffer(Arg *) You can also create the buffer(s) manually and assign them using void LangSetBuffer(Arg *, char *) This is the only choice if you need to assign numeric values to several Args simultaneously. The advantage of the first approach is that the above declarations can be made nops in different languages. Note that if you apply `LangSetDefaultBuffer' to an Arg that contains some value, you can create a leak if you do not free that Arg first. This is a non-problem in real languages, but can be a trouble in `TCL', unless you use only the above API. Creating new Args ----------------- The API for creating a new Arg is void LangNewArg(Arg *, LangFreeProc *) The API for creating a new Arg is absent. Just initialize Arg to be NULL, and apply one of `LangSet...' methods. After you use this Arg, it should be freed thusly: `LangFreeArg(arg, freeProc)'. Evaluating a list ----------------- Use int LangArgEval(Tcl_Interp *, Arg arg) Here `arg' should be a list to evaluate, in particular, the first element should be a `LangCallback' massaged to be an Arg. The arguments can be send to the subroutine by reference or by value in different languages. Getting result as Arg --------------------- Use `Tcl_ArgResult'. It is not guaranteed that result survives this operation, so the Arg you get should be the only mean to access the data from this moment on. After you use this Arg, you should free it with `freeProc' `LANG_DYNAMIC' (you can do LangSet...() in between).