[imbus commit] r33 - trunk/imbus/src

[codesite...@google.com]

Author: choe.hwanjin
Date: Tue Oct 23 01:52:17 2007
New Revision: 33

Modified:
trunk/imbus/src/im_attributes.h

Log:
Update comments for IMAttribute

Modified: trunk/imbus/src/im_attributes.h
==============================================================================
--- trunk/imbus/src/im_attributes.h (original)
+++ trunk/imbus/src/im_attributes.h Tue Oct 23 01:52:17 2007
@@ -340,160 +340,527 @@
/**
* @brief Create an empty IMAttribute object with a specific attribute type.
*
+ * This function creates an empty instance of IMAttribute with IMType
which is
+ * specified by parameter type.
+ *
* @param type The type of newly created attribute object,
- * it must be derived rom IM_TYPE_ATTRIBUTE.
+ * it shall be derived from IM_TYPE_ATTRIBUTE.
+ * @return newly created instance of IMAttribute which shall be
unreferenced by
+ * im_object_unref when no longer needed or NULL if type is
not an
+ * IM_TYPE_ATTRIBUTE type.
*/
IMAttribute* im_attribute_new (IMType
type);
/**
* @brief Clear the content of an attribute.
+ *
+ * This function clears the content of the argument attr, or do
nothing if the
+ * pointer specified by the argument attr is not IMAttribute type.
+ *
+ * @param attr a pointer to an instance of IMAttribute
+ *
+ * @return This function returns no value.
*/
void im_attribute_clear (IMAttribute
*attr);
/**
* @brief Set the start position of an attribute.
+ *
+ * This function sets the start position of the range where the
argument attr
+ * is applied as the argument start. If the argument start is greater
than the
+ * end, the end position shall be changed to same position as the argument
+ * start. If the argument attr is not a pointer to an instance of IMAttribute
+ * type, this function shall do nothing.
+ *
+ * @param attr a pointer to an instance of IMAttribute
+ * @param start new start position
+ *
+ * @return This function returns no value.
*/
void im_attribute_set_start (IMAttribute
*attr,
IMUInt
start);
/**
* @brief Set the end position of an attribute.
+ *
+ * This function sets the end position of the range where the argument
attr is
+ * applied as the argument end. If the argument end is less than the start
+ * position, the start position shall be changed to same position as the
+ * argument end. The end poisition itself shall not be included in the
range of
+ * the argument attr. If the argument attr is not a pointer to an
instance of
+ * IMAttribute type, this function shall do nothing.
+ *
+ * @param attr a pointer to an instance of IMAttribute
+ * @param end new end value.
+ *
+ * @return This function returns no value.
*/
void im_attribute_set_end (IMAttribute
*attr,
IMUInt
end);
/**
* @brief Set the length of an attribute.
*
- * The end position of this attribute will be adjusted accordingly.
+ * This function shall adjust the end position of the argument attr according
+ * to the argument length. The length is defined as the difference
between the
+ * start and the end. If the argument attr is not a pointer to an
instance of
+ * IMAttribute type, this function shall do nothing.
+ *
+ * @param attr a pointer to an instance of IMAttribute
+ * @param length the new length for the arugment attr
+ *
+ * @return This function returns no value.
*/
void im_attribute_set_length (IMAttribute
*attr,
IMUInt
length);
/**
* @brief Get the range of an attribute.
+ *
+ * This function shall copy the start and end of the range of the argument
+ * attr. If the argument start or end is NULL, this function shall not copy
+ * the values. If the argument attr is not a pointer to an instance of
+ * IMAttribute type, this function shall do nothing and the value of the
+ * argument start and end are not defined.
+ *
+ * @param attr a pointer to an instance of IMAttribute
+ * @param start a pointer to IMUInt where the start value shall be copied
+ * @param end a pointer to IMUInt where the end value shall be copied
+ *
+ * @return This function returns no value.
*/
void im_attribute_get_range (const
IMAttribute *attr,
IMUInt
*start,
IMUInt
*end);
/**
* @brief Set the range of an attribute.
+ *
+ * This function sets the range where the argument attr is applied
according to
+ * the argument start and the arugment end. If the arugment start is greater
+ * than the argument end, the argument end shall be the start position
and the
+ * argument start shall be the end position. If the argument attr is
not a
+ * pointer to an instance of IMAttribute type, this function shall do nothing.
+ *
+ * @param attr a pointer to an instance of IMAttribute
+ * @param start new start position
+ * @param end new end position
+ *
+ * @return This function returns no value.
*/
void im_attribute_set_range (IMAttribute
*attr,
IMUInt
start,
IMUInt
end);
/**
* @brief Check whether two attributes are equal.
- * @return TRUE if the two attributes are the same type, and have the
same value.
*
- * Only content of the attributes will be compared.
- * Their range will not be taken into account.
+ * This function compares the argument attr1 and the argument attr2. Only
+ * content of the attributes shall be compared. Their range will not
be taken
+ * into account. If the arguments attr1 or attr2 is NULL or not a type of
+ * IMAttribute, this function shall return FALSE. If the arguments are
not the
+ * same type, this function also return FALSE.
+ *
+ * @param attr1 a pointer to an instance of IMAttribute.
+ * @param attr2 a pointer to an instance of IMAttribute.
+ *
+ * @return TRUE if the two argument are the same type and have the
same value,
+ * or FALSE.
*/
IMBool im_attribute_equal (const
IMAttribute *attr1,
const
IMAttribute *attr2);

