aboutsummaryrefslogtreecommitdiffstats
path: root/e-util/e-menu.h
diff options
context:
space:
mode:
Diffstat (limited to 'e-util/e-menu.h')
-rw-r--r--e-util/e-menu.h323
1 files changed, 323 insertions, 0 deletions
diff --git a/e-util/e-menu.h b/e-util/e-menu.h
new file mode 100644
index 0000000000..a6ff19c907
--- /dev/null
+++ b/e-util/e-menu.h
@@ -0,0 +1,323 @@
+/* -*- Mode: C; tab-width: 8; indent-tabs-mode: t; c-basic-offset: 8 -*-
+ *
+ * Authors: Michel Zucchi <notzed@ximian.com>
+ *
+ * Copyright 2003 Ximian, Inc. (www.ximian.com)
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 59 Temple Street #330, Boston, MA 02111-1307, USA.
+ *
+ */
+
+#ifndef __E_MENU_H__
+#define __E_MENU_H__
+
+#include <glib-object.h>
+#include "e-util/e-msgport.h"
+
+#ifdef __cplusplus
+extern "C" {
+#pragma }
+#endif /* __cplusplus */
+
+/* This is an abstract popup menu management/merging class.
+
+ To implement your own popup menu system, just create your own
+ target types and implement the target free method. */
+
+typedef struct _EMenu EMenu;
+typedef struct _EMenuClass EMenuClass;
+
+typedef struct _EMenuItem EMenuItem;
+typedef struct _EMenuUIFile EMenuUIFile;
+typedef struct _EMenuPixmap EMenuPixmap;
+
+typedef struct _EMenuFactory EMenuFactory; /* anonymous type */
+typedef struct _EMenuTarget EMenuTarget;
+
+typedef void (*EMenuFactoryFunc)(EMenu *emp, void *data);
+typedef void (*EMenuActivateFunc)(EMenu *, EMenuItem *, void *data);
+typedef void (*EMenuToggleActivateFunc)(EMenu *, EMenuItem *, int state, void *data);
+typedef void (*EMenuItemsFunc)(EMenu *, GSList *items, GSList *uifiles, GSList *pixmaps, void *data);
+
+/**
+ * enum _e_menu_t - Menu item type.
+ *
+ * @E_MENU_ITEM: Normal menu item.
+ * @E_MENU_TOGGLE: Toggle menu item.
+ * @E_MENU_RADIO: unimplemented.
+ * @E_MENU_TYPE_MASK: Mask used to separate item type from option bits.
+ * @E_MENU_ACTIVE: Whether a toggle item is active.
+ *
+ * The type of menu items which are supported by the menu system.
+ **/
+enum _e_menu_t {
+ E_MENU_ITEM = 0,
+ E_MENU_TOGGLE,
+ E_MENU_RADIO,
+ E_MENU_TYPE_MASK = 0xffff,
+ E_MENU_ACTIVE = 0x10000,
+};
+
+/**
+ * struct _EMenuItem - A BonoboUI menu item.
+ *
+ * @type: Menu item type. %E_MENU_ITEM or %E_MENU_TOGGLE.
+ * @path: BonoboUI Path to the menu item.
+ * @verb: BonoboUI verb for the menu item.
+ * @activate: Callback when the menu item is selected. This will be a
+ * EMenuToggleActivateFunc for toggle items or EMenuActivateFunc for
+ * normal items.
+ * @user_data: User data for item.
+ * @visible: Visibility mask, unimplemented.
+ * @enable: Sensitivity mask, combined with the target mask.
+ *
+ * An EMenuItem defines a single menu item. This menu item is used to
+ * hook onto callbacks from the bonobo menus, but not to build or
+ * merge the menu itself.
+ **/
+struct _EMenuItem {
+ enum _e_menu_t type;
+ char *path; /* full path? can we just create it from verb? */
+ char *verb; /* command verb */
+ GCallback activate; /* depends on type, the bonobo activate callback */
+ void *user_data; /* up to caller to use */
+ guint32 visible; /* is visible mask */
+ guint32 enable; /* is enable mask */
+};
+
+/**
+ * struct _EMenuPixmap - A menu icon holder.
+ *
+ * @command: The path to the command or verb to which this pixmap belongs.
+ * @name: The name of the icon. Either an icon-theme name or the full
+ * pathname of the icon.
+ * @size: The e-icon-factory icon size.
+ * @pixmap: The pixmap converted to XML format. If not set, then EMenu will
+ * create it as required. This must be freed if set in the free function.
+ *
+ * Used to track all pixmap items used in menus. These need to be
+ * supplied separately from the menu definition.
+ **/
+struct _EMenuPixmap {
+ char *command;
+ char *name;
+ int size;
+ char *pixmap;
+};
+
+/**
+ * struct _EMenuUIFile - A meu UI file holder.
+ *
+ * @appdir: TODO; should this be handled internally.
+ * @appname: TODO; should this be handled internally.
+ * @filename: The filename of the BonoboUI XML menu definition.
+ *
+ * These values are passed directly to bonobo_ui_util_set_ui() when
+ * the menu is activated.
+ **/
+struct _EMenuUIFile {
+ char *appdir;
+ char *appname;
+ char *filename;
+};
+
+/**
+ * struct _EMenuTarget - A BonoboUI menu target definition.
+ *
+ * @menu: The parent menu object, used for virtual methods on the target.
+ * @widget: The parent widget where available. In some cases the type
+ * of this object is part of the published api for the target, in
+ * others it is merely a GtkWidget from which you can find the
+ * toplevel widget.
+ * @type: Target type. This will be defined by the implementation.
+ * @mask: Target mask. This is used to sensitise show items based on
+ * their definition in EMenuItem.
+ *
+ * An EMenuTarget defines the context for a specific view instance.
+ * It is used to enable and show menu items, and to provide contextual
+ * data to menu invocations.
+ **/
+struct _EMenuTarget {
+ struct _EMenu *menu; /* used for virtual methods */
+
+ struct _GtkWidget *widget; /* used if you need a parent toplevel, if available */
+ guint32 type; /* for implementors */
+
+ guint32 mask; /* enable/visible mask */
+
+ /* implementation fields follow */
+};
+
+/**
+ * struct _EMenu - A BonoboUI menu manager object.
+ *
+ * @object: Superclass.
+ * @priv: Private data.
+ * @menuid: The id of this menu instance.
+ * @uic: The current BonoboUIComponent which stores the actual menu
+ * items this object manages.
+ * @target: The current target for the view.
+ *
+ * The EMenu manager object manages the mappings between EMenuItems
+ * and the BonoboUI menus loaded from UI files.
+ **/
+struct _EMenu {
+ GObject object;
+ struct _EMenuPrivate *priv;
+
+ char *menuid;
+ struct _BonoboUIComponent *uic;
+ EMenuTarget *target;
+};
+
+/**
+ * struct _EMenuClass -
+ *
+ * @object_class: Superclass type.
+ * @factories: A list of factories for this particular class of main menu.
+ * @target_free: Virtual method to free the menu target. The base
+ * class free method frees the allocation and unrefs the EMenu parent
+ * pointer.
+ *
+ * The EMenu class definition. This should be sub-classed for each
+ * component that wants to provide hookable main menus. The subclass
+ * only needs to know how to allocate and free the various target
+ * types it supports.
+ **/
+struct _EMenuClass {
+ GObjectClass object_class;
+
+ EDList factories;
+
+ void (*target_free)(EMenu *ep, EMenuTarget *t);
+};
+
+GType e_menu_get_type(void);
+
+/* Static class methods */
+EMenuFactory *e_menu_class_add_factory(EMenuClass *klass, const char *menuid, EMenuFactoryFunc func, void *data);
+void e_menu_class_remove_factory(EMenuClass *klass, EMenuFactory *f);
+
+EMenu *e_menu_construct(EMenu *menu, const char *menuid);
+
+void e_menu_add_ui(EMenu *, const char *appdir, const char *appname, const char *filename);
+void e_menu_add_pixmap(EMenu *, const char *cmd, const char *name, int size);
+
+void *e_menu_add_items(EMenu *emp, GSList *items, GSList *uifiles, GSList *pixmaps, EMenuItemsFunc freefunc, void *data);
+void e_menu_remove_items(EMenu *emp, void *handle);
+
+void e_menu_activate(EMenu *, struct _BonoboUIComponent *uic, int act);
+void e_menu_update_target(EMenu *, void *);
+
+void *e_menu_target_new(EMenu *, int type, size_t size);
+void e_menu_target_free(EMenu *, void *);
+
+/* ********************************************************************** */
+
+/* menu plugin, they are closely integrated */
+
+/* To implement a basic menu plugin, you just need to subclass
+ this and initialise the class target type tables */
+
+#include "e-util/e-plugin.h"
+
+typedef struct _EMenuHookPixmap EMenuHookPixmap;
+typedef struct _EMenuHookMenu EMenuHookMenu;
+typedef struct _EMenuHook EMenuHook;
+typedef struct _EMenuHookClass EMenuHookClass;
+
+typedef struct _EPluginHookTargetMap EMenuHookTargetMap;
+typedef struct _EPluginHookTargetKey EMenuHookTargetMask;
+
+typedef void (*EMenuHookFunc)(struct _EPlugin *plugin, EMenuTarget *target);
+
+/**
+ * struct _EMenuHookMenu - A group of items targetting a specific menu.
+ *
+ * @hook: Parent pointer.
+ * @id: The identifier of the menu or view to which these items belong.
+ * @target_type: The target number of the type of target these menu
+ * items expect. This will be defined by menu itself.
+ * @items: A list of EMenuItems.
+ * @uis: A list of filenames of the BonoboUI files that need to be
+ * loaded for an active view.
+ * @pixmaps: A list of EMenuHookPixmap structures for the menus.
+ *
+ * This structure is used to keep track of all of the items that a
+ * plugin wishes to add to specific menu. This is used internally by
+ * a factory method defined by the EMenuHook to add the right menu
+ * items to a given view.
+ **/
+struct _EMenuHookMenu {
+ struct _EMenuHook *hook; /* parent pointer */
+ char *id; /* target menu id for these menu items */
+ int target_type; /* target type, not used */
+ GSList *items; /* items to add to menu */
+ GSList *uis; /* ui files */
+ GSList *pixmaps; /* pixmap descriptors */
+};
+
+/**
+ * struct _EMenuHook - A BonoboUI menu hook.
+ *
+ * @hook: Superclass.
+ * @menus: A list of EMenuHookMenus for all menus registered on this
+ * hook type.
+ *
+ * The EMenuHook class loads and manages the meta-data to required to
+ * map plugin definitions to physical menus.
+ **/
+struct _EMenuHook {
+ EPluginHook hook;
+
+ GSList *menus;
+};
+
+/**
+ * struct _EMenuHookClass - Menu hook type.
+ *
+ * @hook_class: Superclass type.
+ * @target_map: Table of EluginHookTargetMaps which enumerate the
+ * target types and enable bits of the implementing class.
+ * @menu_class: The EMenuClass of the corresponding popup manager for
+ * implementing the class.
+ *
+ * The EMenuHookClass is an empty concrete class. It must be
+ * subclassed and initialised appropriately to perform useful work.
+ *
+ * The EPluginHookClass.id must be set to the name and version of the
+ * hook handler the implementation defines. The @target_map must be
+ * initialised with the data required to enumerate the target types
+ * and enable flags supported by the implementing class.
+ **/
+struct _EMenuHookClass {
+ EPluginHookClass hook_class;
+
+ /* EMenuHookTargetMap by .type */
+ GHashTable *target_map;
+ /* the menu class these menus belong to */
+ EMenuClass *menu_class;
+};
+
+GType e_menu_hook_get_type(void);
+
+/* for implementors */
+void e_menu_hook_class_add_target_map(EMenuHookClass *klass, const EMenuHookTargetMap *);
+
+#ifdef __cplusplus
+}
+#endif /* __cplusplus */
+
+#endif /* __E_MENU_H__ */