How to extend Hildon Input Methods

The interface

As we were already mentioning the plugin shall handle all the inputs - both real user input and management signals from the system - that are coming to the HIM main UI, so first let's take a look what functions need to be implemented and provided by the plugin to the Hildon Input Method Plugin Interface. Later on in the we will show how we actually register these functions for the HIM Plugin Interface.

The essential functions that shall be implemented by a basic plugin:

• 
  void (*enable) (HildonIMPlugin *plugin, gboolean init);
  
  

  enable is called whenever the plugin becomes available to the user. init holds TRUE whenever this is the initialization time.

  
  /* Called when the plugin is available to the user */
  static void
  enable (HildonIMPlugin *plugin, gboolean init)
  {
    HimsdkVKBPrivate *priv;
    HimsdkVKB *vkb;
  
    vkb = HIMSDK_VKB (plugin);
    priv = HIMSDK_VKB_GET_PRIVATE (vkb);
    if (init == TRUE) 
    {
      hildon_im_keyboard_button_set_toggle (priv->keyboard, 
        BUTTON_MODE_A, TRUE);
      hildon_im_keyboard_button_set_toggle (priv->keyboard, 
        BUTTON_MODE_B, TRUE);
      hildon_im_keyboard_button_set_label (priv->keyboard, 
        BUTTON_MODE_A, "ABC");
      hildon_im_keyboard_button_set_label (priv->keyboard, 
        BUTTON_MODE_B, "Shift");
    }
  }
  
  

• 
  void (*disable) (HildonIMPlugin *plugin)
  
  

  disable is called whenever the plugin become unavailable to the user (e.g. when the main UI is closed).

  
  /* Called when the plugin is 'disappear' */
  static void
  disable(HildonIMPlugin *plugin)
  {
    /* empty, sic. */
  }
         
  

• 
  void (*settings_changed) (HildonIMPlugin *plugin, const gchar *key, const GConfValue *value);
  
  

  settings_changed is called whenever the HIM main UI receive a notification from GConf whenever Hildon Input Method settings are changed. The affected settings are all settings which resides in /apps/osso/inputmethod path. key and value hold the GConf key and it's value respectively.

  
  /* Called when the standard input method settings 
   * has been changed */
  
  static void
  settings_changed (HildonIMPlugin *plugin,
      const gchar *key, const GConfValue *value)
  {
    /* empty, sic. */
  }
         
  

• 
  void (*input_mode_changed) (HildonIMPlugin *plugin);
  
  

  input_mode_changed is called whenever the input mode is changed. Input mode is changed to what has been specified by the client widget. The input mode put constraints to the plugin to limit what input shall be accepted or ignored.

  
  /* Called when input mode changed */
  
  static void
  input_mode_changed (HildonIMPlugin *plugin)
  {
    /* empty, sic. */
  }
         
  

• 
  void (*character_autocase) (HildonIMPlugin *plugin);
  
  

  character_autocase is called whenever the UI need to check whether auto-capitalization is in effect. The plugin is responsible to activate the auto-capitalization in this function if necessary. Auto-capitalization setting can be obtained from the HIM main UI (which basically means querying the GConf itself). Note that this function is frequently called so auto-capitalization setting shall be cached in order to reduce unecessary traffic to GConf.

• 
  void (*clear) (HildonIMPlugin *plugin);
  
  

  clear is called whenever the HIM main UI requests the plugin to clear or refresh it's user interface.

  
  /* Called when the plugin is requested to 'clear'/refresh it's UI */
  
  static void
  clear(HildonIMPlugin *plugin)
  {
    /* empty, sic. */
  }
         
  

• 
  void (*client_widget_changed) (HildonIMPlugin *plugin);
  
  

  client_widget_changed is called whenever the client widget is changed from one to another. For instance a case could be that the user taps to another text entry.

  
  /* Called when the client widget changed */
  
  static void
  client_widget_changed (HildonIMPlugin *plugin)
  {
    /* empty, sic. */
  }
         
  

• 
  void (*save_data) (HildonIMPlugin *plugin);
  
  

  save_data is called whenever the HIM main UI is requested to save it's (and the plugins') data. Usually it is called when the main UI is requested to quit.

  
  /* Called when the plugin is requested to save it's data */
  
  static void
  save_data(HildonIMPlugin *plugin)
  {
    /* empty, sic. */
  }
         
  

• 
  void (*mode_a) (HildonIMPlugin *plugin);
  
  

  mode_a is called whenever the Mode A (Caps Lock in Virtual Keyboard plugin) is pressed.

  
  /* Called when the MODE_A button is pressed */
  
  static void
  mode_a(HildonIMPlugin *plugin)
  {
    HimsdkVKBPrivate *priv;
    HimsdkVKB *vkb;
  
    vkb = HIMSDK_VKB (plugin);
  
    priv = HIMSDK_VKB_GET_PRIVATE (vkb);
    if (hildon_im_keyboard_button_get_active (priv->keyboard,
          BUTTON_MODE_B)) {
      hildon_im_keyboard_button_set_active (priv->keyboard,
          BUTTON_MODE_B, FALSE);
      if (hildon_im_keyboard_button_get_active (priv->keyboard,
          BUTTON_MODE_A)) {
        priv->case_mode = CASE_UPPER;
      } else {
        priv->case_mode = CASE_LOWER;
      }
    } else {
      if (hildon_im_keyboard_button_get_active (priv->keyboard,
          BUTTON_MODE_A)) {
        priv->case_mode = CASE_UPPER;
      } else {
        priv->case_mode = CASE_LOWER;
      }
    }
    update_layout (vkb);
  }
         
  

