AccessEngine.AEScript

1 ''' 2 Defines an L{AEScript} class that can register tasks which will be executed in 3 response to L{AEEvent}s and L{AEInput.Gesture}s. 4 5 @author: Peter Parente 6 @author: Pete Brunet 7 @organization: IBM Corporation 8 @copyright: Copyright (c) 2005, 2007 IBM Corporation 9 10 @author: Frank Zenker 11 @author: Ramona Bunk 12 @author: Nicole Anacker 13 @organization: IT Science Center Ruegen gGmbH, Germany 14 @copyright: Copyright (c) 2007, 2008 ITSC Ruegen 15 16 @license: I{The BSD License}. 17 All rights reserved. This program and the accompanying materials are made 18 available under the terms of the BSD license which accompanies 19 this distribution, and is available at 20 U{http://www.opensource.org/licenses/bsd-license.php} 21 ''' 22 23 import logging, weakref, os, sys 24 import types 25 import AccessEngine 26 from AccessEngine import AEEvent, AEAccInterfaces, AEInput, AEUserInterface 27 import AEConstants, AccessEngineAPI 28 from Tools.i18n import _ 29 from AccessEngine.AEState import AEState as ScriptState 30 31 log = logging.getLogger('AEScript') 32

33 -def _postTimerEvent(interval, task_key, aid, weman):

34 ''' 35 Callback for timer events. Tries to post an L{AEEvent} for 36 the task intended to handle the event if the task is still alive. 37 38 @param interval: Interval in seconds on which the timer fires. 39 @type interval: interval 40 @param task_key: Key of the task to execute in response to the 41 L{AEEvent.TimerAlert}. 42 @type task_key: tuple of string ('task name', 'script name') 43 @param aid: Unique identifier for the application L{AETier} with which the 44 timer is associated. 45 @type aid: opaque 46 @param weman: Weak reference to the L{AEEventManager} to use to post 47 L{AEEvent.TimerAlert} events. 48 @type weman: weakref.proxy 49 @return: If C{True} continue timer alerts on the interval. 50 If C{False} stop them. 51 @rtype: boolean 52 ''' 53 try: 54 weman.postEvents(AEEvent.TimerAlert(aid, task_key, interval)) 55 except ReferenceError: 56 return False 57 return True

58 59 60 EVENT_KINDS = [AEEvent.CaretChange, 61 AEEvent.ChildrenChange, 62 AEEvent.FocusChange, 63 AEEvent.MouseChange, 64 AEEvent.PropertyChange, 65 AEEvent.ScreenChange, 66 AEEvent.SelectorChange, 67 AEEvent.StateChange, 68 AEEvent.TableChange, 69 AEEvent.ViewChange] 70

71 -class AEScript(AEUserInterface.AEUserInterface):

72 ''' 73 Registers and maintains a collection of Task Functions that will execute in 74 response to L{AccessEngine} events and commands (L{AEEvent}s and 75 L{AEInput.Gesture}s). This class should be sublclassed by script developers 76 who wish to define, modify, or extend the SUE user interface. 77 78 @cvar STATE: Class to instantiate and use to store state information across 79 all instances of this L{AEScript}. Defaults to the L{AEState} base class, 80 but can be overridden with a subclass of L{AEState <AEState.AEState>}. 81 @type STATE: L{AEState <AEState.AEState>} class 82 @ivar tier: The tier for the application this script belongs to. 83 @type tier: L{AETier} 84 @ivar registered_tasks: All task wich are registered with the L{registerTask} 85 method in this L{AEScript}. This dictionary connects the name of the task to 86 the associated execute and update functions. Furthermore it notes to which 87 cyclic input task this task belongs :: 88 Dictionary { 89 key: ('task name', 'script name'), 90 value: [execute_function, update_function, [ ('cycle name', 'script name') ]] 91 } 92 @type registered_tasks: dictionary 93 @ivar event_tasks: Notes which tasks are bind to which event type on which 94 event layer :: 95 Dictionary { 96 key: (AEEvent-Type-Class, layer), 97 value: [ ('task name', 'script name') ] 98 } 99 @type event_tasks: dictionary 100 @ivar commands: Connects a task to a L{AEInput.GestureList} sequence on some 101 L{AEInput} device. The task name needs to be hashed into the 102 L{registered_tasks} dictionary to fully resolve the task. :: 103 WeakValueDictionary { 104 key: AEInput.GestureList, 105 value: ('task name', 'script name') 106 } 107 @type commands: weakref.WeakValueDictionary of (L{AEInput.GestureList} : tuple) 108 @ivar command_descriptions: Description of the task to be shown in command chooser :: 109 Dictionary { 110 key: 'task name', 111 value: string 112 } 113 @type command_descriptions: dictionary 114 @ivar cyclic_input_tasks: Connects more than one task to a 115 L{AEInput.GestureList} sequence on some L{AEInput} device. When the action 116 code of the L{AEInput.GestureList} is activated once the first task will be 117 executed. The second time the action code is activated the second task will 118 be executed, and so on...:: 119 Dictionary { 120 key: ('cycle name', 'script name'), 121 value: [ ('task name', 'script name') ] 122 } 123 @type cyclic_input_tasks: dictionary 124 @ivar chooser_tasks: Connects a task to respond to a change in a L{AEChooser} :: 125 Dictionary { 126 key: id(AEChooser), 127 value: ('task name', 'script name') 128 } 129 @type chooser_tasks: dictionary 130 @ivar around_tasks: additional informations for an L{event task <event_tasks>} 131 that is chained around another task :: 132 Dictionary { 133 key: 'new task name', 134 value: ['replaced task name', 'replaced task script', AEScript, 135 execute_function, update_function, ['functions_to_replace']] 136 } 137 @type around_tasks: dictionary 138 @ivar state: Settings for this L{AEScript}. Defaults to an empty L{ScriptState} 139 object that can be used to store state information that is not configurable 140 or persistable unless L{STATE} is specified. 141 @type state: L{ScriptState} 142 @ivar out_caps: Capabilities set by L{setIdealOutput} as ideal for output 143 from this L{AEScript}. These are used to "late bind" a device for use during 144 execution of this L{AEScript} and its tasks. Defaults to audio. 145 @type out_caps: list of string 146 @ivar def_out: Default output device to use for all L{Output.say 147 <AccessEngine.AccessEngineAPI.Output.say>} calls in a L{AEScript} module :: 148 Dictionary { 149 key: Script 150 value: weakref.proxy to AEOutput 151 } 152 @type def_out: dictionary 153 @ivar before_chains: Mapping from target task name to a list of task 154 names which should be executed before the target :: 155 Dictionary { 156 key: ('task name', 'script name'), 157 value: list of [('task name', 'script name')] 158 } 159 @type before_chains: dictionary 160 @ivar after_chains: Mapping from target task name to a list of task 161 names which should be executed after the target :: 162 Dictionary { 163 key: ('task name', 'script name'), 164 value: list of [('task name', 'script name')] 165 } 166 @type after_chains: dictionary 167 @ivar around_chains: Mapping from target task name to one task name 168 which should be executed instead of the target :: 169 Dictionary { 170 key: ('task name', 'script name'), 171 value: ('task name', 'script name') 172 } 173 @type around_chains: dictionary 174 @ivar registered_modifiers: Mapping from device to a registered modifier for 175 that device 176 @type registered_modifiers: weakref.WeakKeyDictionary 177 ''' 178 STATE = ScriptState 179

180 - def __init__(self):

181 ''' 182 Creates empty dictionaries for registered, event, command and chooser tasks. 183 Create a state object for storage using the class in L{STATE} in case the 184 L{AEScript} hasn't previously persisted its settings on disk. 185 186 @note: Script writers should override L{init} to do initialization, not 187 this method. 188 ''' 189 self.tier = None 190 self.registered_tasks = {} 191 self.chooser_tasks = {} 192 self.event_tasks = {} 193 self.cyclic_input_tasks = {} 194 self.commands = {} 195 self.command_descriptions = {} 196 self.around_tasks = {} 197 # default to audio output 198 self.out_caps = ['audio'] 199 self.def_out = None 200 # define empty chains for tasks 201 self.before_chains = {} 202 self.after_chains = {} 203 self.around_chains = {} 204 self.registered_modifiers = weakref.WeakKeyDictionary() 205 206 # instantiate an instance of the STATE class; it may be filled with data 207 # when preInit is called with state already persisted to disk 208 self.state = self.STATE() 209 # initialize state settings 210 self.state.init()

211 212

213 - def preInit(self, tier):

214 ''' 215 Overrides pre-initialization to load persisted state from disk. Fetches the 216 managers from the L{AccessEngine} first so that state can be loaded using 217 the L{AESettingsManager}. Loads the state, then invokes the super class 218 version of this method to finish initialization. 219 220 @note: Script writers should override L{init} to do initialization, not 221 this method. 222 223 @param tier: The tier for the application this L{AEScript} belongs to. 224 @type tier: L{AETier} 225 ''' 226 227 # get managers, this duplicates some work done in the super class, but 228 # it's harmless and only done once per Script 229 try: 230 # use the settings manager to try to load persisted state for this Script 231 self.state = AccessEngine.AESettingsManager.loadState(self.getClassName(), 232 self.state) 233 except KeyError: 234 # do nothing, a blank state object has already been created 235 pass 236 self.tier = tier

237

238 - def init(self):

239 ''' 240 Does nothing. Reserved for subclasses to initialize themselves. 241 ''' 242 pass

243

244 - def postClose(self):

245 ''' 246 Frees all tasks managed by this L{AEScript}. 247 248 @note: Script writers should override L{close} to do finialization, not 249 this method. 250 ''' 251 # unregister modifiers 252 for dev, codes in self.registered_modifiers.iteritems(): 253 self.unregisterModifiers(dev, codes) 254 255 # IMPORTANT: throw away weak ref to device else the callback keeps it alive 256 self.def_out = None 257 # throw away all references 258 self.registered_tasks = {} 259 self.chooser_tasks = {} 260 self.event_tasks = {} 261 self.cyclic_input_tasks = {} 262 self.commands = {} 263 self.around_tasks = {} 264 self.registered_modifiers = weakref.WeakKeyDictionary()

265

266 - def close(self):

267 ''' 268 Does nothing. Reserved for subclasses to finalize themselves. 269 ''' 270 pass

271

272 - def getState(self):

273 ''' 274 Returns the L{AEState <AEState.AEState>} for this L{AEScript} or a dummy 275 object that can be used to store state information that is neither user 276 configurable or persistable. 277 278 @return: Returns the settings for this L{AEScript} or a dummy object. 279 @rtype: L{AEState <AEState.AEState>} 280 ''' 281 return self.state

282

283 - def setIdealOutput(self, *capabilities):

284 ''' 285 Sets the ideal device capabilities to be used to locate a device for all 286 output methods invoked from the caller's L{AEScript} module, including the 287 Script class itself and all of its registered tasks. The capabilities list 288 should include strings naming L{AEOutput <AEOutput.AEOutput>} interfaces 289 ("audio" and/or "braille") at present. 290 291 @param capabilities: Names of capabilities required on the device. 292 @type capabilities: list of string 293 ''' 294 self.out_caps = capabilities

295

296 - def getIdealOutput(self):

297 ''' 298 Gets the ideal device capabilities to locate a device to be used by all 299 output methods invoked from the caller's Script module, including the 300 L{AEScript} class itself and all of its registered tasks. 301 302 @return: Names of capabilities set as ideal for a default output device. 303 @rtype: list of string 304 ''' 305 return self.out_caps

306

307 - def _changeDefaultOutput(self, ref=None):

308 ''' 309 Gets an output device based on the ideal capabilities requested by the 310 current L{AEScript}. Creates a weak proxy for the device object. When the 311 weak ref is no longer valid, this method is called again to find another 312 suitable device. 313 314 @param ref: Weak proxy that is no longer valid 315 @type ref: weakref.proxy 316 ''' 317 # get an output device to serve as the default output 318 caps = self.getIdealOutput() 319 320 # get all devices providing the given capabilities 321 cap_devs = AccessEngine.AEDeviceManager.getOutputByCaps(caps) 322 323 if cap_devs is None or len(cap_devs) == 0: 324 self.def_out = None 325 else: 326 self.def_out = weakref.proxy(cap_devs[0], self._changeDefaultOutput)

327

328 - def getOutputDevices(self):

329 ''' 330 Gets the output device for this L{AEScript}. 331 332 @return: Return the output device for this L{AEScript}. 333 @rtype: L{def_out} 334 ''' 335 return self.def_out

336

337 - def getAETier(self):

338 ''' 339 Gets the L{AETier} to the L{AEScript}. 340 341 @return: Return the tier to the L{AEScript}. 342 @rtype: L{AETier} 343 ''' 344 return self.tier

345

346 - def getPointerPOR(self, script):

347 ''' 348 Gets the pointer L{AEPor <AEPor.AEPor>} for this L{AETier}. 349 350 @return: Point of regard stored programmatically by this L{AETier}. 351 @rtype: L{AEPor <AEPor.AEPor>} 352 ''' 353 return self.tier.getPointer()

354

355 - def setPointerPOR(self, por):

356 ''' 357 Sets the pointer L{AEPor <AEPor.AEPor>} for this L{AETier}. 358 359 @param por: Point of regard to set as the pointer 360 @type por: L{AEPor <AEPor.AEPor>} 361 ''' 362 self.tier.setPointer(por)

363

364 - def getVirtualPOR(self):

365 ''' 366 Get the actual virtual pointer. 367 368 @return: Return the actual virtual pointer 369 @rtype: L{AEPor <AEPor.AEPor>} 370 ''' 371 return self.tier.virtual_por

372

373 - def setVirtualPOR(self, por):

374 ''' 375 Set the virtual pointer on the passed por position. 376 377 @param por: por position 378 @type por: L{AEPor <AEPor.AEPor>} 379 ''' 380 self.tier.virtual_por = por

381

382 - def getLastKey(self):

383 ''' 384 Gets the key code, key sym, and modifiers of the last key pressed when this 385 L{AETier} was active. This information should B{not} be used to trigger 386 events, but rather as additional information for correcting accessibility 387 problems in certain applications where the standard accessibility events do 388 not provide enough information. 389 390 @note: The values returned by this event are platform specific. This may 391 change in the future. Are you sure you don't want to use a task to response 392 to an L{AEInput.Gesture}? 393 394 @return: Key code, key sym, and key modifier bit mask 395 @rtype: 3-tuple of integer, string, integer 396 ''' 397 return self.tier.getLastKey()

398

399 - def getTempData(self, name):

400 ''' 401 Gets the value previously stored under the given name using 402 L{AETier.setTempVal <AccessEngine.AETier.AETier.setTempVal>}. 403 See that method for details. 404 405 If no value has been stored under the given name, C{None} is returned. 406 407 @param name: Name of the stored data. 408 @type name: immutable 409 @return: Value stored under the given name or C{None}. 410 @rtype: object 411 ''' 412 try: 413 return self.tier.getTempVal(name) 414 except KeyError: 415 return None

416

417 - def setTempData(self, name, value):

