1 files changed, 156 insertions, 0 deletions
diff --git a/Master/tlpkg/tlperl/lib/Tk/DialogBox.pod b/Master/tlpkg/tlperl/lib/Tk/DialogBox.pod
new file mode 100644
index 00000000000..a091cd98427
--- /dev/null
+++ b/Master/tlpkg/tlperl/lib/Tk/DialogBox.pod
@@ -0,0 +1,156 @@
+
+=head1 NAME
+
+Tk::DialogBox - create and manipulate a dialog screen.
+
+=for pm Tixish/DialogBox.pm
+
+=for category Tix Extensions
+
+=head1 SYNOPSIS
+
+    use Tk::DialogBox
+    ...
+    $d = $top->DialogBox(-title => "Title", -buttons => ["OK", "Cancel"]);
+    $w = $d->add(Widget, args)->pack;
+    ...
+    $button = $d->Show;
+
+=head1 DESCRIPTION
+
+B<DialogBox> is very similar to B<Dialog> except that it allows
+any widget in the top Frame. B<DialogBox> creates two
+Frames, I<top> and I<bottom>. The bottom Frame shows all the
+specified Buttons, lined up from left to right. The top Frame acts
+as a container for all other widgets that can be added with the
+B<add()> method.
+
+=head1 OPTIONS
+
+The options recognized by B<DialogBox> are as follows:
+
+=over 4
+
+=item B<-title>
+
+Specify the title of the DialogBox. If this is not set, then the
+name of the program is used.
+
+=item B<-buttons>
+
+The button names to display in the bottom Frame. This is a reference
+to an array of strings containing the text to put on each
+Button. There is no default value for this. If you do not specify any
+button names, no Buttons are displayed.
+
+=item B<-default_button>
+
+Specifies the default Button that is considered invoked when user
+presses <Return> on the DialogBox. This Button is highlighted. If
+no default Button is specified, then the first element of the
+array whose reference is passed to the B<-buttons> option is used
+as the default.
+
+=item B<-cancel_button>
+
+Specifies the Button that is considered invoked when the user closes
+the DialogBox using the window manager's close button. If the
+B<-cancel_button> option is not given, and if there's only one button
+configured, then this button is also used as the cancel button.
+Otherwise no button is considered as the cancel button; in such a case
+B<Show> just returns C<undef> when the user closes the DialogBox.
+
+=item B<-command>
+
+A callback which is executed after invoking an action to close the
+DialogBox, but before restoring focus and grab information. The
+selected button is passed as the first argument.
+
+=item B<-focus>
+
+Specify the widget to receive the initial focus after popping up the
+DialogBox. By default the B<-default_button> widget receives the
+initial focus.
+
+=item B<-showcommand>
+
+A callback which is executed before displaying the DialogBox and
+waiting for user input. The DialogBox itself is passed as the first
+argument.
+
+=back
+
+=head1 METHODS
+
+B<DialogBox> supports only two methods as of now:
+
+=over 4
+
+=item B<add(>I<widget>, I<options>B<)>
+
+Add the widget indicated by I<widget>. I<Widget> can be the name
+of any Tk widget (standard or contributed). I<options> are the
+options that the widget accepts. The widget is advertized as a
+subwidget of B<DialogBox>. The name of I<widget> is
+lower-cased and used as the advertised name. If multiple instances of
+I<widget> are created in the B<DialogBox>, then only the last one gets
+the advertised name. B<add()> does not automatically B<pack()> or
+B<grid()> I<widget> into the B<DialogBox>.
+
+=item B<Show(>I<?-global?>B<)>
+
+Displays the Dialog until the user invokes one of the Buttons in the
+bottom Frame. If the grab type I<-global> is specified, then B<Show>
+uses that grab; otherwise it defaults to a local grab. Returns the
+name of the Button invoked.
+
+The actual Dialog is shown using the B<Popup> method. Any other
+options supplied to B<Show> are passed to B<Popup>, and can be used to
+position the Dialog on the screen. Please read Tk::Popup for details.
+
+=item B<Exit()>
+
+Close the dialogbox, by emulating a click on the default button.
+
+=back
+
+=head1 ADVERTISED WIDGETS
+
+=over 4
+
+=item B<top>
+
+The subwidget reference to the top half of the DialogBox widget, the Frame
+containing widgets added by the B<add> method.
+
+=item B<bottom>
+
+The subwidget reference to the bottom half of the DialogBox widget, the Frame
+containing the Button widgets.
+
+=item B<B_"button-text">
+
+Individual subwidget references to the Buttons in the DialogBox widget. The
+subwidget name is the string I<B_> concatenated with the Button's -text
+value.
+
+=back
+
+=head1 BUGS
+
+There is no way of removing a widget once it has been added to the
+top Frame, unless you access the I<top> subwidget and go through the
+child widgets.
+
+There is no control over the appearance of the Buttons in the
+bottom Frame nor is there any way to control the placement of the
+two Frames with respect to each other.
+
+=head1 AUTHOR
+
+B<Rajappa Iyer> rsi@earthling.net
+
+This code is distributed under the same terms as Perl.
+
+=cut
+