import efl_text_types;

interface @beta Efl.Text_Annotate {
   [[Cursor API
   ]]
   c_prefix: efl_text;
   methods {
      // Annotation
      @property annotation {
         [[A new format for $annotation.

           This will replace the format applied by $annotation with $format.
           Assumes that $annotation is a handle for an existing annotation,
           i.e. one that was added using @.annotation_insert to this object.
           Otherwise, this will fail and return $false.
         ]]
         set {
            return: bool; [[$true on success, $false otherwise.]]
         }
         get {
         }
         keys {
            annotation: ptr(Efl.Text_Annotate_Annotation); [[Given annotation]]
         }
         values {
            format: string; [[The new format for the given annotation]]
         }
      }
      range_annotations_get @const {
         [[Returns an iterator of all the handles in a range.
         ]]
         params {
              @in start: ptr(const(Efl.Text_Cursor_Cursor)); [[Start of range]]
              @in end:   ptr(const(Efl.Text_Cursor_Cursor)); [[End of range]]
         }
         return: iterator<ptr(Efl.Text_Annotate_Annotation)> @move; [[Handle of the Annotation]]
      }
      annotation_insert {
         [[Inserts an annotation format in a specified range [$start, $end - 1].

           The $format will be applied to the given range, and the $annotation
           handle will be returned for further handling.
         ]]
         params {
              @in start: ptr(Efl.Text_Cursor_Cursor); [[Start of range]]
              @in end:   ptr(Efl.Text_Cursor_Cursor); [[End of range]]
              @in format: string; [[Annotation format]]
         }
         return: ptr(Efl.Text_Annotate_Annotation); [[Handle of inserted annotation]]
      }
      annotation_del {
         [[Deletes given annotation.

           All formats applied by $annotation will be removed and it will be
           deleted.
         ]]
         params {
            @in annotation: ptr(Efl.Text_Annotate_Annotation); [[Annotation to be
                removed]]
         }
         return: bool; [[$true on success, $false otherwise.]]
      }
      annotation_positions_get {
         [[Sets given cursors to the start and end positions of the annotation.

           The cursors $start and $end will be set to the start and end
           positions of the given annotation $annotation.
         ]]
         params {
             @in annotation: ptr(const(Efl.Text_Annotate_Annotation)); [[Annotation
                 handle to query]]
             @in start: ptr(Efl.Text_Cursor_Cursor); [[Cursor to be set to the start
             position of the annotation in the text]]
             @in end: ptr(Efl.Text_Cursor_Cursor); [[Cursor to be set to the end
             position of the annotation in the text]]
         }
      }
      annotation_is_item {
         [[Whether this is an "item" type of annotation. Should be used before
           querying the annotation's geometry, as only "item" annotations have
           a geometry.

           see @.cursor_item_insert
           see @.item_geometry_get
         ]]
         params {
            annotation: ptr(Efl.Text_Annotate_Annotation); [[Given annotation]]
         }
         return: bool; [[$true if given annotation is an object item, $false otherwise]]
      }
      item_geometry_get {
         [[Queries a given object item for its geometry.

           Note that the provided annotation should be an object item type.
         ]]
         params {
            @in an: ptr(const(Efl.Text_Annotate_Annotation)); [[Given annotation to query]]
            @out x: int; [[X coordinate of the annotation]]
            @out y: int; [[Y coordinate of the annotation]]
            @out w: int; [[Width of the annotation]]
            @out h: int; [[Height of the annotation]]
         }
         return: bool; [[$true if given annotation is an object item, $false otherwise]]
      }
      // Cursor
      @property cursor_item_annotation {
         [[The object-item annotation at the cursor's position.]]
         get {
         }
         values {
            annotation: ptr(Efl.Text_Annotate_Annotation); [[Annotation]]
         }
         keys {
            cur: ptr(Efl.Text_Cursor_Cursor); [[Cursor object]]
         }
      }
      cursor_item_insert {
         [[Inserts a object item at specified position.

           This adds a placeholder to be queried by higher-level code,
           which in turn place graphics on top of it. It essentially places an
           OBJECT REPLACEMENT CHARACTER and set a special annotation to it.
         ]]
         params {
            cur: ptr(Efl.Text_Cursor_Cursor); [[Cursor object]]
            @in item: string;   [[Item key to be used in higher-up
                                  code to query and decided what image, emoticon
                                  etc. to embed.]]
            @in format: string; [[Size format of the inserted item.
                                  This hints how to size the item in the text.]]
         }
         return: ptr(Efl.Text_Annotate_Annotation); [[The annotation handle of the
         inserted item.]]
      }
   }
}