418 ''' 419 Stores the given value under the given name. The data will be available via 420 L{AETier.getTempVal <AccessEngine.AETier.AETier.getTempVal>} to all tasks 421 executing or updating in response to the current L{AEEvent}. Once the event 422 has been handled by all tasks, all stored information is discarded 423 automatically. 424 425 The name must be an immutable object. The value can be an arbitrary object. 426 Only the value from the most recent call with a given name is stored. 427 428 @param name: Name to associate with the value. 429 @type name: immutable 430 @param value: Any value to store. 431 @type value: object 432 ''' 433 self.tier.setTempVal(name, value)

434

435 - def registerTask(self, task_name, execute_function, update_function = None):

436 ''' 437 Registers a new L{AEScript} task under the given name if no task is 438 already registered with that name in this L{AEScript}. 439 440 Only one task can be registered under a name in a L{AEScript}. If a task 441 is already registered under the given name, any other registration with 442 that name is ignored. 443 444 Tasks that will also be bind to an event can specify an update function. 445 This function will be called when another task forbids the execution of 446 other tasks. The update function allows a task to do necessary actions like 447 state changes. 448 449 @param task_name: Name of the task to register. 450 @type task_name: string 451 @param execute_function: Function that implements the task. 452 @type execute_function: instancemethod 453 @param update_function: Function for houskeeping. 454 @type update_function: instancemethod 455 @raise ValueError: When a task with the given name is already registered 456 in this L{AEScript}. 457 ''' 458 key = (task_name, self.getClassName()) 459 if not self.tier.isTaskRegistered(key): 460 self.registered_tasks[key] = [execute_function, update_function, []] 461 self.tier.addTaskRef(key, self) 462 else: 463 raise ValueError(key)

464

465 - def registerTimerTask(self, task_name, interval, execute_function, 466 task_script_name = None):

467 ''' 468 Registers a task to be called on a set interval. 469 470 @param task_name: Register the name of task. 471 @type task_name: string 472 @param interval: Interval in seconds which the task will be notified. 473 @type interval: integer 474 @param execute_function: Function that implements the task. 475 @type execute_function: instancemethod 476 @param task_script_name: Name of the script in which the execute function of 477 the task is implemented. 478 @type task_script_name: string 479 @raise ValueError: When a task with the given name is already registered in 480 the L{AEScript}. 481 ''' 482 if task_script_name is None: 483 task_script_name = self.getClassName() 484 task_key = (task_name, task_script_name) 485 aid = self.tier.getIdentity() 486 weman = weakref.proxy(AccessEngine.AEEventManager) 487 488 if not self.tier.isTaskRegistered(task_key): 489 self.registered_tasks[task_key] = [execute_function, None, []] 490 # use the access engine timer to notify our callback 491 AccessEngine.AEMain.addTimer(_postTimerEvent, interval, 492 interval, task_key, aid, weman) 493 self.tier.addTaskRef(task_key, self) 494 else: 495 raise ValueError(task_key)

496

497 - def registerCyclicInputTask(self, cycle_name, task_name, \ 498 task_script_name = None):

499 ''' 500 Registeres a L{cyclic_input_task <cyclic_input_tasks>} and/or links another 501 task to it. 502 503 A cyclic input task links several tasks together. Every time the cyclic 504 input task is executed it calls the next linked task. This is usefull, to 505 connect more than one task to a keyboard command. 506 This method links one task to the end of a list of tasks, that are already 507 linked to the cyclic input task. 508 509 @note: The task with the task_name must already be registered as a task, 510 before it can be linked to a cyclic input task. 511 512 @param cycle_name: Name of the cyclic input task. 513 @type cycle_name: string 514 @param task_name: Name of the task that shall be linked to the cyclic input 515 task. 516 @type task_name: string 517 @param task_script_name: Name of the script in which the task is registered. 518 If task_script_name is C{None} the current script name will be used. 519 @type task_script_name: string 520 @raise ValueError: When the task is not registered. 521 ''' 522 # build the keys for the cyclic input task and the other task 523 cycle_key = (cycle_name, self.getClassName()) 524 if task_script_name is None: 525 task_script_name = self.getClassName() 526 task_key = (task_name, task_script_name) 527 528 # find the already registered task or raise a ValueError if the task was 529 # not registered before 530 try: 531 function_list = self.registered_tasks[task_key] 532 function_list[2].append(cycle_key) 533 except KeyError: 534 raise ValueError(key) 535 536 # look whether the cyclic input task was registered before, 537 # if not register it now 538 try: 539 task_list = self.cyclic_input_tasks[cycle_key] 540 except KeyError: 541 self.registerTask(cycle_name, self.doCyclicInputTask) 542 task_list = [] 543 self.cyclic_input_tasks[cycle_key] = task_list 544 task_list.append(task_key)

545

546 - def registerCyclicInputTasks(self, cycle_name, *task_names):

547 ''' 548 Registers a list of tasks to a L{cyclic_input_task <cyclic_input_tasks>}. 549 Uses the L{registerCyclicInputTask} method. 550 551 @note: If you use this method all tasks must be implemented in the same 552 script. Otherwise use the L{registerCyclicInputTask} directly and specify 553 a script name. 554 555 @param cycle_name: Name of the cyclic input task. 556 @type cycle_name: string 557 @param task_names: List with task names, that shall be connected to the 558 cyclic input task. 559 @type task_names: list of string 560 ''' 561 for name in task_names: 562 self.registerCyclicInputTask(cycle_name, name)

563

564 - def registerCommand(self, device, task_name, description=None, 565 propagate=False, *codes):

566 ''' 567 Registers a task in this L{AETier} to be executed in response to an 568 L{AEEvent} indicating that the given L{action codes <commands>} were input 569 on the given L{AEInput} device. 570 571 @param device: Input device to monitor. 572 @type device: L{AEInput} 573 @param codes: List of lists of action codes forming the L{AEInput.Gesture} 574 that will trigger the execution of the named task. For example, 575 C{codes=[[Keyboard.AEK_CTRL, Keyboard.AEK_TILDE]]} indicates the single 576 gesture of simultaneously pressing Ctrl and ~ on the keyboard device. 577 @type codes: list of list of integer 578 @param description: Description of the task to be shown in command chooser 579 @type description: string 580 @param task_name: Name of the task registered via L{registerTask} to 581 execute when the input gesture is detected on the device 582 @type task_name: string 583 @param propagate: Should the input gesture be allowed to propagate to the 584 OS after we receive it? 585 @type propagate: boolean 586 @raise ValueError: When a task with the given name is not registered. 587 ''' 588 # construct the key list and find the Task with the given name 589 gl = AEInput.GestureList(device, codes) 590 if self.getCommandTask(gl) is not None: 591 # raise a value error if there is already a command registered for this 592 # sequence of keys in this AETier 593 raise ValueError( 594 'command already registered with action codes %s on device %s' % 595 (codes, device.getName())) 596 597 # add task name and description to dictionary used by command chooser 598 if description == None: description = task_name 599 self.command_descriptions[task_name] = description 600 601 # add key list to our dictionary of commands and store the task to execute 602 # as its value 603 self.commands[gl] = (task_name, self.getClassName()) 604 self.tier.addTaskRef(gl, self) 605 if not propagate: 606 # try to add a filter to the device, ignore if not supported 607 try: 608 device.addFilter(gl) 609 except NotImplementedError: 610 pass 611 # accept a KEY_CMD from the device, ignore if not supported 612 try: 613 device.addKeyCmd(codes) 614 except NotImplementedError: 615 pass

616

617 - def registerChooserTask(self, chooser, task_name):

618 ''' 619 Registers a L{chooser_task <chooser_tasks>} with the given name to be 620 executed in response to a change in the given L{AEChooser}. 621 622 @param chooser: Chooser that the task should observe 623 @type chooser: L{AEChooser} 624 @param task_name: Name of a task that should observe the chooser 625 @type task_name: string 626 ''' 627 cid = id(chooser) 628 if self.tier.getChooserTask(cid) is not None: 629 raise ValueError('Chooser Task already registered') 630 self.chooser_tasks[cid] = (task_name, self.getClassName()) 631 self.tier.addTaskRef(cid, self)

632

633 - def bindToEvent(self, task_name, event_kind, focus=False, tier=False, \ 634 background=False, all=False):

635 ''' 636 Bindes a script task to an event type. The type determines which kind of 637 L{AEEvent} will trigger the execution of the L{registered_tasks}. If one or 638 more tasks are already registered for this type, the given task will be 639 inserted at the top of the registered stack of tasks (i.e. it will be 640 executed first for the appropriate event). 641 642 The B{focus}, B{tier}, and B{background} parameters specify on which layer 643 the task will handle events. If B{focus} is C{True}, the task will be 644 executed in response to an event from a focused control within this 645 L{AETier}. If B{tier} is C{True}, the task will be executed in response to 646 an event from an unfocused control within this L{AETier}. If B{background} 647 is C{True}, the task will be executed in response to an event from any 648 control within the tier when the L{AETier} is not active. 649 650 The three layers are mutually exclusive. You may set any combination of 651 focus, tier, and background to C{True} to register the given task on each 652 selected layer in one call. If all three parameters are C{False}, the 653 registration defaults to the focus layer. 654 655 @param task_name: Register the name of task. 656 @type task_name: string 657 @param event_kind: For which event will this task be registered. Use the 658 constants in L{AEConstants.Event <AEConstants.Event.EVENT_TYPE_CARET_CHANGE>} 659 that start with EVENT_TYPE_ to specify the event kind. 660 @type event_kind: int 661 @param focus: Should this task handle events from focused accessibles in 662 this L{AETier}? 663 @type focus: boolean 664 @param tier: Should this task handle events from unfocused accessibles 665 in this L{AETier}? 666 @type tier: boolean 667 @param background: Should this task handle events from any accessible in 668 this L{AETier} when the L{AETier} is inactive? 669 @type background: boolean 670 @param all: This task registers for all layers. 671 @type all: boolean 672 ''' 673 if all: 674 focus = True 675 tier = True 676 background = True 677 678 # default to the focus layer if no layer is specified 679 default = not (focus or tier or background) 680 d = {AEConstants.LAYER_FOCUS : focus or default, 681 AEConstants.LAYER_TIER : tier, 682 AEConstants.LAYER_BACKGROUND : background} 683 684 # opt: inform the AETier of the kind of event that is desired by this Script 685 try: 686 self.tier.setEventInterest(EVENT_KINDS[event_kind], True) 687 except KeyError: 688 # ignore unknown event types, could be internal 689 pass 690 for layer, val in d.items(): 691 if val: 692 # get the list of Task registered for this type and layer or insert an 693 # empty list and get it instead 694 curr = self.event_tasks.setdefault((EVENT_KINDS[event_kind], layer), []) 695 # insert the task at the front of the list 696 curr.insert(0, (task_name, self.getClassName()))

697

698 - def unregisterTask(self, task_name, class_name = None):

699 ''' 700 Unregisters a L{registered_task <registered_tasks>} B{from this L{AEScript} 701 only}. If a task with the given name is not found in this L{AEScript}, an 702 exception is raised. 703 704 @param task_name: Name of the task to unregister. 705 @type task_name: string 706 @param class_name: Name of the script the task is implemented in. If 707 class_name is C{None} this script will be used as class_name. 708 @type class_name: script 709 @raise KeyError: When a task with the given name in the given script is not 710 registered. 711 ''' 712 #build key 713 if class_name == None: 714 class_name = self.getClassName() 715 task_key = (task_name, class_name) 716 717 # get task functions, raises KeyError, if the task is not registered 718 task = self.registered_tasks[task_key] 719 # unbind task from any possible cyclic input tasks 720 for cycle in task[2]: 721 self.unregisterTaskFromCyclicInputTask(cycle[0], task_name, 722 cycle[1], class_name) 723 # unregister task 724 del self.registered_tasks[task_key] 725 self.tier.removeTaskRef(task_key)

726

727 - def unregisterTimerTask(self, task_name, class_name = None):

728 ''' 729 Unregisters a task from being called on a set interval. 730 731 @param task_name: Name of the task to unregister. 732 @type task_name: string 733 @param class_name: Name of the class the task is implemented in. If 734 class_name is C{None} the current script name will be used. 735 @type class_name: string 736 @raise KeyError: When the task is not registered. 737 ''' 738 self.unregisterTask(task_name, class_name)

739

740 - def unregisterCyclicInputTask(self, cycle_name):

741 ''' 742 Unregisters a L{cyclic_input_tasks}. 743 744 @param cycle_name: Name of the cyclic input task. 745 @type cycle_name: string 746 ''' 747 # build key 748 cycle_key = (cycle_name, self.getClassName()) 749 750 try: 751 # remove all tasks from the cyclic input task 752 for task in self.cyclic_input_tasks[cycle_key]: 753 self.unregisterTaskFromCyclicInputTask(cycle_name, task[0], 754 cycle_key[1], task[1]) 755 # delete and unregister cyclic input task 756 del self.cyclic_input_tasks[cycle_key] 757 self.unregisterTask(cycle_name) 758 except KeyError: 759 pass

760

761 - def unregisterTaskFromCyclicInputTask(self, cycle_name, task_name, 762 cycle_script_name = None, 763 task_script_name = None):

764 ''' 765 Unregisters one task from a L{cyclic_input_tasks}. 766 767 @param cycle_name: Name of the cyclic input task. 768 @type cycle_name: string 769 @param task_name: Name of the task that shall be removed from the cyclic 770 input. 771 @type task_name: string 772 @param cycle_script_name: Name of the script, where the cycle input task 773 was registered. If cycle_script_name is C{None} the current script name 774 will be used. 775 @type cycle_script_name: string 776 @param task_script_name: Name of the script, where the task is implemented. 777 If task_script_name is C{None} the current script name will be used. 778 @type task_script_name: string 779 ''' 780 # build keys: 781 if cycle_script_name is None: 782 cycle_script_name = self.getClassName() 783 cycle_key = (cycle_name, cycle_script_name) 784 if task_script_name is None: 785 task_script_name = self.getClassName() 786 task_key = (task_name, task_script_name) 787 788 # try to remove the cylce reference from the task 789 try: 790 task = self.registered_tasks[task_key] 791 task[2].remove(cycle_key) 792 except KeyError: 793 pass 794 795 # try to remove the task from the cycle 796 try: 797 self.cyclic_input_tasks[cycle_key].remove(task_key) 798 except KeyError: pass 799 except ValueError: pass

800

801 - def unregisterCommand(self, device, *codes):

802 ''' 803 Unregisters the L{action codes <commands>} on the given device. 804 805 @param device: Input device to monitor. 806 @type device: L{AEInput} 807 @param codes: List of lists of action codes forming the L{AEInput.Gesture} 808 that will trigger the execution of the registered tasks. For example, 809 C{codes=[[Keyboard.AEK_CTRL, Keyboard.AEK_TILDE]]} indicates the single 810 gesture of simultaneously pressing Ctrl and ~ on the keyboard device. 811 @type codes: list of list of integer 812 @raise KeyError: When a L{AEInput.GestureList} is not registered 813 ''' 814 # GestureList has __eq__ and __hash__ overridden so two different instances 815 # can hash to the same dictionary location as long as their devices and 816 # codes are the same 817 gl = AEInput.GestureList(device, codes) 818 del self.commands[gl] 819 self.tier.removeTaskRef(gl) 820 # try to remove a filter from the device, ignore if not supported 821 try: 822 device.removeFilter(gl) 823 except (NotImplementedError, AttributeError): 824 pass 825 826 # remove an accepted KEY_CMD from the device, ignore if not supported 827 try: 828 device.removeKeyCmd(codes) 829 except NotImplementedError: 830 pass

