Defining a Popup Context Menu

-#include <mate-panel-applet.h> - -static MateComponentObject * -blah_applet_new () -{ - MatePanelApplet *applet; - - /* - * The old code setting up the applet widgetry - * goes here. So effectively delete calls to - * applet_widget_init and applet_widget_new - * and the replace applet_widget_add with a call - * to mate_panel_applet_new. - */ - - applet = mate_panel_applet_new (label); - - return MATECOMPONENT_OBJECT (mate_panel_applet_get_control (applet)); -} - -static MateComponentObject * -blah_applet_factory (MateComponentGenericFactory *this, - const gchar *iid, - gpointer data) -{ - MateComponentObject *applet = NULL; - - if (!strcmp (iid, "OAFIID:BlahApplet")) - applet = blah_applet_new (); - - return applet; -} - - -MATE_PANEL_APPLET_MATECOMPONENT_FACTORY ("OAFIID:BlahApplet_Factory", - "Blah", - "0", - blah_applet_factory, - NULL) -

-<oaf_info> - -<oaf_server iid="OAFIID:BlahApplet" - type="exe" - location="blah-de-blah-2"> - - <oaf_attribute name="repo_ids" type="stringv"> - <item value="IDL:MateComponent/GenericFactory:1.0""/> - <item value="IDL:MateComponent/Unknown:1.0"/> - </oaf_attribute> - <oaf_attribute name="name" type="string" value="Blah Factory"/> - <oaf_attribute name="description" type="string" value="Blah De Blah"/> - -</oaf_server> - -<oaf_server iid="OAFIID:BlahApplet" - type="factory" - location="OAFIID:BlahApplet_Factory"> - - <oaf_attribute name="repo_ids" type="stringv"> - <item value="IDL:MATE/MatePanelAppletShell:1.0"/> - <item value="IDL:MateComponent/Control:1.0"/> - <item value="IDL:MateComponent/Unknown:1.0"/> - </oaf_attribute> - <oaf_attribute name="name" type="string" value="Blah Applet"/> - <oaf_attribute name="description" type="string" value="Blah De Blah"/> - <oaf_attribute name="panel:icon" type="string" value="blah-de-blah.png"/> - -</oaf_server> - -</oaf_info> -

-static const char fish_menu_xml [] = - "<popup name=\"button3\">\n" - " <menuitem name=\"Properties Item\" verb=\"BlahProperties\" _label=\"Properties ...\"\n" - " pixtype=\"stock\" pixname=\"gtk-properties\"/>\n" - " <menuitem name=\"Help Item\" verb=\"BlahHelp\" _label=\"Help\"\n" - " pixtype=\"stock\" pixname=\"gtk-help\"/>\n" - " <menuitem name=\"About Item\" verb=\"BlahAbout\" _label=\"About ...\"\n" - " pixtype=\"stock\" pixname=\"mate-stock-about\"/>\n" - "</popup>\n"; -

-static const MateComponentUIVerb fish_menu_verbs [] = { - MATECOMPONENT_UI_VERB ("BlahProperties", display_properties_dialog), - MATECOMPONENT_UI_VERB ("BlahHelp", display_help_dialog), - MATECOMPONENT_UI_VERB ("BlahAbout", display_about_dialog), - - MATECOMPONENT_UI_VERB_END -}; -

- mate_panel_applet_setup_menu (MATE_PANEL_APPLET (blah->applet), - blah_menu_xml, - blah_menu_verbs, - blah); -

-#include <string.h> - -#include <mate-panel-applet.h> -#include <gtk/gtklabel.h> - -static gboolean -hello_applet_fill (MatePanelApplet *applet, - const gchar *iid, - gpointer data) -{ - GtkWidget *label; - - if (strcmp (iid, "OAFIID:My_HelloApplet") != 0) - return FALSE; - - label = gtk_label_new ("Hello World"); - gtk_container_add (GTK_CONTAINER (applet), label); - - gtk_widget_show_all (GTK_WIDGET (applet)); - - return TRUE; -} - - -MATE_PANEL_APPLET_MATECOMPONENT_FACTORY ("OAFIID:My_HelloApplet_Factory", - PANEL_TYPE_APPLET, - "TheHelloWorldApplet", - "0", - hello_applet_fill, - NULL); -

