scim::IMEngineInstanceBase Class Referenceabstract
IMEngine

The base class of the real input methods' IMEngineInstance classes. More...

`#include <scim_imengine.h>`

## Public Member Functions

| IMEngineInstanceBase (IMEngineFactoryBase *factory, const String &encoding, int id=-1)
| Constructor.
virtual | ~IMEngineInstanceBase ()
| Virtual destructor.
virtual bool | set_encoding (const String &encoding)
| Set the working encoding for this instance.
String | get_encoding () const
| Get the working encoding of this instance.
int | get_id () const
| Get the unique id of this instance.
String | get_factory_uuid () const
| Get the UUID of the engine factory.
void | set_frontend_data (void *data)
| Attach a pointer to this IMEngineInstance, which is pointed to corresponding FrontEnd data.
void * | get_frontend_data (void)
| Retrieve the pointer previously attached by set_frontend_data();.
Signal connection functions.
These functions are used by FrontEnds to connect their corresponding slots to this IMEngineInstance's signals.
Connection | signal_connect_show_preedit_string (IMEngineSlotVoid *slot)
Connection | signal_connect_show_aux_string (IMEngineSlotVoid *slot)
Connection | signal_connect_show_lookup_table (IMEngineSlotVoid *slot)
Connection | signal_connect_hide_preedit_string (IMEngineSlotVoid *slot)
Connection | signal_connect_hide_aux_string (IMEngineSlotVoid *slot)
Connection | signal_connect_hide_lookup_table (IMEngineSlotVoid *slot)
Connection | signal_connect_update_preedit_caret (IMEngineSlotInt *slot)
Connection | signal_connect_update_preedit_string (IMEngineSlotWideStringAttributeList *slot)
Connection | signal_connect_update_aux_string (IMEngineSlotWideStringAttributeList *slot)
Connection | signal_connect_update_lookup_table (IMEngineSlotLookupTable *slot)
Connection | signal_connect_commit_string (IMEngineSlotWideString *slot)
Connection | signal_connect_forward_key_event (IMEngineSlotKeyEvent *slot)
Connection | signal_connect_register_properties (IMEngineSlotPropertyList *slot)
Connection | signal_connect_update_property (IMEngineSlotProperty *slot)
Connection | signal_connect_beep (IMEngineSlotVoid *slot)
Connection | signal_connect_start_helper (IMEngineSlotString *slot)
Connection | signal_connect_stop_helper (IMEngineSlotString *slot)
Connection | signal_connect_send_helper_event (IMEngineSlotStringTransaction *slot)
Connection | signal_connect_get_surrounding_text (IMEngineSlotGetSurroundingText *slot)
Connection | signal_connect_delete_surrounding_text (IMEngineSlotDeleteSurroundingText *slot)
Action functions.
These functions will be called by FrontEnds to send events to this IMEngineInstance.
virtual bool | process_key_event (const KeyEvent &key)=0
| Process a key event.
virtual void | move_preedit_caret (unsigned int pos)
| Move the preedit caret in the preedit string.
virtual void | select_candidate (unsigned int index)
| Select a candidate in current lookup table.
virtual void | update_lookup_table_page_size (unsigned int page_size)
| Update the page size of current lookup table.
virtual void | lookup_table_page_up ()
| Flip the lookup table to the previous page.
virtual void | lookup_table_page_down ()
| Flip the lookup table to the next page.
virtual void | reset ()
| Reset this engine instance.
virtual void | focus_in ()
| Focus in this engine instance.
virtual void | focus_out ()
| Focus out this engine instance.
virtual void | trigger_property (const String &property)
| Trigger a property.
virtual void | process_helper_event (const String &helper_uuid, const Transaction &trans)
| Process the events sent from a Client Helper process.
virtual void | update_client_capabilities (unsigned int cap)
| Update the capabilities of current client application which is attached to this IMEngineInstance.
Public Member Functions inherited from scim::ReferencedObject
bool | is_referenced () const
void | ref ()
| Increase an object's reference count by one.
void | unref ()

## Protected Member Functions

