/* -*- 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_POPUP_H__
#define __E_POPUP_H__
#include <glib-object.h>
#include "libedataserver/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 _EPopup EPopup;
typedef struct _EPopupClass EPopupClass;
typedef struct _EPopupItem EPopupItem;
typedef struct _EPopupFactory EPopupFactory; /* anonymous type */
typedef struct _EPopupTarget EPopupTarget;
typedef void (*EPopupActivateFunc)(EPopup *ep, EPopupItem *item, void *data);
typedef void (*EPopupFactoryFunc)(EPopup *emp, void *data);
typedef void (*EPopupItemsFunc)(EPopup *ep, GSList *items, void *data);
/**
* enum _e_popup_t - Popup item type enumeration.
* @E_POPUP_ITEM: A simple menu item.
* @E_POPUP_TOGGLE: A toggle menu item.
* @E_POPUP_RADIO: A radio menu item. Note that the radio group is
* global for the entire (sub) menu. i.e. submenu's must be used to
* separate radio button menu items.
* @E_POPUP_IMAGE: A &GtkImage menu item. In this case the @image
* field of &struct _EPopupItem points to the &GtkImage directly.
* @E_POPUP_SUBMENU: A sub-menu header. It is up to the application
* to define the @path properly so that the submenu comes before the
* submenu items.
* @E_POPUP_BAR: A menu separator bar.
* @E_POPUP_TYPE_MASK: Mask used to separate item type from option bits.
* @E_POPUP_ACTIVE: An option bit to signify that the radio button or
* toggle button is active.
*/
enum _e_popup_t {
E_POPUP_ITEM = 0,
E_POPUP_TOGGLE,
E_POPUP_RADIO,
E_POPUP_IMAGE,
E_POPUP_SUBMENU,
E_POPUP_BAR,
E_POPUP_TYPE_MASK = 0xffff,
E_POPUP_ACTIVE = 0x10000,
};
/* FIXME: activate passes back no context data apart from that provided.
FIXME: It should pass the target at the least. The menu widget is
useless */
/**
* struct _EPopupItem - A popup menu item definition.
* @type: The type of the popup. See the &enum _epopup_t definition
* for possible values.
* @path: An absolute path, which when sorted using a simple ASCII
* sort, will put the menu item in the right place in the menu
* heirarchy. '/' is used to separate menus from submenu items.
* @label: The text of the menyu item.
* @activate: A function conforming to &EPopupActivateFunc which will
* be called when the menu item is activated.
* @user_data: Extra per-item user-data available to the
* application. This is not passed to the @data field of @activate.
* @image: For most types, the name of the icon in the icon theme to
* display next to the menu item, if required. For the %E_POPUP_IMAGE
* type, it is a pointer to the &GtkWidget instead.
* @visible: Visibility mask. Used together with the &EPopupTarget mask
* to determine if the item should be part of the menu or not.
* @enable: Sensitivity mask. Similar to the visibility mask, but
* currently unimplemented.
* @popup: Used by e-popup to reference the parent object from
* callbacks.
*
* The EPopupItem defines a single popup menu item, or submenu item,
* or menu separator based on the @type. Any number of these are
* merged at popup display type to form the popup menu.
*
* The application may extend this structure using simple C structure
* containers to add any additional fields it may require.
*/
struct _EPopupItem {
enum _e_popup_t type;
char *path; /* absolute path! must sort ascii-lexographically into the right spot */
char *label;
EPopupActivateFunc activate;
void *user_data; /* user data, not passed directly to @activate */
void *image; /* char* for item type, GtkWidget * for image type */
guint32 visible; /* visibility mask */
guint32 enable; /* sensitivity mask */
};
/**
* struct EPopupTarget - A popup menu target definition.
*
* @popup: The parent popup 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.
* @type: The target type. This will be defined by the
* implementation.
* @mask: Target mask. This is used to sensitise and show items
* based on their definition in EPopupItem.
*
* An EPopupTarget defines the context for a specific popup menu
* instance. The root target object is abstract, and it is up to
* sub-classes of &EPopup to define the additional fields required to
* make it usable.
*/
struct _EPopupTarget {
struct _EPopup *popup; /* used for virtual methods */
struct _GtkWidget *widget; /* used if you need a parent toplevel, if available */
guint32 type; /* targe type, for implementors */
guint32 mask; /* depends on type, visibility mask */
/* implementation fields follow */
};
/**
* struct _EPopup - A Popup menu manager.
*
* @object: Superclass, GObject.
* @priv: Private data.
* @menuid: The id of this menu instance.
* @target: The current target during the display of the popup menu.
*
* The EPopup manager object. Each popup menu is built using this
* one-off object which is created each time the popup is invoked.
*/
struct _EPopup {
GObject object;
struct _EPopupPrivate *priv;
char *menuid;
EPopupTarget *target;
};
/**
* struct _EPopupClass -
*
* @object_class: Superclass type.
* @factories: A list of factories for this particular class of popup
* menu.
* @target_free: Virtual method to free the popup target. The base
* class frees the allocation and unrefs the popup pointer
* structure.
*
* The EPopup class definition. This should be sub-classed for each
* component that wants to provide hookable popup menus. The
* sub-class only needs to know how to allocate and free the various target
* types it supports.
*/
struct _EPopupClass {
GObjectClass object_class;
EDList factories;
void (*target_free)(EPopup *ep, EPopupTarget *t);
};
GType e_popup_get_type(void);
EPopup *e_popup_new(const char *menuid);
/* Static class methods */
EPopupFactory *e_popup_class_add_factory(EPopupClass *klass, const char *menuid, EPopupFactoryFunc func, void *data);
void e_popup_class_remove_factory(EPopupClass *klass, EPopupFactory *f);
EPopup *e_popup_construct(EPopup *, const char *menuid);
void e_popup_add_items(EPopup *, GSList *items, EPopupItemsFunc freefunc, void *data);
void e_popup_add_static_items(EPopup *emp, EPopupTarget *target);
/* do not call e_popup_create_menu, it can leak structures if not used right */
struct _GtkMenu *e_popup_create_menu(EPopup *, EPopupTarget *, guint32 mask);
struct _GtkMenu *e_popup_create_menu_once(EPopup *emp, EPopupTarget *, guint32 mask);
void *e_popup_target_new(EPopup *, int type, size_t size);
void e_popup_target_free(EPopup *, void *);
/* ********************************************************************** */
/* popup plugin target, they are closely integrated */
/* To implement a basic popup menu plugin, you just need to subclass
this and initialise the class target type tables */
#include "e-util/e-plugin.h"
typedef struct _EPopupHookMenu EPopupHookMenu;
typedef struct _EPopupHook EPopupHook;
typedef struct _EPopupHookClass EPopupHookClass;
typedef struct _EPluginHookTargetMap EPopupHookTargetMap;
typedef struct _EPluginHookTargetKey EPopupHookTargetMask;
typedef void (*EPopupHookFunc)(struct _EPlugin *plugin, EPopupTarget *target);
/**
* struct _EPopupHookMenu -
*
* @hook: Parent pointer.
* @id: The identifier of the menu to which these items belong.
* @target_type: The target number of the type of target these menu
* items expect. It will generally also be defined by the menu id.
* @items: A list of EPopupItems.
*
* The structure used to keep track of all of the items that a plugin
* wishes to add to a given menu. This is used internally by a factory
* method set on EPlugin to add the right menu items to a given menu.
*/
struct _EPopupHookMenu {
struct _EPopupHook *hook; /* parent pointer */
char *id; /* target menu id for these menu items */
int target_type; /* target type of this menu */
GSList *items; /* items to add to menu */
};
/**
* struct _EPopupHook - A popup menu hook.
*
* @hook: Superclass.
* @menus: A list of EPopupHookMenus, for all menus registered on
* this hook type.
*
* The EPopupHook class loads and manages the meta-data required to
* map plugin definitions to physical menus.
*/
struct _EPopupHook {
EPluginHook hook;
GSList *menus;
};
/**
* struct _EPopupHookClass -
*
* @hook_class: Superclass.
* @target_map: Table of EPluginHookTargetMaps which enumerate the
* target types and enable bits of the implementing class.
* @popup_class: The EPopupClass of the corresponding popup manager
* for the implementing class.
*
* The EPopupHookClass is a concrete class, however it is empty on its
* own. It needs to be sub-classed and initialised appropriately.
*
* The EPluginHookClass.id must be set to the name and version of the
* hook handler itself. The @target_map must be initialised with the
* data required to enumerate the target types and enable flags
* supported by the implementing class.
*/
struct _EPopupHookClass {
EPluginHookClass hook_class;
/* EPopupHookTargetMap by .type */
GHashTable *target_map;
/* the popup class these popups belong to */
EPopupClass *popup_class;
};
GType e_popup_hook_get_type(void);
/* for implementors */
void e_popup_hook_class_add_target_map(EPopupHookClass *klass, const EPopupHookTargetMap *);
#ifdef __cplusplus
}
#endif /* __cplusplus */
#endif /* __E_POPUP_H__ */