Abstract

-This manual documents the interfaces of the panel applet -library for MATE 2.x and a short guide to porting applets from -the MATE 1.x interfaces. -

Panel Applet Library Reference Manual

- - -

MatePanelApplet

MatePanelApplet — The MatePanelApplet object.

Synopsis

-#include <mate-panel-applet.h>
-
-struct              MatePanelApplet;
-enum                MatePanelAppletOrient;
-enum                MatePanelAppletBackgroundType;
-enum                MatePanelAppletFlags;
-gboolean            (*MatePanelAppletFactoryCallback)       (MatePanelApplet *applet,
-                                                         const gchar *iid,
-                                                         gpointer user_data);
-GtkWidget *         mate_panel_applet_new                    (void);
-MatePanelAppletOrient   mate_panel_applet_get_orient             (MatePanelApplet *applet);
-guint               mate_panel_applet_get_size               (MatePanelApplet *applet);
-MatePanelAppletBackgroundType  mate_panel_applet_get_background  (MatePanelApplet *applet,
-                                                         GdkColor *color,
-                                                         GdkPixmap **pixmap);
-gchar *             mate_panel_applet_get_preferences_key    (MatePanelApplet *applet);
-void                mate_panel_applet_add_preferences        (MatePanelApplet *applet,
-                                                         const gchar *schema_dir,
-                                                         GError **opt_error);
-MatePanelAppletFlags    mate_panel_applet_get_flags              (MatePanelApplet *applet);
-void                mate_panel_applet_set_flags              (MatePanelApplet *applet,
-                                                         MatePanelAppletFlags flags);
-void                mate_panel_applet_set_size_hints         (MatePanelApplet *applet,
-                                                         const int *size_hints,
-                                                         int n_elements,
-                                                         int base_size);
-gboolean            mate_panel_applet_get_locked_down        (MatePanelApplet *applet);
-void                mate_panel_applet_request_focus          (MatePanelApplet *applet,
-                                                         guint32 timestamp);
-void                mate_panel_applet_setup_menu             (MatePanelApplet *applet,
-                                                         const gchar *xml,
-                                                         GtkActionGroup *action_group);
-void                mate_panel_applet_setup_menu_from_file   (MatePanelApplet *applet,
-                                                         const gchar *filename,
-                                                         GtkActionGroup *action_group);
-int                 mate_panel_applet_factory_main           (const gchar *factory_id,
-                                                         gboolean out_process,
-                                                         GType applet_type,
-                                                         MatePanelAppletFactoryCallback callback,
-                                                         gpointer data);
-

Object Hierarchy

-  GObject
-   +----GInitiallyUnowned
-         +----GtkObject
-               +----GtkWidget
-                     +----GtkContainer
-                           +----GtkBin
-                                 +----GtkEventBox
-                                       +----MatePanelApplet
-

Implemented Interfaces

-MatePanelApplet implements - AtkImplementorIface and GtkBuildable.

Properties

-  "background"               gchar*                : Read / Write
-  "closure"                  gpointer              : Read / Write / Construct Only
-  "connection"               GDBusConnection*      : Read / Write / Construct Only
-  "flags"                    guint                 : Read / Write
-  "id"                       gchar*                : Read / Write / Construct Only
-  "locked"                   gboolean              : Read / Write
-  "locked-down"              gboolean              : Read / Write
-  "orient"                   guint                 : Read / Write
-  "prefs-key"                gchar*                : Read / Write
-  "size"                     guint                 : Read / Write
-  "size-hints"               gpointer              : Read / Write
-

Signals