-/** @brief Create a new language attribute object. */
+/**
+ * @brief Create a new language attribute object.
+ *
+ * This function create a new instance of IM_TYPE_ATTR_LANGUAGE IMAttribute.
+ *
+ * @param lang a pointer to a language code string, which is specified
by ISO639-1.
+ * @return newly created IMAttribute instance pointer. This pointer
shall be
+ * unrefenced by im_object_unref when no longer needed.
+ */
IMAttribute* im_attr_language_new (const IMChar
*lang);
/**
* @brief Get the language string from the given attribute object.
*
- * The returned language string should not be released by caller.
+ * This function returns the language code string the the argument
attr. If the
+ * argument attr is not a IM_TYPE_LANGUAGE type, this function shall return
+ * NULL.
+ *
+ * @param a pointer to an instance of IMAttribute.
+ *
+ * @return a pointer to the language code, which shall not be changed
by user
+ * or freed.
*/
const IMChar* im_attr_language_get (const
IMAttribute *attr);
/**
* @brief Set the language in the given attribute object.
*
- * In the attribute object, the original language string would be released,
- * and replaced by a new copy of the given string.
+ * This function shall change the language code string which the
argument attr
+ * represents with the argument lang.
+ *
+ * @param attr a pointer to an instance of IMAttribute.
+ * @param lang a pointer to the language code string.
+ *
+ * @return This function returns no value.
*/
void im_attr_language_set (IMAttribute
*attr,
const IMChar
*lang);
-/** @brief Set the language in the given attribute object with a
static string. */
+/**
+ * @brief Set the language in the given attribute object with a
static string.
+ *
+ * This function shall set the language code string as the argument
lang, so
+ * the argument lang shall be available through the life time of the argument
+ * attr.
+ *
+ * @param attr a pointer to an instance of IMAttribute.
+ * @param lang a pointer to the language code string.
+ *
+ * @return This function returns no value.
+ */
void im_attr_language_set_static (IMAttribute
*attr,
const IMChar
*lang);

-/** @brief Create a new font family attribute object. */
+/**
+ * @brief Create a new font family attribute object.
+ *
+ * This function creates a new instance of IMAttribute of IM_TYPE_ATTR_FONT_FAMILY.
+ *
+ * @param family string to the font family name.
+ *
+ * @return This function returns a newly created instance of IM_TYPE_FONTFAMILY
+ * type IMAttribute.
+ */
IMAttribute* im_attr_font_family_new (const IMChar
*family);
/**
* @brief Get the font family string from the given attribute object.
*
- * The returned font family string should not be released by caller.
+ * This function returns the font family name string, which the
argument attr
+ * represents.
+ *
+ * @param attr a pointer to an instance of IMAttribute.
+ *
+ * @return This function returns the font family string, which shall
not be
+ * modified or freed by user.
*/
const IMChar* im_attr_font_family_get (const
IMAttribute *attr);
/**
* @brief Set the font family in the given attribute object.
*
- * In the attribute object, the original font family string would be released,
- * and replaced by a new copy of the given string.
+ * This function changes the font family name of the argument attr
with the
+ * argument family.
+ *
+ * @param attr a pointer to an instance of IMAttribute.
+ * @param family a pointer to the font family name string.
+ *
+ * @return This function returns no value.
*/
void im_attr_font_family_set (IMAttribute
*attr,
const IMChar
*family);
-/** @brief Set the font family in the given attribute object with a
static string. */
+/**
+ * @brief Set the font family in the given attribute object with a
static string.
+ *
+ * This function shall set the font family name string as the argument family,
+ * so the argument family shall be available through the life time of the
+ * argument attr.
+ *
+ * @param attr a pointer to an instance of IMAttribute.
+ * @param family a pointer to the font family name string.
+ *
+ * @return This function returns no value.
+ */
void im_attr_font_family_set_static (IMAttribute
*attr,
const IMChar
*family);

