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