-  "change-background"                              : Run Last
-  "change-orient"                                  : Run Last
-  "change-size"                                    : Run Last
-  "move-focus-out-of-applet"                       : Action
-

Description

-The MatePanelApplet object is an object which encapsulates an applet. It -is a GtkContainer which may contain a single widget. This widget, in -turn, should contain all widgets exposed by the applet. -

-A MatePanelApplet is associated with a MateComponentControl. The control makes -the cross process UI emmbedding required by applets possible. -

Details

struct MatePanelApplet

struct MatePanelApplet;

-The MatePanelApplet struct contains private data only. -

enum MatePanelAppletOrient

typedef enum {
-	MATE_PANEL_APPLET_ORIENT_UP,
-	MATE_PANEL_APPLET_ORIENT_DOWN,
-	MATE_PANEL_APPLET_ORIENT_LEFT,
-	MATE_PANEL_APPLET_ORIENT_RIGHT
-} MatePanelAppletOrient;
-

-The MatePanelAppletOrient type specifies the orientation of the applet. The -values may seem backward (e.g. MATE_PANEL_APPLET_ORIENT_LEFT means the panel -is on the right hand side), but this is because the value is representative -of the applet's orientation, not the panel's position. -

enum MatePanelAppletBackgroundType

typedef enum {
-	PANEL_NO_BACKGROUND,
-	PANEL_COLOR_BACKGROUND,
-	PANEL_PIXMAP_BACKGROUND
-} MatePanelAppletBackgroundType;
-

-The MatePanelAppletBackgroundType enumerated type specifies the type of -background of a panel. -

-- - - - - - - - - - - - - - -

`PANEL_NO_BACKGROUND`	The panel has no background, the default is used. -
`PANEL_COLOR_BACKGROUND`	The panel has a color, i.e rgb value, -background. -
`PANEL_PIXMAP_BACKGROUND`	The panel has either an image background -or is translucent. -

enum MatePanelAppletFlags

typedef enum {
-	MATE_PANEL_APPLET_FLAGS_NONE   = 0,
-	MATE_PANEL_APPLET_EXPAND_MAJOR = 1 << 0,
-	MATE_PANEL_APPLET_EXPAND_MINOR = 1 << 1,
-	MATE_PANEL_APPLET_HAS_HANDLE   = 1 << 2
-} MatePanelAppletFlags;
-

-The MatePanelAppletFlags associated with the applet are boolean flags which -the panel may read in order to figure out how to handle the applet. -

-- - - - - - - - - - - - - - - - - - -

`MATE_PANEL_APPLET_FLAGS_NONE`	No flags are to be associated with the applet. -
`MATE_PANEL_APPLET_EXPAND_MAJOR`	The applet should expand horizontally on an -horizontal panel and vertically on a vertical panel - e.g. the behaviour -of the Window List applet. -
`MATE_PANEL_APPLET_EXPAND_MINOR`	The applet should expand vertically on an -horizontal panel and horizontally on a vertical panel. Most applets should -set this flag in order to utilise the full panel width and allow the applet -to be Fitt's Law compliant. -
`MATE_PANEL_APPLET_HAS_HANDLE`	The panel should draw a grab handle around the -applet - e.g. the Window List and Notification Area applets both set this -flag. -

MatePanelAppletFactoryCallback ()

gboolean            (*MatePanelAppletFactoryCallback)       (MatePanelApplet *applet,
-                                                         const gchar *iid,
-                                                         gpointer user_data);

-This callback is invoked when the applet is loaded onto the panel. Typically -the callback will check that iid matches and fill the applet with the -widgets which make up the applet. -

-Prior to the callback being invoked the MatePanelApplet (or an instance of the -sub-class specified by the GType passed to the factory macros) is instantiated -and initialized. -

-- - - - - - - - - - - - - - - - - - -

`applet` :	The MatePanelApplet. -
`iid` :	The MateComponent IID of the applet requested. -
`user_data` :	The data passed to the factory macros. -
Returns :	-`TRUE` on success, `FALSE` on failure. -