-/** @brief Create a new font style attribute object. */
+/**
+ * @brief Create a new font style attribute object.
+ *
+ * This function returns a newly created IM_TYPE_ATTR_FONT_STYLE type IMAttribute.
+ *
+ * @param style an IMAttrFontStyle value to specify font style.
+ *
+ * @return This function returns a pointer to an instance of
IMAttribute, which
+ * shall be unreferenced when no longer needed.
+ */
IMAttribute* im_attr_font_style_new
(IMAttrFontStyle style);
-/** @brief Get the font style from the given attribute object. */
+/**
+ * @brief Get the font style from the given attribute object.
+ *
+ * This function returns font style value which the argument attr represents.
+ *
+ * @param attr a pointer to an instance of IMAttribute.
+ *
+ * @return This function returns IMAttrFontStyle value which the
argument attr
+ * represents. If the argument attr is not an IM_TYPE_ATTR_FONT_STYLE,
+ * this function returns IM_ATTR_FONT_STYLE_NORMAL.
+ */
IMAttrFontStyle im_attr_font_style_get (const
IMAttribute *attr);
-/** @brief Set the font style in the given attribute object. */
+/**
+ * @brief Set the font style in the given attribute object.
+ *
+ * This function changes the font style value of the argument attr
with the
+ * argument style. If the argument attr is not a type of
+ * IM_TYPE_ATTR_FONT_STYLE, this function shall do nothing.
+ *
+ * @param attr a pointer to an instance of IMAttribute.
+ * @param style an IMAttrFontStyle value to specify font style.
+ *
+ * @return This function returns no value.
+ */
void im_attr_font_style_set (IMAttribute
*attr,

IMAttrFontStyle style);

-/** @brief Create a new font weight attribute object. */
+/**
+ * @brief Create a new font weight attribute object.
+ *
+ * This function returns a newly created IMAttribute which represents font
+ * weight.
+ *
+ * @param weight IMAttrFontWeight value to specify font weight.
+ *
+ * @return This function returns a newly created
IM_TYPE_ATTR_FONT_WEIGHT type
+ * IMAttribute pointer, which shall be unreferenced when no longer
+ * needed.
+ */
IMAttribute* im_attr_font_weight_new
(IMAttrFontWeight weight);
-/** @brief Get the font weight from the given attribute object. */
+/**
+ * @brief Get the font weight from the given attribute object.
+ *
+ * This function returns the font weight value which the argument attr
+ * represents.
+ *
+ * @param attr a pointer to an instance of IMAttribute.
+ *
+ * @return This function returns IMAttrFontWeight value which the argument
+ * attr represents, or IM_ATTR_FONT_WEIGHT_NORMAL if the
argument attr
+ * is not an IM_TYPE_ATTR_FONT_WEIGHT type.
+ */
IMAttrFontWeight im_attr_font_weight_get (const
IMAttribute *attr);
-/** @brief Set the font weight in the given attribute object. */
+/**
+ * @brief Set the font weight in the given attribute object.
+ *
+ * This function set the font weight value of the argument attr. If the
+ * argument attr is not a pointer to a IM_TYPE_ATTR_FONT_WEIGHT, this function
+ * shall do nothing.
+ *
+ * @param attr a pointer to an instance of IMAttribute.
+ * @param weight new value font weight value for attr.
+ *
+ * @return This function returns no value.
+ */
void im_attr_font_weight_set (IMAttribute
*attr,

IMAttrFontWeight weight);

