From e52986f4225cbe8496043da74ca250521d244705 Mon Sep 17 00:00:00 2001 From: Matthew Barnes Date: Wed, 1 Oct 2008 18:58:37 +0000 Subject: Add more EShell API documentation. svn path=/branches/kill-bonobo/; revision=36533 --- addressbook/gui/widgets/e-addressbook-view.c | 4 +- calendar/modules/e-cal-shell-view-private.c | 4 +- calendar/modules/e-memo-shell-view-private.c | 4 +- calendar/modules/e-task-shell-view-private.c | 4 +- doc/reference/shell/eshell-sections.txt | 25 ++- doc/reference/shell/tmpl/e-shell-view.sgml | 27 ++- doc/reference/shell/tmpl/eshell-unused.sgml | 8 + shell/e-shell-sidebar.c | 76 ++++++++ shell/e-shell-taskbar.c | 52 ++++++ shell/e-shell-view.c | 252 +++++++++++++++++++++++++-- shell/e-shell-view.h | 46 ++++- shell/test/e-test-shell-view.c | 4 +- 12 files changed, 465 insertions(+), 41 deletions(-) diff --git a/addressbook/gui/widgets/e-addressbook-view.c b/addressbook/gui/widgets/e-addressbook-view.c index 67d753c8a8..550fb2dc23 100644 --- a/addressbook/gui/widgets/e-addressbook-view.c +++ b/addressbook/gui/widgets/e-addressbook-view.c @@ -854,9 +854,11 @@ status_message (EAddressbookView *view, { EActivity *activity; EShellView *shell_view; + EShellModule *shell_module; activity = view->priv->activity; shell_view = e_addressbook_view_get_shell_view (view); + shell_module = e_shell_view_get_shell_module (shell_view); if (status == NULL || *status == '\0') { if (activity != NULL) { @@ -868,7 +870,7 @@ status_message (EAddressbookView *view, } else if (activity == NULL) { activity = e_activity_new (status); view->priv->activity = activity; - e_shell_view_add_activity (shell_view, activity); + e_shell_module_add_activity (shell_module, activity); } else e_activity_set_primary_text (activity, status); diff --git a/calendar/modules/e-cal-shell-view-private.c b/calendar/modules/e-cal-shell-view-private.c index 75d0e0e8db..d738d230b3 100644 --- a/calendar/modules/e-cal-shell-view-private.c +++ b/calendar/modules/e-cal-shell-view-private.c @@ -172,11 +172,13 @@ e_cal_shell_view_set_status_message (ECalShellView *cal_shell_view, { EActivity *activity; EShellView *shell_view; + EShellModule *shell_module; g_return_if_fail (E_IS_CAL_SHELL_VIEW (cal_shell_view)); activity = cal_shell_view->priv->activity; shell_view = E_SHELL_VIEW (cal_shell_view); + shell_module = e_shell_view_get_shell_module (shell_view); if (status_message == NULL || *status_message == '\0') { if (activity != NULL) { @@ -187,7 +189,7 @@ e_cal_shell_view_set_status_message (ECalShellView *cal_shell_view, } else if (activity == NULL) { activity = e_activity_new (status_message); - e_shell_view_add_activity (shell_view, activity); + e_shell_module_add_activity (shell_module, activity); } else e_activity_set_primary_text (activity, status_message); diff --git a/calendar/modules/e-memo-shell-view-private.c b/calendar/modules/e-memo-shell-view-private.c index 9fa67bbb30..b4df0ccf9b 100644 --- a/calendar/modules/e-memo-shell-view-private.c +++ b/calendar/modules/e-memo-shell-view-private.c @@ -448,11 +448,13 @@ e_memo_shell_view_set_status_message (EMemoShellView *memo_shell_view, { EActivity *activity; EShellView *shell_view; + EShellModule *shell_module; g_return_if_fail (E_IS_MEMO_SHELL_VIEW (memo_shell_view)); activity = memo_shell_view->priv->activity; shell_view = E_SHELL_VIEW (memo_shell_view); + shell_module = e_shell_view_get_shell_module (shell_view); if (status_message == NULL || *status_message == '\0') { if (activity != NULL) { @@ -463,7 +465,7 @@ e_memo_shell_view_set_status_message (EMemoShellView *memo_shell_view, } else if (activity == NULL) { activity = e_activity_new (status_message); - e_shell_view_add_activity (shell_view, activity); + e_shell_module_add_activity (shell_module, activity); } else e_activity_set_primary_text (activity, status_message); diff --git a/calendar/modules/e-task-shell-view-private.c b/calendar/modules/e-task-shell-view-private.c index 0b81de1186..a038194cf5 100644 --- a/calendar/modules/e-task-shell-view-private.c +++ b/calendar/modules/e-task-shell-view-private.c @@ -427,11 +427,13 @@ e_task_shell_view_set_status_message (ETaskShellView *task_shell_view, { EActivity *activity; EShellView *shell_view; + EShellModule *shell_module; g_return_if_fail (E_IS_TASK_SHELL_VIEW (task_shell_view)); activity = task_shell_view->priv->activity; shell_view = E_SHELL_VIEW (task_shell_view); + shell_module = e_shell_view_get_shell_module (shell_view); if (status_message == NULL || *status_message == '\0') { if (activity != NULL) { @@ -442,7 +444,7 @@ e_task_shell_view_set_status_message (ETaskShellView *task_shell_view, } else if (activity == NULL) { activity = e_activity_new (status_message); - e_shell_view_add_activity (shell_view, activity); + e_shell_module_add_activity (shell_module, activity); } else e_activity_set_primary_text (activity, status_message); diff --git a/doc/reference/shell/eshell-sections.txt b/doc/reference/shell/eshell-sections.txt index fc9a599558..2a7b3d81b2 100644 --- a/doc/reference/shell/eshell-sections.txt +++ b/doc/reference/shell/eshell-sections.txt @@ -23,10 +23,11 @@ e_shell_quit E_SHELL E_IS_SHELL E_TYPE_SHELL -e_shell_get_type E_SHELL_CLASS E_IS_SHELL_CLASS E_SHELL_GET_CLASS +EShellClass +e_shell_get_type EShellPrivate @@ -35,6 +36,7 @@ EShellPrivate e-shell-view EShellView EShellView +EShellViewClass e_shell_view_get_name e_shell_view_get_action e_shell_view_get_title @@ -42,7 +44,6 @@ e_shell_view_set_title e_shell_view_get_view_id e_shell_view_set_view_id e_shell_view_is_active -e_shell_view_add_activity e_shell_view_get_page_num e_shell_view_get_size_group e_shell_view_get_shell_content @@ -56,10 +57,10 @@ e_shell_view_show_popup_menu E_SHELL_VIEW E_IS_SHELL_VIEW E_TYPE_SHELL_VIEW -e_shell_view_get_type E_SHELL_VIEW_CLASS E_IS_SHELL_VIEW_CLASS E_SHELL_VIEW_GET_CLASS +e_shell_view_get_type EShellViewPrivate @@ -79,10 +80,11 @@ e_shell_switcher_set_visible E_SHELL_SWITCHER E_IS_SHELL_SWITCHER E_TYPE_SHELL_SWITCHER -e_shell_switcher_get_type E_SHELL_SWITCHER_CLASS E_IS_SHELL_SWITCHER_CLASS E_SHELL_SWITCHER_GET_CLASS +EShellSwitcherClass +e_shell_switcher_get_type EShellSwitcherPrivate E_SHELL_SWITCHER_DEFAULT_TOOLBAR_STYLE @@ -97,10 +99,11 @@ e_shell_sidebar_new E_SHELL_SIDEBAR E_IS_SHELL_SIDEBAR E_TYPE_SHELL_SIDEBAR -e_shell_sidebar_get_type E_SHELL_SIDEBAR_CLASS E_IS_SHELL_SIDEBAR_CLASS E_SHELL_SIDEBAR_GET_CLASS +EShellSidebarClass +e_shell_sidebar_get_type EShellSidebarPrivate @@ -114,10 +117,11 @@ e_shell_taskbar_new E_SHELL_TASKBAR E_IS_SHELL_TASKBAR E_TYPE_SHELL_TASKBAR -e_shell_taskbar_get_type E_SHELL_TASKBAR_CLASS E_IS_SHELL_TASKBAR_CLASS E_SHELL_TASKBAR_GET_CLASS +EShellTaskbarClass +e_shell_taskbar_get_type EShellTaskbarPrivate @@ -142,10 +146,11 @@ e_shell_module_set_info E_SHELL_MODULE E_IS_SHELL_MODULE E_TYPE_SHELL_MODULE -e_shell_module_get_type E_SHELL_MODULE_CLASS E_IS_SHELL_MODULE_CLASS E_SHELL_MODULE_GET_CLASS +EShellModuleClass +e_shell_module_get_type EShellModulePrivate @@ -159,10 +164,11 @@ e_shell_content_new E_SHELL_CONTENT E_IS_SHELL_CONTENT E_TYPE_SHELL_CONTENT -e_shell_content_get_type E_SHELL_CONTENT_CLASS E_IS_SHELL_CONTENT_CLASS E_SHELL_CONTENT_GET_CLASS +EShellContentClass +e_shell_content_get_type EShellContentPrivate @@ -188,10 +194,11 @@ e_shell_window_register_new_source_actions E_SHELL_WINDOW E_IS_SHELL_WINDOW E_TYPE_SHELL_WINDOW -e_shell_window_get_type E_SHELL_WINDOW_CLASS E_IS_SHELL_WINDOW_CLASS E_SHELL_WINDOW_GET_CLASS +EShellWindowClass +e_shell_window_get_type EShellWindowPrivate E_SHELL_WINDOW_ACTION diff --git a/doc/reference/shell/tmpl/e-shell-view.sgml b/doc/reference/shell/tmpl/e-shell-view.sgml index b6d35b18be..b5ee5e22a6 100644 --- a/doc/reference/shell/tmpl/e-shell-view.sgml +++ b/doc/reference/shell/tmpl/e-shell-view.sgml @@ -77,6 +77,24 @@ EShellView + + + + + +@parent_class: +@label: +@icon_name: +@ui_definition: +@search_options: +@type_module: +@view_collection: +@new_shell_content: +@new_shell_sidebar: +@new_shell_taskbar: +@toggled: +@update_actions: + @@ -140,15 +158,6 @@ EShellView @Returns: - - - - - -@shell_view: -@activity: - - diff --git a/doc/reference/shell/tmpl/eshell-unused.sgml b/doc/reference/shell/tmpl/eshell-unused.sgml index 9360a7003c..80bd636991 100644 --- a/doc/reference/shell/tmpl/eshell-unused.sgml +++ b/doc/reference/shell/tmpl/eshell-unused.sgml @@ -5,3 +5,11 @@ @window: + + + + + +@shell_view: +@activity: + diff --git a/shell/e-shell-sidebar.c b/shell/e-shell-sidebar.c index 6694eacd96..db77ceb168 100644 --- a/shell/e-shell-sidebar.c +++ b/shell/e-shell-sidebar.c @@ -331,6 +331,11 @@ shell_sidebar_class_init (EShellSidebarClass *class) container_class->remove = shell_sidebar_remove; container_class->forall = shell_sidebar_forall; + /** + * EShellTaskbar:primary-text + * + * The primary text is displayed in bold at the top of the sidebar. + **/ g_object_class_install_property ( object_class, PROP_PRIMARY_TEXT, @@ -341,6 +346,12 @@ shell_sidebar_class_init (EShellSidebarClass *class) NULL, G_PARAM_READWRITE)); + /** + * EShellTaskbar:secondary-text + * + * The secondary text is displayed in a smaller font at the top of + * the sidebar. + **/ g_object_class_install_property ( object_class, PROP_SECONDARY_TEXT, @@ -351,6 +362,11 @@ shell_sidebar_class_init (EShellSidebarClass *class) NULL, G_PARAM_READWRITE)); + /** + * EShellSidebar:shell-view + * + * The #EShellView to which the sidebar widget belongs. + **/ g_object_class_install_property ( object_class, PROP_SHELL_VIEW, @@ -411,6 +427,12 @@ e_shell_sidebar_get_type (void) return type; } +/** + * e_shell_sidebar_new: + * @shell_view: an #EShellView + * + * Creates a new #EShellSidebar instance belonging to @shell_view. + **/ GtkWidget * e_shell_sidebar_new (EShellView *shell_view) { @@ -421,6 +443,14 @@ e_shell_sidebar_new (EShellView *shell_view) "shell-view", shell_view, NULL); } +/** + * e_shell_sidebar_get_shell_view: + * @shell_sidebar: an #EShellSidebar + * + * Returns the #EShellView that was passed to e_shell_sidebar_new(). + * + * Returns: the #EShellView to which @shell_sidebar belongs + **/ EShellView * e_shell_sidebar_get_shell_view (EShellSidebar *shell_sidebar) { @@ -429,6 +459,18 @@ e_shell_sidebar_get_shell_view (EShellSidebar *shell_sidebar) return E_SHELL_VIEW (shell_sidebar->priv->shell_view); } +/** + * e_shell_sidebar_get_primary_text: + * @shell_sidebar: an #EShellSidebar + * + * Returns the primary text for @shell_sidebar. + * + * The primary text is displayed in bold at the top of the sidebar. It + * defaults to the shell view's label (as seen on the switcher button), + * but typically shows the name of the selected item in the sidebar. + * + * Returns: the primary text for @shell_sidebar + **/ const gchar * e_shell_sidebar_get_primary_text (EShellSidebar *shell_sidebar) { @@ -437,6 +479,16 @@ e_shell_sidebar_get_primary_text (EShellSidebar *shell_sidebar) return shell_sidebar->priv->primary_text; } +/** + * e_shell_sidebar_set_primary_text: + * @shell_sidebar: an #EShellSidebar + * + * Sets the primary text for @shell_sidebar. + * + * The primary text is displayed in bold at the top of the sidebar. It + * defaults to the shell view's label (as seen on the switcher button), + * but typically shows the name of the selected item in the sidebar. + **/ void e_shell_sidebar_set_primary_text (EShellSidebar *shell_sidebar, const gchar *primary_text) @@ -461,6 +513,19 @@ e_shell_sidebar_set_primary_text (EShellSidebar *shell_sidebar, g_object_notify (G_OBJECT (shell_sidebar), "primary-text"); } +/** + * e_shell_sidebar_get_secondary_text: + * @shell_sidebar: an #EShellSidebar + * + * Returns the secondary text for @shell_sidebar. + * + * The secondary text is displayed in a smaller font at the top of the + * sidebar. It typically shows information about the contents of the + * selected sidebar item, such as total number of items, number of + * selected items, etc. + * + * Returns: the secondary text for @shell_sidebar + **/ const gchar * e_shell_sidebar_get_secondary_text (EShellSidebar *shell_sidebar) { @@ -469,6 +534,17 @@ e_shell_sidebar_get_secondary_text (EShellSidebar *shell_sidebar) return shell_sidebar->priv->secondary_text; } +/** + * e_shell_sidebar_set_secondary_text: + * @shell_sidebar: an #EShellSidebar + * + * Sets the secondary text for @shell_sidebar. + * + * The secondary text is displayed in a smaller font at the top of the + * sidebar. It typically shows information about the contents of the + * selected sidebar item, such as total number of items, number of + * selected items, etc. + **/ void e_shell_sidebar_set_secondary_text (EShellSidebar *shell_sidebar, const gchar *secondary_text) diff --git a/shell/e-shell-taskbar.c b/shell/e-shell-taskbar.c index 24ce2c9994..3f66a89132 100644 --- a/shell/e-shell-taskbar.c +++ b/shell/e-shell-taskbar.c @@ -225,6 +225,11 @@ shell_taskbar_class_init (EShellTaskbarClass *class) object_class->finalize = shell_taskbar_finalize; object_class->constructed = shell_taskbar_constructed; + /** + * EShellTaskbar:message + * + * The message to display in the taskbar. + **/ g_object_class_install_property ( object_class, PROP_MESSAGE, @@ -236,6 +241,11 @@ shell_taskbar_class_init (EShellTaskbarClass *class) G_PARAM_READWRITE | G_PARAM_CONSTRUCT)); + /** + * EShellTaskbar:shell-view + * + * The #EShellView to which the taskbar widget belongs. + **/ g_object_class_install_property ( object_class, PROP_SHELL_VIEW, @@ -311,6 +321,14 @@ e_shell_taskbar_get_type (void) return type; } +/** + * e_shell_taskbar_new: + * @shell_view: an #EShellView + * + * Creates a new #EShellTaskbar instance belonging to @shell_view. + * + * Returns: a new #EShellTaskbar instance + **/ GtkWidget * e_shell_taskbar_new (EShellView *shell_view) { @@ -320,6 +338,14 @@ e_shell_taskbar_new (EShellView *shell_view) E_TYPE_SHELL_TASKBAR, "shell-view", shell_view, NULL); } +/** + * e_shell_taskbar_get_shell_view: + * @shell_taskbar: an #EShellTaskbar + * + * Returns the #EShellView that was passed to e_shell_taskbar_new(). + * + * Returns: the #EShellView to which @shell_taskbar belongs + **/ EShellView * e_shell_taskbar_get_shell_view (EShellTaskbar *shell_taskbar) { @@ -328,6 +354,16 @@ e_shell_taskbar_get_shell_view (EShellTaskbar *shell_taskbar) return shell_taskbar->priv->shell_view; } +/** + * e_shell_taskbar_get_message: + * @shell_taskbar: an #EShellTaskbar + * + * Returns the message currently shown in the taskbar, or an empty string + * if no message is shown. Taskbar messages are used primarily for menu + * tooltips. + * + * Returns: the current taskbar message + **/ const gchar * e_shell_taskbar_get_message (EShellTaskbar *shell_taskbar) { @@ -340,6 +376,15 @@ e_shell_taskbar_get_message (EShellTaskbar *shell_taskbar) return gtk_label_get_text (GTK_LABEL (label)); } +/** + * e_shell_taskbar_set_message: + * @shell_taskbar: an #EShellTaskbar + * @message: the message to show + * + * Shows a message in the taskbar. If @message is %NULL or an empty string, + * the taskbar message is cleared. Taskbar messages are used primarily for + * menu tooltips. + **/ void e_shell_taskbar_set_message (EShellTaskbar *shell_taskbar, const gchar *message) @@ -359,6 +404,13 @@ e_shell_taskbar_set_message (EShellTaskbar *shell_taskbar, g_object_notify (G_OBJECT (shell_taskbar), "message"); } +/** + * e_shell_taskbar_unset_message: + * @shell_taskbar: an #EShellTaskbar + * + * This is equivalent to passing a %NULL message to + * e_shell_taskbar_set_message(). + **/ void e_shell_taskbar_unset_message (EShellTaskbar *shell_taskbar) { diff --git a/shell/e-shell-view.c b/shell/e-shell-view.c index 9273376f2d..a10fb635cb 100644 --- a/shell/e-shell-view.c +++ b/shell/e-shell-view.c @@ -374,6 +374,11 @@ shell_view_class_init (EShellViewClass *class) class->toggled = shell_view_toggled; + /** + * EShellView:action: + * + * The #GtkRadioAction registered with #EShellSwitcher. + **/ g_object_class_install_property ( object_class, PROP_ACTION, @@ -385,6 +390,11 @@ shell_view_class_init (EShellViewClass *class) G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY)); + /** + * EShellView:page-num + * + * The #GtkNotebook page number of the shell view. + **/ g_object_class_install_property ( object_class, PROP_PAGE_NUM, @@ -398,6 +408,12 @@ shell_view_class_init (EShellViewClass *class) G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY)); + /** + * EShellView:title + * + * The title of the shell view. Also serves as the #EShellWindow + * title when the shell view is active. + **/ g_object_class_install_property ( object_class, PROP_TITLE, @@ -408,6 +424,12 @@ shell_view_class_init (EShellViewClass *class) NULL, G_PARAM_READWRITE)); + /** + * EShellView:shell-content + * + * The content widget appears in an #EShellWindow's + * right pane. + **/ g_object_class_install_property ( object_class, PROP_SHELL_CONTENT, @@ -419,6 +441,12 @@ shell_view_class_init (EShellViewClass *class) E_TYPE_SHELL_CONTENT, G_PARAM_READABLE)); + /** + * EShellView:shell-sidebar + * + * The sidebar widget appears in an #EShellWindow's + * left pane. + **/ g_object_class_install_property ( object_class, PROP_SHELL_SIDEBAR, @@ -430,6 +458,11 @@ shell_view_class_init (EShellViewClass *class) E_TYPE_SHELL_SIDEBAR, G_PARAM_READABLE)); + /** + * EShellView:shell-taskbar + * + * The taskbar widget appears at the bottom of an #EShellWindow. + **/ g_object_class_install_property ( object_class, PROP_SHELL_TASKBAR, @@ -441,6 +474,11 @@ shell_view_class_init (EShellViewClass *class) E_TYPE_SHELL_TASKBAR, G_PARAM_READABLE)); + /** + * EShellView:shell-window + * + * The #EShellWindow to which the shell view belongs. + **/ g_object_class_install_property ( object_class, PROP_SHELL_WINDOW, @@ -452,6 +490,11 @@ shell_view_class_init (EShellViewClass *class) G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY)); + /** + * EShellView:view-id + * + * The current #GalView ID. + **/ g_object_class_install_property ( object_class, PROP_VIEW_ID, @@ -462,6 +505,20 @@ shell_view_class_init (EShellViewClass *class) NULL, G_PARAM_READWRITE)); + /** + * EShellView::toggled + * @shell_view: the #EShellView which emitted the signal + * + * Emitted when @shell_view is activated or deactivated. + * Use e_shell_view_is_active() to find out which event has + * occurred. The shell view being deactivated is always + * notified before the shell view being activated. + * + * By default, #EShellView adds the UI definition file + * given in the ui_definition + * field of #EShellViewClass on activation, and removes the + * UI definition on deactivation. + **/ signals[TOGGLED] = g_signal_new ( "toggled", G_OBJECT_CLASS_TYPE (object_class), @@ -471,6 +528,18 @@ shell_view_class_init (EShellViewClass *class) g_cclosure_marshal_VOID__VOID, G_TYPE_NONE, 0); + /** + * EShellView::update-actions + * @shell_view: the #EShellView which emitted the signal + * + * #EShellView subclasses should override the + * update_actions method in + * #EShellViewClass to update sensitivities, labels, or any + * other aspect of the #GtkActions they have registered. + * + * Plugins can also connect to this signal to be notified + * when to update their own #GtkActions. + **/ signals[UPDATE_ACTIONS] = g_signal_new ( "update-actions", G_OBJECT_CLASS_TYPE (object_class), @@ -523,6 +592,16 @@ e_shell_view_get_type (void) return type; } +/** + * e_shell_view_get_name: + * @shell_view: an #EShellView + * + * Returns the view name for @shell_view, which is also the name of + * the corresponding #EShellModule (see the name + * field in #EShellModuleInfo). + * + * Returns: the view name for @shell_view + **/ const gchar * e_shell_view_get_name (EShellView *shell_view) { @@ -537,6 +616,20 @@ e_shell_view_get_name (EShellView *shell_view) return g_object_get_data (G_OBJECT (action), "view-name"); } +/** + * e_shell_view_get_action: + * @shell_view: an #EShellView + * + * Returns the switcher action for @shell_view. + * + * An #EShellWindow creates a #GtkRadioAction for each #EShellView class + * it instantiates. This action gets passed to the #EShellSwitcher, which + * displays a button that proxies the action. The icon at the top of the + * sidebar also proxies the action. When @shell_view is active, the + * action's icon becomes the #EShellWindow icon. + * + * Returns: the switcher action for @shell_view + **/ GtkAction * e_shell_view_get_action (EShellView *shell_view) { @@ -545,6 +638,15 @@ e_shell_view_get_action (EShellView *shell_view) return shell_view->priv->action; } +/** + * e_shell_view_get_title: + * @shell_view: an #EShellView + * + * Returns the title for @shell_view. When @shell_view is active, the + * shell view's title becomes the #EShellWindow title. + * + * Returns: the title for @shell_view + **/ const gchar * e_shell_view_get_title (EShellView *shell_view) { @@ -553,6 +655,14 @@ e_shell_view_get_title (EShellView *shell_view) return shell_view->priv->title; } +/** + * e_shell_view_set_title: + * @shell_view: an #EShellView + * @title: a title for @shell_view + * + * Sets the title for @shell_view. When @shell_view is active, the + * shell view's title becomes the #EShellWindow title. + **/ void e_shell_view_set_title (EShellView *shell_view, const gchar *title) @@ -571,6 +681,19 @@ e_shell_view_set_title (EShellView *shell_view, g_object_notify (G_OBJECT (shell_view), "title"); } +/** + * e_shell_view_get_view_id: + * @shell_view: an #EShellView + * + * Returns the ID of the currently selected #GalView. + * + * #EShellView subclasses are responsible for keeping this property in + * sync with their #GalViewInstance. #EShellView itself just provides + * a place to store the view ID, and emits a #GObject::notify signal + * when the property changes. + * + * Returns: the ID of the current #GalView + **/ const gchar * e_shell_view_get_view_id (EShellView *shell_view) { @@ -579,6 +702,18 @@ e_shell_view_get_view_id (EShellView *shell_view) return shell_view->priv->view_id; } +/** + * e_shell_view_set_view_id: + * @shell_view: an #EShellView + * @view_id: a #GalView ID + * + * Selects the #GalView whose ID is equal to @view_id. + * + * #EShellView subclasses are responsible for keeping this property in + * sync with their #GalViewInstance. #EShellView itself just provides + * a place to store the view ID, and emits a #GObject::notify signal + * when the property changes. + **/ void e_shell_view_set_view_id (EShellView *shell_view, const gchar *view_id) @@ -594,6 +729,14 @@ e_shell_view_set_view_id (EShellView *shell_view, g_object_notify (G_OBJECT (shell_view), "view-id"); } +/** + * e_shell_view_get_shell_window: + * @shell_view: an #EShellView + * + * Returns the #EShellWindow to which @shell_view belongs. + * + * Returns: the #EShellWindow to which @shell_view belongs + **/ EShellWindow * e_shell_view_get_shell_window (EShellView *shell_view) { @@ -602,6 +745,14 @@ e_shell_view_get_shell_window (EShellView *shell_view) return E_SHELL_WINDOW (shell_view->priv->shell_window); } +/** + * e_shell_view_get_shell_module: + * @shell_view: an #EShellView + * + * Returns the corresponding #EShellModule for @shell_view. + * + * Returns: the corresponding #EShellModule for @shell_view + **/ EShellModule * e_shell_view_get_shell_module (EShellView *shell_view) { @@ -611,13 +762,26 @@ e_shell_view_get_shell_module (EShellView *shell_view) /* Calling this function during the shell view's instance * initialization function will return the wrong result, - * so catch that and emit a warning. */ + * so watch for that and emit a warning. */ shell_view_class = E_SHELL_VIEW_GET_CLASS (shell_view); g_return_val_if_fail (E_IS_SHELL_VIEW_CLASS (shell_view_class), NULL); return E_SHELL_MODULE (shell_view_class->type_module); } +/** + * e_shell_view_is_active: + * @shell_view: an #EShellView + * + * Returns %TRUE if @shell_view is active. That is, if it's currently + * visible in its #EShellWindow. An #EShellWindow can only display one + * shell view at a time. + * + * Technically this just checks the #GtkToggleAction:active property of + * the shell view's switcher action. See e_shell_view_get_action(). + * + * Returns: %TRUE if @shell_view is active + **/ gboolean e_shell_view_is_active (EShellView *shell_view) { @@ -630,19 +794,16 @@ e_shell_view_is_active (EShellView *shell_view) return gtk_toggle_action_get_active (GTK_TOGGLE_ACTION (action)); } -void -e_shell_view_add_activity (EShellView *shell_view, - EActivity *activity) -{ - EShellModule *shell_module; - - g_return_if_fail (E_IS_SHELL_VIEW (shell_view)); - g_return_if_fail (E_IS_ACTIVITY (activity)); - - shell_module = e_shell_view_get_shell_module (shell_view); - e_shell_module_add_activity (shell_module, activity); -} - +/** + * e_shell_view_get_page_num: + * @shell_view: an #EShellView + * + * This function is only interesting to #EShellWindow. It returns the + * #GtkNotebook page number for @shell_view. The rest of the application + * should have no need for this. + * + * Returns: the notebook page number for @shell_view + **/ gint e_shell_view_get_page_num (EShellView *shell_view) { @@ -651,6 +812,16 @@ e_shell_view_get_page_num (EShellView *shell_view) return shell_view->priv->page_num; } +/** + * e_shell_view_get_size_group: + * @shell_view: an #EShellView + * + * Returns a #GtkSizeGroup that #EShellContent and #EShellSidebar use + * to keep the search bar and sidebar banner vertically aligned. The + * rest of the application should have no need for this. + * + * Returns: a #GtkSizeGroup for internal use + **/ GtkSizeGroup * e_shell_view_get_size_group (EShellView *shell_view) { @@ -659,6 +830,19 @@ e_shell_view_get_size_group (EShellView *shell_view) return shell_view->priv->size_group; } +/** + * e_shell_view_get_shell_content: + * @shell_view: an #EShellView + * + * Returns the #EShellContent instance for @shell_view. + * + * By default, #EShellView creates a plain #EShellContent during + * initialization. But #EShellView subclasses can override the + * new_shell_content factory method + * in #EShellViewClass to create a custom #EShellContent. + * + * Returns: the #EShellContent instance for @shell_view + **/ EShellContent * e_shell_view_get_shell_content (EShellView *shell_view) { @@ -667,6 +851,19 @@ e_shell_view_get_shell_content (EShellView *shell_view) return E_SHELL_CONTENT (shell_view->priv->shell_content); } +/** + * e_shell_view_get_shell_sidebar: + * @shell_view: an #EShellView + * + * Returns the #EShellSidebar instance for @shell_view. + * + * By default, #EShellView creates a plain #EShellSidebar during + * initialization. But #EShellView subclasses can override the + * new_shell_sidebar factory method + * in #EShellViewClass to create a custom #EShellSidebar. + * + * Returns: the #EShellSidebar instance for @shell_view + **/ EShellSidebar * e_shell_view_get_shell_sidebar (EShellView *shell_view) { @@ -675,6 +872,19 @@ e_shell_view_get_shell_sidebar (EShellView *shell_view) return E_SHELL_SIDEBAR (shell_view->priv->shell_sidebar); } +/** + * e_shell_view_get_shell_taskbar: + * @shell_view: an #EShellView + * + * Returns the #EShellTaskbar instance for @shell_view. + * + * By default, #EShellView creates a plain #EShellTaskbar during + * initialization. But #EShellView subclasses can override the + * new_shell_taskbar factory method + * in #EShellViewClass to create a custom #EShellTaskbar. + * + * Returns: the #EShellTaskbar instance for @shell_view + **/ EShellTaskbar * e_shell_view_get_shell_taskbar (EShellView *shell_view) { @@ -683,6 +893,20 @@ e_shell_view_get_shell_taskbar (EShellView *shell_view) return E_SHELL_TASKBAR (shell_view->priv->shell_taskbar); } +/** + * e_shell_view_update_actions: + * @shell_view: an #EShellView + * + * Emits the #EShellView::update-actions signal. + * + * #EShellView subclasses should implement the + * update_actions method in #EShellViewClass + * to update the various #GtkActions based on the current + * #EShellSidebar and #EShellContent selections. The + * #EShellView::update-actions signal is typically emitted just before + * showing a popup menu or just after the user selects an item in the + * shell view. + **/ void e_shell_view_update_actions (EShellView *shell_view) { diff --git a/shell/e-shell-view.h b/shell/e-shell-view.h index f9f027d0bb..34d001d0d4 100644 --- a/shell/e-shell-view.h +++ b/shell/e-shell-view.h @@ -35,7 +35,6 @@ #include #include -#include #include /* Standard GObject macros */ @@ -74,6 +73,47 @@ struct _EShellView { EShellViewPrivate *priv; }; +/** + * EShellViewClass: + * @parent_class: The parent class structure. + * @label: The initial value for the switcher action's + * #GtkAction:label property. See + * e_shell_view_get_action(). + * @icon_name: The initial value for the switcher action's + * #GtkAction:icon-name property. See + * e_shell_view_get_action(). + * @ui_definition: Base name of the UI definintion file to add + * when the shell view is activated. + * @search_options: Widget path in the UI definition to the search + * options popup menu. The menu gets shown when the + * user clicks the "find" icon in the search entry. + * @type_module: The corresponding #GTypeModule for this shell + * view. Subclasses are responsible for setting + * this. An easy way do so is to pass it to the + * shell view's #GClassInitFunc via the + * class_data field in + * #GTypeInfo. + * @view_collection: A unique #GalViewCollection instance is created + * for each subclass and shared across all instances + * of that subclass. That much is done automatically + * for subclasses, but subclasses are still responsible + * for adding the appropriate #GalView factories to the + * view collection. + * @new_shell_content: Factory method for the shell view's #EShellContent. + * See e_shell_view_get_shell_content(). + * @new_shell_sidebar: Factory method for the shell view's #EShellSidebar. + * See e_shell_view_get_shell_sidebar(). + * @new_shell_taskbar: Factory method for the shell view's #EShellTaskbar. + * See e_shell_view_get_shell_taskbar(). + * @toggled: Class method for the #EShellView::toggled signal. + * Subclasses should rarely need to override the + * default behavior. + * @update_actions: Class method for the #EShellView::update_actions + * signal. There is no default behavior; subclasses + * should override this. + * + * #EShellViewClass contains a number of important settings for subclasses. + **/ struct _EShellViewClass { GObjectClass parent_class; @@ -84,7 +124,7 @@ struct _EShellViewClass { /* Base name of the UI definition file. */ const gchar *ui_definition; - /* Widget path to the search entry popup menu. */ + /* Widget path to the search options popup menu. */ const gchar *search_options; /* Subclasses should set this via the "class_data" field in @@ -114,8 +154,6 @@ const gchar * e_shell_view_get_view_id (EShellView *shell_view); void e_shell_view_set_view_id (EShellView *shell_view, const gchar *view_id); gboolean e_shell_view_is_active (EShellView *shell_view); -void e_shell_view_add_activity (EShellView *shell_view, - EActivity *activity); gint e_shell_view_get_page_num (EShellView *shell_view); GtkSizeGroup * e_shell_view_get_size_group (EShellView *shell_view); EShellContent * e_shell_view_get_shell_content (EShellView *shell_view); diff --git a/shell/test/e-test-shell-view.c b/shell/test/e-test-shell-view.c index 7701849cc2..d243906af7 100644 --- a/shell/test/e-test-shell-view.c +++ b/shell/test/e-test-shell-view.c @@ -70,6 +70,7 @@ test_shell_view_constructed (GObject *object) ETestShellViewPrivate *priv; EShellContent *shell_content; EShellSidebar *shell_sidebar; + EShellModule *shell_module; EShellView *shell_view; EActivity *activity; GtkWidget *widget; @@ -80,6 +81,7 @@ test_shell_view_constructed (GObject *object) priv = E_TEST_SHELL_VIEW_GET_PRIVATE (object); shell_view = E_SHELL_VIEW (object); + shell_module = e_shell_view_get_shell_module (shell_view); shell_content = e_shell_view_get_shell_content (shell_view); shell_sidebar = e_shell_view_get_shell_sidebar (shell_view); @@ -93,7 +95,7 @@ test_shell_view_constructed (GObject *object) activity = e_activity_new ("Test Activity"); e_activity_set_cancellable (activity, TRUE); - e_shell_view_add_activity (shell_view, activity); + e_shell_module_add_activity (shell_module, activity); priv->activity = activity; } -- cgit v1.2.3