phoenix_title wx.TopLevelWindow

wx.TopLevelWindow is a common base class for wx.Dialog and wx.Frame.

It is an abstract base class meaning that you never work with objects of this class directly, but all of its methods are also applicable for the two classes above.

Note that the instances of wx.TopLevelWindow are managed by wxWidgets in the internal top level window list.

events Events Emitted by this Class

Event macros for events emitted by this class:

  • EVT_MAXIMIZE: Process a wxEVT_MAXIMIZE event. See wx.MaximizeEvent.

  • EVT_MOVE: Process a wxEVT_MOVE event, which is generated when a window is moved. See wx.MoveEvent.

  • EVT_MOVE_START: Process a wxEVT_MOVE_START event, which is generated when the user starts to move or size a window. wxMSW only. See wx.MoveEvent.

  • EVT_MOVE_END: Process a wxEVT_MOVE_END event, which is generated when the user stops moving or sizing a window. wxMSW only. See wx.MoveEvent.

  • EVT_SHOW: Process a wxEVT_SHOW event. See wx.ShowEvent.


class_hierarchy Class Hierarchy

Inheritance diagram for class TopLevelWindow:

sub_classes Known Subclasses

wx.Dialog, wx.Frame


method_summary Methods Summary

__init__

Default constructor.

CanSetTransparent

Returns True if the platform supports making the window translucent.

CenterOnScreen

A synonym for CentreOnScreen .

CentreOnScreen

Centres the window on screen.

Create

Creates the top level window.

EnableCloseButton

Enables or disables the Close button (most often in the right upper corner of a dialog) and the Close entry of the system menu (most often in the left upper corner of the dialog).

EnableFullScreenView

Enables the maximize button to toggle full screen mode.

EnableMaximizeButton

Enables or disables the Maximize button (in the right or left upper corner of a frame or dialog).

EnableMinimizeButton

Enables or disables the Minimize button (in the right or left upper corner of a frame or dialog).

GetClassDefaultAttributes

GetDefaultItem

Returns a pointer to the button which is the default for this window, or

GetDefaultSize

Get the default size for a new top level window.

GetIcon

Returns the standard icon of the window.

GetIcons

Returns all icons associated with the window, there will be none of them if neither SetIcon nor SetIcons had been called before.

GetTitle

Gets a string containing the window title.

GetTmpDefaultItem

Iconize

Iconizes or restores the window.

IsActive

Returns True if this window is currently active, i.e. if the user is currently working with it.

IsAlwaysMaximized

Returns True if this window is expected to be always maximized, either due to platform policy or due to local policy regarding particular class.

IsFullScreen

Returns True if the window is in fullscreen mode.

IsIconized

Returns True if the window is iconized.

IsMaximized

Returns True if the window is maximized.

Layout

Lays out the children using the window sizer or resizes the only child of the window to cover its entire area.

MacGetMetalAppearance

MacGetTopLevelWindowRef

MacGetUnifiedAppearance

MacSetMetalAppearance

Maximize

Maximizes or restores the window.

OSXIsModified

Returns the current modified state of the wx.TopLevelWindow on OS X.

OSXSetModified

This function sets the wx.TopLevelWindow’s modified state on OS X, which currently draws a black dot in the wx.TopLevelWindow’s close button.

RequestUserAttention

Use a system-dependent way to attract users attention to the window when it is in background.

Restore

Restore a previously iconized or maximized window to its normal state.

RestoreToGeometry

Restores the window to the previously saved geometry.

SaveGeometry

Save the current window geometry to allow restoring it later.

SetDefaultItem

Changes the default item for the panel, usually win is a button.

SetIcon

Sets the icon for this window.

SetIcons