-/** @brief Create a new font size attribute object. */
+/**
+ * @brief Create a new font size attribute object.
+ *
+ * This function returns a newly created an instance of IMAttribute which
+ * represents font size.
+ *
+ * @param size font size
+ *
+ * @return This function returns an instance of IM_TYPE_ATTR_FONT_SIZE
+ * IMAttribute, which shall be unreferenced when no longer needed.
+ */
IMAttribute* im_attr_font_size_new (IMInt
size);
-/** @brief Get the font size from the given attribute object. */
+/**
+ * @brief Get the font size from the given attribute object.
+ *
+ * This function returns the font weight value which the argument attr
+ * represents.
+ *
+ * @param attr a pointer to an instance of IMAttribute.
+ *
+ * @return This function returns IMAttrFontSize value which the argument
+ * attr represents, or 0 if the argument attr is not an
+ * IM_TYPE_ATTR_FONT_SIZE type. This value is in 1/1000 point.
+ */
IMInt im_attr_font_size_get (const
IMAttribute *attr);
-/** @brief Set the font size in the given attribute object. */
+/**
+ * @brief Set the font size in the given attribute object.
+ *
+ * This function change the font size value which the argument attr represents
+ * with the argument size. If the argument attr is not an
+ * IM_TYPE_ATTR_FONT_WEIGHT type, this function shall do nothing.
+ *
+ * @param attr a pointer to an instance of IMAttribute.
+ * @param size font size for the argument attr in 1/1000 point.
+ *
+ * @return This function set font size value which the argument attr
+ * represents. If the argument attr is not an IM_TYPE_ATTR_FONT_SIZE
+ * type, this function shall do nothing.
+ */
void im_attr_font_size_set (IMAttribute
*attr,
IMInt
size);

-/** @brief Create a new font scale attribute object. */
+/**
+ * @brief Create a new font scale attribute object.
+ *
+ * This function returns a newly created instance of IM_TYPE_ATTR_FONT_SCALE
+ * type which represents the font scale with the argument
scale_factor. If the
+ * font size attribute is already specified in IMText, the font size
shall be
+ * scaled by this factor.
+ *
+ * @param scale_factor value for font scale in percent.
+ *
+ * @return This function returns a newly created instance of
+ * IM_TYPE_ATTR_FONT_SCALE.
+ */
IMAttribute* im_attr_font_scale_new (IMInt
scale_factor);
-/** @brief Get the font scale factor from the given attribute object. */
+/**
+ * @brief Get the font scale factor from the given attribute object.
+ *
+ * This function returns the scale factor of the argument attr.
+ *
+ * @param attr a pointer to an instance of IMAttribute.
+ *
+ * @return This function returns a font scale factor value, or 0 if the
+ * argument attr is not a type of IM_TYPE_ATTR_FONT_SCALE.
+ */
IMInt im_attr_font_scale_get (const
IMAttribute *attr);
-/** @brief Set the font scale factor in the given attribute object. */
+/**
+ * @brief Set the font scale factor in the given attribute object.
+ *
+ * This function change the font scale factor value of the argument
attr with
+ * the argument scale_factor. If the argument attr is not a type of
+ * IM_TYPE_ATTR_FONT_SCALE, this function shall do nothing.
+ *
+ * @param attr a pointer to an instance of IMAttribute.
+ * @param scale_factor font scale factor for the argument attr.
+ *
+ * @return This function returns no value.
+ */
void im_attr_font_scale_set (IMAttribute
*attr,
IMInt
scale_factor);

-/** @brief Create a new foreground attribute object with RGB color. */
+/**
+ * @brief Create a new foreground attribute object with RGB color.
+ *
+ * This function creates a new instance of IMAttribute of
+ * IM_TYPE_ATTR_FOREGROUND which specified by argument red, green and blue.
+ * The value of each argument represents 0 for lowest intencity and
65535 for the
+ * full intencity.
+ *
+ * @param red intencity of red color.
+ * @param green intencity of green color.
+ * @param blue intencity of blue color.
+ *
+ * @return This function returns a newly created instance of
+ * IM_TYPE_ATTR_FOREGROUND type IMAttribute.
+ */
IMAttribute* im_attr_foreground_new (IMUInt16
red,
IMUInt16
green,
IMUInt16
blue);
-/** @brief Get the foreground color (in RGB) from the given attribute
object. */
+/**
+ * @brief Get the foreground color (in RGB) from the given attribute object.
+ *
+ * This function gets the values of each color component. If the
argument red,
+ * green, or blue is NULL, the value of that component shall not
copied. If the
+ * argument attr is not a IM_TYPE_FOREGROUND, the arguments red,
green, blue
+ * shall not changed.
+ *
+ * @param red a pointer where the red component value shall be copied.
+ * @param green a pointer where the green component value shall be copied.
+ * @param blue a pointer where the blue component value shall be copied.
+ *
+ * @return This function returns no value.
+ */
void im_attr_foreground_get (const
IMAttribute *attr,
IMUInt16
*red,
IMUInt16
*green,
IMUInt16
*blue);
-/** @brief Set the foreground color (in RGB) in the given attribute
object. */
+/**
+ * @brief Set the foreground color (in RGB) in the given attribute object.
+ *
+ * This function sets the each color component value of the argument
attr with
+ * the arguments red, green, blue. The value of each argument red,
green and
+ * blue represents 0 for lowest intencity and 65535 for the full intencity.
+ *
+ * @param red intencity of red color component.
+ * @param green intencity of green color component.
+ * @param blue intencity of blue color component.
+ *
+ * @return This function returns no value.
+ */
void im_attr_foreground_set (IMAttribute
*attr,
IMUInt16
red,
IMUInt16
green,
IMUInt16
blue);

