/
VIRTUALKEYBOARD
305 lines (262 loc) · 15.2 KB
/
VIRTUALKEYBOARD
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
A Guide to the VirtualKeyBoard Screen
-------------------------------------
Written by IanSav - 18-Aug-2018
Updated by IanSav - 4-Sep-2018
Updated by IanSav - 12-Nov-2018
Updated by IanSav - 25-Mar-2019
Updated by IanSav - 8-Apr-2019
Updated by IanSav - 2-Jun-2019 *
This document explains the changes and updates to the VirtualKeyBoard of
Enigma2. The code is located in:
/usr/lib/enigma2/python/Screens/VirtualKeyBoard.py
The revised VirtualKeyBoard is dynamically created based on the data
defined in the "self.locales" data in the "__init__" method of the
"VirtualKeyBoard" class. To make creating new locales based on common
languages easier a number of base language definitions are provided.
(Currently English, French, German, Russian, Scandinavian and Spanish.)
The locales are based on the list at https://lh.2xlibre.net/locales/.
The maximum width of the keyboard has been set at 14 buttons. This
limitation is set by the skin allocation of space for the keyboard and then
confirmed in this code in the "virtualKeyBoardEntryComponent" method. If
the "keyList" data describes a keyboard less than 14 characters then that
keyboard will be centred in the 14 wide keyboard space. The button layouts
for each of the keyboards is based on the layouts at http://kbdlayout.info/.
Each element of the "keyList" data is a button displayed on the
VirtualKeyBoard. Certain button names are mapped to images that will be
used for that button. The current image button definitions are listed in
the "self.keyImages" dictionary in the "__init__" method of the
"VirtualKeyBoard" class. To make future updates easier all non English
characters are represented by their unicode numeric code
(https://en.wikipedia.org/wiki/List_of_Unicode_characters).
Any sequence of identical button definitions on any single row of a
"keyList" entry will be used to generate a single wide button on the
screen occupying all the defined positions.
New languages and locales can be added by adding an appropriate entry
into the "self.locales" dictionary. The primary or default keyboard
for the language should use the locale key as provided by Enigma2.
Alternates can be provided with other keys to allow selection of the
alternate by users.
If a keyboard is fundamentally similar to an existing keyboard then the
existing keyboard can be used as a template for the new keyboard. The
method specified in the dictionary should duplicate the existing definition
and then proceed to change the keyboard cells as required. If the new
keyboard is substantially different then a new keyboard keymap should be
defined.
This revision also allows the four colour buttons to be assigned to any
keyboard key by nominating the key text in the "self.keyHiglights"
dictionary in the "__init__" method of the "VirtualKeyBoard" class.
This change will allow for colour button text to be localised rather than
depending on a graphical button to achieve the coloured border. Note that
the ENTER and SHIFT button graphics should default to the GREEN and BLUE
borders, respectively, but can now be changed.
This revision also adds the ability to define the foreground colours of the
characters on the VirtualKeyBoard. The colour selections for the unshifted
and three predefined shift levels are defined as white, white, cyan and
magenta respectively. These colours match the default SHIFT button
images. These colours can be overridden by a skin author via the
"VirtualKeyBoardShiftColors" skin parameter. (The number of shift levels
can be increased if required.)
The updated VirtualKeyBoard has a new and optional calling parameter
"style=". This calling parameter can be used to adjust the text of the
GREEN button and the optional text on the keypad button for the "Enter"
key. The values that can be used are:
VKB_DONE_ICON
VKB_ENTER_ICON
VKB_OK_ICON
VKB_SAVE_ICON
VKB_SEARCH_ICON
VKB_DONE_TEXT
VKB_ENTER_TEXT
VKB_OK_TEXT
VKB_SAVE_TEXT
VKB_SEARCH_TEXT
The first five options change the GREEN button text to "Done", "Enter",
"OK", "Save" and "Search" respectively but keep the keypad grid image of
the "ENTER" button. The next five options change both the GREEN button
and the text used on the keypad grid.
This revision includes two optional new parameters to give skin designers
more control of the VirtualKeyBoard display:
The "VirtualKeyBoardAlignment" parameter takes two comma separated
decimal values. The first value specifies the horizontal alignment of the
data in each of the keyboard keymap cells. The second value specifies the
vertical alignment of the data in each of the keyboard keymap cells.
The horizontal "VirtualKeyBoardAlignment" values are:
0 - Auto - Default (Auto=Left on left button, Centre on middle
buttons, Right on right button).
1 - Left
2 - Centre
3 - Right
The vertical "VirtualKeyBoardAlignment" values are:
0 - Auto - Default (Auto=Centre)
1 - Top
2 - Centre
3 - Bottom
The "VirtualKeyBoardPadding" parameter takes two comma separated
decimal values. The first value specifies the horizontal (left and right)
padding of the data in each of the keyboard keymap cells. The second
value specifies the vertical (top and bottom) padding of the data in each
of the keyboard keymap cells. This parameter controls how close the content
of a cell can come to the edges of that cell. The default is 4 pixels for
720 skins and 7 pixels for 1080 skins. These values allows the content of
the cell to stay clear of the default highlighting and current cell overlay
indicators.
To further assist with changing the skin of the VirtualKeyBoard the
various colour highlights and button images no longer contain any part of
the VirtualKeyBoard background image. They are now standalone images on
a transparent background. These images are now placed on top of the
background cell image rather than replacing it. These images now blend
in with *any* selected image chosen for the cell background. For most
skinning changes to the cell background the skin designer now only needs
to replace the three component images that constitute the cell background.
(NOTE: If a light background is desired then many of the images will need
to be changed to a contrasting colour so as to be seen.)
This revision also improves font size options. The previous
"VirtualKeyBoard" skin font parameter is retained but a new scaling option
has been added to the code such that short text messages can be now assigned
to keyboard buttons. For example, text like ".com", ".org" etc to make
Internet address entry easier. To ensure that longer key text can fit in
the screen space available any text longer than one character will be drawn
at 56% of the "VirtualKeyBoard" skin font parameter assigned font size.
As mentioned in the previous paragraph buttons can be assigned short text
messages to ease user data entry. Please note that text will now be used
exactly as entered in all locales. If translation is required please ensure
that the text is enclosed in the the standard "_(" ")" tokens.
This revision also adds HELP button text to assist users with using the
updated VirtualKeyBoard interface.
* This update includes a change to colour button assignments. The Locales
selection list functionality has now been moved from the YELLOW button to
the TEXT button. A new feature has been added where pressing the YELLOW
button changes the shift level, like the BLUE button, but the shift is
temporary and only applies to the next button pressed on the virtual
keyboard. Once a button is selected the previous shift level is immediately
restored. (This change requires matching changes to the keymap.xml file.)
To clarify the functional differences the previous use of u"SHIFT" and
u"SHIFTICON" buttons have been renamed to u"CAPSLOCK" and u"CAPSLOCKICON"
to maintain the correlations with physical keyboards. The buttons u"SHIFT"
and "u"SHIFTICON" now associate with the temporary shift function.
If the VirtualKeyBoard interface is to be re-skinned then the following
"name=" screen widgets should be defined:
prompt - This widget displays the prompt text for the entry.
text - This widget displays the current text buffer.
list - This widget displays the keyboard grid.
locale - This widget displays the currently selected keyboard
language.
language - This widget displays the current language.
* The standard colour and action buttons "source=" screen widgets can also
be defined:
key_red - This widget displays the RED button exit text prompt.
key_green - This widget displays the GREEN button save text prompt.
key_yellow - This widget displays the YELLOW button shift prompt.
key_blue - This widget displays the BLUE button and the next
caps lock text prompt.
key_info - This widget triggers the INFO button.
key_help - This widget triggers the HELP button.
(See /doc/BUTTONGUIDE in the repository for more information.)
For example in a 1280 x 720 skin:
<fonts>
<font name="DejaVuSans" filename="DejaVuSans.ttf" scale="100" />
<alias name="VirtualKeyBoard" font="DejaVuSans" size="28" height="45" />
</fonts>
<parameters>
<parameter name="VirtualKeyBoardAlignment" value="0,0" />
<parameter name="VirtualKeyBoard" value="45,45" />
<parameter name="VirtualKeyBoardPadding" value="4,4" />
<parameter name="VirtualKeyBoardShiftColors" value="16777215,16777215,65535,16711935" />
</parameters>
<screen name="VirtualKeyBoard" title="Virtual Keyboard" position="center,center" size="660,375" zPosition="99">
<widget name="prompt" position="15,10" size="630,25" font="Regular;20" noWrap="1" transparent="1" />
<ePixmap pixmap="buttons/vkey_text.png" position="10,35" size="640,50" alphatest="blend" zPosition="-4" />
<widget name="text" position="15,35" size="630,46" font="Regular;40" halign="right" noWrap="1" transparent="1" />
<widget name="list" position="15,100" size="630,225" backgroundColor="#001c2c5c" foregroundColor="window-fg" selectionDisabled="1" transparent="1" />
<widget name="locale" position="15,340" size="570,25" font="Regular;20" transparent="1" />
<widget name="mode" position="585,340" size="60,25" font="Regular;20" halign="right" transparent="1" valign="center" />
<widget name="language" position="0,0" size="0,0" font="Regular;20" transparent="1" />
</screen>
WARNING: Due to limitations in the parameter parsing the shift
colours MUST be specified as decimal numbers for all firmware
versions earlier than 4-Sep-2018. For firmware builds later than
4-Sep-2018 the colours can be specified as decimal numbers, hex
numbers, Enigma2 "#" colour codes or colour names. For example,
the following parameters are equaly valid and effectively the same:
<parameter name="VirtualKeyBoardShiftColors" value="16777215,16777215,65535,16711935" />
<parameter name="VirtualKeyBoardShiftColors" value="0x00ffffff,0x00ffffff,0x0000ffff,0x00ff00ff" />
<parameter name="VirtualKeyBoardShiftColors" value="#00ffffff,#00ffffff,#0000ffff,#00ff00ff" />
<parameter name="VirtualKeyBoardShiftColors" value="White,White,Cyan,Magenta" />
(Assuming the colours "White", "Cyan" and "Magenta" are defined!)
IMPORTANT: Make sure that all the 720 "vkey_*" images are copied to
the "/usr/share/enigma2/<skin>/buttons/" directory where "<skin>" is
the name of the skin that you are updating.
For example in a 1920 x 1080 skin:
<fonts>
<font name="DejaVuSans" filename="DejaVuSans.ttf" scale="100" />
<alias name="VirtualKeyBoard" font="DejaVuSans" size="42" height="68" />
</fonts>
<parameters>
<parameter name="VirtualKeyBoardAlignment" value="0,0" />
<parameter name="VirtualKeyBoard" value="68,68" />
<parameter name="VirtualKeyBoardPadding" value="7,7" />
<parameter name="VirtualKeyBoardShiftColors" value="16777215,16777215,65535,16711935" />
</parameters>
<screen name="VirtualKeyBoard" title="Virtual Keyboard" position="center,center" size="980,495" zPosition="99">
<widget name="prompt" position="14,10" size="952,25" font="Regular;20" noWrap="1" transparent="1" />
<ePixmap pixmap="buttons/vkey_text.png" position="10,45" size="960,50" alphatest="blend" zPosition="-4" />
<widget name="text" position="14,48" size="952,46" font="Regular;40" halign="right" noWrap="1" transparent="1" />
<widget name="list" position="14,105" size="952,340" backgroundColor="#001c2c5c" foregroundColor="window-fg" selectionDisabled="1" transparent="1" />
<widget name="locale" position="14,460" size="800,25" font="Regular;20" transparent="1" />
<widget name="mode" position="892,460" size="60,25" font="Regular;20" halign="right" transparent="1" valign="center" />
<widget name="language" position="0,0" size="0,0" font="Regular;20" transparent="1" />
</screen>
WARNING: Due to limitations in the parameter parsing the shift
colours MUST be specified as decimal numbers for all firmware
versions earlier than 4-Sep-2018. For firmware builds later than
4-Sep-2018 the colours can be specified as decimal numbers, hex
numbers, Enigma2 "#" colour codes or colour names. For example,
the following parameters are equaly valid and effectively the same:
<parameter name="VirtualKeyBoardShiftColors" value="16777215,16777215,65535,16711935" />
<parameter name="VirtualKeyBoardShiftColors" value="0x00ffffff,0x00ffffff,0x0000ffff,0x00ff00ff" />
<parameter name="VirtualKeyBoardShiftColors" value="#00ffffff,#00ffffff,#0000ffff,#00ff00ff" />
<parameter name="VirtualKeyBoardShiftColors" value="White,White,Cyan,Magenta" />
(Assuming the colours "White", "Cyan" and "Magenta" are defined!)
IMPORTANT: Make sure that all the 1080 "vkey_*" images are copied to
the "/usr/share/enigma2/<skin>/buttons/" directory where "<skin>" is
the name of the skin that you are updating.
NOTE:
The most important changes for a skin is to ensure that the width of
the "list" object is wide enough to display the larger keyboard. The
width is calculated by multiplying number of buttons (14) by the
width of each button (in parameter "VirtualKeyBoard" and the actual
width of the button background or image. (720 skins 14 x 45 = 630,
1080 skins 14 x 68 = 952)
Also, the enhanced VirtualKeyBoard adds some new button images and
abandons others. Graphic buttons for plain text are deprecated as
the new code creates these on the fly while allowing for language
localisation.
Removing legacy VirtualKeyBoard support:
If support for the old VirtualKeyBoard code is not required for a
skin then the following items may be removed / deleted from the
skin:
From the <fonts> block in the skin remove:
<alias name="VirtualKeyboard" ... />
From the <parameters> block in the skin remove:
<parameter name="VirtualKeyboard" ... />
IMPORTANT: The lower case "b" in "board" is significant! The
"VirtualKeyboard" entries are used by the old code while
"VirtualKeyBoard" entries are used by the new code.
* From the buttons directory in the skin delete:
vkey_all.png
vkey_blue.png
vkey_clr.png
vkey_esc.png
vkey_green.png
vkey_ok.png
vkey_red.png
vkey_sel.png
vkey_shift_sel.png
vkey_yellow.png
Please do not delete any of these images if they are shared by other
skins that continue to support the older VirtualKeyBoard code.
NOTE: The image "vkey_bg.png" is no longer used by the new
VirtualKeyBoard but must not be removed as it is used by
"NTIVirtualKeyBoard.pyo"! When this tool is removed from the
base build the old image can be removed.
---END---