MetaPlugin

MetaPlugin — Entry point for plugins

Synopsis

struct              MetaPlugin;
struct              MetaPluginClass;
struct              MetaPluginInfo;
gboolean            meta_plugin_running                 (MetaPlugin *plugin);
gboolean            meta_plugin_debug_mode              (MetaPlugin *plugin);
const MetaPluginInfo * meta_plugin_get_info             (MetaPlugin *plugin);
struct              MetaPluginVersion;
#define             META_PLUGIN_DECLARE                 (ObjectName,
                                                         object_name)
void                meta_plugin_switch_workspace_completed
                                                        (MetaPlugin *plugin);
void                meta_plugin_minimize_completed      (MetaPlugin *plugin,
                                                         MetaWindowActor *actor);
void                meta_plugin_maximize_completed      (MetaPlugin *plugin,
                                                         MetaWindowActor *actor);
void                meta_plugin_unmaximize_completed    (MetaPlugin *plugin,
                                                         MetaWindowActor *actor);
void                meta_plugin_map_completed           (MetaPlugin *plugin,
                                                         MetaWindowActor *actor);
void                meta_plugin_destroy_completed       (MetaPlugin *plugin,
                                                         MetaWindowActor *actor);
enum                MetaModalOptions;
gboolean            meta_plugin_begin_modal             (MetaPlugin *plugin,
                                                         MetaModalOptions options,
                                                         guint32 timestamp);
void                meta_plugin_end_modal               (MetaPlugin *plugin,
                                                         guint32 timestamp);
MetaScreen *        meta_plugin_get_screen              (MetaPlugin *plugin);
void                meta_plugin_manager_set_plugin_type (GType gtype);

Object Hierarchy

  GObject
   +----MetaPlugin

Properties

  "debug-mode"               gboolean              : Read
  "screen"                   MetaScreen*           : Read / Write

Description

Details

struct MetaPlugin

struct MetaPlugin;

struct MetaPluginClass

struct MetaPluginClass {
  /**
   * MetaPluginClass::start:
   *
   * Virtual function called when the compositor starts managing a screen
   */
  void (*start)            (MetaPlugin         *plugin);

  /**
   * MetaPluginClass::minimize:
   * @actor: a #MetaWindowActor
   *
   * Virtual function called when the window represented by @actor is minimized.
   */
  void (*minimize)         (MetaPlugin         *plugin,
                            MetaWindowActor    *actor);

  /**
   * MetaPluginClass::maximize:
   * @actor: a #MetaWindowActor
   * @x: target X coordinate
   * @y: target Y coordinate
   * @width: target width
   * @height: target height
   *
   * Virtual function called when the window represented by @actor is maximized.
   */
  void (*maximize)         (MetaPlugin         *plugin,
                            MetaWindowActor    *actor,
                            gint                x,
                            gint                y,
                            gint                width,
                            gint                height);

  /**
   * MetaPluginClass::unmaximize:
   * @actor: a #MetaWindowActor
   * @x: target X coordinate
   * @y: target Y coordinate
   * @width: target width
   * @height: target height
   *
   * Virtual function called when the window represented by @actor is unmaximized.
   */
  void (*unmaximize)       (MetaPlugin         *plugin,
                            MetaWindowActor    *actor,
                            gint                x,
                            gint                y,
                            gint                width,
                            gint                height);

  /**
   * MetaPluginClass::map:
   * @actor: a #MetaWindowActor
   *
   * Virtual function called when the window represented by @actor is mapped.
   */
  void (*map)              (MetaPlugin         *plugin,
                            MetaWindowActor    *actor);

  /**
   * MetaPluginClass::destroy:
   * @actor: a #MetaWindowActor
   *
   * Virtual function called when the window represented by @actor is destroyed.
   */
  void (*destroy)          (MetaPlugin         *plugin,
                            MetaWindowActor    *actor);

  /**
   * MetaPluginClass::switch_workspace:
   * @from: origin workspace
   * @to: destination workspace
   * @direction: a #MetaMotionDirection
   *
   * Virtual function called when the window represented by @actor is destroyed.
   */
  void (*switch_workspace) (MetaPlugin         *plugin,
                            gint                from,
                            gint                to,
                            MetaMotionDirection direction);


