diff --git a/legacy/evas/src/lib/Evas.h b/legacy/evas/src/lib/Evas.h index dd608ec08e..ee5b6e19e1 100644 --- a/legacy/evas/src/lib/Evas.h +++ b/legacy/evas/src/lib/Evas.h @@ -2626,49 +2626,85 @@ EAPI const Eina_List *evas_font_path_list (const Evas *e) EINA_WA /** * @defgroup Evas_Object_Group Generic Object Functions * - * Functions that manipulate generic evas objects. + * Functions that manipulate generic Evas objects. + * + * All Evas displaying units are Evas objects. One handles them all by + * means of the handle ::Evas_Object. Besides Evas treats their + * objects equally, they have types, which define their + * specific behavior (and individual API). + * + * Evas comes with a set of built-in object types: + * - rectangle, + * - line, + * - polygon, + * - text, + * - textblock and + * - image. + * + * These functions apply to any Evas object, whichever type + * thay may have. + * + * @note The built-in types which are most used are rectangles, text + * and images. In fact, with these ones one can create 2D interfaces + * of arbitrary complexity and EFL makes it easy. */ /** * @defgroup Evas_Object_Group_Basic Basic Object Manipulation * - * Methods that are often used, like those that change the color, - * clippers and geometry of the object. + * Methods that are broadly used, like those that change the color, + * clippers and geometry of an Evas object. * * @ingroup Evas_Object_Group */ +/** + * @addtogroup Evas_Object_Group_Basic + * @{ + */ + /** * Clip one object to another. + * * @param obj The object to be clipped * @param clip The object to clip @p obj by * - * This function will clip the object @p obj to the area occupied by the - * object @p clipper. 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 object, so - * the resulting color for the clipped object is - * RESULT = (OBJ * CLIP) / (255 * 255) per color element (red, green, blue and - * alpha). Clipping is recursive, so clip objects may be clipped by other - * objects, and their color will in tern 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 as normal, those that clip 1 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, the objects clipped will not be - * shown either. If the object was being clipped by another object when this - * function is called, it is implicitly removed from the clipper it is being - * clipped to, and now is made to clip its new clipper. + * 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). * - * 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 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). * - * The clip object @p clip must be a valid object, but may also be NULL in - * which case the effect of this function is the same as calling - * evas_object_clip_unset() on the @p obj object. + * 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 + * 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. + * + * @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 @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: * @code @@ -2683,16 +2719,17 @@ EAPI const Eina_List *evas_font_path_list (const Evas *e) EINA_WA * evas_object_clip_set(obj, clipper); * evas_object_show(clipper); * @endcode - * */ EAPI void evas_object_clip_set (Evas_Object *obj, Evas_Object *clip) EINA_ARG_NONNULL(1, 2); /** - * Get the object clipping this one (if any). + * Get the object clipping @p obj (if any). + * * @param obj The object to get the clipper from * - * This function returns the the object clipping @p obj. If @p obj not being - * clipped, NULL is returned. The object @p obj must be a valid object. + * This function returns the the object clipping @p obj. If @p obj is + * not being clipped at all, @c 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(). @@ -2710,13 +2747,14 @@ EAPI void evas_object_clip_set (Evas_Object *obj, Evas EAPI Evas_Object *evas_object_clip_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; /** - * Disable clipping for an object. + * Disable/cease clipping on a clipped @p obj object. * * @param obj The object to cease clipping on * - * This function disables clipping for the object @p obj, if it was already - * clipped. If it wasn't, this has no effect. The object @p obj must be a - * valid object. + * This function disables clipping for the object @p obj, if it was + * already clipped, i.e., its visibility and color get detached from + * the previous clipper. If it wasn't, this has no effect. The object + * @p obj must be a valid ::Evas_Object. * * See also evas_object_clip_set(), evas_object_clipees_get() and * evas_object_clip_get(). @@ -2738,20 +2776,22 @@ EAPI Evas_Object *evas_object_clip_get (const Evas_Object *obj EAPI void evas_object_clip_unset (Evas_Object *obj); /** - * Return a list of objects currently clipped by a specific object. + * Return a list of objects currently clipped by @p obj. * * @param obj The object to get a list of clippees from + * @return a list of objects being clipped by @p obj * - * This returns the inernal list handle that contains all objects clipped by - * the object @p obj. If none are clipped, it 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, are deleted or the clipper is - * 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, not limited just to strange behavior but possible - * segfaults and other strange memory errors. The object @p obj must be a valid - * object. + * 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 @c 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(). @@ -2832,53 +2872,87 @@ EAPI void evas_object_layer_set (Evas_Object *obj, shor * child. So the returned value could be wrong in some case. Don't rely on * it's accuracy. * - * @param obj The given evas object. + * @param obj The given Evas object. * @return Number of the layer. */ EAPI short evas_object_layer_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; /** - * Sets the name of the given evas object to the given name. + * Sets the name of the given Evas object to the given name. + * * @param obj The given object. * @param name The given name. + * + * There might be ocasions where one would like to name his/her + * objects. + * */ EAPI void evas_object_name_set (Evas_Object *obj, const char *name) EINA_ARG_NONNULL(1); /** - * Retrieves the name of the given evas object. + * Retrieves the name of the given Evas object. + * * @param obj The given object. - * @return The name of the object. @c NULL if no name has been given - * to the object. + * @return The name of the object or @c NULL, if no name has been given + * to it. */ EAPI const char *evas_object_name_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; /** - * Increments object reference count to defer deletion + * Increments object reference count to defer its deletion. * - * This increments the reference count of an object, which if greater than - * 0 will defer deletion by evas_object_del() until all references are - * released back to 0. References cannot go below 0 and unreferencing more - * times that referencing will result in the reference count being limited - * to 0. References are limited to 2^32 - 1 for an object. Referencing it more - * than this will result in it being limited to this value. + * @param obj The given Evas object to reference + * + * This increments the reference count of an object, which if greater + * than 0 will defer deletion by evas_object_del() until all + * references are released back (counter back to 0). References cannot + * go below 0 and unreferencing past that will result in the reference + * count being limited to 0. References are limited to 2^32 - 1 + * for an object. Referencing it more than this will result in it + * being limited to this value. + * + * @see evas_object_unref() + * @see evas_object_del() + * + * @note This is a very simple reference counting mechanism! For + * instance, Evas is not ready to check for pending references on a + * canvas deletion, or things like that. This is useful on scenarios + * where, inside a code block, callbacks exist which would possibly + * delete an object we are operating on afterwards. Then, one would + * evas_object_ref() it on the beginning of the block and + * evas_object_unref() it on the end. I would then be deleted at this + * point, if it should be. + * + * Example: + * @code + * evas_object_ref(obj); + * + * // action here... + * evas_object_smart_callback_call(obj, SIG_SELECTED, NULL); + * // more action here... + * evas_object_unref(obj); + * @endcode * - * @param obj The given evas object to reference * @ingroup Evas_Object_Group_Basic * @since 1.1.0 */ EAPI void evas_object_ref (Evas_Object *obj); /** - * Decrements object reference count to defer deletion + * Decrements object reference count. * - * This decrements the reference count of an object. If the object has had - * evas_object_del() called on it while references were more than 0, it will - * be deleted at the time this function is called as it normally would have - * been. See evas_object_ref() for more information. + * @param obj The given Evas object to unreference + * + * This decrements the reference count of an object. If the object has + * had evas_object_del() called on it while references were more than + * 0, it will be deleted at the time this function is called and puts + * the counter back to 0. See evas_object_ref() for more information. + * + * @see evas_object_ref() (for an example) + * @see evas_object_del() * - * @param obj The given evas object to unreference * @ingroup Evas_Object_Group_Basic * @since 1.1.0 */ @@ -2886,148 +2960,251 @@ EAPI void evas_object_unref (Evas_Object *obj); /** - * Deletes the given evas object and frees its memory. + * Marks the given Evas object for deletion (when Evas will free its + * memory). * - * The object's 'free' callback is called when this function is called. - * If the object currently has the focus, its 'focus out' callback is - * also called. + * @param obj The given Evas object. + * + * This call will mark @p obj for deletion, which will take place + * whenever it has no more references to it (see evas_object_ref() and + * evas_object_unref()). + * + * At actual deletion time, which may or may not be just after this + * call, ::EVAS_CALLBACK_DEL and ::EVAS_CALLBACK_FREE callbacks will + * be called. If the object currently had the focus, its + * ::EVAS_CALLBACK_FOCUS_OUT callback will also be called. + * + * @see evas_object_ref() + * @see evas_object_unref() * - * @param obj The given evas object. * @ingroup Evas_Object_Group_Basic */ EAPI void evas_object_del (Evas_Object *obj) EINA_ARG_NONNULL(1); /** - * Moves the given evas object to the given location. - * @param obj The given evas object. - * @param x X position to move the object to, in canvas units. - * @param y Y position to move the object to, in canvas units. + * Move the given Evas object to the given location inside its + * canvas' viewport. + * + * @param obj The given Evas object. + * @param x X position to move the object to, in canvas units. + * @param y Y position to move the object to, in canvas units. + * + * Besides being moved, the object's ::EVAS_CALLBACK_MOVE callback + * will be called. + * + * @note Naturally, newly created objects are placed at the canvas' + * origin: 0, 0. + * * @ingroup Evas_Object_Group_Basic */ EAPI void evas_object_move (Evas_Object *obj, Evas_Coord x, Evas_Coord y) EINA_ARG_NONNULL(1); /** - * Changes the size of the given evas object. - * @param obj The given evas object. - * @param w The new width of the evas object. - * @param h The new height of the evas object. + * Changes the size of the given Evas object. + * + * @param obj The given Evas object. + * @param w The new width of the Evas object. + * @param h The new height of the Evas object. + * + * Besides being resized, the object's ::EVAS_CALLBACK_RESIZE callback + * will be called. + * + * @note Newly created objects have zeroed dimensions. Then, you most + * probably want to use evas_object_resize() on them after they are + * created. * * @note Be aware that resizing an object changes its drawing area, - * but that does imply the object is rescaled! For instance, - * images are filled inside their drawing area using the - * specifications of evas_object_image_fill_set(), thus to scale - * the image to match exactly your drawing area, you need to - * change the evas_object_image_fill_set() as well. Consider the - * following example: - * @code - * // rescale image to fill exactly its area without tiling: - * evas_object_resize(img, w, h); - * evas_object_image_fill_set(img, 0, 0, w, h); - * @endcode - * This is more evident in images, but text, textblock, lines - * and polygons will behave similarly. Check their specific APIs - * to know how to achieve your desired behavior. + * but that does imply the object is rescaled! For instance, images + * are filled inside their drawing area using the specifications of + * evas_object_image_fill_set(). Thus to scale the image to match + * exactly your drawing area, you need to change the + * evas_object_image_fill_set() as well. + * + * @note This is more evident in images, but text, textblock, lines + * and polygons will behave similarly. Check their specific APIs to + * know how to achieve your desired behavior. Consider the following + * example: + * + * @code + * // rescale image to fill exactly its area without tiling: + * evas_object_resize(img, w, h); + * evas_object_image_fill_set(img, 0, 0, w, h); + * @endcode * * @ingroup Evas_Object_Group_Basic */ EAPI void evas_object_resize (Evas_Object *obj, Evas_Coord w, Evas_Coord h) EINA_ARG_NONNULL(1); /** - * Retrieves the position and rectangular size of the given evas object. + * Retrieves the position and (rectangular) size of the given Evas + * object. * - * Note that if any of @p x, @p y, @p w or @p h are @c NULL, the @c NULL - * parameters are ignored. + * @param obj The given Evas object. + * @param x Pointer to an integer in which to store the X coordinate + * of the object. + * @param y Pointer to an integer in which to store the Y coordinate + * of the object. + * @param w Pointer to an integer in which to store the width of the + * object. + * @param h Pointer to an integer in which to store the height of the + * object. + * + * The position, naturally, will be relative to the top left corner of + * the canvas' viewport. + * + * @note Use @c NULL pointers on the geometry components you're not + * interested in: they'll be ignored by the function. * - * @param obj The given evas object. - * @param x Pointer to an integer in which to store the X coordinate of - * the object. - * @param y Pointer to an integer in which to store the Y coordinate of - * the object. - * @param w Pointer to an integer in which to store the width of the - * object. - * @param h Pointer to an integer in which to store the height of the - * object. * @ingroup Evas_Object_Group_Basic */ EAPI void evas_object_geometry_get (const Evas_Object *obj, Evas_Coord *x, Evas_Coord *y, Evas_Coord *w, Evas_Coord *h) EINA_ARG_NONNULL(1); /** - * Makes the given evas object visible. - * @param obj The given evas object. + * Makes the given Evas object visible. + * + * @param obj The given Evas object. + * + * Besides becoming visible, the object's ::EVAS_CALLBACK_SHOW + * callback will be called. + * + * @see evas_object_hide() for more on object visibility. + * @see evas_object_visible_get() + * * @ingroup Evas_Object_Group_Basic */ EAPI void evas_object_show (Evas_Object *obj) EINA_ARG_NONNULL(1); /** - * Makes the given evas object invisible. - * @param obj The given evas object. + * Makes the given Evas object invisible. * - * @note the hidden objects will not be checked for changes and will - * not catch events. That is, they are much ligher than an - * object that is invisible due indirect effects, such as - * clipped or out-of-viewport. + * @param obj The given Evas object. + * + * Hidden objects, besides not being shown at all in your canvas, + * won't be checked for changes on the canvas rendering + * process. Furthermore, they will not catch input events. Thus, they + * are much ligher (in processing needs) than an object that is + * invisible due to indirect causes, such as being clipped or out of + * the canvas' viewport. + * + * Besides becoming hidden, @p obj object's ::EVAS_CALLBACK_SHOW + * callback will be called. + * + * @note All objects are created in the hidden state! If you want them + * shown, use evas_object_show() after their creation. + * + * @see evas_object_show() + * @see evas_object_visible_get() * * @ingroup Evas_Object_Group_Basic */ EAPI void evas_object_hide (Evas_Object *obj) EINA_ARG_NONNULL(1); /** - * Retrieves whether or not the given evas object is visible. - * @param obj The given evas object. - * @return @c 1 if the object is visible. @c 0 otherwise. + * Retrieves whether or not the given Evas object is visible. + * + * @param obj The given Evas object. + * @return @c EINA_TRUE if the object is visible, @c EINA_FALSE + * otherwise. + * + * This retrieves an object's visibily as the one enforced by + * evas_object_show() and evas_object_hide(). + * + * @note The value returned isn't, by any means, influenced by + * clippers covering @obj, it being out of its canvas' viewport or + * stacked below other object. + * + * @see evas_object_show() + * @see evas_object_hide() + * * @ingroup Evas_Object_Group_Basic */ EAPI Eina_Bool evas_object_visible_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; /** - * Sets the general colour of the given evas object to the given colour. - * @param obj The given evas object. - * @param r The red component of the given colour. - * @param g The green component of the given colour. - * @param b The blue component of the given colour. - * @param a The alpha component of the given colour. + * Sets the general/main color of the given Evas object to the given + * one. + * + * @param obj The given Evas object. + * @param r The red component of the given color. + * @param g The green component of the given color. + * @param b The blue component of the given color. + * @param a The alpha component of the given color. + * + * @see evas_object_color_get() + * * @ingroup Evas_Object_Group_Basic */ EAPI void evas_object_color_set (Evas_Object *obj, int r, int g, int b, int a) EINA_ARG_NONNULL(1); /** - * Retrieves the general colour of the given evas object. + * Retrieves the general/main color of the given Evas object. * - * Note that if any of @p r, @p g, @p b or @p a are @c NULL, then the - * @c NULL parameters are ignored. + * @param obj The given Evas object to retrieve color from. + * @param r Pointer to an integer in which to store the red component + * of the color. + * @param g Pointer to an integer in which to store the green + * component of the color. + * @param b Pointer to an integer in which to store the blue component + * of the color. + * @param a Pointer to an integer in which to store the alpha + * component of the color. + * + * Retrieves the “main” color's RGB component (and alpha channel) + * values, which range from 0 to 255. For the alpha channel, + * which defines the object's transparency level, the former value + * means totally trasparent, while the latter means opaque. + * + * Usually you’ll use this attribute for text and rectangle objects, + * where the “main” color is their unique one. If set for objects + * which themselves have colors, like the images one, those colors get + * modulated by this one. + * + * @note All newly created Evas rectangles get the default color + * values of 255 255 255 255 (opaque white). + * + * @note Use @c NULL pointers on the components you're not interested + * in: they'll be ignored by the function. * - * @param obj The given evas object. - * @param r Pointer to an integer in which to store the red component of - * the colour. - * @param g Pointer to an integer in which to store the green component of - * the colour. - * @param b Pointer to an integer in which to store the blue component of - * the colour. - * @param a Pointer to an integer in which to store the alpha component of - * the colour. * @ingroup Evas_Object_Group_Basic */ EAPI void evas_object_color_get (const Evas_Object *obj, int *r, int *g, int *b, int *a) EINA_ARG_NONNULL(1); /** - * Retrieves the evas that the given evas object is on. - * @param obj The given evas object. - * @return The evas that the object is on. + * Retrieves the Evas canvas that the given object lives on. + * + * @param obj The given Evas object. + * @return A pointer to the canvas where the object is on. + * + * This function is most useful at code contexts where you need to + * operate on the canvas but have only the object pointer. + * * @ingroup Evas_Object_Group_Basic */ EAPI Evas *evas_object_evas_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; /** - * Retrieves the object type of the given evas object. + * Retrieves the type of the given Evas object. + * * @param obj The given object. * @return The type of the object. + * + * For Evas' builtin types, the return strings will be one of: + * - "rectangle", + * - "line", + * - "polygon", + * - "text", + * - "textblock" and + * - "image". + * + * For Evas smart objects (see @ref Evas_Smart_Group), the name of the + * smart class itself is returned on this call. For the built-in + * clipped smart object, it is "EvasObjectSmartClipped". */ EAPI const char *evas_object_type_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; - /** * Raise @p obj to the top of its layer. * @@ -3086,6 +3263,10 @@ EAPI Evas_Object *evas_object_above_get (const Evas_Object *obj */ EAPI Evas_Object *evas_object_below_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; +/** + * @} + */ + /** * @defgroup Evas_Object_Group_Events Object Events * @@ -4197,23 +4378,30 @@ EAPI void evas_object_size_hint_padding_set (Evas_Object *obj, Evas /** * Set an attached data pointer to an object with a given string key. + * * @param obj The object to attach the data pointer to * @param key The string key for the data to access it * @param data The ponter to the data to be attached * - * This attaches the pointer @p data to the object @p obj given the string - * @p key. This pointer will stay "hooked" to the object until a new pointer - * with the same string key is attached with evas_object_data_set() or it is - * deleted with evas_object_data_del(). On deletion of the object @p obj, the + * This attaches the pointer @p data to the object @p obj, given the + * access string @p key. This pointer will stay "hooked" to the object + * until a new pointer with the same string key is attached with + * evas_object_data_set() or it is deleted with + * evas_object_data_del(). On deletion of the object @p obj, the * pointers will not be accessible from the object anymore. * * You can find the pointer attached under a string key using - * evas_object_data_get(). It is the job of the calling application to free - * any data pointed to by @p data when it is no longer required. + * evas_object_data_get(). It is the job of the calling application to + * free any data pointed to by @p data when it is no longer required. * - * If @p data is NULL, the old value stored at @p key will be removed but no - * new value will be stored. This is synonymous with calling - * evas_object_data_del() with @p obj and @p key. + * If @p data is @c NULL, the old value stored at @p key will be + * removed but no new value will be stored. This is synonymous with + * calling evas_object_data_del() with @p obj and @p key. + * + * @note This function is very handy when you have data associated + * specifically to an Evas object, being of use only when dealing with + * it. Than you don't have the burden to a pointer to it elsewhere, + * using this family of functions. * * Example: * @@ -4229,19 +4417,22 @@ EAPI void evas_object_size_hint_padding_set (Evas_Object *obj, Evas EAPI void evas_object_data_set (Evas_Object *obj, const char *key, const void *data) EINA_ARG_NONNULL(1, 2); /** - * Return an attached data pointer by its given string key. + * Return an attached data pointer on an Evas object by its given + * string key. + * * @param obj The object to which the data was attached * @param key The string key the data was stored under * @return The data pointer stored, or @c NULL if none was stored * - * This function will return the data pointer attached to the object @p obj - * stored using the string key @p key. If the object is valid and data was - * stored under the given key, the pointer that was stored will be reuturned. - * If this is not the case, NULL will be returned, signifying an invalid object - * or non-existent key. It is possible a NULL pointer was stored given that - * key, but this situation is non-sensical and thus can be considered an error - * as well. NULL pointers are never stored as this is the return value if an - * error occurs. + * This function will return the data pointer attached to the object + * @p obj, stored using the string key @p key. If the object is valid + * and a data pointer was stored under the given key, that pointer + * will be returned. If this is not the case, @c NULL will be + * returned, signifying an invalid object or a non-existent key. It is + * possible that a @c NULL pointer was stored given that key, but this + * situation is non-sensical and thus can be considered an error as + * well. @c NULL pointers are never stored as this is the return value + * if an error occurs. * * Example: * @@ -4257,14 +4448,15 @@ EAPI void evas_object_data_set (Evas_Object *ob EAPI void *evas_object_data_get (const Evas_Object *obj, const char *key) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2) EINA_PURE; /** - * Delete at attached data pointer from an object. + * Delete an attached data pointer from an object. + * * @param obj The object to delete the data pointer from * @param key The string key the data was stored under * @return The original data pointer stored at @p key on @p obj * - * This will remove the stored data pointer from @p obj stored under @p key, - * and return the original pointer stored under @p key, if any, nor @c NULL if - * nothing was stored under that key. + * This will remove the stored data pointer from @p obj stored under + * @p key and return this same pointer, if actually there was data + * there, or @c NULL, if nothing was stored under that key. * * Example: * @@ -4329,17 +4521,27 @@ EAPI Eina_Bool evas_object_anti_alias_get (const Evas_Obje /** - * Sets the scaling factor for an evas object. Does not affect all objects. + * Sets the scaling factor for an Evas object. Does not affect all + * objects. + * + * @param obj The given Evas object. + * @param scale The scaling factor. 1.0 means no scaling, + * default size. + * + * 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. + * + * @see evas_object_scale_get() * - * @param obj The given evas object. - * @param scale The scaling factor. 1.0 == none. * @ingroup Evas_Object_Group_Extras */ EAPI void evas_object_scale_set (Evas_Object *obj, double scale) EINA_ARG_NONNULL(1); /** - * Retrieves the scaling factor for the given evas object. - * @param obj The given evas object. + * Retrieves the scaling factor for the given Evas object. + * + * @param obj The given Evas object. * @return The scaling factor. * * @ingroup Evas_Object_Group_Extras diff --git a/legacy/evas/src/lib/canvas/evas_object_main.c b/legacy/evas/src/lib/canvas/evas_object_main.c index d4888af1e2..9627a3795e 100644 --- a/legacy/evas/src/lib/canvas/evas_object_main.c +++ b/legacy/evas/src/lib/canvas/evas_object_main.c @@ -1249,12 +1249,6 @@ evas_objects_in_rectangle_get(const Evas *e, Evas_Coord x, Evas_Coord y, Evas_Co return in; } -/** - * Retrieves the name of the type of the given evas object. - * @param obj The given object. - * @return The name. - * @ingroup Evas_Object_Group_Basic - */ EAPI const char * evas_object_type_get(const Evas_Object *obj) {