summaryrefslogtreecommitdiff
path: root/Master/tlpkg/tlperl/lib/Tk/Button.pod
diff options
context:
space:
mode:
Diffstat (limited to 'Master/tlpkg/tlperl/lib/Tk/Button.pod')
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/Button.pod255
1 files changed, 255 insertions, 0 deletions
diff --git a/Master/tlpkg/tlperl/lib/Tk/Button.pod b/Master/tlpkg/tlperl/lib/Tk/Button.pod
new file mode 100644
index 00000000000..2eb6401ca9d
--- /dev/null
+++ b/Master/tlpkg/tlperl/lib/Tk/Button.pod
@@ -0,0 +1,255 @@
+# 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::Button - Create and manipulate Button widgets
+
+=for category Tk Widget Classes
+
+=head1 SYNOPSIS
+
+I<$button> = I<$parent>-E<gt>B<Button>(?I<options>?);
+
+=head1 STANDARD OPTIONS
+
+B<-activebackground>
+B<-activeforeground>
+B<-anchor>
+B<-background>
+B<-bitmap>
+B<-borderwidth>
+B<-compound>
+B<-cursor>
+B<-disabledforeground>
+B<-font>
+B<-foreground>
+B<-highlightbackground>
+B<-highlightcolor>
+B<-highlightthickness>
+B<-image>
+B<-justify>
+B<-padx>
+B<-pady>
+B<-relief>
+B<-repeatdelay>
+B<-repeatinterval>
+B<-takefocus>
+B<-text>
+B<-textvariable>
+B<-underline>
+B<-wraplength>
+
+See L<Tk::options> for details of the standard options.
+
+=head1 WIDGET-SPECIFIC OPTIONS
+
+=over 4
+
+=item Name: B<command>
+
+=item Class: B<Command>
+
+=item Switch: B<-command>
+
+Specifies a L<Perl/Tk callback|Tk::callbacks> to associate with the
+button. This command is typically invoked when mouse button 1 is
+released over the button window.
+
+=item Command-Line Name: B<-compound>
+
+=item Database Name: B<compound>
+
+=item Database Class: B<Compound>
+
+Specifies whether the button should display both an image and text,
+and if so, where the image should be placed relative to the text.
+Valid values for this option are B<bottom>, B<center>, B<left>,
+B<none>, B<right> and B<top>. The default value is B<none>, meaning
+that the button will display either an image or text, depending on the
+values of the -image and -bitmap options.
+
+=item Name: B<default>
+
+=item Class: B<Default>
+
+=item Switch: B<-default>
+
+Specifies one of three states for the default ring: B<normal>,
+B<active>, or B<disabled>. In active state, the button is drawn
+with the platform specific appearance for a default button. In normal
+state, the button is drawn with the platform specific appearance for a
+non-default button, leaving enough space to draw the default button
+appearance. The normal and active states will result in buttons of
+the same size. In disabled state, the button is drawn with the
+non-default button appearance without leaving space for the default
+appearance. The disabled state may result in a smaller button than
+the active state.
+ring.
+
+=item Name: B<height>
+
+=item Class: B<Height>
+
+=item Switch: B<-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 B<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.
+
+=item Command-Line Name: B<-overrelief>
+
+=item Database Name: B<overRelief>
+
+=item Database Class: B<OverRelief>
+
+Specifies an alternative relief for the button, to be used when
+the mouse cursor is over the widget. This option can be used to
+make toolbar buttons, by configuring B<-relief flat -overrelief
+raised>. If the value of this option is the empty string, then
+no alternative relief is used when the mouse cursor is over the
+button. The empty string is the default value.
+
+=item Name: B<state>
+
+=item Class: B<State>
+
+=item Switch: B<-state>
+
+Specifies one of three states for the button: B<normal>, B<active>,
+or B<disabled>. In normal state the button is displayed using the
+B<foreground> and B<background> options. The active state is
+typically used when the pointer is over the button. In active state
+the button is displayed using the B<activeForeground> and
+B<activeBackground> options. Disabled state means that the button
+should be insensitive: the default bindings will refuse to activate
+the widget and will ignore mouse button presses.
+In this state the B<disabledForeground> and
+B<background> options determine how the button is displayed.
+
+=item Name: B<width>
+
+=item Class: B<Width>
+
+=item Switch: B<-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 B<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.
+
+=back
+
+=head1 DESCRIPTION
+
+The B<Button> method creates a new window (given by the
+$widget argument) and makes it into a button widget.
+Additional
+options, described above, may be specified on the command line
+or in the option database
+to configure aspects of the button such as its colors, font,
+text, and initial relief. The B<button> 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 button is a widget that displays a textual string, bitmap or image.
+If text is displayed, it must all be in a single font, but it
+can occupy multiple lines on the screen (if it contains newlines
+or if wrapping occurs because of the B<-wraplength> option) and
+one of the characters may optionally be underlined using the
+B<-underline> option.
+It can display itself in either of three different ways, according
+to
+the B<-state> option;
+it can be made to appear raised, sunken, or flat;
+and it can be made to flash. When a user invokes the
+button (by pressing mouse button 1 with the cursor over the
+button), then the L<perl/Tk callback|Tk::callbacks> specified in the B<-command>
+option is invoked.
+
+=head1 WIDGET METHODS
+
+The B<Button> method creates a widget object.
+This object supports the B<configure> and B<cget> methods
+described in L<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
+L<Tk::Widget|Tk::Widget> class.
+
+The following additional methods are available for button widgets:
+
+=over 4
+
+=item I<$button>-E<gt>B<flash>
+
+Flash the button. This is accomplished by redisplaying the button
+several times, alternating between active and normal colors. At
+the end of the flash the button is left in the same normal/active
+state as when the command was invoked.
+This command is ignored if the button's state is B<disabled>.
+
+=item I<$button>-E<gt>B<invoke>
+
+Invoke the L<callback|Tk::callbacks> associated with the buttons
+B<-command> option, if there is one.
+The return value is the return value from the callback, or the
+undefined value if there is no callback associated with the button.
+This command is ignored if the button's state is B<disabled>.
+
+=back
+
+=head1 DEFAULT BINDINGS
+
+Tk automatically creates class bindings for buttons that give them
+default behavior:
+
+=over 4
+
+=item [1]
+
+A button activates whenever the mouse passes over it and deactivates
+whenever the mouse leaves the button.
+Under Windows, this binding is only active when mouse button 1 has
+been pressed over the button.
+
+=item [2]
+
+A button's relief is changed to sunken whenever mouse button 1 is
+pressed over the button, and the relief is restored to its original
+value when button 1 is later released.
+
+=item [3]
+
+If mouse button 1 is pressed over a button and later released over
+the button, the button is invoked. However, if the mouse is not
+over the button when button 1 is released, then no invocation occurs.
+
+=item [4]
+
+When a button has the input focus, the space key causes the button
+to be invoked.
+
+If the button's state is B<disabled> then none of the above
+actions occur: the button is completely non-responsive.
+
+The behavior of buttons can be changed by defining new bindings for
+individual widgets or by redefining the class bindings.
+
+=back
+
+=head1 KEYWORDS
+
+button, widget
+
+=cut
+