mate_panel_applet_new ()

GtkWidget *         mate_panel_applet_new                    (void);

-Creates a new MatePanelApplet. This function is typically not -useful as the applet is created before the MatePanelAppletFactoryCallback -is invoked. -

-- - - - -

Returns :

The MatePanelApplet. -

mate_panel_applet_get_orient ()

MatePanelAppletOrient   mate_panel_applet_get_orient             (MatePanelApplet *applet);

-Get the current orientation of the applet. -

-- - - - - - - - - - -

`applet` :	The MatePanelApplet. -
Returns :	The orientation of the applet. -

mate_panel_applet_get_size ()

guint               mate_panel_applet_get_size               (MatePanelApplet *applet);

-Get the current size hint for the panel. The size hint is -not useful for most applets. -

-Note: The return value is not an integer value -specifying the pixel size of the panel. Do not -use this value to calculate the size of the applet. Use it -only as a hint by which to decide the applet's layout. -

-- - - - - - - - - - -

`applet` :	The MatePanelApplet. -
Returns :	The panel's size hint. -

mate_panel_applet_get_background ()

MatePanelAppletBackgroundType  mate_panel_applet_get_background  (MatePanelApplet *applet,
-                                                         GdkColor *color,
-                                                         GdkPixmap **pixmap);

-Returns the current background type. If the background -type is PANEL_NO_BACKGROUND both color and pixmap will -be unaffected. If the background type is PANEL_COLOR_BACKGROUND -then color will contain the current panel background colour. -If the background type is PANEL_PIXMAP_BACKGROUND, pixmap will -contain a pointer to a GdkPixmap which is a copy of the applet's -portion of the panel's background pixmap. -

-- - - - - - - - - - - - - - - - - - -

`applet` :	A MatePanelApplet. -
`color` :	A GdkColor to be filled in. -
`pixmap` :	Returned GdkPixmap. -
Returns :	The background type. -

mate_panel_applet_get_preferences_key ()

gchar *             mate_panel_applet_get_preferences_key    (MatePanelApplet *applet);

-Returns the MateConf path to the directory containing the applet's -per-instance preference keys. Using this you may construct the -full path for the applet's preference keys. See -Panel Applet MateConf Utilities(3) for -more information. -

-- - - - - - - - - - -

`applet` :	The MatePanelApplet. -
Returns :	A MateConf path. -

mate_panel_applet_add_preferences ()

void                mate_panel_applet_add_preferences        (MatePanelApplet *applet,
-                                                         const gchar *schema_dir,
-                                                         GError **opt_error);

-Associates each schema in schema_dir with a key in the applet's -preferences directory (i.e. the directory returned by -mate_panel_applet_get_preferences_key()). Each applet preference -should have an associated schema to ensure that the key has -a defined type, sane default and documentation. -

-If you pass NULL for opt_error, this function will print -a warning message from any GError which MateConf may return. -

-- - - - - - - - - - - - - - -

`applet` :	The MatePanelApplet. -
`schema_dir` :	The MateConf path where the applet's schemas are installed -e.g. /schemas/apps/my_applet -
`opt_error` :	Optional GError. -

mate_panel_applet_get_flags ()

MatePanelAppletFlags    mate_panel_applet_get_flags              (MatePanelApplet *applet);

-Retrieve the MatePanelAppletFlags associated with the applet. -

-- - - - - - - - - - -

`applet` :	The MatePanelApplet. -
Returns :	The MatePanelAppletFlags. -

mate_panel_applet_set_flags ()

void                mate_panel_applet_set_flags              (MatePanelApplet *applet,
-                                                         MatePanelAppletFlags flags);

-Set the MatePanelAppletFlags associated with the applet. See -MatePanelAppletFlags for more details on the possible uses of -these flags. -

-- - - - - - - - - - -

`applet` :	The MatePanelApplet. -
`flags` :	The MatePanelAppletFlags to associate. -

mate_panel_applet_set_size_hints ()

