diff options
| -rw-r--r-- | ChangeLog | 16 | ||||
| -rw-r--r-- | doc/libwnck-docs.sgml | 6 | ||||
| -rw-r--r-- | doc/tmpl/util.sgml | 6 | ||||
| -rw-r--r-- | libwnck/application.c | 9 | ||||
| -rw-r--r-- | libwnck/pager.c | 73 | ||||
| -rw-r--r-- | libwnck/screen.c | 2 | ||||
| -rw-r--r-- | libwnck/selector.c | 8 | ||||
| -rw-r--r-- | libwnck/tasklist.c | 116 | ||||
| -rw-r--r-- | libwnck/tasklist.h | 26 | ||||
| -rw-r--r-- | libwnck/util.c | 49 | ||||
| -rw-r--r-- | libwnck/util.h | 31 | ||||
| -rw-r--r-- | libwnck/window.c | 4 |
12 files changed, 308 insertions, 38 deletions
@@ -1,6 +1,22 @@ 2007-06-09 Vincent Untz <vuntz@gnome.org> * doc/libwnck-docs.sgml: + * doc/tmpl/util.sgml: + * libwnck/application.c: + * libwnck/pager.c: + * libwnck/screen.c: + * libwnck/selector.c: + * libwnck/tasklist.[ch]: + * libwnck/util.[ch]: + * libwnck/window.c: woohoo, 100% symbol coverage for the API doc! + + * libwnck/util.[ch]: (wnck_xid_read_resource_usage), + (wnck_pid_read_resource_usage): s/unsigned long/gulong/ to please + gtk-doc. + +2007-06-09 Vincent Untz <vuntz@gnome.org> + + * doc/libwnck-docs.sgml: * doc/libwnck-sections.txt: * doc/tmpl/screen.sgml: * libwnck/application.c: diff --git a/doc/libwnck-docs.sgml b/doc/libwnck-docs.sgml index 4ac6fda..2af6f3e 100644 --- a/doc/libwnck-docs.sgml +++ b/doc/libwnck-docs.sgml @@ -33,7 +33,7 @@ </partintro> </part> <!-- TODO - wnck_set_client_type() for pagers-like + tell that wnck_set_client_type() should be used for pagers-like users mention that the window/classgroup/application/workspace/screen are owned by libwnck and should not be ref'ed/unref'ed. mention wnck_screen_force_update() --> @@ -49,18 +49,14 @@ <part id="widgets"> <title>Libwnck Widgets</title> - <!-- TODO proofread + consistency --> <xi:include href="xml/pager.xml"/> - <!-- TODO proofread + consistency --> <xi:include href="xml/selector.xml"/> - <!-- TODO proofread + consistency --> <xi:include href="xml/tasklist.xml"/> </part> <part id="utils"> <title>Libwnck Utilities</title> <xi:include href="xml/window-action-menu.xml"/> - <!-- TODO proofread + consistency --> <xi:include href="xml/util.xml"/> </part> diff --git a/doc/tmpl/util.sgml b/doc/tmpl/util.sgml index b526af4..47c01cc 100644 --- a/doc/tmpl/util.sgml +++ b/doc/tmpl/util.sgml @@ -46,6 +46,8 @@ Miscellaneous Functions </para> +@total_bytes_estimate: +@pixmap_bytes: @n_pixmaps: @n_windows: @n_gcs: @@ -63,7 +65,7 @@ Miscellaneous Functions </para> @gdk_display: -@Param2: +@xid: @usage: @@ -73,7 +75,7 @@ Miscellaneous Functions </para> @gdk_display: -@Param2: +@pid: @usage: diff --git a/libwnck/application.c b/libwnck/application.c index 036d55b..2839e1d 100644 --- a/libwnck/application.c +++ b/libwnck/application.c @@ -33,6 +33,15 @@ * @see_also: wnck_window_get_application() * @stability: Unstable * + * The #WnckApplication is a group of #WnckWindow that are all in the same + * application. It can be used to represent windows by applications, group + * windows by applications or to manipulate all windows of a particular + * application. + * + * A #WnckApplication is identified by the group leader of the #WnckWindow + * belonging to it, and new #WnckWindow are added to a #WnckApplication if and + * only if they have the group leader of the #WnckApplication. + * * The #WnckApplication objects are always owned by libwnck and must not be * referenced or unreferenced. */ diff --git a/libwnck/pager.c b/libwnck/pager.c index 7e10e24..dbbe58b 100644 --- a/libwnck/pager.c +++ b/libwnck/pager.c @@ -1668,6 +1668,13 @@ wnck_pager_focus (GtkWidget *widget, return GTK_WIDGET_CLASS (parent_class)->focus (widget, direction); } +/** + * wnck_pager_set_screen: + * @pager: a #WnckPager. + * @screen: a #WnckScreen. + * + * Sets the #WnckScreen for which @pager should display the #WnckWorkspace. + */ void wnck_pager_set_screen (WnckPager *pager, WnckScreen *screen) @@ -1681,6 +1688,17 @@ wnck_pager_set_screen (WnckPager *pager, wnck_pager_connect_screen (pager, screen); } +/** + * wnck_pager_new: + * @screen: a #WnckScreen. + * + * Creates a new #WnckPager showing the #WnckWorkspace of @screen. + * + * Return value: a newly created #WnckPager showing the #WnckWorkspace of + * @screen. + */ +/* TODO: when we break API again, remove the screen from here and do what we do + * in #WnckSelector */ GtkWidget* wnck_pager_new (WnckScreen *screen) { @@ -1725,6 +1743,26 @@ wnck_pager_set_layout_hint (WnckPager *pager) layout_cols); } +/** + * wnck_pager_set_orientation: + * @pager: a #WnckPager. + * @orientation: orientation to use for the layout of #WnckWorkspace on the + * #WnckScreen @pager is watching. + * + * Tries to change the orientation of the layout of #WnckWorkspace on the + * #WnckScreen @pager is watching. Since no more than one application should + * set this property of a #WnckScreen at a time, setting the layout is not + * guaranteed to work. + * + * If @orientation is %GTK_ORIENTATION_HORIZONTAL, the #WnckWorkspace will be + * laid out in rows, with the first #WnckWorkspace in the top left corner. + * + * If @orientation is %GTK_ORIENTATION_VERTICAL, the #WnckWorkspace will be + * laid out in columns, with the first #WnckWorkspace in the top left corner. + * + * For example, if the layout contains one row, but the orientation of the + * layout is vertical, the #WnckPager will display a column of #WnckWorkspace. + */ void wnck_pager_set_orientation (WnckPager *pager, GtkOrientation orientation) @@ -1740,6 +1778,17 @@ wnck_pager_set_orientation (WnckPager *pager, wnck_pager_set_layout_hint (pager); } +/** + * wnck_pager_set_n_rows: + * @pager: a #WnckPager. + * @n_rows: the number of rows to use for the layout of #WnckWorkspace on the + * #WnckScreen @pager is watching. + * + * Tries to change the number of rows in the layout of #WnckWorkspace on the + * #WnckScreen @pager is watching. Since no more than one application should + * set this property of a #WnckScreen at a time, setting the layout is not + * guaranteed to work. + */ void wnck_pager_set_n_rows (WnckPager *pager, int n_rows) @@ -1756,6 +1805,13 @@ wnck_pager_set_n_rows (WnckPager *pager, wnck_pager_set_layout_hint (pager); } +/** + * wnck_pager_set_display_mode: + * @pager: a #WnckPager. + * @mode: a display mode. + * + * Sets the display mode for @pager to @mode. + */ void wnck_pager_set_display_mode (WnckPager *pager, WnckPagerDisplayMode mode) @@ -1769,6 +1825,14 @@ wnck_pager_set_display_mode (WnckPager *pager, gtk_widget_queue_resize (GTK_WIDGET (pager)); } +/** + * wnck_pager_set_show_all: + * @pager: a #WnckPager. + * @show_all_workspaces: whether to display all #WnckWorkspace in @pager. + * + * Sets @pager to display all #WnckWorkspace or not, according to + * @show_all_workspaces. + */ void wnck_pager_set_show_all (WnckPager *pager, gboolean show_all_workspaces) @@ -1784,6 +1848,15 @@ wnck_pager_set_show_all (WnckPager *pager, gtk_widget_queue_resize (GTK_WIDGET (pager)); } +/** + * wnck_pager_set_shadow_type: + * @pager: a #WnckPager. + * @shadow_type: a shadow type. + * + * Sets the shadow type for @pager to @shadow_type. The main use of this + * function is proper integration of #WnckPager in panels with non-system + * backgrounds. + */ void wnck_pager_set_shadow_type (WnckPager * pager, GtkShadowType shadow_type) diff --git a/libwnck/screen.c b/libwnck/screen.c index 69f28bd..0c5fc75 100644 --- a/libwnck/screen.c +++ b/libwnck/screen.c @@ -1027,7 +1027,7 @@ _wnck_screen_process_property_notify (WnckScreen *screen, * the row and column of the #WnckWorkspace with index @space_index. * */ -/* FIXME: when we break API again, remove num_workspaces since we can get it +/* TODO: when we break API again, remove num_workspaces since we can get it * from screen! */ void wnck_screen_calc_workspace_layout (WnckScreen *screen, diff --git a/libwnck/selector.c b/libwnck/selector.c index 416b5f3..53b22b1 100644 --- a/libwnck/selector.c +++ b/libwnck/selector.c @@ -1338,6 +1338,14 @@ wnck_selector_unrealize (GtkWidget *widget) GTK_WIDGET_CLASS (wnck_selector_parent_class)->unrealize (widget); } +/** + * wnck_selector_new: + * + * Creates a new #WnckSelector. The #WnckSelector will list #WnckWindow of the + * #WnckScreen it is on. + * + * Return value: a newly created #WnckSelector. + */ GtkWidget * wnck_selector_new (void) { diff --git a/libwnck/tasklist.c b/libwnck/tasklist.c index 890a712..9e79cb4 100644 --- a/libwnck/tasklist.c +++ b/libwnck/tasklist.c @@ -801,6 +801,13 @@ wnck_tasklist_finalize (GObject *object) G_OBJECT_CLASS (tasklist_parent_class)->finalize (object); } +/** + * wnck_tasklist_set_grouping: + * @tasklist: a #WnckTasklist. + * @grouping: a grouping policy. + * + * Sets the grouping policy for @tasklist to @grouping. + */ void wnck_tasklist_set_grouping (WnckTasklist *tasklist, WnckTasklistGroupingType grouping) @@ -822,6 +829,15 @@ wnck_tasklist_set_relief_callback (WnckWindow *win, gtk_button_set_relief (GTK_BUTTON (task->button), tasklist->priv->relief); } +/** + * wnck_tasklist_set_button_relief: + * @tasklist: a #WnckTasklist. + * @relief: a relief type. + * + * Sets the relief type of the buttons in @tasklist to @relief. The main use of + * this function is proper integration of #WnckTasklist in panels with + * non-system backgrounds. + */ void wnck_tasklist_set_button_relief (WnckTasklist *tasklist, GtkReliefStyle relief) { @@ -839,6 +855,17 @@ wnck_tasklist_set_button_relief (WnckTasklist *tasklist, GtkReliefStyle relief) gtk_button_set_relief (GTK_BUTTON (WNCK_TASK (walk->data)->button), relief); } +/** + * wnck_tasklist_set_switch_workspace_on_unminimize: + * @tasklist: a #WnckTasklist. + * @switch_workspace_on_unminimize: whether to activate the #WnckWorkspace a + * #WnckWindow is on when unminimizing it. + * + * Sets @tasklist to activate or not the #WnckWorkspace a #WnckWindow is on + * when unminimizing it, according to @switch_workspace_on_unminimize. + * + * FIXME: does it still work? + */ void wnck_tasklist_set_switch_workspace_on_unminimize (WnckTasklist *tasklist, gboolean switch_workspace_on_unminimize) @@ -848,6 +875,15 @@ wnck_tasklist_set_switch_workspace_on_unminimize (WnckTasklist *tasklist, tasklist->priv->switch_workspace_on_unminimize = switch_workspace_on_unminimize; } +/** + * wnck_tasklist_set_include_all_workspaces: + * @tasklist: a #WnckTasklist. + * @include_all_workspaces: whether to display #WnckWindow from all + * #WnckWorkspace in @tasklist. + * + * Sets @tasklist to display #WnckWindow from all #WnckWorkspace or not, + * according to @include_all_workspaces. + */ void wnck_tasklist_set_include_all_workspaces (WnckTasklist *tasklist, gboolean include_all_workspaces) @@ -864,6 +900,16 @@ wnck_tasklist_set_include_all_workspaces (WnckTasklist *tasklist, gtk_widget_queue_resize (GTK_WIDGET (tasklist)); } +/** + * wnck_tasklist_set_grouping_limit: + * @tasklist: a #WnckTasklist. + * @limit: a size in pixels. + * + * Sets the maximum size of buttons in @tasklist before @tasklist tries to + * group #WnckWindow in the same #WnckApplication in only one button. This + * limit is valid only when the grouping policy of @tasklist is + * %WNCK_TASKLIST_AUTO_GROUP. + */ void wnck_tasklist_set_grouping_limit (WnckTasklist *tasklist, gint limit) @@ -877,8 +923,14 @@ wnck_tasklist_set_grouping_limit (WnckTasklist *tasklist, gtk_widget_queue_resize (GTK_WIDGET (tasklist)); } -/* set the minimum width - * use -1 to unset it (resulting in the default width */ +/** + * wnck_tasklist_set_minimum_width: + * @tasklist: a #WnckTasklist. + * @size: a minimum width in pixels. + * + * Sets the minimum width to use for @tasklist to @size pixels. If @size is -1, + * sets the minimum width to a default. + */ void wnck_tasklist_set_minimum_width (WnckTasklist *tasklist, gint size) { @@ -893,7 +945,14 @@ wnck_tasklist_set_minimum_width (WnckTasklist *tasklist, gint size) gtk_widget_queue_resize (GTK_WIDGET (tasklist)); } -/* get the minimum width */ +/** + * wnck_tasklist_get_minimum_width: + * @tasklist: a #WnckTasklist. + * + * Returns the minimum width of @tasklist. + * + * Return value: the minimum width of @tasklist. + */ gint wnck_tasklist_get_minimum_width (WnckTasklist *tasklist) { @@ -902,8 +961,14 @@ wnck_tasklist_get_minimum_width (WnckTasklist *tasklist) return tasklist->priv->minimum_width; } -/* set the minimum height - * use -1 to unset it (resulting in the default height */ +/** + * wnck_tasklist_set_minimum_height: + * @tasklist: a #WnckTasklist. + * @size: a minimum height in pixels. + * + * Sets the minimum height to use for @tasklist to @size pixels. If @size is -1, + * sets the minimum height to a default. + */ void wnck_tasklist_set_minimum_height (WnckTasklist *tasklist, gint size) { @@ -918,7 +983,14 @@ wnck_tasklist_set_minimum_height (WnckTasklist *tasklist, gint size) gtk_widget_queue_resize (GTK_WIDGET (tasklist)); } -/* get the minimum height */ +/** + * wnck_tasklist_get_minimum_height: + * @tasklist: a #WnckTasklist. + * + * Returns the minimum height of @tasklist. + * + * Return value: the minimum height of @tasklist. + */ gint wnck_tasklist_get_minimum_height (WnckTasklist *tasklist) { @@ -1261,6 +1333,21 @@ wnck_tasklist_size_request (GtkWidget *widget, tasklist->priv->size_hints = (int *)g_array_free (array, FALSE); } +/** + * wnck_tasklist_get_size_hint_list: + * @tasklist: a #WnckTasklist. + * @n_elements: return location for the number of elements in the array + * returned by this function. This number should always be pair. + * + * Since a #WnckTasklist does not have a fixed size (#WnckWindow can be grouped + * when needed, for example), the standard size request mechanism in GTK+ is + * not enough to announce what sizes can be used by @tasklist. The size hints + * mechanism is a solution for this. See panel_applet_set_size_hints() for more + * information. + * + * Return value: a list of size hints that can be used to allocate an + * appropriate size for @tasklist. + */ const int * wnck_tasklist_get_size_hint_list (WnckTasklist *tasklist, int *n_elements) @@ -1693,6 +1780,13 @@ wnck_tasklist_disconnect_screen (WnckTasklist *tasklist) #endif } +/** + * wnck_tasklist_set_screen: + * @tasklist: a #WnckTasklist. + * @screen: a #WnckScreen. + * + * Sets the #WnckScreen for which @tasklist should list the #WnckWindow. + */ void wnck_tasklist_set_screen (WnckTasklist *tasklist, WnckScreen *screen) @@ -1832,6 +1926,16 @@ wnck_tasklist_scroll_cb (WnckTasklist *tasklist, return TRUE; } +/** + * wnck_tasklist_new: + * @screen: a #WnckScreen. + * + * Creates a new #WnckTasklist listing #WnckWindow of @screen. + * + * Return value: a newly created #WnckTasklist listing #WnckWindow of @screen. + */ +/* TODO: when we break API again, remove the screen from here and do what we do + * in #WnckSelector */ GtkWidget* wnck_tasklist_new (WnckScreen *screen) { diff --git a/libwnck/tasklist.h b/libwnck/tasklist.h index 00cb2b0..d816f84 100644 --- a/libwnck/tasklist.h +++ b/libwnck/tasklist.h @@ -62,6 +62,19 @@ struct _WnckTasklistClass void (* pad4) (void); }; +/** + * WnckTasklistGroupingType: + * @WNCK_TASKLIST_NEVER_GROUP: never group multiple #WnckWindow of the same + * #WnckApplication. + * @WNCK_TASKLIST_AUTO_GROUP: group multiple #WnckWindow of the same + * #WnckApplication for some #WnckApplication, when there is not enough place + * to have a good-looking list of all #WnckWindow. + * @WNCK_TASKLIST_ALWAYS_GROUP: always group multiple #WnckWindow of the same + * #WnckApplication, for all #WnckApplication. + * + * Type defining the policy of the #WnckTasklist for grouping multiple + * #WnckWindow of the same #WnckApplication. + */ typedef enum { WNCK_TASKLIST_NEVER_GROUP, WNCK_TASKLIST_AUTO_GROUP, @@ -93,13 +106,18 @@ gint wnck_tasklist_get_minimum_height (WnckTasklist *tasklist); /** * WnckLoadIconFunction: - * @icon_name: an icon name as in the Icon field in a .desktop file. - * @size: + * @icon_name: an icon name as in the Icon field in a .desktop file for the + * icon to load. + * @size: the desired icon size. * @flags: not defined to do anything yet. - * @data: + * @data: data passed to the function, set when the #WnckLoadIconFunction has + * been set for the #WnckTasklist. * + * Specifies the type of function passed to wnck_tasklist_set_icon_loader(). * - * Returns: + * Returns: it should return a <classname>GdkPixbuf</classname> of @icon_name + * at size @size, or %NULL if no icon for @icon_name at size @size could be + * loaded. */ typedef GdkPixbuf* (*WnckLoadIconFunction) (const char *icon_name, int size, diff --git a/libwnck/util.c b/libwnck/util.c index dc1c91e..438da63 100644 --- a/libwnck/util.c +++ b/libwnck/util.c @@ -48,6 +48,14 @@ set_dock_realize_handler (GtkWidget *widget, gpointer data) _wnck_set_dock_type_hint (GDK_WINDOW_XWINDOW (widget->window)); } +/** + * wnck_gtk_window_set_dock_type: + * @window: a <classname>GtkWindow</classname>. + * + * Sets the semantic type of @window to %WNCK_WINDOW_DOCK. + */ +/* TODO: when we break API again, remove this: nothing is using it, and it + * looks useless... */ void wnck_gtk_window_set_dock_type (GtkWindow *window) { @@ -65,9 +73,21 @@ typedef enum WNCK_EXT_MISSING = 2 } WnckExtStatus; +/** + * wnck_xid_read_resource_usage: + * @gdk_display: a <classname>GdkDisplay</classname>. + * @xid: an X window ID. + * @usage: return location for the X resource usage of the application owning + * the X window ID @xid. + * + * Looks for the X resource usage of the application owning the X window ID + * @xid on display @gdisplay. + * + * To properly work, this function requires the XRes extension on the X server. + */ void wnck_xid_read_resource_usage (GdkDisplay *gdisplay, - unsigned long xid, + gulong xid, WnckResourceUsage *usage) { int event, error; @@ -197,9 +217,26 @@ wnck_xid_read_resource_usage (GdkDisplay *gdisplay, #endif /* HAVE_XRES */ } +/** + * wnck_pid_read_resource_usage: + * @gdk_display: a <classname>GdkDisplay</classname>. + * @pid: a process ID. + * @usage: return location for the X resource usage of the application with + * process ID @pid. + * + * Looks for the X resource usage of the application with process ID @pid on + * display @gdisplay. + * + * To properly work, this function requires the XRes extension on the X server. + * + * A current limitation of this function is that this does not work for + * processes that do not have an X window visible to libwnck. This includes + * processes that do not have any toplevel windows (panel applets, for + * example). + */ void wnck_pid_read_resource_usage (GdkDisplay *gdisplay, - unsigned long pid, + gulong pid, WnckResourceUsage *usage) { Display *xdisplay; @@ -249,6 +286,14 @@ wnck_pid_read_resource_usage (GdkDisplay *gdisplay, static WnckClientType client_type = 0; +/** + * wnck_set_client_type: + * @ewmh_sourceindication_client_type: a role for the client. + * + * Sets the role of the libwnck user. For applications providing some window + * management features, like pagers or tasklists, it is important to set the + * role to %WNCK_CLIENT_TYPE_PAGER for libwnck to properly work. + */ void wnck_set_client_type (WnckClientType ewmh_sourceindication_client_type) { diff --git a/libwnck/util.h b/libwnck/util.h index 0bf8760..44380db 100644 --- a/libwnck/util.h +++ b/libwnck/util.h @@ -32,17 +32,17 @@ typedef struct _WnckResourceUsage WnckResourceUsage; * @total_bytes_estimate: estimation of the total number of bytes allocated in * the X server. * @pixmap_bytes: number of bytes allocated in the X server for resources of - * type PIXMAP. - * @n_pixmaps: number of PIXMAP resources allocated. - * @n_windows: - * @n_gcs: - * @n_pictures: - * @n_glyphsets: - * @n_fonts: - * @n_colormap_entries: - * @n_passive_grabs: - * @n_cursors: - * @n_other: + * type Pixmap. + * @n_pixmaps: number of Pixmap resources allocated. + * @n_windows: number of Window resources allocated. + * @n_gcs: number of GContext resources allocated. + * @n_pictures: number of Picture resources allocated. + * @n_glyphsets: number of Glyphset resources allocated. + * @n_fonts: number of Font resources allocated. + * @n_colormap_entries: number of Colormap resources allocated. + * @n_passive_grabs: number of PassiveGrab resources allocated. + * @n_cursors: number of Cursor resources allocated. + * @n_other: number of other resources allocated. * * The #WnckResourceUsage struct contains information about the total resource * usage of an X client, and the number of resources allocated for each @@ -50,9 +50,9 @@ typedef struct _WnckResourceUsage WnckResourceUsage; */ struct _WnckResourceUsage { - unsigned long total_bytes_estimate; + gulong total_bytes_estimate; - unsigned long pixmap_bytes; + gulong pixmap_bytes; unsigned int n_pixmaps; unsigned int n_windows; @@ -75,7 +75,6 @@ struct _WnckResourceUsage unsigned long pad7; unsigned long pad8; unsigned long pad9; - }; /** @@ -96,11 +95,11 @@ void wnck_gtk_window_set_dock_type (GtkWindow *window); void wnck_set_client_type (WnckClientType ewmh_sourceindication_client_type); void wnck_xid_read_resource_usage (GdkDisplay *gdk_display, - unsigned long xid, + gulong xid, WnckResourceUsage *usage); void wnck_pid_read_resource_usage (GdkDisplay *gdk_display, - unsigned long pid, + gulong pid, WnckResourceUsage *usage); #endif /* WNCK_UTIL_H */ diff --git a/libwnck/window.c b/libwnck/window.c index 8c2948e..cf63414 100644 --- a/libwnck/window.c +++ b/libwnck/window.c @@ -817,9 +817,9 @@ wnck_window_get_window_type (WnckWindow *window) /** * wnck_window_set_window_type: * @window: a #WnckWindow. - * @wintype: the new semantic type for @window. + * @wintype: a semantic type. * - * Sets the semantic type of @window. + * Sets the semantic type of @window to @wintype. **/ void wnck_window_set_window_type (WnckWindow *window, WnckWindowType wintype) |