• 
  void (*mode_b) (HildonIMPlugin *plugin);
  
  

  mode_b is called whenever the Mode B (Shift in Virtual Keyboard plugin) is pressed.

  
  /* Called when the MODE_B button is pressed */
  
  static void
  mode_b(HildonIMPlugin *plugin)
  {
    HimsdkVKBPrivate *priv;
    HimsdkVKB *vkb;
  
    vkb = HIMSDK_VKB (plugin);
  
    priv = HIMSDK_VKB_GET_PRIVATE (vkb);
  
    if (hildon_im_keyboard_button_get_active (priv->keyboard,
          BUTTON_MODE_B)) {
      if (hildon_im_keyboard_button_get_active (priv->keyboard,
          BUTTON_MODE_A)) {
        priv->case_mode = CASE_LOWER;
      } else {
        priv->case_mode = CASE_UPPER;
      }
    } else {
      if (hildon_im_keyboard_button_get_active (priv->keyboard,
          BUTTON_MODE_A)) {
        priv->case_mode = CASE_UPPER;
      } else {
        priv->case_mode = CASE_LOWER;
      }
    }
  
    update_layout (vkb);
  }
  
  

• 
  void (*backspace) (HildonIMPlugin *plugin);
  
  

  backspace is called whenever the virtual backspace key is pressed.

  
  /* Called when the backspace button is pressed */
  
  static void
  backspace (HildonIMPlugin *plugin)
  {
    HimsdkVKBPrivate *priv;
  
    priv = HIMSDK_VKB_GET_PRIVATE (HIMSDK_VKB (plugin));
    hildon_im_keyboard_send_communication_message (priv->keyboard, 
        HILDON_IM_CONTEXT_HANDLE_BACKSPACE);
  }
         
  

• 
  void (*enter) (HildonIMPlugin *plugin);
  
  

  enter is called whenever the virtual enter key is pressed.

  
  /* Called when the enter button is pressed */
  
  static void
  enter (HildonIMPlugin *plugin)
  {
    HimsdkVKBPrivate *priv;
  
    priv = HIMSDK_VKB_GET_PRIVATE (HIMSDK_VKB (plugin));
    hildon_im_keyboard_send_communication_message (priv->keyboard, 
        HILDON_IM_CONTEXT_HANDLE_ENTER);
  }
         
  

• 
  void (*tab) (HildonIMPlugin *plugin);
  
  

  tab is called whenever the virtual tab key is pressed.

  
  /* Called when the tab button is pressed */
  
  static void
  tab (HildonIMPlugin *plugin)
  {
    HimsdkVKBPrivate *priv;
  
    priv = HIMSDK_VKB_GET_PRIVATE (HIMSDK_VKB (plugin));
    hildon_im_keyboard_send_communication_message (priv->keyboard, 
        HILDON_IM_CONTEXT_HANDLE_TAB);
  }
         
  

• 
  void (*fullscreen) (HildonIMPlugin *plugin, gboolean fullscreen);
  
  

  fullscreen is called whenever the application, to which the client widget attached is changed from or to fullscreen. fullscreen argument holds TRUE if the application changes from normal to fullscreen, and vice versa.

Couple of flavoring functions:

• 
  void (*language) (HildonIMPlugin *plugin);
  
  

  language is called whenever a new language is selected from the HIM main UI menu.

  
  /* Called when the language has been changed */
  
  static void
  language (HildonIMPlugin *plugin)
  {
    /* Do nothing, sic. */
    return;
  }
         
  

• 
  void (*language_settings_changed) (HildonIMPlugin *plugin, gint index, gint value);
  
  

  language_settings_changed is called whenever the language settings has been changed. The changed language can be obtained from the arguments.

  index contains:

  • 0: primary languange
  • 1: secondary language

  value is the language code.

  
  /* Called when the language settings has been changed */
  
  static void
  language_settings_changed (HildonIMPlugin *plugin,
      gint index, gint value)
  {
    /* empty, sic. */
  }
         
  

• 
  void (*completion_language_changed) (HildonIMPlugin *plugin);
  
  

  completion_language_changed is called whenever the word completion settings has been changed. For further information check GConf directly to get the new settings of word completion.

Handling input

void hildon_im_keyboard_send_utf8(HildonIMKeyboard *main_ui, const gchar *text);

The plugin can request the main UI to commit a UTF-8 encoded text by calling this function.

void hildon_im_keyboard_send_communication_message(HildonIMKeyboard *main_ui, gint message);

The plugin can use this function to tell the main UI that Enter, Backspace, or Tab virtual buttons are pressed. Simply call this function and pass one of the constants below as the message argument:

• HILDON_IM_CONTEXT_HANDLE_ENTER
• HILDON_IM_CONTEXT_HANDLE_BACKSPACE
• HILDON_IM_CONTEXT_HANDLE_TAB