xartigas pushed a commit to branch master.
http://git.enlightenment.org/core/efl.git/commit/?id=16a93a537459267cd2fe90fd664f32a9af9e6366
commit 16a93a537459267cd2fe90fd664f32a9af9e6366
Author: Mike Blumenkrantz <zm...@samsung.com>
Date: Mon Sep 16 10:42:27 2019 +0200
efl/image: improve docs
Summary:
this adds more docs for the overall interface as well as improvements to
existing docs
ref T7717
Reviewers: segfaultxavi
Reviewed By: segfaultxavi
Subscribers: cedric, #reviewers, #committers
Tags: #efl_docs
Maniphest Tasks: T7717
Differential Revision: https://phab.enlightenment.org/D9929
---
src/lib/efl/interfaces/efl_gfx_image.eo | 86 ++++++++++++++++++---------------
1 file changed, 47 insertions(+), 39 deletions(-)
diff --git a/src/lib/efl/interfaces/efl_gfx_image.eo
b/src/lib/efl/interfaces/efl_gfx_image.eo
index 5a9303f786..3075c21a9a 100644
--- a/src/lib/efl/interfaces/efl_gfx_image.eo
+++ b/src/lib/efl/interfaces/efl_gfx_image.eo
@@ -20,7 +20,7 @@ enum @beta Efl.Gfx.Image_Scale_Hint
enum @beta Efl.Gfx.Image_Scale_Type
{
- [[Enumeration that defines scale types of an image.]]
+ [[Enumeration that defines scaling methods to be used when rendering an
image.]]
none, [[Use the image's natural size.]]
fill, [[Scale the image so that it matches
the object's area exactly.
@@ -60,7 +60,12 @@ struct Efl.Gfx.Image_Stretch_Region
interface @beta Efl.Gfx.Image
{
- [[Common APIs for all 2D images that can be rendered on the canvas.]]
+ [[This interface defines a set of common APIs which should be implemented
by image objects.
+
+ These APIs provide the ability to manipulate how images will be rendered,
+ e.g., determining whether to allow upscaling and downscaling at render
time,
+ as well as functionality for detecting errors during the loading process.
+ ]]
methods {
@property smooth_scale {
@@ -70,46 +75,47 @@ interface @beta Efl.Gfx.Image
when scaling images to sizes other than the source image's
original one. This gives better results but is more
computationally expensive.
-
- $true by default
]]
set {}
get {}
values {
- smooth_scale: bool; [[Whether to use smooth scale or not.]]
+ smooth_scale: bool; [[Whether to use smooth scale or not. The
default value is $true.]]
}
}
@property scale_type {
- [[Control how the image is scaled.]]
+ [[Determine how the image is scaled at render time.
+
+ This allows more granular controls for how an image object should
display its internal
+ buffer. The underlying image data will not be modified.
+ ]]
values {
- scale_type: Efl.Gfx.Image_Scale_Type; [[Image scale type]]
+ scale_type: Efl.Gfx.Image_Scale_Type; [[Image scale type to use.
The default value is @Efl.Gfx.Image_Scale_Type.none.]]
}
}
@property can_upscale {
[[If $true, the image may be scaled to a larger size. If $false,
the image will never be resized larger than its native size.
- This is set to $true by default.
]]
values {
- upscale: bool; [[Allow image upscaling]]
+ upscale: bool; [[Whether to allow image upscaling. The default
value is $true.]]
}
}
@property can_downscale {
[[If $true, the image may be scaled to a smaller size. If $false,
the image will never be resized smaller than its native size.
- This is set to $true by default.
]]
values {
- downscale: bool; [[Allow image downscaling]]
+ downscale: bool; [[Whether to allow image downscaling. The default
value is $true.]]
}
}
@property ratio {
- [[The native width/height ratio of the image.]]
+ [[The native width/height ratio of the image.
+
+ The ratio will be 1.0 if it cannot be calculated (e.g. height =
0).]]
get {
- [[Returns 1.0 if not applicable (eg. height = 0).]]
}
values {
- ratio: double; [[The image's ratio.]]
+ ratio: double; [[The image's ratio. The default value is $[1.0].]]
}
}
@property content_region {
@@ -117,7 +123,7 @@ interface @beta Efl.Gfx.Image
We do expect content to be inside the limit defined by the border
or inside the
stretch region. If a stretch region is provided, the content region
will encompass the
- non strechable area that are surrounded by stretchable area. If no
border and no
+ non-stretchable area that are surrounded by stretchable area. If no
border and no
stretch region is set, they are assumed to be zero and the full
object geometry is
where content can be layout on top. The area size change with the
object size.
@@ -125,7 +131,9 @@ interface @beta Efl.Gfx.Image
]]
get { }
values {
- region: Eina.Rect; [[A rectangle inside the object boundary that
where content is expected.]]
+ region: Eina.Rect; [[A rectangle inside the object boundary where
content is expected.
+ The default value is the image object's
geometry with the @Efl.Gfx.Image.border
+ values subtracted.]]
}
}
@property border {
@@ -152,10 +160,10 @@ interface @beta Efl.Gfx.Image
set {}
get {}
values {
- l: int; [[The border's left width.]]
- r: int; [[The border's right width.]]
- t: int; [[The border's top height.]]
- b: int; [[The border's bottom height.]]
+ l: int; [[The border's left width. The default value is $0.]]
+ r: int; [[The border's right width. The default value is $0.]]
+ t: int; [[The border's top height. The default value is $0.]]
+ b: int; [[The border's bottom height. The default value is $0.]]
}
}
@property border_scale {
@@ -163,13 +171,11 @@ interface @beta Efl.Gfx.Image
This value multiplies the size of the @.border when scaling an
object.
-
- Default value is 1.0 (no scaling).
]]
set {}
get {}
values {
- scale: double; [[The scale factor.]]
+ scale: double; [[The scale factor. The default value is $[1.0].]]
}
}
@property border_center_fill {
@@ -182,14 +188,13 @@ interface @beta Efl.Gfx.Image
part of that defined by @.border.set. This is very useful for
making frames and decorations. You would most probably also be
using a filled image (as in @Efl.Gfx.Fill.fill_auto) to use as a
frame.
-
- The default value is @Efl.Gfx.Border_Fill_Mode.default, i.e. render
- and scale the center area, respecting its transparency.
]]
set {}
get {}
values {
- fill: Efl.Gfx.Border_Fill_Mode; [[Fill mode of the center region.]]
+ fill: Efl.Gfx.Border_Fill_Mode; [[Fill mode of the center region.
+ The default value is
@Efl.Gfx.Border_Fill_Mode.default, i.e. render
+ and scale the center area,
respecting its transparency.]]
}
}
@property stretch_region {
@@ -204,14 +209,16 @@ interface @beta Efl.Gfx.Image
time.
]]
set {
- return: Eina.Error; [[return an error code if the stretch_region
provided are incorrect.]]
+ return: Eina.Error; [[Return an error code if the provided values
are incorrect.]]
}
get {}
values {
horizontal: iterator<ptr(Efl.Gfx.Image_Stretch_Region)>;
[[Representation of areas that are stretchable in
- the
image horizontal space.]]
+ the
image horizontal space. The default value
+ is
$NULL.]]
vertical: iterator<ptr(Efl.Gfx.Image_Stretch_Region)>;
[[Representation of areas that are stretchable in
- the image
vertical space.]]
+ the image
vertical space. The default value
+ is
$NULL.]]
}
}
@property image_size {
@@ -221,15 +228,14 @@ interface @beta Efl.Gfx.Image
the size of the loaded pixel buffer. This is the size of the image
as stored in the original file.
- This is a read-only property, and may return 0x0.
+ This is a read-only property and may return 0x0.
]]
get {}
values {
- size: Eina.Size2D; [[The size in pixels.]]
+ size: Eina.Size2D; [[The size in pixels. The default value is the
size of the image's internal buffer.]]
}
}
- /* Note: those are obscure features of evas image. Expose in
Efl.Gfx.Image? */
@property content_hint {
[[Content hint setting for the image. These hints might be used by EFL
to enable optimizations.
@@ -244,13 +250,14 @@ interface @beta Efl.Gfx.Image
get {
}
values {
- hint: Efl.Gfx.Image_Content_Hint; [[Dynamic or static content
hint.]]
+ hint: Efl.Gfx.Image_Content_Hint; [[Dynamic or static content
hint. The default value is
+
@Efl.Gfx.Image_Content_Hint.none.]]
}
}
@property scale_hint {
[[The scale hint of a given image of the canvas.
- The scale hint affects how Evas is to cache
+ The scale hint affects how EFL is to cache
scaled versions of its original source image.
]]
set {
@@ -258,16 +265,17 @@ interface @beta Efl.Gfx.Image
get {
}
values {
- hint: Efl.Gfx.Image_Scale_Hint; [[Scalable or static size hint,
- see @Efl.Gfx.Image_Scale_Hint]]
+ hint: Efl.Gfx.Image_Scale_Hint; [[Scalable or static size hint.
The default value is
+ @Efl.Gfx.Image_Scale_Hint.none.]]
}
}
@property image_load_error {
- [[The (last) file loading error for a given object.]]
+ [[The (last) file loading error for a given object.
+ This value is set to a nonzero value if an error has occurred.]]
get {
}
values {
- error: Eina.Error; [[The load error code.]]
+ error: Eina.Error; [[The load error code. A value of $0 indicates
no error.]]
}
}
}
--
