compoundDocuments module
- class compoundDocuments.CompoundTextInfo(*args, **kwargs)
Bases:
TextInfo
Constructor. Subclasses must extend this, calling the superclass method first. @param position: The initial position of this range; one of the POSITION_* constants or a position object supported by the implementation. @param obj: The object containing the range of text being represented.
- _makeRawTextInfo(obj, position)
- _normalizeStartAndEnd()
- setEndPoint(other, which)
Sets one end of this range to one end of another range. Subclasses must implement this. @param other: The range from which an end is being obtained. @type other: L{TextInfo} @param which: The ends to use; one of “startToStart”, “startToEnd”, “endToStart”, “endToEnd”.
- collapse(end=False)
Collapses this text info object so that both endpoints are the same. @param end: Whether to collapse to the end; C{True} to collapse to the end, C{False} to collapse to the start. @type end: bool
- copy()
duplicates this text info object so that changes can be made to either one with out afecting the other
- updateCaret()
Moves the system caret to the position of this text info object
- updateSelection()
Moves the selection (usually the system caret) to the position of this text info object
- _get_bookmark()
- _get_NVDAObjectAtStart()
Get the NVDAObject related to the start of the range. Usually it is just the owner NVDAObject, but in the case of virtualBuffers it may be a descendant object. @returns: the NVDAObject at the start
- _get_pointAtStart()
Retrieves x and y coordinates corresponding with the textInfo start. It should return Point. The base implementation uses L{boundingRects}. @rtype: L{locationHelper.Point}
- _isObjectEditableText(obj: NVDAObject) bool
- _isNamedlinkDestination(obj: NVDAObject) bool
- _getControlFieldForObject(obj: NVDAObject, ignoreEditableText=True)
- moveToCodepointOffset(codepointOffset: int) Self
This function moves textInfos by codepoint characters. A codepoint character represents exactly 1 character in a Pythonic string.
- Illustration:
Suppose we have TextInfo that represents a paragraph of text: ``` > s = paragraphInfo.text > s ‘Hello, world!
- ‘
` Suppose that we would like to put the cursor at the first letter of the word 'world'. That means jumping to index 7: `
> s[7:] ‘world!
- ‘
` Here is how this can be done: `
> info = paragraphInfo.moveToCodepointOffset(7) > info.setEndPoint(paragraphInfo, “endToEnd”) > info.text ‘world!
- ‘
- Background:
In many applications there is no one-to-one mapping of codepoint characters and TextInfo characters, e.g. when calling TextInfo.move(UNIT_CHARACTER, n). There are a couple of reasons for this discrepancy: 1. In Wide character encoding, some 4-byte unicode characters are represented as two surrogate characters, whereas in Pythonic string they would be represented by a single character. 2. In non-offset TextInfos (e.g. UIATextInfo) there is no guarantee on the fact that TextInfos.move(UNIT_CHARACTER, 1)would actually move by exactly 1 character. A good illustration of this is in Microsoft Word with UIA enabled always, the first character of a bullet list item would be represented by three pythonic codepoint characters: * Bullet character “•” * Tab character * And the first character of of list item per se.
In many use cases (e.g., sentence navigation, style navigation), we identify pythonic codepoint character that we would like to move our TextInfo to. TextInfos.move(UNIT_CHARACTER, n) would cause many side effects. This function provides a clean and reliable way to jump to a given codepoint offset.
- Assumptions:
1. This function operates on a non-collapsed TextInfo only. In a typical scenario, we might want to jump to a certain offset within a paragraph or a line. In this case this function should be called on TextInfo representing said paragraph or line. The reason for that is that for some implementations we might need to access text of paragraph/line in order to accurately compute result offset. 2. It assumes that 1 character of application-specific TextInfo representation maps to 1 or more characters of codepoint representation. 3. This function is also written with an assumption that a character in application-specific TextInfo representation might not map to any pythonic characters, although this scenario has never been observed in any applications. 4. Also this function assumes that most characters have 1:1 mapping between codepoint and application-specific representations. This assumption is not required, however if this assumption is True, the function will converge faster. If this assumption is false, then it might take many iterations to find the right TextInfo.
- Algorithm:
This generic implementation essentially a biased binary search. On every iteration we operate on a pythonic string and its TextInfo counterpart stored in info variable. We would like to reach a certain offset within that pythonic string, that is stored in codepointOffsetLeft variable. In every iteration of the loop: 1. We try to either move from the left end of info by codepointOffsetLeft characters or from the right end by -codepointOffsetRight characters - depending which move is shorter. We store destination point as collapsed TextInfo tmpInfo. 2. We compute number of pythonic characters from the beginning of info until tmpInfo and store it in actualCodepointOffset variable. 3. We will compare actualCodepointOffset with codepointOffsetLeft : if they are equal, then we just found desired TextInfo. Otherwise we use tmpInfo as the middle point of binary search and we recurse either to the left or to the right, depending where desired offset lies.
One extra part of the algorithm serves to prevent certain conditions: if we happen to move on the step 1 from the same point twice in two consecutive iterations of the loop, then on the second time we will move tmpInfo exactly to the opposite end of info, and the algorithm will fail on sanity check condition in the for loop. To avoid this situation we track last move and the direction of last divide in variables lastMove and lastRecursed. If we detect that we are about to move from the same endpoint for the second time, we reduce the count of characters in order to make sure the algorithm makes some progress on each iteration.
- NVDAObjectAtStart: NVDAObjects.NVDAObject
Typing information for auto-property: _get_NVDAObjectAtStart
- _abc_impl = <_abc._abc_data object>
- bookmark
- pointAtStart
- class compoundDocuments.TreeCompoundTextInfo(*args, **kwargs)
Bases:
CompoundTextInfo
Constructor. Subclasses must extend this, calling the superclass method first. @param position: The initial position of this range; one of the POSITION_* constants or a position object supported by the implementation. @param obj: The object containing the range of text being represented.
- SINGLE_TEXTINFO_UNITS = ('character', 'word', 'line', 'sentence', 'paragraph')
Units contained within a single TextInfo.
- _findContentDescendant(obj)
- _abc_impl = <_abc._abc_data object>
- _getTextInfos()
- boundingRects
- text: str
Typing information for auto-property: _get_text
- _get_text()
The text with in this range. Subclasses must implement this. @return: The text. @note: The text is not guaranteed to be the exact length of the range in offsets.
- _getFirstEmbedIndex(info)
- getTextWithFields(formatConfig: Dict | None = None) List[str | FieldCommand]
Retrieves the text in this range, as well as any control/format fields associated therewith. Subclasses may override this. The base implementation just returns the text. @param formatConfig: Document formatting configuration, useful if you wish to force a particular
configuration for a particular task.
@return: A sequence of text strings interspersed with associated field commands.
- _findNextContent(origin, moveBack=False)
- _getObjectPosition(obj)
- compareEndPoints(other, which)
compares one end of this range to one end of another range. Subclasses must implement this. @param other: the text range to compare with. @type other: L{TextInfo} @param which: The ends to compare; one of “startToStart”, “startToEnd”, “endToStart”, “endToEnd”. @return: -1 if this end is before other end, 1 if this end is after other end or 0 if this end and other end are the same. @rtype: int
- expand(unit)
Expands the start and end of this text info object to a given unit @param unit: a unit constant @type unit: string
- move(unit, direction, endPoint=None)
Moves one or both of the endpoints of this object by the given unit and direction. @param unit: the unit to move by; one of the UNIT_* constants. @param direction: a positive value moves forward by a number of units, a negative value moves back a number of units @type: int @param endPoint: Either None, “start” or “end”. If “start” then the start of the range is moved, if “end” then the end of the range is moved, if None - not specified then collapse to start and move both start and end. @return: The number of units moved;
negative indicates backward movement, positive indicates forward movement, 0 means no movement.
@rtype: int
- _get_boundingRects()
Per line bounding rectangles for the visible text in this range. Implementations should ensure that the bounding rectangles don’t contain off screen coordinates. @rtype: [L{locationHelper.RectLTWH}] @raise NotImplementedError: If not supported. @raise LookupError: If not available (i.e. off screen, hidden, etc.)
- class compoundDocuments.CompoundDocument(*args, **kwargs)
Bases:
EditableText
,DocumentTreeInterceptor
- _abc_impl = <_abc._abc_data object>
- caretObject
- isAlive
- TextInfo
alias of
TreeCompoundTextInfo
- _get_isAlive()
Whether this interceptor is alive. If it is not alive, it will be removed.
- _get_caretObject()
- event_treeInterceptor_gainFocus()
- event_caret(obj, nextHandler)
- event_gainFocus(obj, nextHandler)
- event_focusEntered(obj, nextHandler)
- event_stateChange(obj, nextHandler)
- event_selection(obj, nextHandler)
- event_selectionAdd(obj, nextHandler)
- event_selectionRemove(obj, nextHandler)