## gok-scanner

gok-scanner

## Synopsis

    enum                CallIds;
    enum                RateType;
    #define             MAX_DESCRIPTION_TEXT
    #define             MAX_RATE_NAME
    #define             MAX_DISPLAY_RATE_NAME
    #define             COMPARE_NO
    #define             COMPARE_EQUAL
    #define             COMPARE_LESSTHAN
    #define             COMPARE_GREATERTHAN
    #define             COMPARE_EQUALORLESSTHAN
    #define             COMPARE_EQUALORGREATERTHAN
    gboolean            gok_scanner_initialize              (const gchar *directory,
                                                             const gchar *accessmethod,
                                                             const gchar *selectaction,
                                                             const gchar *scanaction);
    void                gok_scanner_close                   (void);
    void                gok_scanner_stop                    (void);
    void                gok_scanner_start                   (void);
    gboolean            gok_scanner_change_method           (gchar *NameAccessMethod);
    GokAccessMethod*    gok_scanner_create_access_method    (gchar *Name);
    void                gok_scanner_reset_access_method     (void);
    void                gok_scanner_change_state            (GokScannerState *pState,
                                                             gchar *NameAccessMethod);
    void                gok_scanner_next_state              (void);
    void                gok_scanner_set_handlers_null       (void);
    gboolean            gok_scanner_read_access_method      (gchar *Filename);
    GokScannerState*    gok_scanner_construct_state         (void);
    GokAccessMethodRate* gok_scanner_construct_rate         (void);
    GokScannerHandler*  gok_scanner_construct_handler       (gchar *pHandlerName);
    gboolean            gok_scanner_read_rates              (xmlNode *pNode,
                                                             GokAccessMethod *pAccessMethod);
    gboolean            gok_scanner_read_description        (xmlDoc *pDoc,
                                                             xmlNode *pNode,
                                                             GokAccessMethod *pAccessMethod);
    gboolean            gok_scanner_read_operation          (xmlDoc *pDoc,
                                                             xmlNode *pNode,
                                                             GokAccessMethod *pAccessMethod);
    void                gok_scanner_read_ui_loop            (GokControl *pControl,
                                                             xmlNode *pNode);
    gboolean            gok_scanner_read_feedback           (xmlDoc *pDoc,
                                                             xmlNode *pNode,
                                                             GokAccessMethod *pAccessMethod);
    gboolean            gok_scanner_read_options            (xmlDoc *pDoc,
                                                             xmlNode *pNode,
                                                             GokAccessMethod *pAccessMethod);
    void                gok_scanner_update_rates            (void);
    GokAccessMethod*    gok_scanner_get_current_access_method
                                                            (void);
    GokAccessMethod*    gok_scanner_get_first_access_method (void);
    GokScannerState*    gok_scanner_get_current_state       (void);
    void                gok_scanner_get_pointer_location    (gint *pX,
                                                             gint *pY);
    gint                gok_scanner_timer_set               (gint Rate,
                                                             gint ID);
    gint                gok_scanner_timer_stop              (gint TimerId);
    gint                gok_scanner_make_type_from_string   (gchar *pString);
    void                gok_scanner_timer_set_dwell_rate    (gint rate);
    void                gok_scanner_timer_start_dwell       (void);
    void                gok_scanner_timer_stop_dwell        (void);
    gboolean            gok_scanner_timer_on_dwell          (gpointer data);
    void                gok_scanner_left_button_down        (void);
    void                gok_scanner_left_button_up          (void);
    void                gok_scanner_right_button_down       (void);
    void                gok_scanner_right_button_up         (void);
    void                gok_scanner_middle_button_down      (void);
    void                gok_scanner_middle_button_up        (void);
    void                gok_scanner_mouse_movement          (gint x,
                                                             gint y);
    gboolean            gok_scanner_on_timer1               (gpointer data);
    gboolean            gok_scanner_on_timer2               (gpointer data);
    gboolean            gok_scanner_on_timer3               (gpointer data);
    gboolean            gok_scanner_on_timer4               (gpointer data);
    gboolean            gok_scanner_on_timer5               (gpointer data);
    void                gok_scanner_on_key_enter            (GokKey *pKey);
    void                gok_scanner_on_key_leave            (GokKey *pKey);
    void                gok_scanner_on_switch1_down         (void);
    void                gok_scanner_on_switch1_up           (void);
    void                gok_scanner_on_switch2_down         (void);
    void                gok_scanner_on_switch2_up           (void);
    void                gok_scanner_on_switch3_down         (void);
    void                gok_scanner_on_switch3_up           (void);
    void                gok_scanner_on_switch4_down         (void);
    void                gok_scanner_on_switch4_up           (void);
    void                gok_scanner_on_switch5_down         (void);
    void                gok_scanner_on_switch5_up           (void);

