main

## main main |

## Synopsis

    GtkWidget *         gok_main_create_window              (struct gok_window_realize_data *window_realize_data);
    gboolean            gok_main_display_scan               (GokKeyboard *pKeyboard,
                                                             gchar *nameKeyboard,
                                                             KeyboardTypes typeKeyboard,
                                                             KeyboardLayouts layout,
                                                             KeyboardShape shape);
    gboolean            gok_main_display_scan_previous      (void);
    gboolean            gok_main_display_scan_previous_premade
                                                            (void);
    gboolean            gok_main_display_scan_reset         (void);
    gboolean            gok_main_ds                         (GokKeyboard *pKeyboard);
    GokKeyboard *       gok_main_get_first_keyboard         (void);
    void                gok_main_set_first_keyboard         (GokKeyboard *pKeyboard);
    GokKeyboard *       gok_main_get_current_keyboard       (void);
    GtkWidget *         gok_main_get_main_window            (void);
    Accessible *        gok_main_get_foreground_accessible  (void);
    void                gok_main_resize_window              (GtkWidget *pWindow,
                                                             GokKeyboard *pKeyboard,
                                                             gint Width,
                                                             gint Height);
    void                gok_main_store_window_center        (void);
    Accessible *        gok_main_get_foreground_window_accessible
                                                            (void);
    void                gok_main_read_keyboards             (void);
    GokKeyboard *       gok_main_read_keyboards_from_dir    (const char *directory,
                                                             GokKeyboard *first);
    void                gok_main_on_window_position_change  (void);
    void                gok_main_get_our_window_size        (gint *pWidth,
                                                             gint *pHeight);
    void                gok_main_close                      (void);
    void                gok_main_display_error              (const gchar *error,
                                                             const gchar *detail);
    void                gok_main_display_gconf_error        (void);
    void                gok_main_app_change_listener        (Accessible *pAccessible);
    void                gok_main_window_change_listener     (Accessible *pAccessible);
    void                gok_main_mouse_button_listener      (gint button,
                                                             gint state,
                                                             long mods Param3,
                                                             long timestamp Param4);

## Description

## Details

### gok_main_create_window ()

    GtkWidget *         gok_main_create_window              (struct gok_window_realize_data *window_realize_data);

Creates the window that holds the keyboards.

`window_realize_data` : |
Returns : | A pointer to the window, NULL if it couldn't be created.

### gok_main_display_scan ()

    gboolean            gok_main_display_scan               (GokKeyboard *pKeyboard,
                                                             gchar *nameKeyboard,
                                                             KeyboardTypes typeKeyboard,
                                                             KeyboardLayouts layout,
                                                             KeyboardShape shape);

Display a keyboard and allow the user to make selections from it. The keyboard must have already been created and in the list of keyboards. The keyboard is specified by name and keyboard type. A name of NULL means the first keyboard in the list. The previous keyboard is stored on the "branch back stack".

`pKeyboard` : | If this is supplied it takes precedence over the name parameter (useful for dynamic keyboards with the same name)
`nameKeyboard` : | Name of the keyboard you want displayed (must be in the list of keyboards.) # `typeKeyboard`: Can be used to describe a runtime keyboard type (e.g. a Menus keyboard)
`typeKeyboard` : |
`layout` : | Can be used to specify a particular type of keyboard (Example: center-weighted or upper-left-weighted).
`shape` : | Can be used to specify a particular shape of keyboard (Example: square).
Returns : | TRUE if keyboard is displayed, FALSE if not.

### gok_main_display_scan_previous ()

    gboolean            gok_main_display_scan_previous      (void);

Display and scan the previous keyboard (pulled from the branch-back-stack). Don't push the current keyboard on the branch-back-stack.

Returns : | TRUE if the previous keyboard was displayed, FALSE if not.

### gok_main_display_scan_previous_premade ()

    gboolean            gok_main_display_scan_previous_premade
                                                            (void);

Display and scan the first keyboard pulled from the branch-back-stack that is premade. Delete any dynamic keyboards that are on the stack 'along the way'. Don't push the current keyboard on the branch-back-stack.

Returns : | TRUE if the previous keyboard was displayed, FALSE if not.

### gok_main_display_scan_reset ()

    gboolean            gok_main_display_scan_reset         (void);

Display and scan the current keyboard. This should be called after the user settings have been changed.

Returns : | TRUE if the keyboard was displayed, FALSE if not.

