From: Inhong Han Date: Tue, 10 Sep 2024 00:12:03 +0000 (+0900) Subject: Improve documentation X-Git-Tag: accepted/tizen/unified/x/20240911.084250~1 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=71013d0c1bdcac53e55cd9226f02cad8ad2b8f03;p=platform%2Fcore%2Fapi%2Finputmethod.git Improve documentation Change-Id: I70bf9d12f217f22a09073db85a118aa8834ca9b9 --- diff --git a/inputmethod/include/inputmethod.h b/inputmethod/include/inputmethod.h index 535ac92..5f48621 100644 --- a/inputmethod/include/inputmethod.h +++ b/inputmethod/include/inputmethod.h @@ -967,7 +967,7 @@ typedef struct { int ime_run(ime_callback_s *basic_cb, void *user_data); /** - * @brief Sets @c focus_in event callback function. + * @brief Sets the event callback function that is called when an associated text input UI control has focus. * * @since_tizen 2.4 * @@ -995,7 +995,7 @@ int ime_run(ime_callback_s *basic_cb, void *user_data); int ime_event_set_focus_in_cb(ime_focus_in_cb callback_func, void *user_data); /** - * @brief Sets @c focus_out event callback function. + * @brief Sets the event callback function that is called when an associated text input UI control loses focus. * * @since_tizen 2.4 * @@ -1023,7 +1023,7 @@ int ime_event_set_focus_in_cb(ime_focus_in_cb callback_func, void *user_data); int ime_event_set_focus_out_cb(ime_focus_out_cb callback_func, void *user_data); /** - * @brief Sets @c surrounding_text_updated event callback function. + * @brief Sets the event callback function that is called when an associated text input UI control responds to a request with the surrounding text. * * @since_tizen 2.4 * @@ -1051,7 +1051,7 @@ int ime_event_set_focus_out_cb(ime_focus_out_cb callback_func, void *user_data); int ime_event_set_surrounding_text_updated_cb(ime_surrounding_text_updated_cb callback_func, void *user_data); /** - * @brief Sets @c input_context_reset event callback function. + * @brief Sets the event callback function that is called to reset the input context of an associated text input UI control. * * @since_tizen 2.4 * @@ -1079,7 +1079,7 @@ int ime_event_set_surrounding_text_updated_cb(ime_surrounding_text_updated_cb ca int ime_event_set_input_context_reset_cb(ime_input_context_reset_cb callback_func, void *user_data); /** - * @brief Sets @c cursor_position_updated event callback function. + * @brief Sets the event callback function that is called when the position of the cursor in an associated text input UI control changes. * * @since_tizen 2.4 * @@ -1107,7 +1107,7 @@ int ime_event_set_input_context_reset_cb(ime_input_context_reset_cb callback_fun int ime_event_set_cursor_position_updated_cb(ime_cursor_position_updated_cb callback_func, void *user_data); /** - * @brief Sets @c language_requested event callback function. + * @brief Sets the event callback function that is called when an associated text input UI control requests the language from the input panel. * * @since_tizen 2.4 * @@ -1135,7 +1135,7 @@ int ime_event_set_cursor_position_updated_cb(ime_cursor_position_updated_cb call int ime_event_set_language_requested_cb(ime_language_requested_cb callback_func, void *user_data); /** - * @brief Sets @c language_set event callback function. + * @brief Sets the event callback function that is called to set the preferred language to the input panel. * * @since_tizen 2.4 * @@ -1163,7 +1163,7 @@ int ime_event_set_language_requested_cb(ime_language_requested_cb callback_func, int ime_event_set_language_set_cb(ime_language_set_cb callback_func, void *user_data); /** - * @brief Sets @c imdata_set event callback function. + * @brief Sets the event callback function that is called to set the application specific data to deliver to the input panel. * * @since_tizen 2.4 * @@ -1192,7 +1192,7 @@ int ime_event_set_language_set_cb(ime_language_set_cb callback_func, void *user_ int ime_event_set_imdata_set_cb(ime_imdata_set_cb callback_func, void *user_data); /** - * @brief Sets @c imdata_requested event callback function. + * @brief Sets the event callback function that is called when an associated text input UI control requests the application specific data from the input panel. * * @since_tizen 2.4 * @@ -1221,7 +1221,7 @@ int ime_event_set_imdata_set_cb(ime_imdata_set_cb callback_func, void *user_data int ime_event_set_imdata_requested_cb(ime_imdata_requested_cb callback_func, void *user_data); /** - * @brief Sets @c layout_set event callback function. + * @brief Sets the event callback function that is called when an associated text input UI control requests the input panel to set its layout. * * @since_tizen 2.4 * @@ -1249,7 +1249,7 @@ int ime_event_set_imdata_requested_cb(ime_imdata_requested_cb callback_func, voi int ime_event_set_layout_set_cb(ime_layout_set_cb callback_func, void *user_data); /** - * @brief Sets @c return_key_type_set event callback function. + * @brief Sets the event callback function that is called when an associated text input UI control requests the input panel to set the @c Return key label. * * @since_tizen 2.4 * @@ -1277,7 +1277,7 @@ int ime_event_set_layout_set_cb(ime_layout_set_cb callback_func, void *user_data int ime_event_set_return_key_type_set_cb(ime_return_key_type_set_cb callback_func, void *user_data); /** - * @brief Sets @c return_key_state_set event callback function. + * @brief Sets the event callback function that is called when an associated text input UI control requests the input panel to control the @c Return key state. * * @since_tizen 2.4 * @@ -1305,7 +1305,7 @@ int ime_event_set_return_key_type_set_cb(ime_return_key_type_set_cb callback_fun int ime_event_set_return_key_state_set_cb(ime_return_key_state_set_cb callback_func, void *user_data); /** - * @brief Sets @c geometry_requested event callback function. + * @brief Sets the event callback function that is called when an associated text input UI control requests the position and size from the input panel. * * @since_tizen 2.4 * @@ -1333,7 +1333,7 @@ int ime_event_set_return_key_state_set_cb(ime_return_key_state_set_cb callback_f int ime_event_set_geometry_requested_cb(ime_geometry_requested_cb callback_func, void *user_data); /** - * @brief Sets @c process_key_event event callback function. + * @brief Sets the event callback function that is called when a key event is received from external devices or @c ime_send_key_event(). * * @since_tizen 2.4 * @@ -1405,7 +1405,7 @@ int ime_event_set_geometry_requested_cb(ime_geometry_requested_cb callback_func, int ime_event_set_process_key_event_cb(ime_process_key_event_cb callback_func, void *user_data); /** - * @brief Sets @c process_key_event_with_keycode callback function to handle the key event with a keycode. + * @brief Sets the event callback function that is called when a key event is received with a keycode from external devices or @c ime_send_key_event(). * * @since_tizen 5.5 * @@ -1433,7 +1433,7 @@ int ime_event_set_process_key_event_cb(ime_process_key_event_cb callback_func, v int ime_event_set_process_key_event_with_keycode_cb(ime_process_key_event_with_keycode_cb callback_func, void *user_data); /** - * @brief Sets @c display_language_changed event callback function. + * @brief Sets the event callback function that is called when the system display language is changed. * * @since_tizen 2.4 * @@ -1461,7 +1461,7 @@ int ime_event_set_process_key_event_with_keycode_cb(ime_process_key_event_with_k int ime_event_set_display_language_changed_cb(ime_display_language_changed_cb callback_func, void *user_data); /** - * @brief Sets @c rotation_degree_changed event callback function. + * @brief Sets the event callback function that is called when the device is rotated. * * @since_tizen 2.4 * @@ -1489,7 +1489,7 @@ int ime_event_set_display_language_changed_cb(ime_display_language_changed_cb ca int ime_event_set_rotation_degree_changed_cb(ime_rotation_degree_changed_cb callback_func, void *user_data); /** - * @brief Sets @c accessibility_state_changed event callback function. + * @brief Sets the event callback function that is called when Accessibility in Settings application is on or off. * * @since_tizen 2.4 * @@ -1517,7 +1517,7 @@ int ime_event_set_rotation_degree_changed_cb(ime_rotation_degree_changed_cb call int ime_event_set_accessibility_state_changed_cb(ime_accessibility_state_changed_cb callback_func, void *user_data); /** - * @brief Sets @c option_window_created event callback function. + * @brief Sets the event callback function that is called to create the option window. * * @since_tizen 2.4 * @@ -1544,7 +1544,7 @@ int ime_event_set_accessibility_state_changed_cb(ime_accessibility_state_changed int ime_event_set_option_window_created_cb(ime_option_window_created_cb callback_func, void *user_data); /** - * @brief Sets @c option_window_destroyed event callback function. + * @brief Sets the event callback function that is called to destroy the option window. * * @since_tizen 2.4 * @@ -2403,7 +2403,7 @@ int ime_device_info_get_class(ime_device_info_h dev_info, Ecore_IMF_Device_Class int ime_device_info_get_subclass(ime_device_info_h dev_info, Ecore_IMF_Device_Subclass *dev_subclass); /** - * @brief Sets prediction hint event callback function. + * @brief Sets the event callback function that is called to set the prediction hint string to deliver to the input panel. * * @since_tizen 4.0 * @@ -2430,7 +2430,7 @@ int ime_device_info_get_subclass(ime_device_info_h dev_info, Ecore_IMF_Device_Su int ime_event_set_prediction_hint_set_cb(ime_prediction_hint_set_cb callback_func, void *user_data); /** - * @brief Sets MIME type event callback function. + * @brief Sets the event callback function that is called when an associated text input UI control requests the text entry to set the MIME type. * * @since_tizen 4.0 * @@ -2573,7 +2573,7 @@ int ime_set_floating_drag_start(void); int ime_set_floating_drag_end(void); /** - * @brief Sets a callback function to give a hint about predicted words. + * @brief Sets the event callback function that is called to set key-value pairs of predicting messages to deliver to the input panel. * * @since_tizen 5.0 * @@ -2656,7 +2656,7 @@ int ime_update_input_panel_event(ime_event_type_e type, unsigned int value); int ime_set_candidate_visibility_state(bool visible); /** - * @brief Sets @c input_hint_set event callback function. + * @brief Sets the event callback function that is called when an associated text input UI control requests the input panel to set input hint. * * @since_tizen 6.5 * @@ -2705,7 +2705,7 @@ int ime_event_set_input_hint_set_cb(ime_input_hint_set_cb callback_func, void *u int ime_event_unset_input_hint_set_cb(void); /** - * @brief Sets ime_position_align_set_cb() event callback function. + * @brief Sets the event callback function that is called when an associated text input UI control sets the position align of the input panel. * * @since_tizen 9.0 * diff --git a/inputmethod/include/inputmethod_internal.h b/inputmethod/include/inputmethod_internal.h index 4a6b007..9f8df8d 100644 --- a/inputmethod/include/inputmethod_internal.h +++ b/inputmethod/include/inputmethod_internal.h @@ -270,7 +270,7 @@ typedef void (*ime_displayed_candidate_number_chaned_cb)(uint32_t page_num, void typedef void (*ime_candidate_item_long_pressed_cb)(uint32_t index, void *user_data); /** - * @brief Sets @c ime_caps_mode_changed_cb() event callback function. + * @brief Sets the event callback function that is called when a caps mode is changed. * * @since_tizen 3.0 * @@ -295,7 +295,7 @@ typedef void (*ime_candidate_item_long_pressed_cb)(uint32_t index, void *user_da int ime_event_set_caps_mode_changed_cb(ime_caps_mode_changed_cb callback_func, void *user_data); /** - * @brief Sets @c ime_candidate_show_cb() event callback function. + * @brief Sets the event callback function that is called when a candidate list provided by IMEngine should be shown. * * @since_tizen 3.0 * @@ -316,10 +316,30 @@ int ime_event_set_caps_mode_changed_cb(ime_caps_mode_changed_cb callback_func, v */ int ime_event_set_candidate_show_cb(ime_candidate_show_cb callback_func, void *user_data); +/** + * @brief Sets the event callback function that is called when a candidate list provided by IMEngine should be hidden. + * + * @since_tizen 3.0 + * + * @privilege %http://tizen.org/privilege/ime + * + * @param[in] callback_func @c ime_candidate_hide_cb() event callback function + * @param[in] user_data User data to be passed to the callback function + * + * @return 0 on success, otherwise a negative error value + * @retval #IME_ERROR_NONE No error + * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function + * @retval #IME_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #IME_ERROR_OPERATION_FAILED Operation failed + * + * @post The ime_run() function should be called to start to run IME application's main loop. + * + * @see ime_run() + */ int ime_event_set_candidate_hide_cb(ime_candidate_hide_cb callback_func, void *user_data); /** - * @brief Sets @c ime_lookup_table_changed_cb() event callback function. + * @brief Sets the event callback function that is called when a candidate list provided by IMEngine is changed. * * @since_tizen 3.0 * @@ -541,7 +561,7 @@ int ime_set_dotnet_flag(bool set); int ime_set_window_creation_defer_flag(bool flag); /** - * @brief Sets @c ime_optimization_hint_set_cb() event callback function. + * @brief Sets the event callback function that is called when a optimization hint value is set. * * @since_tizen 5.0 * @@ -565,7 +585,7 @@ int ime_set_window_creation_defer_flag(bool flag); int ime_event_set_optimization_hint_set_cb(ime_optimization_hint_set_cb callback_func, void *user_data); /** - * @brief Sets @c ime_process_key_event_with_imengine_cb() event callback function. + * @brief Sets the event callback function that is called when a key event is received from external devices or @c ime_send_key_event(). * * @since_tizen 5.5 * @@ -589,7 +609,7 @@ int ime_event_set_optimization_hint_set_cb(ime_optimization_hint_set_cb callback int ime_event_set_process_key_event_with_imengine_cb(ime_process_key_event_with_imengine_cb callback_func, void *user_data); /** - * @brief Sets @c ime_autocapital_type_set_cb() event callback function. + * @brief Sets the event callback function that is called when a autocapital type is set. * * @since_tizen 5.5 * @@ -612,7 +632,7 @@ int ime_event_set_process_key_event_with_imengine_cb(ime_process_key_event_with_ int ime_event_set_autocapital_type_set_cb(ime_autocapital_type_set_cb callback_func, void *user_data); /** - * @brief Sets @c ime_prediction_allow_set_cb() event callback function. + * @brief Sets the event callback function that is called when a prediction allow is set. * * @since_tizen 5.5 * @@ -635,7 +655,7 @@ int ime_event_set_autocapital_type_set_cb(ime_autocapital_type_set_cb callback_f int ime_event_set_prediction_allow_set_cb(ime_prediction_allow_set_cb callback_func, void *user_data); /** - * @brief Sets @c ime_trigger_property_set_cb() event callback function. + * @brief Sets the event callback function that is called when a trigger property value is set. * * @since_tizen 5.5 * @@ -656,7 +676,7 @@ int ime_event_set_prediction_allow_set_cb(ime_prediction_allow_set_cb callback_f int ime_event_set_trigger_property_set_cb(ime_trigger_property_set_cb callback_func, void *user_data); /** - * @brief Sets @c ime_candidate_more_window_show_cb() event callback function. + * @brief Sets the event callback function that is called when a candidate more window is shown. * * @since_tizen 5.5 * @@ -677,7 +697,7 @@ int ime_event_set_trigger_property_set_cb(ime_trigger_property_set_cb callback_f int ime_event_set_candidate_more_window_show_cb(ime_candidate_more_window_show_cb callback_func, void *user_data); /** - * @brief Sets @c ime_candidate_more_window_hide_cb() event callback function. + * @brief Sets the event callback function that is called when a candidate more window is hidden. * * @since_tizen 5.5 * @@ -698,7 +718,7 @@ int ime_event_set_candidate_more_window_show_cb(ime_candidate_more_window_show_c int ime_event_set_candidate_more_window_hide_cb(ime_candidate_more_window_hide_cb callback_func, void *user_data); /** - * @brief Sets @c ime_aux_select_cb() event callback function. + * @brief Sets the event callback function that is called when an AUX item is selected. * * @since_tizen 5.5 * @@ -719,7 +739,7 @@ int ime_event_set_candidate_more_window_hide_cb(ime_candidate_more_window_hide_c int ime_event_set_aux_select_cb(ime_aux_select_cb callback_func, void *user_data); /** - * @brief Sets @c ime_candidate_select_cb() event callback function. + * @brief Sets the event callback function that is called when a candidate item is selected. * * @since_tizen 5.5 * @@ -740,7 +760,7 @@ int ime_event_set_aux_select_cb(ime_aux_select_cb callback_func, void *user_data int ime_event_set_candidate_select_cb(ime_candidate_select_cb callback_func, void *user_data); /** - * @brief Sets @c ime_candidate_table_page_up_cb() event callback function. + * @brief Sets the event callback function that is called when a candidate table page is up. * * @since_tizen 5.5 * @@ -761,7 +781,7 @@ int ime_event_set_candidate_select_cb(ime_candidate_select_cb callback_func, voi int ime_event_set_candidate_table_page_up_cb(ime_candidate_table_page_up_cb callback_func, void *user_data); /** - * @brief Sets @c ime_candidate_table_page_down_cb() event callback function. + * @brief Sets the event callback function that is called when a candidate table page is down. * * @since_tizen 5.5 * @@ -782,7 +802,7 @@ int ime_event_set_candidate_table_page_up_cb(ime_candidate_table_page_up_cb call int ime_event_set_candidate_table_page_down_cb(ime_candidate_table_page_down_cb callback_func, void *user_data); /** - * @brief Sets @c ime_candidate_table_page_size_chaned_cb() event callback function. + * @brief Sets the event callback function that is called when a page size of the candidate window is changed. * * @since_tizen 5.5 * @@ -803,7 +823,7 @@ int ime_event_set_candidate_table_page_down_cb(ime_candidate_table_page_down_cb int ime_event_set_candidate_table_page_size_chaned_cb(ime_candidate_table_page_size_chaned_cb callback_func, void *user_data); /** - * @brief Sets @c ime_candidate_item_layout_set_cb() event callback function. + * @brief Sets the event callback function that is called when a candidate item layout is set. * * @since_tizen 5.5 * @@ -824,7 +844,7 @@ int ime_event_set_candidate_table_page_size_chaned_cb(ime_candidate_table_page_s int ime_event_set_candidate_item_layout_set_cb(ime_candidate_item_layout_set_cb callback_func, void *user_data); /** - * @brief Sets @c ime_displayed_candidate_number_chaned_cb() event callback function. + * @brief Sets the event callback function that is called when a displayed candidate number is changed. * * @since_tizen 5.5 * @@ -845,7 +865,7 @@ int ime_event_set_candidate_item_layout_set_cb(ime_candidate_item_layout_set_cb int ime_event_set_displayed_candidate_number_chaned_cb(ime_displayed_candidate_number_chaned_cb callback_func, void *user_data); /** - * @brief Sets @c ime_candidate_item_long_pressed_cb() event callback function. + * @brief Sets the event callback function that is called when the candidate item is long pressed. * * @since_tizen 5.5 *