efl/src/lib/efl/interfaces/efl_gfx_image.eo

import efl_gfx_types;
import eina_types;

enum @beta Efl.Gfx.Image_Content_Hint
{
   [[How an image's data is to be treated by EFL, for optimization.]]
   none = 0,    [[No hint on the content (default).]]
   dynamic = 1, [[The content will change over time.]]
   static = 2   [[The content won't change over time.]]
}

enum @beta Efl.Gfx.Image_Scale_Hint
{
  /* FIXME: Legacy is in Emile, where it does not belong. */
  [[How an image's data is to be treated by EFL, with regard to scaling cache.]]
  none = 0,    [[No hint on the scaling (default).]]
  dynamic = 1, [[Image will be re-scaled over time, thus turning scaling cache OFF for its data.]]
  static = 2   [[Image will not be re-scaled over time, thus turning scaling cache ON for its data.]]
}

enum @beta Efl.Gfx.Image_Scale_Type
{
   [[Enumeration that defines scale types of an image.]]
   fill,        [[Scale the image so that it matches
                  the object's area exactly.
                  The image's aspect ratio might be changed.]]
   fit_inside,  [[Scale the image
                  so that it fits inside the object's area
                  while maintaining the aspect ratio.
                  At least one of the dimensions of the image
                  should be equal to the corresponding dimension
                  of the object.]]
   fit_outside, [[Scale the image
                  so that it covers the entire object area
                  while maintaining the aspect ratio.
                  At least one of the dimensions of the image
                  should be equal to the corresponding
                  dimension of the object.]]
   tile,        [[Tile image at its original size.]]
   none         [[Not scale the image]]
}

interface @beta Efl.Gfx.Image
{
   [[Common APIs for all 2D images that can be rendered on the canvas.]]

   methods {
      @property smooth_scale {
         [[Whether to use high-quality image scaling algorithm for this image.

           When enabled, a higher quality image scaling algorithm is used
           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.]]
         }
      }
      @property scale_type {
         [[Control how the image is scaled.]]
         values {
            scale_type: Efl.Gfx.Image_Scale_Type; [[Image scale type]]
         }
      }
      @property ratio {
         [[The native width/height ratio of the image.]]
         get {
            [[Returns 1.0 if not applicable (eg. height = 0).]]
         }
         values {
            ratio: double; [[The image's ratio.]]
         }
      }
      @property border {
         [[Dimensions of this image's border, a region that does not scale
           with the center area.

           When EFL renders an image, its source may be scaled to fit
           the size of the object. This function sets an area from
           the borders of the image inwards which is not to be scaled.
           This function is useful for making frames and for widget
           theming, where, for example, buttons may be of varying
           sizes, but their border size must remain constant.

           The units used for $l, $r, $t and $b are canvas units (pixels).

           Note: The border region itself may be scaled by the
           @.border_scale.set function.

           Note: By default, image objects have no borders set, i.e.
           $l, $r, $t and $b start as 0.

           Note: Similar to the concepts of 9-patch images or cap insets.
         ]]
         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.]]
         }
      }
      @property border_scale {
         [[Scaling factor applied to the image borders.

           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.]]
         }
      }
      @property border_center_fill {
         [[Specifies how the center part of the object (not the borders)
           should be drawn when EFL is rendering it.

           This function sets how the center part of the image object's
           source image is to be drawn, which must be one of the values
           in @Efl.Gfx.Border_Fill_Mode. By center we mean the complementary
           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, ie. render
           and scale the center area, respecting its transparency.
         ]]
         set {}
         get {}
         values {
            fill: Efl.Gfx.Border_Fill_Mode; [[Fill mode of the center region.]]
         }
      }
      @property image_size {
         [[This represents the size of the original image in pixels.

           This may be different from the actual geometry on screen or even
           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.

           @since 1.20
         ]]
         get {}
         values {
            size: Eina.Size2D; [[The size in pixels.]]
         }
      }

      /* Note: those are obscure features of evas image. Expose in Efl.Gfx.Image? */
      @property content_hint {
         set {
            [[Set the content hint setting of a given image object of the
              canvas.

              This function sets the content hint value of the given image
              of the canvas. For example, if you're on the GL engine and
              your driver implementation supports it, setting this hint to
              #EVAS_IMAGE_CONTENT_HINT_DYNAMIC will make it need zero copies
              at texture upload time, which is an "expensive" operation.
            ]]
         }
         get {
            [[Get the content hint setting of a given image object of the
              canvas.

              This returns #EVAS_IMAGE_CONTENT_HINT_NONE on error.
            ]]
         }
         values {
            hint: Efl.Gfx.Image_Content_Hint; [[Dynamic or static content hint,
                                            see @Efl.Gfx.Image_Content_Hint]]
         }
      }
      @property scale_hint {
         set {
            [[Set the scale hint of a given image of the canvas.

              This function sets the scale hint value of the given image
              object in the canvas, which will affect how Evas is to cache
              scaled versions of its original source image.
            ]]
         }
         get {
            [[Get the scale hint of a given image of the canvas.

              This function returns the scale hint value of the given image
              object of the canvas.
            ]]
         }
         values {
            hint: Efl.Gfx.Image_Scale_Hint; [[Scalable or static size hint,
                                          see @Efl.Gfx.Image_Scale_Hint]]
         }
      }
      @property image_load_error {
         get {
             [[Gets the (last) file loading error for a given object.]]
         }
         values {
            error: Eina.Error; [[The load error code.]]
         }
      }
   }
   events {
      image,preload: void; [[Image data has been preloaded.]]
      image,resize: void;  [[Image was resized (its pixel data).]]
      image,unload: void;  [[Image data has been unloaded (by some mechanism in
                       EFL that threw out the original image data).]]
   }
}