### gok_main_ds ()

    gboolean            gok_main_ds                         (GokKeyboard *pKeyboard);

Does the actual work of displaying and scanning the keyboard.

`pKeyboard` : | Pointer to the keyboard that will be displayed and scanned.
Returns : | TRUE if the keyboard was displayed, FALSE if not.

### gok_main_get_first_keyboard ()

    GokKeyboard *       gok_main_get_first_keyboard         (void);

Accessor function.

Returns : | A pointer to the first keyboard in the list of keyboards.

### gok_main_set_first_keyboard ()

    void                gok_main_set_first_keyboard         (GokKeyboard *pKeyboard);

Sets the first keyboard in the list of keyboards.

`pKeyboard` : | Pointer to the keyboard that will be set as the first keyboard.

### gok_main_get_current_keyboard ()

    GokKeyboard *       gok_main_get_current_keyboard       (void);

Accessor function.

Returns : | A pointer to the keyboard that is currently displayed.

### gok_main_get_main_window ()

    GtkWidget *         gok_main_get_main_window            (void);

Accessor function.

Returns : | A pointer to main GOK window.

### gok_main_get_foreground_accessible ()

    Accessible *        gok_main_get_foreground_accessible  (void);

Returns : |

### gok_main_resize_window ()

    void                gok_main_resize_window              (GtkWidget *pWindow,
                                                             GokKeyboard *pKeyboard,
                                                             gint Width,
                                                             gint Height);

Resizes the main window to the given width and height. The main window is centered over the the center location in gok_data The new window will not be resized so it appears off screen. When the new window is resized it generates 2 calls (configure events)to gok_main_store_window_center. If the new window is not centered over the old window then m_countIgnoreConfigure will be set to 2 so that the window center is not changed.

`pWindow` : | Pointer to the main window.
`pKeyboard` : | Pointer to the relevant (pending) keyboard (may be NULL).
`Width` : | Width of the new window.
`Height` : | Height of the new window.

### gok_main_store_window_center ()

    void                gok_main_store_window_center        (void);

Stores in gok_data the center location of the current keyboard.

### gok_main_get_foreground_window_accessible ()

    Accessible *        gok_main_get_foreground_window_accessible
                                                            (void);

Accessor function.

Returns : | A pointer to foreground window's accessible interface.

### gok_main_read_keyboards ()

    void                gok_main_read_keyboards             (void);

Retrieves the name of the directory containing keyboards from GConf. Then loads the keyboards in that directory using gok_main_read_keyboards_from_dir.

### gok_main_read_keyboards_from_dir ()

    GokKeyboard *       gok_main_read_keyboards_from_dir    (const char *directory,
                                                             GokKeyboard *first);

Reads all the keyboard files from the given directory or a subdirectory that is a closer match based on user's language if it exists.

`directory` : | The name of the keyboard root directory location.
`first` : |
Returns : | A pointer to the first keyboard, NULL if no keyboards could be read.

### gok_main_on_window_position_change ()

    void                gok_main_on_window_position_change  (void);

### gok_main_get_our_window_size ()

    void                gok_main_get_our_window_size        (gint *pWidth,
                                                             gint *pHeight);

Retreives the width and height that we last resized the window to.

`pWidth` : | Pointer to a variable that will hold the window width.
`pHeight` : | Pointer to a variable that will hold the window height.

### gok_main_close ()

    void                gok_main_close                      (void);

Delete any keyboards that were created. This must be called at the end of the program.

### gok_main_display_error ()

    void                gok_main_display_error              (const gchar *error,
                                                             const gchar *detail);

Displays an error dialog.

`error` : |
`detail` : | Error details

### gok_main_display_gconf_error ()

    void                gok_main_display_gconf_error        (void);

Displays a gconf error message.

### gok_main_app_change_listener ()

    void                gok_main_app_change_listener        (Accessible *pAccessible);

`pAccessible` : |

### gok_main_window_change_listener ()

    void                gok_main_window_change_listener     (Accessible *pAccessible);

This function is called each time the foreground window changes.

`pAccessible` : | Pointer to the foreground window's accessible interface.

### gok_main_mouse_button_listener ()

    void                gok_main_mouse_button_listener      (gint button,
                                                             gint state,
                                                             long mods Param3,
                                                             long timestamp Param4);

This handler is called each time there is a mouse button event.

`button` : | Mouse button number that has changed state.
`state` : | State of the button.
`Param3` : |
`Param4` : |