1 '''
2 Defines L{AccessEngineAPI} for doing output.
3 Provides methods for doing output on any
4 L{AEOutput <AccessEngine.AEOutput.AEOutput>} device.
5
6 @var may_stop: Count of the number of calls to L{inhibitMayStop}. When
7 greater than zero, the next call to L{mayStop} will decrement the count.
8 When zero, L{mayStop} will send a stop to the output device.
9 @type may_stop: integer
10
11 @author: Peter Parente
12 @author: Pete Brunet
13 @author: Brett Clippingdale
14 @organization: IBM Corporation
15 @copyright: Copyright (c) 2005, 2007 IBM Corporation
16
17 @author: Frank Zenker
18 @author: Nicole Anacker
19 @author: Ramona Bunk
20 @author: Martina Weicht
21 @organization: IT Science Center Ruegen gGmbH, Germany
22 @copyright: Copyright (c) 2007, 2008 ITSC Ruegen
23
24 @license: I{The BSD License}
25 All rights reserved. This program and the accompanying materials are made
26 available under the terms of the BSD license which accompanies
27 this distribution, and is available at
28 U{http://www.opensource.org/licenses/bsd-license.php}
29 '''
30 import os
31 import AccessEngine
32
33 import View
34
35
36
37 from AccessEngine import AEConstants
38 from AccessEngine import AEOutput
39 from Tools.i18n import _
40 from AEApiError import *
41
42 may_stop = 0
43
45 '''
46 Sets the ideal device capabilities to be used to locate a device for all
47 output methods invoked from the caller's L{AEScript <AEScript.AEScript>}
48 module. The capabilities list should include strings naming
49 L{AEOutput <AccessEngine.AEOutput.AEOutput>} interfaces
50 ("audio" and/or "braille") at present.
51
52 @param script: The L{AEScript <AEScript.AEScript>} that call this method
53 @type script: L{AEScript <AEScript.AEScript>}
54 @param capabilities: Names of capabilities required on the device
55 @type capabilities: list of string
56 '''
57 script.setIdealOutput(*capabilities)
58 script._changeDefaultOutput()
59
61 '''
62 Gets the ideal device capabilities to locate a device to be used by all
63 output methods invoked from the caller's L{AEScript <AEScript.AEScript>} module.
64
65 @param script: The L{AEScript <AEScript.AEScript>} that call this method
66 @type script: L{AEScript <AEScript.AEScript>}
67 @return: Names of capabilities set as ideal for a default output device
68 @rtype: list of string
69 '''
70 return script.getIdealOutput()
71
73 '''
74 Gets an L{AEOutput <AccessEngine.AEOutput.AEOutput>} device from the
75 L{AEDeviceManager} given its name or its capabilities. The capabilities list
76 may include strings naming L{AEOutput <AccessEngine.AEOutput.AEOutput>}
77 interfaces ("audio" and/or "braille" at present).
78
79 If neither is specified, the first available output device in the
80 L{AEDeviceManager} is returned.
81
82 @param name: Class (UIE) name of the L{AEOutput <AccessEngine.AEOutput.AEOutput>}
83 device to get
84 @type name: string
85 @param capabilities: Names of capabilities required on the device
86 @type capabilities: list of string
87 @return: The named output device
88 @rtype: L{AEOutput <AccessEngine.AEOutput.AEOutput>}
89 @raise InvalidDeviceError: When the specified L{AEOutput
90 <AccessEngine.AEOutput.AEOutput>} device is not found
91 '''
92 if name is not None:
93 device = AccessEngine.AEDeviceManager.getOutputByName(name)
94 elif len(capabilities):
95 device = AccessEngine.AEDeviceManager.getOutputByCaps(capabilities)
96 else:
97 device = AccessEngine.AEDeviceManager.getFirstOutput()
98 if device is None:
99
100 raise InvalidDeviceError
101 return device
102
103 -def stopNow(script, cap, role, dev=None, sem=None, reset=True, **kwargs):
104 '''
105 Tells the referenced or matching output devices to interrupt current output
106 and clear buffered data.
107
108 @param script: The L{AEScript <AEScript.AEScript>} that calls this method
109 @type script: L{AEScript <AEScript.AEScript>}
110 @param cap: The target device's capability
111 @type cap: string
112 @param role: The target device's role
113 @type role: string
114 @param dev: The device to send the stop to; defaults to None for the
115 default output device
116 @type dev: L{AEOutput <AccessEngine.AEOutput.AEOutput>}
117 @param sem: The semantic information to stop; defaults to None for the
118 default semantic
119 @type sem: integer
120 @param reset: Reset the L{may_stop} count (C{True}) or leave it as-is when
121 sending the stop?
122 @type reset: boolean
123 @param kwargs: this method need EventLayer
124 @type kwargs: dictionary
125 @raise KeyError: when the kwargs don't contain the key 'layer'
126 '''
127 global may_stop
128
129
130 if cap == None:
131 devs = [ dev or script.getOutputDevices() ]
132 else:
133
134 devs = _chooseOutputDevices(cap, role, dev)
135 if reset:
136 may_stop = 0
137 if not AccessEngine.AETierManager.getState().Stopping:
138 return
139 layer = kwargs['layer']
140 for dev in devs:
141 AccessEngine.AEDeviceManager.sendStop(dev, sem, layer)
142
143 -def mayStop(script, cap, role, dev=None, sem=None, **kwargs):
144 '''
145 Stops the device if L{may_stop} is zero. When non-zero, decrements the
146 count.
147
148 @param script: The L{AEScript <AEScript.AEScript>} that calls this method
149 @type script: L{AEScript <AEScript.AEScript>}
150 @param cap: The target device's capability
151 @type cap: string
152 @param role: The target device's role
153 @type role: string
154 @param dev: The device to send the stop to; defaults to None for the
155 default output device
156 @type dev: L{AEOutput <AccessEngine.AEOutput.AEOutput>}
157 @param sem: The semantic information to stop; defaults to None for the
158 default semantic
159 @type sem: integer
160 @param kwargs: need EventLayer
161 @type kwargs: dictionary
162 @return: Was the stop processed (C{True}) or inhibited (C{False})?
163 @rtype: boolean
164 @raise KeyError: when the kwargs don't contain the key 'layer'
165 '''
166 global may_stop
167
168
169 if cap is None:
170 devs = [ dev or script.getOutputDevices() ]
171
172 else:
173 devs = _chooseOutputDevices(cap, role, dev)
174
175 if may_stop == 0:
176 for dev in devs:
177 stopNow(script, cap, role, dev, sem, **kwargs)
178 return True
179 else:
180 may_stop -= 1
181 if may_stop < 0:
182 may_stop = 0
183 return False
184
186 '''
187 Prevents the next call to L{mayStop} from stopping the device provided to
188 that call. Adds one to the L{may_stop} flag.
189 '''
190 global may_stop
191 may_stop += 1
192
193
195 '''
196 Tells the referenced output device to interrupt current output and clear
197 buffered data. Unlike L{stopNow}, this ignores the layer on which the
198 method was called and any semantic information. Everything on the device
199 is stopped, even when L{AETierManager.SUEState} stopping setting is False.
200
201 @param script: The L{AEScript <AEScript.AEScript>} that call this method
202 @type script: L{AEScript <AEScript.AEScript>}
203 @param dev: The device to send the stop to; defaults to None for the
204 default output device
205 @type dev: L{AEOutput <AccessEngine.AEOutput.AEOutput>}
206 '''
207 dev = dev or script.getOutputDevices()
208 AccessEngine.AEDeviceManager.sendStop(dev, None, None)
209
210 -def play(self, script, layer, filename, sem=None, dev=None, talk=True):
211 '''
212 Outputs the contents of a file. The device used to do the output gets to
213 decide what to do with the file based on its contents and the semantic tag
214 and event layer information given.
215
216 @note: MW: Wenn sich ein passender UseCase findet, muss hier geprueft werden,
217 ob hier auch das device anhand von cap und role ausgewaehlt werden muss.
218
219 @param script: The L{AEScript <AEScript.AEScript>} that call this method
220 @type script: L{AEScript <AEScript.AEScript>}
221 @param filename: Name of the file to be output
222 @type filename: string
223 @param sem: The semantic stream on which to send output; defaults to None
224 for the default semantic.
225 @type sem: integer
226 @param layer: Layer on which the event occurred
227 @type layer: integer
228 @param dev: The device to send the filename to; defaults to None for the
229 default output device
230 @type dev: L{AEOutput <AccessEngine.AEOutput.AEOutput>}
231 @param talk: Send a talk command immediately following the filename?
232 @type talk: boolean
233 '''
234 dev = dev or script.getOutputDevices()
235 if not os.path.exists(filename):
236 filename = os.path.join(script.getPath(), filename)
237 AccessEngine.AEDeviceManager.sendFilename(dev, filename, sem, layer)
238 if talk:
239 AccessEngine.AEDeviceManager.sendTalk(dev, sem, layer)
240
241 -def say(script, cap, role, text, layer, por=None, sem=None, dev=None, talk=True):
242 '''
243 Sends a string of text to a device that supports string display. If talk is
244 C{False}, the device should buffer the text until another method call occurs
245 which sends a Talk to the device.
246
247 @param script: The L{AEScript <AEScript.AEScript>} that call this method
248 @type script: L{AEScript <AEScript.AEScript>}
249 @param layer: Layer on which the event occured
250 @type layer: integer
251 @param text: Text to output
252 @type text: string
253 @param cap: The target device's capability
254 @type cap: string
255 @param role: The target device's role
256 @type role: string
257 @param por: The point of regard of the start of text, or None when the text
258 is not from the screen
259 @type por: L{AEPor <AEPor.AEPor>}
260 @param sem: The semantic stream on which to send output; defaults to None
261 for the default semantic.
262 @type sem: integer
263 @param dev: The device to send the text to; defaults to None for the
264 default output device
265 @type dev: L{AEOutput <AccessEngine.AEOutput.AEOutput>}
266 @param talk: Send a talk command immediately following the string?
267 @type talk: boolean
268 '''
269
270 if cap == None:
271 dev = dev or script.getOutputDevices()
272 AccessEngine.AEDeviceManager.sendString(dev, text, sem, layer, por)
273 if talk:
274 AccessEngine.AEDeviceManager.sendTalk(dev, sem, layer)
275 else:
276
277 devs = _chooseOutputDevices(cap, role, dev)
278 for dev in devs:
279 AccessEngine.AEDeviceManager.sendString(dev, text, sem, layer, por)
280 if talk:
281 AccessEngine.AEDeviceManager.sendTalk(dev, sem, layer)
282
284 '''
285 Convenience method to choose the appropriate output devices according to the
286 given capability and role.
287
288 @note: MW: With role == None, all output devices with the given capability
289 will receive the output (need for braille output, where both the device and
290 the monitor want to receive the output). Be careful when setting capability
291 to 'audio': Always provide a role. If not, it might get messy!
292
293 @param cap: The desired target device's capability
294 @type cap: string
295 @param role: The desired target device's role
296 @type role: string
297 @param dev: The device to send the text to; defaults to None for the
298 default output device
299 @type dev: L{AEOutput <AccessEngine.AEOutput.AEOutput>}
300 '''
301 out_devs = []
302
303
304 if cap == None:
305 out_devs.append(dev or def_out)
306
307 else:
308 devs = AccessEngine.AEDeviceManager.getOutputByCaps( [cap] )
309 for dev in devs:
310
311 if role == None:
312 out_devs.append(dev)
313
314 elif role == dev.getRole():
315 out_devs.append(dev)
316 return out_devs
317
318 -def send(script, layer, name, value, sem=None, dev=None, cap=None, role=None):
319 '''
320 Sends arbitrary data to a device. The device must recognize the name in
321 order to decide what to do with the value data.
322
323 This is a generic method which receives all content and commands to be
324 rendered and executed on a device. Standard name identifiers should be used
325 whenever possible. For instance, L{CMD_STOP <AEConstants.Output.CMD_STOP>} and
326 L{CMD_TALK <AEConstants.Output.CMD_TALK>}. However, device specific names and
327 values are certainly possible.
328
329 Only use this method if no other output method is suitable for your
330 purposes.
331
332 @note: MW: defaults to None for cap and role might not be a good choice
333 here. We should make sure we always values for them!
334
335 @param script: The L{AEScript <AEScript.AEScript>} that call this method
336 @type script: L{AEScript <AEScript.AEScript>}
337 @param layer: Layer on which the event occurred
338 @type layer: integer
339 @param name: Descriptor of the data value sent
340 @type name: object
341 @param value: Content value
342 @type value: object
343 @param sem: The semantic stream on which to send output; defaults to None
344 for the default semantic.
345 @type sem: integer
346 @param dev: Device that should receive the command
347 @type dev: L{AEOutput <AccessEngine.AEOutput.AEOutput>}
348 @param cap: The target device's capability; defaults to None
349 @type cap: string
350 @param role: The target device's role; defaults to None
351 @type role: string
352 @return: Return value specific to the given command
353 @rtype: object
354 '''
355 rv = None
356
357
358 if cap == None:
359 dev = dev or script.getOutputDevices()
360 rv = AccessEngine.AEDeviceManager.send(dev, name, value, sem, layer)
361 else:
362
363 devs = _chooseOutputDevices(cap, role, dev)
364 for dev in devs:
365 rv = AccessEngine.AEDeviceManager.send(dev, name, value, sem, layer)
366 return rv
367
368 -def getStyle(script, layer, dev=None, sem=None):
369 '''
370 Gets the L{AEOutput.Style <AccessEngine.AEOutput.AEOutput.Style>} object for
371 the given device, semantic tag, and event layer. This is a low level method
372 that allows direct access to
373 L{AEOutput.Style <AccessEngine.AEOutput.AEOutput.Style>} style objects.
374
375 @see: L{getStyleSetting}
376 @param script: The L{AEScript <AEScript.AEScript>} that call the method
377 @type script: L{AEScript <AEScript.AEScript>}
378 @param layer: Layer on which the event occured
379 @type layer: integer
380 @param dev: The device on which to get the value; defaults to None for the
381 default output device.
382 @type dev: L{AEOutput <AccessEngine.AEOutput.AEOutput>}
383 @param sem: The semantic on which to get the value.
384 @type sem: integer
385 @return: The style object or C{None} if one does not exist.
386 @rtype: L{AccessEngine.AEOutput.AEOutput.Style}
387 '''
388 dev = dev or script.getOutputDevices()
389 return AccessEngine.AEDeviceManager.getStyle(dev, sem, layer)
390
392 '''
393 Gets the L{AEOutput.Style <AccessEngine.AEOutput.AEOutput.Style>} object for
394 the given device, semantic tag, and event layer, then immediately fetches the
395 L{AEState.Setting} object with the given name. This is a low level method that
396 allows direct access to L{AEState.Setting}s on the style. It is permissible to
397 read/write the value property of settings fields and register for change
398 notifications.
399
400 @param script: The L{AEScript <AEScript.AEScript>} that call this method
401 @type script: L{AEScript <AEScript.AEScript>}
402 @param name: Name of the setting object to fetch
403 @type name: string
404 @param dev: The device on which this setting should be changed. Defaults to
405 the default output device established by L{setScriptIdealOutput}.
406 @type dev: L{AEOutput <AccessEngine.AEOutput.AEOutput>}
407 @param sem: The semantic on which to change the value. Defaults to None
408 meaning the default style
409 @type sem: integer
410 @param kwargs: this method need EventLayer
411 @type kwargs: dictionary
412 @return: The setting object
413 @rtype: L{AEState.Setting}
414 @raise InvalidStyleError: When the style or the setting name is not valid
415 @raise KeyError: when the kwargs don't contain the key 'layer'
416 '''
417 layer = kwargs['layer']
418 s = getStyle(script, layer, dev, sem)
419 try:
420 return s.getSettingObj(name)
421 except (TypeError, KeyError):
422 raise InvalidStyleError
423
424 -def getStyleVal(script, name, dev=None, sem=None, **kwargs):
425 '''
426 Gets the L{AEOutput <AccessEngine.AEOutput.AEOutput.Style>} object for the
427 given device, semantic tag, and event layer, then immediately fetches the
428 value of the L{AEState.Setting} object with the given name.
429
430 @param script: The L{AEScript <AEScript.AEScript>} that call this method
431 @type script: L{AEScript <AEScript.AEScript>}
432 @param name: Name of the setting value to fetch
433 @type name: string
434 @param dev: The device on which this setting should be changed. Defaults to
435 the default output device established by L{setScriptIdealOutput}.
436 @type dev: L{AEOutput <AccessEngine.AEOutput.AEOutput>}
437 @param sem: The semantic on which to change the value. Defaults to None
438 meaning the default style
439 @type sem: integer
440 @param kwargs: this method need EventLayer
441 @type kwargs: dictionary
442 @return: The setting value
443 @rtype: object
444 @raise InvalidStyleError: When the style or the setting name is not valid
445 @raise KeyError: when the kwargs don't contain the key 'layer'
446 '''
447 layer = kwargs['layer']
448 s = getStyle(script, layer, dev, sem)
449 try:
450 return s.getSettingVal(name)
451 except (TypeError, KeyError):
452 raise InvalidStyleError
453
454 -def setStyleVal(script, name, val, dev=None, sem=None, **kwargs):
455 '''
456 Gets the L{AEOutput.Style <AccessEngine.AEOutput.AEOutput.Style>} object for
457 the given device, semantic tag, and event layer, then immediately sets the
458 value of the L{AEState.Setting} object with the given name.
459
460 @param script: The L{AEScript <AEScript.AEScript>} that call this method
461 @type script: L{AEScript <AEScript.AEScript>}
462 @param name: Name of the setting value to fetch
463 @type name: string
464 @param val: The setting value
465 @type val: object
466 @param dev: The device on which this setting should be changed. Defaults to
467 the default output device established by L{setScriptIdealOutput}.
468 @type dev: L{AEOutput <AccessEngine.AEOutput.AEOutput>}
469 @param sem: The semantic on which to change the value. Defaults to None
470 meaning the default style
471 @type sem: integer
472 @param kwargs: this method need EventLayer
473 @type kwargs: dictionary
474 @raise InvalidStyleError: When the style or the setting name is not valid
475 @raise KeyError: when the kwargs don't contain the key 'layer'
476 '''
477 layer = kwargs['layer']
478 s = getStyle(script, layer, dev, sem)
479 try:
480 return s.setSettingVal(name, val)
481 except (TypeError, KeyError):
482 raise InvalidStyleError
483
484
485
486
487
488
489
490 -def sayTextAttrs(script, cap, role, text=None, template=u'%s', dev=None,
491 talk=True, **kwargs):
492 '''
493 Calls L{View.getAccAllTextAttrs <AccessEngineAPI.View.getAccAllTextAttrs>}
494 and outputs the result.
495
496 @param script: The L{AEScript <AEScript.AEScript>} that call this method
497 @type script: L{AEScript <AEScript.AEScript>}
498 @param cap: The target device's capability
499 @type cap: string
500 @param role: The target device's role
501 @type role: string
502 @param text: Manually provided text fetched from the L{AEPor <AEPor.AEPor>}
503 @type text: string
504 @param template: Template for text to be spoken. Defaults to %s indicating the
505 text or value retrieved from the L{AEPor <AEPor.AEPor>} is spoken by it
506 @type template: string
507 @param dev: The device to use for output. Defaults to the default output
508 device established by L{setScriptIdealOutput}.
509 @type dev: L{AEOutput <AccessEngine.AEOutput.AEOutput>}
510 @param talk: Send a L{CMD_TALK <AEConstants.Output.CMD_TALK>} immediately
511 after this string is sent?
512 @type talk: boolean
513 @param kwargs: this method need L{AEPor <AEPor.AEPor>}, EventLayer
514 @type kwargs: dictionary
515 @return: Was anything sent for output (C{True}) or was text None (C{False})?
516 @rtype: boolean
517 @raise KeyError: when the kwargs don't contain the keys 'layer' and 'por'
518 '''
519 por = kwargs['por']
520 layer = kwargs['layer']
521 if text is None:
522 attrs = View.getAccAllTextAttrs(por)
523 if not attrs:
524 return False
525 text = ', '.join(attrs.items())
526 if text is None:
527 return False
528 say(script, cap, role, template % text, layer, por,
529 AEConstants.SEM_TEXT_ATTR, dev, talk)
530 return True
531
532 -def sayWord(script, cap, role, text=None, template=u'%s', dev=None, talk=True,
533 **kwargs):
534 '''
535 Calls L{View.getWordText <AccessEngineAPI.View.getWordText>} and outputs the
536 result.
537
538 @param script: The L{AEScript <AEScript.AEScript>} that call this method
539 @type script: L{AEScript <AEScript.AEScript>}
540 @param text: Manually provided text fetched from the L{AEPor <AEPor.AEPor>}
541 @type text: string
542 @param template: Template for text to be spoken. Defaults to %s indicating
543 the text or value retrieved from the L{AEPor <AEPor.AEPor>} is spoken by it
544 @type template: string
545 @param dev: The device to use for output. Defaults to the default output
546 device established by L{setScriptIdealOutput}.
547 @type dev: L{AEOutput <AccessEngine.AEOutput.AEOutput>}
548 @param talk: Send a L{CMD_TALK <AEConstants.Output.CMD_TALK>} immediately
549 after this string is sent?
550 @type talk: boolean
551 @param kwargs: this method need L{AEPor <AEPor.AEPor>}, EventLayer
552 @type kwargs: dictionary
553 @return: Was anything sent for output (C{True}) or was text None (C{False})?
554 @rtype: boolean
555 @raise KeyError: when the kwargs don't contain the keys 'layer' and 'por'
556 '''
557 por = kwargs['por']
558 layer = kwargs['layer']
559 if text is None:
560 text = View.getWordText(por)
561 if text is None:
562 return False
563 say(script, cap, role, template % text, layer, por,
564 AEConstants.SEM_WORD, dev, talk)
565 return True
566
567 -def sayChar(script, cap, role, text=None, template=u'%s', dev=None, talk=True,
568 **kwargs):
569 '''
570 Calls L{View.getCharText <AccessEngineAPI.View.getCharText>} and outputs the
571 result.
572
573 @param script: The L{AEScript <AEScript.AEScript>} that call this method
574 @type script: L{AEScript <AEScript.AEScript>}
575 @param text: Manually provided text fetched from the L{AEPor <AEPor.AEPor>}
576 @type text: string
577 @param template: Template for text to be spoken. Defaults to %s indicating the
578 text or value retrieved from the L{AEPor <AEPor.AEPor>} is spoken by it
579 @type template: string
580 @param dev: The device to use for output. Defaults to the default output
581 device established by L{setScriptIdealOutput}.
582 @type dev: L{AEOutput <AccessEngine.AEOutput.AEOutput>}
583 @param talk: Send a L{CMD_TALK <AEConstants.Output.CMD_TALK>} immediately
584 after this string is sent?
585 @type talk: boolean
586 @param kwargs: this method need L{AEPor <AEPor.AEPor>}, EventLayer
587 @type kwargs: dictionary
588 @return: Was anything sent for output (C{True}) or was text None (C{False})?
589 @rtype: boolean
590 @raise KeyError: when the kwargs don't contain the keys 'layer' and 'por'
591 '''
592 por = kwargs['por']
593 layer = kwargs['layer']
594 if text is None:
595 text = View.getCharText(por)
596 if text is None:
597 return False
598 say(script, cap, role, template % text, layer, por,
599 AEConstants.SEM_CHAR, dev, talk)
600 return True
601
602 -def sayName(script, cap, role, text=None, template=u'%s', dev=None, talk=True,
603 **kwargs):
604 '''
605 Calls L{View.getAccName <AccessEngineAPI.View.getAccName>} and outputs the
606 result.
607
608 @param script: The L{AEScript <AEScript.AEScript>} that call this method
609 @type script: L{AEScript <AEScript.AEScript>}
610 @param text: Manually provided text fetched from the L{AEPor <AEPor.AEPor>}
611 @type text: string
612 @param template: Template for text to be spoken. Defaults to %s indicating the
613 text or value retrieved from the L{AEPor <AEPor.AEPor>} is spoken by it
614 @type template: string
615 @param dev: The device to use for output. Defaults to the default output
616 device established by L{setScriptIdealOutput}.
617 @type dev: L{AEOutput <AccessEngine.AEOutput.AEOutput>}
618 @param talk: Send a L{CMD_TALK <AEConstants.Output.CMD_TALK>} immediately
619 after this string is sent?
620 @type talk: boolean
621 @param kwargs: this method need L{AEPor <AEPor.AEPor>}, EventLayer
622 @type kwargs: dictionary
623 @return: Was anything sent for output (C{True}) or was text None (C{False})?
624 @rtype: boolean
625 @raise KeyError: when the kwargs don't contain the keys 'layer' and 'por'
626 '''
627 por = kwargs['por']
628 layer = kwargs['layer']
629 if text is None:
630 text = View.getAccName(por)
631 if text is None:
632 return False
633 say(script, cap, role, template % text, layer, por,
634 AEConstants.SEM_NAME, dev, talk)
635 return True
636
637 -def sayLabel(script, cap, role, text=None, template=u'%s', dev=None, talk=True,
638 **kwargs):
639 '''
640 Calls L{View.getAccLabel <AccessEngineAPI.View.getAccLabel>} and outputs the
641 result.
642
643 @param script: The L{AEScript <AEScript.AEScript>} that call this method
644 @type script: L{AEScript <AEScript.AEScript>}
645 @param text: Manually provided text fetched from the L{AEPor <AEPor.AEPor>}
646 @type text: string
647 @param template: Template for text to be spoken. Defaults to %s indicating
648 the text or value retrieved from the L{AEPor <AEPor.AEPor>} is spoken by it
649 @type template: string
650 @param dev: The device to use for output. Defaults to the default output
651 device established by L{setScriptIdealOutput}.
652 @type dev: L{AEOutput <AccessEngine.AEOutput.AEOutput>}
653 @param talk: Send a L{CMD_TALK <AEConstants.Output.CMD_TALK>} immediately
654 after this string is sent?
655 @type talk: boolean
656 @param kwargs: this method need L{AEPor <AEPor.AEPor>} and EventLayer
657 @type kwargs: dictionary
658 @return: Was anything sent for output (C{True}) or was text None (C{False})?
659 @rtype: boolean
660 @raise KeyError: when the kwargs don't contain the keys 'layer' and 'por'
661 '''
662 por = kwargs['por']
663 layer = kwargs['layer']
664 if text is None:
665 text = View.getAccLabel(por)
666 if text is None:
667 return False
668 say(script, cap, role, template % text, layer, por,
669 AEConstants.SEM_LABEL, dev, talk)
670 return True
671
672 -def sayItem(script, cap, role, text=None, template=u'%s', dev=None, talk=True,
673 **kwargs):
674 '''
675 Calls L{View.getItemText <AccessEngineAPI.View.getItemText>} and outputs the
676 result.
677
678 @param script: The L{AEScript <AEScript.AEScript>} that call this method
679 @type script: L{AEScript <AEScript.AEScript>}
680 @param text: Manually provided text fetched from the L{AEPor <AEPor.AEPor>}
681 @type text: string
682 @param template: Template for text to be spoken. Defaults to %s indicating
683 the text or value retrieved from the L{AEPor <AEPor.AEPor>} is spoken by it
684 @type template: string
685 @param dev: The device to use for output. Defaults to the default output
686 device established by L{setScriptIdealOutput}.
687 @type dev: L{AEOutput <AccessEngine.AEOutput.AEOutput>}
688 @param talk: Send a L{CMD_TALK <AEConstants.Output.CMD_TALK>} immediately
689 after this string is sent?
690 @type talk: boolean
691 @param kwargs: this method need L{AEPor <AEPor.AEPor>} and EventLayer
692 @type kwargs: dictionary
693 @return: Was anything sent for output (C{True}) or was text None (C{False})?
694 @rtype: boolean
695 @raise KeyError: when the kwargs don't contain the keys 'layer' and 'por'
696 '''
697 por = kwargs['por']
698 layer = kwargs['layer']
699 if text is None:
700 text = View.getItemText(por)
701 if text is None:
702 return False
703 say(script, cap, role, template % text, layer, por,
704 AEConstants.SEM_ITEM, dev, talk)
705 return True
706
707 -def sayWindow(script, cap, role, text=None, template=u'%s', dev=None, talk=True,
708 **kwargs):
709 '''
710 Calls L{View.getWindowTitle <AccessEngineAPI.View.getWindowTitle>} and outputs
711 the result.
712
713 @param script: The L{AEScript <AEScript.AEScript>} that call this method
714 @type script: L{AEScript <AEScript.AEScript>}
715 @param text: Manually provided text fetched from the L{AEPor <AEPor.AEPor>}
716 @type text: string
717 @param template: Template for text to be spoken. Defaults to %s indicating
718 the text or value retrieved from the L{AEPor <AEPor.AEPor>} is spoken by it
719 @type template: string
720 @param dev: The device to use for output. Defaults to the default output
721 device established by L{setScriptIdealOutput}.
722 @type dev: L{AEOutput <AccessEngine.AEOutput.AEOutput>}
723 @param talk: Send a L{CMD_TALK <AEConstants.Output.CMD_TALK>} immediately
724 after this string is sent?
725 @type talk: boolean
726 @param kwargs: this method need L{AEPor <AEPor.AEPor>}, EventLayer
727 @type kwargs: dictionary
728 @return: Was anything sent for output (C{True}) or was text None (C{False})?
729 @rtype: boolean
730 '''
731 por = kwargs['por']
732 layer = kwargs['layer']
733 if text is None:
734 text = View.getWindowTitle(por)
735 if text is None:
736 return False
737 else:
738 text = _("Window ") + text
739 say(script, cap, role, template % text, layer, por,
740 AEConstants.SEM_WINDOW, dev, talk)
741 return True
742
743 -def saySection(script, cap, role, text=None, template=u'%s', dev=None, talk=True,
744 **kwargs):
745 '''
746 Calls L{View.getAccLabel <AccessEngineAPI.View.getAccLabel>} and outputs the
747 result.
748
749 @param script: The L{AEScript <AEScript.AEScript>} that call this method
750 @type script: L{AEScript <AEScript.AEScript>}
751 @param text: Manually provided text fetched from the L{AEPor <AEPor.AEPor>}
752 @type text: string
753 @param template: Template for text to be spoken. Defaults to %s indicating the
754 text or value retrieved from the L{AEPor <AEPor.AEPor>} is spoken by it
755 @type template: string
756 @param dev: The device to use for output. Defaults to the default output
757 device established by L{setScriptIdealOutput}.
758 @type dev: L{AEOutput <AccessEngine.AEOutput.AEOutput>}
759 @param talk: Send a L{CMD_TALK <AEConstants.Output.CMD_TALK>} immediately
760 after this string is sent?
761 @type talk: boolean
762 @param kwargs: this method need L{AEPor <AEPor.AEPor>}, EventLayer
763 @type kwargs: dictionary
764 @return: Was anything sent for output (C{True}) or was text None (C{False})?
765 @rtype: boolean
766 @raise KeyError: when the kwargs don't contain the keys 'layer' and 'por'
767 '''
768 por = kwargs['por']
769 layer = kwargs['layer']
770 if text is None:
771 text = View.getAccLabel(por)
772 if text is None:
773 return False
774 say(script, cap, role, template % text, layer, por,
775 AEConstants.SEM_SECTION, dev, talk)
776 return True
777
778 -def sayApp(script, cap, role, text=None, template=u'%s', dev=None, talk=True,
779 **kwargs):
780 '''
781 Calls L{View.getAppName <AccessEngineAPI.View.getAppName>} and outputs the
782 result.
783
784 @param script: The L{AEScript <AEScript.AEScript>} that call this method
785 @type script: L{AEScript <AEScript.AEScript>}
786 @param text: Manually provided text fetched from the L{AEPor <AEPor.AEPor>}
787 @type text: string
788 @param template: Template for text to be spoken. Defaults to %s indicating the
789 text or value retrieved from the L{AEPor <AEPor.AEPor>} is spoken by it
790 @type template: string
791 @param dev: The device to use for output. Defaults to the default output
792 device established by L{setScriptIdealOutput}.
793 @type dev: L{AEOutput <AccessEngine.AEOutput.AEOutput>}
794 @param talk: Send a L{CMD_TALK <AEConstants.Output.CMD_TALK>} immediately
795 after this string is sent?
796 @type talk: boolean
797 @param kwargs: this method need L{AEPor <AEPor.AEPor>}, EventLayer
798 @type kwargs: dictionary
799 @return: Was anything sent for output (C{True}) or was text None (C{False})?
800 @rtype: boolean
801 @raise KeyError: when the kwargs don't contain the keys 'layer' and 'por'
802 '''
803 por = kwargs['por']
804 layer = kwargs['layer']
805 if text is None:
806 text = View.getAppName(por)
807 if text is None:
808 return False
809 say(script, cap, role, template % text, layer, por,
810 AEConstants.SEM_APP, dev, talk)
811 return True
812
813 -def sayFont(script, cap, role, text=None, template=u'%s', dev=None, talk=True,
814 **kwargs):
815 '''
816 Calls L{View.getAccTextAttr <AccessEngineAPI.View.getAccTextAttr>} and outputs
817 the value associated with the "family-name" property.
818
819 @param script: The L{AEScript <AEScript.AEScript>} that call this method
820 @type script: L{AEScript <AEScript.AEScript>}
821 @param text: Manually provided text fetched from the L{AEPor <AEPor.AEPor>}
822 @type text: string
823 @param template: Template for text to be spoken. Defaults to %s indicating the
824 text or value retrieved from the L{AEPor <AEPor.AEPor>} is spoken by it
825 @type template: string
826 @param dev: The device to use for output. Defaults to the default output
827 device established by L{setScriptIdealOutput}.
828 @type dev: L{AEOutput <AccessEngine.AEOutput.AEOutput>}
829 @param talk: Send a L{CMD_TALK <AEConstants.Output.CMD_TALK>} immediately
830 after this string is sent?
831 @type talk: boolean
832 @param kwargs: this method need L{AEPor <AEPor.AEPor>}, EventLayer
833 @type kwargs: dictionary
834 @return: Was anything sent for output (C{True}) or was text None (C{False})?
835 @rtype: boolean
836 @raise KeyError: when the kwargs don't contain the keys 'layer' and 'por'
837 '''
838 por = kwargs['por']
839 layer = kwargs['layer']
840 if text is None:
841 text = View.getAccTextAttr('family-name', por)
842 if text is None:
843 return False
844 say(script, cap, role, template % text, layer, por,
845 AEConstants.SEM_FONT, dev, talk)
846 return True
847
848 -def sayCount(script, cap, role, text=None, template=u'%s', dev=None, talk=True,
849 **kwargs):
850 '''
851 Calls L{View.getAccCount <AccessEngineAPI.View.getAccCount>} and outputs the
852 result.
853
854 @param script: The L{AEScript <AEScript.AEScript>} that call this method
855 @type script: L{AEScript <AEScript.AEScript>}
856 @param text: Manually provided text fetched from the L{AEPor <AEPor.AEPor>}
857 @type text: string
858 @param template: Template for text to be spoken. Defaults to %s indicating the
859 text or value retrieved from the L{AEPor <AEPor.AEPor>} is spoken by it
860 @type template: string
861 @param dev: The device to use for output. Defaults to the default output
862 device established by L{setScriptIdealOutput}.
863 @type dev: L{AEOutput <AccessEngine.AEOutput.AEOutput>}
864 @param talk: Send a L{CMD_TALK <AEConstants.Output.CMD_TALK>} immediately
865 after this string is sent?
866 @type talk: boolean
867 @param kwargs: this method need L{AEPor <AEPor.AEPor>}, EventLayer
868 @type kwargs: dictionary
869 @return: Was anything sent for output (C{True}) or was text None (C{False})?
870 @rtype: boolean
871 @raise KeyError: when the kwargs don't contain the keys 'layer' and 'por'
872 '''
873 por = kwargs['por']
874 layer = kwargs['layer']
875 if text is None:
876 text = View.getAccCount(por)
877 if text is None:
878 return False
879 say(script, cap, role, template % text, layer, por,
880 AEConstants.SEM_COUNT, dev, talk)
881 return True
882
883 -def sayIndex(script, cap, role, text=None, template=u'%s', dev=None, talk=True,
884 **kwargs):
885 '''
886 Calls L{View.getAccIndex <AccessEngineAPI.View.getAccIndex>} and outputs the
887 result.
888
889 @param script: The L{AEScript <AEScript.AEScript>} that call this method
890 @type script: L{AEScript <AEScript.AEScript>}
891 @param text: Manually provided text fetched from the L{AEPor <AEPor.AEPor>}
892 @type text: string
893 @param template: Template for text to be spoken. Defaults to %s indicating the
894 text or value retrieved from the L{AEPor <AEPor.AEPor>} is spoken by it
895 @type template: string
896 @param dev: The device to use for output. Defaults to the default output
897 device established by L{setScriptIdealOutput}.
898 @type dev: L{AEOutput <AccessEngine.AEOutput.AEOutput>}
899 @param talk: Send a L{CMD_TALK <AEConstants.Output.CMD_TALK>} immediately
900 after this string is sent?
901 @type talk: boolean
902 @param kwargs: this method need L{AEPor <AEPor.AEPor>}, EventLayer
903 @type kwargs: dictionary
904 @return: Was anything sent for output (C{True}) or was text None (C{False})?
905 @rtype: boolean
906 @raise KeyError: when the kwargs don't contain the keys 'layer' and 'por'
907 '''
908 por = kwargs['por']
909 layer = kwargs['layer']
910 if text is None:
911 text = View.getAccIndex(por)
912 if text is None:
913 return False
914
915 say(script, cap, role, template % text, layer, por,
916 AEConstants.SEM_INDEX, dev, talk)
917 return True
918
919 -def sayColor(script, cap, role, text=None, template=u'%s', dev=None, talk=True,
920 **kwargs):
921 '''
922 Calls L{View.getAccTextAttr <AccessEngineAPI.View.getAccTextAttr>} and outputs
923 the value associated with the "fg-color" property.
924
925 @param script: The L{AEScript <AEScript.AEScript>} that call this method
926 @type script: L{AEScript <AEScript.AEScript>}
927 @param text: Manually provided text fetched from the L{AEPor <AEPor.AEPor>}
928 @type text: string
929 @param template: Template for text to be spoken. Defaults to %s indicating the
930 text or value retrieved from the L{AEPor <AEPor.AEPor>} is spoken by it
931 @type template: string
932 @param dev: The device to use for output. Defaults to the default output
933 device established by L{setScriptIdealOutput}.
934 @type dev: L{AEOutput <AccessEngine.AEOutput.AEOutput>}
935 @param talk: Send a L{CMD_TALK <AEConstants.Output.CMD_TALK>} immediately
936 after this string is sent?
937 @type talk: boolean
938 @param kwargs: this method need L{AEPor <AEPor.AEPor>}, EventLayer
939 @type kwargs: dictionary
940 @return: Was anything sent for output (C{True}) or was text None (C{False})?
941 @rtype: boolean
942 @raise KeyError: when the kwargs don't contain the keys 'layer' and 'por'
943 '''
944 por = kwargs['por']
945 layer = kwargs['layer']
946 if text is None:
947 text = View.getAccTextAttr('fg-color', por)
948 if text is None:
949 return False
950 say(script, cap, role, template % text, layer, por,
951 AEConstants.SEM_COLOR, dev, talk)
952 return True
953
954 -def sayRole(script, cap, role, text=None, template=u'%s', dev=None, talk=True,
955 **kwargs):
956 '''
957 Calls L{View.getAccRoleName <AccessEngineAPI.View.getAccRoleName>} and outputs
958 the result.
959
960 @param script: The L{AEScript <AEScript.AEScript>} that call this method
961 @type script: L{AEScript <AEScript.AEScript>}
962 @param text: Manually provided text fetched from the L{AEPor <AEPor.AEPor>}
963 @type text: string
964 @param template: Template for text to be spoken. Defaults to %s indicating the
965 text or value retrieved from the L{AEPor <AEPor.AEPor>} is spoken by it
966 @type template: string
967 @param dev: The device to use for output. Defaults to the default output
968 device established by L{setScriptIdealOutput}.
969 @type dev: L{AEOutput <AccessEngine.AEOutput.AEOutput>}
970 @param talk: Send a L{CMD_TALK <AEConstants.Output.CMD_TALK>} immediately
971 after this string is sent?
972 @type talk: boolean
973 @param kwargs: this method need L{AEPor <AEPor.AEPor>}, EventLayer
974 @type kwargs: dictionary
975 @return: Was anything sent for output (C{True}) or was text None (C{False})?
976 @rtype: boolean
977 @raise KeyError: when the kwargs don't contain the keys 'layer' and 'por'
978 '''
979 por = kwargs['por']
980 layer = kwargs['layer']
981 if text is None:
982 text = View.getAccRoleName(por)
983 if text is None:
984 return False
985 say(script, cap, role, template % text, layer, por,
986 AEConstants.SEM_ROLE, dev, talk)
987 return True
988
989 -def sayLevel(script, cap, role, text=None, template=u'%s', dev=None, talk=True,
990 **kwargs):
991 '''
992 Calls L{View.getAccLevel <AccessEngineAPI.View.getAccLevel>} and outputs the
993 result.
994
995 @param script: The L{AEScript <AEScript.AEScript>} that call this method
996 @type script: L{AEScript <AEScript.AEScript>}
997 @param text: Manually provided text fetched from the L{AEPor <AEPor.AEPor>}
998 @type text: string
999 @param template: Template for text to be spoken. Defaults to %s indicating the
1000 text or value retrieved from the L{AEPor <AEPor.AEPor>} is spoken by it
1001 @type template: string
1002 @param dev: The device to use for output. Defaults to the default output
1003 device established by L{setScriptIdealOutput}.
1004 @type dev: L{AEOutput <AccessEngine.AEOutput.AEOutput>}
1005 @param talk: Send a L{CMD_TALK <AEConstants.Output.CMD_TALK>} immediately
1006 after this string is sent?
1007 @type talk: boolean
1008 @param kwargs: this method need L{AEPor <AEPor.AEPor>}, EventLayer
1009 @type kwargs: dictionary
1010 @return: Was anything sent for output (C{True}) or was text None (C{False})?
1011 @rtype: boolean
1012 @raise KeyError: when the kwargs don't contain the keys 'layer' and 'por'
1013 '''
1014 por = kwargs['por']
1015 layer = kwargs['layer']
1016 if text is None:
1017 text = View.getAccLevel(por)
1018 if text is None:
1019 return False
1020 say(script, cap, role, template % text, layer, por,
1021 AEConstants.SEM_LEVEL, dev, talk)
1022 return True
1023
1024 -def sayStatus(script, cap, role, text=None, template=u'%s', dev=None, talk=True,
1025 **kwargs):
1026 '''
1027 Calls L{View.getItemText <AccessEngineAPI.View.getItemText>} and outputs the
1028 result.
1029
1030 @param script: The L{AEScript <AEScript.AEScript>} that call this method
1031 @type script: L{AEScript <AEScript.AEScript>}
1032 @param text: Manually provided text fetched from the L{AEPor <AEPor.AEPor>}
1033 @type text: string
1034 @param template: Template for text to be spoken. Defaults to %s indicating the
1035 text or value retrieved from the L{AEPor <AEPor.AEPor>} is spoken by it
1036 @type template: string
1037 @param dev: The device to use for output. Defaults to the default output
1038 device established by L{setScriptIdealOutput}.
1039 @type dev: L{AEOutput <AccessEngine.AEOutput.AEOutput>}
1040 @param talk: Send a L{CMD_TALK <AEConstants.Output.CMD_TALK>} immediately
1041 after this string is sent?
1042 @type talk: boolean
1043 @param kwargs: this method need L{AEPor <AEPor.AEPor>}, EventLayer
1044 @type kwargs: dictionary
1045 @return: Was anything sent for output (C{True}) or was text None (C{False})?
1046 @rtype: boolean
1047 @raise KeyError: when the kwargs don't contain the keys 'layer' and 'por'
1048 '''
1049 por = kwargs['por']
1050 layer = kwargs['layer']
1051 if text is None:
1052 text = View.getItemText(por)
1053 if text is None:
1054 return False
1055 say(script, cap, role, template % text, layer, por,
1056 AEConstants.SEM_STATUS, dev, talk)
1057 return True
1058
1059 -def sayState(script, cap, role, text=None, template=u'%s', dev=None, talk=True,
1060 **kwargs):
1061 '''
1062 Calls L{View.getStateText <AccessEngineAPI.View.getStateText>} and outputs the
1063 result.
1064
1065 @param script: The L{AEScript <AEScript.AEScript>} that call this method
1066 @type script: L{AEScript <AEScript.AEScript>}
1067 @param text: Manually provided text fetched from the L{AEPor <AEPor.AEPor>}
1068 @type text: string
1069 @param template: Template for text to be spoken. Defaults to %s indicating the
1070 text or value retrieved from the L{AEPor <AEPor.AEPor>} is spoken by it
1071 @type template: string
1072 @param dev: The device to use for output. Defaults to the default output
1073 device established by L{setScriptIdealOutput}.
1074 @type dev: L{AEOutput <AccessEngine.AEOutput.AEOutput>}
1075 @param talk: Send a L{CMD_TALK <AEConstants.Output.CMD_TALK>} immediately
1076 after this string is sent?
1077 @type talk: boolean
1078 @param kwargs: this method need L{AEPor <AEPor.AEPor>}, EventLayer
1079 @type kwargs: dictionary
1080 @return: Was anything sent for output (C{True}) or was text None (C{False})?
1081 @rtype: boolean
1082 @raise KeyError: when the kwargs don't contain the keys 'layer' and 'por'
1083 '''
1084 por = kwargs['por']
1085 layer = kwargs['layer']
1086 if text is None:
1087 text = View.getStateText(por)
1088 if text is None:
1089 return False
1090 say(script, cap, role, template % text, layer, por,
1091 AEConstants.SEM_STATE, dev, talk)
1092 return True
1093
1094 -def sayDesc(script, cap, role, text=None, template=u'%s', dev=None, talk=True,
1095 **kwargs):
1096 '''
1097 Calls L{View.getAccDesc <AccessEngineAPI.View.getAccDesc>} and outputs the
1098 result.
1099
1100 @param script: The L{AEScript <AEScript.AEScript>} that call this method
1101 @type script: L{AEScript <AEScript.AEScript>}
1102 @param text: Manually provided text fetched from the L{AEPor <AEPor.AEPor>}
1103 @type text: string
1104 @param template: Template for text to be spoken. Defaults to %s indicating the
1105 text or value retrieved from the L{AEPor <AEPor.AEPor>} is spoken by it
1106 @type template: string
1107 @param dev: The device to use for output. Defaults to the default output
1108 device established by L{setScriptIdealOutput}.
1109 @type dev: L{AEOutput <AccessEngine.AEOutput.AEOutput>}
1110 @param talk: Send a L{CMD_TALK <AEConstants.Output.CMD_TALK>} immediately
1111 after this string is sent?
1112 @type talk: boolean
1113 @param kwargs: this method need L{AEPor <AEPor.AEPor>}, EventLayer
1114 @type kwargs: dictionary
1115 @return: Was anything sent for output (C{True}) or was text None (C{False})?
1116 @rtype: boolean
1117 @raise KeyError: when the kwargs don't contain the keys 'layer' and 'por'
1118 '''
1119 por = kwargs['por']
1120 layer = kwargs['layer']
1121 if text is None:
1122 text = View.getAccDesc(por)
1123 if text is None:
1124 return False
1125 say(script, cap, role, template % text, layer, por, AEConstants.SEM_DESC,
1126 dev, talk)
1127 return True
1128
1129 -def sayHotkey(script, cap, role, text=None, template=u'%s', dev=None, talk=True,
1130 **kwargs):
1131 '''
1132 Calls L{View.getAccClickKey <AccessEngineAPI.View.getAccClickKey>} and outputs
1133 the result after replacing <> characters.
1134
1135 @param script: The L{AEScript <AEScript.AEScript>} that call this method
1136 @type script: L{AEScript <AEScript.AEScript>}
1137 @param text: Manually provided text fetched from the L{AEPor <AEPor.AEPor>}
1138 @type text: string
1139 @param template: Template for text to be spoken. Defaults to %s indicating the
1140 text or value retrieved from the L{AEPor <AEPor.AEPor>} is spoken by it
1141 @type template: string
1142 @param dev: The device to use for output. Defaults to the default output
1143 device established by L{setScriptIdealOutput}.
1144 @type dev: L{AEOutput <AccessEngine.AEOutput.AEOutput>}
1145 @param talk: Send a L{CMD_TALK <AEConstants.Output.CMD_TALK>} immediately
1146 after this string is sent?
1147 @type talk: boolean
1148 @param kwargs: this method need L{AEPor <AEPor.AEPor>}, EventLayer
1149 @type kwargs: dictionary
1150 @return: Was anything sent for output (C{True}) or was text None (C{False})?
1151 @rtype: boolean
1152 @raise KeyError: when the kwargs don't contain the keys 'layer' and 'por'
1153 '''
1154 por = kwargs['por']
1155 layer = kwargs['layer']
1156 if text is None:
1157 text = View.getAccClickKey(por)
1158
1159
1160
1161
1162
1163 try:
1164 text = text.replace('<', '')
1165 text = text.replace('>', ', ')
1166 except AttributeError:
1167 pass
1168 if text is None:
1169 return False
1170 say(script, cap, role, template % text, layer, por,
1171 AEConstants.SEM_HOTKEY, dev, talk)
1172 return True
1173
1174 -def sayError(script, cap, role, text=None, template=u'%s', dev=None, talk=True,
1175 **kwargs):
1176 '''
1177 Outputs an SUE system error message.
1178
1179 @param script: The L{AEScript <AEScript.AEScript>} that call this method
1180 @type script: L{AEScript <AEScript.AEScript>}
1181 @param text: Manually provided text fetched from the L{AEPor <AEPor.AEPor>}
1182 @type text: string
1183 @param template: Template for text to be spoken. Defaults to %s indicating the
1184 text or value retrieved from the L{AEPor <AEPor.AEPor>} is spoken by it
1185 @type template: string
1186 @param dev: The device to use for output. Defaults to the default output
1187 device established by L{setScriptIdealOutput}.
1188 @type dev: L{AEOutput <AccessEngine.AEOutput.AEOutput>}
1189 @param talk: Send a L{CMD_TALK <AEConstants.Output.CMD_TALK>} immediately
1190 after this string is sent?
1191 @type talk: boolean
1192 @param kwargs: this method need L{AEPor <AEPor.AEPor>}, EventLayer
1193 @type kwargs: dictionary
1194 @return: Was anything sent for output (C{True}) or was text None (C{False})?
1195 @rtype: boolean
1196 @raise KeyError: when the kwargs don't contain the keys 'layer' and 'por'
1197 '''
1198 por = kwargs['por']
1199 layer = kwargs['layer']
1200
1201 if text is None:
1202 return False
1203 say(script, cap, role, template % text, layer, por,
1204 AEConstants.SEM_ERROR, dev, talk)
1205 return True
1206
1207 -def sayInfo(script, cap, role, text=None, template=u'%s', dev=None, talk=True,
1208 **kwargs):
1209 '''
1210 Outputs an informational SUE system message.
1211
1212 @param script: The L{AEScript <AEScript.AEScript>} that call this method
1213 @type script: L{AEScript <AEScript.AEScript>}
1214 @param text: Manually provided text fetched from the L{AEPor <AEPor.AEPor>}
1215 @type text: string
1216 @param template: Template for text to be spoken. Defaults to %s indicating the
1217 text or value retrieved from the L{AEPor <AEPor.AEPor>} is spoken by it
1218 @type template: string
1219 @param dev: The device to use for output. Defaults to the default output
1220 device established by L{setScriptIdealOutput}.
1221 @type dev: L{AEOutput <AccessEngine.AEOutput.AEOutput>}
1222 @param talk: Send a L{CMD_TALK <AEConstants.Output.CMD_TALK>} immediately
1223 after this string is sent?
1224 @type talk: boolean
1225 @param kwargs: this method need L{AEPor <AEPor.AEPor>}, EventLayer
1226 @type kwargs: dictionary
1227 @return: Was anything sent for output (C{True}) or was text None (C{False})?
1228 @rtype: boolean
1229 @raise KeyError: when the kwargs don't contain the keys 'layer' and 'por'
1230 '''
1231 por = kwargs['por']
1232 layer = kwargs['layer']
1233 if text is None:
1234 return False
1235 say(script, cap, role, template % text, layer, por,
1236 AEConstants.SEM_INFO, dev, talk)
1237 return True
1238
1239 -def sayConfirm(script, cap, role, text=None, template=u'%s', dev=None, talk=True,
1240 **kwargs):
1241 '''
1242 Outputs a confirmation message for a user action. L{AEPor <AEPor.AEPor>}
1243 ignored.
1244
1245 @param script: The L{AEScript <AEScript.AEScript>} that call this method
1246 @type script: L{AEScript <AEScript.AEScript>}
1247 @param text: Manually provided text fetched from the L{AEPor <AEPor.AEPor>}
1248 @type text: string
1249 @param template: Template for text to be spoken. Defaults to %s indicating the
1250 text or value retrieved from the L{AEPor <AEPor.AEPor>} is spoken by it
1251 @type template: string
1252 @param dev: The device to use for output. Defaults to the default output
1253 device established by L{setScriptIdealOutput}.
1254 @type dev: L{AEOutput <AccessEngine.AEOutput.AEOutput>}
1255 @param talk: Send a L{CMD_TALK <AEConstants.Output.CMD_TALK>} immediately
1256 after this string is sent?
1257 @type talk: boolean
1258 @param kwargs: this method need L{AEPor <AEPor.AEPor>}, EventLayer
1259 @type kwargs: dictionary
1260 @return: Was anything sent for output (C{True}) or was text None (C{False})?
1261 @rtype: boolean
1262 @raise KeyError: when the kwargs don't contain the keys 'layer' and 'por'
1263 '''
1264 por = kwargs['por']
1265 layer = kwargs['layer']
1266 if text is None:
1267 return False
1268 say(script, cap, role, template % text, layer, por,
1269 AEConstants.SEM_CONFIRM, dev, talk)
1270 return True
1271
1272 -def sayValue(script, cap, role, text=None, template=u'%s', dev=None, talk=True,
1273 **kwargs):
1274 '''
1275 Calls L{View.getAccFloatValue <AccessEngineAPI.View.getAccFloatValue>} and
1276 outputs the result.
1277
1278 @param script: The L{AEScript <AEScript.AEScript>} that call this method
1279 @type script: L{AEScript <AEScript.AEScript>}
1280 @param text: Manually provided text fetched from the L{AEPor <AEPor.AEPor>}
1281 @type text: string
1282 @param template: Template for text to be spoken. Defaults to %s indicating the
1283 text or value retrieved from the L{AEPor <AEPor.AEPor>} is spoken by it
1284 @type template: string
1285 @param dev: The device to use for output. Defaults to the default output
1286 device established by L{setScriptIdealOutput}.
1287 @type dev: L{AEOutput <AccessEngine.AEOutput.AEOutput>}
1288 @param talk: Send a L{CMD_TALK <AEConstants.Output.CMD_TALK>} immediately
1289 after this string is sent?
1290 @type talk: boolean
1291 @param kwargs: this method need L{AEPor <AEPor.AEPor>}, EventLayer
1292 @type kwargs: dictionary
1293 @return: Was anything sent for output (C{True}) or was text None (C{False})?
1294 @rtype: boolean
1295 @raise KeyError: when the kwargs don't contain the keys 'layer' and 'por'
1296 '''
1297 por = kwargs['por']
1298 layer = kwargs['layer']
1299 if text is None:
1300 text = View.getAccFloatValue(por)
1301 if text is None:
1302 return False
1303 say(script, cap, role, template % text, layer, por,
1304 AEConstants.SEM_VALUE, dev, talk)
1305 return True
1306
1307 -def sayValueExtents(script, cap, role, text=None, template=u'%s', dev=None,
1308 talk=True, **kwargs):
1309 '''
1310 Calls L{View.getAccFloatValueExtents <AccessEngineAPI.View.getAccFloatValueExtents>}
1311 and outputs the result.
1312
1313 @param script: The L{AEScript <AEScript.AEScript>} that call this method
1314 @type script: L{AEScript <AEScript.AEScript>}
1315 @param text: Manually provided text fetched from the L{AEPor <AEPor.AEPor>}
1316 @type text: string
1317 @param template: Template for text to be spoken. Defaults to %s indicating the
1318 text or value retrieved from the L{AEPor <AEPor.AEPor>} is spoken by it
1319 @type template: string
1320 @param dev: The device to use for output. Defaults to the default output
1321 device established by L{setScriptIdealOutput}.
1322 @type dev: L{AEOutput <AccessEngine.AEOutput.AEOutput>}
1323 @param talk: Send a L{CMD_TALK <AEConstants.Output.CMD_TALK>} immediately
1324 after this string is sent?
1325 @type talk: boolean
1326 @param kwargs: this method need L{AEPor <AEPor.AEPor>}, EventLayer
1327 @type kwargs: dictionary
1328 @return: Was anything sent for output (C{True}) or was text None (C{False})?
1329 @rtype: boolean
1330 @raise KeyError: when the kwargs don't contain the keys 'layer' and 'por'
1331 '''
1332 por = kwargs['por']
1333 layer = kwargs['layer']
1334 if text is None:
1335 text = View.getAccFloatValueExtents(por)
1336 if text is None:
1337 return False
1338 say(script, cap, role, template % text, layer, por,
1339 AEConstants.SEM_EXTENTS, dev, talk)
1340 return True
1341
1343 '''
1344 Sets caret location on the device.
1345
1346 @param script: The L{AEScript <AEScript.AEScript>} that call this method
1347 @type script: L{AEScript <AEScript.AEScript>}
1348 @param layer: Layer on which the event occurred
1349 @type layer: integer
1350 @param value: Caret position
1351 @type value: integer
1352 @param cap: The target device's capability
1353 @type cap: string
1354 @param role: The target device's role
1355 @type role: string
1356 @param sem: The semantic stream on which to send output; defaults to None
1357 for the default semantic.
1358 @type sem: integer
1359 @param dev: Device that should receive the command
1360 @type dev: L{AEOutput <AccessEngine.AEOutput.AEOutput>}
1361 '''
1362 send(script, layer, AEConstants.CMD_CARET, value, sem=sem, dev=dev,
1363 cap=cap, role=role)
1364
1365 -def setBrlTruncate(script, layer, value, cap, role, sem=None, dev=None):
1366 '''
1367 Sets a two-item tuple (left, right) to the device indicating if a line of
1368 text has been truncated either on the left or right side.
1369
1370 @param script: The L{AEScript <AEScript.AEScript>} that call this method
1371 @type script: L{AEScript <AEScript.AEScript>}
1372 @param layer: Layer on which the event occurred
1373 @type layer: integer
1374 @param value: Two-item tuple of booleans (left, right) indicating trucation
1375 @type value: tuple
1376 @param sem: The semantic stream on which to send output; defaults to None
1377 for the default semantic.
1378 @type sem: integer
1379 @param dev: Device that should receive the command
1380 @type dev: L{AEOutput <AccessEngine.AEOutput.AEOutput>}
1381 @return: Return value specific to the given command
1382 @rtype: object
1383 '''
1384 send(script, layer, AEConstants.CMD_TRUNCATE, value, sem=sem, dev=dev,
1385 cap=cap, role=role)
1386
1388 '''
1389 Gets a two-item tuple (left and right) containing the ellipsis length.
1390
1391 @param script: The L{AEScript <AEScript.AEScript>} that call this method
1392 @type script: L{AEScript <AEScript.AEScript>}
1393 @param layer: Layer on which the event occurred
1394 @type layer: integer
1395 @param sem: The semantic stream on which to send output; defaults to None
1396 for the default semantic.
1397 @type sem: integer
1398 @param dev: Device that should receive the command
1399 @type dev: L{AEOutput <AccessEngine.AEOutput.AEOutput>}
1400 @return: (left, right) ellipsis length
1401 @rtype: tuple
1402 '''
1403 return send(script, layer, AEConstants.CMD_GET_ELLIPSIS_SIZE, None, \
1404 sem=sem, dev=dev, cap=cap, role=role)
1405
1407 '''
1408 Gets the number of missing/broken cells defined by the
1409 "missing cell string" user setting.
1410
1411 @param script: The L{AEScript <AEScript.AEScript>} that call this method
1412 @type script: L{AEScript <AEScript.AEScript>}
1413 @param layer: Layer on which the event occurred
1414 @type layer: integer
1415 @param sem: The semantic stream on which to send output; defaults to None
1416 for the default semantic.
1417 @type sem: integer
1418 @param dev: Device that should receive the command
1419 @type dev: L{AEOutput <AccessEngine.AEOutput.AEOutput>}
1420 @return: Number of missing/broken cells
1421 @rtype: integer
1422 '''
1423 return send(script, layer, AEConstants.CMD_GET_MISSINGCELL_COUNT, None, \
1424 sem=sem, dev=dev, cap=cap, role=role)
1425
1426 -def setMagGoto(script, layer, value, cap, role, sem=None, dev=None):
1427 '''
1428 Sets the viewport of the magnifier
1429
1430 @param script: The L{AEScript <AEScript.AEScript>} that call this method
1431 @type script: L{AEScript <AEScript.AEScript>}
1432 @param layer: Layer on which the event occurred
1433 @type layer: integer
1434 @param value: viewport settings in the form (x1, y1, x2, y2)
1435 @type value: tuple
1436 @param sem: The semantic stream on which to send output; defaults to None
1437 for the default semantic.
1438 @type sem: integer
1439 @param dev: Device that should receive the command
1440 @type dev: L{AEOutput <AccessEngine.AEOutput.AEOutput>}
1441 '''
1442 send(script, layer, AEConstants.CMD_GOTO, value, sem=sem, dev=dev,
1443 cap=cap, role=role)
1444
1445 -def getMagROI(script, layer, cap, role, sem=None, dev=None):
1446 '''
1447 Get the region of interest from magnifier device.
1448
1449 @param script: The L{AEScript <AEScript.AEScript>} that call this method
1450 @type script: L{AEScript <AEScript.AEScript>}
1451 @param layer: Layer on which the event occurred
1452 @type layer: integer
1453 @param sem: The semantic stream on which to send output; defaults to None
1454 for the default semantic.
1455 @type sem: integer
1456 @param dev: Device that should receive the command
1457 @type dev: L{AEOutput <AccessEngine.AEOutput.AEOutput>}
1458 @return: ROI as a four-item tuple in the form (x1, y1, x2, y2)
1459 @rtype: tuple
1460 '''
1461 return send(script, layer, AEConstants.CMD_GET_ROI, None, sem=sem, \
1462 dev=dev, cap=cap, role=role)
1463
1464 -def getClosestLang(script, layer, tag, cap, role, sem=None, dev=None):
1465 '''
1466 Get the closest language supported by the device to the one given by the
1467 IANA tag. See the L{Devices.Audio.AudioStyle} comment about languages
1468 for help on formatting a proper IANA tag.
1469
1470 @param script: The L{AEScript <AEScript.AEScript>} that call this method
1471 @type script: L{AEScript <AEScript.AEScript>}
1472 @param layer: Layer on which the event occurred
1473 @type layer: integer
1474 @param tag: IANA tag name
1475 @type tag: string
1476 @param sem: Semantic tag indicating the kind of output; defaults to None
1477 for the default semantic.
1478 @type sem: integer
1479 @param dev: Device that should receive the command
1480 @type dev: L{AEOutput <AccessEngine.AEOutput.AEOutput>}
1481 @return: IANA tag name closest to the one given or None meaning no
1482 supported language makes sense
1483 @rtype: string
1484 '''
1485 return send(script, layer, AEConstants.CMD_GET_CLOSEST_LANG, tag, sem=sem, \
1486 dev=dev, cap=cap, role=role)
1487