path: root/src/lib/evas/canvas/efl_canvas_text.eo

struct @extern Efl.Canvas.Text.Cursor;
struct @extern Evas.Textblock.Style;
struct @extern Evas.Textblock.Annotation;
struct Evas.Textblock.Node_Format;

struct Evas_Textblock_Rectangle
{
   [[Rectangle that represents some geometry in this object.]]
   x: Evas.Coord; [[rectangle's x coords.]]
   y: Evas.Coord; [[rectangle's y coords.]]
   w: Evas.Coord; [[rectangle's width.]]
   h: Evas.Coord; [[rectangle's height.]]
}

class Efl.Canvas.Text (Evas.Object, Efl.Text)
{
   legacy_prefix: evas_object_textblock;
   methods {
      @property valign {
         set {
            [[Sets the vertical alignment of text within the textblock object
              as a whole.

              Normally alignment is 0.0 (top of object). Values given should
              be between 0.0 and 1.0 (1.0 bottom of object, 0.5 being
              vertically centered etc.).

              @since 1.1
            ]]
         }
         get {
            [[Gets the vertical alignment of a textblock

              @since 1.1
            ]]
         }
         values {
            align: double; [[The alignment set for the object.]]
         }
      }
      @property bidi_delimiters {
         set {
            [[Sets the BiDi delimiters used in the textblock.

              BiDi delimiters are use for in-paragraph separation of bidi
              segments. This is useful for example in recipients fields of
              e-mail clients where bidi oddities can occur when mixing RTL
              and LTR.

              @since 1.1
            ]]
         }
         get {
            [[Gets the BiDi delimiters used in the textblock.

              BiDi delimiters are use for in-paragraph separation of bidi
              segments. This is useful for example in recipients fields of
              e-mail clients where bidi oddities can occur when mixing RTL
              and LTR.

              @since 1.1
            ]]
         }
         values {
            delim: const(char)*; [[A null terminated string of delimiters, e.g ",|" or $null if empty.]]
         }
      }
      @property replace_char {
         set {
            [[Set the "replacement character" to use for the given textblock object.]]
         }
         get {
            [[Gets the "replacement character" to use for the given text
              object.
            ]]
         }
         values {
            ch: const(char)*; [[The charset name.]]
         }
      }
      @property legacy_newline {
         set {
            [[Sets newline mode. When true, newline character will behave
              as a paragraph separator.

              @since 1.1
            ]]
         }
         get {
            [[Gets newline mode. When true, newline character behaves
              as a paragraph separator.

              @since 1.1
            ]]
         }
         values {
            mode: bool; [[$true for legacy mode, $false otherwise.]]
         }
      }
      @property style {
         set {
            [[Set the objects style to $ts.]]
         }
         get {
            [[Get the style of an object.]]
         }
         values {
            ts: const(Evas.Textblock.Style)*; [[The style.]]
         }
      }
      @property size_formatted {
         get {
            [[Get the formatted width and height.

              This calculates the actual size after restricting the
              textblock to the current size of the object.

              The main difference between this and @.size_native.get
              is that the "native" function does not wrapping into account
              it just calculates the real width of the object if it was
              placed on an infinite canvas, while this function gives the
              size after wrapping according to the size restrictions of the
              object.

              For example for a textblock containing the text:
              "You shall not pass!" with no margins or padding and assuming
              a monospace font and a size of 7x10 char widths (for simplicity)
              has a native size of 19x1 and a formatted size of 5x4.
            ]]
         }
         values {
            w: Evas.Coord; [[The width of the object.]]
            h: Evas.Coord; [[The height of the object.]]
         }
      }
      @property cursor {
         get {
            [[Get the object's main cursor.]]
            return: Efl.Canvas.Text.Cursor *;
         }
      }
      @property size_native {
         get {
            [[Get the native width and height.

              This calculates the actual size without taking account the
              current size of the object.

              The main difference between this and @.size_formatted.get
              is that the "native" function does not take wrapping into
              account it just calculates the real width of the object if
              it was placed on an infinite canvas, while the "formatted"
              function gives the size after  wrapping text according to
              the size restrictions of the object.

              For example for a textblock containing the text:
              "You shall not pass!" with no margins or padding and assuming
              a monospace font and a size of 7x10 char widths (for simplicity)
              has a native size of 19x1 and a formatted size of 5x4.
            ]]
         }
         values {
            w: Evas.Coord; [[The width returned.]]
            h: Evas.Coord; [[The height returned.]]
         }
      }
      @property style_insets {
         get {}
         values {
            l: Evas.Coord;
            r: Evas.Coord;
            t: Evas.Coord;
            b: Evas.Coord;
         }
      }
      @property annotation {
         set {
            [[Sets 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.
            ]]
         return: bool; [[$true on success, $false otherwise.]]
         }
         get {
         [[Returns the format (string) of this annotation.

           @since 1.18
         ]]
         }
         keys {
            annotation: Evas.Textblock.Annotation *;
         }
         values {
            format: const(char)*;
         }
      }
      line_number_geometry_get @const {
         [[Get the geometry of a line number.]]
         return: bool; [[$true on success, $false otherwise.]]
         params {
            @in line: int; [[The line number.]]
            @out cx: Evas.Coord; [[x coord of the line.]]
            @out cy: Evas.Coord; [[y coord of the line.]]
            @out cw: Evas.Coord; [[w coord of the line.]]
            @out ch: Evas.Coord; [[h coord of the line.]]
         }
      }
      style_user_pop {
         [[Del the from the top of the user style stack.

           See also @.style.get.

           @since 1.2
         ]]
      }
      cursor_new @const {
         [[Create a new cursor, associate it to the obj and init it to point
           to the start of the textblock.

           Association to the object means the cursor will be updated when
           the object will change.

           Note: if you need speed and you know what you are doing, it's
           slightly faster to just allocate the cursor yourself and not
           associate it. (only people developing the actual object, and
           not users of the object).
         ]]
         return: Efl.Canvas.Text.Cursor *; [[The new cursor.]]
      }
      cursor_free {
         [[Free the cursor and unassociate it from the object.

           Note: do not use it to free unassociated cursors.]]

         params {
            @in cur: Efl.Canvas.Text.Cursor *; [[The cursor to free.]]
         }
      }
      cursor_pos_set {
         [[Set the cursor pos.]]
         params {
            @in cur: Efl.Canvas.Text.Cursor *; [[The cursor to be set with $pos]]
            @in pos: int; [[The pos to set.]]
         }
      }
      cursor_pos_get {
         [[Gets the cursor position.]]
         return: int; [[The current position of $cur in the text.]]
         params {
            @in cur: const(Efl.Canvas.Text.Cursor)*; [[The cursor to get the position from.]]
         }
      }
      cursor_paragraph_first {
         [[Sets the cursor to the start of the first text node.]]
         params {
            @in cur: Efl.Canvas.Text.Cursor *; [[The cursor to update.]]
         }
      }
      cursor_paragraph_last {
         [[Sets the cursor to the end of the last text node.]]
         params {
            @in cur: Efl.Canvas.Text.Cursor *; [[The cursor to set.]]
         }
      }
      cursor_paragraph_next {
         [[Advances to the start of the next text node.]]
         return: bool; [[$true on success, $false otherwise.]]
         params {
            @in cur: Efl.Canvas.Text.Cursor *; [[The cursor to update.]]
         }
      }
      cursor_paragraph_prev {
         [[Advances to the end of the previous text node]]
         return: bool; [[$true on success, $false otherwise.]]
         params {
            @in cur: Efl.Canvas.Text.Cursor *; [[The cursor to update.]]
         }
      }
      cursor_word_end {
         [[Moves the cursor to the end of the word under the cursor.

           @since 1.2
         ]]
         return: bool; [[$true on success, $false otherwise.]]
         params {
            @in cur: Efl.Canvas.Text.Cursor *; [[The moved cursor.]]
         }
      }
      cursor_char_next {
         [[ Advances $cur one character forward, if possible ]]
         return: bool; [[$true on success, $false otherwise.]]
         params {
            @in cur: Efl.Canvas.Text.Cursor *; [[The moved cursor.]]
         }
      }
      cursor_char_prev {
         [[ Advances $cur one character backwards, if possible ]]
         return: bool; [[$true on success, $false otherwise.]]
         params {
            @in cur: Efl.Canvas.Text.Cursor *; [[The cursor to advance.]]
         }
      }
      cursor_word_start {
         [[ Moves the cursor to the start of the word under the cursor.
         @since 1.2]]
         return: bool; [[$true on success, $false otherwise.]]
         params {
            @in cur: Efl.Canvas.Text.Cursor *; [[The cursor to move.]]
         }
      }
      cursor_paragraph_char_first {
         [[Goes to the first char in the node the cursor is pointing on.]]
         params {
            @in cur: Efl.Canvas.Text.Cursor *; [[The cursor to move.]]
         }
      }
      cursor_paragraph_char_last {
         [[Go to the last char in a text node.]]
         params {
            @in cur: Efl.Canvas.Text.Cursor *; [[The cursor to move.]]
         }
      }
      cursor_line_set {
         [[Sets the cursor position to the start of a given line.]]
         return: bool; [[$true on success, $false otherwise.]]
         params {
            @in cur: Efl.Canvas.Text.Cursor *; [[The cursor to update.]]
            @in line: int; [[The line number to which the cursor is set.]]
         }
      }
      cursor_line_char_first {
         [[Go to the start of the current line.]]
         params {
            @in cur: Efl.Canvas.Text.Cursor *; [[The cursor to move.]]
         }
      }
      cursor_line_char_last {
         [[Go to the end of the current line.]]
         params {
            @in cur: Efl.Canvas.Text.Cursor *; [[The cursor to move.]]
         }
      }
      cursor_compare {
         [[Compares two cursors.

           Note that 0 will be returned if they are cursors of different
           textblock objects.
         ]]
         return: int; [[-1 if cur1 < cur2, 0 if cur1 == cur2, 1 otherwise.]]
         params {
            @in cur1: const(Efl.Canvas.Text.Cursor)*; [[The first cursor.]]
            @in cur2: const(Efl.Canvas.Text.Cursor)*; [[The second cursor.]]
         }
      }
      cursor_copy {
         [[Copies a given cursor to a destination cursor.

           Makes $cur_dest point to the same place as $cur. Does nothing if
           these are cursors for different textblock objects.
         ]]
         params {
            @in cur_dest: Efl.Canvas.Text.Cursor *; [[The destination cursor.]]
            @in cur: const(Efl.Canvas.Text.Cursor)*; [[The source cursor.]]
         }
      }
      cursor_text_append {
         [[Adds text to the current cursor position and sets the cursor to
           *before* the start of the text just added.
           See also @.cursor_text_prepend.
         ]]
         return: int; [[The length of the added text.]]
         params {
            @in cur: Efl.Canvas.Text.Cursor *; [[The cursor to where to add text at.]]
            @in text: const(char)*; [[The text to add.]]
         }
      }
      cursor_text_prepend {
         [[Adds text to the current cursor position and sets the cursor to
           *after* the start of the text just added.
           See also @.cursor_text_append.
         ]]
         return: int; [[The length of the added text.]]
         params {
            @in cur: Efl.Canvas.Text.Cursor *; [[The cursor to where to add text at.]]
            @in text: const(char)*; [[The text to add.]]
         }
      }
      cursor_char_delete {
         [[Delete the character at the location of the cursor.

           If there's a format pointing to this position, delete it as well.
         ]]
         params {
            @in cur: Efl.Canvas.Text.Cursor *; [[The cursor pointing to the current location.]]
         }
      }
      cursor_range_delete {
         [[Delete the range between given cursors.]]
         params {
            @in cur1: Efl.Canvas.Text.Cursor *; [[Range start position.]]
            @in cur2: Efl.Canvas.Text.Cursor *; [[Range end position.]]
         }
      }
      cursor_paragraph_text_get {
         [[Returns the text of the paragraph cur points to.

           The text is returned as markup.
         ]]
         return: const(char)*; [[The markup of the paragraph point by $cur.]]
         params {
            @in cur: const(Efl.Canvas.Text.Cursor)*; [[The cursor we query.]]
         }
      }
      cursor_paragraph_text_length_get {
         [[Returns the length of the paragraph.

          The paragraph we query is pointed by $cur.
          Using this is cheaper the eina_unicode_strlen().
         ]]
         return: int; [[The length of the paragraph on success, -1 otehrwise.]]
         params {
            @in cur: const(Efl.Canvas.Text.Cursor)*; [[The cursor which we query
            the paragraph with.]]
         }
      }
      cursor_visible_range_get {
         [[Return the currently visible range.

           The given $start and $end cursor act like an out-variables here,
           as these are set to the positions of the start and the end of the
           visible range in the text, respectively.

           @since 1.1.
         ]]
         return: bool; [[$true on success, $false otherwise.]]
         params {
            @in start: Efl.Canvas.Text.Cursor *; [[Range start position.]]
            @in end: Efl.Canvas.Text.Cursor *; [[Range end position.]]
         }
      }
      cursor_range_text_get {
         [[Returns the text in the range between $cur1 and $cur2.]]
         return: own(char*); [[The text in the given range.]]
         params {
            @in cur1: const(Efl.Canvas.Text.Cursor)*; [[Range start position.]]
            @in cur2: const(Efl.Canvas.Text.Cursor)*; [[Range end position.]]
         }
      }
      cursor_content_get {
         [[Returns the content in the given cursor's position

           The content is a representation of the actual content: if it is a
           visible format, then it will return a markup string (e.g. "<ps>"); if
           it is a unicode character, then it will return the UTF-8 encoding of
           this character.
         ]]
         return: own(char*); [[The representation of the content at $cur.]]
         params {
            @in cur: const(Efl.Canvas.Text.Cursor)*; [[The cursor to query.]]
         }
      }
      cursor_geometry_bidi_get {
         [[Returns the geometry of two cursors ("split cursor"), if logical cursor is
           between LTR/RTL text, also considering paragraph direction.
           Upper cursor is shown for the text of the same direction as paragraph,
           lower cursor - for opposite.

           Split cursor geometry is valid only  in '|' cursor mode.
           In this case $true is returned and cx2, cy2, cw2, ch2 are set,
           otherwise it behaves like cursor_geometry_get.
           @since 1.8
         ]]
         return: bool; [[$true for split cursor, $false otherwise.]]
         params {
            @in cur: const(Efl.Canvas.Text.Cursor)*; [[The cursor to query.]]
            @out cx: int; [[the x of the cursor (or upper cursor).]]
            @out cy: int; [[the y of the cursor (or upper cursor).]]
            @out cw: int; [[the width of the cursor (or upper cursor).]]
            @out ch: int; [[the height of the cursor (or upper cursor).]]
            @out cx2: int; [[the x of the lower cursor.]]
            @out cy2: int; [[the y of the lower cursor.]]
            @out cw2: int; [[the width of the lower cursor.]]
            @out ch2: int; [[the height of the lower cursor.]]
            @in ctype: Efl.Canvas.Text.Cursor.Type; [[the type of the cursor.]]
         }
      }
      cursor_geometry_get {
         [[Returns the geometry of the cursor. Depends on the type of cursor
           requested. This should be used instead of char_geometry_get because
           there are weird special cases with BiDi text.  in '_' cursor
           mode (i.e a line below the char) it's the same as char_geometry
           get, except for the case of the last char of a line which
           depends on the paragraph direction.

           in '|' cursor mode (i.e a line between two chars) it is very
           variable.  For example consider the following visual string:
           "abcCBA" (ABC are rtl chars), a cursor pointing on A should actually
           draw a '|' between the c and the C.
         ]]
         return: int; [[line number of the char on success, -1 on error.]]
         params {
            @in cur: const(Efl.Canvas.Text.Cursor)*; [[The cursor to query.]]
            @out cx: int; [[the x of the cursor (or upper cursor).]]
            @out cy: int; [[the y of the cursor (or upper cursor).]]
            @out cw: int; [[the width of the cursor (or upper cursor).]]
            @out ch: int; [[the height of the cursor (or upper cursor).]]
            @out dir: Evas.BiDi_Direction; [[the direction of the cursor, can be NULL.]]
            @in ctype: Efl.Canvas.Text.Cursor.Type; [[the type of the cursor.]]
         }
      }
      cursor_char_geometry_get {
         [[Returns the geometry of the char at cur.]]
         return: int; [[line number on success, -1 otherwise.]]
         params {
            @in cur: const(Efl.Canvas.Text.Cursor) *; [[the position of the char.]]
            @out cx: int; [[the x of the char.]]
            @out cy: int; [[the y of the char.]]
            @out cw: int; [[the w of the char.]]
            @out ch: int; [[the h of the char.]]
         }
      }
      cursor_pen_geometry_get {
         [[Returns the geometry of the pen at cur.]]
         return: int; [[line number on success, -1 otherwise.]]
         params {
            @in cur: const(Efl.Canvas.Text.Cursor) *; [[the position of the char.]]
            @out cpen_x: int; [[the x of the char.]]
            @out cy: int; [[the y of the char.]]
            @out cadv: int; [[the w of the char.]]
            @out ch: int; [[the h of the char.]]
         }
      }
      cursor_line_geometry_get {
         [[Returns the geometry of the char at cur.]]
         return: int; [[line number on success, -1 otherwise.]]
         params {
            @in cur: const(Efl.Canvas.Text.Cursor) *; [[the position of the line.]]
            @out cx: int; [[the x of the line.]]
            @out cy: int; [[the y of the line.]]
            @out cw: int; [[the w of the line.]]
            @out ch: int; [[the h of the line.]]
         }
      }
      cursor_range_geometry_get {
         [[Get the geometry of a range.]]
         return: list<Evas.Textblock.Rectangle *> *; [[List of rectangles representing the range.]]
         params {
            @in cur1: const(Efl.Canvas.Text.Cursor)*; [[one side of the range.]]
            @in cur2: const(Efl.Canvas.Text.Cursor)*; [[other size of the range.]]
         }
      }
      cursor_range_simple_geometry_get {
         [[Get the geometry of a range.

           The simple geometry is the geomtry in which rectangles in middle
           lines of range are merged into one big rectangle.
           @since 1.13
         ]]
         return: free(own(iterator<Evas.Textblock.Rectangle *> *),
                 eina_iterator_free); [[iterator of rectangles representing the range.]]
         params {
            @in cur1: const(Efl.Canvas.Text.Cursor)*; [[one side of the range.]]
            @in cur2: const(Efl.Canvas.Text.Cursor)*; [[other size of the range.]]
         }
      }
      cursor_eol_get {
         [[Check if the cursor points to the end of the line.]]
         return: bool; [[$true if $cur is at end of line , $false otherwise.]]
         params {
            @in cur: const(Efl.Canvas.Text.Cursor)*; [[Cursor to query.]]
         }
      }
      cursor_char_coord_set {
         [[Set the position of the cursor according to the X and Y coordinates.]]
         return: bool; [[$true on success, $false otherwise.]]
         params {
            @in cur: Efl.Canvas.Text.Cursor *; [[The cursor to be set.]]
            @in x: Evas.Coord; [[x coord to set by.]]
            @in y: Evas.Coord; [[y coord to set by.]]
         }
      }
      cursor_line_coord_set {
         [[Set the cursor position according to the y coord.]]
         return: int; [[line number on success, -1 otherwise.]]
         params {
            @in cur: Efl.Canvas.Text.Cursor *; [[The cursor to be set.]]
            @in y: Evas.Coord; [[y coord to set by.]]
         }
      }
      object_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.
         ]]
         return: Evas.Textblock.Annotation *; [[The annotation handle of the
         inserted item.]]
         params {
            @in cur: Efl.Canvas.Text.Cursor *; [[Position of the inserted item.]]
            @in format: const(char)*; [[Format of the inserted item.
            See Format styles.]]
         }
      }
      style_user_peek @const {
         [[Get (don't remove) the style at the top of the user style stack.

           See also @.style.get.

           @since 1.2
         ]]
         return: const(Evas.Textblock.Style)*; [[The style of the object.]]
      }
      clear {
         [[Clear the textblock object.

           Note: Does *NOT* free the Evas object itself.
         ]]
         legacy: null;
      }
      style_user_push {
         [[Push ts to the top of the user style stack.

           FIXME: API is solid but currently only supports 1 style in the
           stack.

           The user style overrides the corresponding elements of the
           regular style. This is the proper way to do theme overrides
           in code.

           See also @.style.set.

           @since 1.2
         ]]
         params {
            @in ts: Evas.Textblock.Style *; [[The style to set.]]
         }
      }
      obstacle_add {
         [[Add obstacle evas object $eo_obs to be observed during layout
           of text.

           The textblock does the layout of the text according to the
           position of the obstacle.

           @since 1.15
         ]]
         params {
            @in eo_obs: Evas.Object *;
         }
         return: bool; [[$true on success, $false otherwise.]]
      }
      obstacle_del {
         [[Removes $eo_obs from observation during text layout.

           @since 1.15
         ]]
         params {
            @in eo_obs: Evas.Object *;
         }
         return: bool; [[$true on success, $false otherwise.]]
      }
      obstacles_update {
         [[Triggers for relayout due to obstacles' state change.

           The obstacles alone don't affect the layout, until this is
           called. Use this after doing changes (moving, positioning etc.)
           in the obstacles that you  would like to be considered in the
           layout.

           For example: if you have just repositioned the obstacles to
           differrent coordinates relative to the textblock, you need to
           call this so it will consider this new state and will relayout
           the text.

           @since 1.15
         ]]
      }
      annotation_insert {
         [[Inserts an annotation format in a specified range [$start, $end - 1].

           This will add both opening and closing formats for the given
           $format.
           Returns a handle to manipulate the inserted annotation.

           @since 1.18
         ]]
         /*
         return: free(own(iterator<Evas.Textblock.Annotation *> *),
                 eina_iterator_free); [[Handle of the Annotation]]
          */
         return: Evas.Textblock.Annotation *;
         params {
              @in start: Efl.Canvas.Text.Cursor *;
              @in end:   Efl.Canvas.Text.Cursor *;
              @in format: const(char)*;
         }
      }
      annotation_range_get_all {
         [[Returns an iterator of all the handles in a range.

           @since 1.18
         ]]
         return: free(own(iterator<Evas.Textblock.Annotation *> *),
                 eina_iterator_free); [[Handle of the Annotation]]
         params {
              @in start: const(Efl.Canvas.Text.Cursor)*;
              @in end:   const(Efl.Canvas.Text.Cursor)*;
         }
      }
      annotation_del {
         [[Deletes $annotation.

           All formats applied by $annotations will be removed and it will be
           deleted.
         ]]
         return: bool; [[$true on success, $false otherwise.]]
         params {
            @in annotation: Evas.Textblock.Annotation *;
         }
      }
   }
   implements {
      Eo.Base.constructor;
      Eo.Base.destructor;
      Eo.Base.dbg_info_get;
      Evas.Object.paragraph_direction.set;
      Evas.Object.paragraph_direction.get;
      Efl.Text.text.set;
      Efl.Text.text.get;
   }
}