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