GtkHotkeyInfo

## GtkHotkeyInfo GtkHotkeyInfo — Primary representation of a hotkey |

## Synopsis

                        GtkHotkeyInfo;
    gboolean            gtk_hotkey_info_bind                (GtkHotkeyInfo *self,
                                                             GError **error);
    gboolean            gtk_hotkey_info_unbind              (GtkHotkeyInfo *self,
                                                             GError **error);
    const gchar*        gtk_hotkey_info_get_application_id  (GtkHotkeyInfo *self);
    const gchar*        gtk_hotkey_info_get_key_id          (GtkHotkeyInfo *self);
    GAppInfo*           gtk_hotkey_info_get_app_info        (GtkHotkeyInfo *self);
    const gchar*        gtk_hotkey_info_get_signature       (GtkHotkeyInfo *self);
    const gchar*        gtk_hotkey_info_get_description     (GtkHotkeyInfo *self);
    void                gtk_hotkey_info_set_description     (GtkHotkeyInfo *self,
                                                             const gchar *description);
    gboolean            gtk_hotkey_info_equals              (GtkHotkeyInfo *hotkey1,
                                                             GtkHotkeyInfo *hotkey2,
                                                             gboolean sloppy_equals);
    void                gtk_hotkey_info_activated           (GtkHotkeyInfo *self,
                                                             guint event_time);
    GtkHotkeyInfo*      gtk_hotkey_info_new                 (const gchar *app_id,
                                                             const gchar *key_id,
                                                             const gchar *signature,
                                                             GAppInfo *app_info);

## Object Hierarchy

      GObject
       +----GtkHotkeyInfo

## Properties

      "app-info"                 GAppInfo*             : Read / Write / Construct Only
      "application-id"           gchar*                : Read / Write / Construct Only
      "bound"                    gboolean              : Read
      "description"              gchar*                : Read / Write
      "key-id"                   gchar*                : Read / Write / Construct Only
      "signature"                gchar*                : Read / Write / Construct Only

## Signals

      "activated"                                      : Run Last

## Description

GtkHotkeyInfo is the primary object around which the GtkHotkey library revolves.

Hotkeys are stored and managed via a GtkHotkeyRegistry, while the actual binding and listening for key-presses is done by a GtkHotkeyListener.

## Details

### GtkHotkeyInfo

    typedef struct _GtkHotkeyInfo GtkHotkeyInfo;

### gtk_hotkey_info_bind ()

    gboolean            gtk_hotkey_info_bind                (GtkHotkeyInfo *self,
                                                             GError **error);

Register the hotkey with the system. The "activated" signal will now be emitted when the user presses the keyboard combination matching the hotkey's signature.

`self` : | The hotkey to bind
`error` : | Place to return a GError, or `NULL` to ignore
Returns : | `TRUE` on success, and `FALSE` on error in which case `error` is also set

### gtk_hotkey_info_unbind ()

    gboolean            gtk_hotkey_info_unbind              (GtkHotkeyInfo *self,
                                                             GError **error);

Remove the hotkey binding from the system. The "activated" signal will no longer be emitted when the hotkey is pressed.

`self` : | The hotkey to unbind
`error` : | Place to return a GError, or `NULL` to ignore
Returns : | `TRUE` on success, and `FALSE` on error in which case `error` is also set

### gtk_hotkey_info_get_application_id ()

    const gchar*        gtk_hotkey_info_get_application_id  (GtkHotkeyInfo *self);

Get the unique system identifier for the hotkey. See "application-id" for details.

`self` : |
Returns : |

### gtk_hotkey_info_get_key_id ()

    const gchar*        gtk_hotkey_info_get_key_id          (GtkHotkeyInfo *self);

Get the identifier the owning application use to identify this hotkey. See "key-id" for details.

`self` : |
Returns : |

### gtk_hotkey_info_get_app_info ()

    GAppInfo*           gtk_hotkey_info_get_app_info        (GtkHotkeyInfo *self);

Not to be confused with the value of the "application-id" property. The hotkey can be associated with an installed desktop application via a GAppInfo. This is not mandatory and this method returns `NULL` if no desktop application has been associated with this hotkey.

See the "app-info" property for details.

`self` : |
Returns : |

### gtk_hotkey_info_get_signature ()

    const gchar*        gtk_hotkey_info_get_signature       (GtkHotkeyInfo *self);

Get the keyboard signature of the hotkey. This could for example be '<Alt>F3' or '<Control><Shift>G'.

`self` : |
Returns : |

### gtk_hotkey_info_get_description ()

    const gchar*        gtk_hotkey_info_get_description     (GtkHotkeyInfo *self);

