home *** CD-ROM | disk | FTP | other *** search
/ Netrunner 2004 October / NETRUNNER0410.ISO / regular / ActivePerl-5.8.4.810-MSWin32-x86.msi / _a926f27f2c707d3cfc0f9a5476afe963 < prev    next >
Encoding:
Text File  |  2004-06-01  |  4.3 KB  |  163 lines
  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, I<top> and I<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.
  27.  
  28. =head1 OPTIONS
  29.  
  30. The options recognized by B<DialogBox> are as follows:
  31.  
  32. =over 4
  33.  
  34. =item B<-title>
  35.  
  36. Specify the title of the DialogBox. If this is not set, then the
  37. name of the program is used.
  38.  
  39. =item B<-buttons>
  40.  
  41. The button names to display in the bottom Frame. This is a reference
  42. to an array of strings containing the text to put on each
  43. Button. There is no default value for this. If you do not specify any
  44. button names, no Buttons are displayed.
  45.  
  46. =item B<-default_button>
  47.  
  48. Specifies the default Button that is considered invoked when user
  49. presses <Return> on the DialogBox. This Button is highlighted. If
  50. no default Button is specified, then the first element of the
  51. array whose reference is passed to the B<-buttons> option is used
  52. as the default.
  53.  
  54. =item B<-command>
  55.  
  56. A callback which is executed after invoking an action to close the
  57. DialogBox, but before restoring focus and grab information. The
  58. selected button is passed as the first argument.
  59.  
  60. =item B<-focus>
  61.  
  62. Specify the widget to receive the initial focus after popping up the
  63. DialogBox. By default the B<-default_button> widget receives the
  64. initial focus.
  65.  
  66. =item B<-showcommand>
  67.  
  68. A callback which is executed before displaying the DialogBox and
  69. waiting for user input. The DialogBox itself is passed as the first
  70. argument.
  71.  
  72. =back
  73.  
  74. =head1 METHODS
  75.  
  76. B<DialogBox> supports only two methods as of now:
  77.  
  78. =over 4
  79.  
  80. =item B<add(>I<widget>, I<options>B<)>
  81.  
  82. Add the widget indicated by I<widget>. I<Widget> can be the name
  83. of any Tk widget (standard or contributed). I<options> are the
  84. options that the widget accepts. The widget is advertized as a
  85. subwidget of B<DialogBox>. The first character of I<widget> is
  86. lower-cased and used as the advertised name.
  87.  
  88. =item B<Show(>I<?-global?>B<)>
  89.  
  90. Displays the Dialog until the user invokes one of the Buttons in the
  91. bottom Frame. If the grab type I<-global> is specified, then B<Show>
  92. uses that grab; otherwise it defaults to a local grab. Returns the
  93. name of the Button invoked.
  94.  
  95. The actual Dialog is shown using the B<Popup> method. Any other
  96. options supplied to B<Show> are passed to B<Popup>, and can be used to
  97. position the Dialog on the screen. Please read Tk::Popup for details.
  98.  
  99. =back
  100.  
  101. =head1 ADVERTISED WIDGETS
  102.  
  103. =over 4
  104.  
  105. =item B<top>
  106.  
  107. The subwidget reference to the top half of the DialogBox widget, the Frame
  108. containing widgets added by the B<add> method.
  109.  
  110. =item B<bottom>
  111.  
  112. The subwidget reference to the bottom half of the DialogBox widget, the Frame
  113. containing the Button widgets.
  114.  
  115. =item B<B_"button-text">
  116.  
  117. Individual subwidget references to the Buttons in the DialogBox widget. The
  118. subwidget name is the string I<B_> concatenated with the Button's -text
  119. value.
  120.  
  121. =back
  122.  
  123. =head1 ADVERTISED WIDGETS
  124.  
  125. =over 4
  126.  
  127. =item B<top>
  128.  
  129. The subwidget reference to the top half of the DialogBox widget, the Frame
  130. containing widgets added by the B<add> method.
  131.  
  132. =item B<bottom>
  133.  
  134. The subwidget reference to the bottom half of the DialogBox widget, the Frame
  135. containing the Button widgets.
  136.  
  137. =item B<B_"button-text">
  138.  
  139. Individual subwidget references to the Buttons in the DialogBox widget. The
  140. subwidget name is the string I<B_> concatenated with the Button's -text
  141. value.
  142.  
  143. =back
  144.  
  145. =head1 BUGS
  146.  
  147. There is no way of removing a widget once it has been added to the
  148. top Frame, unless you access the I<top> subwidget and go through the
  149. child widgets.
  150.  
  151. There is no control over the appearance of the Buttons in the
  152. bottom Frame nor is there any way to control the placement of the
  153. two Frames with respect to each other.
  154.  
  155. =head1 AUTHOR
  156.  
  157. B<Rajappa Iyer> rsi@earthling.net
  158.  
  159. This code is distributed under the same terms as Perl.
  160.  
  161. =cut
  162.  
  163.