From 16a93a537459267cd2fe90fd664f32a9af9e6366 Mon Sep 17 00:00:00 2001 From: Mike Blumenkrantz Date: Mon, 16 Sep 2019 10:42:27 +0200 Subject: [PATCH] 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; [[Representation of areas that are stretchable in - the image horizontal space.]] + the image horizontal space. The default value + is $NULL.]] vertical: iterator; [[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.]] } } }