## Description

## Details

### enum CallIds

    typedef enum {
    CALL_CHUNKER_RESET,
    CALL_CHUNKER_CHUNK_NONE,
    CALL_CHUNKER_CHUNK_KEYS,
    CALL_CHUNKER_CHUNK_ROWS,
    CALL_CHUNKER_CHUNK_COLUMNS,
    CALL_CHUNKER_NEXT_CHUNK,
    CALL_CHUNKER_PREVIOUS_CHUNK,
    CALL_CHUNKER_NEXT_KEY,
    CALL_CHUNKER_PREVIOUS_KEY,
    CALL_CHUNKER_KEY_UP,
    CALL_CHUNKER_KEY_DOWN,
    CALL_CHUNKER_KEY_LEFT,
    CALL_CHUNKER_KEY_RIGHT,
    CALL_CHUNKER_KEY_HIGHLIGHT,
    CALL_CHUNKER_KEY_UNHIGHLIGHT,
    CALL_CHUNKER_WRAP_TOFIRST_CHUNK,
    CALL_CHUNKER_WRAP_TOLAST_CHUNK,
    CALL_CHUNKER_WRAP_TOFIRST_KEY,
    CALL_CHUNKER_WRAP_TOLAST_KEY,
    CALL_CHUNKER_WRAP_TOBOTTOM,
    CALL_CHUNKER_WRAP_TOTOP,
    CALL_CHUNKER_WRAP_TOLEFT,
    CALL_CHUNKER_WRAP_TORIGHT,
    CALL_CHUNKER_MOVE_LEFTRIGHT,
    CALL_CHUNKER_MOVE_TOPBOTTOM,
    CALL_CHUNKER_IF_NEXT_CHUNK,
    CALL_CHUNKER_IF_PREVIOUS_CHUNK,
    CALL_CHUNKER_IF_NEXT_KEY,
    CALL_CHUNKER_IF_PREVIOUS_KEY,
    CALL_CHUNKER_IF_TOP,
    CALL_CHUNKER_IF_BOTTOM,
    CALL_CHUNKER_IF_LEFT,
    CALL_CHUNKER_IF_RIGHT,
    CALL_CHUNKER_IF_KEY_SELECTED,
    CALL_CHUNKER_HIGHLIGHT_CENTER,
    CALL_CHUNKER_HIGHLIGHT_FIRST_CHUNK,
    CALL_CHUNKER_HIGHLIGHT_FIRST_KEY,
    CALL_CHUNKER_SELECT_CHUNK,
    CALL_CHUNKER_HIGHLIGHT_CHUNK,
    CALL_CHUNKER_UNHIGHLIGHT_ALL,

    CALL_SCANNER_REPEAT_ON,
    /* CALL_SCANNER_REPEAT_OFF,  use CALL_STATE_RESTART */

    CALL_TIMER1_SET,
    CALL_TIMER1_STOP,
    CALL_TIMER2_SET,
    CALL_TIMER2_STOP,
    CALL_TIMER3_SET,
    CALL_TIMER3_STOP,
    CALL_TIMER4_SET,
    CALL_TIMER4_STOP,
    CALL_TIMER5_SET,
    CALL_TIMER5_STOP,

    CALL_COUNTER_SET,
    CALL_COUNTER_INCREMENT,
    CALL_COUNTER_DECREMENT,
    CALL_COUNTER_GET,

    CALL_STATE_RESTART,
    CALL_STATE_NEXT,
    CALL_STATE_JUMP,

    CALL_OUTPUT_SELECTEDKEY,
    CALL_SET_SELECTEDKEY,

    CALL_FEEDBACK,

    CALL_GET_RATE
    } CallIds;

### enum RateType

    typedef enum {
    RATE_TYPE_UNDEFINED,
    RATE_TYPE_EFFECT
    } RateType;

### MAX_DESCRIPTION_TEXT

    #define MAX_DESCRIPTION_TEXT 200

### MAX_RATE_NAME

    #define MAX_RATE_NAME 20