831

832 - def unregisterChooserTask(self, chooser):

833 ''' 834 Removes the connection between a L{chooser_tasks} and a L{AEChooser} so the 835 task is no longer executed in response to a change in the given AEChooser. 836 837 @param chooser: Chooser that the task should no longer observe. 838 @type chooser: L{AEChooser} 839 @raise KeyError: When the given L{AEChooser} is not registered. 840 ''' 841 cid = id(chooser) 842 task = self.chooser_tasks[cid] 843 del self.chooser_tasks[cid] 844 845 # We don't want to close the Task because technically it's not getting 846 # unregistered, just decoupled from the chooser it was managing. The Task 847 # must stay registered so that the chooser can be invoked again in the 848 # future. 849 850 self.tier.removeTaskRef(cid)

851

852 - def unbindFromEvent(self, task_name, event_kind, focus=False, tier=False, 853 background=False, all=False):

854 ''' 855 Removes the connection between an event_kind and a task. If the 856 given task was not registered for an event in this L{AEScript}, an 857 exception is raised. The B{focus}, B{tier}, and B{background} parameters 858 state from which layer(s) this task should be unregistered. 859 860 @param task_name: Name of the task. 861 @type task_name: string 862 @param event_kind: For which event was this task registered. Use the 863 constants in L{AEConstants.Event <AEConstants.Event.EVENT_TYPE_CARET_CHANGE>} 864 that start with EVENT_TYPE_ to specify the event kind. 865 @type event_kind: int 866 @param focus: Should this task handle events from focused accessibles in 867 this L{AETier}? 868 @type focus: boolean 869 @param tier: Should this task handle events from unfocused accessibles 870 in this L{AETier}? 871 @type tier: boolean 872 @param background: Should this task handle events from any accessible in 873 this L{AETier} when the L{AETier} is inactive? 874 @type background: boolean 875 @param all: This task registers for all layers. 876 @type all: boolean 877 878 @raise KeyError: When there are no tasks registered for the event type on 879 the specified layer. 880 @raise ValueError: When the given task is not registered for the event type 881 on one of the specified layers. 882 @see: L{bindToEvent} 883 ''' 884 if all: 885 focus = True 886 tier = True 887 background = True 888 # default to the focus layer if no layer is specified 889 default = not (focus or tier or background) 890 d = {AEConstants.LAYER_FOCUS : focus or default, 891 AEConstants.LAYER_TIER : tier, 892 AEConstants.LAYER_BACKGROUND : background} 893 894 # opt: inform the AETier of the kind of event that is no longer 895 # desired by this Script 896 try: 897 self.tier.setEventInterest(EVENT_KINDS[event_kind], False) 898 except KeyError: 899 # ignore unknown event types, could be internal 900 pass 901 for layer, val in d.items(): 902 if val: 903 # get the list of Task registered for this type and layer or insert an 904 # empty list and get it instead 905 curr = self.event_tasks[(EVENT_KINDS[event_kind], layer)] 906 curr.remove((task_name, self.getClassName()))

907

908 - def getCommandTask(self, gesture_list):

909 ''' 910 Gets the task registered B{in this L{AEScript} only} to execute in response 911 to the given L{AEInput.GestureList}. 912 913 Called by L{AETier.AETier.getCommandTask} during a search through all 914 L{AEScript}s in the owning L{AETier} for the given key list. 915 916 @param gesture_list: Gestures and device on which they were performed. 917 @type gesture_list: L{AEInput.GestureList} 918 @return: Key of the task set to execute in response to the input 919 gesture or C{None}. 920 @rtype: tuple of string ('task name', 'script name') 921 ''' 922 return self.commands.get(gesture_list)

923

924 - def getChooserTask(self, chooser_key):

925 ''' 926 Gets a L{chooser_tasks} registered to respond to a certain chooser. 927 C{None} is returned if not found. 928 929 Called by L{AETier.getChooserTask <AETier.AETier.getChooserTask>} during a 930 search through all L{AEScript}s in the owning L{AETier} for the given 931 L{AEChooser}. 932 933 @param chooser_key: Unique key identifying the Chooser. 934 @type chooser_key: integer 935 @return: Key to a task set to execute in response to the chooser or C{None}. 936 @rtype: tuple of string ('task name', 'script name') 937 ''' 938 return self.chooser_tasks.get(chooser_key)

939

940 - def getRegisteredTask(self, task_key):

941 ''' 942 Gets the execute and update functions for the task if it is registered 943 B{in this L{AEScript} only}. If no task is registered under the given key in 944 this L{AEScript}, returns C{None}. 945 946 Called by L{AETier.getRegisteredTasks <AETier.AETier.getRegisteredTasks>} 947 during a search through all L{AEScript}s in the owning L{AETier} for the 948 given name. 949 950 @param task_key: Key of the task to locate. 951 @type task_key: tuple of string ('task name', 'script name') 952 @return: List with the task functions. 953 @rtype: list 954 ''' 955 return self.registered_tasks.get(task_key)

956

957 - def getEventTasks(self, event_type, task_layer):

958 ''' 959 Get all tasks registered to handle the given L{AEEvent} type 960 B{in this L{AEScript} only}. 961 962 Called by L{AETier.getEventTasks <AETier.AETier.getEventTasks>} during a 963 search through all L{AEScript}s in the owning L{AETier} for the given task 964 type. 965 966 @param event_type: Desired type of L{AEEvent}. 967 @type event_type: L{AEEvent} class 968 @param task_layer: Layer on which the desired tasks are registered. 969 @type task_layer: integer 970 @return: List of all tasks that handle the given event type on the given 971 layer in this L{AEScript}. 972 @rtype: list of tuple ('task name', 'script name') 973 ''' 974 return list(self.event_tasks.get((event_type, task_layer), []))

975

976 - def getChainSegment(self, link, target, class_name = None):

977 ''' 978 Gets a copy of the segment of the task chain for target specified by the 979 link type. A copy is returned to avoid iteration errors if the list changes 980 size during execution of the tasks in the chain. 981 982 @param link: One of the CHAIN constants in L{AEConstants.API} . 983 @type link: integer 984 @param target: Name of the task to link to. 985 @type target: string 986 @param class_name: name of the class the task is implemented in. 987 @type class_name: string 988 @return: Task names chained in the given manner. 989 @rtype: list of string 990 ''' 991 # build key 992 if class_name == None: 993 class_name = self.getClassName() 994 key = (target, class_name) 995 996 if link == AEConstants.CHAIN_BEFORE: 997 return self.before_chains.get(key, [])[:] 998 elif link == AEConstants.CHAIN_AFTER: 999 return self.after_chains.get(key, [])[:] 1000 elif link == AEConstants.CHAIN_AROUND: 1001 alist = [] 1002 if self.around_chains.has_key(key): 1003 alist.append(self.around_chains[key]) 1004 return alist

1005

1006 - def mergeChain(self, target, before, after, target_class_name = None):

1007 ''' 1008 Adds the before and after segments of the chain for the target specified. 1009 The parameters before and after are lists, possibly containing segments 1010 from other L{AEScript}s. These lists are modified in place for performance. 1011 The around segment is returned since it is a single value. 1012 1013 @param target: Name or key of the task to link to. 1014 @type target: string or tuple of string ('target name', 'script name') 1015 @param target_class_name: Name of the script the task is implemented in 1016 @type target_class_name: string 1017 @param before: List with task keys, that are chained to be executed before 1018 the target 1019 @type before: list with tuple of string [('task name', 'script name')] 1020 @param after: List with task keys, that are chained to be executed after 1021 the target 1022 @type after: list with tuple of string [('task name', 'script name')] 1023 @return: Task name for around link type, or C{None} if nothing is linked 1024 around the target 1025 @rtype: tuple of string ('task name', 'script name') 1026 ''' 1027 # build the right key for the dictionaries 1028 if type(target) is not types.TupleType: 1029 if target_class_name == None: target_class_name = self.getClassName() 1030 key = (target, target_class_name) 1031 else: 1032 key = target 1033 1034 try: 1035 before.extend(self.before_chains[key]) 1036 except KeyError: 1037 pass 1038 try: 1039 after.extend(self.after_chains[key]) 1040 except KeyError: 1041 pass 1042 return self.around_chains.get(key, None)

1043

1044 - def chainTask(self, task_name, link, target, target_class_name = None):

1045 ''' 1046 Links a task to the one named in target. The task will be added either 1047 before, after, or around depending on the value of link. Does not allow a 1048 task to link to itself (i.e. name cannot equal target). 1049 1050 Invokes L{AETier.addChainRef <AETier.AETier.addChainRef>} to add a reference 1051 to this L{AEScript} to the L{AETier} which will later have to traverse the 1052 chain across L{AEScript}s. 1053 1054 Chains the task with the given name to the target task. If link is 1055 CHAIN_BEFORE, the linked task will execute before the target. If link is 1056 CHAIN_AFTER, the linked task will execute after. If link is CHAIN_AROUND, 1057 the linked task will execute in lieu of the target, but can execute the 1058 target manually using L{doTask}. 1059 1060 @param task_name: Name of the task to link. 1061 @type task_name: string 1062 @param link: One of the CHAIN constants in L{AEConstants.API}. 1063 @type link: integer 1064 @param target: Name of the task to link to. 1065 @type target: string 1066 @param target_class_name: Name of the script the target task is implemented 1067 in. If target_class_name is C{None} the current script will be used. 1068 @type target_class_name: string 1069 @raise ValueError: When the link type is unknown. 1070 @raise AssertionError: When the name equals the target. 1071 ''' 1072 differentTasks = False 1073 if (task_name != target): 1074 differentTasks = True 1075 elif (target_class_name is not None and 1076 target_class_name != self.getClassName()): 1077 differentTasks = True 1078 assert differentTasks 1079 1080 if target_class_name == None: 1081 target_class_name = self.getClassName() 1082 key = (target, target_class_name) 1083 value = (task_name, self.getClassName()) 1084 1085 if link == AEConstants.CHAIN_BEFORE: 1086 self.before_chains.setdefault(key, []).append(value) 1087 elif link == AEConstants.CHAIN_AFTER: 1088 self.after_chains.setdefault(key, []).append(value) 1089 elif link == AEConstants.CHAIN_AROUND: 1090 self.around_chains[key] = value 1091 else: 1092 raise ValueError(link) 1093 # add a reference to this Script to the AETier 1094 self.tier.addChainRef(key, self)

1095

1096 - def unchainTask(self, task_name, link, target, target_class_name = None):

1097 ''' 1098 Unlinks a task from the one named in target. The task will be unlinked 1099 either before, after, or around depending on the value of link. If link is 1100 C{None}, the task will be unlinked from all cases if possible. 1101 1102 Invokes L{AETier.removeChainRef <AETier.AETier.removeChainRef>} to delete a 1103 reference to this L{AEScript} to the L{AETier} which will later have to 1104 traverse the chain across L{AEScript}s. 1105 1106 Unchains the task with the given name to the target task. The link parameter 1107 has the same meaning as in L{chainTask}. If link is set to C{None}, one 1108 reference to the named task is removed from the before, after, and around 1109 chains. 1110 1111 @note: The target task must be registered at the time of invocation. 1112 1113 @param task_name: Name of the task to unlink. 1114 @type task_name: string 1115 @param link: One of the CHAIN constants in L{AEConstants.API}. 1116 @type link: integer 1117 @param target: Name of the task to unlink from. 1118 @type target: string 1119 @param target_class_name: Name of the script the target task is implemented 1120 in. If target_class_name is C{None} the current script will be used. 1121 @type target_class_name: string 1122 @raise ValueError: When the named task is not unlinked at least once or the 1123 link type is unknown. 1124 @raise KeyError: When the target task does not have a chain segement in this 1125 L{AEScript} for the given link type. 1126 ''' 1127 if target_class_name == None: 1128 target_class_name = self.getClassName() 1129 key = (target, target_class_name) 1130 value = (task_name, self.getClassName()) 1131 1132 if link is not None: 1133 if link == AEConstants.CHAIN_BEFORE: 1134 self.before_chains[key].remove(value) 1135 if len(self.before_chains[key]) == 0: 1136 del self.before_chains[key] 1137 elif link == AEConstants.CHAIN_AFTER: 1138 self.after_chains[key].remove(value) 1139 if len(self.after_chains[key]) == 0: 1140 del self.after_chains[key] 1141 elif link == AEConstants.CHAIN_AROUND: 1142 # don't unlink around unless it matches 1143 if self.around_chains[key] == value: 1144 del self.around_chains[key] 1145 else: 1146 raise ValueError(value) 1147 else: 1148 raise ValueError(link) 1149 else: 1150 # track how many removals we make 1151 count = 0 1152 # try removing from all chain segments 1153 try: 1154 self.before_chains[key].remove(value) 1155 if len(self.before_chains[key]) == 0: 1156 del self.before_chains[key] 1157 count += 1 1158 except (KeyError, ValueError): 1159 pass 1160 try: 1161 self.after_chains[key].remove(value) 1162 if len(self.after_chains[key]) == 0: 1163 del self.after_chains[key] 1164 count += 1 1165 except (KeyError, ValueError): 1166 pass 1167 try: 1168 if self.around_chains[key] == value: 1169 # there is only one so get rid of key and value 1170 del self.around_chains[key] 1171 count += 1 1172 except (KeyError, ValueError): 1173 pass 1174 1175 if count == 0: 1176 # error if we didn't remove anything 1177 raise ValueError 1178 # remove reference in tier if they are no longer needed 1179 if not self.around_chains.has_key(key) \ 1180 and not self.before_chains.has_key(key) \ 1181 and not self.after_chains.has_key(key) : 1182 self.tier.removeChainRef(key, self)

1183

1184 - def getTaskKeys(self):

1185 ''' 1186 Gets the keys to all tasks registered in this L{AEScript}. 1187 1188 @return: All keys. 1189 @rtype: list of tuple ('task name', 'script name') 1190 ''' 1191 return self.registered_tasks.keys()

1192

1193 - def unregisterModifiers(self, dev, modifiers):

1194 ''' 1195 Unregisters a list of input modifiers. Ignores the error cases when the 1196 device has no registered modifiers or one of the given modifiers is not 1197 registered. 1198 1199 @param dev: An L{AEInput} device. 1200 @type dev: L{AEInput} 1201 @param modifiers: A list of key codes used as modifiers. 1202 @type modifiers: integer 1203 ''' 1204 for m in modifiers: 1205 try: 1206 self.registered_modifiers[dev].remove(m) 1207 except (KeyError, ValueError): 1208 pass

1209

1210 - def registerModifiers(self, dev, modifiers):

