cm(3X) cm(3X)
NAME
cm, cm_open, cm_close, cm_put - Kana-Kanji Conversion Manager Library
SYNOPSIS
cc [ flags ...] files ... -lmle [ libraries ...]
#include <mle/cm.h>
#include <mle/env.h>
#include <mle/cmkeys.h>
Cm_session cm_open(cm_id, cm_initvalue, se_initvalue)
Cm_id cm_id;
struct cm_initstruct *cm_initvalue;
struct cm_to_env *se_initvalue;
int cm_close(cm_id, cm_session);
Cm_id cm_id;
Cm_session cm_session;
struct cm_to_env *cm_put(cm_id, cmsession, inptr)
Cm_id cm_id;
Cm_session cmsession;
struct env_to_cm *inptr;
DESCRIPTION
This library defines the interface for presenting the input data and receiving the intermediate and final results of language-specific con-
version process such as Kana-Kanji conversion. The current release supports such conversion for the Japanese language.
Use of this library enables the user to construct a universal application system that can handle different languages, simply by describing
language-independent input procedures (such as screen control) in the applications.
When the user passes input data to the Conversion Manager (CM), two primary responses are returned from the CM. One is a character string
resulting from the conversion process, which will be treated as the input data. The other is logical data describing the display request
for the screen for any user interactions that have occurred during the conversion process. The user can expand the logical data into a
visible screen image (physical data), which achieves the user interface for the conversion.
The display request sent from the CM is presented as operations for the following four regions:
- Intermediate region
- Selection region
- Mode region
- Miscellaneous region
The intermediate region is mainly used for showing the intermediate results of conversion. It consists of logical data in the following
structure.
int ce_cursor /* cursor position */
int ce_cursor_type/* cursor type */
e_char *ce_text /* text to display */
u_char *ce_text_attr/* attribute, color & type of text */
int ce_v_pos /* display position */
int ce_v_type /* meaning of ce_v_pos */
The image being input is indicated by this structure. The library user determines how to display this data on the screen, and where on the
screen.
The selection region enables the candidate selection process. It consists of logical data in the following structure.
int ce_ncandidate/* number of candidates */
e_char **ce_candidate/* array of EUC strings for candidates */
int ce_prevexist /* whether previous candidate exists */
int ce_nextexist /* whether next candidate exists */
e_char *ce_sel_prompt/* user prompt for selection operation */
ce_prevexist being true indicates that one or more candidates follow, and ce_nextexist being true indicates that one or more candidates
precede.
The mode region is used for presenting the modes the CM has. It consists of logical data in the following structure.
((mode_name mode_value)(mode_name mode_value) ....)
It is the library user's responsibility to ensure the correspondence between the mode names and the values to be displayed.
The miscellaneous region is used for achieving other display operations such as displaying help messages and adding to dictionaries. It
comprises three subregions:
- Interactive subregion
- Label subregion
- Message subregion
Logical data for each subregion is represented by the structure shown below.
Interactive subregion
int ce_cursor /* cursor position */
int ce_cursor_type/* cursor type */
e_char *ce_text /* text to display */
u_char *ce_text_attr/* attribute, color & type of text */
int ce_v_pos /* display position */
int ce_v_type /* meaning of ce_v_pos */
Label subregion
e_char *ce_text /* label text */
Message subregion
e_char *ce_text /* text to display */
int ce_prevexist /* previous text exists */
int ce_nextexist /* next text exists */
Refer to cm_put() for details on operations for these regions.
FUNCTIONS
cm_open() declares the beginning of the use of the CM specified by cm_id. The current release only supports (int)1 as cm_id.
cm_initstruct contains the members shown below.
e_char *env_value; /* unused */
struct usr_auth_info {
int uid; /* user ID */
char *user_name;/* user name */
int gid; /* group ID */
char *grp_name;/* group name */
int hid; /* host ID */
char *host_name;/* host name */
}
cm_close() terminates the session initiated by cm_open().
cm_put() passes operations for regions to the CM, and receives instructions from the CM. The env_to_cm structure contains the request and
information to be passed to CM. The cm_to_env structure contains the operation request generated as a result of processing the request,
and the pointer to that structure is given as the return value of the cm_put() function.
OPERATIONS SENT TO CM
The env_to_cm structure consists of the following elements.
struct env_to_cm *ec_next; /* pointer to next structure */
Operation_type ec_operation; /* operation sent to CM */
union {
/* parameters required for the operation */
}
A single call can send multiple requests by chaining the sets of an operation and associated parameters. ec_next being NULL represents the
last structure in the chain.
The following lists the operations defined in <mle/cm.h>.
CM_RESET Reset request for CM
CM_SIMPLE_EVENT Data input to CM
CM_CMON Reporting that CM became ON
CM_NOP No operation
The following operations are used in the selection region.
CM_NEXT_CANDIDATE Direct CM to send next candidates
CM_PREV_CANDIDATE Direct CM to send previous candidates
CM_SELECT Notify CM of selected candidate's id
CM_ABORT_SELECTION Direct CM to stop selection
CM_SELECT_INVALID Notify CM of invalid selection
OPERATIONS SENT FROM CM
The cm_to_env structure consists of the following elements.
struct cm_to_env *ce_next; /* pointer to next structure */
Operation_type ce_operation; /* operation sent to CM */
union {
/* parameters required for the operation */
}
Since multiple sets of an operation and associated parameters may be chained, the user should process the request from CM until encounter-
ing a structure where ce_next is NULL.
The following operations are defined in <mle/env.h>.
ENV_COMMIT Pass the committed string
ENV_SET_CURRENT_REGION Specify active region
ENV_NOP No operation
ENV_CM_OFF Switch to CM OFF state
ENV_SETKEY_CM_ON Define key for making CM active
The following operations are used in the intermediate region.
ENV_INTERM_RESET Reset intermediate region
ENV_INTERM Identify intermediate region
The following operations are used in the selection region.
ENV_SELECT_RESET Reset selection region
ENV_SELECT Start selection and identify selection region
ENV_SELECT_END End selection
ENV_SELECT_NEXT Get next candidates
ENV_SELECT_PREV Get previous candidates
ENV_SELECT_COMMIT Request selected candidate to be committed
ENV_SELECT_NEXT_CAN Make next candidate active
ENV_SELECT_PREV_CAN Make previous candidate to be active
ENV_SELECT_TEST Test whether selected candidate can be comitted
The following operation is used in the mode region.
ENV_SET_MODE Display mode
The following operations are used in the miscellaneous region.
ENV_MISC_RESET Reset miscellaneous region
ENV_M_INTERACTIVE Display interactive subregion
ENV_M_LABEL Display label subregion
ENV_M_MESS Display message subregion
ENV_M_MESS_NEXT_P Display next page of message subregion
ENV_M_MESS_PREV_P Display prev. page of message subregion
Refer to mle/cm.h,mle/env.h and mle/cmkeys.h for a complete list of parameters.
BUGS
Addresses returned from cm_put() and all parameter addresses should be treated as read-only data. The results may be unpredictable if
these addresses are modified.
In JFP, this library is provided for a compatibility with a certain application which has ENV/CM type interface for its japanese input
mothod. Therefore, Misc Region is not supported.
27 March 1992 cm(3X)