### MAX_DISPLAY_RATE_NAME

    #define MAX_DISPLAY_RATE_NAME 30

### COMPARE_NO

    #define COMPARE_NO 0

### COMPARE_EQUAL

    #define COMPARE_EQUAL 1

### COMPARE_LESSTHAN

    #define COMPARE_LESSTHAN 2

### COMPARE_GREATERTHAN

    #define COMPARE_GREATERTHAN 3

### COMPARE_EQUALORLESSTHAN

    #define COMPARE_EQUALORLESSTHAN 4

### COMPARE_EQUALORGREATERTHAN

    #define COMPARE_EQUALORGREATERTHAN 5

### gok_scanner_initialize ()

    gboolean            gok_scanner_initialize              (const gchar *directory,
                                                             const gchar *accessmethod,
                                                             const gchar *selectaction,
                                                             const gchar *scanaction);

Reads all the access methods from the given directory and gets them ready to go.

`directory` : | The name of the directory to read the access method files from.
`accessmethod` : | If non-NULL, overrides access method name in gconf configuration data.
`selectaction` : | If non-NULL, overrides action associated with 'select' for the current access method in gconf configuration data.
`scanaction` : | If non-NULL, overrides access method associated with 'select' for the current access method in gconf configuration data.
Returns : | TRUE if the access methods were initialized, FALSE if not. Don't use the access methods if this fails.

### gok_scanner_close ()

    void                gok_scanner_close                   (void);

Stops the current access method and frees any memory allocated for the access methods. This must be called at the end of the program.

### gok_scanner_stop ()

    void                gok_scanner_stop                    (void);

Stops the current access method.

### gok_scanner_start ()

    void                gok_scanner_start                   (void);

Starts the current access method.

### gok_scanner_change_method ()

    gboolean            gok_scanner_change_method           (gchar *NameAccessMethod);

Changes the type of access method.

`NameAccessMethod` : | Name of the desired access method.
Returns : | TRUE if the access method was changed, FALSE if not.

### gok_scanner_create_access_method ()

    GokAccessMethod*    gok_scanner_create_access_method    (gchar *Name);

Creates a new access method structure and adds it to the list of access methods.

`Name` : | Name of the access method.
Returns : | A pointer to the new access method, NULL if if can't be created.

### gok_scanner_reset_access_method ()

    void                gok_scanner_reset_access_method     (void);

Resets the current access method so it's ready for use.

### gok_scanner_change_state ()

    void                gok_scanner_change_state            (GokScannerState *pState,
                                                             gchar *NameAccessMethod);

Maps event handlers to effects..

`pState` : | Pointer to the new state.
`NameAccessMethod` : | Name of the access method that contains the state.

### gok_scanner_next_state ()

    void                gok_scanner_next_state              (void);

### gok_scanner_set_handlers_null ()

    void                gok_scanner_set_handlers_null       (void);

Sets all the event handlers to NULL.

### gok_scanner_read_access_method ()

    gboolean            gok_scanner_read_access_method      (gchar *Filename);

Read an access method file from disk and create a new access method. The new access method is added to the list of access methods.

`Filename` : | Name of the access method file.
Returns : | TRUE if the acces method was created, FALSE if not.

### gok_scanner_construct_state ()

    GokScannerState*    gok_scanner_construct_state         (void);

Creates a new handler state.

Returns : | A pointer to the new state, NULL if it was not created.

### gok_scanner_construct_rate ()

    GokAccessMethodRate* gok_scanner_construct_rate         (void);

Creates a new access method rate.

Returns : | A pointer to the new rate, NULL if it was not created.

### gok_scanner_construct_handler ()

    GokScannerHandler*  gok_scanner_construct_handler       (gchar *pHandlerName);

Creates a new access method handler.

`pHandlerName` : | Name of the handler.
Returns : | A pointer to the new handler, NULL if it was not created.

### gok_scanner_read_rates ()

    gboolean            gok_scanner_read_rates              (xmlNode *pNode,
                                                             GokAccessMethod *pAccessMethod);

Reads the rates for the given access method and add them to the list of rates stored on the access method.

`pNode` : | Pointer to the XML node that contains the first rate.
`pAccessMethod` : | Pointer to the access method that is associated with the rates.
Returns : | TRUE if the rates were read, FALSE if there were 1 or more errors reading the rates.