1211 ''' 1212 Registers a list of input modifiers. 1213 1214 @param dev: An L{AEInput} device. 1215 @type dev: L{AEInput} 1216 @param modifiers: A list of key codes used as modifiers. 1217 @type modifiers: integer 1218 ''' 1219 self.registered_modifiers.setdefault(dev, []).extend(modifiers)

1220

1221 - def doTask(self, task_name_to_do, task_script_to_do=None, propagate=True, 1222 chain=True, **kwargs):

1223 ''' 1224 Immediately executes a task registered under the given name in this 1225 L{AETier}. Keyword arguments for task execution may be provided. The 1226 L{AEPor <AEPor.AEPor>} of this task is always provided to the task being 1227 executed and this task's L{AEPor <AEPor.AEPor>} is updated with the value of 1228 the pointer after the other task has finished execution. 1229 1230 The chain parameter dictates whether only the L{registered_tasks} is 1231 executed (C{False}), or if all other tasks chained to it are as well 1232 (C{True}). The propagate parameter determines whether the execute or update 1233 method is called on the task. This param is not typically specified by a 1234 task or L{AEScript}. It is used internally by a L{cyclic_input_tasks} to 1235 handle the propagation flag in task chains. 1236 1237 @param task_name_to_do: Name of the task to execute 1238 @type task_name_to_do: string 1239 @param task_script_to_do: name of the script the task is implemented in 1240 @type task_script_to_do: string 1241 @param chain: Execute all tasks chained to the one named or just the 1242 one named? 1243 @type chain: boolean 1244 @param propagate: Should chained tasks be executed (C{True}) or updated 1245 (C{False})? 1246 @type propagate: boolean 1247 @param kwargs: Arbitrary keyword arguments to pass to the task, some of 1248 which may be required, others which may be optional, and others which 1249 may be completely ignored 1250 @type kwargs: dictionary 1251 ''' 1252 # build key 1253 if task_script_to_do == None: 1254 task_script_to_do = self.getClassName() 1255 key = (task_name_to_do, task_script_to_do) 1256 1257 # update keyword argument 'task_name' 1258 kwargs['task_name'] = task_name_to_do 1259 try: 1260 por = kwargs['por'] 1261 except KeyError: 1262 por = None 1263 try: 1264 layer = kwargs['layer'] 1265 except KeyError: 1266 layer = None 1267 # execute the task 1268 self.tier.manageChain(por, layer, key, kwargs, propagate, chain)

1269

1270 - def doCyclicInputTask(self, **kwargs):

1271 ''' 1272 Executes the next task which is connected to the L{cyclic_input_tasks}. 1273 1274 @param kwargs: Arbitrary keyword arguments to pass to the task, some of 1275 which may be required, others which may be optional, and others which 1276 may be completely ignored. 1277 @type kwargs: dictionary 1278 1279 @raise KeyError: When the cycle input task is not registered as such. 1280 @raise LookupError: When the task list for the cyclic input task is empty. 1281 @note: KeyError inherits LookupError 1282 ''' 1283 # build key for the cyclic input task 1284 cycle_key = (kwargs['task_name'], self.getClassName()) 1285 1286 # try to get the task list for this cyclic input task 1287 # if the cyclic input task is not found an KeyError will be raised 1288 cycle_task_list = self.cyclic_input_tasks[cycle_key] 1289 1290 # get the number of tasks connected to the cyclic input task 1291 if len(cycle_task_list) is 0: 1292 raise LookupError 1293 1294 # find the next task that shall be executed 1295 i = kwargs['cycle_count'] % len(cycle_task_list) 1296 task_to_do_key = cycle_task_list[i] 1297 self.doTask(task_to_do_key[0], task_to_do_key[1], **kwargs)

1298

1299 - def getScriptSetting(self, setting_name):

1300 ''' 1301 Gets the L{AEScript} L{AEState.Setting} variable with the given name. 1302 1303 This method should be used when a script wants to access its own settings. 1304 If a script needs to access the settings of another script use the 1305 L{System.getScriptSetting 1306 <AccessEngine.AccessEngineAPI.System.getScriptSetting>} method. 1307 1308 @param setting_name: Name of the script 1309 @type setting_name: immutable 1310 @return: L{Setting} object for given script. 1311 @rtype: object 1312 ''' 1313 return self.state.getSettingObj(setting_name)

1314

1315 - def getScriptSettingVal(self, setting_name):

1316 ''' 1317 Gets the value of the L{AEScript} L{AEState.Setting} state variable with the 1318 given name. 1319 1320 This method should be used when a script wants to access its own settings. 1321 If a script needs to access the settings of another script use the 1322 L{System.getScriptSettingVal 1323 <AccessEngine.AccessEngineAPI.System.getScriptSettingVal>} method. 1324 1325 @param setting_name: Name of the script. 1326 @type setting_name: immutable 1327 @return: Value contained in L{AEState} attribute with given name. 1328 @rtype: object 1329 ''' 1330 return self.state.getSettingVal(setting_name)

1331

1332 - def setScriptSettingVal(self, setting_name, value):

1333 ''' 1334 Sets the value of the L{AEScript} L{AEState.Setting} state variable with the 1335 given name. 1336 1337 This method should be used when a script wants to set its own settings. 1338 If a script needs to set the settings of another script use the 1339 L{System.setScriptSettingVal 1340 <AccessEngine.AccessEngineAPI.System.setScriptSettingVal>} method. 1341 1342 @param setting_name: Name of the script. 1343 @type setting_name: immutable 1344 @param value: Value contained in L{AEState} attribute with given name. 1345 @type value: object 1346 @raise KeyError: When the L{AEScript} is not found 1347 ''' 1348 self.state.setSettingVal(setting_name, value)

1349

1350 - def getAnchorTaskId(self):

1351 ''' 1352 Gets the identity of the task. 1353 ''' 1354 try: 1355 return self.tier.getAnchor()[0] 1356 except TypeError: 1357 return None

1358

1359 - def getAnchorScriptClassName(self):

1360 ''' 1361 Gets the class name of the L{AEScript}. 1362 ''' 1363 try: 1364 return self.tier.getAnchor()[1] 1365 except TypeError: 1366 return None

1367 1368

1369 -class EventScript(AEScript):

1370 ''' 1371 The EventScript class expands the L{AEScript} class with methods, which are 1372 ment as a framework for the possible events. When a script needs to respond to 1373 a certain event, it should implement the appropriate method. 1374 ''' 1375

1376 - def registerEventTask(self, task_name, event_kind, focus=False, tier=False, \ 1377 background=False, all=False):

1378 ''' 1379 Registers a task as an L{event task <event_tasks>}. 1380 1381 @note: This method calls the L{registerTask} and L{bindToEvent} methods. 1382 1383 The type determines which kind of L{AEEvent} will trigger the execution of 1384 the registered task. If one or more tasks are already registered for this 1385 type, the given task will be inserted at the top of the registered stack of 1386 tasks (i.e. it will be executed first for the appropriate event). 1387 1388 The B{focus}, B{tier}, and B{background} parameters specify on which layer 1389 the task will handle events. If B{focus} is C{True}, the task will be 1390 executed in response to an event from a focused control within this 1391 L{AETier}. If B{tier} is C{True}, the task will be executed in response to 1392 an event from an unfocused control within this L{AETier}. If B{background} 1393 is C{True}, the task will be executed in response to an event from any 1394 control within the tier when the L{AETier} is not active. 1395 1396 The three layers are mutually exclusive. You may set any combination of 1397 B{focus}, B{tier}, and B{background} to C{True} to register the given task 1398 on each selected layer in one call. If all three parameters are C{False}, 1399 the registration defaults to the focus layer. 1400 1401 @param task_name: Register the name of task. 1402 @type task_name: string 1403 @param event_kind: For which event will this task be registered. Use the 1404 constants in L{AEConstants.Event <AEConstants.Event.EVENT_TYPE_CARET_CHANGE>} 1405 that start with EVENT_TYPE_ to specify the event kind. 1406 @type event_kind: int 1407 @param focus: Should this task handle events from focused accessibles in 1408 this L{AETier}? 1409 @type focus: boolean 1410 @param tier: Should this task handle events from unfocused accessibles 1411 in this L{AETier}? 1412 @type tier: boolean 1413 @param background: Should this task handle events from any accessible in 1414 this L{AETier} when the L{AETier} is inactive? 1415 @type background: boolean 1416 @param all: This task registers for all layers 1417 @type all: boolean 1418 ''' 1419 exec_func = None 1420 update_func = None 1421 if event_kind == AEConstants.EVENT_TYPE_CARET_CHANGE: 1422 exec_func = self.onCaretChange 1423 update_func = self.updateOnCaretChange 1424 elif event_kind == AEConstants.EVENT_TYPE_CHILDREN_CHANGE: 1425 exec_func = self.onChildrenChange 1426 update_func = self.updateOnChildrenChange 1427 elif event_kind == AEConstants.EVENT_TYPE_FOCUS_CHANGE: 1428 exec_func = self.onFocusChange 1429 update_func = self.updateOnFocusChange 1430 elif event_kind == AEConstants.EVENT_TYPE_MOUSE_CHANGE: 1431 exec_func = self.onMouseChange 1432 update_func = self.updateOnMouseChange 1433 elif event_kind == AEConstants.EVENT_TYPE_PROPERTY_CHANGE: 1434 exec_func = self.onPropertyChange 1435 update_func = self.updateOnPropertyChange 1436 elif event_kind == AEConstants.EVENT_TYPE_SCREEN_CHANGE: 1437 exec_func = self.onScreenChange 1438 update_func = self.updateOnScreenChange 1439 elif event_kind == AEConstants.EVENT_TYPE_SELECTOR_CHANGE: 1440 exec_func = self.onSelectorChange 1441 update_func = self.updateOnSelectorChange 1442 elif event_kind == AEConstants.EVENT_TYPE_STATE_CHANGE: 1443 exec_func = self.onStateChange 1444 update_func = self.updateOnStateChange 1445 elif event_kind == AEConstants.EVENT_TYPE_TABLE_CHANGE: 1446 exec_func = self.onTableChange 1447 update_func = self.updateOnTableChange 1448 elif event_kind == AEConstants.EVENT_TYPE_VIEW_CHANGE: 1449 exec_func = self.onViewChange 1450 update_func = self.updateOnViewChange 1451 1452 if exec_func == None: 1453 return 1454 1455 self.registerTask(task_name, exec_func, update_func) 1456 self.bindToEvent(task_name, event_kind, focus, tier, background, all)

1457

1458 - def unregisterEventTask(self, task_name, event_kind, class_name=None, \ 1459 focus=False, tier=False, background=False, all=False):

1460 ''' 1461 Unregisters an L{event task <event_tasks>}. 1462 1463 @note: calls the L{unbindFromEvent} and L{unregisterTask} methods. 1464 1465 @param task_name: Name of the task. 1466 @type task_name: string 1467 @param event_kind: For which event was this task registered. Use the 1468 constants in L{AEConstants.Event <AEConstants.Event.EVENT_TYPE_CARET_CHANGE>} 1469 that start with EVENT_TYPE_ to specify the event kind. 1470 @type event_kind: int 1471 @param class_name: Name of the script the task is implemented in. If 1472 class_name is C{None} this script will be used as class_name. 1473 @type class_name: script 1474 @param focus: Should this task handle events from focused accessibles in 1475 this L{AETier}? 1476 @type focus: boolean 1477 @param tier: Should this task handle events from unfocused accessibles 1478 in this L{AETier}? 1479 @type tier: boolean 1480 @param background: Should this task handle events from any accessible in 1481 this L{AETier} when the L{AETier} is inactive? 1482 @type background: boolean 1483 @param all: This task registers for all layers. 1484 @type all: boolean 1485 1486 @raise KeyError: When a task with the given name in the given script is not 1487 registered 1488 @raise KeyError: When there are no tasks registered for the event type on 1489 the specified layer 1490 @raise ValueError: When the given task is not registered for the event type 1491 on one of the specified layers 1492 ''' 1493 self.unbindFromEvent(task_name, event_kind, focus, tier, background, all) 1494 self.unregisterTask(task_name, class_name)

1495 1496 ######################################### 1497 ## AEConstants.EVENT_TYPE_CARET_CHANGE ## 1498 #########################################

1499 - def updateOnCaretChange(self, **kwargs):

1500 ''' 1501 Updates this L{EventScript} in response to a consumed caret change event. 1502 Called by L{AETier._executeTask <AETier.AETier._executeTask>}. 1503 1504 This method should be implemented if it's needed. 1505 1506 @param kwargs: Arbitrary data given by the observer. 1507 @type kwargs: dictionary 1508 1509 @keyword por: Point of regard for the related accessible. 1510 @type por: L{AEPor <AEPor.AEPor>} 1511 @keyword layer: Layer on which the event occurred. 1512 @type layer: integer 1513 @keyword text: The text inserted, deleted or the line of the caret 1514 @type text: string 1515 @keyword text_offset: The offset of the inserted/deleted text or the 1516 absolute offset when movement only 1517 @type text_offset: integer 1518 @keyword added: C{True} when text added, C{False} when text deleted, 1519 and C{None} (the default) when event is for caret movement only 1520 @type added: boolean 1521 ''' 1522 pass

1523

1524 - def onCaretChange(self, **kwargs):

1525 ''' 1526 Executes this L{EventScript} in response to a caret change event. Called by 1527 L{AETier._executeTask <AETier.AETier._executeTask>}. 1528 1529 @param kwargs: Arbitrary data given by the observer. 1530 @type kwargs: dictionary 1531 1532 @keyword por: Point of regard for the related accessible. 1533 @type por: L{AEPor <AEPor.AEPor>} 1534 @keyword layer: Layer on which the event occurred. 1535 @type layer: integer 1536 @keyword task_name: Name of the task this function executes. 1537 @type task_name: string 1538 @keyword text: The text inserted, deleted or the line of the caret 1539 @type text: string 1540 @keyword text_offset: The offset of the inserted/deleted text or the 1541 absolute offset when movement only 1542 @type text_offset: integer 1543 @keyword added: C{True} when text added, C{False} when text deleted, and 1544 C{None} (the default) when event is for caret movement only 1545 @type added: boolean 1546 1547 @return: C{True} to allow other task to process this event 1548 @rtype: boolean 1549 ''' 1550 added = kwargs['added'] 1551 if added is None: 1552 return self.onCaretMoved(**kwargs) 1553 elif added: 1554 return self.onCaretInserted(**kwargs) 1555 else: 1556 return self.onCaretDeleted(**kwargs)

1557

1558 - def onCaretInserted(self, **kwargs):

1559 ''' 1560 Executes this L{EventScript} in response to a caret insert event. Called by 1561 L{onCaretChange}. 1562 1563 @param kwargs: Arbitrary data given by the observer. 1564 @type kwargs: dictionary 1565 @keyword por: Point of regard for the related accessible 1566 @type por: L{AEPor <AEPor.AEPor>} 1567 @keyword layer: Layer on which the event occurred 1568 @type layer: integer 1569 @keyword task_name: Name of the task this function executes. 1570 @type task_name: string 1571 @keyword text: The text inserted. 1572 @type text: string 1573 @keyword text_offset: The offset of the inserted text 1574 @type text_offset: integer 1575 @keyword added: C{True} when text added 1576 @type added: boolean 1577 1578 @return: C{True} to allow other tasks to process this event 1579 @rtype: boolean 1580 ''' 1581 return True

