Methods
gtk.Window.set_title
def set_title(title
)
title :
| the title of the window |
The set_title
() method sets the "title" property
of the gtk.Window
to the
value specified by title
. The title of a window will
be displayed in its title bar. On the X Window System, the title bar is
rendered by the window manager, so exactly how the title appears to users
may vary according to a user's exact configuration. The title should help a
user distinguish this window from other windows they may have open. A good
title might include the application name and current document
filename.
gtk.Window.get_title
def get_title()
Returns : | the title of the window, or
None . |
The get_title
() method returns the
value of the "title" property of the window. See the set_title
()
method.
gtk.Window.set_wmclass
def set_wmclass(wmclass_name
, wmclass_class
)
wmclass_name :
| the window name hint |
wmclass_class :
| the window class hint |
The set_wmclass
() method sets the X
Window System "class" and "name" hints for a window. Applications should not
call this method. According to the ICCCM, you should always set these to the
same value for all windows in an application, and PyGTK
sets them to that value by default, so calling this method is sort of
pointless. However, you may want to call the set_role
()
method on each window in your application, for the benefit of the session
manager. Setting the role allows the window manager to restore window
positions when loading a saved session.
gtk.Window.set_role
def set_role(role
)
role :
| a unique identifier for the
window |
The set_role
() method sets a unique
identifier (specified by role
) for the window to be
used when restoring a session. This method is only useful on X11. In
combination with the window title, the window role allows a window manager
to identify "the same" window when an application is restarted. So for
example you might set the "toolbox" role on your app's toolbox window, so
that when the user restarts their session, the window manager can put the
toolbox back in the same place. If a window already has a unique title, you
don't need to set the role, since the WM can use the title to identify the
window when restoring the session.d
gtk.Window.get_role
def get_role()
Returns : | the role of the window if set, or
None . |
The get_role
() method returns the role
of the window. See the set_role
()
method for further explanation.
gtk.Window.add_accel_group
def add_accel_group(accel_group
)
The add_accel_group
() method associates
the accelerator group specified by accel_group
with
the window.
gtk.Window.remove_accel_group
def remove_accel_group(accel_group
)
The remove_accel_group
() method
dissociates the accelerator group specified by
accel_group
from the widget. This method reverses the
effects of the add_accel_group
()
method.
gtk.Window.set_position
def set_position(position
)
position :
| a position constraint. |
The set_position
() method sets the
"window-position" property to the value of position
.
The value of position
must be one of the GTK Window Position Constants.
If the old or new window position constraint is
gtk.WIN_POS_CENTER_ALWAYS
, this will also cause the
window to be repositioned to satisfy the new constraint.
gtk.Window.activate_focus
def activate_focus()
Returns : | True if the window has a
focus widget |
The activate_focus
() method activates
the child widget with the focus. This method returns True
if the window has a widget with the focus.
gtk.Window.set_focus
def set_focus(focus
)
focus :
| the widget to be the new focus
widget or None to unset a focus widget |
The set_focus
() method sets the widget
specified by focus
to be the focus widget for the
window. If focus
is None
the
window's focus widget is unset. To set the focus to a particular widget in
the toplevel, it is usually more convenient to use the gtk.Widget.grab_focus
()
method instead of this method.
gtk.Window.get_focus
def get_focus()
Returns : | the currently focused
widget. |
The get_focus
() method returns the
current focused widget within the window. The focus widget is the widget
that would have the focus if the toplevel window is focused.
gtk.Window.set_default
def set_default(default_widget
)
default_widget :
| the widget to be the default, or
None to unset the default widget. |
The set_default
() method sets the
window's default widget to the value specified by
default_widget
. If
default_widget
is None
the
window's default widget is unset. The default widget is the widget that's
activated when the user presses Enter in a window. When
setting (rather than unsetting) the default widget it's generally easier to
call the gtk.Widget.grab_default
()
method on the widget. Before making a widget the default widget, you must
set the gtk.CAN_DEFAULT
flag on the widget you'd like to
make the default using the gtk.Object.set_flags
()
method.
gtk.Window.activate_default
def activate_default()
Returns : | True if the window has a
default widget or a focus widget. |
The activate_default
() method activates
the default widget. If there is no default widget or the default widget
cannot be activated, the window's focus widget (if any) is activated. This
method returns False
if no default widget could be
activated or there is no focus widget.
gtk.Window.set_transient_for
def set_transient_for(parent
)
parent :
| the parent window or None to
remove the transient parent |
The set_transient_for
() method sets the
window as a transient window for the window specified by
parent
. Dialog windows should be set transient for
the main application window they were spawned from. This allows window
managers to keep the dialog on top of the main window, or center the dialog
over the main window. The gtk.Dialog() constructor and other
convenience functions in PyGTK
will sometimes call the
set_transient_for
() method on your behalf.
On Windows, this method will and put the child window on top of the parent,
much as the window manager would have done on X.
gtk.Window.get_transient_for
def get_transient_for()
Returns : | the transient parent for this window, or
None if no transient parent has been
set. |
The get_transient_for
() method returns
the transient parent for this window or None
if no
transient window is set. See the set_transient_for
()
method.
gtk.Window.set_type_hint
def set_type_hint(hint
)
The set_type_hint
() method sets the
window type hint for the window to the value specified by
hint
. The value of hint
must
be one of the GDK Window Type Hint Constants.
By setting the type hint for the window, you allow the window
manager to decorate and handle the window in a way which is suitable to the
method of the window in your application. This method should be called
before the window becomes visible. The gtk.Dialog() constructor and other
convenience functions in PyGTK
will sometimes call this
method on your behalf.
gtk.Window.get_type_hint
def get_type_hint()
Returns : | the type hint for the
window. |
The get_type_hint
() method returns the
type hint for this window. See the set_type_hint
()
method.
gtk.Window.set_destroy_with_parent
def set_destroy_with_parent(setting
)
setting :
| if True destroy the window
with its transient parent |
The set_destroy_with_parent
() method
sets the "destroy-with-parent" property to the value specified by
setting
. If setting
is
True
, destroying the transient parent of the window will
also destroy the window itself. This is useful for dialogs that shouldn't
persist beyond the lifetime of the main window they're associated
with.
gtk.Window.get_destroy_with_parent
def get_destroy_with_parent()
Returns : | True if the window will be
destroyed with its transient parent. |
The get_destroy_with_parent
() method
returns the value of the "destroy-with-parent" property that determines if
the window will be destroyed with its transient parent. See the set_destroy_with_parent
()
method.
gtk.Window.set_resizable
def set_resizable(resizable
)
resizable :
| if True the user can resize
this window |
The set_resizable
() method sets the
"resizable" property to the value of resizable
. If
resizable
is True
the user can
resize the window. Windows are user resizable by default.
gtk.Window.get_resizable
def get_resizable()
Returns : | True if the user can resize
the window |
The get_resizable
() method returns the
value of the "resizable" property. See the set_resizable
()
method.
gtk.Window.set_gravity
def set_gravity(gravity
)
gravity :
| the window gravity |
The set_gravity
() method sets the
gravity of the window to the value specified by
gravity
. The window gravity defines the meaning of
coordinates passed to the move
()
method. The value of gravity must be one of the GDK Gravity Constants.
The default window gravity is
gtk.gdk.GRAVITY_NORTH_WEST
which will typically "do what
you want."
gtk.Window.get_gravity
def get_gravity()
Returns : | the window gravity |
The get_gravity
() method returns window
gravity. See the set_gravity
()
method.
gtk.Window.set_geometry_hints
def set_geometry_hints(geometry_widget
, min_width
=-1, min_height
=-1, max_width
=-1, max_height
=-1, base_width
=-1, base_height
=-1, width_inc
=-1, height_inc
=-1, min_aspect
=-1.0, max_aspect
=-1.0)
geometry_widget :
| the widget the geometry hints will be applied
to |
min_width :
| the minimum width of window (or -1 to use
requisition) |
min_height :
| the minimum height of window (or -1 to use
requisition) |
max_width :
| the maximum width of window (or -1 to use
requisition) |
max_height :
| the maximum height of window (or -1 to use
requisition) |
base_width :
| allowed window widths are base_width +
width_inc * N where N is any integer |
base_height :
| allowed window heights are base_height +
width_inc * N where N is any integer |
width_inc :
| the width resize increment |
height_inc :
| the height resize
increment |
min_aspect :
| the minimum width to height
ratio |
max_aspect :
| the maximum width to height
ratio |
The set_geometry_hints
() method sets up
hints about how a window can be resized by the user. You can set the minimum
and maximum widths and heights, the base width and height for resizing, the
allowed width and height resize increments (e.g. for xterm, you can only
resize by the size of a character), and the minimum and maximum aspect
ratios. If geometry_widget
is not
None
it specifies the widget to figure the geometry
on.
gtk.Window.set_screen
def set_screen(screen
)
Note
This method is available in PyGTK 2.2 and above.
The set_screen
() method sets the
"screen" property to the gtk.gdk.Screen
specified by screen
. The "screen" property contains
the screen that the window is displayed on. If the window is already mapped,
it will be unmapped, and then remapped on the new screen.
gtk.Window.get_screen
def get_screen()
Note
This method is available in PyGTK 2.2 and above.
The get_screen
() method returns the
gtk.gdk.Screen
that the window is displayed on.
gtk.Window.is_active
def is_active()
Returns : | True if the window is part
of the current active window. |
Note
This method is available in PyGTK 2.4 and above.
The is_active
() method returns
True
if the window is part of the current active
toplevel, i.e., the toplevel window receiving keystrokes. The return value
is True
if the window is active the toplevel itself, or
if it is, for example, a gtk.Plug
embedded in
the active toplevel. You might use this method if you wanted to draw a
widget differently in an active window from a widget in an inactive window.
See the has_toplevel_focus()
method.
gtk.Window.has_toplevel_focus
def has_toplevel_focus()
Returns : | True if the the input focus
is within the window |
Note
This method is available in PyGTK 2.4 and above.
The has_toplevel_focus
() method returns
True
if the input focus is within the window. For real
toplevel windows, this is identical to is_active()
,
but for embedded windows, like a gtk.Plug
, the results
will differ.
gtk.Window.set_has_frame
def set_has_frame(setting
)
setting :
| if True PyGTK draws the
window border |
The set_has_frame
() method sets the
flag that causes PyGTK
to draw its own window border for
the window.
Note
This is a special-purpose method for the framebuffer port. For
most applications, you want the set_decorated
()
method instead,that tells the window manager whether to draw the window
border.
If this method is called on a window with setting of
True
, before it is realized or showed, it will have a
"frame" window around the window's gtk.gdk.Window
,
accessible in the window's frame. Using the signal "frame-event" you can
receive all events targeted at the frame. This method is used by the
linux-fb port to implement managed windows, but it could conceivably be used
by X-programs that want to do their own window decorations.
gtk.Window.get_has_frame
def get_has_frame()
Returns : | True if a frame has been
added to the window via the set_has_frame ()
method. |
The get_has_frame
() method returns the
value of the window's "has_frame" flag that determines if the window has a
frame window exterior to its gtk.gdk.Window
. See
the set_has_frame
()
method for more information.
gtk.Window.set_frame_dimensions
def set_frame_dimensions(left
, top
, right
, bottom
)
left :
| the width of the left
border |
top :
| the height of the top
border |
right :
| the width of the right
border |
bottom :
| the height of the bottom
border |
The set_frame_dimensions
() method sets
the size of the frame around the window to the values specified by
left
, top
,
bottom
and right
.
Note
This is a special-purpose method intended for the framebuffer
port. See the set_has_frame
()
method. It will have no effect on the window border drawn by the window
manager, which is the normal case when using the X Window system.
For windows with frames (see the set_has_frame
()
method) this method can be used to change the size of the frame
border.
gtk.Window.get_frame_dimensions
def get_frame_dimensions()
Returns : | a tuple containing the frame dimensions: the
width of the frame at the left; the height of the frame at the top; the
width of the frame at the right; and, the height of the frame at the
bottom. |
The get_frame_dimensions
() method
returns a tuple containing the frame dimensions: the width of the frame at
the left; the height of the frame at the top; the width of the frame at the
right; and, the height of the frame at the bottom.
Note
This is a special-purpose method intended for the framebuffer
port See the set_has_frame
()
method. It will not return the size of the window border drawn by the window
manager, which is the normal case when using a windowing system. See the
get_frame_extents
()
to get the standard window border extents.
See the set_has_frame
()
and set_frame_dimensions
()
methods for more information.
gtk.Window.set_decorated
def set_decorated(setting
)
setting :
| if True decorate the
window |
The set_decorated
() method sets the
decorated flag to the value specified by setting
. If
setting
is True
the window will be
decorated. By default, windows are decorated with a title bar, resize
controls, etc. Some window managers allow PyGTK to disable these
decorations, creating a borderless window. If you set the decorated property
to False
using this method, PyGTK
will
do its best to convince the window manager not to decorate the window. On
Windows, this method always works, since there's no window manager policy
involved.
gtk.Window.get_decorated
def get_decorated()
Returns : | True if the window has been
set to have decorations |
The get_decorated
() method returns the
value of the decorated flag that determines if the window has been set to
have decorations such as a title bar. See the set_decorated
()
method.
gtk.Window.set_icon_list
def set_icon_list(...
)
The set_icon_list
() method sets up the
icon representing the window using the set of gtk.gdk.Pixbuf
objects passed as arguments. If no gtk.gdk.Pixbuf
objects are passed in the icon is unset and reverts to the default icon. The
icon is used when the window is minimized (also known as iconified). Some
window managers or desktop environments may also place it in the window
frame, or display it in other contexts. This method allows you to pass in
the same icon in several hand-drawn sizes. The gtk.gdk.Pixbuf
objects should contain the natural sizes your icon is available in; i.e.,
don't scale the image before passing it to PyGTK
. Scaling
is postponed until the last minute, when the desired final size is known, to
allow best quality. By passing several sizes, you may improve the final
image quality of the icon, by reducing or eliminating automatic image
scaling. The recommended sizes to provide are: 16x16, 32x32, 48x48 at
minimum, and larger images (64x64, 128x128) if you have them.
See the gtk.window_set_default_icon_list
()
function to set the icon for all windows in your application in one go. Note
that transient windows (those who have been set transient for another window
using the set_transient_for
()
method) will inherit their icon from their transient parent. So there's no
need to explicitly set the icon on transient windows.
gtk.Window.get_icon_list
def get_icon_list()
Returns : | a copy of the window's icon
list |
The get_icon_list
() method returns the
list of icons set by the set_icon_list
()
method.
gtk.Window.set_icon
def set_icon(icon
)
icon :
| an icon image, or
None |
The set_icon
() method sets the "icon"
property to the value specified by icon
. This icon is
used when the window is minimized (also known as iconified). Some window
managers or desktop environments may also place it in the window frame, or
display it in other contexts. The icon should be provided in whatever size
it was naturally drawn; that is, don't scale the image before passing it to
PyGTK
. Scaling is postponed until the last minute, when
the desired final size is known, to allow best quality. If you have your
icon hand-drawn in multiple sizes, use the set_icon_list
()
method. Then the best size will be used.
This method is equivalent to calling the set_icon_list
()
method with a 1-element list. See the gtk.window_set_default_icon_list
()
function to set the icon for all windows in your application in one
go.
gtk.Window.set_icon_from_file
def set_icon_from_file(filename
)
filename :
| the name of a file containing an icon
image |
Returns : | True if the icon was
loaded. |
The set_icon_from_file
() method sets
the "icon" property to the icon loaded from the file specified by
filename
. The icon is used when the window is
minimized (also known as iconified). See the set_icon
())
method for more information. This method is equivalent to calling the set_icon
()
method with a pixbuf created by loading the image from
filename
.
The GError exception is raised if an error occurs while loading
the pixbuf from filename
.
gtk.Window.get_icon
def get_icon()
Returns : | the icon for window |
The get_icon
() method returns the value
of the "icon" property set by the set_icon
()
(or if you've called the set_icon_list
()
method, returns the first icon in the icon list).
gtk.Window.set_modal
def set_modal(modal
)
modal :
| if True the window is
modal |
The set_modal
() method sets the "modal"
property to the value of modal
. If
modal
is True
the window becomes
modal. Modal windows prevent interaction with other windows in the same
application. Typically modal windows are used for gtk.Dialog
windows
that require a user response before the application can continue. To keep
modal dialogs on top of the main application windows, use the set_transient_for
()
method to make the dialog transient for the parent - most window managers
will then disallow lowering the dialog below the parent.
gtk.Window.get_modal
def get_modal()
Returns : | True if the window is set to
be modal and establishes a grab when shown |
The get_modal
() method returns the
value of the "modal" property. If "modal" is True
the
window is modal. See the set_modal
()
method.
gtk.Window.add_mnemonic
def add_mnemonic(keyval
, target
)
keyval :
| the mnemonic key |
target :
| the widget that gets activated by the
mnemonic |
The add_mnemonic
() method adds a
mnemonic key specified by keyval
to this window. When
the mnemonic key is pressed the widget specified by
target
will be activated.
gtk.Window.remove_mnemonic
def remove_mnemonic(keyval
, target
)
keyval :
| the mnemonic key |
target :
| the widget that gets activated by the
mnemonic |
The remove_mnemonic
() method removes
the mnemonic specified by keyval
for the widget
specified by target
from this window.
gtk.Window.mnemonic_activate
def mnemonic_activate(keyval
, modifier
)
keyval :
| the mnemonic key |
modifier :
| the modifiers |
Returns : | True if the activation was
done |
The mnemonic_activate
() method
activates the targets associated with the mnemonic specified by
keyval
. The window's mnemonic modifier must match
modifier
to allow the activation to proceed. See the
set_mnemonic_modifier
()
method for more information.
gtk.Window.set_mnemonic_modifier
def set_mnemonic_modifier(modifier
)
modifier :
| the modifier mask used to activate mnemonics on
this window. |
The set_mnemonic_modifier
() method sets
the mnemonic modifier for this window to the value specified by
modifier
. The value of
modifier
is one of:
gtk.gdk.SHIFT_MASK
| The Shift key. |
gtk.gdk.CONTROL_MASK
| The Control key. |
gtk.gdk.MOD1_MASK
| The fourth modifier key (it depends on the modifier
mapping of the X server which key is interpreted as this modifier, but
normally it is the Alt key). |
gtk.Window.get_mnemonic_modifier
def get_mnemonic_modifier()
Returns : | the modifier mask used to activate mnemonics on
this window. |
The get_mnemonic_modifier
() method
returns the mnemonic modifier for this window. See the set_mnemonic_modifier
()
method for more detail.
gtk.Window.activate_key
def activate_key(event
)
event :
| a gtk.gdk.Event |
Returns : | True if a mnemonic or
accelerator was found and activated. |
Note
This method is available in PyGTK 2.4 and above.
The activate_key
() method activates
mnemonics and accelerators for the window. This is normally called by the
default gtk.Widget
"key-press-event" signal
handler for toplevel windows, however in some cases it may be useful to call
this directly when overriding the standard key handling for a toplevel
window.
gtk.Window.propagate_key_event
def propagate_key_event(event
)
event :
| a gtk.gdk.Event |
Returns : | True if a widget in the
focus chain handled the event. |
Note
This method is available in PyGTK 2.4 and above.
The propagate_key_event
() method
propagates a key press or release event to the focus widget and up the focus
container chain until a widget handles the key event specified by
event
. This is normally called by the default gtk.Widget
"key-press-event" and
"key-release-event"
signal handlers for toplevel windows, however in some cases it may be useful
to call this directly when overriding the standard key handling for a
toplevel window.
gtk.Window.present
def present()
The present
() method presents a window
to the user. This may mean raising the window in the stacking order,
deiconifying it, moving it to the current desktop, and/or giving it the
keyboard focus, possibly dependent on the user's platform, window manager,
and preferences. If the window is hidden, this method calls the the gtk.Widget.show
()
method as well. This method should be used when the user tries to open a
window that's already open. Say for example the preferences dialog is
currently open, and the user chooses
from the menu a second time; use the present
()
method to move the already-open dialog where the user can see it.
gtk.Window.iconify
def iconify()
The iconify
() method asks the window
manager to iconify (i.e. minimize) the specified the window. Note that you
shouldn't assume the window is definitely iconified afterward, because other
entities (e.g. the user or window manager) could deiconify it again, or
there may not be a window manager in which case iconification isn't
possible, etc. But normally the window will end up iconified. Just don't
write code that crashes if not. This method can be called before showing a
window, in which case the window will be iconified before it ever appears
on-screen. You can track iconification via the gtk.Widget
"window-state-event"
signal.
gtk.Window.deiconify
def deiconify()
The deiconify
() method asks the window
manager to deiconify (i.e. unminimize) the specified the window. Note that
you shouldn't assume the window is definitely deiconified afterward, because
other entities (e.g. the user or window manager) could iconify it again
before your code which assumes deiconification gets to run. You can track
iconification via the gtk.Widget
"window-state-event"
signal.
gtk.Window.stick
def stick()
The stick
() method asks the window
manager to stick the window, which means that it will appear on all user
desktops. Note that you shouldn't assume the window is definitely stuck
afterward, because other entities (e.g. the user or window manager) could
unstick it again, and some window managers do not support sticking windows.
But normally the window will end up stuck. Just don't write code that
crashes if not. This method can be called before showing a window. You can
track stickiness via the gtk.Widget
"window-state-event"
signal.
gtk.Window.unstick
def unstick()
The unstick() method asks the window manager to unstick the
window, which means that it will appear on only one of the user's desktops.
Note that you shouldn't assume the window is definitely unstuck afterward,
because other entities (e.g. the user or window manager) could stick it
again. But normally the window will end up stuck. Just don't write code that
crashes if not. You can track stickiness via the gtk.Widget
"window-state-event"
signal.
gtk.Window.maximize
def maximize()
The maximize
() method asks the window
manager to maximize the window, so that it becomes full-screen. Note that
you shouldn't assume the window is definitely maximized afterward, because
other entities (e.g. the user or window manager) could unmaximize it again,
and not all window managers support maximization. But normally the window
will end up maximized. This method can be called before showing a window, in
which case the window will be maximized when it appears on-screen initially.
You can track maximization via the gtk.Widget
"window-state-event"
signal.
gtk.Window.unmaximize
def unmaximize()
The unmaximize
() method asks the window
manager to unmaximize the window. Note that you shouldn't assume the window
is definitely unmaximized afterward, because other entities (e.g. the user
or window manager) could maximize it again, and not all window managers
honor requests to unmaximize. But normally the window will end up
unmaximized. You can track maximization via the gtk.Widget
"window-state-event"
signal.
gtk.Window.fullscreen
def fullscreen()
Note
This method is available in PyGTK 2.2 and above.
The fullscreen
() method requests the
window manager to place the window in the fullscreen state. Note you
shouldn't assume the window is definitely full screen afterward, because
other entities (e.g. the user or window manager) could unfullscreen it
again, and not all window managers honor requests to fullscreen windows. But
normally the window will end up fullscreen. Just don't write code that
crashes if not.
You can track the fullscreen state via the gtk.Widget
"window-state-event"
signal.
gtk.Window.unfullscreen
def unfullscreen()
Note
This method is available in PyGTK 2.2 and above.
The unfullscreen
() method requests the
window manager to toggle off the fullscreen state for the window. Note that
you shouldn't assume the window is definitely not full screen afterward,
because other entities (e.g. the user or window manager) could fullscreen it
again, and not all window managers honor requests to unfullscreen
windows. But normally the window will end up restored to its normal
state. Just don't write code that crashes if not.
You can track the fullscreen state via the gtk.Widget
"window_state_event"
signal.
gtk.Window.set_keep_above
def set_keep_above(setting
)
setting :
| if True keep the window
above other windows |
Note
This method is available in PyGTK 2.4 and above.
The set_keep_above
() method requests
the window manager to keep the window on top if
setting
is True
. Note that you
shouldn't assume the window is definitely above afterward, because other
entities (e.g. the user or window manager) could not keep it above, and not
all window managers support keeping windows above. But normally the window
will end kept above. Just don't write code that crashes if not.
It's permitted to call this method before showing a window, so
the window will be kept above when it appears on-screen initially.
You can track the above state via the gtk.Widget
"window_state_event"
signal.
Note that, according to the Extended
Window Manager Hints specification, the above state is mainly meant
for user preferences and should not be used by applications e.g. for drawing
attention to their dialogs.
gtk.Window.set_keep_below
def set_keep_below(setting
)
setting :
| if True keep the window
below other windows |
Note
This method is available in PyGTK 2.4 and above.
The set_keep_below
() method requests
the window manager to keep the window on the bottom (i.e. below all other
windows). Note that you shouldn't assume the window is definitely below
afterward, because other entities (e.g. the user or window manager) could
not keep it below, and not all window managers support putting windows
below. But normally the window will be kept below. Just don't write code
that crashes if not.
It's permitted to call this function before showing a window, in
which case the window will be kept below when it appears on-screen
initially.
You can track the below state via the gtk.Widget
"window_state_event"
signal.
Note that, according to the Extended
Window Manager Hints specification, the above state is mainly meant
for user preferences and should not be used by applications e.g. for drawing
attention to their dialogs.
gtk.Window.begin_resize_drag
def begin_resize_drag(edge
, button
, root_x
, root_y
, timestamp
)
edge :
| the position of the resize
control |
button :
| the mouse button that initiated the
drag |
root_x :
| the X position where the user clicked to
initiate the drag, in root window coordinates |
root_y :
| the Y position where the user clicked to
initiate the drag |
timestamp :
| the timestamp from the click event that
initiated the drag |
The begin_resize_drag
() method starts
resizing a window from the edge specified by edge
.
The mouse button that started the resize is specified by
button
; the location, by
root_x
and root_y
; and the
time of the event, by timestamp
. The value of
edge
must be one of the GDK Window Edge Constants.
This method is used if an application has window resizing
controls. When PyGTK
can support it, the resize will be
done using the standard mechanism for the window manager or windowing
system. Otherwise, PyGTK
will try to emulate window
resizing, potentially not all that well, depending on the windowing
system.
gtk.Window.begin_move_drag
def begin_move_drag(button
, root_x
, root_y
, timestamp
)
button :
| the mouse button that initiated the
drag |
root_x :
| the X position where the user clicked to
initiate the drag, in root window coordinates |
root_y :
| the Y position where the user clicked to
initiate the drag |
timestamp :
| the timestamp from the click event that
initiated the drag |
The begin_move_drag
() method starts
moving a window when the user presses the mouse button specified by
button
at the location specified by
root_x
and root_y
at the time
specified by timestamp
. This method is used if an
application has window movement grips. When PyGTK
can
support it, the window movement will be done using the standard mechanism
for the window manager or windowing system. Otherwise,
PyGTK
will try to emulate window movement, potentially
not all that well, depending on the windowing system.
gtk.Window.set_default_size
def set_default_size(width
, height
)
width :
| the width in pixels, or -1 to unset the default
width |
height :
| the height in pixels, or -1 to unset the
default height |
The set_default_size
() method sets the
default size of the window to the specified width
and
height
. If the window's "natural" size (its size
request) is larger than the default, the default will be ignored. More
generally, if the default size does not obey the geometry hints for the
window (the set_geometry_hints
()
method can be used to set these explicitly), the default size will be
clamped to the nearest permitted size.
Unlike the gtk.Widget.set_size_request
()
method, which sets a size request for a widget and thus would keep users
from shrinking the window, this method only sets the initial size, just as
if the user had resized the window themselves. Users can still shrink the
window again as they normally would. Setting a default size of -1 means to
use the "natural" default size (the size request of the window). For more
control over a window's initial size and how resizing works, investigate the
set_geometry_hints
()
method.
For some uses, the resize
()
method is more appropriate as it changes the current size of the window,
rather than the size to be used on initial display. The resize
()
method always affects the window itself, not the geometry widget. The
default size of a window only affects the first time a window is shown; if a
window is hidden and re-shown, it will remember the size it had prior to
hiding, rather than using the default size. Windows can't actually be 0x0 in
size, they must be at least 1x1, but passing 0 for
width
and height
is OK,
resulting in a 1x1 default size.
gtk.Window.get_default_size
def get_default_size()
Returns : | a tuple containing the default width and height
of the window |
The get_default_size
() method returns a
tuple containing the default width and height of the window. A value of -1
for the returned width or height indicates that a default size has not been
explicitly set for that dimension, so the "natural" size of the window will
be used. See the set_default_size
()
method for more information
gtk.Window.resize
def resize(width
, height
)
width :
| the width in pixels to resize the window
to |
height :
| the height in pixels to resize the window
to |
The resize
() method resizes the window
to the specified width
and
height
as if the user had done so, obeying geometry
constraints. The default geometry constraint is that windows may not be
smaller than their size request; to override this constraint, call the gtk.Widget.set_size_request
()
method to set the window's request to a smaller value. If the
resize
() method is called before showing a window
for the first time, it overrides any default size set with the set_default_size
()
method. Windows may not be resized smaller than 1 by 1 pixels.
gtk.Window.get_size
def get_size()
Returns : | a tuple containing the width and height of the
window |
The get_size
() method returns a tuple
containing the current width and height of the window. If the window is not
on-screen, it returns the size PyGTK
will suggest to the
window manager for the initial window size (but this is not reliably the
same as the size the window manager will actually select). The size obtained
by the get_size
() method is the last size received
in a configure event, that is, PyGTK
uses its
locally-stored size, rather than querying the X server for the size. As a
result, if you call the resize
()
method then immediately call the get_size
() method,
the size won't have taken effect yet. After the window manager processes the
resize request, PyGTK receives notification that the size has changed via a
configure event, and the size of the window gets updated.
Note
Nearly any use of this method creates a race condition,
because the size of the window may change between the time that you get the
size and the time that you perform some action assuming that size is the
current size. To avoid race conditions, connect to "configure_event" on the
window and adjust your size-dependent state to match the size delivered in
the configure event.
The returned size does not include the
size of the window manager decorations (aka the window frame or border).
Those are not drawn by PyGTK
which has no reliable method
of determining their size.
If you are getting a window size in order to position the
window on-screen, there may be a better way. The preferred way is to simply
set the window's semantic type with the set_type_hint
()
method, that allows the window manager to center dialogs, etc. Also, if you
set the transient parent of dialogs with the set_transient_for
()
method, window managers will often center the dialog over its parent window.
It's much preferred to let the window manager handle these things rather
than doing it yourself, because all apps will behave consistently and
according to user prefs if the window manager handles it. Also, the window
manager can take the size of the window decorations/border into account,
while your application cannot.
In any case, if you insist on application-specified window
positioning, there's still a better way than doing it
yourself - the set_position
()
method will frequently handle the details for you.
gtk.Window.move
def move(x
, y
)
x :
| the X coordinate to move window
to |
y :
| the Y coordinate to move window
to |
The move
() method asks the window
manager to move the window to the position specified by
x
and y
. Window managers are
free to ignore this. In fact, most window managers ignore requests for
initial window positions (instead using a user-defined placement algorithm)
and honor requests after the window has already been shown.
The position is the position of the gravity-determined
reference point for the window. The gravity determines two things: first,
the location of the reference point in root window coordinates; and second,
which point on the window is positioned at the reference point. By default
the gravity is gtk.gdk.GRAVITY_NORTH_WEST
, so the
reference point is simply the x
,
y
supplied to the move
()
method. The top-left corner of the window decorations (aka window frame or
border) will be placed at x
,
y
. Therefore, to position a window at the top left of
the screen, you want to use the default gravity (which is
gtk.gdk.GRAVITY_NORTH_WEST
) and move the window to
0,0.
To position a window at the bottom right corner of the screen,
you would set gtk.gdk.GRAVITY_SOUTH_EAST
, which means
that the reference point is at x
+ the window width
and y
+ the window height, and the bottom-right
corner of the window border will be placed at that reference point. So, to
place a window in the bottom right corner you would first set gravity to
south east, then move the window:
window.set_gravity(gtk.gdk.GRAVITY_SOUTH_EAST)
width, height = window.get_size()
window.move(gtk.gdk.screen_width() - width, gtk.gdk.screen_height() - height)
The Extended
Window Manager Hints specification has a nice table of gravities in
the "implementation notes" section. The get_position
()
method documentation may also be relevant.
gtk.Window.get_position
def get_position()
Returns : | a tuple containing the X and Y coordinates of
the gravity-determined reference point |
The get_position
() method returns a
tuple containing the x and y coordinates of the window that you would need
to pass to the move
()
method to keep the window in its current position. This means that the
meaning of the returned value varies with window gravity. See the move
()
method for more details. If you haven't changed the window gravity, its
gravity will be gtk.gdk.GRAVITY_NORTH_WEST
. This means
that the get_position
() method gets the position of
the top-left corner of the window manager frame for the window. The move
()
method sets the position of this same top-left corner.
The get_position
() method is not 100%
reliable because the X Window System does not specify a way to obtain the
geometry of the decorations placed on a window by the window manager. Thus
PyGTK
is using a "best guess" that works with most window
managers. Moreover, nearly all window managers are historically broken with
respect to their handling of window gravity. So moving a window to its
current position as returned by the get_position
()
method tends to result in moving the window slightly. Window managers are
slowly getting better over time.
If a window has gravity
gtk.gdk.GRAVITY_STATIC
the window manager frame is not
relevant, and thus the get_position
() method will
always produce accurate results. However you can't use static gravity to do
things like place a window in a corner of the screen, because static gravity
ignores the window manager decorations. If you are saving and restoring your
application's window positions, you should know that it's impossible for
applications to do this without getting it somewhat wrong because
applications do not have sufficient knowledge of window manager state. The
correct mechanism is to support the session management protocol (see the
"GnomeClient" object in the GNOME libraries for example) and allow the
window manager to save your window sizes and positions.
gtk.Window.parse_geometry
def parse_geometry(geometry
)
geometry :
| the geometry string |
Returns : | True if string was parsed
successfully |
The parse_geometry
() method parses the
standard X Window System geometry string specified by
geometry
. The geometry string has the format
"WIDTHxHEIGHT+XOFFSET+YOFFSET" where WIDTH, HEIGHT, XOFFSET and YOFFSET are
specified in pixels (see the X documentation for more details). This method
works work on all PyGTK
ports including Win32 but is
primarily intended for an X environment. If either a size or a position can
be extracted from the geometry string, the
parse_geometry
() method returns
True
and calls the set_default_size
()
and move
()
methods to resize and move the window.
If the parse_geometry
() method returns
True
, it will also set the
gtk.gdk.HINT_USER_POS
and
gtk.gdk.HINT_USER_SIZE
hints indicating to the window
manager that the size and position of the window was user-specified. This
causes most window managers to honor the geometry.
gtk.Window.reshow_with_initial_size
def reshow_with_initial_size()
The reshow_with_initial_size
() method
hides the window, then reshows it, resetting the default size and position
of the window. Used by GUI builders only.
gtk.Window.tooltips_get_info_from_tip_window
def tooltips_get_info_from_tip_window()
Note
This method is available in PyGTK 2.4 and above.
The tooltips_get_info_from_tip_window
()
method returns a 2-tuple containing the gtk.Tooltips
and
gtk.Widget
displayed in the window. If the window is not displaying tooltips this
method returns None. This method is mostly intended for use by accessibility
technologies - applications should have little use for it.
gtk.Window.set_focus_on_map
def set_focus_on_map(setting
)
setting :
| If True this window would
like to receive focus when mapped. |
Note
This method is available in PyGTK 2.6 and above.
The set_focus_on_map
() method sets the
"focus-on-map" property to the value of setting
. If
setting
is True
a hint is set
asking the desktop environment to give focus to the window when it is
mapped.
gtk.Window.get_focus_on_map
def get_focus_on_map()
Returns : | True if the window would
like to receive focus when mapped. |
Note
This method is available in PyGTK 2.6 and above.
The get_focus_on_map
() method returns
the value of the "focus-on-map" property. See the set_focus_on_map
()
method for more information.
gtk.Window.set_icon_name
def set_icon_name(name
)
name :
| the name of the themed icon or
None |
Note
This method is available in PyGTK 2.6 and above.
The set_icon_name
() method sets the
"icon-name" property to the value of name
. If
name
is None
, then the default
themed icon will be used. The "icon-name" property contains the name of the
icon used for the window. See the gtk.IconTheme
reference for more information.
gtk.Window.get_icon_name
def get_icon_name()
Returns : | The name of the themed icon used for the
window icon or None if no icon is set. |
Note
This method is available in PyGTK 2.6 and above.
The get_icon_name
() method returns the
name of the themed icon for the window, see the set_icon_name
()
method for more information.
gtk.Window.set_urgency_hint
def set_urgency_hint(urgency_hint
)
urgency_hint :
| if True mark this window
as needing urgent attention. |
Note
This method is available in PyGTK 2.8 and above.
The set_urgency_hint
() method sets the
"urgency-hint" property to the value of
urgency_hint
. If the "urgency-hint" property is True
the window sets a hint to the desktop environment to draw the users
attention to the window.
gtk.Window.get_urgency_hint
def get_urgency_hint()
Returns : | True if the window is marked
as needing urgent user attention. |
Note
This method is available in PyGTK 2.8 and above.
The get_urgency_hint
() method returns
the value of the "urgency-hint" property. See the set_urgency_hint
()
method for more information.
gtk.Window.present_with_time
def present_with_time(timestamp
)
timestamp :
| the timestamp of the user interaction (typically
a button or key press event) which triggered this call |
Note
This method is available in PyGTK 2.8 and above.
The present_with_time
() method presents
a window to the user in response to a user interaction. If you need to
present a window without a timestamp, use the present
()
method.
gtk.Window.set_deletable
def set_deletable(setting
)
setting :
| if True decorate the window
as deletable |
Note
This method is available in PyGTK 2.10 and above.
By default, windows have a close button in the window
frame. Some window managers allow GTK+ to disable this button. If you
set the deletable property to False
using this
method, GTK+ will do its best to convince the window manager not to
show a close button. Depending on the system, this method may not have
any effect when called on a window that is already visible, so you
should call it before calling
gtk_window_show
().
On Windows, this method always works, since there's no window
manager policy involved.
gtk.Window.get_deletable
def get_deletable()
Returns : | True if the window has been
set to have a close button |
Note
This method is available in PyGTK 2.10 and above.
Returns whether the window has been set to have a close button
via the gtk.Window.set_deletable()
method.
gtk.Window.get_group
def get_group()
Note
This method is available in PyGTK 2.10 and above.
Returns the gtk.WindowGroup
or the default group, if the window does not have an explicit window
group.
gtk.Window.set_opacity
def set_opacity(opacity
)
opacity :
| desired opacity, between 0 and 1. |
Note
This method is available in PyGTK 2.12 and above.
Request the windowing system to make window partially transparent, with
opacity 0 being fully transparent and 1 fully opaque. (Values of the
opacity parameter are clamped to the [0,1] range.) On X11 this has any
effect only on X screens with a compositing manager running.
See gtk.Widget.is_composited
().
On Windows it should work always.
Note that setting a window's opacity after the window has been shown causes it to flicker once on Windows.
gtk.Window.get_opacity
def get_opacity()
Returns : | the requested opacity for this window. |
Note
This method is available in PyGTK 2.12 and above.
Fetches the requested opacity for this window. See
gtk.Window.set_opacity
().
gtk.Window.set_startup_id
def set_startup_id(startup_id
)
startup_id :
| a string with startup-notification identifier |
Note
This method is available in PyGTK 2.12 and above.
Startup notification identifiers are used by desktop environment to track
application startup, to provide user feedback and other features. This
function changes the corresponding property on the underlying GdkWindow.
Normally, startup identifier is managed automatically and you should only
use this function in special cases like transferring focus from other processes.
You should use this function before calling
gtk.Window.present
()
or any equivalent function generating a window map event.
This function is only useful on X11, not with other GTK+ targets.
gtk.Window.get_default_widget
def get_default_widget()
Returns : | The default widget, or None
if there is none. |
Note
This method is available in PyGTK 2.14 and above.
Returns the default widget for window. See
gtk.Window.set_default
()()
for more details.