From 93c7e7dc8f2ad5efa7617e25b8f51346e67778ce Mon Sep 17 00:00:00 2001 From: Xavi Artigas Date: Thu, 9 Jan 2020 18:11:59 +0100 Subject: [PATCH] docs: Improvements to Text API documentation Ref T7855 Ref T7934 Ref T7935 Ref T7936 Ref T7937 Ref T7938 Ref T7941 Ref T7942 Ref T7943 Ref T7944 Ref T7945 --- .../interfaces/efl_text_font_properties.eo | 82 +++++++------- src/lib/efl/interfaces/efl_text_format.eo | 39 ++++--- src/lib/efl/interfaces/efl_text_style.eo | 107 ++++++++++-------- src/lib/elementary/efl_ui_textbox.eo | 21 ++-- src/lib/evas/canvas/efl_canvas_textblock.eo | 8 +- 5 files changed, 140 insertions(+), 117 deletions(-) diff --git a/src/lib/efl/interfaces/efl_text_font_properties.eo b/src/lib/efl/interfaces/efl_text_font_properties.eo index 160b182803..71d8e3d5d9 100644 --- a/src/lib/efl/interfaces/efl_text_font_properties.eo +++ b/src/lib/efl/interfaces/efl_text_font_properties.eo @@ -1,50 +1,54 @@ import efl_gfx_types; enum @beta Efl.Text_Font_Weight { - [[Type of font weight.]] - normal, [[Normal font weight.]] - thin, [[Thin font weight.]] - ultralight, [[Ultralight font weight.]] - extralight, [[Extralight font weight.]] - light, [[Light font weight.]] - book, [[Book font weight.]] - medium, [[Medium font weight.]] - semibold, [[Semibold font weight.]] - bold, [[Bold font weight.]] - ultrabold, [[Ultrabold font weight.]] - extrabold, [[Extrabold font weight.]] - black, [[Black font weight.]] - extrablack, [[Extrablack font weight.]] + [[The weight of a particular font is the thickness of the character outlines relative to their height. + The given numerical values follow the TrueType scale (from 100 to 900) and are approximate. + It is up to each font to provide all of them.]] + normal, [[Normal font weight (400).]] + thin, [[Thin font weight (100).]] + ultralight, [[Ultralight font weight (200).]] + extralight, [[Extralight font weight (200).]] + light, [[Light font weight (300).]] + book, [[Book font weight (350).]] + medium, [[Medium font weight (500).]] + semibold, [[Semibold font weight (600).]] + bold, [[Bold font weight (700).]] + ultrabold, [[Ultrabold font weight (800).]] + extrabold, [[Extrabold font weight (800).]] + black, [[Black font weight (900).]] + extrablack, [[Extrablack font weight (950).]] } enum @beta Efl.Text_Font_Width { - [[Type of font width.]] - normal, [[Normal font width.]] + [[Font width relative to its height. + It is up to each font to provide all these widths.]] + normal, [[Normal font width.]] ultracondensed, [[Ultracondensed font width.]] extracondensed, [[Extracondensed font width.]] - condensed, [[Condensed font width.]] - semicondensed, [[Semicondensed font width.]] - semiexpanded, [[Semiexpanded font width.]] - expanded, [[Expanded font width.]] - extraexpanded, [[Extraexpanded font width.]] - ultraexpanded, [[Ultraexpanded font width.]] + condensed, [[Condensed font width.]] + semicondensed, [[Semicondensed font width.]] + semiexpanded, [[Semiexpanded font width.]] + expanded, [[Expanded font width.]] + extraexpanded, [[Extraexpanded font width.]] + ultraexpanded, [[Ultraexpanded font width.]] } enum @beta Efl.Text_Font_Slant { [[Type of font slant.]] - normal, [[Normal font slant.]] - oblique, [[Oblique font slant.]] - italic, [[Italic font slant.]] + normal, [[Normal font slant: Sets the text to the normal font (non-italicized).]] + oblique, [[Oblique font slant: Sets the text to use a simulated version of an italic font, + created by algorithmically slanting the normal version.]] + italic, [[Italic font slant: Sets the text to use the italic version of the font if available. + If not available, it will simulate italics with oblique instead.]] } enum @beta Efl.Text_Font_Bitmap_Scalable { - [[Scalable of bitmap fonts. - ]] - none = 0, [[Disable scalable feature for bitmap fonts.]] - color = (1 << 0), [[Enable scalable feature for color bitmap fonts.]] + [[When are bitmap fonts allowed to be scaled.]] + none = 0, [[Disable scaling for bitmap fonts.]] + color = (1 << 0), [[Enable scaling for color bitmap fonts.]] } interface @beta Efl.Text_Font_Properties { - [[Font settings for text. + [[Properties related to font handling. ]] c_prefix: efl_text; methods { @@ -72,9 +76,9 @@ interface @beta Efl.Text_Font_Properties { } @property font_size { - [[The font size for a given text object. + [[The font size to use, in points. - This property controls the font size of a text object. + If the specified @.font_family does not provide this particular size, it will be scaled. ]] set {} get {} @@ -112,7 +116,7 @@ interface @beta Efl.Text_Font_Properties { } @property font_weight { - [[Type of weight of the displayed font + [[Type of weight (e.g. bold or normal) of the displayed font Default is @Efl.Text_Font_Weight.normal. ]] @@ -122,7 +126,7 @@ interface @beta Efl.Text_Font_Properties { } @property font_slant { - [[Type of slant of the displayed font. + [[Type of slant (e.g. italic or normal) of the displayed font. Default is @Efl.Text_Font_Slant.normal. ]] @@ -132,7 +136,7 @@ interface @beta Efl.Text_Font_Properties { } @property font_width { - [[Type of width of the displayed font. + [[Type of width (e.g. condensed, expanded or normal) of the displayed font. Default is @Efl.Text_Font_Width.normal. ]] @@ -155,14 +159,14 @@ interface @beta Efl.Text_Font_Properties { } @property font_bitmap_scalable { - [[The bitmap fonts have fixed size glyphs for several available sizes. - Basically, it is not scalable. But, it needs to be scalable for some use cases. - (e.g. colorful emoji fonts) + [[Bitmap fonts have fixed size glyphs for several available sizes. + Other sizes need to be algorithmically scaled, resulting in blurry glyphs. + This property controls whether scaling of non-provided sizes is allowed. Default is @Efl.Text_Font_Bitmap_Scalable.none. ]] values { - scalable: Efl.Text_Font_Bitmap_Scalable; [[Scalable.]] + scalable: Efl.Text_Font_Bitmap_Scalable; [[When should bitmap fonts be scaled.]] } } } diff --git a/src/lib/efl/interfaces/efl_text_format.eo b/src/lib/efl/interfaces/efl_text_format.eo index 96b724c84b..14d80a107c 100644 --- a/src/lib/efl/interfaces/efl_text_format.eo +++ b/src/lib/efl/interfaces/efl_text_format.eo @@ -1,5 +1,5 @@ enum @beta Efl.Text_Format_Wrap { - [[Wrapping policy of the text.]] + [[Wrapping policy for the text.]] none, [[No wrapping.]] char, [[Wrap at character boundaries.]] word, [[Wrap at word boundaries.]] @@ -9,7 +9,7 @@ enum @beta Efl.Text_Format_Wrap { } enum @beta Efl.Text_Format_Horizontal_Alignment_Auto_Type { - [[Auto-horizontal alignment setting for the text (Left-To-Right or Right-To-Left).]] + [[Automatic horizontal alignment setting for the text (Left-To-Right or Right-To-Left).]] none, [[No auto-alignment rule: Horizontal Alignment is decided by @Efl.Text_Format.text_horizontal_align]] auto, [[Respects LTR/RTL (bidirectional) characters found inside the text content.]] locale, [[Respects the system's language settings.]] @@ -33,36 +33,42 @@ interface @beta Efl.Text_Format { ]] values { - value: double; [[Ellipsis value.]] + value: double; [[Position of the ellipsis inside the text, from $[0.0] to $[1.0].]] } } @property wrap { - [[Wrapping policy of the text. Requires @.multiline to be $true.]] + [[Wrapping policy for the text. + + When text does not fit the widget in a single line, it can be automatically wrapped at + character or word boundaries, for example. + + Requires @.multiline to be $true. + ]] values { - wrap: Efl.Text_Format_Wrap; [[Wrap mode.]] + wrap: Efl.Text_Format_Wrap; [[Wrapping policy.]] } } @property multiline { [[Enables text to span multiple lines. - + When $false, new-line characters are ignored and no text wrapping occurs. ]] values { - enabled: bool; [[$true if multiline is enabled.]] + enabled: bool; [[$true if multiple lines should be rendered.]] } } @property text_horizontal_align_auto_type { [[Specifies when the text's horizontal alignment should be set automatically.]] values { - value: Efl.Text_Format_Horizontal_Alignment_Auto_Type; [[Alignment type.]] + value: Efl.Text_Format_Horizontal_Alignment_Auto_Type; [[Automatic horizontal alignment type.]] } } @property text_horizontal_align { - [[Horizontal alignment of text. $[0.0] means "left" + [[Manual horizontal alignment of text. $[0.0] means "left" and $[1.0] means "right". Setting this value also sets @.text_horizontal_align_auto_type to @Efl.Text_Format_Horizontal_Alignment_Auto_Type.none. @@ -75,7 +81,7 @@ interface @beta Efl.Text_Format { } @property text_vertical_align { - [[Vertical alignment of text.$[0.0] means "top" + [[Vertical alignment of text. $[0.0] means "top" and $[1.0] means "bottom"]] values { value: double; [[Alignment value between $[0.0] and $[1.0].]] @@ -105,16 +111,16 @@ interface @beta Efl.Text_Format { } @property tab_stops { - [[Size of the tab character.]] + [[Size (in pixels) of the tab character.]] values { - value: int; [[Size in pixels.]] + value: int; [[Size in pixels, greater than 1.]] } } @property password { [[Enabling this causes all characters to be replaced by @.replacement_char. - + This is useful for password input boxes. ]] values @@ -124,13 +130,12 @@ interface @beta Efl.Text_Format { } @property replacement_char { - [[The character used to replace characters that can't be displayed + [[The character used to replace characters that can't be displayed. - Currently only used to replace characters if @.password - is enabled. + Only used to replace characters if @.password is enabled. ]] values { - repch: string; [[Replacement character]] + repch: string; [[Replacement character.]] } } } diff --git a/src/lib/efl/interfaces/efl_text_style.eo b/src/lib/efl/interfaces/efl_text_style.eo index a975ebdc96..bb168fd5dd 100644 --- a/src/lib/efl/interfaces/efl_text_style.eo +++ b/src/lib/efl/interfaces/efl_text_style.eo @@ -1,70 +1,80 @@ enum @beta Efl.Text_Style_Background_Type { - [[Whether to add a background colored rectangle (background) to each line of text or not.]] - none = 0, [[Do not use background.]] - solid_color, [[Use solid color background.]] - + [[Type of background to use behind each line of text.]] + none = 0, [[Do not use background.]] + solid_color, [[Use a solid-color rectangle as background. + Requires @Efl.Text_Style.text_background_color.]] } enum @beta Efl.Text_Style_Strikethrough_Type { [[Whether to add a strike-through decoration to the displayed text or not.]] none = 0, [[Do not use strike-through.]] - single, [[Strikethrough with a single line.]] - + single, [[Strike-through with a single line. + Requires @Efl.Text_Style.text_strikethrough_color.]] } enum @beta Efl.Text_Style_Effect_Type { [[Effect to apply to the displayed text.]] - none = 0, [[No effect.]] - - // colored with shadow_color - shadow, [[Shadow effect.]] - far_shadow, [[Far shadow effect.]] - soft_shadow, [[Soft shadow effect.]] - far_soft_shadow, [[Far and soft shadow effect.]] - // colored with glow_color - glow, [[Glow effect.]] - // colored with outline_color - outline, [[Outline effect.]] - soft_outline, [[Soft outline effect.]] - // colored with outline_color + shadow_color - outline_shadow, [[Outline + shadow effect.]] - outline_soft_shadow, [[Outline + soft shadow effect.]] + none = 0, [[No effect.]] + shadow, [[Shadow effect. + Uses @Efl.Text_Style.text_shadow_color and @Efl.Text_Style.text_shadow_direction.]] + far_shadow, [[Far shadow effect. + Uses @Efl.Text_Style.text_shadow_color and @Efl.Text_Style.text_shadow_direction.]] + soft_shadow, [[Soft shadow effect. + Uses @Efl.Text_Style.text_shadow_color and @Efl.Text_Style.text_shadow_direction.]] + far_soft_shadow, [[Far and soft shadow effect. + Uses @Efl.Text_Style.text_shadow_color and @Efl.Text_Style.text_shadow_direction.]] + glow, [[Glow effect. + Uses @Efl.Text_Style.text_glow_color and @Efl.Text_Style.text_secondary_glow_color.]] + outline, [[Outline effect. + Uses @Efl.Text_Style.text_outline_color.]] + soft_outline, [[Soft outline effect. + Uses @Efl.Text_Style.text_outline_color.]] + outline_shadow, [[Outline + shadow effect. + Uses @Efl.Text_Style.text_shadow_color, @Efl.Text_Style.text_shadow_direction and + @Efl.Text_Style.text_outline_color.]] + outline_soft_shadow, [[Outline + soft shadow effect. + Uses @Efl.Text_Style.text_shadow_color, @Efl.Text_Style.text_shadow_direction and + @Efl.Text_Style.text_outline_color.]] } enum @beta Efl.Text_Style_Shadow_Direction { - [[Direction of the shadow.]] + [[Direction of the shadow effect.]] bottom_right = 0, [[Shadow towards bottom right.]] - bottom, [[Shadow towards bottom.]] - bottom_left, [[Shadow towards bottom left.]] - left, [[Shadow towards left.]] - top_left, [[Shadow towards top left.]] - top, [[Shadow towards top.]] - top_right, [[Shadow towards top right.]] - right, [[Shadow towards right.]] + bottom, [[Shadow towards bottom.]] + bottom_left, [[Shadow towards bottom left.]] + left, [[Shadow towards left.]] + top_left, [[Shadow towards top left.]] + top, [[Shadow towards top.]] + top_right, [[Shadow towards top right.]] + right, [[Shadow towards right.]] } enum @beta Efl.Text_Style_Underline_Type { - [[Type of underline of the displayed text.]] + [[Type of underline for the displayed text.]] none = 0, [[Text without underline.]] - single, [[Underlined with a single line.]] - double, [[Underlined with a double line.]] - dashed, [[Underlined with a dashed line.]] + single, [[Underlined with a single line. + Requires @Efl.Text_Style.text_underline_color.]] + double, [[Underlined with a double line. + Requires @Efl.Text_Style.text_underline_color and @Efl.Text_Style.text_secondary_underline_color.]] + dashed, [[Underlined with a dashed line. + Requires @Efl.Text_Style.text_underline_dashed_color, @Efl.Text_Style.text_underline_dashed_width and + @Efl.Text_Style.text_underline_dashed_gap.]] } interface @beta Efl.Text_Style { [[Decorations to add to the text. - Decorations can be coloring, effects, underlines, strike-through etc. + Decorations include text color, glow, outline, underline, strike-through and shadows. ]] c_prefix: efl_text; methods { @property text_color { - [[Color of text, excluding decorations like, shadow, outline or glow.]] + [[Color of text, excluding all other decorations. By default it is invisible.]] values { r: ubyte; [[Red component.]] @@ -75,7 +85,7 @@ interface @beta Efl.Text_Style { } @property text_background_type { - [[Enables rendering of a background rectangle behind each line of text.]] + [[Type of background to use behind each line of text.]] values { type: Efl.Text_Style_Background_Type; [[Background type.]] @@ -83,7 +93,7 @@ interface @beta Efl.Text_Style { } @property text_background_color { - [[Color of the background rectangle (backing) behind each line of text.]] + [[Color of the background behind each line of text. By default it is invisible.]] values { r: ubyte; [[Red component.]] @@ -94,7 +104,7 @@ interface @beta Efl.Text_Style { } @property text_underline_type { - [[Underline style for the text.]] + [[Type of underline to use for the text.]] values { type: Efl.Text_Style_Underline_Type; [[Underline type.]] @@ -103,7 +113,7 @@ interface @beta Efl.Text_Style { @property text_underline_color { - [[Color of normal underline style.]] + [[Color of the primary underline. By default it is invisible.]] values { r: ubyte; [[Red component.]] @@ -126,7 +136,7 @@ interface @beta Efl.Text_Style { @property text_underline_dashed_color { [[Color of the dashed underline. Only valid when @.text_underline_type is - @Efl.Text_Style_Underline_Type.dashed.]] + @Efl.Text_Style_Underline_Type.dashed. By default it is invisible.]] values { r: ubyte; [[Red component.]] @@ -159,7 +169,7 @@ interface @beta Efl.Text_Style { @property text_secondary_underline_color { [[Color of the secondary underline. Only valid when @.text_underline_type is - @Efl.Text_Style_Underline_Type.double.]] + @Efl.Text_Style_Underline_Type.double. By default it is invisible.]] values { r: ubyte; [[Red component.]] @@ -179,7 +189,7 @@ interface @beta Efl.Text_Style { @property text_strikethrough_color { - [[Color of the line striking through the text.]] + [[Color of the line striking through the text. By default it is invisible.]] values { r: ubyte; [[Red component.]] @@ -198,7 +208,7 @@ interface @beta Efl.Text_Style { } @property text_outline_color { - [[Color of the text outline.]] + [[Color of the text outline. By default it is invisible.]] values { r: ubyte; [[Red component.]] @@ -210,7 +220,7 @@ interface @beta Efl.Text_Style { @property text_shadow_direction { - [[Direction of shadow effect.]] + [[Direction of the shadow effect.]] values { type: Efl.Text_Style_Shadow_Direction; [[Shadow direction.]] @@ -219,7 +229,7 @@ interface @beta Efl.Text_Style { @property text_shadow_color { - [[Color of the shadow.]] + [[Color of the text shadow. By default it is invisible.]] values { r: ubyte; [[Red component.]] @@ -231,7 +241,7 @@ interface @beta Efl.Text_Style { @property text_glow_color { - [[Color of the glow decoration.]] + [[Color of the text glow. By default it is invisible.]] values { r: ubyte; [[Red component.]] @@ -245,7 +255,8 @@ interface @beta Efl.Text_Style { { [[Color of the secondary glow decoration. This is the color of the inner glow (where it touches the text) which - gradually fades into @.text_glow_color as it reaches the edge. + gradually fades into @.text_glow_color as it reaches the outer edge. + By default it is invisible. ]] values { @@ -264,7 +275,7 @@ interface @beta Efl.Text_Style { ]] values { - code: string; [[Filter code]] + code: string; [[Filter code.]] } } } diff --git a/src/lib/elementary/efl_ui_textbox.eo b/src/lib/elementary/efl_ui_textbox.eo index aa3a5dd5be..ce4ca09b24 100644 --- a/src/lib/elementary/efl_ui_textbox.eo +++ b/src/lib/elementary/efl_ui_textbox.eo @@ -6,7 +6,7 @@ class @beta Efl.Ui.Textbox extends Efl.Ui.Layout_Base implements Efl.Input.Click [[A flexible text widget which can be static (as a label) or editable by the user (as a text entry). It provides all sorts of editing facilities like automatic scrollbars, virtual keyboard, clipboard, configurable - context menus or autocapitalization, for example.]] + context menus or auto-capitalization, for example.]] methods { @property scrollable { [[Enable or disable scrolling in the widget. @@ -16,17 +16,19 @@ class @beta Efl.Ui.Textbox extends Efl.Ui.Layout_Base implements Efl.Input.Click set {} get {} values { - scroll: bool; [[$true to enable scrolling. Default is $false.]] + scroll: bool(false); [[$true to enable scrolling.]] } } @property context_menu_enabled { - [[This enables or disables the entry's contextual (longpress) menu.]] + [[This enables or disables the widget's contextual menu, typically + accessible through a long-press or a right-button click. + ]] set { } get { } values { - enabled: bool; [[If $true, the menu is enabled.]] + enabled: bool; [[$true to enable the contextual menu.]] } } @property cnp_mode { @@ -46,13 +48,14 @@ class @beta Efl.Ui.Textbox extends Efl.Ui.Layout_Base implements Efl.Input.Click } } @property selection_handles_enabled { - [[This enables or disables the entry's selection handlers.]] + [[This enables or disables the visual handles around selected text, + to allow simpler modification on touch screens.]] set { } get { } values { - enabled: bool; [[If $true, the selection handlers are enabled.]] + enabled: bool; [[$true to enable the selection handles.]] } } @@ -69,13 +72,13 @@ class @beta Efl.Ui.Textbox extends Efl.Ui.Layout_Base implements Efl.Input.Click return: Efl.Text.Cursor @move; [[Text cursor.]] } selection_copy { - [[This executes a "copy" action on the selected text in the entry.]] + [[This executes a "copy" action on the selected text in the widget.]] } selection_paste { - [[This executes a "paste" action in the entry.]] + [[This executes a "paste" action in the widget.]] } selection_cut { - [[This executes a "cut" action on the selected text in the entry.]] + [[This executes a "cut" action on the selected text in the widget.]] } } implements { diff --git a/src/lib/evas/canvas/efl_canvas_textblock.eo b/src/lib/evas/canvas/efl_canvas_textblock.eo index edc170ba81..8e9bee7dba 100644 --- a/src/lib/evas/canvas/efl_canvas_textblock.eo +++ b/src/lib/evas/canvas/efl_canvas_textblock.eo @@ -140,8 +140,8 @@ class @beta Efl.Canvas.Textblock extends Efl.Canvas.Object implements Efl.Text, Requires $underline. See @Efl.Text_Style.text_underline_color. - - $secondary_underline_color: Color code for the secondary text underline (See bottom for the complete list of - supported codes). Only valid when $[underline=double]. + - $secondary_underline_color: Color code for the secondary text underline (See bottom for the complete list + of supported codes). Only valid when $[underline=double]. Default value is $[rgba(0,0,0,0)] meaning that secondary underline will not be rendered. See @Efl.Text_Style.text_secondary_underline_color. @@ -165,8 +165,8 @@ class @beta Efl.Canvas.Textblock extends Efl.Canvas.Object implements Efl.Text, Default value is $[rgba(0,0,0,0)] meaning that no glow will be rendered. See @Efl.Text_Style.text_glow_color. - - $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 $style attribute includes a glow. + - $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 $style attribute includes a glow. Default value is $[rgba(0,0,0,0)] meaning that only the primary $glow_color will be used. See @Efl.Text_Style.text_secondary_glow_color.