[imbus commit] r27 - trunk/imbus/src
codesite...@google.com
Date: Mon Oct 22 08:11:02 2007
New Revision: 27
Modified:
trunk/imbus/src/im_lookup_table.h
trunk/imbus/src/im_properties.h
Log:
Polish the comments of im_property.h and im_lookup_table.h.
Modified: trunk/imbus/src/im_lookup_table.h
==============================================================================
--- trunk/imbus/src/im_lookup_table.h (original)
+++ trunk/imbus/src/im_lookup_table.h Mon Oct 22 08:11:02 2007
@@ -18,23 +18,32 @@
* which can be put into an IMLookupTable object and displayed
by GUI
* component.
*
- * An IMCandidate object may contain the following information:
- * -# Label (IMText) (Optional)\n
- * A text label to indicate the candidate.
- * -# Content (IMText)\n
- * Content of the candidate.
- * -# Icon (IMString) (Optional)\n
- * The file path of an icon that can be displayed along with the
candidate content.
- * -# Annotation (IMObject) (Optional)\n
- * An object to annotate the candidate.
- * If it's an IMText object, then it maybe a description of the candidate.
- * If it's an IMLookupTable object, then it's a sub lookup table associated
- * with the candidate.
- * Default GUI component may only recognize and handle IMText or IMLookupTable
- * annotations.
+ * IMCandidate class shall consist the following kinds of data members
of a candidate phrase.
+ * - Label \n
+ * type: IMText \n
+ * A text label to indicate the candidate on lookup table.
+ * - Content \n
+ * type: IMText \n
+ * Content of the candidate on lookup table. If the content is
empty, UIC may
+ * refuse to render the this item, it depends on the UIC implementation.
+ * - Icon \n
+ * type: IMString \n
+ * The identifier (usually a path name) of an icon that UIC may display
+ * along with the candidate content.
+ * - Annotation \n
+ * type: IMObject \n
+ * An object to annotate the candidate.
+ * If it's an IMText object, then it maybe a description of the candidate.
+ * If it's an IMLookupTable object, then it's a sub lookup table associated
+ * with the candidate.
+ * Default GUI component may only recognize and handle IMText or IMLookupTable
+ * annotations.
+ *
+ * These data members can only be accessed by setter and getter
interfaces of
+ * IMCandidate object. The default values of these data members are null.
*/
-/**
+/**
* @struct IMLookupTable
* @brief IMLookupTable class is used to manipulate a set of
IMCandidate objects.
*
@@ -132,6 +141,10 @@
/**
* @enum IMLookupTableOrientation
* @brief Layout orientation of a lookup table.
+ * - IM_LOOKUP_TABLE_HORIZONTAL \n
+ * the layout orientation is horizontal
+ * - IM_LOOKUP_TABLE_VERTICAL \n
+ * the layout orientation is vertical
*/
typedef enum {
IM_LOOKUP_TABLE_HORIZONTAL = 0,
@@ -174,22 +187,26 @@
/**
* @brief Creates a new IMCandidate with specified content.
*
- * @param content an IMText of the candidate's content.
*
- * @returns a new IMCandidate.
+ * @param content an IMText of the candidate's content. The
content object
+ * will only be referenced rather than cloned.
+ *
+ * @return a new IMCandidate.
*/
IMCandidate* im_candidate_new (IMText
*content);
/**
* @brief Creates a new IMCandidate with specified content, label,
icon and
- * annotation.
+ * annotation.
*
* @param content an IMText of the candidate's content.
* @param label an IMText of the candidate's label.
* @param icon an IMText of the candidate's icon.
* @param annotation an IMPointer of annotation data for the candidate.
*
- * @returns the new IMCandidate.
+ * The objects in parameter list will only be referenced rather than cloned.
+ *
+ * @return a new IMCandidate.
*/
IMCandidate* im_candidate_new_full (IMText
*content,
IMText
*label,
@@ -201,6 +218,8 @@
*
* @param candidate an IMCandidate.
* @param content the new content for candidate.
+ *
+ * The content object will only be referenced rather than cloned.
*/
void im_candidate_set_content (IMCandidate
*candidate,
IMText
*content);
@@ -210,7 +229,7 @@
*
* @param candidate an IMCandidate.
*
- * @returns the candidate's content.
+ * @return the candidate's content, that you should not free.
*/
IMText* im_candidate_get_content (const IMCandidate
*candidate);
@@ -219,6 +238,8 @@
*
* @param candidate an IMCandidate.
* @param label the new label for candidate.
+ *
+ * The label object will only be referenced rather than cloned.
*/
void im_candidate_set_label (IMCandidate
*candidate,
IMText
*label);
@@ -227,7 +248,7 @@
*
* @param candidate an IMCandidate.
*
- * @returns the candidate's label.
+ * @return the candidate's label, that you should not free.
*/
IMText* im_candidate_get_label (const IMCandidate
*candidate);
@@ -236,6 +257,8 @@
*
* @param candidate an IMCandidate.
* @param icon the new icon file path for candidate.
+ *
+ * The icon identifier object will only be referenced rather than cloned.
*/
void im_candidate_set_icon (IMCandidate
*candidate,
IMString
*icon);
@@ -245,7 +268,7 @@
*
* @param candidate an IMCandidate.
*
- * @returns the candidate's icon file path.
+ * @return the candidate's icon file path, that you should not free.
*/
IMString* im_candidate_get_icon (const IMCandidate
*candidate);
@@ -254,6 +277,8 @@
*
* @param candidate an IMCandidate.
* @param annotation the new annotation data for candidate.
+ *
+ * The annotation object will only be referenced rather than cloned.
*/
void im_candidate_set_annotation (IMCandidate
*candidate,
IMPointer
*annotation);
@@ -263,7 +288,7 @@
*
* @param candidate an IMCandidate.
*
- * @returns the candidate's annotation data.
+ * @return the candidate's annotation data, that you should not free.
*/
IMPointer im_candidate_get_annotation (const IMCandidate
*candidate);
@@ -278,7 +303,7 @@
*
* @param uid a unique ID to identify this IMLookupTable.
*
- * @returns a new IMLookupTable.
+ * @return a new IMLookupTable.
*/
IMLookupTable* im_lookup_table_new (IMUInt32
uid);
@@ -294,7 +319,7 @@
* @param cols number of columns in the lookup table.
* @param rows number of rows in the lookup table.
*
- * @returns a new IMLookupTable.
+ * @return a new IMLookupTable.
*/
IMLookupTable* im_lookup_table_new_full (IMUInt32
uid,
IMUInt
orientation,
@@ -325,16 +350,16 @@
*
* @param table an IMLookupTable.
*
- * @returns the unique ID.
+ * @return the unique ID.
*/
IMUInt32 im_lookup_table_get_unique_id (const IMLookupTable
*table);
/**
* @brief Sets the layout orientation of an IMLookupTable.
*
- * @param table an IMLookupTable.
+ * @param table an IMLookupTable.
* @param orientation can be IM_LOOKUP_TABLE_HORIZONTAL or
- * IM_LOOKUP_TABLE_VERTICAL.
+ * IM_LOOKUP_TABLE_VERTICAL.
*/
void im_lookup_table_set_orientation (IMLookupTable
*table,
IMUInt
orientation);
@@ -344,7 +369,7 @@
*
* @param table an IMLookupTable.
*
- * @returns the layout orientation, either IM_LOOKUP_TABLE_HORIZONTAL or
+ * @return the layout orientation, either IM_LOOKUP_TABLE_HORIZONTAL or
* IM_LOOKUP_TABLE_VERTICAL.
*/
IMUInt im_lookup_table_get_orientation (const IMLookupTable
*table);
@@ -369,6 +394,10 @@
IMUInt
rows);
/**
* @brief Get lookup table's page size
+ *
+ * @param table an IMLookupTable.
+ * @param cols number of columns (X size).
+ * @param rows number of rows (Y size).
*/
void im_lookup_table_get_page_size (const IMLookupTable
*table,
IMUInt
*cols,
@@ -376,41 +405,60 @@
/**
* @brief Set cursor position (the currently focused candidate)
* in current page.
+ *
+ * @param table an IMLookupTable.
+ * @param cur the cursor index in that table, if beyonds the
last element,
+ * it will be set to the end (i.e. columns*rows - 1).
*/
void im_lookup_table_set_cursor (IMLookupTable
*table,
IMUInt
cur);
/**
* @brief Get cursor position (the currently focused candidate).
+ *
+ * @param table an IMLookupTable.
+ *
+ * @return the cursor index.
*/
IMUInt im_lookup_table_get_curosr (const IMLookupTable
*table);
/**
* @brief Enable various flags for a lookup table to adjust its behaviour.
+ *
+ * @param table an IMLookupTable.
+ * @param flags the flags (bitmask of IMLookupTableFlag) of lookup table.
*/
void im_lookup_table_enable_flags (IMLookupTable
*table,
IMUInt
flags);
/**
* @brief Disable various flags for a lookup table to adjust its behaviour.
+ *
+ * @param table an IMLookupTable.
+ * @param flags the flags (bitmask of IMLookupTableFlag) of lookup table.
*/
void im_lookup_table_disable_flags (IMLookupTable
*table,
IMUInt
flags);
/**
* @brief Check whether one or more flags is enabled or not.
+ *
+ * @param table an IMLookupTable.
+ * @param flags the flags (bitmask of IMLookupTableFlag) of lookup table.
*/
IMBool im_lookup_table_check_flags (const IMLookupTable
*table,
IMUInt
flags);
/**
* @brief Set title of a lookup table.
*
- * The title is a IMText object, which can have text attributes to decorate
- * text.
+ * @param table an IMLookupTable.
+ * @param title an IMText object, which can have text attributes
to decorate the text.
*/
void im_lookup_table_set_title (IMLookupTable
*table,
IMText
*title);
/**
* @brief Get title of a lookup table.
*
+ * @param table an IMLookupTable.
+ *
* @return The IMText object used by the lookup table object as title,
* 0 if there is no title. It shouldn't be modified or released
* by caller.
@@ -424,16 +472,16 @@
* displayed among all pages.
* The scroll bar is also clickable by user to generate page flip event.
*
- * @param table A IMLookupTable object
+ * @param table an IMLookupTable object
* @param num_pages Number of pages totally available.
- * @param cur_page Current page is being displayed,
+ * @param cur_page Current page is being displayed,
* must between 0 to (num_pages - 1).
* If it's 0, then the scroll bar cursor will be at beginning
* position, and the page up button will be inactivated,
* so that user can't do page up.
* If it's num_pages - 1, then the scroll bar cursor will be at
* ending position, and the page down button will be inactivated,
- * so that user can't do page done.
+ * so that user can't do page down.
*/
void im_lookup_table_set_scroll_info (IMLookupTable
*table,
IMUInt
num_pages,
@@ -441,6 +489,10 @@
/**
* @brief Get scroll bar information of a lookup table.
+ *
+ * @param table an IMLookupTable object
+ * @param num_pages Number of pages totally available.
+ * @param cur_page Current page is being displayed,
*/
void im_lookup_table_get_scroll_info (const IMLookupTable
*table,
IMUInt
*num_pages,
@@ -459,9 +511,10 @@
IMCandidate
*candidate);
/**
* @brief Get the candidate at specified index.
- * @param table a IMLookupTable object
- * @param index candidate index to be get. Must be 0 to (page_size - 1).
- * page_size = cols * rows.
+ *
+ * @param table an IMLookupTable object
+ * @param index candidate index to be get. Must be 0 to (page_size
- 1).
+ * page_size = cols * rows.
* @return The IMCandidate object. Or 0 if the candidate is empty.
*/
IMCandidate* im_lookup_table_get_candidate (const IMLookupTable
*table,
Modified: trunk/imbus/src/im_properties.h
==============================================================================
--- trunk/imbus/src/im_properties.h (original)
+++ trunk/imbus/src/im_properties.h Mon Oct 22 08:11:02 2007
@@ -12,76 +12,84 @@
* @{
*/
-/** @struct IMProperty
- * @brief An object holds a property of an IMBUS component.
- *
- * A property of an IMBUS component represents a state or
- * a switch of the component, such as current input mode or
- * something like that.
- *
- * GUI component can accept properties registered by other IMBUS
- * components and draw them on screen in arbitrary form
- * (a button, a label, etc.)
- *
- * User can trigger a property by specified method, such as by
- * clicking on it. An event will be sent back to the component
- * which owns the property as soon as it's triggered by user.
- * So that the component can adjust its internal state accordingly.
- *
- * There are four @copydoc IMPropertyType
- *
- * A property contains the following elements:
- * - key: (const char*) \n
- * An unique string key to identify the property.
- * A separator property should have an unique string key as well,
- * so that it can be manipulated by IMPropList object.
- * - label: (IMText*) \n
- * A human readable text label which will be displayed on
- * the screen.
- * It doesn't apply to separator property.
- * - icon: (const char*) \n
- * An icon file which will be displayed on the screen along
- * with label.
- * It doesn't apply to separator property.
- * - tip: (IMText*) \n
- * A human readable text to describe the meaning of the property,
- * which may be displayed on the screen.
- * It doesn't apply to separator property.
- * - flags: (IMUInt32) \n
- * Flags to indicate various states of the property, such as
- * whether it's active or not.
- * It doesn't apply to separator property.
- * - sub_props: (IMPropList *) \n
- * Optionally a IMPropList object contains one or more sub-properties.
- * With sub-properties list, we can organize multiple properties
- * in hierarchy style.
- * It doesn't apply to separator property.
- *
- * Multiple properties can be organized in hierarchy style
- * by attaching a IMPropList object, which contains sub-properties,
- * to a property. A property with sub-properties attached becomes
- * root property. Normally user may not trigger a root property.
- *
- * A reasonable screen display form of a multi-level properties
- * hierarchy can look like a menu:
- *
- * @code
- * +-------+
- * | prop1 |
- * | prop2-+->+-------+
- * | prop3 | | prop5 |
- * |-------| | prop6-+->+-------+
- * | prop4 | | prop7 | | prop8 |
- * +-------+ +-------+ | prop9 |
- * +-------+
- * @endcode
- *
- * In such case, prop2 is root property of prop5,prop6 and prop7.
- * While prop6 is root property of prop8 and prop9. So user may
- * not trigger prop2 and prop6.
+/**
+ * @struct IMProperty
+ * @brief An object holds a property of an IMBUS component.
+ *
+ * A property of an IMBUS component represents a state or
+ * a switch of the component, such as current input mode or
+ * something like that.
+ *
+ * GUI component can accept properties registered by other IMBUS
+ * components and draw them on screen in arbitrary form
+ * (a button, a label, etc.)
+ *
+ * User can trigger a property by specified method, such as by
+ * clicking on it. An event will be sent back to the component
+ * which owns the property as soon as it's triggered by user.
+ * So that the component can adjust its internal state accordingly.
+ *
+ * There are four @copydoc IMPropertyType
+ *
+ * A property contains the following elements:
+ * - Key \n
+ * type: const char* \n
+ * An unique string key to identify the property.
+ * A separator property should have an unique string key as well,
+ * so that it can be manipulated by IMPropList object.
+ * - Label \n
+ * type: IMText* \n
+ * A human readable text label which will be displayed on
+ * the screen.
+ * It doesn't apply to separator property.
+ * - Icon \n
+ * type: const char* \n
+ * An icon file which will be displayed on the screen along
+ * with label.
+ * It doesn't apply to separator property.
+ * - Tip \n
+ * type: IMText* \n
+ * A human readable text to describe the meaning of the property,
+ * which may be displayed on the screen.
+ * It doesn't apply to separator property.
+ * - Flags
+ * type: IMUInt32 \n
+ * Flags to indicate various states of the property, such as
+ * whether it's active or not.
+ * It doesn't apply to separator property.
+ * - Sub Properties \n
+ * type: IMPropList * \n
+ * Optionally a IMPropList object contains one or more sub-properties.
+ * With sub-properties list, we can organize multiple properties
+ * in hierarchy style.
+ * It doesn't apply to separator property.
+ *
+ * Multiple properties can be organized in hierarchy style
+ * by attaching a IMPropList object, which contains sub-properties,
+ * to a property. A property with sub-properties attached becomes
+ * root property. Normally user may not trigger a root property.
+ *
+ * A reasonable screen display form of a multi-level properties
+ * hierarchy can look like a menu:
+ *
+ * @code
+ * +-------+
+ * | prop1 |
+ * | prop2-+->+-------+
+ * | prop3 | | prop5 |
+ * |-------| | prop6-+->+-------+
+ * | prop4 | | prop7 | | prop8 |
+ * +-------+ +-------+ | prop9 |
+ * +-------+
+ * @endcode
+ *
+ * In such case, prop2 is root property of prop5,prop6 and prop7.
+ * While prop6 is root property of prop8 and prop9. So user may
+ * not trigger prop2 and prop6.
*/
-/** @struct IMPropList
+/**
+ * @struct IMPropList
* @brief An object to hold multiple properties.
*
* When an IMBUS component wants to send some properties to
@@ -90,7 +98,8 @@
* component.
*/
-/** @struct IMPropIterator
+/**
+ * @struct IMPropIterator
* @brief Iterator of IMPropList to iterate all properties
* stored in a IMPropList object.
*/
@@ -131,30 +140,31 @@
typedef struct _IMPropIterator IMPropIterator;
-/** @enum IMPropertyType
+/**
+ * @enum IMPropertyType
* @brief types of an IMProperty.
*
- * - IM_PROPERTY_NORMAL \n
- * Normal property that represents a state of IMBUS component.
- * It can be triggerred by user.
- * Normal property may be displayed as a normal button or menu
- * item by GUI component.
- * - IM_PROPERTY_SWITCH \n
- * Like normal property, a switch property can represent a state
- * of IMBUS component and can be triggerred by user.
- * But GUI component may display a switch property with different
- * appearance which indicates that it can be turned on or off
- * (selected or deselected).
- * - IM_PROPERTY_RADIO \n
- * Similar than switch property, but it may have a different
- * appearance which indicates that it's one of an items group,
- * in which only one item can be selected at one time. Just
- * like radio buttons widget used in GUI interface.
- * - IM_PROPERTY_SEPARATOR \n
- * A separator property doesn't carry any state information of IMBUS
- * component. It will just be displayed as a separator to split
- * other properties into different groups.
- * Thus it can't be triggerred by user.
+ * - IM_PROPERTY_NORMAL \n
+ * Normal property that represents a state of IMBUS component.
+ * It can be triggerred by user.
+ * Normal property may be displayed as a normal button or menu
+ * item by GUI component.
+ * - IM_PROPERTY_SWITCH \n
+ * Like normal property, a switch property can represent a state
+ * of IMBUS component and can be triggerred by user.
+ * But GUI component may display a switch property with different
+ * appearance which indicates that it can be turned on or off
+ * (selected or deselected).
+ * - IM_PROPERTY_RADIO \n
+ * Similar than switch property, but it may have a different
+ * appearance which indicates that it's one of an items group,
+ * in which only one item can be selected at one time. Just
+ * like radio buttons widget used in GUI interface.
+ * - IM_PROPERTY_SEPARATOR \n
+ * A separator property doesn't carry any state information of IMBUS
+ * component. It will just be displayed as a separator to split
+ * other properties into different groups.
+ * Thus it can't be triggerred by user.
*/
typedef enum
{
@@ -164,7 +174,8 @@
IM_PROPERTY_SEPARATOR
} IMPropertyType;
-/** @enum IMPropertyFlag
+/**
+ * @enum IMPropertyFlag
* @brief Flags to control various behaviours of an IMProperty.
*
* - IM_PROPERTY_SENSITIVE \n
@@ -197,6 +208,12 @@
/**
* @brief Create a new property with a specified key string.
*
+ * @param key the string id of this property, does not check the key duplication.
+ *
+ * @return the newly created IMProperty object.
+ *
+ * The key IMString object will only be referenced rather than cloned.
+ *
* The default type is IM_PROPERTY_NORMAL, default flag is
* IM_PROPERTY_SENSITIVE|IM_PROPERTY_VISIBLE
*/
@@ -204,6 +221,18 @@
/**
* @brief Create a new property with specified parameters.
+ *
+ * @param type the IMPropertyType
+ * @param flags bitmask of IMPropertyFlag(s)
+ * @param key the string id of this property
+ * @param icon the icon id of this property
+ * @param label the label (IMText*) of this property
+ * @param tip the tip (IMText*) of this property
+ *
+ * The objects (not primitive types) in parameter list will only be referenced
+ * rather than cloned.
+ *
+ * @return the newly created IMProperty object.
*/
IMProperty* im_property_new_full (IMPropertyType
type,
IMUInt
flags,
@@ -214,6 +243,9 @@
/**
* @brief Set the type of specified property.
*
+ * @param prop an IMProperty
+ * @param type an IMPropertyType
+ *
* If the type is set to IM_PROPERTY_SEPARATOR, all original
information, except
* the string key, will be lost.
*/
@@ -221,63 +253,106 @@
IMPropertyType
type);
/**
* @brief Get the type of specified property.
+ *
+ * @param prop an IMProperty
+ *
+ * @return the property type
*/
IMPropertyType im_property_get_type (const IMProperty
*prop);
/**
* @brief Enable various flags for a property to adjust its behaviour.
+ *
+ * @param prop an IMProperty
+ * @param flags the bitmask of IMPropertyFlag(s)
*/
void im_property_enable_flags (IMProperty
*prop,
IMUInt
flags);
/**
* @brief Disable various flags for a property to adjust its behaviour.
+ *
+ * @param prop an IMProperty
+ * @param flags the bitmask of IMPropertyFlag(s)
*/
void im_property_disable_flags (IMProperty
*prop,
IMUInt
flags);
/**
* @brief Check whether one or more flags is enabled or not.
+ *
+ * @param prop an IMProperty
+ * @param flags the bitmask of IMPropertyFlag(s)
*/
IMBool im_property_check_flags (const IMProperty
*prop,
IMUInt
flags);
/**
* @brief Set key string of a property.
+ *
+ * @param prop an IMProperty
+ * @param key the string id
+ *
+ * The key IMString object will only be referenced rather than cloned.
*/
void im_property_set_key (IMProperty
*prop,
IMString
*key);
/**
* @brief Get key string of a specified IMProperty object.
+ *
+ * @param prop an IMProperty
+ *
+ * @return the string id
*/
IMString* im_property_get_key (const IMProperty
*prop);
/**
* @brief Set icon file of a property.
+ *
+ * @param prop an IMProperty
+ * @param icon the icon path
+ *
+ * The icon IMString object will only be referenced rather than cloned.
*/
void im_property_set_icon (IMProperty
*prop,
IMString
*icon);
/**
* @brief Get icon file path of a specified IMProperty object.
+ *
+ * @param prop an IMProperty
+ *
+ * @return the icon path
*/
IMString* im_property_get_icon (const IMProperty
*prop);
/**
* @brief Set the label of a specofied IMProperty object.
*
- * The label IMText object will only be referenced rather than
- * cloning.
+ * @param prop an IMProperty
+ * @param label the label object
+ *
+ * The label IMText object will only be referenced rather than cloned.
*/
void im_property_set_label (IMProperty
*prop,
IMText
*label);
/**
* @brief Get tje label of a specified IMProperty object.
+ *
+ * @param prop an IMProperty
+ *
+ * @return the label object
*/
IMText* im_property_get_label (const IMProperty
*prop);
/**
* @brief Set the tip of a specofied IMProperty object.
*
- * The tip IMText object will only be referenced rather than
- * cloning.
+ * @param prop an IMProperty
+ * @param tip the tip object
+ *
+ * The tip IMText object will only be referenced rather than cloned.
*/
void im_property_set_tip (IMProperty
*prop,
IMText
*tip);
/**
* @brief Get the tip of a specified IMProperty object.
+ *
+ * @param prop an IMProperty
+ *
+ * @return the tip object
*/
IMText* im_property_get_tip (const IMProperty
*prop);
@@ -285,15 +360,19 @@
* @brief Attach or remove a list of sub properties
* to a specified property.
*
- * @param prop A specified property.
- * @param subprops A IMPropList object contains one or more sub properties,
- * or 0 to remove the old list.
+ * @param prop an IMProperty
+ * @param subprops an IMPropList object contains one or more sub properties,
+ * or 0 to remove the old list.
+ *
+ * The subprops IMPropList object will only be referenced rather than cloned.
*/
void im_property_set_sub_props (IMProperty
*prop,
IMPropList
*subprops);
/**
* @brief Get sub properties list attached to a specified property.
*
+ * @param prop an IMProperty
+ *
* @return The IMPropList object which contains sub properties,
* or 0 if there is no sub properties.
* Caller shouldn't modify or release the returned object.
@@ -302,78 +381,129 @@
/**
* @brief Create a new IMPropList object.
+ *
+ * @return the newly created IMPropList.
*/
IMPropList* im_prop_list_new ();
/**
* @brief Clear an IMPropList object. All IMProperty objects held by
* it will be released.
+ *
+ * @param list an IMPropList
*/
void im_prop_list_clear (IMPropList
*list);
/**
* @brief Check whether a specified IMPropList object is empty or not.
+ *
+ * @param list an IMPropList
+ * @return TRUE if list is an IMPropList, else FALSE;
*/
IMBool im_prop_list_empty (const IMPropList
*list);
/**
* @brief Append an IMProperty object into a specified IMPropList object.
+ *
+ * @param list an IMPropList
+ * @param prop an IMProperty
*/
void im_prop_list_append (IMPropList
*list,
IMProperty
*prop);
/**
* @brief Remove a IMProperty object with specified key
* from a specified IMPropList object.
+ *
+ * @param list an IMPropList
+ * @param key the key of an IMProperty
*/
void im_prop_list_remove (IMPropList
*list,
const IMChar
*key);
/**
* @brief Get a IMProperty object with specified key stored in
* a specified IMPropList object.
+ *
+ * @param list an IMPropList
+ * @param key the key of an IMProperty
+ *
+ * @return the IMProperty object with the specified key.
*/
IMProperty* im_prop_list_get (const IMPropList
*list,
const IMChar
*key);
/**
* @brief Call a specified function against each IMProperty objects
stored in
* a specified IMPropList object.
+ *
+ * @param list an IMPropList
+ * @param func the iterator callback function
+ * @param user_data the user data passed to the callback function
*/
void im_prop_list_foreach (const IMPropList
*list,
IMFunc
func,
IMPointer
user_data);
/**
* @brief Create an iterator for a specified IMPropList object.
+ *
+ * @param list an IMPropList
+ *
+ * @return an iterator
*/
IMPropIterator* im_prop_list_get_iterator (IMPropList
*list);
/**
* @brief Clone a IMPropIterator structure.
+ *
+ * @param iter an IMPropIterator
+ *
+ * @return the cloned iterator
*/
IMPropIterator* im_prop_iterator_clone (const
IMPropIterator *iter);
/**
* @brief Destroy a IMPropIterator instance.
+ *
+ * @param iter an IMPropIterator
*/
void im_prop_iterator_destroy (IMPropIterator
*iter);
/**
* @brief Advance a IMPropIterator instance to point to the next
* IMProperty object inside its associated IMPropList object.
+ *
+ * @param an IMPropIterator
+ *
+ * @return TRUE if the current list has next element, else FALSE.
*/
IMBool im_prop_iterator_next (IMPropIterator
*iter);
/**
* @brief Get the IMProperty object pointed by a specified IMPropIterator
* instance.
+ *
+ * @param an IMPropIterator
+ *
+ * @return the IMProperty object associated with this iterator
*/
IMProperty* im_prop_iterator_get (const
IMPropIterator *iter);
/**
* @brief Check whether a IMPropIterator instance is pointed to a valid
* IMProperty object.
+ *
+ * @param an IMPropIterator
+ *
+ * @return TRUE if the iterator refers to a valid IMProperty object,
else FALSE.
*/
IMBool im_prop_iterator_valid (const
IMPropIterator *iter);
/**
* @brief Check whether two IMPropIterator instances point to the same
* IMProperty object or not.
+ *
+ * @param iter1 an IMPropIterator
+ * @param iter2 another IMPropIterator
+ *
+ * @return TRUE if iter1 and iter2 point to the same IMProperty
object, else FALSE.
*/
IMBool im_prop_iterator_equal (const
IMPropIterator *iter1,
const
IMPropIterator *iter2);
/**
* @brief Remove the IMProperty object pointed by specified IMPropIterator
- * instance from its associated IMPropList object,
+ * instance from its associated IMPropList object.
+ *
+ * @param iter an IMPropIterator
*/
void im_prop_iterator_remove (IMPropIterator
*iter);