Signal activation functions
These functions should be called by derived classes to fire the corresponding signals. The FrontEnd connected to those signals will receive and process them.
void | show_preedit_string ()
| Show the preedit string area.
void | show_aux_string ()
| Show the aux string area.
void | show_lookup_table ()
| Show the lookup table area.
void | hide_preedit_string ()
| Hide the preedit string area.
void | hide_aux_string ()
| Hide the aux string area.
void | hide_lookup_table ()
| Hide the lookup table area.
void | update_preedit_caret (int caret)
| Update the preedit caret position in the preedit string.
void | update_preedit_string (const WideString &str, const AttributeList &attrs=AttributeList())
| Update the content of the preedit string,.
void | update_aux_string (const WideString &str, const AttributeList &attrs=AttributeList())
| Update the content of the aux string,.
void | update_lookup_table (const LookupTable &table)
| Update the content of the lookup table,.
void | commit_string (const WideString &str)
| Commit a string to the client application.
void | forward_key_event (const KeyEvent &key)
| Forward a key event to the client application.
void | register_properties (const PropertyList &properties)
| Register all properties of this IMEngineInstance into the FrontEnd.
void | update_property (const Property &property)
| Update a registered property.
void | beep ()
| Generate a short beep.
void | start_helper (const String &helper_uuid)
| Start a Client Helper process.
void | stop_helper (const String &helper_uuid)
| Stop a Client Helper process which was started by start_helper.
void | send_helper_event (const String &helper_uuid, const Transaction &trans)
| Send an events transaction to a client helper process.
bool | get_surrounding_text (WideString &text, int &cursor, int maxlen_before=-1, int maxlen_after=-1)
| Retrieves context around the insertion point.
bool | delete_surrounding_text (int offset, int len)
| Ask the client to delete characters around the cursor position.
Protected Member Functions inherited from scim::ReferencedObject
| ReferencedObject ()
| Constructor.
virtual | ~ReferencedObject ()=0
| Destructor.
void | set_referenced (bool reference)

## Detailed Description

The base class of the real input methods' IMEngineInstance classes.

Each input method should implement a class derived from scim::IMEngineInstanceBase, which takes charge of recording Input Context status and processing user input events.

## Constructor & Destructor Documentation

## IMEngineInstanceBase()

scim::IMEngineInstanceBase::IMEngineInstanceBase | ( | IMEngineFactoryBase * | factory,
|  | const String & | encoding,
|  | int | id = -1 )

Constructor.

Parameters

  factory | - the factory which creates this instance.
  encoding | - the working encoding.
  id | - the unique id of this instance.

## ~IMEngineInstanceBase()

virtual scim::IMEngineInstanceBase::~IMEngineInstanceBase | ( |  | ) |

virtual

Virtual destructor.

## Member Function Documentation

## set_encoding()

virtual bool scim::IMEngineInstanceBase::set_encoding | ( | const String & | encoding | ) |

virtual

Set the working encoding for this instance.

One engine instance can only support one client encoding at the same time. This encoding must be supported by the IMEngineFactory as well.

This method could be overrided in derived class to do some extra job. But the method of this base class must be invoked within the new method.

After invoking this method, reset() should be invoked to let the new encoding take effect.

Returns
  true if the encoding is supported, otherwise false.

Reimplemented in scim::FilterInstanceBase.

## get_encoding()

String scim::IMEngineInstanceBase::get_encoding | ( |  | ) | const

Get the working encoding of this instance.

This method returns the encoding passed to the constructor when constructing this object.

Returns
  The working encoding.

## get_id()

int scim::IMEngineInstanceBase::get_id | ( |  | ) | const

Get the unique id of this instance.

Returns
  The id of this instance.

## get_factory_uuid()

String scim::IMEngineInstanceBase::get_factory_uuid | ( |  | ) | const

Get the UUID of the engine factory.

Returns
  The UUID string of the engine factory.

## set_frontend_data()

void scim::IMEngineInstanceBase::set_frontend_data | ( | void * | data | ) |

Attach a pointer to this IMEngineInstance, which is pointed to corresponding FrontEnd data.

Parameters

  data | The pointer to corresponding FrontEnd data, eg. input context object.

## get_frontend_data()

void * scim::IMEngineInstanceBase::get_frontend_data | ( | void |  | ) |

Retrieve the pointer previously attached by set_frontend_data();.

Returns
  The pointer previously attached by set_frontend_data();

## signal_connect_show_preedit_string()

Connection scim::IMEngineInstanceBase::signal_connect_show_preedit_string | ( | IMEngineSlotVoid * | slot | ) |

References scim::slot().

## signal_connect_show_aux_string()

Connection scim::IMEngineInstanceBase::signal_connect_show_aux_string | ( | IMEngineSlotVoid * | slot | ) |

References scim::slot().

## signal_connect_show_lookup_table()

Connection scim::IMEngineInstanceBase::signal_connect_show_lookup_table | ( | IMEngineSlotVoid * | slot | ) |

References scim::slot().

## signal_connect_hide_preedit_string()

