## gok-key

gok-key

## Synopsis

    enum                KeyStyles;
    #define             FONT_SIZE_GROUP_UNDEFINED
    #define             FONT_SIZE_GROUP_UNIQUE
    #define             FONT_SIZE_GROUP_WORDCOMPLETE
    gboolean            gok_key_initialize                  (GokKey *pKey,
                                                             xmlNode *pNode);
    gboolean            gok_key_add_label                   (GokKey *pKey,
                                                             gchar *pLabelText,
                                                             guint level,
                                                             guint group,
                                                             const gchar *vmods);
    void                gok_key_set_output                  (GokKey *pKey,
                                                             gint Type,
                                                             gchar *pName,
                                                             AccessibleKeySynthType Flag);
    void                gok_key_change_label                (GokKey *pKey,
                                                             gchar *LabelText);
    void                gok_key_update_label                (GokKey *pKey);
    gint                gok_key_get_label_lengthpercell     (GokKey *pKey);
    gint                gok_key_get_label_heightpercell     (GokKey *pKey);
    gint                gok_key_calculate_font_size         (GokKey *pKey,
                                                             gboolean width,
                                                             gboolean bHeight);
    void                gok_key_set_font_size               (GokKey *pKey,
                                                             gint Size);
    void                gok_key_set_button_name             (GokKey *pKey);
    void                gok_key_set_button_label            (GokKey *pKey,
                                                             gchar *LabelText);
    gchar*              gok_key_get_label                   (GokKey *pKey);
    GokKeyLabel*        gok_keylabel_new                    (GokKey *pKey,
                                                             gchar *pLabelText,
                                                             guint level,
                                                             guint group,
                                                             const gchar *vmods);
    void                gok_keylabel_delete                 (GokKeyLabel *pKeyLabel);
    void                gok_key_set_cells                   (GokKey *pKey,
                                                             gint top,
                                                             gint bottom,
                                                             gint left,
                                                             gint right);
    GokKey*             gok_key_duplicate                   (GokKey *pKey);

## Description

## Details

### enum KeyStyles

    typedef enum {
    KEYSTYLE_NORMAL,
    KEYSTYLE_BRANCH,
    KEYSTYLE_BRANCHBACK,
    KEYSTYLE_GENERALDYNAMIC,
    KEYSTYLE_BRANCHMENUS,
    KEYSTYLE_BRANCHMENUITEMS,
    KEYSTYLE_MENUITEM,
    KEYSTYLE_BRANCHTOOLBARS,
    KEYSTYLE_TOOLBARITEM,
    KEYSTYLE_BRANCHGUI,
    KEYSTYLE_BRANCHGUIACTIONS,
    KEYSTYLE_PAGESELECTION,
    KEYSTYLE_BRANCHCOMPOSE,
    KEYSTYLE_TEXTNAV,
    KEYSTYLE_EDIT,
    KEYSTYLE_SELECT,
    KEYSTYLE_TOGGLESELECT,
    KEYSTYLE_BRANCHALPHABET,
    KEYSTYLE_SETTINGS,
    KEYSTYLE_SPELL,
    KEYSTYLE_WORDCOMPLETE,
    KEYSTYLE_POINTERCONTROL,
    KEYSTYLE_BRANCHHYPERTEXT,
    KEYSTYLE_BRANCHMODAL,
    KEYSTYLE_HTMLACTION,
    KEYSTYLE_HYPERLINK,
    KEYSTYLE_BRANCHTEXT,
    KEYSTYLE_HELP,
    KEYSTYLE_ABOUT,
    KEYSTYLE_DOCK,
    KEYSTYLE_MOUSE,
    KEYSTYLE_MOUSEBUTTON,
    KEYSTYLE_REPEATNEXT,
    KEYSTYLE_ADDWORD,
    KEYSTYLE_INSENSITIVE
    } KeyStyles;

### FONT_SIZE_GROUP_UNDEFINED

    #define FONT_SIZE_GROUP_UNDEFINED 0

### FONT_SIZE_GROUP_UNIQUE

    #define FONT_SIZE_GROUP_UNIQUE -1

### FONT_SIZE_GROUP_WORDCOMPLETE

    #define FONT_SIZE_GROUP_WORDCOMPLETE -2

### gok_key_initialize ()

    gboolean            gok_key_initialize                  (GokKey *pKey,
                                                             xmlNode *pNode);

`pKey` : | Pointer to the key that's getting initialized.
`pNode` : | Pointer to the XML node that contains the key data.
Returns : | TRUE if the key was initialized, FALSE if not.

### gok_key_add_label ()

    gboolean            gok_key_add_label                   (GokKey *pKey,
                                                             gchar *pLabelText,
                                                             guint level,
                                                             guint group,
                                                             const gchar *vmods);

Adds a label to the key. This allocates memory for the label that will be freed in gok_key_delete.

`pKey` : | Pointer to the key that's gets the new label.
`pLabelText` : |
`level` : |
`group` : |
`vmods` : |
Returns : | TRUE if the key was initialized, FALSE if not.

