action-publisher

action-publisher — Publish action data to the HUD

Stability Level

Stable, unless otherwise indicated

Synopsis

#include <libhud/action-publisher.h>

#define             HUD_ACTION_PUBLISHER_SIGNAL_ACTION_GROUP_ADDED
#define             HUD_ACTION_PUBLISHER_SIGNAL_ACTION_GROUP_REMOVED
#define             HUD_ACTION_PUBLISHER_NO_CONTEXT
#define             HUD_ACTION_PUBLISHER_ALL_WINDOWS
struct              HudActionPublisherActionGroupSet;
HudActionPublisher * hud_action_publisher_new           (guint window_id,
                                                         const gchar *context_id);
HudActionPublisher * hud_action_publisher_new_for_application
                                                        (GApplication *application);
void                hud_action_publisher_add_description
                                                        (HudActionPublisher *publisher,
                                                         HudActionDescription *description);
void                hud_action_publisher_add_action_group
                                                        (HudActionPublisher *publisher,
                                                         const gchar *prefix,
                                                         const gchar *object_path);
void                hud_action_publisher_remove_action_group
                                                        (HudActionPublisher *publisher,
                                                         const gchar *prefix,
                                                         GVariant *identifier);
guint               hud_action_publisher_get_window_id  (HudActionPublisher *publisher);
const gchar *       hud_action_publisher_get_context_id (HudActionPublisher *publisher);
GList *             hud_action_publisher_get_action_groups
                                                        (HudActionPublisher *publisher);
const gchar *       hud_action_publisher_get_description_path
                                                        (HudActionPublisher *publisher);
HudActionDescription * hud_action_description_new       (const gchar *action_name,
                                                         GVariant *action_target);
HudActionDescription * hud_action_description_ref       (HudActionDescription *description);
void                hud_action_description_unref        (HudActionDescription *description);
const gchar *       hud_action_description_get_action_name
                                                        (HudActionDescription *description);
GVariant *          hud_action_description_get_action_target
                                                        (HudActionDescription *description);
void                hud_action_description_set_attribute_value
                                                        (HudActionDescription *description,
                                                         const gchar *attribute_name,
                                                         GVariant *value);
void                hud_action_description_set_attribute
                                                        (HudActionDescription *description,
                                                         const gchar *attribute_name,
                                                         const gchar *format_string,
                                                         ...);
void                hud_action_description_set_parameterized
                                                        (HudActionDescription *parent,
                                                         GMenuModel *child);
                    HudActionPublisher;
                    HudActionDescription;

Object Hierarchy

  GObject
   +----HudActionPublisher
  GObject
   +----HudActionDescription

Signals

  "action-group-added"                             : Run Last
  "action-group-removed"                           : Run Last
  "changed"                                        : Has Details

Description

Each context in the application should have a HudActionPublisher object to represents the actions that are available to the user when that window and context are visible. This acts as a set of actions that can be activated by either the window manager changing focus or the application changing contexts.

On each action publisher there exits several action groups which can be separated by allowing different prefixes for those action groups. A particular prefix should only be used once per action publisher, but an action group can by used by several action publishers.

The values describing the action, including the label and description that show up in the HUD are set via creating a HudActionDescription for a action. Each action can have more than one description if there is a reason to do so. But, it is probably better to use the keywords attribute in the majority cases.

Details

HUD_ACTION_PUBLISHER_SIGNAL_ACTION_GROUP_ADDED

#define HUD_ACTION_PUBLISHER_SIGNAL_ACTION_GROUP_ADDED      "action-group-added"

Define for the string to access the signal HudActionPublisher::action-group-added


HUD_ACTION_PUBLISHER_SIGNAL_ACTION_GROUP_REMOVED

#define HUD_ACTION_PUBLISHER_SIGNAL_ACTION_GROUP_REMOVED    "action-group-removed"

Define for the string to access the signal HudActionPublisher::action-group-removed


HUD_ACTION_PUBLISHER_NO_CONTEXT

#define HUD_ACTION_PUBLISHER_NO_CONTEXT                     (NULL)

Can be passed to hud_action_publisher_new() to request that it build it's own context.


HUD_ACTION_PUBLISHER_ALL_WINDOWS

#define HUD_ACTION_PUBLISHER_ALL_WINDOWS                    (0)