Get the free form description of the hotkey. The description is not guaranteed to be set and may be `NULL`.

FIXME: Do we need to take i18n into account here?

`self` : |
Returns : | The description of the hotkey or `NULL` if none is set

### gtk_hotkey_info_set_description ()

    void                gtk_hotkey_info_set_description     (GtkHotkeyInfo *self,
                                                             const gchar *description);

Set a description for the hotkey. See also `gtk_hotkey_info_get_description()`.

`self` : |
`description` : |

### gtk_hotkey_info_equals ()

    gboolean            gtk_hotkey_info_equals              (GtkHotkeyInfo *hotkey1,
                                                             GtkHotkeyInfo *hotkey2,
                                                             gboolean sloppy_equals);

Compare two GtkHotkeyInfos to see if they are equal. This method allows an optional 'sloppy equality' which ignores "description" and "app-info".

`hotkey1` : | The first hotkey to compare
`hotkey2` : | Second hotkey to compare to
`sloppy_equals` : | If `TRUE` sloppy equality will be used. This ignores the "description" and "app-info" properties of the objects.
Returns : | `TRUE` if all the properties of the hotkeys match. Two `NULL` hotkeys are also considered equal.

### gtk_hotkey_info_activated ()

    void                gtk_hotkey_info_activated           (GtkHotkeyInfo *self,
                                                             guint event_time);

Emit the "activated" signal on a hotkey. Mainly called by GtkHotkeyListener implementations. This method should not normally be used by applications.

`self` : | GtkHotkeyInfo to emit the "activated" signal
`event_time` : | The system time the event happened on. This is useful for applications to pass through focus stealing prevention when mapping windows

### gtk_hotkey_info_new ()

    GtkHotkeyInfo*      gtk_hotkey_info_new                 (const gchar *app_id,
                                                             const gchar *key_id,
                                                             const gchar *signature,
                                                             GAppInfo *app_info);

Create a new hotkey. To actually trigger the hotkey when the user enters the right keyboard combination call `gtk_hotkey_info_bind()`. To save and load your hotkey settings use the GtkHotkeyRegistry provided by `gtk_hotkey_registry_get_default()`.

`app_id` : | Unique identifier the running application can choose for it self. May be a free form string, but a descriptive name is encouraged
`key_id` : | A key the application uses to recognize the hotkey. May be a free form string, but a descriptive name is encouraged
`signature` : | A key press signature parsable by `gtk_accelerator_parse()`. For examplpe '<Alt>F3' or '<Control><Shift>G'.
`app_info` : | An optional GAppInfo to associate with the hotkey. Pass `NULL` to ignore this
Returns : | A new GtkHotkeyInfo or `NULL` on error. Error conditions could for example be invalid an invalid `signature`, or `NULL` arguments.

## Property Details

### The `"app-info"` property

      "app-info"                 GAppInfo*             : Read / Write / Construct Only

A GAppInfo associated with the key. This is mainly useful for external applications which can use the information provided by the GAppInfo to display meaningful messages to the user. Like 'The keyboard combination <Alt>F3' is already assigned to the application "Deskbar Applet", please select another'.

### The `"application-id"` property

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

A free form string chosen by the application using the hotkey, under which the application identifies itself.

Default value: NULL

### The `"bound"` property

      "bound"                    gboolean              : Read

Property reflecting whether or not this hotkey has been bound to a GtkHotkeyListener. If this property is `TRUE` you will receive "activated" signals when the hotkey is triggered by the user.

Default value: FALSE

### The `"description"` property

      "description"              gchar*                : Read / Write

An optional free form description of the hotkey.

Default value: ""

### The `"key-id"` property

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

A free form string the application using the hotkey has attributed the hotkey so that it can be identified later on. Applications are encouraged to choose descriptive key ids.

Default value: NULL

### The `"signature"` property

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

The keyboard signature of the hotkey. This could for example by '<Alt>F3' or '<Control><Shift>G'. The signature should be parsable by `gtk_accelerator_parse()`.

Default value: NULL

## Signal Details

### The `"activated"` signal

    void                user_function                      (GtkHotkeyInfo *hotkey,
                                                            guint          event_time,
                                                            gpointer       user_data)       : Run Last

Emitted when a hotkey has been activated.

`hotkey` : | a GtkHotkeyInfo for the hotkey that was activated
`event_time` : | Time for event triggering the keypress. This is mainly used to pass to window management functions to pass through focus stealing prevention
`user_data` : | user data set when the signal handler was connected.

## See Also

GtkHotkeyRegistry