void                mate_panel_applet_set_size_hints         (MatePanelApplet *applet,
-                                                         const int *size_hints,
-                                                         int n_elements,
-                                                         int base_size);

-Set a list of desired size ranges for an applet with the -MATE_PANEL_APPLET_EXPAND_MAJOR flags set. size_hints is an -array of (max, min) pairs where min(i) > max(i + 1). -

-The panel will endeavour to allocate the applet a size -in one of the (base + max, base + min) ranges. -

-- - - - - - - - - - - - - - - - - - -

`applet` :	The MatePanelApplet. -
`size_hints` :	Array of size_hints. -
`n_elements` :	Number of elements in the array. -Not the number of pairs. -
`base_size` :	The base size of the applet. -

mate_panel_applet_get_locked_down ()

gboolean            mate_panel_applet_get_locked_down        (MatePanelApplet *applet);

-Check if the applet is locked down. A locked down applet should not allow any change to its configuration. -

-- - - - - - - - - - -

`applet` :	The MatePanelApplet. -
Returns :	-`TRUE` if the `applet` is locked down, `FALSE` otherwise. -

mate_panel_applet_request_focus ()

void                mate_panel_applet_request_focus          (MatePanelApplet *applet,
-                                                         guint32 timestamp);

-Set keyboard focus to applet. -

-- - - - - - - - - - -

`applet` :	The MatePanelApplet. -
`timestamp` :	timestamp of the event triggering the window focus -

mate_panel_applet_setup_menu ()

void                mate_panel_applet_setup_menu             (MatePanelApplet *applet,
-                                                         const gchar *xml,
-                                                         GtkActionGroup *action_group);

-Sets up a popup menu for applet described by the xml -string, xml. See Writing Applets section -for a description of the format of the xml. -

-- - - - - - - - - - - - - - -

`applet` :	A MatePanelApplet. -
`xml` :	The xml character string describing the popup menu. -
`action_group` :	-

mate_panel_applet_setup_menu_from_file ()

void                mate_panel_applet_setup_menu_from_file   (MatePanelApplet *applet,
-                                                         const gchar *filename,
-                                                         GtkActionGroup *action_group);

-Sets up a popup menu for applet described by the xml -file, file. See Writing Applets for a description of -the format of the xml. -

-- - - - - - - - - - - - - - -

`applet` :	A MatePanelApplet. -
`filename` :	-
`action_group` :	-

mate_panel_applet_factory_main ()

int                 mate_panel_applet_factory_main           (const gchar *factory_id,
-                                                         gboolean out_process,
-                                                         GType applet_type,
-                                                         MatePanelAppletFactoryCallback callback,
-                                                         gpointer data);

-A generic 'main' routine for applets. This should not normally be -used directly because it is invoked by MATE_PANEL_APPLET_MATECOMPONENT_FACTORY. -

-- - - - - - - - - - - - - - - - - - - - - - - - - - -

`factory_id` :	-
`out_process` :	-
`applet_type` :	The GType to instantiate. -
`callback` :	The factory callback. -
`data` :	The factory user data pointer. -
Returns :	0 on success, 1 on failure. -

Property Details

The `"background"` property

  "background"               gchar*                : Read / Write

Panel Applet Background.

Default value: NULL

The `"closure"` property

  "closure"                  gpointer              : Read / Write / Construct Only

The Applet closure.

The `"connection"` property

  "connection"               GDBusConnection*      : Read / Write / Construct Only

The DBus Connection.

The `"flags"` property

  "flags"                    guint                 : Read / Write

Panel Applet flags.

Default value: 0

The `"id"` property

  "id"                       gchar*                : Read / Write / Construct Only

The Applet identifier.

Default value: NULL

The `"locked"` property

  "locked"                   gboolean              : Read / Write

Whether Panel Applet is locked.

Default value: FALSE

The `"locked-down"` property

  "locked-down"              gboolean              : Read / Write

Whether Panel Applet is locked down.

Default value: FALSE

