Solaris Input Method Server (Htt) for X Window System environment provides default GUI objects, such as preedit, status, and lookup selection window. Although these default GUI objects provide adequate functionalities for basic operations, input method engines requires much richer functionalities than the default GUI objects provide.
The mechanism of X auxiliary object enables Input Method engine vendors to define their own GUI objects which will work well with their Input Method engines.
This document describes the interface between Solaris Input Method Server provided by Solaris, and X Auxiliary Object which will be provided by Input Method engine vendors.
X Auxiliary Object is implemented as an shared library, which will be loaded by xiiimp.so. The loading is initiated by the request from xiiimp.so. After loading the shared library, xiiimp.so will forwards requests from Input Method engine to the shared library.
IIIM server can specify path names of X auxiliary shared library objects, or path names of configuration files.
Path names may not start with ``/
'', nor contain
''/../
''. Path names are interpreted relative to
``/usr/lib/im/
''.
One X auxiliary shared library can contain one or more X auxiliary objects. See X Auxiliary Object Directory for more detail.
One X auxiliary object configuration file can contain one or more names of X auxiliary shared library objects. See X Auxiliary Object Configuration File for more detail of.
aux_t structure is defined in iiimpAux.h
. X
auxiliary object can access the member ``service
'',
but may not access other members.
X Auxiliary Object must define an auxiliary object directory, which consists of array of aux_dir_t structure. Each element defines an X auxiliary object. The array will be terminated with null element.
typedef struct {
aux_name_t name;
aux_method_t * method;
} aux_dir_t;
X auxiliary object must export a symbol ``aux_dir
''
which points to the array of aux_aux_t
structures.
X Auxiliary Object must define the name of auxiliary object, as UTF-16 strings. The length is specified as a byte length.
typedef struct {
int len;
CARD16 * ptr;
} aux_name_t;
X Auxiliary Object must define the following methods.
typedef struct {
Bool (* create)(aux_t *);
Bool (* start)(aux_t *, const unsigned char *, int);
Bool (* draw)(aux_t *, const unsigned char *, int);
Bool (* done)(aux_t *, const unsigned char *, int);
Bool (* switched)(aux_t *, int, int);
Bool (* destroy)(aux_t *);
} aux_method_t;
xiiimp.so
provides the following service methods,
which can be accessed thru the member ``service
''
of aux_t
structure.
struct {
void (* aux_setvalue)(aux_t *, const unsigned char *, int);
int (* im_id)(aux_t *);
int (* ic_id)(aux_t *);
Display * (* display)(aux_t *);
Window (* window)(aux_t *);
XPoint * (* point)(aux_t *, XPoint *);
XPoint * (* point_caret)(aux_t *, XPoint *);
size_t (* utf16_mb)(const char **, size_t *,
char **, size_t *);
size_t (* mb_utf16)(const char **, size_t *,
char **, size_t *);
unsigned char * (* compose)(const aux_data_t *, int *);
int (* compose_size)(aux_data_type_t,
const unsigned char *);
aux_data_t * (* decompose)(aux_data_type_t, const unsigned char *);
void (* decompose_free)(aux_data_t *);
void (* register_X_filter)(Display *, Window, int, int,
Bool (*)(Display *, Window,
XEvent *, XPointer),
XPointer);
void (* unregister_X_filter)(Display *, Window,
Bool (*)(Display *, Window,
XEvent *, XPointer),
XPointer);
Bool (* server)(aux_t *);
Window (* client_window)(aux_t *);
Window (* focus_window)(aux_t *);
int (* screen_number)(aux_t *);
int (* point_screen)(aux_t *, XPoint *);
int (* point_caret_screen)(aux_t *, XPoint *);
} aux_service_t;
aux_data_t structure is defined in iiimpAux.h
.
X auxiliary object may not access a member string_ptr
.
It is intended to be used by decompose()
and decompose_free()
service methods.
typedef struct {
aux_data_type_t type;
int im;
int ic;
int aux_index;
int aux_name_length;
unsigned char * aux_name;
int integer_count;
int * integer_list;
int string_count;
aux_string_t * string_list;
unsigned char * string_ptr;
} aux_data_t;
aux_data_type_t
is used for
compose()
and
compose_size()
service methods.
typedef enum {
AUX_DATA_NONE = 0,
AUX_DATA_START = 1,
AUX_DATA_DRAW = 2,
AUX_DATA_DONE = 3,
AUX_DATA_SETVALUE = 4
} aux_data_type_t;
X auxiliary object configuration files can be defined to specify the names of X auxiliary shared library objects.
The configuration file is an ASCII file. The first line should be:
# IIIM X auxiliary
Lines beginning with ``#
'' are treated as comments,
and will be ignored.
Empty lines are also ignored.
Each line consists of two fields. The first field is the name of X auxiliary object. The second filed is the path name to the X auxiliary shared library object.
The path name can be specified as an absolute path name or an
relative path name. If the path name begins with
``/
'', it will be interpreted as an absolute path
name. Otherwise, the path name will be interpreted relative to
the directory in which the configuration file resides.
When the IM engine issues IM_AUX_START
request for the first time for the X auxiliary object,
create()
method will be invoked before the
invocation of start()
.
When the X auxiliary object is destroyed, destroy()
method will be invoked.
The method should deallocate any resources allocated in
create
method and other invocation of X Auxiliary
Object methods.
Bool (* create)(aux_t * aux)
Bool (* destroy)(aux_t * aux)
When the IM engine issues IM_AUX_START request,
start()
method will be invoked.
When the IM engine issues IM_AUX_DONE request,
done()
method will be invoked.
Bool (* start)(aux_t * aux, const unsigned char * p, int len)
Bool (* done)(aux_t * aux, const unsigned char * p, int len)
aux_data_t
object
using decompose()
service method.
When the IM engine issues IM_AUX_DRAW request,
draw()
method will be invoked.
Bool (* draw)(aux_t * aux, const unsigned char * p, int len)
aux_data_t
object
using decompose()
service method.
When the IM is switched on or off by Htt IM server,
switched()
method will be invoked.
Bool (* switched)(aux_t * aux, int im_id, int on_off)
Send IM_AUX_SETVALUES request to IIIM server.
void (* aux_setvalue)(aux_t * aux, const unsigned char * p, int len)
IM_AUX_SETVALUES
request dataIM_AUX_SETVALUES
request dataGet IM identifier.
int (* im_id)(aux_t * aux)
Get IC identifier.
int (* ic_id)(aux_t * aux)
Save IC specific auxiliary private data
void (* data_set)(aux_t * aux, int im_id, void * data)
Get IC specific auxiliary private data.
void * (* data_get)(aux_t * aux, int im_id)
Get X display descriptor.
Display * (* display)(aux_t * aux)
Get window identifier of focus window, client window, or None.
Window (* window)(aux_t * aux)
Get cursor point, or spot location, relative to the window obtained by window().
XPoint * (* point)(aux_t * aux, XPoint * point)
Get caret point, or spot location, relative to the window obtained by window(), with caret adjustment.
XPoint * (* point_caret)(aux_t * aux, XPoint * point)
Convert character encoding from UTF-16 to MultiByte.
size_t (* utf16_mb)(const char ** inbuf, size_t * inbytesleft,
char ** outbuf, size_t * outbytesleft)
Convert character encoding from MultiByte to UTF-16.
size_t (* mb_utf16)(const char ** inbuf, size_t * inbytesleft,
char ** outbuf, size_t * outbytesleft)
Compose IIIMP request data.
This method does not perform encoding conversion on the member
``string_list
''.
Normally, each string of string_list should be encoded with
UTF-16 encoding. Locale related MultiByte strings can be
converted to UTF-16 strings using
mb_utf16()
service method.
X auxiliary object must fill all member of aux_data object
excluding ``string_ptr
''.
unsigned char * (* compose)(const aux_data_t * aux_data, int * size)
aux_data_t
object from which IIIMP request is composed.Get the size of composed IIIMP request.
int (* compose_size)(aux_data_type_t data_type, const unsigned char * p)
Decompose IIIMP request to aux_data_t
object. This
method does not perform encoding conversion on the member
``string_list
''.
Normally, each string of string_list is encoded with UTF-16
encoding. UTF-16 strings can be converted to locale related
MultiByte strings using utf16_mb()
service method.
aux_data_t * (* decompose)(aux_data_type_t data_type, const unsigned char * p)
aux_data_t
object
Free aux_data_t
object which is returned by
compose()
service method.
void (* decompose_free)(aux_data_t * aux_data)
aux_data_t
object.Register X event filter.
void (* register_X_filter)(Display * display, Window window,
int start_type, int end_type,
Bool (* filter)(Display *,
Window,
XEvent *,
XPointer),
XPointer client_data);
Unregister X event filter.
void (* unregister_X_filter)(Display * display, Window window,
Bool (* filter)(Display *, Window,
XEvent *, XPointer),
XPointer client_data);
Returns True
if the current process is Htt X back
end server. Otherwise returns False
;
Bool (* server)(aux_t * aux);
Get window identifier of client window or None.
Window (* client_window)(aux_t * aux)
Get window identifier of focus window or None.
Window (* focus_window)(aux_t * aux)
Returns screen number of focus window, client window, or -1.
int (* screen_number)(aux_t * aux)
Get cursor point, or spot location, relative to the root window.
Returns screen number of focus window, client window, or -1.
int (* point_screen)(aux_t * aux, XPoint * point)
Get caret point, or spot location, relative to the root window, with caret adjustment.
Returns screen number of focus window, client window, or -1.
int (* point_caret_screen)(aux_t * aux, XPoint * point)
xiiimp.so is loaded by Htt X back end server, or X applications. Thus the followings are required.
server()
service method
can be used to see whether the X auxiliary object is attached to
an Htt X back end server or not.
If the X Auxiliary Object is to be implemented using Motif or other toolkits, it should be implemented as an external stand alone process. Communication between X Auxiliary Object and the external process can be achieved via X client message or property. Sample source files are available at the following directory.
IM_AUX_START
iml_make_aux_start_inst()
then
iml_execute()
, IIIM server sends the request to the client.
IM_AUX_DRAW
iml_make_aux_draw_inst()
then
iml_execute()
, IIIM server sends the request to the client.
IM_AUX_DONE
iml_make_aux_done_inst()
then
iml_execute()
, IIIM server sends the request to the client.
IM_AUX_SETVALUES
X auxiliary object directory
/usr/lib/im/language/
language/
IM/
.X auxiliary object shared library
.so
''.X auxiliary object configuration file
.conf
''.