| 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 | |