1582

1583 - def onCaretMoved(self, **kwargs):

1584 ''' 1585 Executes this L{EventScript} in response to a caret movement event. Called 1586 by L{onCaretChange}. 1587 1588 @param kwargs: Arbitrary data given by the observer. 1589 @type kwargs: dictionary 1590 1591 @keyword por: Point of regard for the related accessible. 1592 @type por: L{AEPor <AEPor.AEPor>} 1593 @keyword layer: Layer on which the event occurred. 1594 @type layer: integer 1595 @keyword task_name: Name of the task this function executes. 1596 @type task_name: string 1597 @keyword text: The text line of the caret. 1598 @type text: string 1599 @keyword text_offset: The absolute offset 1600 @type text_offset: integer 1601 @keyword added: C{None} (the default) when event is for caret movement 1602 @type added: boolean 1603 1604 @return: C{True} to allow other tasks to process this event 1605 @rtype: boolean 1606 ''' 1607 return True

1608

1609 - def onCaretDeleted(self, **kwargs):

1610 ''' 1611 Executes this L{EventScript} in response to a caret delete event. Called by 1612 L{onCaretChange}. 1613 1614 @param kwargs: Arbitrary data given by the observer. 1615 @type kwargs: dictionary 1616 1617 @keyword por: Point of regard for the related accessible. 1618 @type por: L{AEPor <AEPor.AEPor>} 1619 @keyword layer: Layer on which the event occurred. 1620 @type layer: integer 1621 @keyword task_name: Name of the task this function executes. 1622 @type task_name: string 1623 @keyword text: The text deleted or the line of the caret. 1624 @type text: string 1625 @keyword text_offset: The offset of the deleted text. 1626 @type text_offset: integer 1627 @keyword added: C{False} when text deleted. 1628 @type added: boolean 1629 1630 @return: C{True} to allow other tasks to process this event 1631 @rtype: boolean 1632 ''' 1633 return True

1634 1635 ############################################ 1636 ## AEConstants.EVENT_TYPE_CHILDREN_CHANGE ## 1637 ############################################

1638 - def updateOnChildrenChange(self, **kwargs):

1639 ''' 1640 Updates this L{EventScript} in response to a consumed children change event. 1641 Called by L{AETier._executeTask <AETier.AETier._executeTask>}. 1642 1643 @param kwargs: Arbitrary data given by the observer. 1644 @type kwargs: dictionary 1645 1646 @keyword por: Point of regard for the related accessible. 1647 @type por: L{AEPor <AEPor.AEPor>} 1648 @keyword layer: Layer on which the event occurred. 1649 @type layer: integer 1650 @keyword task_name: Name of the task this function executes. 1651 @type task_name: string 1652 @keyword added: C{True} when a child is added, C{False} when removed. 1653 @type added: boolean 1654 @keyword child_por: The L{AEPor <AEPor.AEPor>} of added/removed child. 1655 @type child_por: L{AEPor <AEPor.AEPor>} 1656 ''' 1657 pass

1658

1659 - def onChildrenChange(self, **kwargs):

1660 ''' 1661 Executes this L{EventScript} in response to a children change event. Called 1662 by L{AETier._executeTask <AETier.AETier._executeTask>}. 1663 1664 @param kwargs: Arbitrary data given by the observer. 1665 @type kwargs: dictionary 1666 1667 @keyword por: Point of regard for the related accessible. 1668 @type por: L{AEPor <AEPor.AEPor>} 1669 @keyword layer: Layer on which the event occurred. 1670 @type layer: integer 1671 @keyword task_name: Name of the task this function executes. 1672 @type task_name: string 1673 @keyword added: C{True} when a child is added, C{False} when removed. 1674 @type added: boolean 1675 @keyword child_por: The L{AEPor <AEPor.AEPor>} of added/removed child 1676 @type child_por: L{AEPor <AEPor.AEPor>} 1677 1678 @return: C{True} to allow other tasks to process this event 1679 @rtype: boolean 1680 ''' 1681 added = kwargs['added'] 1682 if added == True: 1683 return self.onChildAdded(**kwargs) 1684 else: 1685 return self.onChildRemoved(**kwargs)

1686

1687 - def onChildAdded(self, **kwargs):

1688 ''' 1689 Executes this L{EventScript} in response to a ChildrenChange-added event. 1690 Called by L{onChildrenChange}. 1691 1692 @param kwargs: Arbitrary data given by the observer. 1693 @type kwargs: dictionary 1694 1695 @keyword por: Point of regard for the related accessible. 1696 @type por: L{AEPor <AEPor.AEPor>} 1697 @keyword layer: Layer on which the event occurred. 1698 @type layer: integer 1699 @keyword task_name: Name of the task this function executes. 1700 @type task_name: string 1701 @keyword added: C{True} when a child is added 1702 @type added: boolean 1703 @keyword child_por: The L{AEPor <AEPor.AEPor>} of added child 1704 @type child_por: L{AEPor <AEPor.AEPor>} 1705 1706 @return: C{True} to allow other tasks to process this event 1707 @rtype: boolean 1708 ''' 1709 return True

1710

1711 - def onChildRemoved(self, **kwargs):

1712 ''' 1713 Executes this L{EventScript} in response to a ChildrenChange-removed event. 1714 Called by L{onChildrenChange}. 1715 1716 @param kwargs: Arbitrary data given by the observer. 1717 @type kwargs: dictionary 1718 1719 @keyword por: Point of regard for the related accessible 1720 @type por: L{AEPor <AEPor.AEPor>} 1721 @keyword layer: Layer on which the event occurred. 1722 @type layer: integer 1723 @keyword task_name: Name of the task this function executes. 1724 @type task_name: string 1725 @keyword added: C{False} when a child removed. 1726 @type added: boolean 1727 @keyword child_por: The L{AEPor <AEPor.AEPor>} of added/removed child 1728 @type child_por: L{AEPor <AEPor.AEPor>} 1729 1730 @return: C{True} to allow other tasks to process this event 1731 @rtype: boolean 1732 ''' 1733 return True

1734 1735 ######################################### 1736 ## AEConstants.EVENT_TYPE_FOCUS_CHANGE ## 1737 #########################################

1738 - def updateOnFocusChange(self, **kwargs):

1739 ''' 1740 Updates this L{EventScript} in response to a consumed focus change event. 1741 Called by L{AETier._executeTask <AETier.AETier._executeTask>}. 1742 1743 @param kwargs: Arbitrary data given by the observer. 1744 @type kwargs: dictionary 1745 1746 @keyword por: Point of regard related at which the event occurred 1747 @type por: L{AEPor <AEPor.AEPor>} 1748 @keyword layer: Layer on which the event occurred. 1749 @type layer: integer 1750 @keyword task_name: Name of the task this function executes. 1751 @type task_name: string 1752 @keyword gained: C{True} when a focus gained or C{False} when focus lost. 1753 @type gained: boolean 1754 ''' 1755 pass

1756

1757 - def onFocusChange(self, **kwargs):

1758 ''' 1759 Executes this L{EventScript} in response to a focus change event. Called by 1760 L{AETier._executeTask <AETier.AETier._executeTask>}. 1761 1762 @param kwargs: Arbitrary data given by the observer. 1763 @type kwargs: dictionary 1764 1765 @keyword por: Point of regard related at which the event occurred. 1766 @type por: L{AEPor <AEPor.AEPor>} 1767 @keyword layer: Layer on which the event occurred. 1768 @type layer: integer 1769 @keyword task_name: Name of the task this function executes. 1770 @type task_name: string 1771 @keyword gained: C{True} when focus gained or C{False} when focus lost. 1772 @type gained: boolean 1773 1774 @return: C{True} to allow other tasks to process this event 1775 @rtype: boolean 1776 ''' 1777 if kwargs['gained']: 1778 return self.onFocusGained(**kwargs) 1779 else: 1780 return self.onFocusLost(**kwargs)

1781

1782 - def onFocusGained(self, **kwargs):

1783 ''' 1784 Executes this L{EventScript} in response to a focus gained event. Called by 1785 L{onFocusChange}. 1786 1787 @param kwargs: Arbitrary data given by the observer. 1788 @type kwargs: dictionary 1789 1790 @keyword por: Point of regard related at which the event occurred. 1791 @type por: L{AEPor <AEPor.AEPor>} 1792 @keyword layer: Layer on which the event occurred. 1793 @type layer: integer 1794 @keyword task_name: Name of the task this function executes. 1795 @type task_name: string 1796 @keyword gained: C{True} when focus gained. 1797 @type gained: boolean 1798 1799 @return: C{True} to allow other tasks to process this event 1800 @rtype: boolean 1801 ''' 1802 return True

1803

1804 - def onFocusLost(self, **kwargs):

1805 ''' 1806 Executes this L{EventScript} in response to a focus lost event. Called by 1807 L{onFocusChange}. 1808 1809 @param kwargs: Arbitrary data given by the observer. 1810 @type kwargs: dictionary 1811 1812 @keyword por: Point of regard related at which the event occurred. 1813 @type por: L{AEPor <AEPor.AEPor>} 1814 @keyword layer: Layer on which the event occurred. 1815 @type layer: integer 1816 @keyword task_name: Name of the task this function executes. 1817 @type task_name: string 1818 @keyword gained: C{False} when focus lost. 1819 @type gained: boolean 1820 1821 @return: C{True} to allow other tasks to process this event 1822 @rtype: boolean 1823 ''' 1824 return True

1825 1826 ######################################### 1827 ## AEConstants.EVENT_TYPE_MOUSE_CHANGE ## 1828 #########################################

1829 - def updateOnMouseChange(self, **kwargs):

1830 ''' 1831 Updates this L{EventScript} in response to a consumed mouse event. Called by 1832 L{AETier._executeTask <AETier.AETier._executeTask>}. 1833 1834 @param kwargs: Arbitrary data given by the observer. 1835 @type kwargs: dictionary 1836 1837 @keyword por: Point of regard related at which the event occurred. 1838 @type por: L{AEPor <AEPor.AEPor>} 1839 @keyword layer: Layer on which the event occurred. 1840 @type layer: integer 1841 @keyword task_name: Name of the task this function executes. 1842 @type task_name: string 1843 @keyword kind: Kind of event. 1844 @type kind: integer 1845 @keyword pos: Absolute position of the mouse pointer. 1846 @type pos: 2-tuple of integer 1847 @keyword button: Number of the button pressed. 1848 @type button: integer 1849 ''' 1850 pass

1851

1852 - def onMouseChange(self, **kwargs):

1853 ''' 1854 Executes this L{EventScript} in response to a mouse event. Called by 1855 L{AETier._executeTask <AETier.AETier._executeTask>}. 1856 1857 @param kwargs: Arbitrary data given by the observer. 1858 @type kwargs: dictionary 1859 1860 @keyword por: Point of regard related at which the event occurred. 1861 @type por: L{AEPor <AEPor.AEPor>} 1862 @keyword layer: Layer on which the event occurred. 1863 @type layer: integer 1864 @keyword task_name: Name of the task this function executes. 1865 @type task_name: string 1866 @keyword kind: Kind of event. 1867 @type kind: integer 1868 @keyword pos: Absolute position of the mouse pointer. 1869 @type pos: 2-tuple of integer 1870 @keyword button: Number of the button pressed. 1871 @type button: integer 1872 1873 @return: C{True} to allow other tasks to process this event. 1874 @rtype: boolean 1875 ''' 1876 kind = kwargs['kind'] 1877 if kind == AEConstants.EVENT_MOUSE_MOVE: 1878 return self.onMouseMoved(**kwargs) 1879 elif kind == AEConstants.EVENT_MOUSE_PRESS: 1880 return self.onMousePressed(**kwargs) 1881 else: 1882 return self.onMouseReleased(**kwargs)

1883

1884 - def onMouseMoved(self, **kwargs):

1885 ''' 1886 Executes this L{EventScript} in response to a mouse movement. Called by 1887 L{onMouseChange}. 1888 1889 @param kwargs: Arbitrary data given by the observer. 1890 @type kwargs: dictionary 1891 1892 @keyword por: Point of regard related at which the event occurred. 1893 @type por: L{AEPor <AEPor.AEPor>} 1894 @keyword layer: Layer on which the event occurred. 1895 @type layer: integer 1896 @keyword task_name: Name of the task this function executes. 1897 @type task_name: string 1898 @keyword kind: Kind of event. 1899 @type kind: integer 1900 @keyword pos: Absolute position of the mouse pointer. 1901 @type pos: 2-tuple of integer 1902 @keyword button: Number of the button pressed. 1903 @type button: integer 1904 1905 @return: C{True} to allow other tasks to process this event 1906 @rtype: boolean 1907 ''' 1908 return True

1909

1910 - def onMousePressed(self, **kwargs):

1911 ''' 1912 Executes this L{EventScript} in response to a mouse button press. Called by 1913 L{onMouseChange}. 1914 1915 @param kwargs: Arbitrary data given by the observer. 1916 @type kwargs: dictionary 1917 1918 @keyword por: Point of regard related at which the event occurred. 1919 @type por: L{AEPor <AEPor.AEPor>} 1920 @keyword layer: Layer on which the event occurred. 1921 @type layer: integer 1922 @keyword task_name: Name of the task this function executes. 1923 @type task_name: string 1924 @keyword kind: Kind of event. 1925 @type kind: integer 1926 @keyword pos: Absolute position of the mouse pointer. 1927 @type pos: 2-tuple of integer 1928 @keyword button: Number of the button pressed. 1929 @type button: integer 1930 1931 @return: C{True} to allow other tasks to process this event 1932 @rtype: boolean 1933 ''' 1934 return True

1935

1936 - def onMouseReleased(self, **kwargs):

1937 ''' 1938 Executes this L{EventScript} in response to a mouse button release. Called 1939 by L{onMouseChange}. 1940 1941 @param kwargs: Arbitrary data given by the observer. 1942 @type kwargs: dictionary 1943 1944 @keyword por: Point of regard related at which the event occurred. 1945 @type por: L{AEPor <AEPor.AEPor>} 1946 @keyword layer: Layer on which the event occurred. 1947 @type layer: integer 1948 @keyword task_name: Name of the task this function executes. 1949 @type task_name: string 1950 @keyword kind: Kind of event. 1951 @type kind: integer 1952 @keyword pos: Absolute position of the mouse pointer. 1953 @type pos: 2-tuple of integer 1954 @keyword button: Number of the button pressed. 1955 @type button: integer 1956 1957 @return: C{True} to allow other tasks to process this event. 1958 @rtype: boolean 1959 ''' 1960 return True

1961 ############################################ 1962 ## AEConstants.EVENT_TYPE_PROPERTY_CHANGE ## 1963 ############################################

1964 - def updateOnPropertyChange(self, **kwargs):

