kimcinoo
/
efl
forked from enlightenment/efl
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

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
This commit is contained in:
Xavi Artigas 2020-01-09 18:11:59 +01:00
parent 83a2916043
commit 93c7e7dc8f
5 changed files with 140 additions and 117 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

82
src/lib/efl/interfaces/efl_text_font_properties.eo
View File

@ -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.]]
}
}
}

39
src/lib/efl/interfaces/efl_text_format.eo
View File

@ -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.]]
}
}
}

107
src/lib/efl/interfaces/efl_text_style.eo
View File

@ -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.]]
}
}
}

21
src/lib/elementary/efl_ui_textbox.eo
View File

@ -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 {

8
src/lib/evas/canvas/efl_canvas_textblock.eo
View File

@ -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.