GtkHotkeyRegistry

## GtkHotkeyRegistry GtkHotkeyRegistry — Abstract base class for services storing and loading hotkeys |

## Synopsis

                        GtkHotkeyRegistry;
    enum                GtkHotkeyRegistryError;
    #define             GTK_HOTKEY_REGISTRY_ERROR
    GtkHotkeyRegistry*  gtk_hotkey_registry_get_default     (void);
    GtkHotkeyInfo*      gtk_hotkey_registry_get_hotkey      (GtkHotkeyRegistry *self,
                                                             const char *app_id,
                                                             const char *key_id,
                                                             GError **error);
    GList*              gtk_hotkey_registry_get_application_hotkeys
                                                            (GtkHotkeyRegistry *self,
                                                             const char *app_id,
                                                             GError **error);
    GList*              gtk_hotkey_registry_get_all_hotkeys (GtkHotkeyRegistry *self);
    gboolean            gtk_hotkey_registry_store_hotkey    (GtkHotkeyRegistry *self,
                                                             GtkHotkeyInfo *info,
                                                             GError **error);
    gboolean            gtk_hotkey_registry_delete_hotkey   (GtkHotkeyRegistry *self,
                                                             const gchar *app_id,
                                                             const gchar *key_id,
                                                             GError **error);
    gboolean            gtk_hotkey_registry_has_hotkey      (GtkHotkeyRegistry *self,
                                                             const gchar *app_id,
                                                             const gchar *key_id);
    void                gtk_hotkey_registry_hotkey_stored   (GtkHotkeyRegistry *self,
                                                             GtkHotkeyInfo *hotkey);
    void                gtk_hotkey_registry_hotkey_deleted  (GtkHotkeyRegistry *self,
                                                             GtkHotkeyInfo *hotkey);

## Object Hierarchy

      GObject
       +----GtkHotkeyRegistry

## Signals

      "hotkey-deleted"                                 : Run Last
      "hotkey-stored"                                  : Run Last

## Description

GtkHotkeyRegistry is an abstract base class for implementing a platform specific service for storing and loading hotkey configurations.

The actual binding of the hotkey into the environment is done by a GtkHotkeyListener. This class is only meant to do the management part of the hotkey handling.

The reasong why applications should use a GtkHotkeyRegistry and not just a flat text file with the hotkey signature is to make sure we don't overwrite or interfere with the hotkeys of other applications. And possibly providing a unified user interface for managing the hotkeys of all applications.

To obtain a GtkHotkeyRegistry matching your desktop environment use the factory method `gtk_hotkey_registry_get_default()`.

## Details

### GtkHotkeyRegistry

    typedef struct _GtkHotkeyRegistry GtkHotkeyRegistry;

### enum GtkHotkeyRegistryError

    typedef enum
    {
    	GTK_HOTKEY_REGISTRY_ERROR_UNKNOWN_APP,
    	GTK_HOTKEY_REGISTRY_ERROR_UNKNOWN_KEY,
    	GTK_HOTKEY_REGISTRY_ERROR_MALFORMED_MEDIUM,
    	GTK_HOTKEY_REGISTRY_ERROR_IO,
    	GTK_HOTKEY_REGISTRY_ERROR_UNKNOWN,
    	GTK_HOTKEY_REGISTRY_ERROR_BAD_SIGNATURE,
    	GTK_HOTKEY_REGISTRY_ERROR_MISSING_APP,
    } GtkHotkeyRegistryError;

Error codes for GErrors related to GtkHotkeyRegistrys

`GTK_HOTKEY_REGISTRY_ERROR_UNKNOWN_APP` | The application which is the involved in the transaction has not registered any hotkeys
`GTK_HOTKEY_REGISTRY_ERROR_UNKNOWN_KEY` | The hotkey key-id (the identifier that identifies the hotkey among those belonging to an application) is not known.
`GTK_HOTKEY_REGISTRY_ERROR_MALFORMED_MEDIUM` | The medium from which to read or write is in an unrecoverable state. For example a file containing syntax errors
`GTK_HOTKEY_REGISTRY_ERROR_IO` | There was some problem with the actual io operation. Missing file permissions, disk full, etc.
`GTK_HOTKEY_REGISTRY_ERROR_UNKNOWN` | Unexpected and uncharacterized error
`GTK_HOTKEY_REGISTRY_ERROR_BAD_SIGNATURE` | The hotkey signature is not valid. See "signature".
`GTK_HOTKEY_REGISTRY_ERROR_MISSING_APP` | A GtkHotkeyInfo is referring an application via its "app-info" property, but the application can not be found.

### GTK_HOTKEY_REGISTRY_ERROR

    #define GTK_HOTKEY_REGISTRY_ERROR gtk_hotkey_registry_error_quark()

Error domain for GtkHotkeyRegistry.

### gtk_hotkey_registry_get_default ()

    GtkHotkeyRegistry*  gtk_hotkey_registry_get_default     (void);

Currently the only implementation of this class is GtkHotkeyKeyFileRegistry.

Returns : | A reference to a GtkHotkeyRegistry matching your platform

### gtk_hotkey_registry_get_hotkey ()

    GtkHotkeyInfo*      gtk_hotkey_registry_get_hotkey      (GtkHotkeyRegistry *self,
                                                             const char *app_id,
                                                             const char *key_id,
                                                             GError **error);

