1Prima::Bidi(3) User Contributed Perl Documentation Prima::Bidi(3)
2
6 Prima::Bidi - helper routines for bi-directional text input and output
7
9 use Prima::Bidi qw(:enable is_bidi);
10 say Prima::Bidi::visual( $bidi_text ) if is_bidi($bidi_text);
11 or same, for classes
13 use Prima::Bidi qw(:methods);
15 say $self->bidi_visual( $bidi_text ) if $self-> is_bidi($bidi_text);
16
18 The API follows closely Text::Bidi api, with view to serve as a loose
19 set of helper routines for input and output in Prima widgets. It also
20 makes use of installations without "Text::Bidi" safe. Exports set of
21 "bidi_XXX" names, available as method calls.
22 is_bidi $TEXT
24 Returns boolean flags whether the text contains any bidirectional
25 characters.
26 bidi_map $TEXT, ...
28 Shortcut for "Text::Bidi::Paragraph->new($TEXT, ...)->map".
29 Returns a set of integer indices, showing placement of where in
31 original bidi text a corresponding character can be found, i.e.
32 $map[0] contains the index of the character to be displayed
33 leftmost, etc.
34 This function could be useful f.ex. for translating screen position
36 to text position.
37 See "map" in Text::Bidi::Paragraph for more.
39 bidi_paragraph $TEXT, $RTL, $FLAGS
41 Returns a "Text::Bidi::Paragraph(dir =" $RTL)> object together with
42 result of call to "visual($FLAGS)".
43 bidi_revmap $MAP
45 Returns an inverse array of result of "map", i.e. showing where, if
46 any, a bidi character is to be displayed in visual text, so that
47 f.ex. $revmap[0] contains visual position of character #0, etc.
48 bidi_edit_delete $PARAGRAPH, $VISUAL_POSITION, $DELETE
50 Handles bidirectional deletion, emulating user hitting a backspace
51 ("$DELETE = 0") or delete ("$DELETE = 1") key at $VISUAL_POSITION
52 in text represented by a "Text::Bidi::Paragraph" object.
53 Returns three integers, showing 1) how many characters are to be
55 deleted, 2) at which text offset, and 3) how many characters to the
56 right the cursor has to move.
57 $PARAGRAPH can be a non-object, in which case the text is
59 considered to be non-bidi.
60 bidi_edit_insert $PARAGRAPH, $VISUAL_POSITION, $NEW_STRING
62 Handles typing of bidirectional text $NEW_STRING, inside an
63 existing $PARAGRAPH represented by a "Text::Bidi::Paragraph"
64 object, where cursor is a $VISUAL_POSITION.
65 $PARAGRAPH can be a non-object, in which case the text is
67 considered to be non-bidi.
68 bidi_map_find $MAP, $INDEX
70 Searches thround $MAP (returned by "bidi_map") for integer $INDEX,
71 returns its position if found.
72 bidi_selection_chunks $MAP, $START, $END, $OFFSET = 0
74 Calculates a set of chunks of texts, that, given a text selection
75 from positions $START to $END, represent each either a set of
76 selected and non-selected visual characters. The text is
77 represented by a result of "bidi_map".
78 Returns array of integers, RLE-encoding the chunks, where the first
80 integer signifies number of non-selected characters to display, the
81 second - number of selected characters, the third the non-selected
82 again, etc. If the first character belongs to the selected chunk,
83 the first integer in the result is set to 0.
84 $MAP can be also an integer length of text (i.e. shortcut for an
86 identity array (0,1,2,3...) in which case the text is considered to
87 be non-bidi, and selection result will contain max 3 chunks).
88 $OFFSET may be greater that 0, but less than $START, if that
90 information is not needed.
91 Example: consider embedded number in a bidi text. For the sake of
93 clarity I'll use latin characters here. For example, we have a text
94 scalar containing these characters:
95 ABC123
97 where ABC is right-to-left text, and which, when rendered on
99 screen, should be displayed as
100 123CBA
102 (and $MAP will be (3,4,5,2,1,0) ).
104 Next, the user clicks the mouse between A and B (in text offset 1),
106 drags the mouse then to the left, and finally stops between
107 characters 2 and 3 (text offset 4). The resulting selection then
108 should not be, as one might naively expect, this:
109 123CBA
111 __^^^_
112 but this instead:
114 123CBA
116 ^^_^^_
117 because the next character after C is 1, and the range of the
119 selected sub-text is from characters 1 to 4.
120 In this case, the result of call to "bidi_selection_chunks( $MAP,
122 1, 4 )" will be "0,2,1,2,1" .
123 bidi_selection_diff $OLD, $NEW
125 Given set of two chunk lists, in format as returned by
126 "bidi_selection_chunks", calculates the list of chunks affected by
127 the selection change. Can be used for efficient repaints when the
128 user interactively changes text selection, to redraw only the
129 changed regions.
130 bidi_selection_map $TEXT
132 Same as "bidi_map", except when $TEXT is not bidi, returns just the
133 length of it. Such format can be used to pass the result further to
134 "bidi_selection_chunks" efficiently where operations are performed
135 on a non-bidi text.
136 bidi_selection_walk $CHUNKS, $FROM, $TO = length, $SUB
138 Walks the selection chunks array, returned by
139 "bidi_selection_chunks", between $FROM and $TO visual positions,
140 and for each chunk calls the provided "$SUB->($offset, $length,
141 $selected)", where each call contains 2 integers to chunk offset
142 and length, and a boolean flag whether the chunk is selected or
143 not.
144 Can be also used on a result of "bidi_selection_walk", in which
146 case $selected flag is irrelevant.
147 bidi_visual $TEXT, $RTL, $FLAGS
149 Same as "bidi_paragraph" but returns only the rendered text,
150 omitting the paragraph object.
151
153 Dmitry Karasik, <dmitry@karasik.eu.org>.
154
156 examples/bidi.pl, Text::Bidi
157perl v5.28.0 2017-02-28 Prima::Bidi(3)