1965 ''' 1966 Updates this L{EventScript} in response to a consumed property change event. 1967 Called by L{AETier._executeTask <AETier.AETier._executeTask>}. 1968 1969 @param kwargs: Arbitrary data given by the observer. 1970 @type kwargs: dictionary 1971 1972 @keyword por: Point of regard for the related accessible. 1973 @type por: L{AEPor <AEPor.AEPor>} 1974 @keyword layer: Layer on which the event occurred. 1975 @type layer: integer 1976 @keyword task_name: Name of the task this function executes. 1977 @type task_name: string 1978 @keyword name: Name of the property that changed. 1979 @type name: string 1980 @keyword value: New value of the property. 1981 @type value: string or number 1982 ''' 1983 pass

1984

1985 - def onPropertyChange(self, **kwargs):

1986 ''' 1987 Executes this L{EventScript} in response to a property change event. Called 1988 by L{AETier._executeTask <AETier.AETier._executeTask>}. 1989 1990 @param kwargs: Arbitrary data given by the observer. 1991 @type kwargs: dictionary 1992 1993 @keyword por: Point of regard for the related accessible. 1994 @type por: L{AEPor <AEPor.AEPor>} 1995 @keyword layer: Layer on which the event occurred. 1996 @type layer: integer 1997 @keyword task_name: Name of the task this function executes. 1998 @type task_name: string 1999 @keyword name: Name of the property that changed. 2000 @type name: string 2001 @keyword value: New value of the property. 2002 @type value: string or number 2003 2004 @return: C{True} to allow other tasks to process this event 2005 @rtype: boolean 2006 ''' 2007 return True

2008 ########################################## 2009 ## AEConstants.EVENT_TYPE_SCREEN_CHANGE ## 2010 ##########################################

2011 - def updateOnScreenChange(self, **kwargs):

2012 ''' 2013 Updates this L{EventScript} in response to a consumed screen change event. 2014 Called by L{AETier._executeTask <AETier.AETier._executeTask>}. 2015 2016 @param kwargs: Arbitrary data given by the observer. 2017 @type kwargs: dictionary 2018 2019 @keyword por: Point of regard for the related accessible. 2020 @type por: L{AEPor <AEPor.AEPor>} 2021 @keyword layer: Layer on which the event occurred. 2022 @type layer: integer 2023 @keyword task_name: Name of the task this function executes. 2024 @type task_name: string 2025 @keyword kind: Indicates the kind of selection event. 2026 @type kind: integer 2027 ''' 2028 pass

2029

2030 - def onScreenChange(self, **kwargs):

2031 ''' 2032 Executes this L{EventScript} in response to a screen change event. Called by 2033 L{AETier._executeTask <AETier.AETier._executeTask>}. 2034 2035 @param kwargs: Arbitrary data given by the observer. 2036 @type kwargs: dictionary 2037 2038 @keyword por: Point of regard for the related accessible. 2039 @type por: L{AEPor <AEPor.AEPor>} 2040 @keyword layer: Layer on which the event occurred. 2041 @type layer: integer 2042 @keyword task_name: Name of the task this function executes. 2043 @type task_name: string 2044 @keyword kind: Indicates the kind of selection event. 2045 @type kind: integer 2046 2047 @return: C{True} to allow other tasks to process this event 2048 @rtype: boolean 2049 ''' 2050 kind = kwargs['kind'] 2051 if kind == AEConstants.SCREEN_OBJECT_BOUNDS: 2052 return self.onScreenResized(**kwargs) 2053 elif kind == AEConstants.SCREEN_TEXT_BOUNDS: 2054 return self.onScreenReflowed(**kwargs) 2055 else: 2056 return self.onScreenRefreshed(**kwargs)

2057

2058 - def onScreenResized(self, **kwargs):

2059 ''' 2060 Executes this L{EventScript} in response to a change in the bounds of an 2061 object. Called by L{onScreenChange}. 2062 2063 @param kwargs: Arbitrary data given by the observer. 2064 @type kwargs: dictionary 2065 2066 @keyword por: Point of regard for the related accessible. 2067 @type por: L{AEPor <AEPor.AEPor>} 2068 @keyword layer: Layer on which the event occurred. 2069 @type layer: integer 2070 @keyword task_name: Name of the task this function executes. 2071 @type task_name: string 2072 @keyword kind: Indicates the kind of selection event. 2073 @type kind: integer 2074 2075 @return: C{True} to allow other tasks to process this event. 2076 @rtype: boolean 2077 ''' 2078 return True

2079

2080 - def onScreenReflowed(self, **kwargs):

2081 ''' 2082 Executes this L{EventScript} in response to a change in the bounds of a body 2083 of text. Called by L{onScreenChange}. 2084 2085 @param kwargs: Arbitrary data given by the observer. 2086 @type kwargs: dictionary 2087 2088 @keyword por: Point of regard for the related accessible. 2089 @type por: L{AEPor <AEPor.AEPor>} 2090 @keyword layer: Layer on which the event occurred. 2091 @type layer: integer 2092 @keyword task_name: Name of the task this function executes. 2093 @type task_name: string 2094 @keyword kind: Indicates the kind of selection event. 2095 @type kind: integer 2096 2097 @return: C{True} to allow other tasks to process this event. 2098 @rtype: boolean 2099 ''' 2100 return True

2101

2102 - def onScreenRefreshed(self, **kwargs):

2103 ''' 2104 Executes this L{EventScript} in response to a change in the visible data on 2105 an object. Called by L{onScreenChange}. 2106 2107 @param kwargs: Arbitrary data given by the observer. 2108 @type kwargs: dictionary 2109 2110 @keyword por: Point of regard for the related accessible. 2111 @type por: L{AEPor <AEPor.AEPor>} 2112 @keyword layer: Layer on which the event occurred. 2113 @type layer: integer 2114 @keyword task_name: Name of the task this function executes. 2115 @type task_name: string 2116 @keyword kind: Indicates the kind of selection event. 2117 @type kind: integer 2118 2119 @return: C{True} to allow other tasks to process this event. 2120 @rtype: boolean 2121 ''' 2122 return True

2123 ############################################ 2124 ## AEConstants.EVENT_TYPE_SELECTOR_CHANGE ## 2125 ############################################

2126 - def updateOnSelectorChange(self, **kwargs):

2127 ''' 2128 Update this L{EventScript} in response to a consumed selector change event. 2129 Called by L{AETier._executeTask <AETier.AETier._executeTask>}. 2130 2131 @param kwargs: Arbitrary data given by the observer. 2132 @type kwargs: dictionary 2133 2134 @keyword por: Point of regard for the related accessible. 2135 @type por: L{AEPor <AEPor.AEPor>} 2136 @keyword layer: Layer on which the event occurred. 2137 @type layer: integer 2138 @keyword kind: Indicates the kind of selection event. 2139 @type kind: integer 2140 @keyword text: The accessible text or name of the item at the POR. 2141 @type text: string 2142 ''' 2143 pass

2144

2145 - def onSelectorChange(self, **kwargs):

2146 ''' 2147 Executes this L{EventScript} in response to a selector change event. Called 2148 by L{AETier._executeTask <AETier.AETier._executeTask>}. 2149 2150 @param kwargs: Arbitrary data given by the observer. 2151 @type kwargs: dictionary 2152 2153 @keyword por: Point of regard for the related accessible. 2154 @type por: L{AEPor <AEPor.AEPor>} 2155 @keyword layer: Layer on which the event occurred. 2156 @type layer: integer 2157 @keyword kind: Indicates the kind of selection event. 2158 @type kind: integer 2159 @keyword text: The accessible text or name of the item at the POR. 2160 @type text: string 2161 2162 @return: Should processing continue? Always returns C{True} by default. 2163 @rtype: boolean 2164 ''' 2165 kind = kwargs['kind'] 2166 if kind == AEConstants.EVENT_ACTIVE_ITEM_SELECT: 2167 return self.onSelectorActive(**kwargs) 2168 elif kind == AEConstants.EVENT_ADD_ITEM_SELECT: 2169 return self.onSelectorAdded(**kwargs) 2170 elif kind == AEConstants.EVENT_REMOVE_ITEM_SELECT: 2171 return self.onSelectorRemoved(**kwargs) 2172 elif kind == AEConstants.EVENT_CHANGE_TEXT_SELECT: 2173 return self.onSelectorText(**kwargs)

2174

2175 - def onSelectorActive(self, **kwargs):

2176 ''' 2177 Executes this L{EventScript} in response to an active selection change event. 2178 Called by L{onSelectorChange}. 2179 2180 @param kwargs: Arbitrary data given by the observer. 2181 @type kwargs: dictionary 2182 2183 @keyword por: Point of regard for the related accessible. 2184 @type por: L{AEPor <AEPor.AEPor>} 2185 @keyword layer: Layer on which the event occurred. 2186 @type layer: integer 2187 @keyword kind: Indicates the kind of selection event. 2188 @type kind: integer 2189 @keyword text: The accessible text or name of the item at the POR. 2190 @type text: string 2191 2192 @return: Should processing continue? Always returns C{True} by default. 2193 @rtype: boolean 2194 ''' 2195 return True

2196

2197 - def onSelectorText(self, **kwargs):

2198 ''' 2199 Executes this L{EventScript} in response to an addition to the current 2200 selection. Called by L{onSelectorChange}. 2201 2202 @param kwargs: Arbitrary data given by the observer. 2203 @type kwargs: dictionary 2204 2205 @keyword por: Point of regard for the related accessible. 2206 @type por: L{AEPor <AEPor.AEPor>} 2207 @keyword layer: Layer on which the event occurred. 2208 @type layer: integer 2209 @keyword kind: Indicates the kind of selection event. 2210 @type kind: integer 2211 @keyword text: The accessible text or name of the item at the POR. 2212 @type text: string 2213 2214 @return: Should processing continue? Always returns C{True} by default. 2215 @rtype: boolean 2216 ''' 2217 return True

2218

2219 - def onSelectorAdded(self, **kwargs):

2220 ''' 2221 Executes this L{EventScript} in response to a removal from the current 2222 selection. Called by L{onSelectorChange}. 2223 2224 @param kwargs: Arbitrary data given by the observer. 2225 @type kwargs: dictionary 2226 2227 @keyword por: Point of regard for the related accessible. 2228 @type por: L{AEPor <AEPor.AEPor>} 2229 @keyword layer: Layer on which the event occurred. 2230 @type layer: integer 2231 @keyword kind: Indicates the kind of selection event. 2232 @type kind: integer 2233 @keyword text: The accessible text or name of the item at the POR. 2234 @type text: string 2235 2236 @return: Should processing continue? Always returns C{True} by default. 2237 @rtype: boolean 2238 ''' 2239 return True

2240

2241 - def onSelectorRemoved(self, **kwargs):

2242 ''' 2243 Executes this L{EventScript} in response to a removal from the current 2244 selection. Called by L{onSelectorChange}. 2245 2246 @param kwargs: Arbitrary data given by the observer. 2247 @type kwargs: dictionary 2248 2249 @keyword por: Point of regard for the related accessible. 2250 @type por: L{AEPor <AEPor.AEPor>} 2251 @keyword layer: Layer on which the event occurred. 2252 @type layer: integer 2253 @keyword kind: Indicates the kind of selection event. 2254 @type kind: integer 2255 @keyword text: The accessible text or name of the item at the POR. 2256 @type text: string 2257 2258 @return: Should processing continue? Always returns C{True} by default. 2259 @rtype: boolean 2260 ''' 2261 return True

2262 2263 ######################################### 2264 ## AEConstants.EVENT_TYPE_STATE_CHANGE ## 2265 #########################################

2266 - def updateOnStateChange(self, **kwargs):

2267 ''' 2268 Updates this L{EventScript} in response to a consumed state change event. 2269 Called by L{AETier._executeTask <AETier.AETier._executeTask>}. 2270 2271 @param kwargs: Arbitrary data given by the observer. 2272 @type kwargs: dictionary 2273 2274 @keyword por: Point of regard for the related accessible 2275 @type por: L{AEPor <AEPor.AEPor>} 2276 @keyword layer: Layer on which the event occurred 2277 @type layer: integer 2278 @keyword task_name: Name of the task this function executes. 2279 @type task_name: string 2280 @keyword name: Name of the state that changed 2281 @type name: string 2282 @keyword value: C{True} if the state is now set, C{False} if not 2283 @type value: boolean 2284 ''' 2285 pass

2286

2287 - def onStateChange(self, **kwargs):

2288 ''' 2289 Executes this L{EventScript} in response to a state change event. Called by 2290 L{AETier._executeTask <AETier.AETier._executeTask>}. 2291 2292 @param kwargs: Arbitrary data given by the observer. 2293 @type kwargs: dictionary 2294 2295 @keyword por: Point of regard for the related accessible. 2296 @type por: L{AEPor <AEPor.AEPor>} 2297 @keyword layer: Layer on which the event occurred. 2298 @type layer: integer 2299 @keyword task_name: Name of the task this function executes. 2300 @type task_name: string 2301 @keyword name: Name of the state that changed. 2302 @type name: string 2303 @keyword value: C{True} if the state is now set, C{False} if not. 2304 @type value: boolean 2305 2306 @return: C{True} to allow other tasks to process this event 2307 @rtype: boolean 2308 ''' 2309 return True

2310 2311 ######################################### 2312 ## AEConstants.EVENT_TYPE_TABLE_CHANGE ## 2313 #########################################

2314 - def updateOnTableChange(self, **kwargs):

2315 ''' 2316 Updates this L{EventScript} in response to a consumed table change event. 2317 Called by L{AETier._executeTask <AETier.AETier._executeTask>}. 2318 2319 @param kwargs: Arbitrary data given by the observer. 2320 @type kwargs: dictionary 2321 2322 @keyword por: Point of regard for the related accessible. 2323 @type por: L{AEPor <AEPor.AEPor>} 2324 @keyword layer: Layer on which the event occurred. 2325 @type layer: integer 2326 @keyword task_name: Name of the task this function executes. 2327 @type task_name: string 2328 @keyword is_row: C{True} if a table row, C{False} if a table column. 2329 @type is_row: boolean 2330 @keyword added: C{True} when a row/column is added, C{False} when removed, 2331 C{None} when reordered 2332 @type added: boolean 2333 @keyword first_child_por: The L{AEPor <AEPor.AEPor>} of first 2334 inserted/deleted row/column. 2335 @type first_child_por: L{AEPor <AEPor.AEPor>} 2336 @keyword last_child_por: The L{AEPor <AEPor.AEPor>} of last 2337 inserted/deleted row/column. 2338 @type last_child_por: L{AEPor <AEPor.AEPor>} 2339 ''' 2340 pass

2341

2342 - def onTableChange(self, **kwargs):