  /**
   * MetaPluginClass::kill_window_effects:
   * @actor: a #MetaWindowActor
   *
   * Virtual function called when the effects on @actor need to be killed
   * prematurely; the plugin must call the completed() callback as if the effect
   * terminated naturally.
   */
  void (*kill_window_effects)      (MetaPlugin      *plugin,
                                    MetaWindowActor *actor);

  /**
   * MetaPluginClass::kill_switch_workspace:
   *
   * Virtual function called when the workspace-switching effect needs to be
   * killed prematurely.
   */
  void (*kill_switch_workspace)    (MetaPlugin     *plugin);

  /**
   * MetaPluginClass::xevent_filter:
   * @event: (type xlib.XEvent):
   *
   * Virtual function called when handling each event.
   *
   * Returns: %TRUE if the plugin handled the event type (i.e., if the return
   * value is %FALSE, there will be no subsequent call to the manager
   * completed() callback, and the compositor must ensure that any appropriate
   * post-effect cleanup is carried out.
   */
  gboolean (*xevent_filter) (MetaPlugin       *plugin,
                             XEvent           *event);

  /**
   * MetaPluginClass::keybinding_filter:
   * @binding: a #MetaKeyBinding
   *
   * Virtual function called when handling each keybinding.
   *
   * Returns: %TRUE if the plugin handled the keybinding.
   */
  gboolean (*keybinding_filter) (MetaPlugin     *plugin,
                                 MetaKeyBinding *binding);

  /**
   * MetaPluginClass::confirm_display_config:
   * @plugin: a #MetaPlugin
   *
   * Virtual function called when the display configuration changes.
   * The common way to implement this function is to show some form
   * of modal dialog that should ask the user if everything was ok.
   *
   * When confirmed by the user, the plugin must call meta_plugin_complete_display_change()
   * to make the configuration permanent. If that function is not
   * called within the timeout, the previous configuration will be
   * reapplied.
   */
  void (*confirm_display_change) (MetaPlugin *plugin);

  /**
   * MetaPluginClass::plugin_info:
   * @plugin: a #MetaPlugin
   *
   * Virtual function that returns information about the #MetaPlugin.
   *
   * Returns: a #MetaPluginInfo.
   */
  const MetaPluginInfo * (*plugin_info) (MetaPlugin *plugin);
};

start ()

virtual function called when the compositor starts managing a screen

minimize ()

virtual function called when a window is minimized

maximize ()

virtual function called when a window is maximized

unmaximize ()

virtual function called when a window is unmaximized

map ()

virtual function called when a window is mapped

destroy ()

virtual function called when a window is destroyed

switch_workspace ()

virtual function called when the user switches to another workspace

kill_window_effects ()

virtual function called when the effects on a window need to be killed prematurely; the plugin must call the completed() callback as if the effect terminated naturally

kill_switch_workspace ()

virtual function called when the workspace-switching effect needs to be killed prematurely

xevent_filter ()

virtual function called when handling each event

keybinding_filter ()

virtual function called when handling each keybinding

confirm_display_change ()

plugin_info ()

virtual function that returns information about the MetaPlugin

struct MetaPluginInfo

struct MetaPluginInfo {
  const gchar *name;
  const gchar *version;
  const gchar *author;
  const gchar *license;
  const gchar *description;
};

const gchar *name;

name of the plugin

const gchar *version;

version of the plugin

const gchar *author;

author of the plugin

const gchar *license;

license of the plugin

const gchar *description;

description of the plugin

meta_plugin_running ()

gboolean            meta_plugin_running                 (MetaPlugin *plugin);

meta_plugin_debug_mode ()

gboolean            meta_plugin_debug_mode              (MetaPlugin *plugin);

meta_plugin_get_info ()

const MetaPluginInfo * meta_plugin_get_info             (MetaPlugin *plugin);

struct MetaPluginVersion

struct MetaPluginVersion {
  /*
   * Version information; the first three numbers match the Meta version
   * with which the plugin was compiled (see clutter-plugins/simple.c for sample
   * code).
   */
  guint version_major;
  guint version_minor;
  guint version_micro;

  /*
   * Version of the plugin API; this is unrelated to the matacity version
   * per se. The API version is checked by the plugin manager and must match
   * the one used by it (see clutter-plugins/default.c for sample code).
   */
  guint version_api;
};

