[Uim] Re: Suggestion: Renaming new API functions

[YamaKen]

At Thu, 7 Oct 2004 06:26:51 +0900,
tkng at xem.jp wrote:
> 
> On Fri, 01 Oct 2004 17:48:52 +0900
> YamaKen <yamaken at bp.iij4u.or.jp> wrote:
> 
> > > >   So I suggest an accurate name uim_get_im_name_of_context().
> > > 
> > > Because uim's input context has plural input methods (so of course
> > > plural input method names), I opposite this function name. Anyway, I
> > > need your blow-by-blow opinion.
> > 
> > In your view, an input context HAS an input method as slave. So
> > each input context also has the concept 'current input context'.
> 
> Yes, but it's not my view. A uim_context keeps a list of available input
> methods as a struct member actually.

I can't find such member in struct uim_context_. What are you
referring to?  In my view, uim_im_array[] keeps a list of
available IMs in C-side.

> > But in natural view, an input context BELONGS TO only one input
> > method. So I suggest the name uim_im_name_of_context() to
> > conform to this model. It simply returns its only one input
> > method name as an attribute of the input context.
> 
> I want to distinguish these two models as 1-n model and 1-1 model.
> 
> I agree that people will feel 1-1 model is more natural than 1-n model.

I'm afraid of miscommunication between you and I about my
intention.

I had said that one input context belongs to only one input
method. But I had not said that one input method has only one
input context. So n-1 model represents my intention in your
expression. Following diagram expresses my intention more
precisely. The diagram reflects current implementation of uim.


               C-side context     Scheme-side context         input method
               -------------        ---------------            ---------
           ^  | uim_context | ---> | anthy-context | ---+---> |  Anthy  |
           |   -------------        ---------------     |      ---------
           |   -------------        ---------------     |
           |  | uim_context | ---> | anthy-context | ---+
           |   -------------        ---------------     |
           |   -------------        ---------------     |
           |  | uim_context | ---> | anthy-context | ---+
           |   -------------        ---------------
           |   -------------        ---------------            ---------
  coexist  |  | uim_context | ---> |  skk-context  | ---+---> |   SKK   |
           |   -------------        ---------------     |      ---------
           |   -------------        ---------------     |
           |  | uim_context | ---> |  skk-context  | ---+
           |   -------------        ---------------
           |   -------------        ---------------            ---------
           |  | uim_context | ---> | prime-context | ---+---> |  PRIME  |
           |   -------------        ---------------     |      ---------
           |   -------------        ---------------     |
           v  | uim_context | ---> | prime-context | ---+
               -------------        ---------------


> To be honest, I was also confused this concept before. But as identified
> above, uim_context has a list of available input methods actually and
> it's refrected to the API. See the function uim_get_nr_im.

uim_get_nr_im() uses uim_im_array[] to count the number of
available IMs. uim_context does nothing about it.

> Uim already employed 1-n model, so introducing 1-1 model will cause API
> confusion. I think such change should be done after 1.0.0, because it
> concerns developers only, there's no direct benefit to users.

My suggestion does not change any actual codes or behaviors. It
only wants a renaming to avoid confusion.

uim_switch_im() actually performs the switching as follows.

(1) An uim_context is pointing to an anthy-context

   --------------        ----------------            ---------
  | :uim_context | ---> | :anthy-context | -------> |  Anthy  |
  |--------------|       ----------------            ---------
  | id = 3       |
   --------------

(2) The anthy-context has been destroyed. But the uim_context
    remains

   --------------
  | :uim_context |
  |--------------|
  | id = 3       |
   --------------

(3) A new Scheme-side context such as a skk-context is newly
    created

   --------------        ----------------            ---------
  | :uim_context |      |  :skk-context  | -------> |   SKK   |
  |--------------|       ----------------            ---------
  | id = 3       |
   --------------

(4) the Scheme-side context created in (3) has been bound to (2)

   --------------        ----------------            ---------
  | :uim_context | ---> |  :skk-context  | -------> |   SKK   |
  |--------------|       ----------------            ---------
  | id = 3       |
   --------------

As explained above, the Scheme-side contexts does not have the
concept 'current input method'. The contexts are permanently
related to its only one input method although an uim_context can
switch corresponding Scheme-side context.

However, the concept 'current input method of context' can be
accepted if developer regards uim_context as an concrete
IM-multiplexer rather than abstract context object, although the
concept is inaccurate. It accurately means 'the input method of
(Scheme-side) context that is currently being bound to an
IM-multiplexer'.

But the concept enforces 'regard uim_context as IM-multiplexer'
to all developers, and implies that an assumption 'an
uim_context will switches its IM regularly'. But the concept and
assumption is only an optional use case of libuim. We should not
enforce one specific use case to developers.

Simply to say, the name uim_get_current_im_name() is too
specific about its purpose. So I want to rename it to a more
generic name uim_get_im_name_of_context().

Consider following case.

(1) A bridge implementaion that does not use uim_im_switch()
    such as IMKit-uim exists. IMKit-uim will not use
    uim_im_switch() since the Qtopia platform well-supports its
    own IM-switching mechanism. And almost embedded application
    will also not use the IM-switching itself

(2) An uim_context in such bridges persistently points to its
    corresponding Scheme-side context over its lifetime

   --------------        ----------------            ---------
  | :uim_context | ---> | :anthy-context | -------> |  Anthy  |
  |--------------|       ----------------            ---------
  | id = 5       |
   --------------

(3) To know the input method name of the context,
    uim_get_current_im_name() will be performed. But no 'current
    input method of an uim_context' concept exists for the
    uim_contexts in the bridges. It will cause a confusion about
    the API. Developers will simply want to know 'the input
    method of an uim_context'


In other expression, current naming scheme is felt as follows
for me.

class uim_context {
public:
  current_im_name();  // 'current im' is a concept of the subclass
};

class im_multiplexer : public uim_context {
public:
  switch_im();
};

The name current_im_name() enforces 'regard all uim_context as
instance of the subclass im_multiplexer' to all developers. It's
a layer violation.

In contrast, more generic name im_name() keeps uim_context
abstract if developer does not want im_multiplexer. The name
does not conflict with the concept of im_multiplexer.

class uim_context {
public:
  im_name();
};

class im_multiplexer : public uim_context {
public:
  switch_im();
};

The name uim_get_im_name_of_context() is the equivalent of
uim_context::im_name() in this example. Please consider the
location of the function in the class hierachy.


Regards,
-------------------------------
YamaKen  yamaken at bp.iij4u.or.jp