Connection scim::IMEngineInstanceBase::signal_connect_hide_preedit_string | ( | IMEngineSlotVoid * | slot | ) |

References scim::slot().

## signal_connect_hide_aux_string()

Connection scim::IMEngineInstanceBase::signal_connect_hide_aux_string | ( | IMEngineSlotVoid * | slot | ) |

References scim::slot().

## signal_connect_hide_lookup_table()

Connection scim::IMEngineInstanceBase::signal_connect_hide_lookup_table | ( | IMEngineSlotVoid * | slot | ) |

References scim::slot().

## signal_connect_update_preedit_caret()

Connection scim::IMEngineInstanceBase::signal_connect_update_preedit_caret | ( | IMEngineSlotInt * | slot | ) |

References scim::slot().

## signal_connect_update_preedit_string()

Connection scim::IMEngineInstanceBase::signal_connect_update_preedit_string | ( | IMEngineSlotWideStringAttributeList * | slot | ) |

References scim::slot().

## signal_connect_update_aux_string()

Connection scim::IMEngineInstanceBase::signal_connect_update_aux_string | ( | IMEngineSlotWideStringAttributeList * | slot | ) |

References scim::slot().

## signal_connect_update_lookup_table()

Connection scim::IMEngineInstanceBase::signal_connect_update_lookup_table | ( | IMEngineSlotLookupTable * | slot | ) |

References scim::slot().

## signal_connect_commit_string()

Connection scim::IMEngineInstanceBase::signal_connect_commit_string | ( | IMEngineSlotWideString * | slot | ) |

References scim::slot().

## signal_connect_forward_key_event()

Connection scim::IMEngineInstanceBase::signal_connect_forward_key_event | ( | IMEngineSlotKeyEvent * | slot | ) |

References scim::slot().

## signal_connect_register_properties()

Connection scim::IMEngineInstanceBase::signal_connect_register_properties | ( | IMEngineSlotPropertyList * | slot | ) |

References scim::slot().

## signal_connect_update_property()

Connection scim::IMEngineInstanceBase::signal_connect_update_property | ( | IMEngineSlotProperty * | slot | ) |

References scim::slot().

## signal_connect_beep()

Connection scim::IMEngineInstanceBase::signal_connect_beep | ( | IMEngineSlotVoid * | slot | ) |

References scim::slot().

## signal_connect_start_helper()

Connection scim::IMEngineInstanceBase::signal_connect_start_helper | ( | IMEngineSlotString * | slot | ) |

References scim::slot().

## signal_connect_stop_helper()

Connection scim::IMEngineInstanceBase::signal_connect_stop_helper | ( | IMEngineSlotString * | slot | ) |

References scim::slot().

## signal_connect_send_helper_event()

Connection scim::IMEngineInstanceBase::signal_connect_send_helper_event | ( | IMEngineSlotStringTransaction * | slot | ) |

References scim::slot().

## signal_connect_get_surrounding_text()

Connection scim::IMEngineInstanceBase::signal_connect_get_surrounding_text | ( | IMEngineSlotGetSurroundingText * | slot | ) |

References scim::slot().

## signal_connect_delete_surrounding_text()

Connection scim::IMEngineInstanceBase::signal_connect_delete_surrounding_text | ( | IMEngineSlotDeleteSurroundingText * | slot | ) |

References scim::slot().

## process_key_event()

virtual bool scim::IMEngineInstanceBase::process_key_event | ( | const KeyEvent & | key | ) |

pure virtual

Process a key event.

Parameters

  key | - the key event to be processed.

Returns
  true if the event is processed, otherwise the event is not processed and should be forward to client application.

Implemented in scim::ComposeKeyInstance, scim::DummyIMEngineInstance, and scim::FilterInstanceBase.

## move_preedit_caret()

virtual void scim::IMEngineInstanceBase::move_preedit_caret | ( | unsigned int | pos | ) |

virtual

Move the preedit caret in the preedit string.

Parameters

  pos | - the new position that user requested.

Reimplemented in scim::ComposeKeyInstance, and scim::FilterInstanceBase.

## select_candidate()

virtual void scim::IMEngineInstanceBase::select_candidate | ( | unsigned int | index | ) |

virtual

Select a candidate in current lookup table.

When user click a candidate directly, this method will be invoked by FrontEnd.

Parameters

  index | - the index in current page of the selected candidate.

Reimplemented in scim::ComposeKeyInstance, and scim::FilterInstanceBase.

## update_lookup_table_page_size()

virtual void scim::IMEngineInstanceBase::update_lookup_table_page_size | ( | unsigned int | page_size | ) |

