Libwnck Reference Manual | ||||
---|---|---|---|---|
Top | Description | Object Hierarchy | Signals |
#include <libwnck/libwnck.h> struct WnckScreen; WnckScreen * wnck_screen_get_default (void
); WnckScreen * wnck_screen_get (int index
); WnckScreen * wnck_screen_get_for_root (gulong root_window_id
); int wnck_screen_get_number (WnckScreen *screen
); int wnck_screen_get_width (WnckScreen *screen
); int wnck_screen_get_height (WnckScreen *screen
); void wnck_screen_force_update (WnckScreen *screen
); const char * wnck_screen_get_window_manager_name (WnckScreen *screen
); gboolean wnck_screen_net_wm_supports (WnckScreen *screen
,const char *atom
); WnckWindow * wnck_screen_get_active_window (WnckScreen *screen
); WnckWindow * wnck_screen_get_previously_active_window (WnckScreen *screen
); GList * wnck_screen_get_windows (WnckScreen *screen
); GList * wnck_screen_get_windows_stacked (WnckScreen *screen
); WnckWorkspace * wnck_screen_get_active_workspace (WnckScreen *screen
); GList * wnck_screen_get_workspaces (WnckScreen *screen
); WnckWorkspace * wnck_screen_get_workspace (WnckScreen *screen
,int workspace
); int wnck_screen_get_workspace_index (WnckScreen *screen
,WnckWorkspace *space
); enum WnckMotionDirection; WnckWorkspace * wnck_screen_get_workspace_neighbor (WnckScreen *screen
,WnckWorkspace *space
,WnckMotionDirection direction
); int wnck_screen_get_workspace_count (WnckScreen *screen
); void wnck_screen_change_workspace_count (WnckScreen *screen
,int count
); int wnck_screen_try_set_workspace_layout (WnckScreen *screen
,int current_token
,int rows
,int columns
); void wnck_screen_release_workspace_layout (WnckScreen *screen
,int current_token
); struct WnckWorkspaceLayout; void wnck_screen_calc_workspace_layout (WnckScreen *screen
,int num_workspaces
,int space_index
,WnckWorkspaceLayout *layout
); void wnck_screen_free_workspace_layout (WnckWorkspaceLayout *layout
); void wnck_screen_move_viewport (WnckScreen *screen
,int x
,int y
); gulong wnck_screen_get_background_pixmap (WnckScreen *screen
); gboolean wnck_screen_get_showing_desktop (WnckScreen *screen
); void wnck_screen_toggle_showing_desktop (WnckScreen *screen
,gboolean show
);
"active-window-changed" :Run Last
"active-workspace-changed" :Run Last
"application-closed" :Run Last
"application-opened" :Run Last
"background-changed" :Run Last
"class-group-closed" :Run Last
"class-group-opened" :Run Last
"showing-desktop-changed" :Run Last
"viewports-changed" :Run Last
"window-closed" :Run Last
"window-manager-changed" :Run Last
"window-opened" :Run Last
"window-stacking-changed" :Run Last
"workspace-created" :Run Last
"workspace-destroyed" :Run Last
The WnckScreen represents a physical screen. A screen may consist of multiple monitors which are merged to form a large screen area. The WnckScreen is at the bottom of the libwnck stack of objects: WnckWorkspace objects exist a WnckScreen and WnckWindow objects are displayed on a WnckWorkspace.
The WnckScreen corresponds to the notion of
GdkScreen
in GDK.
The WnckScreen objects are always owned by libwnck and must not be referenced or unreferenced.
struct WnckScreen;
The WnckScreen struct contains only private fields and should not be directly accessed.
WnckScreen * wnck_screen_get_default (void
);
Gets the default WnckScreen on the default display.
Returns : |
the default WnckScreen. The returned WnckScreen is owned by libwnck and must not be referenced or unreferenced. [transfer none] |
WnckScreen * wnck_screen_get (int index
);
Gets the WnckScreen for a given screen on the default display.
|
screen number, starting from 0. |
Returns : |
the WnckScreen for screen index , or NULL
if no such screen exists. The returned WnckScreen is owned by libwnck and
must not be referenced or unreferenced. [transfer none]
|
WnckScreen * wnck_screen_get_for_root (gulong root_window_id
);
Gets the WnckScreen for the root window at root_window_id
, or
NULL
if no WnckScreen exists for this root window.
This function does not work if wnck_screen_get()
was not called for the
sought WnckScreen before, and returns NULL
.
|
an X window ID. |
Returns : |
the WnckScreen for the root window at
root_window_id , or NULL . The returned WnckScreen is owned by libwnck and
must not be referenced or unreferenced. [transfer none]
|
int wnck_screen_get_number (WnckScreen *screen
);
Gets the index of screen
on the display to which it belongs. The first
WnckScreen has an index of 0.
|
a WnckScreen. |
Returns : |
the index of space on screen , or -1 on errors. |
Since 2.20
int wnck_screen_get_width (WnckScreen *screen
);
Gets the width of screen
.
|
a WnckScreen. |
Returns : |
the width of screen . |
int wnck_screen_get_height (WnckScreen *screen
);
Gets the height of screen
.
|
a WnckScreen. |
Returns : |
the height of screen . |
void wnck_screen_force_update (WnckScreen *screen
);
Synchronously and immediately updates the list of WnckWindow on screen
.
This bypasses the standard update mechanism, where the list of WnckWindow
is updated in the idle loop.
This is usually a bad idea for both performance and correctness reasons (to get things right, you need to write model-view code that tracks changes, not get a static list of open windows). However, this function can be useful for small applications that just do something and then exit.
|
a WnckScreen. |
const char * wnck_screen_get_window_manager_name (WnckScreen *screen
);
Gets the name of the window manager.
|
a WnckScreen. |
Returns : |
the name of the window manager, or NULL if the window manager
does not comply with the EWMH
specification. |
Since 2.20
gboolean wnck_screen_net_wm_supports (WnckScreen *screen
,const char *atom
);
Gets whether the window manager for screen
supports a certain hint from
the Extended
Window Manager Hints specification (EWMH).
When using this function, keep in mind that the window manager can change
over time; so you should not use this function in a way that impacts
persistent application state. A common bug is that your application can
start up before the window manager does when the user logs in, and before
the window manager starts wnck_screen_net_wm_supports()
will return FALSE
for every property.
See also gdk_x11_screen_supports_net_wm_hint()
in GDK.
|
a WnckScreen. |
|
a property atom. |
Returns : |
TRUE if the window manager for screen supports the atom
hint, FALSE otherwise. |
WnckWindow * wnck_screen_get_active_window (WnckScreen *screen
);
Gets the active WnckWindow on screen
. May return NULL
sometimes, since
not all window managers guarantee that a window is always active.
|
a WnckScreen. |
Returns : |
the active WnckWindow on screen , or NULL .
The returned WnckWindow is owned by libwnck and must not be referenced or
unreferenced. [transfer none]
|
WnckWindow * wnck_screen_get_previously_active_window
(WnckScreen *screen
);
Gets the previously active WnckWindow on screen
. May return NULL
sometimes, since not all window managers guarantee that a window is always
active.
|
a WnckScreen. |
Returns : |
the previously active WnckWindow on screen ,
or NULL . The returned WnckWindow is owned by libwnck and must not be
referenced or unreferenced. [transfer none]
|
Since 2.8
GList * wnck_screen_get_windows (WnckScreen *screen
);
Gets the list of WnckWindow on screen
. The list is not in a defined
order, but should be "stable" (windows should not be reordered in it).
However, the stability of the list is established by the window manager, so
don't blame libwnck if it breaks down.
|
a WnckScreen. |
Returns : |
the list of
WnckWindow on screen , or NULL if there is no window on screen . The list
should not be modified nor freed, as it is owned by screen . [element-type WnckWindow][transfer none]
|
GList * wnck_screen_get_windows_stacked (WnckScreen *screen
);
Gets the list of WnckWindow on screen
in bottom-to-top order.
|
a WnckScreen. |
Returns : |
the list of
WnckWindow in stacking order on screen , or NULL if there is no window on
screen . The list should not be modified nor freed, as it is owned by
screen . [element-type WnckWindow][transfer none]
|
WnckWorkspace * wnck_screen_get_active_workspace (WnckScreen *screen
);
Gets the active WnckWorkspace on screen
. May return NULL
sometimes,
if libwnck is in a weird state due to the asynchronous nature of the
interaction with the window manager.
|
a WnckScreen. |
Returns : |
the active WnckWorkspace on screen , or
NULL . The returned WnckWorkspace is owned by libwnck and must not be
referenced or unreferenced. [transfer none]
|
GList * wnck_screen_get_workspaces (WnckScreen *screen
);
Gets the list of WnckWorkspace on screen
. The list is ordered: the
first element in the list is the first WnckWorkspace, etc..
|
a WnckScreen. |
Returns : |
the list of
WnckWorkspace on screen . The list should not be modified nor freed, as it
is owned by screen . [element-type WnckWorkspace][transfer none]
|
Since 2.20
WnckWorkspace * wnck_screen_get_workspace (WnckScreen *screen
,int workspace
);
Gets the WnckWorkspace numbered workspace
on screen
.
|
a WnckScreen. |
|
a workspace index, starting from 0. |
Returns : |
the WnckWorkspace numbered workspace on
screen , or NULL if no such workspace exists. The returned WnckWorkspace
is owned by libwnck and must not be referenced or unreferenced. [transfer none]
|
int wnck_screen_get_workspace_index (WnckScreen *screen
,WnckWorkspace *space
);
wnck_screen_get_workspace_index
has been deprecated since version 2.20 and should not be used in newly-written code. Use wnck_workspace_get_number()
instead.
Gets the index of space
on screen
. The first WnckWorkspace has an
index of 0. See also wnck_workspace_get_number()
.
|
a WnckScreen. |
|
a WnckWorkspace. |
Returns : |
the index of space on screen , or -1 on errors. |
Since 2.14
typedef enum { WNCK_MOTION_UP = -1, WNCK_MOTION_DOWN = -2, WNCK_MOTION_LEFT = -3, WNCK_MOTION_RIGHT = -4 } WnckMotionDirection;
Type defining a direction in which to search a neighbor WnckWorkspace.
search a neighbor WnckWorkspace above another WnckWorkspace. | |
search a neighbor WnckWorkspace below another WnckWorkspace. | |
search a neighbor WnckWorkspace at the left of another WnckWorkspace. | |
search a neighbor WnckWorkspace at the right of another WnckWorkspace. |
Since 2.14
WnckWorkspace * wnck_screen_get_workspace_neighbor (WnckScreen *screen
,WnckWorkspace *space
,WnckMotionDirection direction
);
wnck_screen_get_workspace_neighbor
has been deprecated since version 2.20 and should not be used in newly-written code. Use wnck_workspace_get_neighbor()
instead.
Gets the neighbor WnckWorkspace of space
in the direction
direction on
screen
.
|
a WnckScreen. |
|
a WnckWorkspace. |
|
direction in which to search the neighbor. |
Returns : |
the neighbor WnckWorkspace of space in the
direction direction on screen , or NULL if no such neighbor WnckWorkspace
exists. The returned WnckWorkspace is owned by libwnck and must not be
referenced or unreferenced. [transfer none]
|
Since 2.14
int wnck_screen_get_workspace_count (WnckScreen *screen
);
Gets the number of WnckWorkspace on screen
.
|
a WnckScreen. |
Returns : |
the number of WnckWorkspace on screen . |
void wnck_screen_change_workspace_count (WnckScreen *screen
,int count
);
Asks the window manager to change the number of WnckWorkspace on screen
.
|
a WnckScreen. |
|
the number of WnckWorkspace to request. |
Since 2.2
int wnck_screen_try_set_workspace_layout (WnckScreen *screen
,int current_token
,int rows
,int columns
);
Tries to modify the layout of WnckWorkspace on screen
. To do this, tries
to acquire ownership of the layout. If the current process is the owner of
the layout, current_token
is used to determine if the caller is the owner
(there might be more than one part of the same process trying to set the
layout). Since no more than one application should set this property of
screen
at a time, setting the layout is not guaranteed to work.
If rows
is 0, the actual number of rows will be determined based on
columns
and the number of WnckWorkspace. If columns
is 0, the actual
number of columns will be determined based on rows
and the number of
WnckWorkspace. rows
and columns
must not be 0 at the same time.
You have to release the ownership of the layout with
wnck_screen_release_workspace_layout()
when you do not need it anymore.
|
a WnckScreen. |
|
a token. Use 0 if you do not called
wnck_screen_try_set_workspace_layout() before, or if you did not keep the
old token. |
|
the number of rows to use for the WnckWorkspace layout. |
|
the number of columns to use for the WnckWorkspace layout. |
Returns : |
a token to use for future calls to
wnck_screen_try_set_workspace_layout() and to
wnck_screen_release_workspace_layout() , or 0 if the layout could not be set. |
void wnck_screen_release_workspace_layout (WnckScreen *screen
,int current_token
);
Releases the ownership of the layout of WnckWorkspace on screen
.
current_token
is used to verify that the caller is the owner of the layout.
If the verification fails, nothing happens.
|
a WnckScreen. |
|
the token obtained through
wnck_screen_try_set_workspace_layout() . |
struct WnckWorkspaceLayout { int rows; int cols; int *grid; int grid_area; int current_row; int current_col; };
WnckWorkspaceLayout
has been deprecated since version 2.20 and should not be used in newly-written code.
The WnckWorkspaceLayout struct contains information about the layout of WnckWorkspace on a WnckScreen, and the exact position of a specific WnckWorkspace.
number of rows in the layout grid. | |
number of columns in the layout grid. | |
array of size grid_area containing the index (starting from 0) of
the WnckWorkspace for each position in the layout grid, or -1 if the
position does not correspond to any WnckWorkspace. |
|
size of the grid containing all WnckWorkspace. This can be bigger than the number of WnckWorskpace because the grid might not be filled. | |
row of the specific WnckWorkspace, starting from 0. | |
column of the specific WnckWorkspace, starting from 0. |
Since 2.12
void wnck_screen_calc_workspace_layout (WnckScreen *screen
,int num_workspaces
,int space_index
,WnckWorkspaceLayout *layout
);
wnck_screen_calc_workspace_layout
has been deprecated since version 2.20 and should not be used in newly-written code.
Calculates the layout of WnckWorkspace, with additional information like
the row and column of the WnckWorkspace with index space_index
.
|
a WnckScreen. |
|
the number of WnckWorkspace on screen , or -1 to let
wnck_screen_calc_workspace_layout() find this number. |
|
the index of a Workspace. |
|
return location for the layout of WnckWorkspace with additional information. |
Since 2.12
void wnck_screen_free_workspace_layout (WnckWorkspaceLayout *layout
);
wnck_screen_free_workspace_layout
has been deprecated since version 2.20 and should not be used in newly-written code.
Frees the content of layout
. This does not free layout
itself, so you
might want to free layout
yourself after calling this.
|
a WnckWorkspaceLayout. |
Since 2.12
void wnck_screen_move_viewport (WnckScreen *screen
,int x
,int y
);
Asks the window manager to move the viewport of the current WnckWorkspace
on screen
.
|
a WnckScreen. |
|
X offset in pixels of viewport. |
|
Y offset in pixels of viewport. |
Since 2.4
gulong wnck_screen_get_background_pixmap (WnckScreen *screen
);
Gets the X window ID of the background pixmap of screen
.
|
a WnckScreen. |
Returns : |
the X window ID of the background pixmap of screen . |
gboolean wnck_screen_get_showing_desktop (WnckScreen *screen
);
Gets whether screen
is in the "showing the desktop" mode. This mode is
changed when a "showing-desktop-changed" signal gets emitted.
|
a WnckScreen. |
Returns : |
TRUE if window is fullscreen, FALSE otherwise. |
Since 2.2
void wnck_screen_toggle_showing_desktop (WnckScreen *screen
,gboolean show
);
Asks the window manager to set the "showing the desktop" mode on screen
according to show
.
|
a WnckScreen. |
|
whether to activate the "showing the desktop" mode on screen . |
Since 2.2
"active-window-changed"
signalvoid user_function (WnckScreen *screen,
WnckWindow *previously_active_window,
gpointer user_data) : Run Last
Emitted when the active window on screen
has changed.
|
the WnckScreen which emitted the signal. |
|
the previously active WnckWindow before this change. |
|
user data set when the signal handler was connected. |
"active-workspace-changed"
signalvoid user_function (WnckScreen *screen,
WnckWorkspace *previously_active_space,
gpointer user_data) : Run Last
Emitted when the active workspace on screen
has changed.
|
the WnckScreen which emitted the signal. |
|
the previously active WnckWorkspace before this change. |
|
user data set when the signal handler was connected. |
"application-closed"
signalvoid user_function (WnckScreen *screen,
WnckApplication *app,
gpointer user_data) : Run Last
Emitted when a WnckApplication is closed on screen
.
|
the WnckScreen which emitted the signal. |
|
the closed WnckApplication. |
|
user data set when the signal handler was connected. |
"application-opened"
signalvoid user_function (WnckScreen *screen,
WnckApplication *app,
gpointer user_data) : Run Last
Emitted when a new WnckApplication is opened on screen
.
|
the WnckScreen which emitted the signal. |
|
the opened WnckApplication. |
|
user data set when the signal handler was connected. |
"background-changed"
signalvoid user_function (WnckScreen *screen,
gpointer user_data) : Run Last
Emitted when the background on the root window of screen
has changed.
|
the WnckScreen which emitted the signal. |
|
user data set when the signal handler was connected. |
"class-group-closed"
signalvoid user_function (WnckScreen *screen,
WnckClassGroup *class_group,
gpointer user_data) : Run Last
Emitted when a WnckClassGroup is closed on screen
.
|
the WnckScreen which emitted the signal. |
|
the closed WnckClassGroup. |
|
user data set when the signal handler was connected. |
Since 2.20
"class-group-opened"
signalvoid user_function (WnckScreen *screen,
WnckClassGroup *class_group,
gpointer user_data) : Run Last
Emitted when a new WnckClassGroup is opened on screen
.
|
the WnckScreen which emitted the signal. |
|
the opened WnckClassGroup. |
|
user data set when the signal handler was connected. |
Since 2.20
"showing-desktop-changed"
signalvoid user_function (WnckScreen *screen,
gpointer user_data) : Run Last
Emitted when "showing the desktop" mode of screen
is toggled.
|
the WnckScreen which emitted the signal. |
|
user data set when the signal handler was connected. |
Since 2.20
"viewports-changed"
signalvoid user_function (WnckScreen *screen,
gpointer user_data) : Run Last
Emitted when a viewport position has changed in a WnckWorkspace of
screen
or when a WnckWorkspace of screen
gets or loses its viewport.
|
the WnckScreen which emitted the signal. |
|
user data set when the signal handler was connected. |
Since 2.20
"window-closed"
signalvoid user_function (WnckScreen *screen,
WnckWindow *window,
gpointer user_data) : Run Last
Emitted when a WnckWindow is closed on screen
.
|
the WnckScreen which emitted the signal. |
|
the closed WnckWindow. |
|
user data set when the signal handler was connected. |
"window-manager-changed"
signalvoid user_function (WnckScreen *screen,
gpointer user_data) : Run Last
Emitted when the window manager on screen
has changed.
|
the WnckScreen which emitted the signal. |
|
user data set when the signal handler was connected. |
Since 2.20
"window-opened"
signalvoid user_function (WnckScreen *screen,
WnckWindow *window,
gpointer user_data) : Run Last
Emitted when a new WnckWindow is opened on screen
.
|
the WnckScreen which emitted the signal. |
|
the opened WnckWindow. |
|
user data set when the signal handler was connected. |
"window-stacking-changed"
signalvoid user_function (WnckScreen *screen,
gpointer user_data) : Run Last
Emitted when the stacking order of WnckWindow on screen
has changed.
|
the WnckScreen which emitted the signal. |
|
user data set when the signal handler was connected. |
"workspace-created"
signalvoid user_function (WnckScreen *screen,
WnckWorkspace *space,
gpointer user_data) : Run Last
Emitted when a WnckWorkspace is created on screen
.
|
the WnckScreen which emitted the signal. |
|
the workspace that has been created. |
|
user data set when the signal handler was connected. |
"workspace-destroyed"
signalvoid user_function (WnckScreen *screen,
WnckWorkspace *space,
gpointer user_data) : Run Last
Emitted when a WnckWorkspace is destroyed on screen
.
|
the WnckScreen which emitted the signal. |
|
the workspace that has been destroyed. |
|
user data set when the signal handler was connected. |