guint version_major;

major component of the version number of Meta with which the plugin was compiled

guint version_minor;

minor component of the version number of Meta with which the plugin was compiled

guint version_micro;

micro component of the version number of Meta with which the plugin was compiled

guint version_api;

version of the plugin API

META_PLUGIN_DECLARE()

#define             META_PLUGIN_DECLARE(ObjectName, object_name)

meta_plugin_switch_workspace_completed ()

void                meta_plugin_switch_workspace_completed
                                                        (MetaPlugin *plugin);

meta_plugin_minimize_completed ()

void                meta_plugin_minimize_completed      (MetaPlugin *plugin,
                                                         MetaWindowActor *actor);

meta_plugin_maximize_completed ()

void                meta_plugin_maximize_completed      (MetaPlugin *plugin,
                                                         MetaWindowActor *actor);

meta_plugin_unmaximize_completed ()

void                meta_plugin_unmaximize_completed    (MetaPlugin *plugin,
                                                         MetaWindowActor *actor);

meta_plugin_map_completed ()

void                meta_plugin_map_completed           (MetaPlugin *plugin,
                                                         MetaWindowActor *actor);

meta_plugin_destroy_completed ()

void                meta_plugin_destroy_completed       (MetaPlugin *plugin,
                                                         MetaWindowActor *actor);

enum MetaModalOptions

typedef enum {
  META_MODAL_POINTER_ALREADY_GRABBED = 1 << 0,
  META_MODAL_KEYBOARD_ALREADY_GRABBED = 1 << 1
} MetaModalOptions;

Options that can be provided when calling meta_plugin_begin_modal().

META_MODAL_POINTER_ALREADY_GRABBED

if set the pointer is already grabbed by the plugin and should not be grabbed again.

META_MODAL_KEYBOARD_ALREADY_GRABBED

if set the keyboard is already grabbed by the plugin and should not be grabbed again.

meta_plugin_begin_modal ()

gboolean            meta_plugin_begin_modal             (MetaPlugin *plugin,
                                                         MetaModalOptions options,
                                                         guint32 timestamp);

This function is used to grab the keyboard and mouse for the exclusive use of the plugin. Correct operation requires that both the keyboard and mouse are grabbed, or thing will break. (In particular, other passive X grabs in Meta can trigger but not be handled by the normal keybinding handling code.) However, the plugin can establish the keyboard and/or mouse grabs ahead of time and pass in the META_MODAL_POINTER_ALREADY_GRABBED and/or META_MODAL_KEYBOARD_ALREADY_GRABBED options. This facility is provided for two reasons: first to allow using this function to establish modality after a passive grab, and second to allow using obscure features of XGrabPointer() and XGrabKeyboard() without having to add them to this API.

plugin :

a MetaPlugin

options :

flags that modify the behavior of the modal grab

timestamp :

the timestamp used for establishing grabs

Returns :

whether we successfully grabbed the keyboard and mouse and made the plugin modal.

meta_plugin_end_modal ()

void                meta_plugin_end_modal               (MetaPlugin *plugin,
                                                         guint32 timestamp);

Ends the modal operation begun with meta_plugin_begin_modal(). This ungrabs both the mouse and keyboard even when META_MODAL_POINTER_ALREADY_GRABBED or META_MODAL_KEYBOARD_ALREADY_GRABBED were provided as options when beginnning the modal operation.

plugin :

a MetaPlugin

timestamp :

the time used for releasing grabs

meta_plugin_get_screen ()

MetaScreen *        meta_plugin_get_screen              (MetaPlugin *plugin);

Gets the MetaScreen corresponding to a plugin. Each plugin instance is associated with exactly one screen; if Metacity is managing multiple screens, multiple plugin instances will be created.

plugin :

a MetaPlugin

Returns :

the MetaScreen for the plugin. [transfer none]

meta_plugin_manager_set_plugin_type ()

void                meta_plugin_manager_set_plugin_type (GType gtype);

Property Details

The "debug-mode" property

  "debug-mode"               gboolean              : Read

Debug Mode.

Default value: FALSE


The "screen" property

  "screen"                   MetaScreen*           : Read / Write

MetaScreen.