Can be passed to hud_action_publisher_new() to request that these actions apply to all windows for the application.


struct HudActionPublisherActionGroupSet

struct HudActionPublisherActionGroupSet {
	gchar * prefix;
	gchar * path;
};

A set of properties of that describe the action group.

gchar *prefix;

Action prefix for the action group

gchar *path;

Path that the action group is exported on DBus

hud_action_publisher_new ()

HudActionPublisher * hud_action_publisher_new           (guint window_id,
                                                         const gchar *context_id);

Creates a new HudActionPublisher based on the window ID passed in via window_id and context ID from context_id.

Either one of them can be not used by passing in eithe of the defines HUD_ACTION_PUBLISHER_ALL_WINDOWS or HUD_ACTION_PUBLISHER_NO_CONTEXT for the appropriate parameter.

window_id :

A window ID. [allow-none]

context_id :

A context ID. [allow-none]

Returns :

A new HudActionPublisher object. [transfer full]

hud_action_publisher_new_for_application ()

HudActionPublisher * hud_action_publisher_new_for_application
                                                        (GApplication *application);

Creates a new HudActionPublisher and automatically registers the default actions under the "app" prefix.

application :

A GApplication object

Returns :

A new HudActionPublisher object. [transfer full]

hud_action_publisher_add_description ()

void                hud_action_publisher_add_description
                                                        (HudActionPublisher *publisher,
                                                         HudActionDescription *description);

Adds description to the list of actions that the application exports to the HUD.

If the application is already exporting an action with the same name and target value as description then it will be replaced.

You should only use this API for situations like recent documents and bookmarks.

publisher :

the HudActionPublisher

description :

an action description

hud_action_publisher_add_action_group ()

void                hud_action_publisher_add_action_group
                                                        (HudActionPublisher *publisher,
                                                         const gchar *prefix,
                                                         const gchar *object_path);

Informs the HUD of the existance of an action group.

The action group must be published on the shared session bus connection of this process at object_path.

The prefix defines the type of action group. Currently "app" and "win" are supported. For example, if the exported action group contained a "quit" action and you wanted to refer to it as "app.quit" from action descriptions, then you would use the prefix "app" here.

identifier is a piece of identifying information, depending on which prefix is used. Currently, this should be NULL for the "app" prefix and should be a uint32 specifying the window ID (eg: XID) for the "win" prefix.

You do not need to manually export your action groups if you are using GApplication.

publisher :

a HudActionPublisher

prefix :

the action prefix for the group (like "app")

object_path :

the object path of the exported group

hud_action_publisher_remove_action_group ()

void                hud_action_publisher_remove_action_group
                                                        (HudActionPublisher *publisher,
                                                         const gchar *prefix,
                                                         GVariant *identifier);

Informs the HUD that an action group no longer exists.

This reverses the effect of a previous call to hud_action_publisher_add_action_group() with the same parameters.

publisher :

a HudActionPublisher

prefix :

the action prefix for the group (like "app")

identifier :

an identifier, or NULL. [allow-none]

hud_action_publisher_get_window_id ()

guint               hud_action_publisher_get_window_id  (HudActionPublisher *publisher);

Gets the window ID for this publisher

publisher :

A HudActionPublisher object

Returns :

The Window ID associtaed with this action publisher

hud_action_publisher_get_context_id ()

const gchar *       hud_action_publisher_get_context_id (HudActionPublisher *publisher);

Gets the context ID for this publisher

publisher :

A HudActionPublisher object

Returns :

The context ID associtaed with this action publisher

hud_action_publisher_get_action_groups ()

GList *             hud_action_publisher_get_action_groups
                                                        (HudActionPublisher *publisher);

Grabs the action groups for this publisher

publisher :

A HudActionPublisher object

Returns :

The groups in this publisher. [transfer container][element-type HudActionPublisherActionGroupSet *]

hud_action_publisher_get_description_path ()

const gchar *       hud_action_publisher_get_description_path
                                                        (HudActionPublisher *publisher);

Grabs the object path of the description for this publisher

publisher :

A HudActionPublisher object

Returns :

The object path of the descriptions

hud_action_description_new ()

HudActionDescription * hud_action_description_new       (const gchar *action_name,
                                                         GVariant *action_target);