### gok_scanner_read_description ()

    gboolean            gok_scanner_read_description        (xmlDoc *pDoc,
                                                             xmlNode *pNode,
                                                             GokAccessMethod *pAccessMethod);

Reads the description of the access method and stores it on the structure.

`pDoc` : | Pointer to the XML document that contains the node.
`pNode` : | Pointer to the XML root node.
`pAccessMethod` : | Pointer to the access method that is associated with the description.
Returns : | TRUE if the description was read, FALSE if not.

### gok_scanner_read_operation ()

    gboolean            gok_scanner_read_operation          (xmlDoc *pDoc,
                                                             xmlNode *pNode,
                                                             GokAccessMethod *pAccessMethod);

Reads the UI 'operation' of the access method and stores it on the structure.

`pDoc` : | Pointer to the XML document that contains the node.
`pNode` : | Pointer to the XML root node.
`pAccessMethod` : | Pointer to the access method that is associated with the operation.
Returns : | TRUE if the operation was read, FALSE if not.

### gok_scanner_read_ui_loop ()

    void                gok_scanner_read_ui_loop            (GokControl *pControl,
                                                             xmlNode *pNode);

Reads the UI 'operation' of the access method and stores it on the structure.

`pControl` : | Pointer to the parent control that will contain any new controls found in the node.
`pNode` : | Pointer to the XML root node.

### gok_scanner_read_feedback ()

    gboolean            gok_scanner_read_feedback           (xmlDoc *pDoc,
                                                             xmlNode *pNode,
                                                             GokAccessMethod *pAccessMethod);

Reads the UI 'feedback' of the access method and stores it on the structure.

`pDoc` : | Pointer to the XML doc that contains the feedbacks.
`pNode` : | Pointer to the XML root node.
`pAccessMethod` : | Pointer to the access method that is associated with the feedback.
Returns : | TRUE if the feedback was read, FALSE if not.

### gok_scanner_read_options ()

    gboolean            gok_scanner_read_options            (xmlDoc *pDoc,
                                                             xmlNode *pNode,
                                                             GokAccessMethod *pAccessMethod);

Reads the UI 'options' of the access method and stores it on the structure.

`pDoc` : | Pointer to the XML document that contains the node.
`pNode` : | Pointer to the XML root node.
`pAccessMethod` : | Pointer to the access method that is associated with the options.
Returns : | TRUE if the options were read, FALSE if not.

### gok_scanner_update_rates ()

    void                gok_scanner_update_rates            (void);

Updates all the rates in all access methods from the GokData.

### gok_scanner_get_current_access_method ()

    GokAccessMethod*    gok_scanner_get_current_access_method
                                                            (void);

Accessor function to get the current access method.

Returns : | A pointer to the current access method.

### gok_scanner_get_first_access_method ()

    GokAccessMethod*    gok_scanner_get_first_access_method (void);

Returns : |

### gok_scanner_get_current_state ()

    GokScannerState*    gok_scanner_get_current_state       (void);

Accessor function to get the current handler state.

Returns : | A pointer to the current handler state.

### gok_scanner_get_pointer_location ()

    void                gok_scanner_get_pointer_location    (gint *pX,
                                                             gint *pY);

Gets the current location of the mouse pointer.

`pX` : | Pointer to the integer that receives the mouse pointer X coordinate.
`pY` : | Pointer to the integer that receives the mouse pointer Y coordinate.

### gok_scanner_timer_set ()

    gint                gok_scanner_timer_set               (gint Rate,
                                                             gint ID);

Starts a timer.

`Rate` : | Time in 100s of a second.
`ID` : | Timer identifier
Returns : | Always 0.

### gok_scanner_timer_stop ()

    gint                gok_scanner_timer_stop              (gint TimerId);

Stops a timer.

`TimerId` : | Id of the timer that will be stopped.
Returns : | Always 0.

### gok_scanner_make_type_from_string ()

    gint                gok_scanner_make_type_from_string   (gchar *pString);

`pString` : | Pointer to the string that describes one or more effect types.
Returns : | An int that describes all the effect types in the string.

### gok_scanner_timer_set_dwell_rate ()

    void                gok_scanner_timer_set_dwell_rate    (gint rate);

Sets the dwell rate.

`rate` : | Dwell rate in 100s of a second.

### gok_scanner_timer_start_dwell ()

    void                gok_scanner_timer_start_dwell       (void);

Starts the dwell timer.

### gok_scanner_timer_stop_dwell ()

    void                gok_scanner_timer_stop_dwell        (void);