virtual

Update the page size of current lookup table.

In the next time, the lookup table should page down by this size.

Parameters

  page_size | - the new size of current page.

Reimplemented in scim::ComposeKeyInstance, and scim::FilterInstanceBase.

## lookup_table_page_up()

virtual void scim::IMEngineInstanceBase::lookup_table_page_up | ( |  | ) |

virtual

Flip the lookup table to the previous page.

The method will be invoked by FrontEnd when user click the lookup table page up button.

Reimplemented in scim::ComposeKeyInstance, and scim::FilterInstanceBase.

## lookup_table_page_down()

virtual void scim::IMEngineInstanceBase::lookup_table_page_down | ( |  | ) |

virtual

Flip the lookup table to the next page.

The method will be invoked by FrontEnd when user click the lookup table page down button.

Reimplemented in scim::ComposeKeyInstance, and scim::FilterInstanceBase.

## reset()

virtual void scim::IMEngineInstanceBase::reset | ( |  | ) |

virtual

Reset this engine instance.

All status of this engine instance should be reset, including the working encoding.

The client encoding may have been changed before calling this method, so if the IMEngine makes use of the client's encoding information, it should check whether the encoding has been changed. IMEngineInstance could call the get_encoding () method of base class to get the client encoding.

Reimplemented in scim::ComposeKeyInstance, and scim::FilterInstanceBase.

## focus_in()

virtual void scim::IMEngineInstanceBase::focus_in | ( |  | ) |

virtual

Focus in this engine instance.

This function should update/show/hide the status area, preedit area and lookup table, and update the full width punctuation/letter state.

Reimplemented in scim::ComposeKeyInstance, scim::DummyIMEngineInstance, and scim::FilterInstanceBase.

## focus_out()

virtual void scim::IMEngineInstanceBase::focus_out | ( |  | ) |

virtual

Focus out this engine instance.

Reimplemented in scim::ComposeKeyInstance, and scim::FilterInstanceBase.

## trigger_property()

virtual void scim::IMEngineInstanceBase::trigger_property | ( | const String & | property | ) |

virtual

Trigger a property.

This function should do some action according to the triggered property. For example toggle the input mode, etc.

Parameters

  property | the key of the triggered property.

Reimplemented in scim::ComposeKeyInstance, and scim::FilterInstanceBase.

## process_helper_event()

virtual void scim::IMEngineInstanceBase::process_helper_event | ( | const String & | helper_uuid,
|  | const Transaction & | trans )

virtual

Process the events sent from a Client Helper process.

Parameters

  helper_uuid | The UUID of the Helper process which sent the events.
  trans | The transaction which contains the events.

Reimplemented in scim::FilterInstanceBase.

## update_client_capabilities()

virtual void scim::IMEngineInstanceBase::update_client_capabilities | ( | unsigned int | cap | ) |

virtual

Update the capabilities of current client application which is attached to this IMEngineInstance.

Some client may not support all capabilities provided by the IMEngine API. For example:

- OnTheSpot preedit string display (Embedded into client window).
- Property display
- Helper module
- etc.

This method will be called to inform this IMEngineInstance object which capabilities are supported by the client application. It may be called multiple times, if the capabilities was changed.

Parameters

  cap | A bitmask to indicate which client capabilities are supported by the client application.

See also
  scim::ClientCapability

Reimplemented in scim::FilterInstanceBase.

## show_preedit_string()

void scim::IMEngineInstanceBase::show_preedit_string | ( |  | ) |

protected

Show the preedit string area.

The preedit string should be updated by calling update_preedit_string before or right after this call.

## show_aux_string()

void scim::IMEngineInstanceBase::show_aux_string | ( |  | ) |

protected

Show the aux string area.

The aux string should be updated by calling update_aux_string before or right after this call.

The aux string can contain any additional information whatever the input method engine want.

## show_lookup_table()

void scim::IMEngineInstanceBase::show_lookup_table | ( |  | ) |

protected

Show the lookup table area.

The lookup table should be updated by calling update_lookup_table before or right after this call.

## hide_preedit_string()

void scim::IMEngineInstanceBase::hide_preedit_string | ( |  | ) |

protected

Hide the preedit string area.

## hide_aux_string()

void scim::IMEngineInstanceBase::hide_aux_string | ( |  | ) |

protected

Hide the aux string area.

## hide_lookup_table()

void scim::IMEngineInstanceBase::hide_lookup_table | ( |  | ) |

protected

Hide the lookup table area.

## update_preedit_caret()