The `"orient"` property

  "orient"                   guint                 : Read / Write

Panel Applet Orientation.

Default value: 0

The `"prefs-key"` property

  "prefs-key"                gchar*                : Read / Write

MateConf Preferences Key.

Default value: NULL

The `"size"` property

  "size"                     guint                 : Read / Write

Panel Applet Size.

Default value: 0

The `"size-hints"` property

  "size-hints"               gpointer              : Read / Write

Panel Applet Size Hints.

Signal Details

The `"change-background"` signal

void                user_function                      (MatePanelApplet              *matepanelapplet,
-                                                        MatePanelAppletBackgroundType arg1,
-                                                        GdkColor                 *arg2,
-                                                        GdkPixmap                *arg3,
-                                                        gpointer                  user_data)        : Run Last

-Emitted when the background of the panel changes. Use type to -determine which, if any, of color and pimxap is valid. -

-- - - - - - - - - - - - - - - - - - - - - - -

`matepanelapplet` :	The object which received the signal. -
`arg1` :	-
`arg2` :	-
`arg3` :	-
`user_data` :	user data set when the signal handler was connected.

The `"change-orient"` signal

void                user_function                      (MatePanelApplet *matepanelapplet,
-                                                        guint        arg1,
-                                                        gpointer     user_data)        : Run Last

-Emitted when the orientation of the panel changes. -

-- - - - - - - - - - - - - - -

`matepanelapplet` :	The object which received the signal. -
`orient` :	The new MatePanelAppletOrient of the applet. -
`user_data` :	user data set when the signal handler was connected.

The `"change-size"` signal

void                user_function                      (MatePanelApplet *matepanelapplet,
-                                                        gint         arg1,
-                                                        gpointer     user_data)        : Run Last

-Emitted when the size of the panel changes. -

-Note: this is different for size negotiation which is handled by -size_request() and size_allocate() as usual. This signal should -be used to determine what font size or widget layout to use -depending on the size of the panel. See mate_panel_applet_get_size(). -

-- - - - - - - - - - - - - - -

`matepanelapplet` :	The object which received the signal. -
`size` :	The size hint of the panel. -
`user_data` :	user data set when the signal handler was connected.

The `"move-focus-out-of-applet"` signal

void                user_function                      (MatePanelApplet     *matepanelapplet,
-                                                        GtkDirectionType arg1,
-                                                        gpointer         user_data)        : Action

-Emitted when the applet has lost focus. This signal is used internally and is not meant to be used by applets themselves. -

-- - - - - - - - - - - - - - -

`matepanelapplet` :	The object which received the signal. -
`direction` :	The direction of focus movement. -
`user_data` :	user data set when the signal handler was connected.

-<oaf_info> -<oaf_server iid="OAFIID:My_HelloApplet_Factory" type="exe" - location="test-matecomponent-applet"> - - <oaf_attribute name="repo_ids" type="stringv"> - <item value="IDL:MateComponent/GenericFactory:1.0"/> - <item value="IDL:MateComponent/Unknown:1.0"/> - </oaf_attribute> - <oaf_attribute name="name" type="string" value="Hello World Applet Factory"/> - <oaf_attribute name="description" type="string" value="My first applet factory"/> -</oaf_server> - -<oaf_server iid="OAFIID:My_HelloApplet" type="factory" - location="OAFIID:My_HelloApplet_Factory"> - - <oaf_attribute name="repo_ids" type="stringv"> - <item value="IDL:MATE/Vertigo/MatePanelAppletShell:1.0"/> - <item value="IDL:MateComponent/Control:1.0"/> - <item value="IDL:MateComponent/Unknown:1.0"/> - </oaf_attribute> - <oaf_attribute name="name" type="string" value="Hello World Applet"/> - <oaf_attribute name="description" type="string" value="My first applet for the MATE2 panel"/> - <oaf_attribute name="panel:icon" type="string" value="mate-applets.png"/> -</oaf_server> -</oaf_info> -