| 1 | |
| 2 | =head1 NAME |
| 3 | |
| 4 | Tk::DialogBox - create and manipulate a dialog screen. |
| 5 | |
| 6 | =for pm Tixish/DialogBox.pm |
| 7 | |
| 8 | =for category Tix Extensions |
| 9 | |
| 10 | =head1 SYNOPSIS |
| 11 | |
| 12 | use Tk::DialogBox |
| 13 | ... |
| 14 | $d = $top->DialogBox(-title => "Title", -buttons => ["OK", "Cancel"]); |
| 15 | $w = $d->add(Widget, args); |
| 16 | ... |
| 17 | $button = $d->Show; |
| 18 | |
| 19 | =head1 DESCRIPTION |
| 20 | |
| 21 | B<DialogBox> is very similar to B<Dialog> except that it allows |
| 22 | any widget in the top frame. B<DialogBox> creates two |
| 23 | frames---"top" and "bottom". The bottom frame shows all the |
| 24 | specified buttons, lined up from left to right. The top frame acts |
| 25 | as a container for all other widgets that can be added with the |
| 26 | B<add()> method. The non-standard options recognized by |
| 27 | B<DialogBox> are as follows: |
| 28 | |
| 29 | =over 4 |
| 30 | |
| 31 | =item B<-title> |
| 32 | |
| 33 | Specify the title of the dialog box. If this is not set, then the |
| 34 | name of the program is used. |
| 35 | |
| 36 | =item B<-buttons> |
| 37 | |
| 38 | The buttons to display in the bottom frame. This is a reference to |
| 39 | an array of strings containing the text to put on each |
| 40 | button. There is no default value for this. If you do not specify |
| 41 | any buttons, no buttons will be displayed. |
| 42 | |
| 43 | =item B<-default_button> |
| 44 | |
| 45 | Specifies the default button that is considered invoked when user |
| 46 | presses <Return> on the dialog box. This button is highlighted. If |
| 47 | no default button is specified, then the first element of the |
| 48 | array whose reference is passed to the B<-buttons> option is used |
| 49 | as the default. |
| 50 | |
| 51 | =back |
| 52 | |
| 53 | =head1 METHODS |
| 54 | |
| 55 | B<DialogBox> supports only two methods as of now: |
| 56 | |
| 57 | =over 4 |
| 58 | |
| 59 | =item B<add(>I<widget>, I<options>B<)> |
| 60 | |
| 61 | Add the widget indicated by I<widget>. I<Widget> can be the name |
| 62 | of any Tk widget (standard or contributed). I<Options> are the |
| 63 | options that the widget accepts. The widget is advertized as a |
| 64 | subwidget of B<DialogBox>. |
| 65 | |
| 66 | =item B<Show(>I<grab>B<)> |
| 67 | |
| 68 | Display the dialog box, until user invokes one of the buttons in |
| 69 | the bottom frame. If the grab type is specified in I<grab>, then |
| 70 | B<Show> uses that grab; otherwise it uses a local grab. Returns |
| 71 | the name of the button invoked. |
| 72 | |
| 73 | =back |
| 74 | |
| 75 | =head1 BUGS |
| 76 | |
| 77 | There is no way of removing a widget once it has been added to the |
| 78 | top frame. |
| 79 | |
| 80 | There is no control over the appearance of the buttons in the |
| 81 | bottom frame nor is there any way to control the placement of the |
| 82 | two frames with respect to each other e.g. widgets to the left, |
| 83 | buttons to the right instead of widgets on the top and buttons on |
| 84 | the bottom always. |
| 85 | |
| 86 | =head1 AUTHOR |
| 87 | |
| 88 | B<Rajappa Iyer> rsi@earthling.net |
| 89 | |
| 90 | This code is distributed under the same terms as Perl. |
| 91 | |
| 92 | =cut |
| 93 | |