Pmw/Pmw_1_2/doc/MegaToplevel.html

   1
   2     <html>
   3     <head>
   4     <meta name="description" content="Pmw - a toolkit for building high-level compound widgets in Python">
   5     <meta name="content" content="python, megawidget, mega widget, compound widget, gui, tkinter">
   6     <title>Pmw.MegaToplevel reference manual</title>
   7     </head>
   8
   9     <body bgcolor="#ffffff" text="#000000" link="#0000ee"
  10         vlink="551a8b" alink="ff0000">
  11
  12     <h1 ALIGN="CENTER">Pmw.MegaToplevel</h1>
  13
  14 <dl>
  15 <dt> <h3>Name</h3></dt><dd>
  16 <p>Pmw.MegaToplevel() -
  17     base class for megawidgets within a toplevel
  18 </p>
  19
  20
  21 </dd>
  22 <dt> <h3>Inherits</h3></dt><dd>
  23 <a href="MegaArchetype.html">Pmw.MegaArchetype</a><br>
  24 </dd>
  25 <dt> <h3>Description</h3></dt><dd>
  26 <p>
  27     This class creates a megawidget contained within a toplevel
  28     window.  It may be used directly to create a toplevel megawidget
  29     or it may be used as a base class for more specialised toplevel
  30     megawidgets, such as <a href="Dialog.html">Pmw.Dialog</a>.  It creates a Tkinter.Toplevel
  31     component, named <strong>hull</strong>, to act as the container of the megawidget.
  32     The window class name for the <strong>hull</strong> widget is set to the
  33     most-specific class name for the megawidget.  Derived classes
  34     specialise this class by creating other widget components as
  35     children of the <strong>hull</strong> widget.</p>
  36
  37 <p>    The megawidget may be used as either a normal toplevel window or
  38     as a modal dialog.  Use <code>show()</code> and <code>withdraw()</code> for normal use
  39     and <code>activate()</code> and <code>deactivate()</code> for modal dialog use.  If the
  40     window is deleted by the window manager while being shown
  41     normally, the default behaviour is to destroy the window.  If the
  42     window is deleted by the window manager while the window is active
  43     (ie:  when used as a modal dialog), the window is deactivated.
  44     Use the <code>userdeletefunc()</code> and <code>usermodaldeletefunc()</code> methods to
  45     override these behaviours.  Do not call <code>protocol()</code> to set the
  46     <strong>WM_DELETE_WINDOW</strong> window manager protocol directly if you want to
  47     use this window as a modal dialog.</p>
  48
  49 <p>    The currently active windows form a stack with the most recently
  50     activated window at the top of the stack.  All mouse and
  51     keyboard events are sent to this top window.  When it
  52     deactivates, the next window in the stack will start to receive
  53     events.</p>
  54
  55 <p></p>
  56
  57
  58 </dd>
  59 <dt> <h3>Options</h3></dt><dd>
  60 Options for this megawidget and its base
  61 classes are described below.<p></p>
  62 <a name=option.activatecommand></a>
  63 <dl><dt> <strong>activatecommand
  64 </strong></dt><dd>
  65 If this is callable, it will be called whenever the megawidget is
  66     activated by a call to <code>activate()</code>. The default is <strong>None</strong>.</p>
  67
  68
  69 </dd></dl>
  70 <a name=option.deactivatecommand></a>
  71 <dl><dt> <strong>deactivatecommand
  72 </strong></dt><dd>
  73 If this is callable, it will be called whenever the megawidget is
  74     deactivated by a call to <code>deactivate()</code>. The default is <strong>None</strong>.</p>
  75
  76
  77 </dd></dl>
  78 <a name=option.master></a>
  79 <dl><dt> <strong>master
  80 </strong></dt><dd>
  81 This is used by the <code>activate()</code> method to control whether the
  82     window is made <em>transient</em> during modal dialogs.  See the
  83     <code>activate()</code> method. The default is <strong>None</strong>.</p>
  84
  85
  86 </dd></dl>
  87 <a name=option.title></a>
  88 <dl><dt> <strong>title
  89 </strong></dt><dd>
  90 This is the title that the window manager displays in the title
  91     bar of the window. The default is <strong>None</strong>.</p>
  92
  93
  94 </dd></dl>
  95 </dd>
  96 <dt> <h3>Components</h3></dt><dd>
  97 Components created by this megawidget and its base
  98 classes are described below.<p></p>
  99 <a name=component.hull></a>
 100 <dl><dt> <strong>hull
 101 </strong></dt><dd>
 102 This acts as the body for the entire megawidget.  Other components
 103     are created as children of the hull to further specialise this
 104     class. By default, this component is a Tkinter.Toplevel.</p>
 105
 106
 107 </dd></dl>
 108 </dd>
 109 <a name=methods></a>
 110 <dt> <h3>Methods</h3></dt><dd>
 111 Only methods specific to this megawidget are described below.
 112 For a description of its inherited methods, see the
 113 manual for its base class
 114 <strong><a href="MegaArchetype.html#methods">Pmw.MegaArchetype</a></strong>.
 115 In addition, methods from the
 116 <strong>Tkinter.Toplevel</strong> class
 117 are forwarded by this megawidget to the
 118 <strong>hull</strong> component.
 119 <p></p>
 120 <a name=method.activate></a>
 121 <dl><dt> <strong>activate</strong>(<em>globalMode</em> = <strong>0</strong>, <em>geometry</em> = <strong>'centerscreenfirst'</strong>)</dt><dd>
 122 Display the window as a modal dialog.  This means that all mouse
 123     and keyboard events go to this window and no other windows can
 124     receive any events.  If you do not want to restrict mouse and
 125     keyboard events to this window, use the <code>show()</code> method instead.</p>
 126 <p>    If the BLT extension to Tk is present, a busy cursor will be
 127     displayed on other toplevel windows, using <code>Pmw.showbusycursor()</code>.</p>
 128
 129 <p>    The <code>activate()</code> method does not return until the <code>deactivate()</code>
 130     method is called, when the window is withdrawn, the grab released
 131     and the result returned.</p>
 132
 133 <p>    If <em>globalMode</em> is false, the window will grab control of the
 134     pointer and keyboard, preventing any events from being delivered
 135     to any other toplevel windows within the application.  If
 136     <em>globalMode</em> is true, the grab will prevent events from being
 137     delivered to any other toplevel windows regardless of application.
 138     Global grabs should be used sparingly, if at all.</p>
 139
 140 <p>    If <em>globalMode</em> is <strong>'nograb'</strong>, then no grab is performed.  If BLT
 141     is present, this will allow mouse and keyboard events to be
 142     received by other windows whose <strong>exclude</strong> busycursor attribute has
 143     been set to true by a call to <code>Pmw.setbusycursorattributes()</code>.
 144     Note that if <strong>'nograb'</strong> is used and BLT is not present, then <em>all</em>
 145     other windows will receive mouse and keyboard events.  This is
 146     because, in plain Tk, there is no way to specify that two windows
 147     (only) receive events.  If your application may be used without
 148     BLT, then do not use <strong>'nograb'</strong>.</p>
 149
 150 <p>    When the window is displayed, it is positioned on the screen
 151     according to <em>geometry</em> which may be one of:</p>
 152
 153 <dl><dt><strong>centerscreenfirst</strong></dt><dd>The window will be centered the first time it is activated.
 154         On subsequent activations it will be positioned in the same
 155         position as the last time it was displayed, even if it has
 156         been moved by the user.<p></p>
 157
 158 </dd>
 159 <dt><strong>centerscreenalways</strong></dt><dd>The window will be be centered on the screen (halfway across
 160         and one third down).<p></p>
 161
 162 </dd>
 163 <dt><strong>first</strong> + <em>spec</em></dt><dd>It is assumed that the rest of the argument (after <strong>'first'</strong>)
 164         is a standard geometry specification.  The window will be
 165         positioned using this specification the first time it is
 166         activated.  On subsequent activations it will be positioned in
 167         the same position as the last time it was displayed, even if
 168         it has been moved by the user.  For example,
 169         <code>geometry = first+100+100</code> will initially display the window
 170         at position (100,100).  Other calls to <code>activate()</code> will not
 171         change the previous position of the window.<p></p>
 172
 173 </dd>
 174 <dt><em>spec</em></dt><dd>This is a standard geometry specification.  The window will be
 175         be positioned using this specification.<p></p>
 176
 177 </dd></dl>
 178 <p>    If the <strong>BLT</strong> Tcl extension library is present, a <strong>clock</strong> cursor
 179     will be displayed until the window is deactivated.</p>
 180
 181 <p>    If the <strong>activatecommand</strong> option is callable, it is called just
 182     before the window begins to wait for the result.</p>
 183
 184 <p>    If the <strong>master</strong> option is not <strong>None</strong>, the window will become a
 185     transient window of <strong>master</strong>, which should be a toplevel window.
 186     If <strong>master</strong> has the special value of <strong>'parent'</strong>, the master is the
 187     toplevel window of the window's parent.</p>
 188
 189
 190
 191 </dd></dl>
 192 <a name=method.active></a>
 193 <dl><dt> <strong>active</strong>()</dt><dd>
 194 Return true if the megawidget is currently active (that is,
 195     <code>activate()</code> is currently waiting for a result to be passed to it
 196     by a call to <code>deactivate()</code>).</p>
 197
 198
 199 </dd></dl>
 200 <a name=method.deactivate></a>
 201 <dl><dt> <strong>deactivate</strong>(<em>result</em> = <strong>None</strong>)</dt><dd>
 202 This should be called while a call to <code>activate()</code> is waiting.  It
 203     will withdraw the window, release the grab and cause the
 204     <code>activate()</code> call to return with the value of <em>result</em>.</p>
 205 <p>    If the <strong>deactivatecommand</strong> option is callable, it is called just
 206     before the <code>deactivate()</code> method returns.</p>
 207
 208
 209
 210 </dd></dl>
 211 <a name=method.destroy></a>
 212 <dl><dt> <strong>destroy</strong>()</dt><dd>
 213 Destroy the <strong>hull</strong> component widget, including all of its
 214     children.  If the megawidget is currently active, deactivate it.</p>
 215
 216
 217 </dd></dl>
 218 <a name=method.show></a>
 219 <dl><dt> <strong>show</strong>(<em>master</em> = <strong>None</strong>)</dt><dd>
 220 Make the window visible.  This raises or deiconifies the toplevel
 221     window.  If the window has previously been shown it will remain in
 222     the same position.  This means that calling <code>withdraw()</code> then
 223     <code>show()</code> will not move the window, whereas calling <code>withdraw()</code>
 224     then <code>deiconify()</code> may change the window's position.  (This may
 225     depend on the behaviour of the window manager.)</p>
 226
 227
 228 </dd></dl>
 229 <a name=method.userdeletefunc></a>
 230 <dl><dt> <strong>userdeletefunc</strong>(<em>func</em> = <strong>None</strong>)</dt><dd>
 231 If <em>func</em> is <strong>None</strong>, return the function that will be called
 232     when the window is deleted by the window manager while being
 233     displayed normally.  If <em>func</em> is not <strong>None</strong>, set this function to
 234     <em>func</em>.  By default, the function is <code>self.destroy</code>.</p>
 235
 236
 237 </dd></dl>
 238 <a name=method.usermodaldeletefunc></a>
 239 <dl><dt> <strong>usermodaldeletefunc</strong>(<em>func</em> = <strong>None</strong>)</dt><dd>
 240 If <em>func</em> is <strong>None</strong>, return the function that will be called
 241     when the window is deleted by the window manager while it is
 242     active (ie:  when being used as a modal dialog).  If <em>func</em> is not
 243     <strong>None</strong>, set this function to <em>func</em>.  By default, the function is
 244     <code>self.deactivate</code>.</p>
 245
 246
 247 </dd></dl>
 248 </dd>
 249 </dl>
 250
 251     <center><P ALIGN="CENTER">
 252     <IMG SRC = blue_line.gif ALT = "" WIDTH=320 HEIGHT=5>
 253     </p></center>
 254
 255
 256     <font size=-1>
 257     <center><P ALIGN="CENTER">
 258     Pmw 1.2 -
 259      5 Aug 2003
 260      - <a href="index.html">Home</a>
 261     <br>Manual page last reviewed: 22 May 1998
 262     </p></center>
 263     </font>
 264
 265     </body>
 266     </html>
 267