diff options
Diffstat (limited to 'Master/tlpkg/tlperl/lib/Tk/options.pod')
-rw-r--r-- | Master/tlpkg/tlperl/lib/Tk/options.pod | 787 |
1 files changed, 0 insertions, 787 deletions
diff --git a/Master/tlpkg/tlperl/lib/Tk/options.pod b/Master/tlpkg/tlperl/lib/Tk/options.pod deleted file mode 100644 index 49d81ddd2b4..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/options.pod +++ /dev/null @@ -1,787 +0,0 @@ -# Copyright (c) 1990-1994 The Regents of the University of California. -# Copyright (c) 1994-1996 Sun Microsystems, Inc. -# See the file "license.terms" for information on usage and redistribution -# of this file, and for a DISCLAIMER OF ALL WARRANTIES. -# -# - -=head1 NAME - -Tk::options - Standard options supported by widgets and their manipulation - -=for category Creating and Configuring Widgets - -=head1 SYNOPSIS - -S< >I<$value> = I<$widget>-E<gt>B<cget>('I<-option>'); - -S< >I<$widget>-E<gt>B<configure>(I<-option>=E<gt>I<value> ?,I<-option>=E<gt>I<value> ...?); - -S< >I<@list> = I<$widget>-E<gt>B<configure>('I<-option>'); - -S< >I<@lol> = I<$widget>-E<gt>B<configure>; - -=head1 DESCRIPTION - -All widgets, and images have a standard mechanism for setting and querying -attibutes or options. The mechanism is based on two methods B<configure> -and B<cget>. The behaviour of these methods is as follows: - -=over 4 - -=item I<$widget>-E<gt>B<configure>(I<-option>=E<gt>I<value> ?,I<-option>=E<gt>I<value> ...?); - -Sets the values of I<-option> to I<value> for each I<-option>=E<gt>I<value> -pair. The internal B<new> method does an implicit B<configure> in this -form with options passed in at widget create time. - -=item I<$widget>-E<gt>B<configure>('I<-option>') - -In array context returns a list of five or two elements. If I<-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., -C<('-bg', 'background')>. If I<-option> is not an alias the returned -list has the following five elements: - -=over 8 - -=item I<Option Name> - -The value of I<-option>, e.g., B<-background>. - -=item I<Name> - -The option's name in the option database, e.g., C<background>. - -=item I<Class> - -The option's class value in the option database, e.g., C<Background>. - -=item I<Default> - -The default value for the option if not specified or in the option database, -e.g., C<grey>. - -=item I<Value> - -The current value (as returned by B<cget>), e.g., C<white>. - -=back - -=item I<$widget>-E<gt>B<configure> - -Returns a list of lists for all the options supported by I<$widget>. -Each sub-list is in the form returned by B<configure>('I<-option>'). -(This mechanism is used by the B<Tk::Derived> class to determine -the options available from base class.) - -=item I<$widget>-E<gt>B<cget>('I<-option>') - -Returns the current value of I<-option> for I<$widget>. - -B<cget>('I<-option>') is clumsy with the need for B<''> due to perl's -parsing rules. Something more subtle using L<tie|perlfunc/tie> might look better. - -=back - -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 B<configure> widget methods to set this value. For example, if an option's -configure option is B<-foreground> and there exists a widget I<$widget>, then the -call: - -S< >I<$widget>-E<gt>B<configure>(B<-foreground>=E<gt>B<'black'>) - -may be used to specify the value B<black> for the option in the widget I<$widget>. -Configure options may be abbreviated, as long as the abbreviation is unambiguous -(abbreviation is deprecated in perl/Tk). - -=head2 Creation options: Widget Name and Class - -The B<Name> and B<-class> options can only be specified when a widget is -created, and cannot be changed with B<configure>. These options determine -the widget's identity and how Tk applies resource values from the -option database (see L<Tk::option>) and so they -cannot be assigned by the options database. - -=over 4 - -=item Name: I<name> - -=item Switch: B<Name> - -Specifies the path element for the widget. Names generally begin with a -lowercase letter. - -Each widget has a unique I<pathname> that follows the hierarchy from the -B<MainWindow> to the widget itself. Since the widget's B<PathName> is -used to assign options from the options database, it is important to -specify a distinctive B<Name> for any widget that will have non-default -options. See L<Tk::option> for details. - -=item Name: I<class> - -=item Switch: B<-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 B<TopLevel> or B<Frame> so that the class will apply to all of -that widget's children. - -=back - -=head2 Reconfigurable options - -These options can be set at widget creation or changed later via B<configure>. - -=over 4 - -=item Name: B<activeBackground> - -=item Class: B<Foreground> - -=item Switch: B<-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 -B<$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. - -=item Name: B<activeBorderWidth> - -=item Class: B<BorderWidth> - -=item Switch: B<-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 B<Tk_GetPixels>. -This option is typically only available in widgets displaying more -than one element at a time (e.g. menus but not buttons). - -=item Name: B<activeForeground> - -=item Class: B<Background> - -=item Switch: B<-activeforeground> - -Specifies foreground color to use when drawing active elements. -See above for definition of active elements. - -=item Name: B<activetile> - -=item Class: B<Tile> - -=item Switch: B<-activetile> - -Specifies image used to display inside active elements of the widget. -See above for definition of active elements. - -=item Name: B<anchor> - -=item Class: B<Anchor> - -=item Switch: B<-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 B<n>, B<ne>, B<e>, B<se>, -B<s>, B<sw>, B<w>, B<nw>, or B<center>. -For example, B<nw> means display the information such that its -top-left corner is at the top-left corner of the widget. - -=item Name: B<background> - -=item Class: B<Background> - -=item Switch: B<-background> - -=item Alias: B<-bg> - -Specifies the normal background color to use when displaying the -widget. - -=item Name: B<bitmap> - -=item Class: B<Bitmap> - -=item Switch: B<-bitmap> - -Specifies a bitmap to display in the widget, in any of the forms -acceptable to B<Tk_GetBitmap>. -The exact way in which the bitmap is displayed may be affected by -other options such as B<-anchor> or B<-justify>. -Typically, if this option is specified then it overrides other -options that specify a textual value to display in the widget; -the B<-bitmap> option may be reset to an empty string to re-enable -a text display. -In widgets that support both B<-bitmap> and B<-image> options, -B<-image> will usually override B<-bitmap>. - -=item Name: B<borderWidth> - -=item Class: B<BorderWidth> - -=item Switch: B<-borderwidth> - -=item Alias: B<-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 B<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 B<Tk_GetPixels>. - -=item Name: B<compound> - -=item Class: B<Compound> - -=item Switch: B<-compound> - -Specifies if the widget should display text and bitmaps/images at the -same time, and if so, where the bitmap/image should be placed relative -to the text. Must be one of the values B<none>, B<bottom>, B<top>, -B<left>, B<right>, or B<center>. For example, the (default) value -B<none> specifies that the bitmap or image should (if defined) be -displayed instead of the text, the value B<left> specifies that the -bitmap or image should be displayed to the left of the text, and the -value B<center> specifies that the bitmap or image should be displayed on -top of the text. - -=item Name: B<cursor> - -=item Class: B<Cursor> - -=item Switch: B<-cursor> - -Specifies the mouse cursor to be used for the widget. -The value may have any of the forms acceptable to B<Tk_GetCursor>. - -=item Name: B<dash> - -=item Class: B<Dash> - -=item Switch: B<-dash> - -The value may have any of the forms accepted by B<Tk_GetDash>, -such as B<4>, B<[6,4]>, B<.>, B<->, B<-.>, or B<-..>. - -=item Name: B<dashoffset> - -=item Class: B<Dashoffset> - -=item Switch: B<-dashoffset> - -Specifies the offset in the dash list where the drawing starts. - -=item Name: B<disabledForeground> - -=item Class: B<DisabledForeground> - -=item Switch: B<-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. - -=item Name: B<disabledtile> - -=item Class: B<Tile> - -=item Switch: B<-disabledtile> - -Specifies image to use when drawing a disabled element. - -=item Name: B<exportSelection> - -=item Class: B<ExportSelection> - -=item Switch: B<-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 B<Tcl_GetBoolean>, -such as B<true>, B<false>, B<0>, B<1>, B<yes>, or B<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. - -=item Name: B<font> - -=item Class: B<Font> - -=item Switch: B<-font> - -Specifies the font to use when drawing text inside the widget. - -=item Name: B<foreground> - -=item Class: B<Foreground> - -=item Switch: B<-foreground> - -=item Alias: B<-fg> - -Specifies the normal foreground color to use when displaying the widget. - -=item Name: B<highlightBackground> - -=item Class: B<HighlightBackground> - -=item Switch: B<-highlightbackground> - -Specifies the color to display in the traversal highlight region when -the widget does not have the input focus. - -=item Name: B<highlightColor> - -=item Class: B<HighlightColor> - -=item Switch: B<-highlightcolor> - -Specifies the color to use for the traversal highlight rectangle that is -drawn around the widget when it has the input focus. - -=item Name: B<highlightThickness> - -=item Class: B<HighlightThickness> - -=item Switch: B<-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 B<Tk_GetPixels>. -If the value is zero, no focus highlight is drawn around the widget. - -=item Name: B<image> - -=item Class: B<Image> - -=item Switch: B<-image> - -Specifies an image to display in the widget, which must have been -created with an image create. (See L<Tk::Image> for details of image creation.) -Typically, if the B<-image> option is specified then it overrides other -options that specify a bitmap or textual value to display in the widget; -the B<-image> option may be reset to an empty string to re-enable -a bitmap or text display. - -=item Name: B<insertBackground> - -=item Class: B<Foreground> - -=item Switch: B<-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). - -=item Name: B<insertBorderWidth> - -=item Class: B<BorderWidth> - -=item Switch: B<-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 B<Tk_GetPixels>. - -=item Name: B<insertOffTime> - -=item Class: B<OffTime> - -=item Switch: B<-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. - -=item Name: B<insertOnTime> - -=item Class: B<OnTime> - -=item Switch: B<-insertontime> - -Specifies a non-negative integer value indicating the number of -milliseconds the insertion cursor should remain ``on'' in each blink cycle. - -=item Name: B<insertWidth> - -=item Class: B<InsertWidth> - -=item Switch: B<-insertwidth> - -Specifies a value indicating the total width of the insertion cursor. -The value may have any of the forms acceptable to B<Tk_GetPixels>. -If a border has been specified for the insertion -cursor (using the B<insertBorderWidth> option), the border -will be drawn inside the width specified by the B<insertWidth> -option. - -=item Name: B<jump> - -=item Class: B<Jump> - -=item Switch: B<-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 -B<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). - -=item Name: B<justify> - -=item Class: B<Justify> - -=item Switch: B<-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 B<left>, B<center>, or B<right>. -B<Left> means that the lines' left edges all line up, B<center> -means that the lines' centers are aligned, and B<right> means -that the lines' right edges line up. - -=item Name: B<offset> - -=item Class: B<Offset> - -=item Switch: B<-offset> - -Specifies the offset of tiles (see also B<-tile> option). It can -have two different formats B<-offset x,y> or B<-offset side>, -where side can be B<n>, B<ne>, B<e>, B<se>, B<s>, -B<sw>, B<w>, B<nw>, or B<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 B<#> in front of the coordinate pair -indicates using the toplevel origin in stead. For canvas objects, -the B<-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. - -=item Name: B<orient> - -=item Class: B<Orient> - -=item Switch: B<-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 B<horizontal> -or B<vertical> or an abbreviation of one of these. - -=item Name: B<padX> - -=item Class: B<Pad> - -=item Switch: B<-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 B<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. - -=item Name: B<padY> - -=item Class: B<Pad> - -=item Switch: B<-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 B<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. - -=item Name: B<relief> - -=item Class: B<Relief> - -=item Switch: B<-relief> - -Specifies the 3-D effect desired for the widget. Acceptable -values are B<raised>, B<sunken>, B<flat>, B<ridge>, -B<solid>, and B<groove>. -The value -indicates how the interior of the widget should appear relative -to its exterior; for example, B<raised> means the interior of -the widget should appear to protrude from the screen, relative to -the exterior of the widget. - -=item Name: B<repeatDelay> - -=item Class: B<RepeatDelay> - -=item Switch: B<-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. - -=item Name: B<repeatInterval> - -=item Class: B<RepeatInterval> - -=item Switch: B<-repeatinterval> - -Used in conjunction with B<repeatDelay>: once auto-repeat -begins, this option determines the number of milliseconds between -auto-repeats. - -=item Name: B<selectBackground> - -=item Class: B<Foreground> - -=item Switch: B<-selectbackground> - -Specifies the background color to use when displaying selected -items. - -=item Name: B<selectBorderWidth> - -=item Class: B<BorderWidth> - -=item Switch: B<-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 B<Tk_GetPixels>. - -=item Name: B<selectForeground> - -=item Class: B<Background> - -=item Switch: B<-selectforeground> - -Specifies the foreground color to use when displaying selected -items. - -=item Name: B<setGrid> - -=item Class: B<SetGrid> - -=item Switch: B<-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 B<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 L<Tk::Wm/"GRIDDED GEOMETRY MANAGEMENT"> -for more details. - -=item Name: B<takeFocus> - -=item Class: B<TakeFocus> - -=item Switch: B<-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 B<takeFocus> option. -A value of B<0> means that the window should be skipped entirely -during keyboard traversal. -B<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 B<0>, B<1>, or an empty string: a -B<0> or B<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. - -=item Name: B<text> - -=item Class: B<Text> - -=item Switch: B<-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 B<anchor> or B<justify>. - -=item Name: B<textVariable> - -=item Class: B<Variable> - -=item Switch: B<-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 -B<anchor> or B<justify>. - -=item Name: B<tile> - -=item Class: B<Tile> - -=item Switch: B<-tile> - -Specifies image used to display the widget. If image is the empty -string, then the normal background color is displayed. - -=item Name: B<troughColor> - -=item Class: B<Background> - -=item Switch: B<-troughcolor> - -Specifies the color to use for the rectangular trough areas -in widgets such as scrollbars and scales. - -=item Name: B<troughTile> - -=item Class: B<Tile> - -=item Switch: B<-troughtile> - -Specifies image used to display in the rectangular trough areas -in widgets such as scrollbars and scales. - -=item Name: B<underline> - -=item Class: B<Underline> - -=item Switch: B<-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. - -=item Name: B<wrapLength> - -=item Class: B<WrapLength> - -=item Switch: B<-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. - -=item Name: B<xScrollCommand> - -=item Class: B<ScrollCommand> - -=item Switch: B<-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 -B<xScrollCommand> option consists of the scrollbar widget object -and the method ``set'' i.e. [B<set> =E<gt> I<$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. - -=item Name: B<yScrollCommand> - -=item Class: B<ScrollCommand> - -=item Switch: B<-yscrollcommand> - -Specifies a calback used to communicate with vertical -scrollbars. This option is treated in the same way as the -B<xScrollCommand> option, except that it is used for vertical -scrollbars and is provided by widgets that support vertical scrolling. -See the description of B<xScrollCommand> for details -on how this option is used. - -=back - -=head1 SEE ALSO - -L<Tk::option> -L<Tk::callbacks> -L<Tk::ConfigSpecs> -L<Tk_GetPixels|Tk::pTk::GetPixels> - -=head1 KEYWORDS - -class, name, standard option, switch - -=cut - |