/
brailleInput.py
454 lines (414 loc) · 16.1 KB
/
brailleInput.py
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
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
# -*- coding: UTF-8 -*-
#brailleInput.py
#A part of NonVisual Desktop Access (NVDA)
#This file is covered by the GNU General Public License.
#See the file COPYING for more details.
#Copyright (C) 2012-2016 NV Access Limited, Rui Batista
import os.path
import time
import louis
import brailleTables
import braille
import config
from logHandler import log
import winUser
import inputCore
import speech
import keyboardHandler
import api
"""Framework for handling braille input from the user.
All braille input is represented by a {BrailleInputGesture}.
Normally, all that is required is to create and execute a L{BrailleInputGesture},
as there are built-in gesture bindings for braille input.
"""
#: Table to use if the input table configuration is invalid.
FALLBACK_TABLE = "en-us-comp8.ctb"
DOT7 = 1 << 6
DOT8 = 1 << 7
#: This bit flag must be added to all braille cells when using liblouis with dotsIO.
LOUIS_DOTS_IO_START = 0x8000
#: The start of the Unicode braille range.
#: @type: int
UNICODE_BRAILLE_START = 0x2800
#: The Unicode braille character to use when masking cells in protected fields.
#: @type: unicode
UNICODE_BRAILLE_PROTECTED = u"⣿" # All dots down
#: The singleton BrailleInputHandler instance.
#: @type: L{BrailleInputHandler}
handler = None
def initialize():
global handler
handler = BrailleInputHandler()
log.info("Braille input initialized")
def terminate():
global handler
handler = None
class BrailleInputHandler(object):
"""Handles braille input.
"""
def __init__(self):
# #6140: Migrate to new table names as smoothly as possible.
tableName = config.conf["braille"]["inputTable"]
newTableName = brailleTables.RENAMED_TABLES.get(tableName)
if newTableName:
tableName = config.conf["braille"]["inputTable"] = newTableName
try:
self._table = brailleTables.getTable(tableName)
except LookupError:
log.error("Invalid table: %s" % tableName)
self._table = brailleTables.getTable(FALLBACK_TABLE)
#: A buffer of entered braille cells so that state set by previous cells can be maintained;
#: e.g. capital and number signs.
self.bufferBraille = []
#: The text translated so far from the cells in L{bufferBraille}.
self.bufferText = u""
#: Indexes of cells which produced text.
#: For example, this includes letters and numbers, but not number signs,
#: since a number sign by itself doesn't produce text.
#: This is used when erasing cells to determine when to backspace an actual character.
self.cellsWithText = set()
#: The cells in L{bufferBraille} that have not yet been translated
#: or were translated but did not produce any text.
#: This is used to show these cells to the user while they're entering braille.
#: This is a string of Unicode braille.
#: @type: unicode
self.untranslatedBraille = ""
#: The position in L{brailleBuffer} where untranslated braille begins.
self.untranslatedStart = 0
#: The user's cursor position within the untranslated braille.
#: This enables the user to move within the untranslated braille.
self.untranslatedCursorPos = 0
#: The time at which uncontracted characters were sent to the system.
self._uncontSentTime = None
config.configProfileSwitched.register(self.handleConfigProfileSwitch)
@property
def table(self):
"""The translation table to use for braille input.
@rtype: L{brailleTables.BrailleTable}
"""
return self._table
@table.setter
def table(self, table):
self._table = table
config.conf["braille"]["inputTable"] = table.fileName
def _translate(self, endWord):
"""Translate buffered braille up to the cursor.
Any text produced is sent to the system.
@param endWord: C{True} if this is the end of a word, C{False} otherwise.
@type endWord: bool
@return: C{True} if translation produced text, C{False} if not.
@rtype: bool
"""
assert not self._table.contracted or endWord, "Must only translate contracted at end of word"
if self._table.contracted:
# self.bufferText has been used by _reportContractedCell, so clear it.
self.bufferText = u""
oldTextLen = len(self.bufferText)
pos = self.untranslatedStart + self.untranslatedCursorPos
data = u"".join([unichr(cell | LOUIS_DOTS_IO_START) for cell in self.bufferBraille[:pos]])
self.bufferText = louis.backTranslate(
[os.path.join(brailleTables.TABLES_DIR, self._table.fileName),
"braille-patterns.cti"],
data, mode=louis.dotsIO | louis.noUndefinedDots)[0]
newText = self.bufferText[oldTextLen:]
if newText:
# New text was generated by the cells just entered.
if self._table.contracted:
# For contracted braille, an entire word is sent at once.
# Don't speak characters as this is sent.
speech._suppressSpeakTypedCharacters(len(newText))
else:
self._uncontSentTime = time.time()
self.untranslatedStart = pos
self.untranslatedCursorPos = 0
self.sendChars(newText)
if endWord:
# We only need to buffer one word.
# Clear the previous word (anything before the cursor) from the buffer.
del self.bufferBraille[:pos]
self.bufferText = u""
self.cellsWithText.clear()
self.untranslatedStart = 0
self.untranslatedCursorPos = 0
if newText or endWord:
self._updateUntranslated()
return True
return False
def _translateForReportContractedCell(self, pos):
"""Translate text for current input as required by L{_reportContractedCell}.
@return: The previous translated text.
@rtype: unicode
"""
cells = self.bufferBraille[:pos + 1]
data = u"".join([unichr(cell | LOUIS_DOTS_IO_START) for cell in cells])
oldText = self.bufferText
text = louis.backTranslate(
[os.path.join(brailleTables.TABLES_DIR, self._table.fileName),
"braille-patterns.cti"],
data, mode=louis.dotsIO | louis.noUndefinedDots | louis.partialTrans)[0]
self.bufferText = text
return oldText
def _reportContractedCell(self, pos):
"""Report a guess about the character(s) produced by a cell of contracted braille.
It's not possible to report the exact characters because later cells might change text produced by earlier cells.
However, it's helpful for the user to have a rough idea.
For example, in English contracted braille, "alw" is the contraction for "always".
As the user types "alw", the characters a, l, w will be spoken.
@return: C{True} if a guess was reported, C{False} if not (e.g. a number sign).
@rtype: bool
"""
oldText = self._translateForReportContractedCell(pos)
oldTextLen = len(oldText)
if oldText != self.bufferText[:oldTextLen]:
# This cell caused the text before it to change, so we can't make a useful guess.
return False
newText = self.bufferText[oldTextLen:]
if newText:
# New text was generated by the cells just entered.
# Speak them as separate characters.
speech.speakMessage(" ".join(newText))
return True
return False
def _reportUntranslated(self, pos):
"""Report a braille cell which hasn't yet been translated into text.
"""
speakTyped = config.conf["keyboard"]["speakTypedCharacters"]
protected = api.isTypingProtected()
if speakTyped:
if protected:
speech.speakSpelling(speech.PROTECTED_CHAR)
elif not self._table.contracted or not self._reportContractedCell(pos):
dots = self.bufferBraille[pos]
speakDots(dots)
if self._table.contracted and (not speakTyped or protected):
# Even if we're not speaking contracted cells, we might need to start doing so midword.
# For example, the user might have speak typed characters disabled, but enable it midword.
# Update state needed to report contracted cells.
self._translateForReportContractedCell(pos)
self._updateUntranslated()
self.updateDisplay()
def input(self, dots):
"""Handle one cell of braille input.
"""
# Insert the newly entered cell into the buffer at the cursor position.
pos = self.untranslatedStart + self.untranslatedCursorPos
self.bufferBraille.insert(pos, dots)
self.untranslatedCursorPos += 1
# Space ends the word.
endWord = dots == 0
# For uncontracted braille, translate the buffer for each cell added.
# Any new characters produced are then sent immediately.
# For contracted braille, translate the buffer only when a word is ended (i.e. a space is typed).
# This is because later cells can change characters produced by previous cells.
# For example, in English grade 2, "tg" produces just "tg",
# but "tgr" produces "together".
if not self._table.contracted or endWord:
if self._translate(endWord):
if not endWord:
self.cellsWithText.add(pos)
else:
# This cell didn't produce any text; e.g. number sign.
self._reportUntranslated(pos)
else:
self._reportUntranslated(pos)
def enter(self):
"""Translates any braille input and presses the enter key.
"""
self._translate(True)
inputCore.manager.emulateGesture(keyboardHandler.KeyboardInputGesture.fromName("enter"))
def translate(self):
"""Translates any braille input without inserting a space or new line.
"""
self._translate(True)
def _updateUntranslated(self):
"""Update the untranslated braille to be shown to the user.
If the display will not otherwise be updated, L{updatedisplay} should be called after this.
"""
if api.isTypingProtected():
self.untranslatedBraille = UNICODE_BRAILLE_PROTECTED * (len(self.bufferBraille) - self.untranslatedStart)
else:
self.untranslatedBraille = "".join([unichr(UNICODE_BRAILLE_START + dots) for dots in self.bufferBraille[self.untranslatedStart:]])
def updateDisplay(self):
"""Update the braille display to reflect untranslated input.
"""
region = braille.handler.mainBuffer.regions[-1] if braille.handler.mainBuffer.regions else None
if isinstance(region, braille.TextInfoRegion):
braille.handler._doCursorMove(region)
def eraseLastCell(self):
# Get the index of the cell being erased.
index = self.untranslatedStart + self.untranslatedCursorPos - 1
if index < 0:
# Erasing before the start of the buffer.
self._uncontSentTime = time.time()
inputCore.manager.emulateGesture(keyboardHandler.KeyboardInputGesture.fromName("backspace"))
return
cell = self.bufferBraille.pop(index)
if index in self.cellsWithText:
# Erase a real character.
self._uncontSentTime = time.time()
inputCore.manager.emulateGesture(keyboardHandler.KeyboardInputGesture.fromName("backspace"))
char = self.bufferText[-1]
self.bufferText = self.bufferText[:-1]
region = braille.handler.mainBuffer.regions[-1] if braille.handler.mainBuffer.regions else None
if (not isinstance(region, braille.TextInfoRegion) or region.cursorPos is None
or region.rawText[region.cursorPos - 1] != char
):
# The character before the cursor isn't the character we expected to erase.
# The cursor must have moved between typing and erasing.
# Thus, the buffer is now invalid.
self.flushBuffer()
return
self.cellsWithText.remove(index)
self.untranslatedStart -= 1
self.untranslatedCursorPos = 0
# This might leave us with some untranslated braille.
# For example, in English grade 1, erasing the number 1 leaves us with a number sign.
for prevIndex in xrange(index - 1, -1, -1):
if prevIndex in self.cellsWithText:
# This cell produced text, so stop.
break
# This cell didn't produce text (e.g. number sign),
# so show this untranslated input to the user.
self.untranslatedStart = prevIndex
self.untranslatedCursorPos += 1
if self.untranslatedCursorPos > 0:
self._updateUntranslated()
self.updateDisplay()
else:
# This cell didn't produce text.
if self._table.contracted:
# Update state needed to report contracted cells.
self._translateForReportContractedCell(index)
speakDots(cell)
self.untranslatedCursorPos -= 1
self._updateUntranslated()
self.updateDisplay()
def flushBuffer(self):
self.bufferBraille = []
self.bufferText = u""
self.cellsWithText.clear()
self.untranslatedBraille = ""
self.untranslatedStart = 0
self.untranslatedCursorPos = 0
def sendChars(self, chars):
inputs = []
for ch in chars:
for direction in (0,winUser.KEYEVENTF_KEYUP):
input = winUser.Input()
input.type = winUser.INPUT_KEYBOARD
input.ii.ki = winUser.KeyBdInput()
input.ii.ki.wScan = ord(ch)
input.ii.ki.dwFlags = winUser.KEYEVENTF_UNICODE|direction
inputs.append(input)
winUser.SendInput(inputs)
def handleGainFocus(self, obj):
# Clear all state when the focus changes.
self.flushBuffer()
def handleCaretMove(self, obj):
if not self.bufferBraille:
# No pending braille input, so nothing to do.
return
if self._uncontSentTime:
# Uncontracted braille recently sent characters to the system.
# This might cause a caret move, but we don't want to clear state
# due to our own text entry.
# If the caret move occurred within a short time, we assume it was caused by us.
if time.time() - self._uncontSentTime <= 0.3:
# This was caused by us. Ignore it.
return
self._uncontSentTime = None
# Braille input is incomplete, but the cursor has been moved.
# Clear all state.
self.flushBuffer()
def handleConfigProfileSwitch(self):
table = config.conf["braille"]["inputTable"]
if table != self._table.fileName:
self._table = brailleTables.getTable(table)
def formatDotNumbers(dots):
out = []
for dot in xrange(8):
if dots & (1 << dot):
out.append(str(dot + 1))
return " ".join(out)
def speakDots(dots):
# Translators: Used when reporting braille dots to the user.
speech.speakMessage(_("dot") + " " + formatDotNumbers(dots))
class BrailleInputGesture(inputCore.InputGesture):
"""Input (dots and/or space bar) from a braille keyboard.
This could either be as part of a braille display or a stand-alone unit.
L{dots} and L{space} should be set appropriately.
"""
#: Bitmask of pressed dots.
#: @type: int
dots = 0
#: Whether the space bar is pressed.
#: @type: bool
space = False
def _makeDotsId(self):
items = ["dot%d" % (i+1) for i in xrange(8) if self.dots & (1 << i)]
if self.space:
items.append("space")
return "bk:" + "+".join(items)
#: The generic gesture identifier for space plus any dots.
#: This could be used to bind many braille commands to a single script.
GENERIC_ID_SPACE_DOTS = inputCore.normalizeGestureIdentifier("bk:space+dots")
#: The generic gesture identifier for any dots.
#: This is used to bind entry of braille text to a single script.
GENERIC_ID_DOTS = inputCore.normalizeGestureIdentifier("bk:dots")
def _get_identifiers(self):
if self.space and self.dots:
return (self._makeDotsId(), self.GENERIC_ID_SPACE_DOTS)
elif self.dots in (DOT7, DOT8, DOT7 | DOT8):
# Allow bindings to dots 7 and/or 8 by themselves.
return (self._makeDotsId(), self.GENERIC_ID_DOTS)
elif self.dots or self.space:
return (self.GENERIC_ID_DOTS,)
else:
return ()
@classmethod
def _makeDisplayText(cls, dots, space):
if space and dots:
# Translators: Reported when braille space is pressed with dots in input help mode.
out = _("space with dot")
elif dots:
# Translators: Reported when braille dots are pressed in input help mode.
out = _("dot")
elif space:
# Translators: Reported when braille space is pressed in input help mode.
out = _("space")
if dots:
out += " " + formatDotNumbers(dots)
return out
def _get_displayName(self):
if not self.dots and not self.space:
return None
return self._makeDisplayText(self.dots, self.space)
@classmethod
def getDisplayTextForIdentifier(cls, identifier):
# Translators: Used when describing keys on a braille keyboard.
source = _("braille keyboard")
if identifier == cls.GENERIC_ID_SPACE_DOTS:
# Translators: Used to describe the press of space
# along with any dots on a braille keyboard.
return (source, _("space with any dots"))
if identifier == cls.GENERIC_ID_DOTS:
# Translators: Used to describe the press of any dots
# on a braille keyboard.
return (source, _("any dots"))
# Example identifier: bk:space+dot1+dot2
# Strip the bk: prefix.
partsStr = identifier.split(":", 1)[1]
parts = partsStr.split("+")
dots = 0
space = False
for part in parts:
if part == "space":
space = True
else:
# Example part: "dot1"
# Get the dot number and make it 0 based instead of 1 based.
dot = int(part[3]) - 1
# Update the dots bitmask.
dots += 1 << dot
return (source, cls._makeDisplayText(dots, space))
inputCore.registerGestureSource("bk", BrailleInputGesture)