2343 ''' 2344 Executes this L{EventScript} in response to a hierarchy change event. Called 2345 by L{AETier._executeTask <AETier.AETier._executeTask>}. 2346 2347 @param kwargs: Arbitrary data given by the observer. 2348 @type kwargs: dictionary 2349 2350 @keyword por: Point of regard for the related accessible. 2351 @type por: L{AEPor <AEPor.AEPor>} 2352 @keyword layer: Layer on which the event occurred. 2353 @type layer: integer 2354 @keyword task_name: Name of the task this function executes. 2355 @type task_name: string 2356 @keyword is_row: C{True} if a table row, C{False} if a table column. 2357 @type is_row: boolean 2358 @keyword added: C{True} when a row/column is added, C{False} when removed, 2359 C{None} when reordered. 2360 @type added: boolean 2361 @keyword first_child_por: The L{AEPor <AEPor.AEPor>} of first 2362 inserted/deleted row/column. 2363 @type first_child_por: L{AEPor <AEPor.AEPor>} 2364 @keyword last_child_por: The L{AEPor <AEPor.AEPor>} of last 2365 inserted/deleted row/column. 2366 @type last_child_por: L{AEPor <AEPor.AEPor>} 2367 2368 @return: C{True} to allow other tasks to process this event 2369 @rtype: boolean 2370 ''' 2371 2372 is_row = kwargs['is_row'] 2373 added = kwargs['added'] 2374 if is_row == True: #row 2375 if added == True: #row-inserted 2376 return self.onTableRowInserted(**kwargs) 2377 elif added == False: #row-deleted 2378 return self.onTableRowDeleted(**kwargs) 2379 else: #row-reordered 2380 return self.onTableRowReordered(**kwargs) 2381 2382 else: # column 2383 if added == True: #column-inserted 2384 return self.onTableColumnInserted(**kwargs) 2385 elif added == False: #column-deleted 2386 return self.onTableColumnDeleted(**kwargs) 2387 else: #column-reordered 2388 return self.onTableColumnReordered(**kwargs)

2389 2390

2391 - def onTableRowInserted(self, **kwargs):

2392 ''' 2393 Executes this L{EventScript} in response to a row-inserted table change 2394 event. Called by L{onTableChange}. 2395 2396 @param kwargs: Arbitrary data given by the observer. 2397 @type kwargs: dictionary 2398 2399 @keyword por: Point of regard for the related accessible. 2400 @type por: L{AEPor <AEPor.AEPor>} 2401 @keyword layer: Layer on which the event occurred. 2402 @type layer: integer 2403 @keyword task_name: Name of the task this function executes. 2404 @type task_name: string 2405 @keyword is_row: C{True} if a table row. 2406 @type is_row: boolean 2407 @keyword added: C{True} when a row is added. 2408 @type added: boolean 2409 @keyword first_child_por: The L{AEPor <AEPor.AEPor>} of first inserted row. 2410 @type first_child_por: L{AEPor <AEPor.AEPor>} 2411 @keyword last_child_por: The L{AEPor <AEPor.AEPor>} of last inserted row. 2412 @type last_child_por: L{AEPor <AEPor.AEPor>} 2413 2414 @return: C{True} to allow other tasks to process this event 2415 @rtype: boolean 2416 ''' 2417 return True

2418

2419 - def onTableRowDeleted(self, **kwargs):

2420 ''' 2421 Executes this L{EventScript} in response to a row-deleted table change event. 2422 Called by L{onTableChange}. 2423 2424 @param kwargs: Arbitrary data given by the observer. 2425 @type kwargs: dictionary 2426 2427 @keyword por: Point of regard for the related accessible. 2428 @type por: L{AEPor <AEPor.AEPor>} 2429 @keyword layer: Layer on which the event occurred. 2430 @type layer: integer 2431 @keyword task_name: Name of the task this function executes. 2432 @type task_name: string 2433 @keyword is_row: C{True} if a table row. 2434 @type is_row: boolean 2435 @keyword added: C{False} when a row removed. 2436 @type added: boolean 2437 @keyword first_child_por: The L{AEPor <AEPor.AEPor>} of first deleted row 2438 @type first_child_por: L{AEPor <AEPor.AEPor>} 2439 @keyword last_child_por: The L{AEPor <AEPor.AEPor>} of last deleted row 2440 @type last_child_por: L{AEPor <AEPor.AEPor>} 2441 2442 @return: C{True} to allow other tasks to process this event 2443 @rtype: boolean 2444 ''' 2445 return True

2446

2447 - def onTableRowReordered(self, **kwargs):

2448 ''' 2449 Executes this L{EventScript} in response to a row-reordered table change 2450 event. Called by L{onTableChange}. 2451 2452 @param kwargs: Arbitrary data given by the observer. 2453 @type kwargs: dictionary 2454 2455 @keyword por: Point of regard for the related accessible 2456 @type por: L{AEPor <AEPor.AEPor>} 2457 @keyword layer: Layer on which the event occurred 2458 @type layer: integer 2459 @keyword task_name: Name of the task this function executes. 2460 @type task_name: string 2461 @keyword is_row: C{True} if a table row, C{False} if a table column. 2462 @type is_row: boolean 2463 @keyword added: C{None} when a row reordered. 2464 @type added: boolean 2465 @keyword first_child_por: The L{AEPor <AEPor.AEPor>} of first 2466 inserted/deleted row 2467 @type first_child_por: L{AEPor <AEPor.AEPor>} 2468 @keyword last_child_por: The L{AEPor <AEPor.AEPor>} of last 2469 inserted/deleted row 2470 @type last_child_por: L{AEPor <AEPor.AEPor>} 2471 2472 @return: C{True} to allow other tasks to process this event 2473 @rtype: boolean 2474 ''' 2475 return True

2476

2477 - def onTableColumnInserted(self, **kwargs):

2478 ''' 2479 Executes this L{EventScript} in response to a column-inserted table change 2480 event. Called by L{onTableChange}. 2481 2482 @param kwargs: Arbitrary data given by the observer. 2483 @type kwargs: dictionary 2484 2485 @keyword por: Point of regard for the related accessible. 2486 @type por: L{AEPor <AEPor.AEPor>} 2487 @keyword layer: Layer on which the event occurred. 2488 @type layer: integer 2489 @keyword task_name: Name of the task this function executes. 2490 @type task_name: string 2491 @keyword is_row: C{True} if a table row, C{False} if a table column. 2492 @type is_row: boolean 2493 @keyword added: C{True} when a column is added 2494 @type added: boolean 2495 @keyword first_child_por: The L{AEPor <AEPor.AEPor>} of first inserted column 2496 @type first_child_por: L{AEPor <AEPor.AEPor>} 2497 @keyword last_child_por: The L{AEPor <AEPor.AEPor>} of last inserted column 2498 @type last_child_por: L{AEPor <AEPor.AEPor>} 2499 2500 @return: C{True} to allow other tasks to process this event 2501 @rtype: boolean 2502 ''' 2503 return True

2504

2505 - def onTableColumnDeleted(self, **kwargs):

2506 ''' 2507 Executes this L{EventScript} in response to a column-deleted table change 2508 event. Called by L{onTableChange}. 2509 2510 @param kwargs: Arbitrary data given by the observer. 2511 @type kwargs: dictionary 2512 2513 @keyword por: Point of regard for the related accessible. 2514 @type por: L{AEPor <AEPor.AEPor>} 2515 @keyword layer: Layer on which the event occurred. 2516 @type layer: integer 2517 @keyword task_name: Name of the task this function executes. 2518 @type task_name: string 2519 @keyword is_row: C{False} if a table column. 2520 @type is_row: boolean 2521 @keyword added: C{False} when a column removed. 2522 @type added: boolean 2523 @keyword first_child_por: The L{AEPor <AEPor.AEPor>} of first deleted column. 2524 @type first_child_por: L{AEPor <AEPor.AEPor>} 2525 @keyword last_child_por: The L{AEPor <AEPor.AEPor>} of last deleted column. 2526 @type last_child_por: L{AEPor <AEPor.AEPor>} 2527 2528 @return: C{True} to allow other tasks to process this event 2529 @rtype: boolean 2530 ''' 2531 return True

2532

2533 - def onTableColumnReordered(self, **kwargs):

2534 ''' 2535 Executes this L{EventScript} in response to a column-reordered table change 2536 event. Called by L{onTableChange}. 2537 2538 @param kwargs: Arbitrary data given by the observer. 2539 @type kwargs: dictionary 2540 2541 @keyword por: Point of regard for the related accessible. 2542 @type por: L{AEPor <AEPor.AEPor>} 2543 @keyword layer: Layer on which the event occurred. 2544 @type layer: integer 2545 @keyword task_name: Name of the task this function executes. 2546 @type task_name: string 2547 @keyword is_row: C{True} if a table row, C{False} if a table column. 2548 @type is_row: boolean 2549 @keyword added: C{None} when a column reordered. 2550 @type added: boolean 2551 @keyword first_child_por: The L{AEPor <AEPor.AEPor>} of first 2552 inserted/deleted column. 2553 @type first_child_por: L{AEPor <AEPor.AEPor>} 2554 @keyword last_child_por: The L{AEPor <AEPor.AEPor>} of last 2555 inserted/deleted column. 2556 @type last_child_por: L{AEPor <AEPor.AEPor>} 2557 2558 @return: C{True} to allow other tasks to process this event 2559 @rtype: boolean 2560 ''' 2561 return True

2562 ######################################## 2563 ## AEConstants.EVENT_TYPE_View_CHANGE ## 2564 ########################################

2565 - def updateOnViewChange(self, **kwargs):

2566 ''' 2567 Updates this L{EventScript} in response to a consumed view change event. 2568 Called by L{AETier._executeTask <AETier.AETier._executeTask>}. 2569 2570 @param kwargs: Arbitrary data given by the observer. 2571 @type kwargs: dictionary 2572 2573 @keyword por: Point of regard for the related accessible. 2574 @type por: L{AEPor <AEPor.AEPor>} 2575 @keyword layer: Layer on which the event occurred. 2576 @type layer: integer 2577 @keyword task_name: Name of the task this function executes. 2578 @type task_name: string 2579 @keyword title: Title of the view. 2580 @type title: string 2581 @keyword gained: The kind of view change event. 2582 @type gained: integer 2583 ''' 2584 pass

2585

2586 - def onViewChange(self, **kwargs):

2587 ''' 2588 Executes this L{EventScript} in response to a view change event. 2589 Called by L{AETier._executeTask <AETier.AETier._executeTask>}. 2590 2591 @param kwargs: Arbitrary data given by the observer. 2592 @type kwargs: dictionary 2593 2594 @keyword por: Point of regard for the related accessible. 2595 @type por: L{AEPor <AEPor.AEPor>} 2596 @keyword layer: Layer on which the event occurred. 2597 @type layer: integer 2598 @keyword task_name: Name of the task this function executes. 2599 @type task_name: string 2600 @keyword title: Title of the view. 2601 @type title: string 2602 @keyword gained: The kind of view change event. 2603 @type gained: integer 2604 2605 @return: C{True} to allow other tasks to process this event. 2606 @rtype: boolean 2607 ''' 2608 gained = kwargs['gained'] 2609 if gained == AEConstants.EVENT_VIEW_GAINED: 2610 return self.onViewGained(**kwargs) 2611 elif gained == AEConstants.EVENT_VIEW_LOST: 2612 return self.onViewLost(**kwargs) 2613 elif gained == AEConstants.EVENT_VIEW_STARTUP: 2614 return self.onViewStartup(**kwargs) 2615 elif gained == AEConstants.EVENT_VIEW_FIRST_GAINED: 2616 return self.onViewFirstGained(**kwargs)

2617

2618 - def onViewGained(self, **kwargs):

2619 ''' 2620 Executes this L{EventScript} in response to a view gained event. 2621 Called by L{onViewChange}. 2622 2623 @param kwargs: Arbitrary data given by the observer. 2624 @type kwargs: dictionary 2625 2626 @keyword por: Point of regard for the related accessible 2627 @type por: L{AEPor <AEPor.AEPor>} 2628 @keyword layer: Layer on which the event occurred. 2629 @type layer: integer 2630 @keyword task_name: Name of the task this function executes. 2631 @type task_name: string 2632 @keyword title: Title of the view. 2633 @type title: string 2634 @keyword gained: The kind of view change event. 2635 @type gained: integer 2636 2637 @return: C{True} to allow other tasks to process this event. 2638 @rtype: boolean 2639 ''' 2640 return True

2641

2642 - def onViewLost(self, **kwargs):

2643 ''' 2644 Executes this L{EventScript} in response to a view lost event. 2645 Called by L{onViewChange}. 2646 2647 @param kwargs: Arbitrary data given by the observer. 2648 @type kwargs: dictionary 2649 2650 @keyword por: Point of regard for the related accessible. 2651 @type por: L{AEPor <AEPor.AEPor>} 2652 @keyword layer: Layer on which the event occurred. 2653 @type layer: integer 2654 @keyword task_name: Name of the task this function executes. 2655 @type task_name: string 2656 @keyword title: Title of the view. 2657 @type title: string 2658 @keyword gained: The kind of view change event. 2659 @type gained: integer 2660 2661 @return: C{True} to allow other tasks to process this event. 2662 @rtype: boolean 2663 ''' 2664 return True

2665

2666 - def onViewStartup(self, **kwargs):

2667 ''' 2668 Executes this L{EventScript} in response to the view being identified during 2669 SUE startup. Called by L{onViewChange}. 2670 2671 @param kwargs: Arbitrary data given by the observer. 2672 @type kwargs: dictionary 2673 2674 @keyword por: Point of regard for the related accessible. 2675 @type por: L{AEPor <AEPor.AEPor>} 2676 @keyword layer: Layer on which the event occurred. 2677 @type layer: integer 2678 @keyword task_name: Name of the task this function executes. 2679 @type task_name: string 2680 @keyword title: Title of the view. 2681 @type title: string 2682 @keyword gained: The kind of view change event. 2683 @type gained: integer 2684 2685 @return: C{True} to allow other tasks to process this event. 2686 @rtype: boolean 2687 ''' 2688 return True

2689

2690 - def onViewFirstGained(self, **kwargs):

2691 ''' 2692 Executes this L{EventScript} in response to the view being identified as the 2693 active view during SUE startup. Called by L{onViewChange}. 2694 2695 @param kwargs: Arbitrary data given by the observer. 2696 @type kwargs: dictionary 2697 2698 @keyword por: Point of regard for the related accessible. 2699 @type por: L{AEPor <AEPor.AEPor>} 2700 @keyword layer: Layer on which the event occurred. 2701 @type layer: integer 2702 @keyword task_name: Name of the task this function executes. 2703 @type task_name: string 2704 @keyword title: Title of the view. 2705 @type title: string 2706 @keyword gained: The kind of view change event. 2707 @type gained: integer 2708 2709 @return: C{True} to allow other tasks to process this event. 2710 @rtype: boolean 2711 ''' 2712 return True

2713 2714 2715 ########################### 2716 ## AEEvent.ChooserChange ## 2717 ###########################

2718 - def onChooserChange(self, **kwargs):

