From b0c09a6e354adde20c0190c5a2597f09615dd29e Mon Sep 17 00:00:00 2001 From: Tom Hacohen Date: Fri, 7 Aug 2015 15:04:10 +0100 Subject: [PATCH] Widget item: migrate docs. --- src/lib/elm_widget_item.eo | 611 ++++++++++++------------------------- 1 file changed, 190 insertions(+), 421 deletions(-) diff --git a/src/lib/elm_widget_item.eo b/src/lib/elm_widget_item.eo index af0f1af14..021b4c001 100644 --- a/src/lib/elm_widget_item.eo +++ b/src/lib/elm_widget_item.eo @@ -5,232 +5,132 @@ class Elm.Widget_Item(Eo.Base, Elm_Interface_Atspi_Accessible, legacy_prefix: elm_object_item; methods { @property tooltip_window_mode { - get { - /*@ - @brief Get size restriction state of an object's tooltip + [[Control size restriction state of an object's tooltip - This function returns whether a tooltip is allowed to expand beyond - its parent window's canvas. - It will instead be limited only by the size of the display. - */ + This function returns whether a tooltip is allowed to expand beyond + its parent window's canvas. + It will instead be limited only by the size of the display.]] + get { } set { - /*@ - @brief Disable size restrictions on an object's tooltip - - This function allows a tooltip to expand beyond its parent window's canvas. - It will instead be limited only by the size of the display. - */ - return: bool; /*@ $false on failure, $true on success */ + return: bool; [[$false on failure, $true on success]] } values { - disable: bool; /*@ If $true, size restrictions are disabled */ + disable: bool; [[If $true, size restrictions are disabled]] } } @property tooltip_style { - get { - /*@ - Get the style for this item tooltip. + [[Control a different style for this item tooltip. - @see elm_object_tooltip_style_get() for more details. - @see elm_object_item_tooltip_style_set() + Note: before you set a style you should define a tooltip with + @.tooltip_content_cb_set or + @.tooltip_text_set - @ingroup General - */ + See: elm_object_tooltip_style_set() for more details.]] + get { } set { - /*@ - Sets a different style for this item tooltip. - - @note before you set a style you should define a tooltip with - elm_object_item_tooltip_content_cb_set() or - elm_object_item_tooltip_text_set() - - @see elm_object_tooltip_style_set() for more details. - - @ingroup General - */ } values { - style: const (char)*; /*@ the theme style used/to use (default, transparent, ...) */ + style: const (char)*; [[the theme style used/to use (default, transparent, ...)]] } } @property cursor { - get { - /*@ - Get the type of mouse pointer/cursor decoration set to be shown, - when the mouse pointer is over the given item + [[Control the type of mouse pointer/cursor decoration to be shown, + when the mouse pointer is over the given item - @see elm_object_cursor_get() - @see elm_object_item_cursor_set() - @see elm_object_item_cursor_unset() + This function works analogously as elm_object_cursor_set(), but + here the cursor's changing area is restricted to the item's + area, and not the whole widget's. Note that that item cursors + have precedence over widget cursors, so that a mouse over an + item with custom cursor set will always show that cursor. - @ingroup General - */ + If this function is called twice for an object, a previously set + cursor will be unset on the second call.]] + get { } set { - /*@ - Set the type of mouse pointer/cursor decoration to be shown, - when the mouse pointer is over the given item - - This function works analogously as elm_object_cursor_set(), but - here the cursor's changing area is restricted to the item's - area, and not the whole widget's. Note that that item cursors - have precedence over widget cursors, so that a mouse over an - item with custom cursor set will always show @b that cursor. - - If this function is called twice for an object, a previously set - cursor will be unset on the second call. - - @see elm_object_cursor_set() - @see elm_object_item_cursor_get() - @see elm_object_item_cursor_unset() - - @ingroup General - */ } values { - cursor: const (char) *; /*@ the cursor type's name */ + cursor: const (char) *; [[the cursor type's name]] } } @property cursor_style { - get { - /*@ - Get the current @b style set for a given item's custom - cursor + [[Conrol a different $style for a given custom cursor set for an item. - @see elm_object_item_cursor_style_set() for more details + This function only makes sense when one is using custom mouse + cursor decorations defined in a theme file, which can have, + given a cursor name/type, alternate styles on it. It + works analogously as elm_object_cursor_style_set(), but here + applies only to item objects. - @ingroup General - */ + Warning: Before you set a cursor style you should have defined a + custom cursor previously on the item, with @.cursor.set]] + get { } set { - /*@ - Set a different @b style for a given custom cursor set for an - item. - - This function only makes sense when one is using custom mouse - cursor decorations defined in a theme file, which can have, - given a cursor name/type, alternate styles on it. It - works analogously as elm_object_cursor_style_set(), but here - applies only to item objects. - - @warning Before you set a cursor style you should have defined a - custom cursor previously on the item, with - elm_object_item_cursor_set() - - @see elm_object_item_cursor_engine_only_set() - @see elm_object_item_cursor_style_get() - - @ingroup General - */ } values { - style: const (char) *; /*@ the theme style to use/in use (e.g. $"default", $"transparent", etc) */ + style: const (char) *; [[the theme style to use/in use (e.g. $"default", $"transparent", etc)]] } } @property cursor_engine_only { - get { - /*@ - Get if the (custom) cursor for a given item is being - searched in its theme, also, or is only relying on the rendering - engine. - - @return $true, if cursors are being looked for only on - those provided by the rendering engine, $false if they - are being searched on the widget's theme, as well. + [[Control if the (custom)cursor for a given item should be + searched in its theme, also, or should only rely on the + rendering engine. - @see elm_object_item_cursor_engine_only_set(), for more details + Note: This call is of use only if you've set a custom cursor + for items, with @.cursor.set. - @ingroup General - */ + Note: By default, cursors will only be looked for between those + provided by the rendering engine.]] + get { } set { - /*@ - Set if the (custom)cursor for a given item should be - searched in its theme, also, or should only rely on the - rendering engine. - - @note This call is of use only if you've set a custom cursor - for items, with elm_object_item_cursor_set(). - - @note By default, cursors will only be looked for between those - provided by the rendering engine. - - @ingroup General - */ } values { - engine_only: bool; /*@ Use $true to have cursors looked for only - on those provided by the rendering engine, $false - to have them searched on the widget's theme, as well. */ + engine_only: bool; [[Use $true to have cursors looked for only on those provided by the rendering engine, $false to have them searched on the widget's theme, as well.]] } } @property part_content { - get { - /*@ - Get a content of an object item - - @return content of the object item or NULL for any error + [[Control a content of an object item - @note Elementary object items may have many contents - - @ingroup General - */ + This sets a new object to an item as a content object. If any object was + already set as a content object in the same part, previous object will be + deleted automatically.]] + get { } set { - /*@ - Set a content of an object item - - This sets a new object to an item as a content object. If any object was - already set as a content object in the same part, previous object will be - deleted automatically. - - @note Elementary object items may have many contents - - @ingroup General - */ } keys { - part: const (char) * @nullable; /*@ The content part name (NULL for the default content) */ + part: const (char) * @nullable; [[The content part name (NULL for the default content)]] } values { - content: Evas.Object *; /*@ The content of the object item */ + content: Evas.Object *; [[The content of the object item]] } } @property part_text { - get { - /*@ - Get a label of an object item + [[Control a label of an object item - @note Elementary object items may have many labels - - @ingroup General - */ + Note: Elementary object items may have many labels]] + get { } set { - /*@ - Set a label of an object item - - @note Elementary object items may have many labels - - @ingroup General - */ } keys { - part: const (char) * @nullable; /*@ The text part name (NULL for the default label) */ + part: const (char) * @nullable; [[The text part name (NULL for the default label)]] } values { - label: const (char) *; /*@ Text of the label */ + label: const (char) *; [[Text of the label]] } } @property part_text_custom @protected { get { - /*@ Get additional text part content */ + [[Get additional text part content]] legacy: null; } set { - /*@ Save additional text part content */ + [[Save additional text part content]] legacy: null; } keys { @@ -241,277 +141,194 @@ class Elm.Widget_Item(Eo.Base, Elm_Interface_Atspi_Accessible, } } @property focus { - get { - /*@ - Get whether the $it is focused or not. + [[Control the object item focused - @see elm_object_item_focus_set() - - @ingroup Focus - @since 1.10 - */ + @since 1.10]] + get { } set { - /*@ - Set the object item focused - - @see elm_object_item_focus_get() - - @ingroup Focus - @since 1.10 - */ } values { - focused: bool; /*@ The focused state */ + focused: bool; [[The focused state]] } } @property style { - get { - /*@ - Get the style of an object item - - @since 1.9 + [[Control the style of an object item - @ingroup General - */ + @since 1.9]] + get { } set { - /*@ - Set a style of an object item - - @since 1.9 - - @ingroup General - */ } values { - style: const (char) *; /*@ The style of object item */ + style: const (char) *; [[The style of object item]] } } @property disabled { - get { - /*@ - Get the disabled state of an widget item. + [[Control the disabled state of an widget item. - This gets the state of the widget, which might be enabled or disabled. + Elementary object item can be disabled, in which state they won't + receive input and, in general, will be themed differently from + their normal state, usually greyed out. Useful for contexts + where you don't want your users to interact with some of the + parts of you interface. - @ingroup Styles - */ + This sets the state for the widget item, either disabling it or + enabling it back.]] + get { } set { - /*@ - Set the disabled state of an widget item. - - Elementary object item can be @b disabled, in which state they won't - receive input and, in general, will be themed differently from - their normal state, usually greyed out. Useful for contexts - where you don't want your users to interact with some of the - parts of you interface. - - This sets the state for the widget item, either disabling it or - enabling it back. - - @ingroup Styles - */ } values { - disable: bool; /*@ $true, if the widget item is disabled, $false if it's enabled (or on errors) */ + disable: bool; [[$true, if the widget item is disabled, $false if it's enabled (or on errors)]] } } access_order_get { - /*@ - @brief Get highlight order - @since 1.8 + [[Get highlight order - @ingroup General - */ + @since 1.8]] return: const(list) *; } access_order_set { - /*@ - @brief Set highlight order - @since 1.8 + [[Set highlight order - @ingroup General - */ + @since 1.8]] params { - @in objs: own(list *); /*@ Order of objects to pass highlight */ + @in objs: own(list *); [[Order of objects to pass highlight]] } } widget_get @const { - /*@ - Get the widget object's handle which contains a given item + [[Get the widget object's handle which contains a given item - @note This returns the widget object itself that an item belongs to. - @note Every elm_object_item supports this API - @ingroup General - */ - return: Evas.Object*; /*@ The widget object */ + Note: This returns the widget object itself that an item belongs to. + Note: Every elm_object_item supports this API]] + return: Evas.Object*; [[The widget object]] } del { - /*@ - Delete the given item. - - @ingroup General - */ + [[Delete the given item.]] } pre_notify_del @protected { - /*@ notify deletion of widget item */ + [[notify deletion of widget item]] legacy: null; } tooltip_text_set { - /*@ - Set the text to be shown in a given object item's tooltips. + [[Set the text to be shown in a given object item's tooltips. Setup the text as tooltip to object. The item can have only one tooltip, so any previous tooltip data - set with this function or - elm_object_item_tooltip_content_cb_set() - is removed. + @.tooltip_content_cb_set - is removed. - @see elm_object_tooltip_text_set() for more details. - - @ingroup General - */ + See: elm_object_tooltip_text_set() for more details.]] params { - text: const (char) *; /*@ The text to set in the content. */ + text: const (char) *; [[The text to set in the content.]] } } tooltip_translatable_text_set @protected { - /*@ Set widget item tooltip as a text string */ + [[Set widget item tooltip as a text string]] legacy: null; params { text: const (char) *; } } tooltip_unset { - /*@ - Unset tooltip from item. + [[Unset tooltip from item. Remove tooltip from item. The callback provided as del_cb to - elm_object_item_tooltip_content_cb_set() will be called to notify + @.tooltip_content_cb_set will be called to notify it is not used anymore. - @see elm_object_tooltip_unset() for more details. - @see elm_object_item_tooltip_content_cb_set() - - @ingroup General - */ + See: elm_object_tooltip_unset() for more details. + See: @.tooltip_content_cb_set]] } cursor_unset { - /*@ - Unset any custom mouse pointer/cursor decoration set to be + [[Unset any custom mouse pointer/cursor decoration set to be shown, when the mouse pointer is over the given - item, thus making it show the @b default cursor again. + item, thus making it show the default cursor again. Use this call to undo any custom settings on this item's cursor decoration, bringing it back to defaults (no custom style set). - @see elm_object_cursor_unset() - @see elm_object_item_cursor_set() - - @ingroup General - */ + See: elm_object_cursor_unset() + See: @.cursor.set]] } part_content_unset { - /*@ - Unset a content of an object item - - @note Elementary object items may have many contents + [[Unset a content of an object item - @ingroup General - */ + Note: Elementary object items may have many contents]] params { - part: const (char) *; /*@ The content part name to unset (NULL for the default content) */ + part: const (char) *; [[The content part name to unset (NULL for the default content)]] } return: Evas.Object*; } part_text_custom_update @protected { - /*@ Update additional text part content */ + [[Update additional text part content]] legacy: null; } signal_callback_add { - /*@ - Add a callback for a signal emitted by object item edje. + [[Add a callback for a signal emitted by object item edje. This function connects a callback function to a signal emitted by the edje object of the object item. Globs can occur in either the emission or source name. - @since 1.8 - - @ingroup General - */ + @since 1.8]] params { - emission: const (char) *; /*@ The signal's name. */ - source: const (char) *; /*@ The signal's source. */ - func: Elm_Object_Item_Signal_Cb; /*@ The callback function to be executed when the signal is emitted. */ - data: void *; /*@ A pointer to data to pass to the callback function. */ + emission: const (char) *; [[The signal's name.]] + source: const (char) *; [[The signal's source.]] + func: Elm_Object_Item_Signal_Cb; [[The callback function to be executed when the signal is emitted.]] + data: void *; [[A pointer to data to pass to the callback function.]] } } signal_callback_del { - /*@ - Remove a signal-triggered callback from a object item edje object. + [[Remove a signal-triggered callback from a object item edje object. - This function removes the @b last callback, previously attached to - a signal emitted by an underlying Edje object of @a it, whose - parameters @a emission, @a source and $func match exactly with + This function removes the last callback, previously attached to + a signal emitted by an underlying Edje object of $it, whose + parameters $emission, $source and $func match exactly with those passed to a previous call to - elm_object_item_signal_callback_add(). The data pointer that was passed + @.signal_callback_add. The data pointer that was passed to this call will be returned. - @see elm_object_item_signal_callback_add() - @since 1.8 + See: @.signal_callback_add - @ingroup General - */ + @since 1.8]] params { - emission: const (char) *; /*@ The signal's name. */ - source: const (char) *; /*@ The signal's source. */ - func: Elm_Object_Item_Signal_Cb; /*@ The callback function to be executed when the signal is emitted. */ + emission: const (char) *; [[The signal's name.]] + source: const (char) *; [[The signal's source.]] + func: Elm_Object_Item_Signal_Cb; [[The callback function to be executed when the signal is emitted.]] } - return: void*; /*@ The data pointer of the signal callback or $NULL, on errors. */ + return: void*; [[The data pointer of the signal callback or $NULL, on errors.]] } signal_emit { - /*@ - Send a signal to the edje object of the widget item. + [[Send a signal to the edje object of the widget item. This function sends a signal to the edje object of the obj item. An edje program can respond to a signal by specifying matching - 'signal' and 'source' fields. - - @ingroup General - */ + 'signal' and 'source' fields.]] params { - emission: const (char) *; /*@ The signal's name. */ - source: const (char) *; /*@ The signal's source. */ + emission: const (char) *; [[The signal's name.]] + source: const (char) *; [[The signal's source.]] } } access_info_set { - /*@ - Set the text to read out when in accessibility mode - - @ingroup General - */ + [[Set the text to read out when in accessibility mode]] params { - txt: const (char) *; /*@ The text that describes the widget to people with poor or no vision */ + txt: const (char) *; [[The text that describes the widget to people with poor or no vision]] } } access_object_get @const { - /*@ - @brief Get an accessible object of the object item. - @since 1.8 + [[Get an accessible object of the object item. - @ingroup General - */ - return: Evas.Object*; /*@ Accessible object of the object item or NULL for any error */ + @since 1.8]] + return: Evas.Object*; [[Accessible object of the object item or NULL for any error]] } domain_translatable_part_text_set { - /*@ - Set the text for an object item's part, marking it as translatable. + [[Set the text for an object item's part, marking it as translatable. The string to set as $text must be the original one. Do not pass the return of $gettext() here. Elementary will translate the string internally and set it on the object item using - elm_object_item_part_text_set(), also storing the original string so that it + @.part_text.set, also storing the original string so that it can be automatically translated when the language is changed with elm_language_set(). The $domain will be stored along to find the translation in the correct catalog. It can be NULL, in which case it will use @@ -520,64 +337,54 @@ class Elm.Widget_Item(Eo.Base, Elm_Interface_Atspi_Accessible, its own translatable strings, that should not be mixed with those of programs using the library. - @ingroup General - @since 1.8 - */ + @since 1.8]] params { - part: const (char) *; /*@ The name of the part to set */ - domain: const (char) *; /*@ The translation domain to use */ - label: const (char) *; /*@ The original, non-translated text to set */ + part: const (char) *; [[The name of the part to set]] + domain: const (char) *; [[The translation domain to use]] + label: const (char) *; [[The original, non-translated text to set]] } } translatable_part_text_get @const { - /*@ - Get the original string set as translatable for an object item. + [[Get the original string set as translatable for an object item. - When setting translated strings, the function elm_object_item_part_text_get() + When setting translated strings, the function @.part_text.get will return the translation returned by $gettext(). To get the original string use this function. - @ingroup General - @since 1.8 - */ + @since 1.8]] params { - part: const (char) *; /*@ The name of the part that was set */ + part: const (char) *; [[The name of the part that was set]] } - return: const (char)*; /*@ The original, untranslated string */ + return: const (char)*; [[The original, untranslated string]] } translate @protected { - /*@ Query translate */ + [[Query translate]] legacy: null; } domain_part_text_translatable_set { - /*@ - Mark the part text to be translatable or not. + [[Mark the part text to be translatable or not. Once you mark the part text to be translatable, the text will be translated - internally regardless of elm_object_item_part_text_set() and - elm_object_item_domain_translatable_part_text_set(). In other case, if you + internally regardless of @.part_text.set and + @.domain_translatable_part_text_set. In other case, if you set the Elementary policy that all text will be translatable in default, you can set the part text to not be translated by calling this API. - @see elm_object_item_domain_translatable_part_text_set() - @see elm_object_item_part_text_set() - @see elm_policy() - - @since 1.8 + See: @.domain_translatable_part_text_set + See: @.part_text.set + See: elm_policy() - @ingroup General - */ + @since 1.8]] params { - part: const (char) *; /*@ The part name of the translatable text */ - domain: const (char) *; /*@ The translation domain to use */ - translatable: bool; /*@ $true, the part text will be translated internally. $false, otherwise. */ + part: const (char) *; [[The part name of the translatable text]] + domain: const (char) *; [[The translation domain to use]] + translatable: bool; [[$true, the part text will be translated internally. $false, otherwise.]] } } track { - /*@ - This returns track object of the item. + [[This returns track object of the item. - @note This gets a rectangle object that represents the object item's internal + Note: This gets a rectangle object that represents the object item's internal object. If you wanna check the geometry, visibility of the item, you can call the evas apis such as evas_object_geometry_get(), evas_object_visible_get() to the track object. Note that all of the @@ -590,82 +397,60 @@ class Elm.Widget_Item(Eo.Base, Elm_Interface_Atspi_Accessible, at the moment you need to refer. Otherwise, you need to add some callbacks to the track object to track it's attributes changes. - @warning After use the track object, please call the - elm_object_item_untrack() paired to elm_object_item_track() + Warning: After use the track object, please call the + @.untrack() paired to elm_object_item_track definitely to free the track object properly. Don't delete the track object. - @see elm_object_item_untrack() - @see elm_object_item_track_get() + See: @.untrack + See: @.track_get - @since 1.8 - - @ingroup General - */ - return: Evas.Object*; /*@ The track object */ + @since 1.8]] + return: Evas.Object*; [[The track object]] } untrack { - /*@ - This retrieve the track object of the item. - - @note This retrieves the track object that was returned from - elm_object_item_track(). + [[This retrieve the track object of the item. - @see elm_object_item_track() - @see elm_object_item_track_get() + Note: This retrieves the track object that was returned from + @.track. - @since 1.8 + See: @.track + See: @.track_get - @ingroup General - */ + @since 1.8]] } track_get @const { - /*@ - Get the track object reference count. + [[Get the track object reference count. - @note This gets the reference count for the track object. Whenever you call - the elm_object_item_track(), the reference count will be increased by + Note: This gets the reference count for the track object. Whenever you call + the @.track, the reference count will be increased by one. Likely the referece count will be decreased again when you call - the elm_object_item_untrack(). Unless the reference count reaches to + the @.untrack. Unless the reference count reaches to zero, the track object won't be deleted. So please be sure to call - elm_object_item_untrack() paired to the elm_object_item_track() call + @.untrack() paired to the elm_object_item_track call count. - @see elm_object_item_track() - @see elm_object_item_track_get() + See: @.track + See: @.track_get - @since 1.8 - - @ingroup General - */ + @since 1.8]] return: int; } track_cancel @protected { - /*@ Query track_cancel */ + [[Query track_cancel]] legacy: null; } del_cb_set { - /*@ - @brief Set the function to be called when an item from the widget is + [[Set the function to be called when an item from the widget is freed. - That function will receive these parameters: - @li void * item data - @li Evas_Object * widget object - @li Elm.Widget_Item * widget item - - @note Every elm_object_item supports this API - - @see elm_object_item_del() - @ingroup General - */ + Note: Every elm_object_item supports this API]] params { - del_cb: Evas_Smart_Cb @nullable; /*@ The function called */ + del_cb: Evas_Smart_Cb @nullable; [[The function called]] } } tooltip_content_cb_set { - /*@ - Set the content to be shown in the tooltip item. + [[Set the content to be shown in the tooltip item. Setup the tooltip to item. The item can have only one tooltip, so any previous tooltip data is removed. $func(with $data) will @@ -673,45 +458,29 @@ class Elm.Widget_Item(Eo.Base, Elm_Interface_Atspi_Accessible, return a valid Evas_Object. This object is then managed fully by tooltip system and is deleted when the tooltip is gone. - @see elm_object_tooltip_content_cb_set() for more details. - - @ingroup General - */ + See: elm_object_tooltip_content_cb_set() for more details.]] params { - func: Elm_Tooltip_Item_Content_Cb @nullable; /*@ the function used to create the tooltip contents. */ - data: const (void) * @optional; /*@ what to provide to @a func as callback data/context. */ - del_cb: Evas_Smart_Cb @optional; /*@ called when data is not needed anymore, either when - another callback replaces @a func, the tooltip is unset with - elm_object_item_tooltip_unset() or the owner @a item - dies. This callback receives as the first parameter the - given @a data, and $event_info is the item. */ + func: Elm_Tooltip_Item_Content_Cb @nullable; [[the function used to create the tooltip contents.]] + data: const (void) * @optional; [[what to provide to $func as callback data/context.]] + del_cb: Evas_Smart_Cb @optional; [[called when data is not needed anymore, either when another callback replaces $func, the tooltip is unset with @.tooltip_unset or the owner $item dies. This callback receives as the first parameter the given $data, and $event_info is the item.]] } } access_register { - /*@ - @brief Register object item as an accessible object. - @since 1.8 + [[Register object item as an accessible object. - @ingroup General - */ - return: Evas.Object*; /*@ Accessible object of the object item or NULL for any error */ + @since 1.8]] + return: Evas.Object*; [[Accessible object of the object item or NULL for any error]] } access_unregister { - /*@ - @brief Unregister accessible object of the object item. - @since 1.8 + [[Unregister accessible object of the object item. - @ingroup General - */ + @since 1.8]] } access_order_unset { - /*@ - @brief Unset highlight order - @since 1.8 + [[Unset highlight order - @ingroup General - */ + @since 1.8]] } disable @protected { legacy: null; -- 2.34.1