void scim::IMEngineInstanceBase::update_preedit_caret | ( | int | caret | ) |

protected

Update the preedit caret position in the preedit string.

Parameters

  caret | - the new position of the preedit caret.

## update_preedit_string()

void scim::IMEngineInstanceBase::update_preedit_string | ( | const WideString & | str,
|  | const AttributeList & | attrs = AttributeList() )

protected

Update the content of the preedit string,.

Parameters

  str | - the string content
  attrs | - the string attributes

## update_aux_string()

void scim::IMEngineInstanceBase::update_aux_string | ( | const WideString & | str,
|  | const AttributeList & | attrs = AttributeList() )

protected

Update the content of the aux string,.

Parameters

  str | - the string content
  attrs | - the string attribute

## update_lookup_table()

void scim::IMEngineInstanceBase::update_lookup_table | ( | const LookupTable & | table | ) |

protected

Update the content of the lookup table,.

FrontEnd may reduce the page size of the table according to screen resolution. If the page size is changed, FrontEnd will inform this engine instance by calling update_lookup_table_page_size method.

Parameters

  table | - the new LookupTable

## commit_string()

void scim::IMEngineInstanceBase::commit_string | ( | const WideString & | str | ) |

protected

Commit a string to the client application.

The preedit string should be hid before calling this method. Otherwise the clients which use OnTheSpot input mode will flicker annoyingly.

Parameters

  str | - the string to be committed.

## forward_key_event()

void scim::IMEngineInstanceBase::forward_key_event | ( | const KeyEvent & | key | ) |

protected

Forward a key event to the client application.

Parameters

  key | - the key event to be forwarded.

## register_properties()

void scim::IMEngineInstanceBase::register_properties | ( | const PropertyList & | properties | ) |

protected

Register all properties of this IMEngineInstance into the FrontEnd.

The old properties previously registered by other IMEngineInstance will be discarded, so for each time focus_in() is called, all properties should be registered no matter whether they had been registered before.

Parameters

  properties | the PropertyList contains all of the properties.

## update_property()

void scim::IMEngineInstanceBase::update_property | ( | const Property & | property | ) |

protected

Update a registered property.

Update a property which already registered by register_properties () method.

Parameters

  property | the property to be updated.

## beep()

void scim::IMEngineInstanceBase::beep | ( |  | ) |

protected

Generate a short beep.

## start_helper()

void scim::IMEngineInstanceBase::start_helper | ( | const String & | helper_uuid | ) |

protected

Start a Client Helper process.

Parameters

  helper_uuid | The UUID of the Helper object.

## stop_helper()

void scim::IMEngineInstanceBase::stop_helper | ( | const String & | helper_uuid | ) |

protected

Stop a Client Helper process which was started by start_helper.

Parameters

  helper_uuid | The UUID of the Helper object.

## send_helper_event()

void scim::IMEngineInstanceBase::send_helper_event | ( | const String & | helper_uuid,
|  | const Transaction & | trans )

protected

Send an events transaction to a client helper process.

Parameters

  helper_uuid | The UUID of the Helper object.
  trans | The transaction which contains events.

## get_surrounding_text()

bool scim::IMEngineInstanceBase::get_surrounding_text | ( | WideString & | text,
|  | int & | cursor,
|  | int | maxlen_before = -1,
|  | int | maxlen_after = -1 )

protected

Retrieves context around the insertion point.

Input methods typically want context in order to constrain input text based on existing text; this is important for languages such as Thai where only some sequences of characters are allowed.

Unlike other signal activation actions, this action will return the result immediately.

Parameters

  text | location to store the context string around the insertion point.
  cursor | location to store index of the insertion cursor within @text.
  maxlen_before | the maxmium length of context string to be retrieved before the cursor; -1 means unlimited.
  maxlen_after | the maxmium length of context string to be retrieved after the cursor; -1 means unlimited.

Returns
  true if surrounding text was provided.

## delete_surrounding_text()

bool scim::IMEngineInstanceBase::delete_surrounding_text | ( | int | offset,
|  | int | len )

protected

Ask the client to delete characters around the cursor position.

In order to use this function, you should first call get_surrounding_text () to get the current context, and call this function immediately afterwards to make sure that you know what you are deleting. You should also account for the fact that even if the signal was handled, the input context might not have deleted all the characters that were requested to be deleted.

Parameters

  offset | offset from cursor position in chars; a negative value means start before the cursor.
  len | number of characters to delete.

Returns
  true if the signal was handled.

The documentation for this class was generated from the following file:

- scim_imengine.h