-/** @brief Create a background attribute object with RGB color. */
+/**
+ * @brief Create a background attribute object with RGB color.
+ *
+ * The im_attr_background_new function creates a new instance of
IMAttribute of
+ * IM_TYPE_ATTR_BACKGROUND which specified by the arguments red,
green, blue.
+ * The value of each argument represents the intencity of color component.
+ * 65535 is the full intencity.
+ *
+ * @param red intencity of red color.
+ * @param green intencity of green color.
+ * @param blue intencity of blue color.
+ *
+ * @return The im_attr_background_new function returns newly created instance
+ * of IM_TYPE_ATTR_BACKGROUND IMAttribute.
+ */
IMAttribute* im_attr_background_new (IMUInt16
red,
IMUInt16
green,
IMUInt16
blue);
-/** @brief Get the background color (in RGB) from the given attribute
object. */
+/**
+ * @brief Get the background color (in RGB) from the given attribute object.
+ *
+ * This function gets the values of each color component of the
argument attr.
+ * If the argument red, green, or blue is NULL, the value of that component
+ * shall not copied. If the argument attr is not a IM_TYPE_FOREGROUND, the
+ * values pointed by the arguments red, green, blue shall not changed.
+ *
+ * @param red a pointer where the red component value shall be copied.
+ * @param green a pointer where the green component value shall be copied.
+ * @param blue a pointer where the blue component value shall be copied.
+ *
+ * @return This function returns no value.
+ * */
void im_attr_background_get (const
IMAttribute *attr,
IMUInt16
*red,
IMUInt16
*green,
IMUInt16
*blue);
-/** @brief Set the background color (in RGB) in the given attribute
object. */
+/**
+ * @brief Set the background color (in RGB) in the given attribute object.
+ *
+ * This function sets the each color component value of the argument
attr with
+ * the arguments red, green, blue. The value of each argument red,
green and
+ * blue represents intencity of color component, 0 for lowest
intencity and
+ * 65535 for the full intencity.
+ *
+ * @param red intencity of red color component.
+ * @param green intencity of green color component.
+ * @param blue intencity of blue color component.
+ *
+ * @return This function returns no value.
+ */
void im_attr_background_set (IMAttribute
*attr,
IMUInt16
red,
IMUInt16
green,
IMUInt16
blue);

-/** @brief Create a new underline attribute object. */
+/**
+ * @brief Create a new underline attribute object.
+ *
+ * The im_attr_underline_new function creates new instance of IMAttribute
+ * of IM_TYPE_ATTR_UNDERLINE type.
+ *
+ * @param type a value of IMAttrUnderline
+ *
+ * @return The im_attr_underline_new function returns newly created
instance of
+ * IM_TYPE_ATTR_UNDERLINE IMAttribute.
+ */
IMAttribute* im_attr_underline_new
(IMAttrUnderline type);
-/** @brief Get the underline type from the given attribute object. */
+/**
+ * @brief Get the underline type from the given attribute object.
+ *
+ * The im_attr_underline_get function get the underline style of the argument
+ * attr.
+ *
+ * @param attr a pointer to an instance of IMAttribute.
+ *
+ * @return The im_attr_underline_get function
+ */
IMAttrUnderline im_attr_underline_get (const
IMAttribute *attr);
-/** @brief Set the underline type in the given attribute object. */
+/**
+ * @brief Set the underline type in the given attribute object.
+ */
void im_attr_underline_set (IMAttribute
*attr,

IMAttrUnderline type);