#ifndef _EFL_CANVAS_TEXTBLOCK_EO_H_
#define _EFL_CANVAS_TEXTBLOCK_EO_H_
#ifndef _EFL_CANVAS_TEXTBLOCK_EO_CLASS_TYPE
#define _EFL_CANVAS_TEXTBLOCK_EO_CLASS_TYPE
typedef Eo Efl_Canvas_Textblock;
#endif
#ifndef _EFL_CANVAS_TEXTBLOCK_EO_TYPES
#define _EFL_CANVAS_TEXTBLOCK_EO_TYPES
#endif
/**
* @brief This is the Canvas-level text class. This class only takes care of
* rendering text, if you need user interaction consider the classes in
* Efl.Ui.
*
* @note No text will be rendered until a font, a font size and a font color
* are specified. This can be accomplished using @ref efl_text_font_family_get,
* @ref efl_text_font_size_get and @ref efl_text_color_get. Alternatively,
* @ref efl_canvas_textblock_style_apply can be used providing the attributes
* @c font, @c font_size and @c color.
*
* @since 1.24
*
* @ingroup Efl_Canvas_Textblock
*/
#define EFL_CANVAS_TEXTBLOCK_CLASS efl_canvas_textblock_class_get()
EVAS_API EVAS_API_WEAK const Efl_Class *efl_canvas_textblock_class_get(void) EINA_CONST;
/**
* @brief Whether the object is empty (no text) or not.
*
* @param[in] obj The object.
*
* @return @c true if empty.
*
* @since 1.24
*
* @ingroup Efl_Canvas_Textblock
*/
EVAS_API EVAS_API_WEAK Eina_Bool efl_canvas_textblock_is_empty_get(const Eo *obj);
/**
* @brief Creates a new cursor and adds it to the text object. This cursor can
* be used to manipulate and iterate the content of the text object.
*
* @param[in] obj The object.
*
* @return The created text cursor.
*
* @since 1.24
*
* @ingroup Efl_Canvas_Textblock
*/
EVAS_API EVAS_API_WEAK Efl_Text_Cursor_Object *efl_canvas_textblock_cursor_create(Eo *obj) EFL_TRANSFER_OWNERSHIP EINA_WARN_UNUSED_RESULT;
/**
* @brief Returns the currently visible range.
*
* The given @c start and @c end cursors are output variables: they are set to
* the positions of the start and the end of the visible range in the text,
* respectively.
*
* @param[in] obj The object.
* @param[in] start Range start position.
* @param[in] end Range end position.
*
* @return @c true on success.
*
* @since 1.24
*
* @ingroup Efl_Canvas_Textblock
*/
EVAS_API EVAS_API_WEAK Eina_Bool efl_canvas_textblock_visible_range_get(Eo *obj, Efl_Text_Cursor_Object *start, Efl_Text_Cursor_Object *end);
/**
* @brief Gets the left, right, top and bottom insets of the text.
*
* The inset is any applied padding on the text (which is calculated internally
* by styling applied to Textblock).
*
* @param[in] obj The object.
* @param[out] l Left padding.
* @param[out] r Right padding.
* @param[out] t Top padding.
* @param[out] b Bottom padding.
*
* @since 1.24
*
* @ingroup Efl_Canvas_Textblock
*/
EVAS_API EVAS_API_WEAK void efl_canvas_textblock_style_insets_get(const Eo *obj, int *l, int *r, int *t, int *b);
/**
* @brief BiDi delimiters are used for in-paragraph separation of bidirectional
* segments. This is useful, for example, in the recipient fields of e-mail
* clients where bidi oddities can occur when mixing RTL (right-to-left) and
* LTR (left-to-right) text.
*
* @param[in] obj The object.
* @param[in] delim A null terminated string of delimiters, e.g ",|" or @c null
* if empty.
*
* @since 1.24
*
* @ingroup Efl_Canvas_Textblock
*/
EVAS_API EVAS_API_WEAK void efl_canvas_textblock_bidi_delimiters_set(Eo *obj, const char *delim);
/**
* @brief BiDi delimiters are used for in-paragraph separation of bidirectional
* segments. This is useful, for example, in the recipient fields of e-mail
* clients where bidi oddities can occur when mixing RTL (right-to-left) and
* LTR (left-to-right) text.
*
* @param[in] obj The object.
*
* @return A null terminated string of delimiters, e.g ",|" or @c null if
* empty.
*
* @since 1.24
*
* @ingroup Efl_Canvas_Textblock
*/
EVAS_API EVAS_API_WEAK const char *efl_canvas_textblock_bidi_delimiters_get(const Eo *obj);
/**
* @brief When @c true, the newline character will behave as a paragraph
* separator. Paragraph separator equal U+2029, and new line equal U+000A. This
* will effect a lot of text behaviour like @ref efl_text_cursor_object_move
* method.
*
* @param[in] obj The object.
* @param[in] mode @c true to treat new line as paragraph separator, @c false
* otherwise.
*
* @since 1.24
*
* @ingroup Efl_Canvas_Textblock
*/
EVAS_API EVAS_API_WEAK void efl_canvas_textblock_newline_as_paragraph_separator_set(Eo *obj, Eina_Bool mode);
/**
* @brief When @c true, the newline character will behave as a paragraph
* separator. Paragraph separator equal U+2029, and new line equal U+000A. This
* will effect a lot of text behaviour like @ref efl_text_cursor_object_move
* method.
*
* @param[in] obj The object.
*
* @return @c true to treat new line as paragraph separator, @c false
* otherwise.
*
* @since 1.24
*
* @ingroup Efl_Canvas_Textblock
*/
EVAS_API EVAS_API_WEAK Eina_Bool efl_canvas_textblock_newline_as_paragraph_separator_get(const Eo *obj);
/**
* @brief Applies several style attributes at once using a formatting string.
* Given style attributes override previous values, leaving other attributes
* unaffected. This is akin to setting individual style attributes using
* properties like @ref efl_text_font_slant_get or @ref efl_text_wrap_get, for
* example.
*
* The formatting string is a whitespace-separated list of
* attribute=value pairs.
*
* The following attributes are accepted:
*
* - @c font: Name of the font to use. Default value is empty, meaning that no
* text will be rendered. Requires @c font_size and @c font_color. See
* @ref efl_text_font_family_get.
*
* - @c font_fallbacks: Comma-delimited list of fonts to try if finding the
* primary font fails. Example:
* font_fallbacks=consolas,courier,monospace. Default value is empty.
* See @ref efl_text_font_fallbacks_get.
*
* - @c font_size: Height of font, in points. Default value is 0. Requires
* @c font and @c font_color. See @ref efl_text_font_size_get.
*
* - @c font_source: Path to the file containing the font to use. Example:
* font_source=/usr/share/fonts/Sans.ttf. Default value is empty. See
* @ref efl_text_font_source_get.
*
* - @c font_weight: Thickness of the font. The value must be one of:
* @c normal, @c thin, @c ultralight, @c extralight, @c light, @c book,
* @c medium, @c semibold, @c bold, @c ultrabold, @c extrabold, @c black and
* @c extrablack. Default value is @c normal. See
* @ref efl_text_font_weight_get.
*
* - @c font_style: Style of the font. The value must be one of: @c normal,
* @c oblique and @c italic. Default value is @c normal. See
* @ref efl_text_font_slant_get.
*
* - @c font_width: How wide the font is, relative to its height. The value
* must be one of: @c normal, @c ultracondensed, @c extracondensed,
* @c condensed, @c semicondensed, @c semiexpanded, @c expanded,
* @c extraexpanded and @c ultraexpanded. Default value is @c normal. See
* @ref efl_text_font_weight_get.
*
* - @c lang: A 2-letter ISO 639-1 language code, @c auto (to use the system
* locale setting) or @c none (to disable language support). Example:
* lang=he. Default value is empty. See @ref efl_text_font_lang_get.
*
* - @c color: Color code for the text (See bottom for the complete list of
* supported codes). Default value is rgba(0,0,0,0) meaning that
* no text will be rendered. Requires @c font and @c font_size. See
* @ref efl_text_color_get.
*
* - @c underline_color: Color code for the text underline (See bottom for the
* complete list of supported codes). Default value is
* rgba(0,0,0,0) meaning that no underline will be rendered. Requires
* @c underline_type. See @ref efl_text_underline_color_get.
*
* - @c secondary_underline_color: Color code for the secondary text underline
* (See bottom for the complete list of supported codes). Only valid when
* underline_type=double. Default value is rgba(0,0,0,0)
* meaning that secondary underline will not be rendered. See
* @ref efl_text_secondary_underline_color_get.
*
* - @c underline_dashed_color: Color code for the dashed underline (See bottom
* for the complete list of supported codes). Only valid when
* underline_type=dashed. Default value is rgba(0,0,0,0)
* meaning that dashed underline will not be rendered. See
* @ref efl_text_underline_dashed_color_get.
*
* - @c outline_color: Color code for the text outline (See bottom for the
* complete list of supported codes). Only valid when the @c effect_type
* attribute includes an outline. Default value is rgba(0,0,0,0)
* meaning that no outline will be rendered. See
* @ref efl_text_outline_color_get.
*
* - @c shadow_color: Color code for the text shadow (See bottom for the
* complete list of supported codes). Only valid when the @c effect_type
* attribute includes a shadow. Default value is rgba(0,0,0,0)
* meaning that no shadow will be rendered. See @ref efl_text_shadow_color_get.
*
* - @c glow_color: Color code for the glow component of the text (See bottom
* for the complete list of supported codes). Only valid when the
* @c effect_type attribute includes a glow. Default value is
* rgba(0,0,0,0) meaning that no glow will be rendered. See
* @ref efl_text_glow_color_get.
*
* - @c secondary_glow_color: Color code for the secondary (inner) glow
* component of the text (See bottom for the complete list of supported codes).
* Only valid when the @c effect_type attribute includes a glow. Default value
* is rgba(0,0,0,0) meaning that only the primary @c glow_color
* will be used. See @ref efl_text_secondary_glow_color_get.
*
* - @c background_color: Color code for the background of the text (See bottom
* for the complete list of supported codes). Use a fully transparent color to
* disable the background. Default value is rgba(0,0,0,0) meaning
* that no background will be rendered. Requires @c background_type. See
* @ref efl_text_background_color_get.
*
* - @c strikethrough_color: Color code for the line striking through the text
* (See bottom for the complete list of supported codes). Only valid when
* strikethrough_type=single Default value is
* rgba(0,0,0,0) meaning that no strike-through line will be rendered.
* See @ref efl_text_strikethrough_color_get.
*
* - @c align: Horizontal alignment of the text. The value can either be a
* decimal number ($[0.0] means "left" and 1.0 means "right"), a
* percentage ($[0%] means "left" and 100% means "right") or one
* of: @c auto (Respects LTR/RTL settings), @c locale (Respects language
* direction settings), @c center (Centers the text in the line), @c middle
* (Alias for @c center), @c left (Puts the text at the left of the line),
* @c right (Puts the text at the right of the line), @c start (Alias for
* @c auto), @c end (Puts the text at the opposite side of LTR/RTL settings).
* Default value is @c auto. See @ref efl_text_horizontal_align_get.
*
* - @c valign: Vertical alignment of the text. The value can either be a
* decimal number ($[0.0] means "top" and 1.0 means "bottom"), a
* percentage ($[0%] means "top" and 100% means "bottom") or one
* of: @c top (Puts the text at the top of the text box), @c center (Puts the
* text at the middle of the text box), @c middle (Alias for @c center),
* @c bottom (Puts the text at the bottom of the text box), @c baseline (Puts
* the text's baseline at the middle of the text box), @c base (Alias for
* @c baseline). Default value is @c baseline. See
* @ref efl_text_vertical_align_get.
*
* - @c wrap: Wrapping policy of the text. The value must be one of the
* following: @c word (Only wraps lines at word boundaries), @c char (Wraps at
* any character), @c mixed (Wraps at word boundaries if possible, at any
* character if not), @c hyphenation (Hyphenate if possible, otherwise try
* wrapping at word boundaries or at any character) or @c none to disable
* wrapping. Default value is @c none. See @ref efl_text_wrap_get.
*
* - @c left_margin: Distance in pixels from the left side of the text block to
* the beginning of the text (inner margin). The value can be a number (to set
* the margin), or a number preceded by + or - to
* increment or decrement the existing margin value. @c reset is also accepted,
* to set the margin to 0 pixels. Default value is 0. Examples:
* left_margin=10, left_margin=+10,
* left_margin=reset.
*
* - @c right_margin: Distance in pixels from the right side of the text block
* to the beginning of the text (inner margin). The value can be a number (to
* set the margin), or a number preceded by + or -
* to increment or decrement the existing margin value. @c reset is also
* accepted, to set the margin to 0 pixels. Default value is 0.
* Examples: right_margin=10, right_margin=+10,
* right_margin=reset.
*
* - @c underline_type: Style of the underline. The value must be one of
* @c none (No underlining), @c single (A single line under the text) ,
* @c double (Two lines under the text), @c dashed (A dashed line under the
* text). Default value is @c none. Requires either @c underline_color,
* @c secondary_underline_color or @c underline_dashed_color. See
* @ref efl_text_underline_type_get.
*
* - @c strikethrough_type: Enables crossed-out text. Possible values are
* @c single and @c none. Default value is @c none. Requires
* @c strikethrough_color. See @ref efl_text_strikethrough_type_get.
*
* - @c background_type: Enables background color for the text. Possible values
* are @c solid and @c none. Default value is @c none. Requires
* @c background_color. See @ref efl_text_background_type_get.
*
* - @c effect_type: Controls a number of decorations around the text, like
* shadow, outline and glow, including combinations of them. Possible values
* are @c none (No decoration), @c shadow, @c outline, @c soft_outline,
* @c outline_shadow, @c outline_soft_shadow, @c glow (alias for
* @c soft_outline), @c far_shadow, @c soft_shadow and @c far_soft_shadow.
* Default value is @c none. Requires either @c shadow_color, @c glow_color or
* @c outline_color. See @ref efl_text_effect_type_get
*
* - @c shadow_direction: Indicate the shadow direction. Valid positions are
* @c bottom_right, @c bottom, @c bottom_left, @c left, @c top_left, @c top,
* @c top_right and @c right. Requires either @c effect_type. See
* @ref efl_text_shadow_direction_get.
*
* - @c tab_stops: Size (in pixels) of the tab character. The value must be a
* number greater than one. Default value is 32. See
* @ref efl_text_tab_stops_get.
*
* - @c line_size: Distance (in pixels) from the baseline of one line of text
* to the next. This is, a value of 0 would render all lines on
* top of each other (However, this value will be ignored if it results in
* overlapping lines of text). Setting this value sets @c line_rel_size to
* 0% (disables it). Default value is 0.
*
* - @c line_rel_size: Distance (in percentage over the natural line height)
* from the baseline of one line of text to the next. A value of
* 100% does not have any impact, smaller values render lines closer
* together and bigger values render them further apart. Setting this value
* sets @c line_size to 0 (disables it). Default value is
* 0%.
*
* - @c line_gap: Additional empty space (in pixels) between the bottom of one
* line of text and the top of the next. Setting this value sets
* @c line_rel_gap to 0% (disables it). Default value is
* 0. See @ref efl_text_line_gap_get.
*
* - @c line_rel_gap: Additional empty space (in percentage over the natural
* line height) between the bottom of one line of text and the top of the next.
* Setting this value sets @c line_gap to 0 (disables it).
* Default value is 0%. See @ref efl_text_line_rel_gap_get.
*
* - @c line_fill: An alternate way to specify the @c line_size as a percentage
* of the canvas height. A value of 100% means that a single line
* fills the canvas, whereas 25% means that 4 lines fit in the
* same height. When both @c line_fill and @c line_size are specified the one
* resulting in the smallest line size is used. Default value is
* 0.
*
* - @c ellipsis: Controls automatic addition of ellipsis "..." to replace text
* which cannot be shown. The value must be a number indicating the position of
* the ellipsis inside the visible text. 0.0 means the beginning
* of the text, 1.0 means the end of the text, and values in
* between mean the proportional position inside the text. Any value smaller
* than 0 or greater than 1 disables ellipsis. Default value is
* -1. Examples: ellipsis=0.5 See
* @Efl.Text_Format.ellipsis.
*
* - @c password: Enabling this causes all characters to be replaced by
* @c replacement_char. This is useful for password input boxes. Value must be
* either @c on or @c off. Default value is off. Requires
* @c replacement_char. See @ref efl_text_password_get.
*
* - @c replacement_char: Character to use instead of the actual characters
* when @c password is @c on. Default value is empty, meaning that no
* replacement will take place. Requires @c password. Examples:
* replacement_char=*. See @ref efl_text_replacement_char_get.
*
* - @c underline_dashed_width: Length (in pixels) of the dashes when
* @c underline_type is @c dashed. Default value is 6. See
* @ref efl_text_underline_dashed_width_get.
*
* - @c underline_dashed_gap: Length (in pixels) of the gaps between the dashes
* when @c underline_type is @c dashed. Default value is 2. See
* @ref efl_text_underline_dashed_gap_get.
*
* - @c underline_height: Width (in pixels) of the single underline when
* @c underline_type is @c single. Default value is 1. See
* @ref efl_text_underline_height_get.
*
* - @c gfx_filter: Experimental filter name. See @ref Efl_Gfx_Filter for more
* information.
*
* Color codes: Colors can be specified using any of the following formats:
* #RRGGBB, #RRGGBBAA, #RGB,
* #RGBA, rgb(r,g,b), rgba(r,g,b,a).
* Additionally, X11 color names like @c red or @c blanchedalmond can be used.
* See https://en.wikipedia.org/wiki/X11_color_names for the full list.
*
* @param[in] obj The object.
* @param[in] style A whitespace-separated list of
* attribute=value pairs, for example, font=sans font_size=30
* color=white.
*
* @since 1.24
*
* @ingroup Efl_Canvas_Textblock
*/
EVAS_API EVAS_API_WEAK void efl_canvas_textblock_style_apply(Eo *obj, const char *style);
/**
* @brief A string representing the complete set of attributes applied to this
* text object. This includes the default attributes plus any additional style
* applied with @ref efl_canvas_textblock_style_apply or individual style
* properties like @ref efl_text_font_slant_get or @ref efl_text_wrap_get.
*
* See @ref efl_canvas_textblock_style_apply for the description of all
* attributes.
*
* @param[in] obj The object.
*
* @return A whitespace-separated list of attribute=value pairs,
* for example, font=sans font_size=30 color=white.
*
* @since 1.24
*
* @ingroup Efl_Canvas_Textblock
*/
EVAS_API EVAS_API_WEAK const char *efl_canvas_textblock_all_styles_get(const Eo *obj);
/**
* @brief The formatted width and height of this text block.
*
* This calculates the actual size after restricting the text block to the
* current size of the object.
*
* The main difference between this and
* @ref efl_canvas_textblock_size_native_get is that the "native" function does
* not take wrapping into account: it just calculates the real width of the
* object as if it was placed on an infinite canvas, while
* @ref efl_canvas_textblock_size_formatted_get gives the size after wrapping
* text according to the size restrictions of the object.
*
* The formatted width and height do not include padding size. To get the total
* size of text with style, you need to query padding size from
* @ref efl_canvas_textblock_style_insets_get.
*
* For example a text block 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.
*
* @param[in] obj The object.
*
* @return The formatted size of the object (after wrapping).
*
* @since 1.24
*
* @ingroup Efl_Canvas_Textblock
*/
EVAS_API EVAS_API_WEAK Eina_Size2D efl_canvas_textblock_size_formatted_get(const Eo *obj);
/**
* @brief The native width and height of this text block.
*
* This calculates the actual size without taking account the current size of
* the object.
*
* The main difference between this and
* @ref efl_canvas_textblock_size_formatted_get is that the "native" function
* does not take wrapping into account: it just calculates the real width of
* the object as if it was placed on an infinite canvas, while
* @ref efl_canvas_textblock_size_formatted_get gives the size after wrapping
* text according to the size restrictions of the object.
*
* The native width and height do not include padding size. To get the total
* size of text with style, you need to query padding size from
* @ref efl_canvas_textblock_style_insets_get.
*
* For example a text block 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.
*
* @param[in] obj The object.
*
* @return The native size of the object (without wrapping).
*
* @since 1.24
*
* @ingroup Efl_Canvas_Textblock
*/
EVAS_API EVAS_API_WEAK Eina_Size2D efl_canvas_textblock_size_native_get(const Eo *obj);
#ifdef EFL_BETA_API_SUPPORT
/**
* @brief Add obstacle object @c eo_obs to be avoided during layout of text.
*
* The textblock does the layout of the text according to the position of the
* obstacle.
*
* @param[in] obj The object.
* @param[in] eo_obs Obstacle object.
*
* @return @c true on success.
*
* @since 1.24
*
* @ingroup Efl_Canvas_Textblock
*/
EVAS_API EVAS_API_WEAK Eina_Bool efl_canvas_textblock_obstacle_add(Eo *obj, Efl_Canvas_Object *eo_obs);
#endif /* EFL_BETA_API_SUPPORT */
#ifdef EFL_BETA_API_SUPPORT
/**
* @brief Removes @c eo_obs from observation during text layout.
*
* @param[in] obj The object.
* @param[in] eo_obs Obstacle object.
*
* @return @c true on success.
*
* @since 1.24
*
* @ingroup Efl_Canvas_Textblock
*/
EVAS_API EVAS_API_WEAK Eina_Bool efl_canvas_textblock_obstacle_del(Eo *obj, Efl_Canvas_Object *eo_obs);
#endif /* EFL_BETA_API_SUPPORT */
#ifdef EFL_BETA_API_SUPPORT
/**
* @brief 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 different
* coordinates relative to the text block, you need to call this so it will
* consider this new state and will relayout the text.
*
* @param[in] obj The object.
*
* @since 1.24
*
* @ingroup Efl_Canvas_Textblock
*/
EVAS_API EVAS_API_WEAK void efl_canvas_textblock_obstacles_update(Eo *obj);
#endif /* EFL_BETA_API_SUPPORT */
/**
* @brief Requests to layout the text off the mainloop.
*
* Once layout is complete, the result is returned as @ref Eina_Rect, with the
* @c w and @c h fields set.
*
* This can be used to layout Textblock before it is required to layout
* internally in back thread, which can enhance application performance.
*
* @param[in] obj The object.
*
* @return Future for layout result.
*
* @since 1.24
*
* @ingroup Efl_Canvas_Textblock
*/
EVAS_API EVAS_API_WEAK Eina_Future *efl_canvas_textblock_async_layout(Eo *obj);
EVAS_API EVAS_API_WEAK extern const Efl_Event_Description _EFL_CANVAS_TEXTBLOCK_EVENT_CHANGED;
/** Called when canvas text changed
*
* @since 1.24
*
* @ingroup Efl_Canvas_Textblock
*/
#define EFL_CANVAS_TEXTBLOCK_EVENT_CHANGED (&(_EFL_CANVAS_TEXTBLOCK_EVENT_CHANGED))
EVAS_API EVAS_API_WEAK extern const Efl_Event_Description _EFL_CANVAS_TEXTBLOCK_EVENT_LAYOUT_FINISHED;
/** Called when the object has been layed out
*
* @since 1.24
*
* @ingroup Efl_Canvas_Textblock
*/
#define EFL_CANVAS_TEXTBLOCK_EVENT_LAYOUT_FINISHED (&(_EFL_CANVAS_TEXTBLOCK_EVENT_LAYOUT_FINISHED))
EVAS_API EVAS_API_WEAK extern const Efl_Event_Description _EFL_CANVAS_TEXTBLOCK_EVENT_STYLE_INSETS_CHANGED;
/** Called when the property @ref efl_canvas_textblock_style_insets_get
* changed.
*
* @since 1.24
*
* @ingroup Efl_Canvas_Textblock
*/
#define EFL_CANVAS_TEXTBLOCK_EVENT_STYLE_INSETS_CHANGED (&(_EFL_CANVAS_TEXTBLOCK_EVENT_STYLE_INSETS_CHANGED))
#endif