A Window is a top-level component. In order to be visible on the screen,
a component must be directly or indirectly contained in a window.
A newly-created window is initially hidden so that components can
be added to it without unsightly flashing. Once constructed, it should be
shown using the show method.
Size and positionThe geometry properties of a window govern the size and position of the window's content
area relative to the screen. Usually there will be borders, a title bar
and so forth existing outside this area, and on some platforms there
will also be a menu bar between the title and the content area. These
things should be kept in mind if you are setting the position of a
window explicitly. For example, trying to place a window in the top
left corner of the screen by setting its position to (0, 0) will
probably not work as expected, as it will result in the title bar and
menus being hidden. (There is
currently no good way of dealing with this; as a rule of thumb, allow 5
pixels to the left and 40 pixels above to accommodate window
The initial position of a window is determined in a platform-dependent
way, and may not correspond to the initial values of its x and
y properties. For example, standard-style windows might be staggered
and dialog-style windows might be centred on the screen. However, once the
window has been shown for the first time, the x and y properties
will reflect its actual screen position, and changing them will move the
window to the specified position.
A window can be given a list of window-specific menus that are to be available
(along with the application-wide menus) only when that window is active.
The manner in which these menus are presented is platform-dependent.
A window can be associated with a document. When this is done, the behaviour
of the window changes in the following ways:
The window's title will (by default) be derived automatically from the document's
- The document becomes the window's next handler for keyboard
events and menu commands.
- An attempt by the user to close the window is taken as a request to
close the associated document, which may trigger a dialog asking whether
to save changes.
- Closing the document causes all its associated windows to be destroyed.
- Window(style = 'standard',
- movable = default, closable
= default, hidable = default,
- resizable = default, zoomable
- The style parameter determines the appearance of the window,
according to platform conventions. It is one of:
- Not all of these styles are necessarily distinguishable on all platforms.
- Note that the 'modal_dialog'and 'alert' styles only affect the appearance of the
window; they do not in themselves cause the window to behave modally. For a window
with modal behaviour, use a ModalDialog or one of the alert functions.
- The options'movable', 'closable', 'resizable', 'hidable'(minimizable) and 'zoomable'(maximizable) request
the presence or absence of controls for performing these functions. The default
values of these options depend on the window style in a platform-dependent
way. Some combinations of styles and options may not be available, in which case you will get the nearest available combination.
window is created without any title, borders or other decoration, and
with an initial size and position that covers the whole screen. The
effect of changing a fullscreen window's size or position is undefined.
On MacOSX, the menu bar is hidden when a fullscreen window is the
Note: the fullscreen style is currently not implemented on Gtk.
- Title of the window. Whether and how the title is displayed depends
on the window style and platform conventions.
- The Document instance to which this window belongs, if any.
- List of window-specific menus, i.e. those which should be available
only when this window is active.
- Do not modify the contents of this list. To change it, you
should construct a new list of menus and then assign the whole list to this
- True if the window is shown on the screen. The visibility of the window can be changed using the show and hide methods, or by assigning to this property. The effect on window stacking order of assigning true to this property is undefined.
- If true, the window will be positioned automatically the first
time it is shown. The method of positioning depends on the platform and
the style of the window. Typically, dialog windows will be centred on
the screen, and other windows will be staggered or the user will be
asked to place them.
If false, the initial position of the window is determined by the settings of its geometry properties.
- Read only. The component within the window, if any, that is currently the target of keyboard events and menu commands. May not be implemented on all platforms.
boolean controlling whether the presence of this window keeps its
associated document open. When a window is closed, and its document has
no other window whose keeps_document_open
flag is true, the document and any other remaining windows for it are
closed. Defaults to true. May be specified as a class attribute.
- Makes the window visible on the screen (by setting the visible
property to true), and brings it to the front.
- Temporarily removes the window from the screen. Equivalent to setting
the visible property to false.
- Moves the window to the front of the stacking order. [NOT YET IMPLEMENTED]
- Moves the window to the back of the stacking order. [NOT YET IMPLEMENTED]
- Places the window just behind the given window in the stacking order.
[NOT YET IMPLEMENTED]
- Runs an event loop, fetching and handling input events for this window
is called. Interaction with other windows is prevented.
If a Cancel
exception is raised during the event loop, it is silently caught and
the event loop continues. The handling of an exception of any other
type is platform-dependent; it may break the event loop and be
propagated, or it may be handled within the loop using the application's report_exception() method.
- Causes the current call to modal_event_loop() to
- Called when the title of the document owning this window changes.
By default it changes the window title to match the document title.
- Called in response to the Close menu command, or by activation
of whatever gadget is used to close a window on the platform concerned.
If the window belongs to a document and the document does not own any other
windows, the document's close_cmd method is called. In any other
case, the destroy method of this window is called.
- Permanently removes the window from the screen, dissociates it from
any document, and recursively destroys any sub-components. Neither the
window nor any of its sub-components should be used again.
- All windows and other components should be destroyed when they are
no longer needed, otherwise they may not be garbage collected properly and
may continue to tie up window system resources. This is taken care of by
the framework when the user closes a window or document. In other situations
you may need to call the destroy method yourself.