forked from enlightenment/efl
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
This commit is contained in:
parent
f7a33a326d
commit
16a93a5374
|
@ -20,7 +20,7 @@ enum @beta Efl.Gfx.Image_Scale_Hint
|
||||||
|
|
||||||
enum @beta Efl.Gfx.Image_Scale_Type
|
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.]]
|
none, [[Use the image's natural size.]]
|
||||||
fill, [[Scale the image so that it matches
|
fill, [[Scale the image so that it matches
|
||||||
the object's area exactly.
|
the object's area exactly.
|
||||||
|
@ -60,7 +60,12 @@ struct Efl.Gfx.Image_Stretch_Region
|
||||||
|
|
||||||
interface @beta Efl.Gfx.Image
|
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 {
|
methods {
|
||||||
@property smooth_scale {
|
@property smooth_scale {
|
||||||
|
@ -70,46 +75,47 @@ interface @beta Efl.Gfx.Image
|
||||||
when scaling images to sizes other than the source image's
|
when scaling images to sizes other than the source image's
|
||||||
original one. This gives better results but is more
|
original one. This gives better results but is more
|
||||||
computationally expensive.
|
computationally expensive.
|
||||||
|
|
||||||
$true by default
|
|
||||||
]]
|
]]
|
||||||
set {}
|
set {}
|
||||||
get {}
|
get {}
|
||||||
values {
|
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 {
|
@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 {
|
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 {
|
@property can_upscale {
|
||||||
[[If $true, the image may be scaled to a larger size. If $false,
|
[[If $true, the image may be scaled to a larger size. If $false,
|
||||||
the image will never be resized larger than its native size.
|
the image will never be resized larger than its native size.
|
||||||
This is set to $true by default.
|
|
||||||
]]
|
]]
|
||||||
values {
|
values {
|
||||||
upscale: bool; [[Allow image upscaling]]
|
upscale: bool; [[Whether to allow image upscaling. The default value is $true.]]
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
@property can_downscale {
|
@property can_downscale {
|
||||||
[[If $true, the image may be scaled to a smaller size. If $false,
|
[[If $true, the image may be scaled to a smaller size. If $false,
|
||||||
the image will never be resized smaller than its native size.
|
the image will never be resized smaller than its native size.
|
||||||
This is set to $true by default.
|
|
||||||
]]
|
]]
|
||||||
values {
|
values {
|
||||||
downscale: bool; [[Allow image downscaling]]
|
downscale: bool; [[Whether to allow image downscaling. The default value is $true.]]
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
@property ratio {
|
@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 {
|
get {
|
||||||
[[Returns 1.0 if not applicable (eg. height = 0).]]
|
|
||||||
}
|
}
|
||||||
values {
|
values {
|
||||||
ratio: double; [[The image's ratio.]]
|
ratio: double; [[The image's ratio. The default value is $[1.0].]]
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
@property content_region {
|
@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
|
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
|
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
|
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.
|
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 { }
|
get { }
|
||||||
values {
|
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 {
|
@property border {
|
||||||
|
@ -152,10 +160,10 @@ interface @beta Efl.Gfx.Image
|
||||||
set {}
|
set {}
|
||||||
get {}
|
get {}
|
||||||
values {
|
values {
|
||||||
l: int; [[The border's left width.]]
|
l: int; [[The border's left width. The default value is $0.]]
|
||||||
r: int; [[The border's right width.]]
|
r: int; [[The border's right width. The default value is $0.]]
|
||||||
t: int; [[The border's top height.]]
|
t: int; [[The border's top height. The default value is $0.]]
|
||||||
b: int; [[The border's bottom height.]]
|
b: int; [[The border's bottom height. The default value is $0.]]
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
@property border_scale {
|
@property border_scale {
|
||||||
|
@ -163,13 +171,11 @@ interface @beta Efl.Gfx.Image
|
||||||
|
|
||||||
This value multiplies the size of the @.border when scaling an
|
This value multiplies the size of the @.border when scaling an
|
||||||
object.
|
object.
|
||||||
|
|
||||||
Default value is 1.0 (no scaling).
|
|
||||||
]]
|
]]
|
||||||
set {}
|
set {}
|
||||||
get {}
|
get {}
|
||||||
values {
|
values {
|
||||||
scale: double; [[The scale factor.]]
|
scale: double; [[The scale factor. The default value is $[1.0].]]
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
@property border_center_fill {
|
@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
|
part of that defined by @.border.set. This is very useful for
|
||||||
making frames and decorations. You would most probably also be
|
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.
|
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 {}
|
set {}
|
||||||
get {}
|
get {}
|
||||||
values {
|
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 {
|
@property stretch_region {
|
||||||
|
@ -204,14 +209,16 @@ interface @beta Efl.Gfx.Image
|
||||||
time.
|
time.
|
||||||
]]
|
]]
|
||||||
set {
|
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 {}
|
get {}
|
||||||
values {
|
values {
|
||||||
horizontal: iterator<ptr(Efl.Gfx.Image_Stretch_Region)>; [[Representation of areas that are stretchable in
|
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
|
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 {
|
@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
|
the size of the loaded pixel buffer. This is the size of the image
|
||||||
as stored in the original file.
|
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 {}
|
get {}
|
||||||
values {
|
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 {
|
@property content_hint {
|
||||||
[[Content hint setting for the image. These hints might be used by EFL
|
[[Content hint setting for the image. These hints might be used by EFL
|
||||||
to enable optimizations.
|
to enable optimizations.
|
||||||
|
@ -244,13 +250,14 @@ interface @beta Efl.Gfx.Image
|
||||||
get {
|
get {
|
||||||
}
|
}
|
||||||
values {
|
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 {
|
@property scale_hint {
|
||||||
[[The scale hint of a given image of the canvas.
|
[[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.
|
scaled versions of its original source image.
|
||||||
]]
|
]]
|
||||||
set {
|
set {
|
||||||
|
@ -258,16 +265,17 @@ interface @beta Efl.Gfx.Image
|
||||||
get {
|
get {
|
||||||
}
|
}
|
||||||
values {
|
values {
|
||||||
hint: Efl.Gfx.Image_Scale_Hint; [[Scalable or static size hint,
|
hint: Efl.Gfx.Image_Scale_Hint; [[Scalable or static size hint. The default value is
|
||||||
see @Efl.Gfx.Image_Scale_Hint]]
|
@Efl.Gfx.Image_Scale_Hint.none.]]
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
@property image_load_error {
|
@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 {
|
get {
|
||||||
}
|
}
|
||||||
values {
|
values {
|
||||||
error: Eina.Error; [[The load error code.]]
|
error: Eina.Error; [[The load error code. A value of $0 indicates no error.]]
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
Loading…
Reference in New Issue