q66 pushed a commit to branch master. http://git.enlightenment.org/core/efl.git/commit/?id=d381b79e95aca383d2d72d4e4711bd321ab8b3be
commit d381b79e95aca383d2d72d4e4711bd321ab8b3be Author: Daniel Kolesa <d.kol...@osg.samsung.com> Date: Wed Sep 2 12:51:15 2015 +0100 evas object: more doc conversion --- src/lib/evas/canvas/evas_object.eo | 462 +++++++++++++++++-------------------- 1 file changed, 209 insertions(+), 253 deletions(-) diff --git a/src/lib/evas/canvas/evas_object.eo b/src/lib/evas/canvas/evas_object.eo index b540685..630db49 100644 --- a/src/lib/evas/canvas/evas_object.eo +++ b/src/lib/evas/canvas/evas_object.eo @@ -285,35 +285,37 @@ abstract Evas.Object (Eo.Base, Evas.Common_Interface, Efl.Gfx.Base, Efl.Gfx.Stac } @property size_hint_aspect { set { - /*@ - Sets the hints for an object's aspect ratio. - - This is not a size enforcement in any way, it's just a hint that should - be used whenever appropriate. + [[Sets the hints for an object's aspect ratio. - If any of the given aspect ratio terms are @c 0, - the object's container will ignore the aspect and scale @p obj to - occupy the whole available area, for any given policy. + This is not a size enforcement in any way, it's just a hint + that should be used whenever appropriate. - @note Smart objects(such as elementary) can have their own size hint - policy. So calling this API may or may not affect the size of smart objects. + If any of the given aspect ratio terms are 0, the object's + container will ignore the aspect and scale $obj to occupy + the whole available area, for any given policy. - @see evas_object_size_hint_aspect_get() for more information. */ + Note: Smart objects(such as elementary) can have their own + size hint policy. So calling this API may or may not affect + the size of smart objects. + ]] } get { - /*@ - Retrieves the hints for an object's aspect ratio. + [[Retrieves the hints for an object's aspect ratio. - The different aspect ratio policies are documented in the - #Evas_Aspect_Control type. A container respecting these size hints - would @b resize its children accordingly to those policies. + The different aspect ratio policies are documented in the + #Evas_Aspect_Control type. A container respecting these size + hints would resize its children accordingly to those policies. - For any policy, if any of the given aspect ratio terms are @c 0, - the object's container should ignore the aspect and scale @p obj to - occupy the whole available area. If they are both positive - integers, that proportion will be respected, under each scaling - policy. + For any policy, if any of the given aspect ratio terms are 0, + the object's container should ignore the aspect and scale $obj + to occupy the whole available area. If they are both positive + integers, that proportion will be respected, under each + scaling policy. + Note: Use $null pointers on the hint components you're not + interested in: they'll be ignored by the function. + ]] + /* FIXME-doc These images illustrate some of the #Evas_Aspect_Control policies: @image html any-policy.png @@ -334,132 +336,130 @@ abstract Evas.Object (Eo.Base, Evas.Common_Interface, Efl.Gfx.Base, Efl.Gfx.Stac 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. - + --- Example: @dontinclude evas-aspect-hints.c @skip if (strcmp(ev->key, "c") == 0) @until } See the full @ref Example_Evas_Aspect_Hints "example". - - @see evas_object_size_hint_aspect_set() */ + */ } values { - aspect: Evas.Aspect_Control; /*@ The policy/type of aspect ratio to apply to @p obj. */ - w: Evas.Coord; /*@ Integer to use as aspect width ratio term. */ - h: Evas.Coord; /*@ Integer to use as aspect height ratio term. */ + aspect: Evas.Aspect_Control; [[The policy/type of aspect ratio to apply to $obj.]] + w: Evas.Coord; [[Integer to use as aspect width ratio term.]] + h: Evas.Coord; [[Integer to use as aspect height ratio term.]] } } @property clip { set { - /*@ - Clip one object to another. - - This function will clip the object @p obj to the area occupied by - the object @p clip. This means the object @p obj will only be - visible within the area occupied by the clipping object (@p clip). - - The color of the object being clipped will be multiplied by the - color of the clipping one, so the resulting color for the former - will be <code>RESULT = (OBJ * CLIP) / (255 * 255)</code>, per color - element (red, green, blue and alpha). - - Clipping is recursive, so clipping objects may be clipped by - others, and their color will in term be multiplied. You may @b not - set up circular clipping lists (i.e. object 1 clips object 2, which - clips object 1): the behavior of Evas is undefined in this case. - - Objects which do not clip others are visible in the canvas as - normal; <b>those that clip one or more objects become invisible - themselves</b>, only affecting what they clip. If an object ceases - to have other objects being clipped by it, it will become visible - again. - - The visibility of an object affects the objects that are clipped by - it, so if the object clipping others is not shown (as in - evas_object_show()), the objects clipped by it will not be shown - either. - - If @p obj was being clipped by another object when this function is - called, it gets implicitly removed from the old clipper's domain - and is made now to be clipped by its new clipper. - + [[Clip one object to another. + + This function will clip the object $obj to the area occupied + by the object $clip. This means the object $obj will only be + visible within the area occupied by the clipping object + ($clip). + + The color of the object being clipped will be multiplied by + the color of the clipping one, so the resulting color for the + former will be "RESULT = (OBJ * CLIP) / (255 * 255)", per color + element (red, green, blue and alpha). + + Clipping is recursive, so clipping objects may be clipped by + others, and their color will in term be multiplied. You may + not set up circular clipping lists (i.e. object 1 clips + object 2, which clips object 1): the behavior of Evas is + undefined in this case. + + Objects which do not clip others are visible in the canvas as + normal; those that clip one or more objects become invisible + themselves, only affecting what they clip. If an object ceases + to have other objects being clipped by it, it will become + visible again. + + The visibility of an object affects the objects that are + clipped by it, so if the object clipping others is not shown + (as in \@ref evas_object_show), the objects clipped by it will + not be shown either. + + If $obj was being clipped by another object when this function + is called, it gets implicitly removed from the old clipper's + domain and is made now to be clipped by its new clipper. + + Note: At the moment the only objects that can validly be used + to clip other objects are rectangle objects. All other object + types are invalid and the result of using them is undefined. + The clip object $clip must be a valid object, but can also be + $null, in which case the effect of this function is the same + as @.clip_unset on the $obj object. + ]] + /* FIXME-doc The following figure illustrates some clipping in Evas: @image html clipping.png @image rtf clipping.png @image latex clipping.eps - - @note At the moment the <b>only objects that can validly be used to - clip other objects are rectangle objects</b>. All other object - types are invalid and the result of using them is undefined. The - clip object @p clip must be a valid object, but can also be @c - NULL, in which case the effect of this function is the same as - calling evas_object_clip_unset() on the @p obj object. - + --- Example: @dontinclude evas-object-manipulation.c @skip solid white clipper (note that it's the default color for a @until evas_object_show(d.clipper); - See the full @ref Example_Evas_Object_Manipulation "example". */ + See the full @ref Example_Evas_Object_Manipulation "example". + */ } get { - /*@ - Get the object clipping @p obj (if any). - - This function returns the object clipping @p obj. If @p obj is - not being clipped at all, $null is returned. The object @p obj - must be a valid .Evas_Object. - - See also evas_object_clip_set(), evas_object_clip_unset() and - evas_object_clipees_get(). + [[Get the object clipping $obj (if any). + This function returns the object clipping $obj. If $obj is + not being clipped at all, $null is returned. The object $obj + must be a valid Evas_Object. + ]] + /* FIXME-doc Example: @dontinclude evas-object-manipulation.c @skip if (evas_object_clip_get(d.img) == d.clipper) @until return - See the full @ref Example_Evas_Object_Manipulation "example". */ + See the full @ref Example_Evas_Object_Manipulation "example". + */ } values { - clip: Evas.Object * @nonull; /*@ The object to clip @p obj by */ + clip: Evas.Object * @nonull; [[The object to clip $obj by.]] } } @property size_hint_padding { set { - /*@ - Sets the hints for an object's padding space. - - This is not a size enforcement in any way, it's just a hint that - should be used whenever appropriate. + [[Sets the hints for an object's padding space. - @note Smart objects(such as elementary) can have their own size hint - policy. So calling this API may or may not affect the size of smart objects. + This is not a size enforcement in any way, it's just a hint + that should be used whenever appropriate. - @see evas_object_size_hint_padding_get() for more information */ + Note: Smart objects(such as elementary) can have their own + size hint policy. So calling this API may or may not affect + the size of smart objects. + ]] } get { - /*@ - Retrieves the hints for an object's padding space. + [[Retrieves the hints for an object's padding space. + + Padding is extra space an object takes on each of its + delimiting rectangle sides, in canvas units. - Padding is extra space an object takes on each of its delimiting - rectangle sides, in canvas units. This space will be rendered + 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. + ]] + /* FIXME-doc + This space will be rendered transparent, naturally, as in the following figure: @image html padding-hints.png @image rtf padding-hints.png @image latex padding-hints.eps - - 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. - + --- Example: @dontinclude evas-hints.c @skip evas_object_size_hint_padding_set @@ -468,76 +468,65 @@ abstract Evas.Object (Eo.Base, Evas.Common_Interface, Efl.Gfx.Base, Efl.Gfx.Stac In this example the padding 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_padding_set() */ + */ } values { - l: Evas.Coord; /*@ Integer to specify left padding. */ - r: Evas.Coord; /*@ Integer to specify right padding. */ - t: Evas.Coord; /*@ Integer to specify top padding. */ - b: Evas.Coord; /*@ Integer to specify bottom padding. */ + l: Evas.Coord; [[Integer to specify left padding.]] + r: Evas.Coord; [[Integer to specify right padding.]] + t: Evas.Coord; [[Integer to specify top padding.]] + b: Evas.Coord; [[Integer to specify bottom padding.]] } } @property repeat_events { set { - /*@ - Set whether an Evas object is to repeat events. - - If @p repeat is $true, it will make events on @p obj to also - be repeated for the @b next lower object in the objects' stack (see - see evas_object_below_get()). + [[Set whether an Evas object is to repeat events. - If @p repeat is $false, events occurring on @p obj will be - processed only on it. + If $repeat is $true, it will make events on $obj to also be + repeated for the next lower object in the objects' stack (see + see \@ref evas_object_below_get). + If $repeat is $false, events occurring on $obj will be + processed only on it. + ]] + /* FIXME-doc Example: @dontinclude evas-stacking.c @skip if (strcmp(ev->key, "r") == 0) @until } See the full @ref Example_Evas_Stacking "example". - - @see evas_object_repeat_events_get() - @see evas_object_pass_events_set() - @see evas_object_propagate_events_set() - @see evas_object_freeze_events_set() */ + */ } get { - /*@ - Determine whether an object is set to repeat events. - - @return whether @p obj is set to repeat events ($true) - or not ($false) - - @see evas_object_repeat_events_set() for an example - @see evas_object_pass_events_get() - @see evas_object_propagate_events_get() - @see evas_object_freeze_events_get() */ + [[Determine whether an object is set to repeat events.]] } values { - repeat: bool; /*@ whether @p obj is to repeat events ($true) or not - ($false) */ + repeat: bool; [[Whether $obj is to repeat events ($true) or + not ($false).]] } } @property size_hint_weight { set { - /*@ - Sets the hints for an object's weight. + [[Sets the hints for an object's weight. - This is not a size enforcement in any way, it's just a hint that - should be used whenever appropriate. - - This is a hint on how a container object should @b resize a given - child within its area. Containers may adhere to the simpler logic - of just expanding the child object's dimensions to fit its own (see - the #EVAS_HINT_EXPAND helper weight macro) or the complete one of - taking each child's weight hint as real @b weights to how much of - its size to allocate for them in each axis. A container is supposed - to, after @b normalizing the weights of its children (with weight - hints), distribute the space it has to layout them by those factors - -- most weighted children get larger in this process than the least - ones. + This is not a size enforcement in any way, it's just a hint + that should be used whenever appropriate. + This is a hint on how a container object should resize a given + child within its area. Containers may adhere to the simpler + logic of just expanding the child object's dimensions to fit + its own (see the #EVAS_HINT_EXPAND helper weight macro) or + the complete one of taking each child's weight hint as real + weights to how much of its size to allocate for them in each + axis. A container is supposed to, after normalizing the + weights of its children (with weight hints), distribut + the space it has to layout them by those factors -- most + weighted children get larger in this process than the least + ones. + + Note: Default weight hint values are 0.0, for both axis. + ]] + /* FIXME-doc Example: @dontinclude evas-hints.c @skip evas_object_size_hint_weight_set @@ -546,190 +535,157 @@ abstract Evas.Object (Eo.Base, Evas.Common_Interface, Efl.Gfx.Base, Efl.Gfx.Stac In this example the weight hints change the behavior of an Evas box when layouting its children. See the full @ref Example_Evas_Size_Hints "example". - - @note Default weight hint values are 0.0, for both axis. - - @see evas_object_size_hint_weight_get() for more information */ + */ } get { - /*@ - Retrieves the hints for an object's weight. + [[Retrieves the hints for an object's weight. - Accepted values are zero or positive values. Some users might use - this hint as a boolean, but some might consider it as a @b - proportion, see documentation of possible users, which in Evas are - the @ref Evas_Object_Box "box" and @ref Evas_Object_Table "table" - smart objects. + Accepted values are zero or positive values. Some users might + use this hint as a boolean, but some might consider it as a + proportion, see documentation of possible users, which in + Evas are the \@ref Evas_Object_Box "box" and + \@ref Evas_Object_Table "table" smart objects. - 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.0 + 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_weight_set() for an example */ + Note: If $obj is invalid, then the hint components will be + set with 0.0. + ]] } values { - x: double; /*@ Nonnegative double value to use as horizontal weight hint. */ - y: double; /*@ Nonnegative double value to use as vertical weight hint. */ + x: double; [[Non-negative double value to use as horizontal weight hint.]] + y: double; [[Non-negative double value to use as vertical weight hint.]] } } @property name { set { - /*@ - Sets the name of the given Evas object to the given name. - - There might be occasions where one would like to name his/her - objects. + [[Sets the name of the given Evas object to the given name. + There might be occasions where one would like to name his/her + objects. + ]] + /* FIXME-doc Example: @dontinclude evas-events.c @skip d.bg = evas_object_rectangle_add(d.canvas); @until evas_object_name_set(d.bg, "our dear rectangle"); - See the full @ref Example_Evas_Events "example". */ + See the full @ref Example_Evas_Events "example". + */ } get { - /*@ - Retrieves the name of the given Evas object. - - @return The name of the object or $null, if no name has been given - to it. + [[Retrieves the name of the given Evas object. + Return: The name of the object or $null, if no name has been + given to it. + ]] + /* FIXME-doc Example: @dontinclude evas-events.c @skip fprintf(stdout, "An object got focused: %s\n", @until evas_focus_get - See the full @ref Example_Evas_Events "example". */ + See the full @ref Example_Evas_Events "example". + */ } values { - name: const(char)*; /*@ The given name. */ + name: const(char)*; [[The given name.]] } } @property scale { set { - /*@ - Sets the scaling factor for an Evas object. Does not affect all - objects. - - This will multiply the object's dimension by the given factor, thus - altering its geometry (width and height). Useful when you want - scalable UI elements, possibly at run time. - - @note Only text and textblock objects have scaling change - handlers. Other objects won't change visually on this call. + [[Sets the scaling factor for an Evas object. Does not affect + all objects. - @see evas_object_scale_get() + This will multiply the object's dimension by the given factor, + thus altering its geometry (width and height). Useful when + you want scalable UI elements, possibly at run time. - @ingroup Evas_Object_Group_Extras */ + Note: Only text and textblock objects have scaling change + handlers. Other objects won't change visually on this call. + ]] } get { - /*@ - Retrieves the scaling factor for the given Evas object. - - @return The scaling factor. - - @ingroup Evas_Object_Group_Extras - - @see evas_object_scale_set() */ + [[Retrieves the scaling factor for the given Evas object.]] } values { - scale: double; /*@ The scaling factor. <c>1.0</c> means no scaling, - default size. */ + scale: double; [[The scaling factor. 1.0 means no scaling, + default size.]] } } @property static_clip { set { - /*@ - Set a hint flag on the given Evas object that it's used as a "static - clipper". - - This is a hint to Evas that this object is used as a big static - clipper and shouldn't be moved with children and otherwise - considered specially. The default value for new objects is - $false. - - @see evas_object_static_clip_get() + [[Set a hint flag on the given Evas object that it's used as a + "static clipper". - @ingroup Evas_Object_Group_Extras */ + This is a hint to Evas that this object is used as a big + static clipper and shouldn't be moved with children and + otherwise considered specially. The default value for new + objects is $false. + ]] } get { - /*@ - Get the "static clipper" hint flag for a given Evas object. - - @return $true if it's set as a static clipper, - $false otherwise. - - @see evas_object_static_clip_set() for more details - - @ingroup Evas_Object_Group_Extras */ + [[Get the "static clipper" hint flag for a given Evas object.]] } values { - is_static_clip: bool; /*@ $true if it's to be used as a static - clipper, $false otherwise. */ + is_static_clip: bool; [[$true if it's to be used as a static + clipper, $false otherwise.]] } } @property focus { set { - /*@ - Sets or unsets a given object as the currently focused one on its - canvas. + [[Sets or unsets a given object as the currently focused one on + its canvas. - Changing focus only affects where (key) input events go. There can - be only one object focused at any time. If @p focus is $true, - @p obj will be set as the currently focused object and it will - receive all keyboard events that are not exclusive key grabs on - other objects. + Changing focus only affects where (key) input events go. + There can be only one object focused at any time. If $focus + is $true, $obj will be set as the currently focused object + and it will receive all keyboard events that are not + exclusive key grabs on other objects. + See also @.key_grab, @.key_ungrab. + ]] + /* FIXME-doc Example: @dontinclude evas-events.c @skip evas_object_focus_set @until evas_object_focus_set See the full example @ref Example_Evas_Events "here". - - @see evas_object_focus_get - @see evas_focus_get - @see evas_object_key_grab - @see evas_object_key_ungrab */ + */ } get { - /*@ - Retrieve whether an object has the focus. - - @return $true if the object has the focus, $false otherwise. - - If the passed object is the currently focused one, $true is - returned. $false is returned, otherwise. + [[Retrieve whether an object has the focus. + If the passed object is the currently focused one, $true is + returned. $false is returned, otherwise. + ]] + /* FIXME-doc Example: @dontinclude evas-events.c @skip And again @until something is bad See the full example @ref Example_Evas_Events "here". - - @see evas_object_focus_set - @see evas_focus_get - @see evas_object_key_grab - @see evas_object_key_ungrab */ + */ } values { - focus: bool; /*@ $true, to set it as focused or $false, - to take away the focus from it. */ + focus: bool; [[$true when set as focused or $false otherwise.]] } } @property is_frame_object { set { - /*@ @since 1.2 */ + [[@since 1.2]] } get { - /*@ @since 1.2 */ + [[@since 1.2]] } values { - is_frame: bool; /*@ in */ + is_frame: bool; } } @property map_enable { --