2719 ''' 2720 Executes a registered task function in response to some change in a 2721 L{AEChooser}, starting it, ending it, or applying its current options. 2722 Called by L{AETier._executeTask <AETier.AETier._executeTask>}. 2723 2724 @param kwargs: Arbitrary data given by the observer. 2725 @type kwargs: dictionary 2726 2727 @keyword por: Point of regard for the related accessible. 2728 @type por: L{AEPor <AEPor.AEPor>} 2729 @keyword layer: Layer on which the event occurred. 2730 @type layer: integer 2731 @keyword task_name: Name of the task this function executes. 2732 @type task_name: string 2733 @keyword chooser: Chooser that fired the event. 2734 @type chooser: L{AEChooser} 2735 @keyword kind: Kind of signal, APPLY, OK, or CANCEL or an arbitrary constant 2736 provided by the L{AEChooser}. 2737 @type kind: integer 2738 2739 @return: Should processing continue? Always returns C{True} by default. 2740 @rtype: boolean 2741 ''' 2742 try : 2743 chooser = kwargs['chooser'] 2744 kind = kwargs['kind'] 2745 except (KeyError): 2746 return self.onChooserStart(**kwargs) 2747 2748 if kind in (chooser.OK, chooser.CANCEL): 2749 # call signal then end 2750 # return the AND of the return values 2751 update = self.onChooserSignal( **kwargs) 2752 end = self.onChooserEnd(**kwargs) 2753 return end and update 2754 else: 2755 # call signal 2756 return self.onChooserSignal(**kwargs)

2757

2758 - def onChooserStart(self, **kwargs):

2759 ''' 2760 Executes a registered task function to start a new L{AEChooser}, typically 2761 in response to input on an L{AEInput} device. Called by L{onChooserChange}. 2762 2763 @param kwargs: Arbitrary data given by the observer. 2764 @type kwargs: dictionary 2765 2766 @keyword por: Point of regard for the related accessible. 2767 @type por: L{AEPor <AEPor.AEPor>} 2768 @keyword layer: Layer on which the event occurred. 2769 @type layer: integer 2770 @keyword task_name: Name of the task this function executes. 2771 @type task_name: string 2772 2773 @return: Should processing continue? Always returns C{True} by default. 2774 @rtype: boolean 2775 ''' 2776 return True

2777

2778 - def onChooserSignal(self, **kwargs):

2779 ''' 2780 Executes a registered task function in response to a chooser request to have 2781 its current options immediately applied without its completion. Called by 2782 L{onChooserChange}. 2783 2784 @param kwargs: Arbitrary data given by the observer. 2785 @type kwargs: dictionary 2786 2787 @keyword por: Point of regard for the related accessible. 2788 @type por: L{AEPor <AEPor.AEPor>} 2789 @keyword layer: Layer on which the event occurred. 2790 @type layer: integer 2791 @keyword task_name: Name of the task this function executes. 2792 @type task_name: string 2793 @keyword chooser: Chooser that fired the event. 2794 @type chooser: L{AEChooser} 2795 @keyword kind: Kind of signal, APPLY, OK, or CANCEL or an arbitrary constant 2796 provided by the L{AEChooser} 2797 @type kind: integer 2798 2799 @return: Should processing continue? Always returns C{True} by default. 2800 @rtype: boolean 2801 ''' 2802 return True

2803

2804 - def onChooserEnd(self, **kwargs):

2805 ''' 2806 Executes a registered task function in response to the ending of a chooser 2807 dialog. Called by L{onChooserChange}. 2808 2809 The default implementation calls L{AEScript.unregisterChooserTask} which is 2810 the desired behavior for most L{AEChooser}. 2811 2812 @param kwargs: Arbitrary data given by the observer. 2813 @type kwargs: dictionary 2814 2815 @keyword por: Point of regard for the related accessible. 2816 @type por: L{AEPor <AEPor.AEPor>} 2817 @keyword layer: Layer on which the event occurred. 2818 @type layer: integer 2819 @keyword task_name: Name of the task this function executes. 2820 @type task_name: string 2821 @keyword chooser: Chooser that fired the event. 2822 @type chooser: L{AEChooser} 2823 @keyword kind: Kind of signal, APPLY, OK, or CANCEL or an arbitrary constant 2824 provided by the L{AEChooser}. 2825 @type kind: integer 2826 2827 @return: Should processing continue? Always returns C{True} by default. 2828 @rtype: boolean 2829 ''' 2830 self.unregisterChooserTask(kwargs['chooser']) 2831 return True

2832 2833 ############################# 2834 ## chainNewEventTaskAround ## 2835 #############################

2836 - def chainNewEventTaskAround(self, new_task, old_task, old_task_script = None,\ 2837 *functions_to_replace):

2838 ''' 2839 Allows to only replace certain parts of another event task. 2840 2841 Registers the new task and chains it around the old one. If the relevant 2842 event comes in, there will be a test which of the two events should be 2843 executed. 2844 2845 Example: A 'new task' wants to replace part of the execution to a 2846 CaretChange event. The 'new task' is only interested in this event when a 2847 caret move occured. :: 2848 self.chainNewEventTaskAround('new task', 2849 'read caret', 'BasicSpeechScript', 2850 'onCaretMoved') 2851 2852 When a caret move comes in, the new task will be called, but when an update 2853 on the caret event is necessary or an caret inserted or caret deleted comes 2854 in, the 'read caret' task will be executed. 2855 2856 @param new_task: Name of the new event task. This task can't be an already 2857 registered task. 2858 @type new_task: string 2859 @param old_task: Name of the task that will be replaced partly. 2860 @type old_task: string 2861 @param old_task_script: Name of the script. 2862 @type old_task_script: string 2863 @param functions_to_replace: List of function names, that shall be replaced. 2864 @type functions_to_replace: list of strings 2865 ''' 2866 # build the key for the old task: 2867 if old_task_script is None: 2868 old_task_script = self.getClassName() 2869 old_task_key = (old_task, old_task_script) 2870 2871 # get the functions that the old task implements: 2872 if old_task_script == self.getClassName(): 2873 script = self 2874 else: 2875 script = self.tier.script_refs[old_task_key] 2876 execute_function = script.registered_tasks[old_task_key][0] 2877 update_function = script.registered_tasks[old_task_key][1] 2878 2879 self.around_tasks[new_task] = [old_task, old_task_script, script, 2880 execute_function, update_function, 2881 functions_to_replace] 2882 2883 # then try to register the new task 2884 try: 2885 self.registerTask(new_task, self.executeAroundTask, self.updateAroundTask) 2886 except ValueError: 2887 raise ValueError 2888 2889 # chain around the old task 2890 self.chainTask(new_task, AEConstants.CHAIN_AROUND, old_task, old_task_script)

2891

2892 - def updateAroundTask(self, **kwargs):

2893 ''' 2894 Needed in context to L{chainNewEventTaskAround} for the decision which 2895 update function should be executed. 2896 2897 @param kwargs: Arbitrary data given by the observer. 2898 @type kwargs: dictionary 2899 2900 ''' 2901 update_function = self.around_tasks[kwargs['task_name']][4] 2902 functions_to_replace = self.around_tasks[kwargs['task_name']][5] 2903 for function in functions_to_replace: 2904 if function.startswith('updateOn'): 2905 update_function(**kwargs) 2906 return 2907 self._doReplacedTask(**kwargs)

2908

2909 - def executeAroundTask(self, **kwargs):

2910 ''' 2911 Needed in context to L{chainNewEventTaskAround} for the decision which 2912 execute function should be called. 2913 2914 @Note: This function should be removed. It's functionality should be 2915 included in the on...Change(self, **kwargs) methods. Right now the 2916 decision is made in two places (redundancy). 2917 2918 @param kwargs: Arbitrary data given by the observer. 2919 @type kwargs: dictionary 2920 ''' 2921 script = self.around_tasks[kwargs['task_name']][2] 2922 execute_function = self.around_tasks[kwargs['task_name']][3] 2923 functions_to_replace = self.around_tasks[kwargs['task_name']][5] 2924 2925 # replace standard tasks for events functions 2926 if execute_function == script.onCaretChange: 2927 added = kwargs['added'] 2928 for function in functions_to_replace: 2929 if added is None: 2930 if function == 'onCaretMoved': 2931 return self.onCaretMoved(**kwargs) 2932 else: 2933 return self._doReplacedTask(**kwargs) 2934 elif added: 2935 if function == 'onCaretInserted': 2936 return self.onCaretInserted(**kwargs) 2937 else: 2938 return self._doReplacedTask(**kwargs) 2939 else: 2940 if function == 'onCaretDeleted': 2941 return self.onCaretDeleted(**kwargs) 2942 else: 2943 return self._doReplacedTask(**kwargs) 2944 2945 if execute_function == script.onChildrenChange: 2946 added = kwargs['added'] 2947 for function in functions_to_replace: 2948 if added == True: 2949 if function == 'onChildAdded': 2950 return self.onChildAdded(**kwargs) 2951 else: 2952 return self._doReplacedTask(**kwargs) 2953 else: 2954 if function == 'onChildRemoved': 2955 return self.onChildRemoved(**kwargs) 2956 else: 2957 return self._doReplacedTask(**kwargs) 2958 2959 if execute_function == script.onFocusChange: 2960 for function in functions_to_replace: 2961 if kwargs['gained']: 2962 if function == 'onFocusGained': 2963 return self.onFocusGained(**kwargs) 2964 else: 2965 return self._doReplacedTask(**kwargs) 2966 else: 2967 if function == 'onFocusLost': 2968 return self.onFocusLost(**kwargs) 2969 else: 2970 return self._doReplacedTask(**kwargs) 2971 2972 if execute_function == script.onMouseChange: 2973 kind = kwargs['kind'] 2974 for function in functions_to_replace: 2975 if kind == AEConstants.EVENT_MOUSE_MOVE: 2976 if function == 'onMouseMoved': 2977 return self.onMouseMoved(**kwargs) 2978 else: 2979 return self._doReplacedTask(**kwargs) 2980 elif kind == AEConstants.EVENT_MOUSE_PRESS: 2981 if function == 'onMousePressed': 2982 return self.onMousePressed(**kwargs) 2983 else: 2984 return self._doReplacedTask(**kwargs) 2985 else: 2986 if function == 'onMouseReleased': 2987 return self.onMouseReleased(**kwargs) 2988 else: 2989 return self._doReplacedTask(**kwargs) 2990 2991 if execute_function == script.onPropertyChange: 2992 return self.onPropertyChange(**kwargs) 2993 2994 if execute_function == script.onScreenChange: 2995 kind = kwargs['kind'] 2996 for function in functions_to_replace: 2997 if kind == AEConstants.SCREEN_OBJECT_BOUNDS: 2998 if function == 'onScreenResized': 2999 return self.onScreenResized(**kwargs) 3000 else: 3001 return self._doReplacedTask(**kwargs) 3002 elif kind == AEConstants.SCREEN_TEXT_BOUNDS: 3003 if function == 'onScreenReflowed': 3004 return self.onScreenReflowed(**kwargs) 3005 else: 3006 return self._doReplacedTask(**kwargs) 3007 else: 3008 if function == 'onScreenRefreshed': 3009 return self.onScreenRefreshed(**kwargs) 3010 else: 3011 return self._doReplacedTask(**kwargs) 3012 3013 if execute_function == script.onSelectorChange: 3014 kind = kwargs['kind'] 3015 for function in functions_to_replace: 3016 if kind == AEConstants.EVENT_ACTIVE_ITEM_SELECT: 3017 if function == 'onSelectorActive': 3018 return self.onSelectorActive(**kwargs) 3019 else: 3020 return self._doReplacedTask(**kwargs) 3021 elif kind == AEConstants.EVENT_ADD_ITEM_SELECT: 3022 if function == 'onSelectorAdded': 3023 return self.onSelectorAdded(**kwargs) 3024 else: 3025 return self._doReplacedTask(**kwargs) 3026 elif kind == AEConstants.EVENT_REMOVE_ITEM_SELECT: 3027 if function == 'onSelectorRemoved': 3028 return self.onSelectorRemoved(**kwargs) 3029 else: 3030 return self._doReplacedTask(**kwargs) 3031 elif kind == AEConstants.EVENT_CHANGE_TEXT_SELECT: 3032 if function == 'onSelectorText': 3033 return self.onSelectorText(**kwargs) 3034 else: 3035 return self._doReplacedTask(**kwargs) 3036 3037 if execute_function == script.onStateChange: 3038 return self.onStateChange(**kwargs) 3039 3040 if execute_function == script.onTableChange: 3041 is_row = kwargs['is_row'] 3042 added = kwargs['added'] 3043 if is_row == True: # row 3044 for function in functions_to_replace: 3045 if added == True: 3046 if function == 'onTableRowInserted': 3047 return self.onTableRowInserted(**kwargs) 3048 else: 3049 return self._doReplacedTask(**kwargs) 3050 elif added == False: 3051 if function == 'onTableRowDeleted': 3052 return self.onTableRowDeleted(**kwargs) 3053 else: 3054 return self._doReplacedTask(**kwargs) 3055 else: 3056 if function == 'onTableRowReordered': 3057 return self.onTableRowReordered(**kwargs) 3058 else: 3059 return self._doReplacedTask(**kwargs) 3060 else: # column 3061 for function in functions_to_replace: 3062 if added == True: 3063 if function == 'onTableColumnInserted': 3064 return self.onTableColumnInserted(**kwargs) 3065 else: 3066 return self._doReplacedTask(**kwargs) 3067 elif added == False: 3068 if function == 'onTableColumnDeleted': 3069 return self.onTableColumnDeleted(**kwargs) 3070 else: 3071 return self._doReplacedTask(**kwargs) 3072 else: 3073 if function == 'onTableColumnReordered': 3074 return self.onTableColumnReordered(**kwargs) 3075 else: 3076 return self._doReplacedTask(**kwargs) 3077 3078 if execute_function == script.onViewChange: 3079 gained = kwargs['gained'] 3080 for function in functions_to_replace: 3081 if gained == AEConstants.EVENT_VIEW_GAINED: 3082 if function == 'onViewGained': 3083 return self.onViewGained(**kwargs) 3084 else: 3085 return self._doReplacedTask(**kwargs) 3086 elif gained == AEConstants.EVENT_VIEW_LOST: 3087 if function == 'onViewLost': 3088 return self.onViewLost(**kwargs) 3089 else: 3090 return self._doReplacedTask(**kwargs) 3091 elif gained == AEConstants.EVENT_VIEW_STARTUP: 3092 if function == 'onViewStartup': 3093 return self.onViewStartup(**kwargs) 3094 else: 3095 return self._doReplacedTask(**kwargs) 3096 elif gained == AEConstants.EVENT_VIEW_FIRST_GAINED: 3097 if function == 'onViewFirstGained': 3098 return self.onViewFirstGained(**kwargs) 3099 else: 3100 return self._doReplacedTask(**kwargs)

3101 3102

3103 - def _doReplacedTask(self, **kwargs):

3104 ''' 3105 Needed in context with L{chainNewEventTaskAround}. 3106 3107 @param kwargs: Arbitrary data given by the observer. 3108 @type kwargs: dictionary 3109 ''' 3110 try: 3111 old_task = self.around_tasks[kwargs['task_name']][0] 3112 old_task_script = self.around_tasks[kwargs['task_name']][1] 3113 except KeyError: 3114 return True 3115 3116 self.unchainTask(kwargs['task_name'], AEConstants.CHAIN_AROUND, 3117 old_task, old_task_script) 3118 rv = self.doTask(old_task, old_task_script, **kwargs) 3119 self.chainTask(kwargs['task_name'], AEConstants.CHAIN_AROUND, 3120 old_task, old_task_script) 3121 return rv

3122

Source Code for Module AccessEngine.AEScript