Sets several icons of different sizes for this window: this allows using different icons for different situations (e.g.

SetMaxSize

A simpler interface for setting the size hints than SetSizeHints .

SetMinSize

A simpler interface for setting the size hints than SetSizeHints .

SetRepresentedFilename

Sets the file name represented by this wx.TopLevelWindow.

SetSizeHints

Allows specification of minimum and maximum window sizes, and window size increments.

SetTitle

Sets the window title.

SetTmpDefaultItem

SetTransparent

If the platform supports it will set the window to be translucent.

ShouldPreventAppExit

This virtual function is not meant to be called directly but can be overridden to return False (it returns True by default) to allow the application to close even if this, presumably not very important, window is still opened.

ShowFullScreen

Depending on the value of show parameter the window is either shown full screen or restored to its normal state.

ShowWithoutActivating

Show the wx.TopLevelWindow, but do not give it keyboard focus.


api Class API

class wx.TopLevelWindow(NonOwnedWindow)

Possible constructors:

TopLevelWindow()

TopLevelWindow(parent, id=ID_ANY, title="",
               pos=DefaultPosition, size=DefaultSize, style=DEFAULT_FRAME_STYLE,
               name=FrameNameStr)

TopLevelWindow is a common base class for Dialog and Frame.


Methods

__init__(self, *args, **kw)

overload Overloaded Implementations:



__init__ (self)

Default constructor.



__init__ (self, parent, id=ID_ANY, title=””, pos=DefaultPosition, size=DefaultSize, style=DEFAULT_FRAME_STYLE, name=FrameNameStr)

Constructor creating the top level window.

Parameters
  • parent (wx.Window) –

  • id (wx.WindowID) –

  • title (string) –

  • pos (wx.Point) –

  • size (wx.Size) –

  • style (long) –

  • name (string) –





CanSetTransparent(self)

Returns True if the platform supports making the window translucent.

Return type

bool

See also

SetTransparent



CenterOnScreen(self, direction=BOTH)

A synonym for CentreOnScreen .

Parameters

direction (int) –



CentreOnScreen(self, direction=BOTH)

Centres the window on screen.

Parameters

direction (int) – Specifies the direction for the centering. May be HORIZONTAL , VERTICAL or BOTH .



Create(self, parent, id=ID_ANY, title="", pos=DefaultPosition, size=DefaultSize, style=DEFAULT_FRAME_STYLE, name=FrameNameStr)

Creates the top level window.

Parameters
  • parent (wx.Window) –

  • id (wx.WindowID) –

  • title (string) –

  • pos (wx.Point) –

  • size (wx.Size) –

  • style (long) –

  • name (string) –

Return type

bool



EnableCloseButton(self, enable=True)

Enables or disables the Close button (most often in the right upper corner of a dialog) and the Close entry of the system menu (most often in the left upper corner of the dialog).

Returns True if operation was successful. This may be wrong on X11 (including GTK+) where the window manager may not support this operation and there is no way to find out.

Parameters

enable (bool) –

Return type

bool



EnableFullScreenView(self, enable=True)

Enables the maximize button to toggle full screen mode.

Prior to OS X 10.10 a full screen button is added to the right upper corner of a window’s title bar.

Currently only available for OSX/Cocoa.

Parameters

enable (bool) – If True (default) adds the full screen button in the title bar; if False the button is removed.

Return type

bool

Returns

True if the button was added or removed, False if running under another OS.

New in version 3.1.0.

Availability

Only available for OSX.

Note

Having the button is also required to let ShowFullScreen make use of the full screen API available since OS X 10.7: a full screen window gets its own space and entering and exiting the mode is animated. If the button is not present the old way of switching to full screen is used.

See also

ShowFullScreen



EnableMaximizeButton(self, enable=True)

Enables or disables the Maximize button (in the right or left upper corner of a frame or dialog).

Currently only implemented for wxMSW and wxOSX.

The window style must contain wx.MAXIMIZE_BOX.

Returns True if operation was successful. Note that a successful operation does not change the window style flags.

Parameters

enable (bool) –

Return type

bool

New in version 3.1.0.



EnableMinimizeButton(self, enable=True)

Enables or disables the Minimize button (in the right or left upper corner of a frame or dialog).

Currently only implemented for wxMSW and wxOSX.

The window style must contain wx.MINIMIZE_BOX.

Note that in wxMSW a successful operation will change the window style flags.

Returns True if operation was successful. Note that a successful operation does not change the window style flags.

Parameters

enable (bool) –

Return type

bool

New in version 3.1.0.



static GetClassDefaultAttributes(variant=WINDOW_VARIANT_NORMAL)
Parameters

variant (WindowVariant) –

Return type

wx.VisualAttributes



GetDefaultItem(self)

Returns a pointer to the button which is the default for this window, or

The default button is the one activated by pressing the Enter key.

Return type

wx.Window



static GetDefaultSize()

Get the default size for a new top level window.

This is used internally by wxWidgets on some platforms to determine the default size for a window created using wx.DefaultSize so it is not necessary to use it when creating a wx.TopLevelWindow, however it may be useful if a rough estimation of the window size is needed for some other reason.

Return type

wx.Size

New in version 2.9.2.



GetIcon(self)

Returns the standard icon of the window.

The icon will be invalid if it hadn’t been previously set by SetIcon .

Return type

wx.Icon

See also

GetIcons



GetIcons(self)

Returns all icons associated with the window, there will be none of them if neither SetIcon nor SetIcons had been called before.

Use GetIcon to get the main icon of the window.

Return type

wx.IconBundle

See also

wx.IconBundle



GetTitle(self)

Gets a string containing the window title.

Return type

string

See also

SetTitle



GetTmpDefaultItem(self)
Return type

wx.Window



Iconize(self, iconize=True)

Iconizes or restores the window.

Note that in wxGTK the change to the window state is not immediate, i.e. IsIconized will typically return False right after a call to Iconize and its return value will only change after the control flow returns to the event loop and the notification about the window being really iconized is received.

Parameters

iconize (bool) – If True, iconizes the window; if False, shows and restores it.



IsActive(self)

Returns True if this window is currently active, i.e. if the user is currently working with it.

Return type

bool



IsAlwaysMaximized(self)

Returns True if this window is expected to be always maximized, either due to platform policy or due to local policy regarding particular class.

Return type

bool



IsFullScreen(self)

Returns True if the window is in fullscreen mode.

Return type

bool

See also

ShowFullScreen



IsIconized(self)

Returns True if the window is iconized.

Return type

bool



IsMaximized(self)

Returns True if the window is maximized.

Return type

bool



Layout(self)

Lays out the children using the window sizer or resizes the only child of the window to cover its entire area.

This class overrides the base class Layout method to check if this window contains exactly one child – which is commonly the case, with wx.Panel being often created as the only child of wx.TopLevelWindow – and, if this is the case, resizes this child window to cover the entire client area.

Note that if you associate a sizer with this window, the sizer takes precedence and the only-child-resizing is only used as fallback.

Return type

bool

Returns

False if nothing was done because the window doesn’t have neither a sizer nor a single child, True otherwise.



MacGetMetalAppearance(self)
Return type

bool



MacGetTopLevelWindowRef(self)


MacGetUnifiedAppearance(self)
Return type

bool



MacSetMetalAppearance(self, on)


Maximize(self, maximize=True)

Maximizes or restores the window.

Note that, just as with Iconize , the change to the window state is not immediate in at least wxGTK port.

Parameters

maximize (bool) – If True, maximizes the window, otherwise it restores it.

See also

Restore , Iconize



OSXIsModified(self)

Returns the current modified state of the wx.TopLevelWindow on OS X.

On other platforms, this method does nothing.

Return type

bool

See also

OSXSetModified



OSXSetModified(self, modified)

This function sets the wx.TopLevelWindow’s modified state on OS X, which currently draws a black dot in the wx.TopLevelWindow’s close button.

On other platforms, this method does nothing.

Parameters

modified (bool) –

See also

OSXIsModified



RequestUserAttention(self, flags=USER_ATTENTION_INFO)

Use a system-dependent way to attract users attention to the window when it is in background.

flags may have the value of either USER_ATTENTION_INFO (default) or USER_ATTENTION_ERROR which results in a more drastic action. When in doubt, use the default value.

This function is currently implemented for Win32 where it flashes the window icon in the taskbar, and for wxGTK with task bars supporting it.

Parameters

flags (int) –

Note

This function should normally be only used when the application is not already in foreground.



Restore(self)

Restore a previously iconized or maximized window to its normal state.

In wxGTK this method currently doesn’t return the maximized window to its normal state and you must use Maximize with False argument explicitly for this. In the other ports, it both unmaximizes the maximized windows and uniconizes the iconized ones.

See also

Iconize , Maximize



RestoreToGeometry(self, ser)

Restores the window to the previously saved geometry.

This is a companion function to SaveGeometry and can be called later to restore the window to the geometry it had when it was saved.

Parameters

ser (wx.TopLevelWindow.GeometrySerializer) – An object implementing wx.TopLevelWindow.GeometrySerializer virtual methods.

Return type

bool

Returns

True if any (and, usually, but not necessarily, all) of the window geometry attributes were restored or False if there was no saved geometry information at all or restoring it failed.

New in version 3.1.2.



SaveGeometry(self, ser)

Save the current window geometry to allow restoring it later.

After calling this function, window geometry is saved in the provided serializer and calling RestoreToGeometry with the same serializer later (i.e. usually during a subsequent program execution) would restore the window to the same position, size, maximized/minimized state etc.

This function is used by PersistentTLW , so it is not necessary to use it if the goal is to just save and restore window geometry in the simplest possible way. However is more flexibility is required, it can be also used directly with a custom serializer object.

Parameters

ser (wx.TopLevelWindow.GeometrySerializer) – An object implementing wx.TopLevelWindow.GeometrySerializer virtual methods.

Return type

bool

Returns

True if the geometry was saved, False if doing it failed

New in version 3.1.2.



SetDefaultItem(self, win)

Changes the default item for the panel, usually win is a button.

Parameters

win (wx.Window) –

Return type

wx.Window

See also

GetDefaultItem



SetIcon(self, icon)

Sets the icon for this window.

Parameters

icon (wx.Icon) – The wx.Icon to associate with this window.

Note

The window takes a ‘copy’ of icon, but since it uses reference counting, the copy is very quick. It is safe to delete icon after calling this function.

Note

In wxMSW, icon must be either 16x16 or 32x32 icon.

See also

wx.Icon, SetIcons



SetIcons(self, icons)

Sets several icons of different sizes for this window: this allows using different icons for different situations (e.g.

task switching bar, taskbar, window title bar) instead of scaling, with possibly bad looking results, the only icon set by SetIcon .

Parameters

icons (wx.IconBundle) – The icons to associate with this window.

Note

In wxMSW, icons must contain a 16x16 or 32x32 icon, preferably both.

See also

wx.IconBundle



SetMaxSize(self, size)

A simpler interface for setting the size hints than SetSizeHints .

Parameters

size (wx.Size) –



SetMinSize(self, size)

A simpler interface for setting the size hints than SetSizeHints .

Parameters

size (wx.Size) –



SetRepresentedFilename(self, filename)

Sets the file name represented by this wx.TopLevelWindow.

Under OS X, this file name is used to set the “proxy icon”, which appears in the window title bar near its title, corresponding to this file name. Under other platforms it currently doesn’t do anything but it is harmless to call it now and it might be implemented to do something useful in the future so you’re encouraged to use it for any window representing a file-based document.

Parameters

filename (string) –

New in version 2.9.4.



SetSizeHints(self, *args, **kw)

overload Overloaded Implementations:



SetSizeHints (self, minW, minH, maxW=-1, maxH=-1, incW=-1, incH=-1)

Allows specification of minimum and maximum window sizes, and window size increments.

If a pair of values is not set (or set to -1), no constraints will be used.

Parameters
  • minW (int) – The minimum width.

  • minH (int) – The minimum height.

  • maxW (int) – The maximum width.

  • maxH (int) – The maximum height.

  • incW (int) – Specifies the increment for sizing the width (GTK/Motif/Xt only).

  • incH (int) – Specifies the increment for sizing the height (GTK/Motif/Xt only).

Note

Notice that this function not only prevents the user from resizing the window outside the given bounds but it also prevents the program itself from doing it using wx.Window.SetSize .



SetSizeHints (self, minSize, maxSize=DefaultSize, incSize=DefaultSize)

Allows specification of minimum and maximum window sizes, and window size increments.

If a pair of values is not set (or set to -1), no constraints will be used.

Parameters
  • minSize (wx.Size) – The minimum size of the window.

  • maxSize (wx.Size) – The maximum size of the window.

  • incSize (wx.Size) – Increment size (only taken into account under X11-based ports such as GTK/wxMotif/wxX11).

Note

Notice that this function not only prevents the user from resizing the window outside the given bounds but it also prevents the program itself from doing it using wx.Window.SetSize .





SetTitle(self, title)

Sets the window title.

Parameters

title (string) – The window title.

See also

GetTitle



SetTmpDefaultItem(self, win)
Parameters

win (wx.Window) –

Return type

wx.Window



SetTransparent(self, alpha)

If the platform supports it will set the window to be translucent.

Parameters

alpha (wx.Byte) – Determines how opaque or transparent the window will be, if the platform supports the operation. A value of 0 sets the window to be fully transparent, and a value of 255 sets the window to be fully opaque.

Return type

bool



ShouldPreventAppExit(self)

This virtual function is not meant to be called directly but can be overridden to return False (it returns True by default) to allow the application to close even if this, presumably not very important, window is still opened.

By default, the application stays alive as long as there are any open top level windows.

Return type

bool



ShowFullScreen(self, show, style=FULLSCREEN_ALL)

Depending on the value of show parameter the window is either shown full screen or restored to its normal state.

style is a bit list containing some or all of the following values, which indicate what elements of the window to hide in full-screen mode:

  • FULLSCREEN_NOMENUBAR

  • FULLSCREEN_NOTOOLBAR

  • FULLSCREEN_NOSTATUSBAR

  • FULLSCREEN_NOBORDER

  • FULLSCREEN_NOCAPTION

  • FULLSCREEN_ALL (all of the above)

This function has not been tested with MDI frames.

Parameters
  • show (bool) –

  • style (long) –

Return type

bool

Note

Showing a window full screen also actually Show s the window if it isn’t shown.



ShowWithoutActivating(self)

Show the wx.TopLevelWindow, but do not give it keyboard focus.

This can be used for pop up or notification windows that should not steal the current focus.


Properties

DefaultItem

See GetDefaultItem and SetDefaultItem



Icon

See GetIcon and SetIcon



MacMetalAppearance

See MacGetMetalAppearance and MacSetMetalAppearance



OSXModified

See OSXIsModified and OSXSetModified



Title

See GetTitle and SetTitle



TmpDefaultItem

See GetTmpDefaultItem and SetTmpDefaultItem