### gok_key_set_output ()

    void                gok_key_set_output                  (GokKey *pKey,
                                                             gint Type,
                                                             gchar *pName,
                                                             AccessibleKeySynthType Flag);

Sets the output for the key. This allocates memory for the output that will be freed in gok_key_delete.

`pKey` : | Pointer to the key that's gets the new output.
`Type` : | Type of output (e.g. keysym or keycode)
`pName` : | Pointer to the name string.
`Flag` : | Type of key synth output (if relevant)

### gok_key_change_label ()

    void                gok_key_change_label                (GokKey *pKey,
                                                             gchar *LabelText);

Changes the label displayed on the gok key.

`pKey` : | Pointer to the key that gets the new label.
`LabelText` : | The new label text.

### gok_key_update_label ()

    void                gok_key_update_label                (GokKey *pKey);

Changes the key's label if the modifier state has changed.

`pKey` : | Pointer to the key that gets an updated label.

### gok_key_get_label_lengthpercell ()

    gint                gok_key_get_label_lengthpercell     (GokKey *pKey);

Calculates the length of the key's label. Some keys span more than one cell so divide the label length into the number of cells.

`pKey` : | Pointer to the key you want the to find the label length per cell.
Returns : | The length of the key's label per cell.

### gok_key_get_label_heightpercell ()

    gint                gok_key_get_label_heightpercell     (GokKey *pKey);

Calculates the height of the key's label. Some keys span more than one cell so divide the label height into the number of cells.

`pKey` : | Pointer to the key you want to find the height.
Returns : | The height of the key's label per cell.

### gok_key_calculate_font_size ()

    gint                gok_key_calculate_font_size         (GokKey *pKey,
                                                             gboolean width,
                                                             gboolean bHeight);

Calculates the font size needed for the key's label to fill the key.

`pKey` : | Pointer to the key that we're getting the font size for.
`width` : |
`bHeight` : | If TRUE then calculate the font size needed for the height of the key's label. Note: Both bWidth and bHeight can be TRUE.
Returns : | The font size, in 1000s of a point (e.g. 9 point is 9000).

### gok_key_set_font_size ()

    void                gok_key_set_font_size               (GokKey *pKey,
                                                             gint Size);

Sets the font size for the key.

`pKey` : | Pointer to the key that gets the new font size.
`Size` : | Font size you want the key's text to be.

### gok_key_set_button_name ()

    void                gok_key_set_button_name             (GokKey *pKey);

Sets the 'name' of the key's label. The 'name' is used to determine the key/label colors from the .rc file. This must be called for every key after it's created and after the label name has been changed.

`pKey` : | Pointer to the key that gets the new 'name'.

### gok_key_set_button_label ()

    void                gok_key_set_button_label            (GokKey *pKey,
                                                             gchar *LabelText);

Changes the button label displayed on the key.

`pKey` : | Pointer to the key that will have it's button label changed.
`LabelText` : | Text for the button.

### gok_key_get_label ()

    gchar*              gok_key_get_label                   (GokKey *pKey);

`pKey` : | Pointer to the key that you want the label for.
Returns : | A pointer to the label's text string, NULL if no label.

### gok_keylabel_new ()

    GokKeyLabel*        gok_keylabel_new                    (GokKey *pKey,
                                                             gchar *pLabelText,
                                                             guint level,
                                                             guint group,
                                                             const gchar *vmods);

Allocates memory for a new key label and initializes the GokKeyLabel structure. Returns a pointer to the new key label, NULL if it can't be created. Add this label to a key so it will be deleted when the key is deleted.

`pKey` : | Pointer to the key that gets the new label.
`pLabelText` : | Text string for this label.
`level` : | the level (see XKB spec) for which this label is valid.
`group` : | the group (see XKB spec) for which this label is valid.
`vmods` : | a delimited list of virtual modifier names which must be matched in order for this label to be valid, or NULL if no virtual modifiers are relevant to this label.
Returns : | A pointer to the new key label, NULL if it wasn't created.

### gok_keylabel_delete ()

    void                gok_keylabel_delete                 (GokKeyLabel *pKeyLabel);

`pKeyLabel` : | Pointer to the key label that will be deleted.

### gok_key_set_cells ()

    void                gok_key_set_cells                   (GokKey *pKey,
                                                             gint top,
                                                             gint bottom,
                                                             gint left,
                                                             gint right);

Changes the cell coordinates (used by the editor).

`pKey` : | Key that gets it's cells changed.
`top` : | Top cell for the key.
`bottom` : | Bottom cell for the key.
`left` : | Left cell for the key.
`right` : | Right cell for the key.

### gok_key_duplicate ()

    GokKey*             gok_key_duplicate                   (GokKey *pKey);

Not implemented yet.

`pKey` : | Pointer to the key that gets duplicated
Returns : | A pointer to the duplicate key, NULL if it was not created.