IIIMCF object life-cycle

IIIMCF has various kinds of objects, e.g., IIIMCF_text IIIMCF_lookup_choice , IIIMCF_event , .etc. In principle, users do not need to manage such objects' construction nor destruction. In principle, IIIMCF library manages life-cycles of such objects.

There are only two rules that you must follow. First, you must be sure to call iiimcf_ignore_event for the event obtained by iiimcf_get_next_event . IIIMCF library does not discard the event until users call iiimcf_get_next_event to it.

Second, users are able to create IIIMCF_attr by iiimcf_create_attr and duplicate IIIMCF_text by IIIMCF_duplicate_text . Such objects are never deleted by IIIMCF library so that users must destroy it by iiimcf_destroy_attr or iiimcf_destroy_text . Of course, users must not delete other IIIMCF_text and IIIMCF_attr objects that are not created or duplicated by these function.

Note that any objects other than such created attr or duplicated text may be inaccessible after calling iiimcf_forward_event or iiimcf_dispatch_event , or returning from component entry function. After such operations, you have to retrieve again such objects by proper information obtaining APIs.

However, there is one exception to the above rule. iiimcf_dispatch_event does not discard the dispatched event. Therefore, you have to call iiimcf_ignore_event to it as well. The following example illustrates it.

IIIMF_status
your_component_entry_function(
    IIIMCF_context context,
    IIIMCF_event event,
    IIIMCF_component current,
    IIIMCF_component parent
)
{
    IIIMCF_event newevent;
    IIIMCF_keyevent kev;
    /* At this point, you can access "event". */
    iiimcf_dispatch_event(context, event);
    /* Also at this point, you can still access "event"
       despite having dispatched it. */
    kev.keychar = kev.keycode =  kev.modifier = kev.time_stamp = 0;
    iiimcf_create_keyevent(kev, &newevent);
    /* At this point, you can access both "event" and "newevent". */
    iiimcf_dispatch_event(context, newevent);
    /* Also at this point, you can access both "event" and "newevent". */
    iiimcf_ignore_event(newevent);
    /* Now newevent is discarded, you cannot access "newevent". */

    return IIIMF_STATUS_SUCCESS;
}
      

NOTICE: old version of libiiimcf had discarded any events dispatched by iiimcf_dispatch_event . But in the new version, you MUST call iiimcf_ignore_event to all events that are obtained by iiimcf_get_next_event even though they are dispatched by iiimcf_dispatch_event .