Stops the dwell timer

### gok_scanner_timer_on_dwell ()

    gboolean            gok_scanner_timer_on_dwell          (gpointer data);

This will be called when the dwell timer counts down.

`data` : | Passed from the event. Ignored.
Returns : | Always FALSE.

### gok_scanner_left_button_down ()

    void                gok_scanner_left_button_down        (void);

Handler for the left mouse button down event.

### gok_scanner_left_button_up ()

    void                gok_scanner_left_button_up          (void);

Handler for the left mouse button up event.

### gok_scanner_right_button_down ()

    void                gok_scanner_right_button_down       (void);

Handler for the right mouse button down event.

### gok_scanner_right_button_up ()

    void                gok_scanner_right_button_up         (void);

Handler for the right mouse button up event.

### gok_scanner_middle_button_down ()

    void                gok_scanner_middle_button_down      (void);

Handler for the middle mouse button down event.

### gok_scanner_middle_button_up ()

    void                gok_scanner_middle_button_up        (void);

Handler for the mouse middle button up event.

### gok_scanner_mouse_movement ()

    void                gok_scanner_mouse_movement          (gint x,
                                                             gint y);

Handler for the mouse movement event. Stores the location of the mouse pointer.

`x` : | Horizontal location of the mouse pointer.
`y` : | Vertical location of the mouse pointer.

### gok_scanner_on_timer1 ()

    gboolean            gok_scanner_on_timer1               (gpointer data);

Handler for the timer1 event (timer 1 has counted down).

`data` : | Pointer to the user data associated with the timer.
Returns : | FALSE always.

### gok_scanner_on_timer2 ()

    gboolean            gok_scanner_on_timer2               (gpointer data);

Handler for the timer2 event (timer 2 has counted down).

`data` : | Pointer to the user data associated with the timer.
Returns : | FALSE always.

### gok_scanner_on_timer3 ()

    gboolean            gok_scanner_on_timer3               (gpointer data);

Handler for the timer3 event (timer 3 has counted down).

`data` : | Pointer to the user data associated with the timer.
Returns : | FALSE always.

### gok_scanner_on_timer4 ()

    gboolean            gok_scanner_on_timer4               (gpointer data);

Handler for the timer4 event (timer 4 has counted down).

`data` : | Pointer to the user data associated with the timer.
Returns : | FALSE always.

### gok_scanner_on_timer5 ()

    gboolean            gok_scanner_on_timer5               (gpointer data);

Handler for the timer5 event (timer 5 has counted down).

`data` : | Pointer to the user data associated with the timer.
Returns : | FALSE always.

### gok_scanner_on_key_enter ()

    void                gok_scanner_on_key_enter            (GokKey *pKey);

Handler for the key enter notify.

`pKey` : | Pointer to the key that the mouse pointer has entered.

### gok_scanner_on_key_leave ()

    void                gok_scanner_on_key_leave            (GokKey *pKey);

Handler for the key leave notify.

`pKey` : | Pointer to the key that the mouse pointer has left.

### gok_scanner_on_switch1_down ()

    void                gok_scanner_on_switch1_down         (void);

Handler for the switch 1 down event.

### gok_scanner_on_switch1_up ()

    void                gok_scanner_on_switch1_up           (void);

Handler for the switch 1 up event.

### gok_scanner_on_switch2_down ()

    void                gok_scanner_on_switch2_down         (void);

Handler for the switch 2 down event.

### gok_scanner_on_switch2_up ()

    void                gok_scanner_on_switch2_up           (void);

Handler for the switch 2 up event.

### gok_scanner_on_switch3_down ()

    void                gok_scanner_on_switch3_down         (void);

Handler for the switch 3 down event.

### gok_scanner_on_switch3_up ()

    void                gok_scanner_on_switch3_up           (void);

Handler for the switch 3 up event.

### gok_scanner_on_switch4_down ()

    void                gok_scanner_on_switch4_down         (void);

Handler for the switch 4 down event.

### gok_scanner_on_switch4_up ()

    void                gok_scanner_on_switch4_up           (void);

Handler for the switch 4 up event.

### gok_scanner_on_switch5_down ()

    void                gok_scanner_on_switch5_down         (void);

Handler for the switch 5 down event.

### gok_scanner_on_switch5_up ()

    void                gok_scanner_on_switch5_up           (void);

Handler for the switch 5 up event.