Look up a hotkey given its id and application id.

`self` : | The registry to search in
`app_id` : | The name under which the application has registered it self when it created the GtkHotkeyInfo in the first place.
`key_id` : | The id assignedd to the actual hotkey on the moment of its creation
`error` : | Place to store a GError in case of errors, or `NULL` to ignore
Returns : | The GtkHotkeyInfo for the requested parameters or `NULL` is none where found. In the case `NULL` is returned `error` will be set accordingly. Free the hotkey with `g_object_unref()` when you are done using it.

### gtk_hotkey_registry_get_application_hotkeys ()

    GList*              gtk_hotkey_registry_get_application_hotkeys
                                                            (GtkHotkeyRegistry *self,
                                                             const char *app_id,
                                                             GError **error);

Look up all hotkeys registered by a given application.

`self` : | The GtkHotkeyRegistry to look hotkeys up in
`app_id` : | Unique application id
`error` : | Place to return a GError or `NULL`
Returns : | A list of GtkHotkeyInfo objects. The list should be with freed with `g_list_free()` and the hotkey objects should be freed with `g_object_unref()`.

### gtk_hotkey_registry_get_all_hotkeys ()

    GList*              gtk_hotkey_registry_get_all_hotkeys (GtkHotkeyRegistry *self);

Look up all hotkeys registered by a given application.

`self` : | The GtkHotkeyRegistry to look hotkeys up in
Returns : | A list of all valid GtkHotkeyInfos stored in the registry. The list should be with freed with `g_list_free()` and the hotkey objects should be freed with `g_object_unref()`.

### gtk_hotkey_registry_store_hotkey ()

    gboolean            gtk_hotkey_registry_store_hotkey    (GtkHotkeyRegistry *self,
                                                             GtkHotkeyInfo *info,
                                                             GError **error);

Store a hotkey in the registry for later usage. In case of success the "hotkey-stored" signal will be emitted.

`self` : | The GtkHotkeyRegistry in which to store the hotkey
`info` : | The GtkHotkeyInfo to store
`error` : | Place to return a GError or `NULL` to ignore
Returns : | `TRUE` on success and `FALS` otherwise. In case of errors `error` will be set accordingly.

### gtk_hotkey_registry_delete_hotkey ()

    gboolean            gtk_hotkey_registry_delete_hotkey   (GtkHotkeyRegistry *self,
                                                             const gchar *app_id,
                                                             const gchar *key_id,
                                                             GError **error);

Delete a hotkey from the registry. In case of success the "hotkey-deleted" signal will be emitted.

`self` : | The GtkHotkeyRegistry from which to delete the hotkey
`app_id` : | The value of the "application-id" property of the stored hotkey
`key_id` : | The value of the "key-id" property of the stored hotkey
`error` : | Place to return a GError or `NULL` to ignore
Returns : | `TRUE` on success and `FALS` otherwise. In case of errors `error` will be set accordingly.

### gtk_hotkey_registry_has_hotkey ()

    gboolean            gtk_hotkey_registry_has_hotkey      (GtkHotkeyRegistry *self,
                                                             const gchar *app_id,
                                                             const gchar *key_id);

Look up all hotkeys registered by a given application.

`self` : | The GtkHotkeyRegistry to look hotkeys up in
`app_id` : | The value of the "application-id" property of the stored hotkey
`key_id` : | The value of the "key-id" property of the stored hotkey
Returns : | `TRUE` if the registry has stored a hotkey with with application id `app_id` and hotkey id `key_id`.

### gtk_hotkey_registry_hotkey_stored ()

    void                gtk_hotkey_registry_hotkey_stored   (GtkHotkeyRegistry *self,
                                                             GtkHotkeyInfo *hotkey);

Emit the "hotkey-stored" signal on `self`. This method should only be used by child classes of GtkHotkeyRegistry.

`self` : | The GtkHotkeyRegistry to emit the signal on
`hotkey` : |

### gtk_hotkey_registry_hotkey_deleted ()

    void                gtk_hotkey_registry_hotkey_deleted  (GtkHotkeyRegistry *self,
                                                             GtkHotkeyInfo *hotkey);

Emit the "hotkey-deleted" signal on `self`. This method should only be used by child classes of GtkHotkeyRegistry.

`self` : | The GtkHotkeyRegistry to emit the signal on
`hotkey` : |

## Signal Details

### The `"hotkey-deleted"` signal

    void                user_function                      (GtkHotkeyRegistry *hotkey,
                                                            GObject           *arg1,
                                                            gpointer           user_data)      : Run Last

Emitted when a hotkey has been deleted from the registry

`hotkey` : | The hotkey that was deleted
`user_data` : | user data set when the signal handler was connected.

### The `"hotkey-stored"` signal

    void                user_function                      (GtkHotkeyRegistry *hotkey,
                                                            GObject           *arg1,
                                                            gpointer           user_data)      : Run Last

Emitted when a hotkey has been stored in the registry

`hotkey` : | The hotkey that was stored
`user_data` : | user data set when the signal handler was connected.

## See Also

GtkHotkeyKeyFileRegistry