class `Window(Container)`

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 position

The 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 decorations.)

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.

Menus

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.

Document association

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

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.

Constructor

Window(style = 'standard',

movable = default, closable = default, hidable = default,

resizable = default, zoomable = default)

The style parameter determines the appearance of the window, according to platform conventions. It is one of:

'standard'

'nonmodal_dialog'

'modal_dialog'

'alert'
'fullscreen'

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.

A 'fullscreen' 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 active window.

Note: the fullscreen style is currently not implemented on Gtk.

Properties

title

Title of the window. Whether and how the title is displayed depends on the window style and platform conventions.

document

The Document instance to which this window belongs, if any.

menus

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

visible

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.

auto_position

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.

target

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.

Attributes

keeps_document_open: A 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.

Methods

show(): Makes the window visible on the screen (by setting the visible property to true), and brings it to the front.

hide(): Temporarily removes the window from the screen. Equivalent to setting the visible property to false.

bring_to_front(): Moves the window to the front of the stacking order. [NOT YET IMPLEMENTED]

send_to_back(): Moves the window to the back of the stacking order. [NOT YET IMPLEMENTED]

place_behind(window): Places the window just behind the given window in the stacking order. [NOT YET IMPLEMENTED]

modal_event_loop(): Runs an event loop, fetching and handling input events for this window until exit_modal_event_loop() 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.
exit_modal_event_loop(): Causes the current call to modal_event_loop() to exit.

Abstract methods

update_title(): Called when the title of the document owning this window changes. By default it changes the window title to match the document title.

close_cmd(): 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.

Destructor

destroy(): 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.

class Window(Container)