Creates a new HudActionDescription.

The situations in which you want to do this are limited to "dynamic" types of actions -- things like bookmarks or recent documents.

Use hud_action_publisher_add_descriptions_from_file() to take care of the bulk of the actions in your application.

action_name :

a (namespaced) action name

action_target :

an action target

Returns :

a new HudActionDescription with no attributes

hud_action_description_ref ()

HudActionDescription * hud_action_description_ref       (HudActionDescription *description);

Increase the reference count to an action description

description :

A HudActionDescription

Returns :

Value of description. [transfer none]

hud_action_description_unref ()

void                hud_action_description_unref        (HudActionDescription *description);

Decrease the reference count to an action description

description :

A HudActionDescription

hud_action_description_get_action_name ()

const gchar *       hud_action_description_get_action_name
                                                        (HudActionDescription *description);

Gets the action name of description.

This, together with the action target, uniquely identify an action description.

description :

a HudActionDescription

Returns :

the action name. [transfer none]

hud_action_description_get_action_target ()

GVariant *          hud_action_description_get_action_target
                                                        (HudActionDescription *description);

Gets the action target of description (ie: the GVariant that will be passed to invocations of the action).

This may be NULL.

This, together with the action name, uniquely identify an action description.

description :

a HudActionDescription

Returns :

the target value. [transfer none]

hud_action_description_set_attribute_value ()

void                hud_action_description_set_attribute_value
                                                        (HudActionDescription *description,
                                                         const gchar *attribute_name,
                                                         GVariant *value);

Sets or unsets an attribute on description.

You may not change the "action" or "target" attributes.

If value is non-NULL then it is the new value for attribute. A NULL value unsets attribute_name.

value is consumed if it is floating.

description :

a HudActionDescription

attribute_name :

an attribute name

value :

the new value for the attribute. [allow-none]

hud_action_description_set_attribute ()

void                hud_action_description_set_attribute
                                                        (HudActionDescription *description,
                                                         const gchar *attribute_name,
                                                         const gchar *format_string,
                                                         ...);

Sets or unsets an attribute on description.

You may not change the "action" or "target" attributes.

If format_string is non-NULL then this call is equivalent to g_variant_new() and hud_action_description_set_attribute_value().

If format_string is NULL then this call is equivalent to hud_action_description_set_attribute_value() with a NULL value.

description :

a HudActionDescription

attribute_name :

an attribute name

format_string :

a GVariant format string. [allow-none]

... :

arguments to format_string

hud_action_description_set_parameterized ()

void                hud_action_description_set_parameterized
                                                        (HudActionDescription *parent,
                                                         GMenuModel *child);

A function to put one action description as a child for the first one. This is used for parameterized actions where one can set up children that are displayed on the 'dialog' mode of the HUD.

parent :

a HudActionDescription

child :

The child GMenuModel to add

HudActionPublisher

typedef struct _HudActionPublisher HudActionPublisher;

An object representing the actions that are published for a particular context within the application. Most often this is a window, but could also be used for tabs or other modal style user contexts in the application.


HudActionDescription

typedef struct _HudActionDescription HudActionDescription;

A description of an action that is accessible from the HUD. This is an opaque structure type and all accesses must be made via the API.

Signal Details

The "action-group-added" signal

void                user_function                      (HudActionPublisher *param1,
                                                        gchar              *param2,
                                                        gchar              *arg2,
                                                        gpointer            user_data)      : Run Last

Emitted when a new action group is added to the publisher

param1 :

Prefix for the action group

param2 :

Path group is exported on DBus

user_data :

user data set when the signal handler was connected.

The "action-group-removed" signal

void                user_function                      (HudActionPublisher *param1,
                                                        gchar              *param2,
                                                        gchar              *arg2,
                                                        gpointer            user_data)      : Run Last

Emitted when a new action group is removed from the publisher

param1 :

Prefix for the action group

param2 :

Path group is exported on DBus

user_data :

user data set when the signal handler was connected.

The "changed" signal

void                user_function                      (HudActionDescription *param1,
                                                        gchar                *arg1,
                                                        gpointer              user_data)      : Has Details

Emitted when a property of the action description gets changed.

param1 :

Name of changed property

user_data :

user data set when the signal handler was connected.