From 3752e0aa34cc51688b32545a9ab9cb3e1e0f1d59 Mon Sep 17 00:00:00 2001 From: Daniel Kolesa Date: Wed, 2 Sep 2015 14:09:04 +0100 Subject: [PATCH] evas object: finish doc conversion --- src/lib/evas/canvas/evas_object.eo | 512 +++++++++++++---------------- 1 file changed, 230 insertions(+), 282 deletions(-) diff --git a/src/lib/evas/canvas/evas_object.eo b/src/lib/evas/canvas/evas_object.eo index 630db49d89..0639af214b 100644 --- a/src/lib/evas/canvas/evas_object.eo +++ b/src/lib/evas/canvas/evas_object.eo @@ -690,104 +690,96 @@ abstract Evas.Object (Eo.Base, Evas.Common_Interface, Efl.Gfx.Base, Efl.Gfx.Stac } @property map_enable { set { - /*@ - Enable or disable the map that is set. + [[Enable or disable the map that is set. - Enable or disable the use of map for the object @p obj. - On enable, the object geometry will be saved, and the new geometry will - change (position and size) to reflect the map geometry set. + Enable or disable the use of map for the object $obj. On + enable, the object geometry will be saved, and the new + geometry will change (position and size) to reflect the + map geometry set. - If the object doesn't have a map set (with evas_object_map_set()), the - initial geometry will be undefined. It is advised to always set a map - to the object first, and then call this function to enable its use. */ + If the object doesn't have a map set (with + \@ref evas_object_map_set), the initial geometry will be + undefined. It is advised to always set a map to the object + first, and then call this function to enable its use. + ]] } get { - /*@ - Get the map enabled state + [[Get the map enabled state - This returns the currently enabled state of the map on the object indicated. - The default map enable state is off. You can enable and disable it with - evas_object_map_enable_set(). - - @return the map enabled state */ + This returns the currently enabled state of the map on the + object indicated. The default map enable state is off. You + can enable and disable it with @.map_enable.set. + ]] } values { - enabled: bool; /*@ enabled state */ + enabled: bool; [[Enabled state.]] } } @property precise_is_inside { set { - /*@ - Set whether to use precise (usually expensive) point collision - detection for a given Evas object. + [[Set whether to use precise (usually expensive) point collision + detection for a given Evas object. - Use this function to make Evas treat objects' transparent areas as - @b not belonging to it with regard to mouse pointer events. By - default, all of the object's boundary rectangle will be taken in - account for them. - - @warning By using precise point collision detection you'll be - making Evas more resource intensive. + Use this function to make Evas treat objects' transparent + areas as not belonging to it with regard to mouse pointer + events. By default, all of the object's boundary rectangle + will be taken in account for them. + Warning: By using precise point collision detection you'll be + making Evas more resource intensive. + ]] + /* FIXME-doc Example code follows. @dontinclude evas-events.c @skip if (strcmp(ev->key, "p") == 0) @until } See the full example @ref Example_Evas_Events "here". - - @see evas_object_precise_is_inside_get() - @ingroup Evas_Object_Group_Extras */ + */ } get { - /*@ - Determine whether an object is set to use precise point collision - detection. - - @return whether @p obj is set to use precise point collision - detection or not The default value is false. - - @see evas_object_precise_is_inside_set() for an example - - @ingroup Evas_Object_Group_Extras */ + [[Determine whether an object is set to use precise point + collision detection. + ]] } values { - precise: bool; /*@ Whether to use precise point collision detection or - not. The default value is false. */ + precise: bool; [[Whether to use precise point collision + detection or not. The default value is false.]] } } @property size_hint_align { set { - /*@ - Sets the hints for an object's alignment. + [[Sets the hints for an object's alignment. - These are hints on how to align an object inside the boundaries - of a container/manager. Accepted values are in the @c 0.0 to @c - 1.0 range, with the special value #EVAS_HINT_FILL used to specify - "justify" or "fill" by some users. In this case, maximum size hints - should be enforced with higher priority, if they are set. Also, any - padding hint set on objects should add up to the alignment space on - the final scene composition. + These are hints on how to align an object inside the + boundaries of a container/manager. Accepted values are in + the 0.0 to 1.0 range, with the special value #EVAS_HINT_FILL + used to specify "justify" or "fill" by some users. In this + case, maximum size hints should be enforced with higher + priority, if they are set. Also, any padding hint set on + objects should add up to the alignment space on the final + scene composition. - See documentation of possible users: in Evas, they are the @ref - Evas_Object_Box "box" and @ref Evas_Object_Table "table" smart - objects. + See documentation of possible users: in Evas, they are the + \@ref Evas_Object_Box "box" and \@ref Evas_Object_Table "table" + smart objects. - For the horizontal component, @c 0.0 means to the left, @c 1.0 - means to the right. Analogously, for the vertical component, @c 0.0 - to the top, @c 1.0 means to the bottom. + For the horizontal component, 0.0 means to the left, 1.0 + means to the right. Analogously, for the vertical component, + 0.0 to the top, 1.0 means to the bottom. + This is not a size enforcement in any way, it's just a hint + that should be used whenever appropriate. + + Note: Default alignment hint values are 0.5, for both axis. + ]] + /* FIXME-doc See the following figure: @image html alignment-hints.png @image rtf alignment-hints.png @image latex alignment-hints.eps - - This is not a size enforcement in any way, it's just a hint that - should be used whenever appropriate. - - @note Default alignment hint values are 0.5, for both axis. - + --- Example: @dontinclude evas-hints.c @skip evas_object_size_hint_align_set @@ -796,177 +788,144 @@ abstract Evas.Object (Eo.Base, Evas.Common_Interface, Efl.Gfx.Base, Efl.Gfx.Stac In this example the alignment hints change the behavior of an Evas box when layouting its children. See the full @ref Example_Evas_Size_Hints "example". - - @see evas_object_size_hint_align_get() - @see evas_object_size_hint_max_set() - @see evas_object_size_hint_padding_set() */ + */ } get { - /*@ - Retrieves the hints for on object's alignment. + [[Retrieves the hints for on object's alignment. - This is not a size enforcement in any way, it's just a hint that - should be used whenever appropriate. + This is not a size enforcement in any way, it's just a hint + that should be used whenever appropriate. - @note Use $null pointers on the hint components you're not - interested in: they'll be ignored by the function. - @note If @c obj is invalid, then the hint components will be set with 0.5 + Note: Use $null pointers on the hint components you're not + interested in: they'll be ignored by the function. - @see evas_object_size_hint_align_set() for more information */ + Note: If $obj is invalid, then the hint components will be + set with 0.5 + ]] } values { - x: double; /*@ Double, ranging from @c 0.0 to @c 1.0 or with the - special value #EVAS_HINT_FILL, to use as horizontal alignment hint. */ - y: double; /*@ Double, ranging from @c 0.0 to @c 1.0 or with the - special value #EVAS_HINT_FILL, to use as vertical alignment hint. */ + x: double; [[Double, ranging from 0.0 to 1.0 or with the special value + #EVAS_HINT_FILL, to use as horizontal alignment hint.]] + y: double; [[Double, ranging from 0.0 to 1.0 or with the special value + #EVAS_HINT_FILL, to use as vertical alignment hint.]] } } @property propagate_events { set { - /*@ - Set whether events on a smart object's member should get propagated - up to its parent. + [[Set whether events on a smart object's member should get + propagated up to its parent. - This function has @b no effect if @p obj is not a member of a smart - object. + This function has no effect if $obj is not a member of a + smart object. - If @p prop is $true, events occurring on this object will be - propagated on to the smart object of which @p obj is a member. If - @p prop is $false, events occurring on this object will @b - not be propagated on to the smart object of which @p obj is a - member. The default value is $true. + If $prop is $true, events occurring on this object will be + propagated on to the smart object of which $obj is a member. + If $prop is $false, events occurring on this object will not + be propagated on to the smart object of which $obj is a + member. The default value is $true. - @see evas_object_propagate_events_get() - @see evas_object_repeat_events_set() - @see evas_object_pass_events_set() - @see evas_object_freeze_events_set() */ + See also @.repeat_events.set, @.pass_events.set, + @.freeze_events.set. + ]] } get { - /*@ - Retrieve whether an Evas object is set to propagate events. + [[Retrieve whether an Evas object is set to propagate events. - @return whether @p obj is set to propagate events ($true) - or not ($false) - - @see evas_object_propagate_events_set() - @see evas_object_repeat_events_get() - @see evas_object_pass_events_get() - @see evas_object_freeze_events_get() */ + See also @.repeat_events.get, @.pass_events.get, + @.freeze_events.get. + ]] } values { - propagate: bool; /*@ whether to propagate events ($true) or not - ($false) */ + propagate: bool; [[Whether to propagate events ($true) or not + ($false).]] } } @property pass_events { set { - /*@ - Set whether an Evas object is to pass (ignore) events. + [[Set whether an Evas object is to pass (ignore) events. - If @p pass is $true, it will make events on @p obj to be @b - ignored. They will be triggered on the @b next lower object (that - is not set to pass events), instead (see evas_object_below_get()). + If $pass is $true, it will make events on $obj to be ignored. + They will be triggered on the next lower object (that is not + set to pass events), instead (see \@ref evas_object_below_get). - If @p pass is $false, events will be processed on that - object as normal. + If $pass is $false, events will be processed on that object + as normal. - @see evas_object_pass_events_get() for an example - @see evas_object_repeat_events_set() - @see evas_object_propagate_events_set() - @see evas_object_freeze_events_set() */ + See also @.repeat_events.set, @.propagate_events.set, + @.freeze_events.set. + ]] } get { - /*@ - Determine whether an object is set to pass (ignore) events. - - @return pass whether @p obj is set to pass events ($true) or not - ($false) + [[Determine whether an object is set to pass (ignore) events. + See also @.repeat_events.get, @.propagate_events.get, + @.freeze_events.get. + ]] + /* FIXME-doc Example: @dontinclude evas-stacking.c @skip if (strcmp(ev->key, "p") == 0) @until } See the full @ref Example_Evas_Stacking "example". - - @see evas_object_pass_events_set() - @see evas_object_repeat_events_get() - @see evas_object_propagate_events_get() - @see evas_object_freeze_events_get() */ + */ } values { - pass: bool; /*@ whether @p obj is to pass events ($true) or not - ($false) */ + pass: bool; [[Whether $obj is to pass events ($true) or not + ($false).]] } } @property anti_alias { set { - /*@ - Sets whether or not the given Evas object is to be drawn anti-aliased. - - @ingroup Evas_Object_Group_Extras */ + [[Sets whether or not the given Evas object is to be drawn + anti-aliased. + ]] } get { - /*@ - Retrieves whether or not the given Evas object is to be drawn anti_aliased. - @return ($true) if the object is to be anti_aliased. ($false) otherwise. - @ingroup Evas_Object_Group_Extras */ + [[Retrieves whether or not the given Evas object is to be drawn + anti_aliased. + ]] } values { - anti_alias: bool; /*@ ($true) if the object is to be anti_aliased, ($false) otherwise. */ + anti_alias: bool; [[$true if the object is to be anti_aliased, + $false otherwise.]] } } @property smart_data { get { - /*@ - Retrieve user data stored on a given smart object. - - @return A pointer to data stored using - evas_object_smart_data_set(), or $null, if none has been - set. - - @see evas_object_smart_data_set() - - @ingroup Evas_Smart_Object_Group */ - return: void * @warn_unused; + [[Retrieve user data stored on a given smart object.]] + return: void * @warn_unused; [[A pointer to data or $null.]] } } @property smart_clipped_clipper { get { - /*@ - Get the clipper object for the given clipped smart object. + [[Get the clipper object for the given clipped smart object. - @return the clipper object. - - Use this function if you want to change any of this clipper's - properties, like colors. - - @see evas_object_smart_clipped_smart_add() */ + Use this function if you want to change any of this clipper's + properties, like colors. + ]] return: Evas.Object * @warn_unused; } } @property clipees { get { - /*@ - Return a list of objects currently clipped by @p obj. + [[Return a list of objects currently clipped by $obj. - @return a list of objects being clipped by @p obj - - This returns the internal list handle that contains all objects - clipped by the object @p obj. If none are clipped by it, the call - returns $null. This list is only valid until the clip list is - changed and should be fetched again with another call to - evas_object_clipees_get() if any objects being clipped by this - object are unclipped, clipped by a new object, deleted or get the - clipper deleted. These operations will invalidate the list - returned, so it should not be used anymore after that point. Any - use of the list after this may have undefined results, possibly - leading to crashes. The object @p obj must be a valid - .Evas_Object. - - See also evas_object_clip_set(), evas_object_clip_unset() and - evas_object_clip_get(). + This returns the internal list handle that contains all + objects clipped by the object $obj. If none are clipped by + it, the call returns $null. This list is only valid until + the clip list is changed and should be fetched again with + another call to this function if any objects being clipped + by this object are unclipped, clipped by a new object, + deleted or get the clipper deleted. These operations will + invalidate the list returned, so it should not be used + anymore after that point. Any use of the list after this + may have undefined results, possibly leading to crashes. + The object $obj must be a valid Evas_Object. + See also @.clip.set, @.clip_unset and @.clip.get. + ]] + /* FIXME-doc Example: @code extern Evas_Object *obj; @@ -984,178 +943,167 @@ abstract Evas.Object (Eo.Base, Evas.Common_Interface, Efl.Gfx.Base, Efl.Gfx.Stac evas_object_show(obj_tmp); } @endcode */ - return: const(list)* @warn_unused; + return: const(list)* @warn_unused; [[A list of objects being clipped by $obj.]] } } @property smart_parent { get { - /*@ - Gets the parent smart object of a given Evas object, if it has one. - - @return Returns the parent smart object of @a obj or $null, if @a - obj is not a smart member of any - - @ingroup Evas_Smart_Object_Group */ - return: Evas.Object * @warn_unused; + [[Gets the parent smart object of a given Evas object, if it + has one. + ]] + return: Evas.Object * @warn_unused; [[The parent smart object + of $obj or $null.]] } } @property size_hint_display_mode { get { - /*@ - Retrieves the hints for an object's display mode + [[Retrieves the hints for an object's display mode - These are hints on the display mode @p obj. This is - not a size enforcement in any way, it's just a hint that can be - used whenever appropriate. - This mode can be used object's display mode like commpress or expand */ + These are hints on the display mode $obj. This is not a size + enforcement in any way, it's just a hint that can be used + whenever appropriate. This mode can be used object's display + mode like commpress or expand. + ]] } set { - /*@ - Sets the hints for an object's disply mode + [[Sets the hints for an object's disply mode, - This is not a size enforcement in any way, it's just a hint that - can be used whenever appropriate.*/ + This is not a size enforcement in any way, it's just a hint + that can be used whenever appropriate. + ]] } values { - dispmode: Evas.Display_Mode; /*@ display mode hint */ + dispmode: Evas.Display_Mode; [[Display mode hint.]] } } clipees_has @const { - /*@ - Test if any object is clipped by @p obj. + [[Test if any object is clipped by $obj. - @return EINA_TRUE if @p obj clip any object. - @since 1.8 */ + @since 1.8 + ]] return: bool @warn_unused; } key_grab { - /*@ - Requests @p keyname key events be directed to @p obj. + [[Requests $keyname key events be directed to $obj. - @return $true, if the call succeeded, $false otherwise. + Key grabs allow one or more objects to receive key events for + specific key strokes even if other objects have focus. Whenever + a key is grabbed, only the objects grabbing it will get the + events for the given keys. - Key grabs allow one or more objects to receive key events for - specific key strokes even if other objects have focus. Whenever a - key is grabbed, only the objects grabbing it will get the events - for the given keys. + $keyname is a platform dependent symbolic name for the key + pressed (see \@ref Evas_Keys for more information). - @p keyname is a platform dependent symbolic name for the key - pressed (see @ref Evas_Keys for more information). + $modifiers and $not_modifiers are bit masks of all the + modifiers that must and mustn't, respectively, be pressed along + with $keyname key in order to trigger this new key grab. + Modifiers can be things such as Shift and Ctrl as well as + user defined types via \@ref evas_key_modifier_add. Retrieve + them with \@ref evas_key_modifier_mask_get or use 0 for empty + masks. - @p modifiers and @p not_modifiers are bit masks of all the - modifiers that must and mustn't, respectively, be pressed along - with @p keyname key in order to trigger this new key - grab. Modifiers can be things such as Shift and Ctrl as well as - user defined types via evas_key_modifier_add(). Retrieve them with - evas_key_modifier_mask_get() or use @c 0 for empty masks. + $exclusive will make the given object the only one permitted to + grab the given key. If given $true, subsequent calls on this + function with different $obj arguments will fail, unless the key + is ungrabbed again. - @p exclusive will make the given object the only one permitted to - grab the given key. If given $true, subsequent calls on this - function with different @p obj arguments will fail, unless the key - is ungrabbed again. + Warning: Providing impossible modifier sets creates undefined + behavior. + See also @.key_ungrab, @.focus.get, @.focus.set, + \@ref evas_focus_get, \@ref evas_key_modifier_add. + ]] + /* FIXME-doc Example code follows. @dontinclude evas-events.c @skip if (d.focus) @until else See the full example @ref Example_Evas_Events "here". + */ - @warning Providing impossible modifier sets creates undefined behavior - - @see evas_object_key_ungrab - @see evas_object_focus_set - @see evas_object_focus_get - @see evas_focus_get - @see evas_key_modifier_add */ - - return: bool @warn_unused; + return: bool @warn_unused; [[$true if the call succeeded, $false otherwise.]] params { - @in keyname: const(char)* @nonull; /*@ the key to request events for. */ - @in modifiers: Evas.Modifier_Mask; /*@ a mask of modifiers that must be present to - trigger the event. */ - @in not_modifiers: Evas.Modifier_Mask; /*@ a mask of modifiers that must @b not be present - to trigger the event. */ - @in exclusive: bool; /*@ request that the @p obj is the only object - receiving the @p keyname events. */ + @in keyname: const(char)* @nonull; [[The key to request events for.]] + @in modifiers: Evas.Modifier_Mask; [[A mask of modifiers that must be + present to trigger the event.]] + @in not_modifiers: Evas.Modifier_Mask; [[A mask of modifiers that must + not be present to trigger the event.]] + @in exclusive: bool; [[Request that the $obj is the only object + receiving the $keyname events.]] } } smart_type_check @const { - /*@ - Checks whether a given smart object or any of its smart object - parents is of a given smart class. + [[Checks whether a given smart object or any of its smart object + parents is of a given smart class. - @return $true, if @a obj or any of its parents is of type @a - type, $false otherwise + If $obj is not a smart object, this call will fail immediately. - If @p obj is not a smart object, this call will fail - immediately. + This function supports Eo and legacy inheritance mechanisms. + However, it is recommended to use \@ref eo_isa instead if your + object is using Eo from top to bottom. - This function supports Eo and legacy inheritance mechanisms. However, - it is recommended to use eo_isa instead if your object is using Eo from - top to bottom. + The checks use smart classes names and string comparison. There + is a version of this same check using pointer comparison, since + a smart class' name is a single string in Evas. - The checks use smart classes names and string - comparison. There is a version of this same check using - pointer comparison, since a smart class' name is a single - string in Evas. - - @see evas_object_smart_type_check_ptr() - @see eo_isa - - @ingroup Evas_Smart_Object_Group */ + See also @.smart_type_check_ptr. + ]] return: bool @warn_unused; params { - @in type: const(char)* @nonull; /*@ The @b name (type) of the smart class to check for */ + @in type: const(char)* @nonull; [[The name (type) of the smart class to check for.]] } } name_child_find @const { - /*@ - Retrieves the object from children of the given object with the given name. - @return If successful, the Evas object with the given name. Otherwise, - $null. + [[Retrieves the object from children of the given object with the + given name. - This looks for the evas object given a name by evas_object_name_set(), but - it ONLY looks at the children of the object *p obj, and will only recurse - into those children if @p recurse is greater than 0. If the name is not - unique within immediate children (or the whole child tree) then it is not - defined which child object will be returned. If @p recurse is set to -1 then - it will recurse without limit. + This looks for the evas object given a name by @.name.set, but + it ONLY looks at the children of the object *p obj, and will + only recurse into those children if $recurse is greater than 0. + If the name is not unique within immediate children (or the whole + child tree) then it is not defined which child object will be + returned. If $recurse is set to -1 then it will recurse without + limit. - @since 1.2 - - @ingroup Evas_Object_Group_Find */ - return: Evas.Object * @warn_unused; + @since 1.2 + ]] + return: Evas.Object * @warn_unused; [[The Evas object with the given name + on success, Otherwise $null.]] params { - @in name: const(char)*; /*@ The given name. */ - @in recurse: int; /*@ Set to the number of child levels to recurse (0 == don't recurse, 1 == only look at the children of @p obj or their immediate children, but no further etc.). */ + @in name: const(char)*; [[The given name.]] + @in recurse: int; [[ + Set to the number of child levels to recurse (0 == don't + recurse, 1 == only look at the children of $obj or their + immediate children, but no further etc.). + ]] } } key_ungrab { - /*@ - Removes the grab on @p keyname key events by @p obj. + [[Removes the grab on $keyname key events by $obj. - Removes a key grab on @p obj if @p keyname, @p modifiers, and @p - not_modifiers match. + Removes a key grab on $obj if $keyname, $modifiers, and + $not_modifiers match. + See also @.key_grab, @.focus.get, @.focus.set, + \@ref evas_focus_get. + ]] + /* FIXME-doc Example code follows. @dontinclude evas-events.c @skip got here by key grabs @until } See the full example @ref Example_Evas_Events "here". - - @see evas_object_key_grab - @see evas_object_focus_set - @see evas_object_focus_get - @see evas_focus_get */ - + */ params { - @in keyname: const(char)* @nonull; /*@ the key the grab is set for. */ - @in modifiers: Evas.Modifier_Mask; /*@ a mask of modifiers that must be present to - trigger the event. */ - @in not_modifiers: Evas.Modifier_Mask; /*@ a mask of modifiers that must not not be - present to trigger the event. */ + @in keyname: const(char)* @nonull; [[he key the grab is set for.]] + @in modifiers: Evas.Modifier_Mask; [[A mask of modifiers that must be + present to trigger the event.]] + @in not_modifiers: Evas.Modifier_Mask; [[A mask of modifiers that mus + not not be present to trigger + the event. + ]] } } clip_unset {