aboutsummaryrefslogtreecommitdiffstats
path: root/shell/e-shell-view.c
diff options
context:
space:
mode:
authorMatthew Barnes <mbarnes@src.gnome.org>2008-10-02 02:58:37 +0800
committerMatthew Barnes <mbarnes@src.gnome.org>2008-10-02 02:58:37 +0800
commite52986f4225cbe8496043da74ca250521d244705 (patch)
treeb77ea07323e7ae339410012e672e643c1502eb91 /shell/e-shell-view.c
parentc6795be3a8b7b17ced9e99e17db9ac6cbed6e018 (diff)
downloadgsoc2013-evolution-e52986f4225cbe8496043da74ca250521d244705.tar.gz
gsoc2013-evolution-e52986f4225cbe8496043da74ca250521d244705.tar.zst
gsoc2013-evolution-e52986f4225cbe8496043da74ca250521d244705.zip
Add more EShell API documentation.
svn path=/branches/kill-bonobo/; revision=36533
Diffstat (limited to 'shell/e-shell-view.c')
-rw-r--r--shell/e-shell-view.c252
1 files changed, 238 insertions, 14 deletions
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 <structfield>ui_definition</structfield>
+ * 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
+ * <structfield>update_actions</structfield> method in
+ * #EShellViewClass to update sensitivities, labels, or any
+ * other aspect of the #GtkAction<!-- -->s they have registered.
+ *
+ * Plugins can also connect to this signal to be notified
+ * when to update their own #GtkAction<!-- -->s.
+ **/
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 <structfield>name</structfield>
+ * 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
+ * <structfield>new_shell_content</structfield> 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
+ * <structfield>new_shell_sidebar</structfield> 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
+ * <structfield>new_shell_taskbar</structfield> 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
+ * <structfield>update_actions</structfield> method in #EShellViewClass
+ * to update the various #GtkAction<!-- -->s 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)
{