home *** CD-ROM | disk | FTP | other *** search
/ Netrunner 2004 October / NETRUNNER0410.ISO / regular / ActivePerl-5.8.4.810-MSWin32-x86.msi / _1209fa19bade180dc0d2237bfb8a8eee < prev    next >
Encoding:
Text File  |  2004-06-01  |  3.2 KB  |  90 lines
  1.  
  2. =head1 NAME
  3.  
  4. Tk::Wm::Popup - popup dialog windows.
  5.  
  6. =for pm Tk/Wm.pm
  7.  
  8. =for category Tk Toplevel widgets
  9.  
  10. =head1 SYNOPSIS
  11.  
  12.  $dialog->Popup(qw/
  13.      -popover    => 'cursor' | $widget | undef,
  14.      -overanchor => c | n | ne | e | se | s | sw | w | nw,
  15.      -popanchor  => c | n | ne | e | se | s | sw | w | nw,
  16.  /);
  17.  
  18. =head1 DESCRIPTION
  19.  
  20. You've probably had occasion to use a Dialog (or DialogBox)
  21. widget. These widgets are derived from a Toplevel (which is a subclass
  22. of Tk::Wm, the window manager) and spend most of their time in a
  23. withdrawn state. It's also common to use Toplevels as containers for
  24. custom built popup windows.  Menus, too, are dialogs derived from the
  25. window manager class. For this discussion, we'll use the simple term
  26. I<dialog> to refer any widget that pops up and awaits user
  27. interaction, whether it be a Menu, a special purpose Toplevel, or any
  28. of the dialog-type widgets, including, but not limited to, ColorEditor,
  29. Dialog, DialogBox, ErrorDialog, FileSelect, FBox, getOpenFile and
  30. getSaveFile.
  31.  
  32. When it's time to display these dialogs, we call the Perl/Tk
  33. window manager B<Popup> method. B<Popup> accepts three special purpose
  34. options that specify placement information in high-level terms rather
  35. than numerical coordinates. It is B<Popup>'s responsibility to take
  36. our human specifications and turn them into actual screen
  37. coordinates before displaying the dialog.
  38.  
  39. We can direct the dialog to appear in two general locations, either
  40. over another window (e.g. the root window (screen) or a particular
  41. widget), or over the cursor. This is called the I<popover
  42. location>. Once we've made this decision we can further refine the
  43. exact placement of the dialog relative to the popover location by
  44. specifying the intersection of two I<anchor points>. The I<popanchor
  45. point> is associated with the dialog and the I<overanchor point> is
  46. associated with the popover location (whether it be a window or the
  47. cursor). The point where the two anchor points coincide is the I<popup
  48. locus>. Anchor points are string values and can be I<c> (for center),
  49. or any of the eight cardinal compass points: I<n>, I<ne>, I<e>, I<se>,
  50. I<s>, I<sw>, I<w> or I<nw>.
  51.  
  52. For example, if I<-popover> specifies a widget, I<-popanchor> is I<sw>,
  53. and I<-overanchor> is I<ne>, the the dialog's southwest corner pops up
  54. at the widget's northeast corner.
  55.  
  56. =head1 OPTIONS
  57.  
  58. The options recognized by B<Popup> are as follows:
  59.  
  60. =over 4
  61.  
  62. =item B<-popover>
  63.  
  64. Specifies whether the dialog "pops over" a window or the cursor. 
  65. It may be the string I<cursor>, a widget reference, or undef for the 
  66. root window.
  67.  
  68. =item B<-popanchor>
  69.  
  70. Specifies the anchor point of the dialog.  For instance, if I<e> is
  71. specified, the right side of the dialog is the anchor.
  72.  
  73. =item B<-overanchor>
  74.  
  75. Specifies where the dialog should anchor relative to the popover
  76. location. For instance, if I<e> is specified the dialog appears over
  77. the right side of the popover location and if it's I<ne> the the
  78. dialog is positioned at the upper-right corner of the popover location.
  79.  
  80. =back
  81.  
  82. =head1 AUTHOR
  83.  
  84. Nick Ing-Simmons, Steve Lidie
  85.  
  86. This code is distributed under the same terms as Perl.
  87.  
  88. =cut
  89.  
  90.