Source Code for Module AccessEngine.AEEvent.CaretChange

  1  ''' 
  2  Defines an L{AEEvent} indicating that the caret has moved. 
  3   
  4  @author: Pete Brunet 
  5  @author: Larry Weiss 
  6  @organization: IBM Corporation 
  7  @copyright: Copyright (c) 2005, 2007 IBM Corporation 
  8  @license: The BSD License 
  9   
 10  @author: Frank Zenker 
 11  @author: Ramona Bunk 
 12  @organization: IT Science Center Ruegen gGmbH, Germany 
 13  @copyright: Copyright (c) 2007, 2008 ITSC Ruegen 
 14  @license: The BSD License 
 15   
 16  All rights reserved. This program and the accompanying materials are made  
 17  available under the terms of the BSD license which accompanies 
 18  this distribution, and is available at 
 19  U{http://www.opensource.org/licenses/bsd-license.php} 
 20  ''' 
 21   
 22  import AccessEngine 
 23  import Base 
 24  from AccessEngine.AEConstants import LAYER_FOCUS 
 25   
 26 -class CaretChange(Base.AEEvent): 
 27    ''' 
 28    Event that fires when the caret moves in an accessible. 
 29     
 30    This class registers its name and whether it should be monitored by default 
 31    in an L{AEMonitor} using the L{Base.registerEventType} function when this 
 32    module is first imported. The L{AEMonitor} can use this information to build 
 33    its menus. 
 34     
 35    @ivar text: The text inserted, deleted or the line of the caret 
 36    @type text: string 
 37    @ivar text_offset: The offset of the inserted/deleted text or the line  
 38      offset when movement only 
 39    @type text_offset: integer 
 40    @ivar added: True when text added, False when text deleted, and None  
 41      (the default) when event is for caret movement only 
 42    @type added: boolean 
 43    ''' 
 44    Base.registerEventType('CaretChange', False) 
 45     
 46 -  def __init__(self, por, text, text_offset, added=None, **kwargs): 
 47      ''' 
 48      Calls the base class (which set the event priority) and then stores the  
 49      text and offset to be passed along to the AETier as part of the event. 
 50       
 51      @param por: Point of regard 
 52      @type por: L{AEPor} 
 53      @param text: The text inserted, deleted or the line of the caret 
 54      @type text: string 
 55      @param text_offset: The offset of the inserted/deleted text or the line  
 56        offset when movement only 
 57      @type text_offset: integer 
 58      @param added: True when text added, False when text deleted, and None  
 59        (the default) when event is for caret movement only 
 60      @type added: boolean 
 61      ''' 
 62      Base.AEEvent.__init__(self, **kwargs) 
 63      self.por = por 
 64      self.text = text 
 65      self.text_offset = text_offset 
 66      self.added = added 
 67   
 68 -  def __str__(self): 
 69      ''' 
 70      Returns a human readable representation of this event including its name, 
 71      its text, its text offset, and whether the text was added, removed, or  
 72      moved. 
 73       
 74      @return: Information about this event 
 75      @rtype: string 
 76      ''' 
 77      name = Base.AEEvent.__str__(self) 
 78      if self.added is None: 
 79        action = 'moved' 
 80      elif self.added: 
 81        action = 'inserted' 
 82      else: 
 83        action = 'deleted' 
 84      return '%s:\n\tPOR: %s\n\ttext: %s\n\toffset: %d\n\taction: %s' % \ 
 85             (name, self.por, self.text, self.text_offset, action) 
 86     
 87 -  def execute(self): 
 88      ''' 
 89      Contacts the L{AccessEngine.AETierManager} so it can manage the caret change event. 
 90       
 91     @return: True if there is an active view, False if not to delay execution  
 92        of this event until there is 
 93      @rtype: boolean 
 94      ''' 
 95      if AccessEngine.AEViewManager.getAEView() is None and self.layer == LAYER_FOCUS: 
 96        return False 
 97      else: 
 98        AccessEngine.AETierManager.manageEvent(self) 
 99        return True 
100   
101 -  def getFocusPOR(self): 
102      ''' 
103      Returns the L{AEPor} for caret movement events. Used by L{AETier} to maintain a 
104      focus L{AEPor}. 
105       
106      @return: Point-of-regard for this focus event 
107      @rtype: L{AEPor} 
108      @raise AttributeError: When the event does not represent a change in the 
109        focus 
110      ''' 
111      if (self.layer != LAYER_FOCUS or 
112          self.added is not None): 
113        raise AttributeError 
114      return self.por 
115   
116 -  def getDataForTask(self): 
117      ''' 
118      Fetches data out of this L{CaretChange} for use by a 
119      L{AEScript.EventScript.onCaretChange}-Task. 
120       
121      @return: Dictionary of parameters to be passed to a 
122        L{AEScript.EventScript.onCaretChange}-Task as  
123        follows: 
124          - por: The L{AEPor <AEPor.AEPor>} of the accessible in which the caret 
125            moved 
126          - text: The text inserted, deleted or the line of the caret 
127          - text_offset: The offset of the inserted/deleted text or the line  
128            offset when movement only 
129          - added: Boolean that is True when the text was added 
130      @rtype: dictionary 
131      '''     
132      return {'por':self.getPOR(), 'text':self.text, 
133              'text_offset':self.text_offset, 'added':self.added} 
134