Package at.bestsolution.uia

Interface ITextRangeProvider

public interface ITextRangeProvider
Provides access to a span of continuous text in a text container that implements ITextProvider or ITextProvider2.

  • Method Details

    • initialize

      default void initialize(ITextAttributeSupport context)

    • AddToSelection

      void AddToSelection()
      Adds the text range to the collection of selected text ranges in a control that supports multiple, disjoint spans of selected text.

    • Clone

      ITextRangeProvider Clone()
      Returns a new ITextRangeProvider identical to the original ITextRangeProvider and inheriting all properties of the original.
      Returns:
      Receives a pointer to the copy of the text range. A null reference is never returned. This parameter is passed uninitialized.

    • Compare

      boolean Compare(ITextRangeProvider other)
      Retrieves a value that specifies whether this text range has the same endpoints as another text range.
      Parameters:
      other - The text range to compare with this one.
      Returns:
      Receives TRUE if the text ranges have the same endpoints, or FALSE if they do not.

    • CompareEndpoints

      int CompareEndpoints(TextPatternRangeEndpoint endpoint, ITextRangeProvider targetRange, TextPatternRangeEndpoint targetEndpoint)
      Returns a value that specifies whether two text ranges have identical endpoints.

      Returns a negative value if the caller's endpoint occurs earlier in the text than the target endpoint. Returns zero if the caller's endpoint is at the same location as the target endpoint. Returns a positive value if the caller's endpoint occurs later in the text than the target endpoint.

      Parameters:
      endpoint - the endpoint
      targetRange - The text range to be compared.
      targetEndpoint - the target endpoint
      Returns:
      Receives a value that indicates whether the two text ranges have identical endpoints. This parameter is passed uninitialized.

    • ExpandToEnclosingUnit

      void ExpandToEnclosingUnit(TextUnit unit)
      Normalizes the text range by the specified text unit. The range is expanded if it is smaller than the specified unit, or shortened if it is longer than the specified unit.
      Parameters:
      unit - The type of text units, such as character, word, paragraph, and so on.

    • FindText

      ITextRangeProvider FindText(String text, boolean backward, boolean ignoreCase)
      Returns a text range subset that contains the specified text.
      Parameters:
      text - The text string to search for.
      backward - TRUE if the last occurring text range should be returned instead of the first; otherwise FALSE.
      ignoreCase - TRUE if case should be ignored; otherwise FALSE.
      Returns:
      Receives a pointer to the text range matching the specified text; otherwise NULL. This parameter is passed uninitialized.

    • GetBoundingRectangles

      Bounds[] GetBoundingRectangles()
      Returns:
      Receives a pointer to one of the following.
      • An array of bounding rectangles for each full or partial line of text in a text range.
      • An empty array for a degenerate range.
      • An empty array for a text range that has screen coordinates placing it completely off-screen, scrolled out of view, or obscured by an overlapping window.

    • GetChildren

      IUIAElement[] GetChildren()
      Retrieves a collection of all elements that are both contained (either partially or completely) within the specified text range, and are child elements of the enclosing element for the specified text range.
      Returns:
      An array of pointers to the IUIAElement interfaces for all child elements that are enclosed by the text range (sorted by the Start endpoint of their ranges). If the text range does not include any child elements, an empty collection is returned. This parameter is passed uninitialized.

    • GetEnclosingElement

      IUIAElement GetEnclosingElement()
      Returns the innermost element that encloses the specified text range.
      Returns:
      The UI Automation provider of the innermost element that encloses the specified ITextRangeProvider.

      Note: The enclosing element can span more than just the specified ITextRangeProvider.

      If no enclosing element is found, the ITextProvider parent of the ITextRangeProvider is returned.

    • GetText

      String GetText(int maxLength)
      Retrieves the plain text of the range.
      Parameters:
      maxLength - The maximum length of the string to return. Use -1 if no limit is required.
      Returns:
      Receives the plain text of the text range, possibly truncated at the specified maximum length. This parameter is passed uninitialized.

    • Move

      int Move(TextUnit unit, int count)
      Moves the text range forward or backward by the specified number of text units.
      Parameters:
      unit - the unit
      count - The number of text units to move. A positive value moves the text range forward. A negative value moves the text range backward. Zero has no effect.
      Returns:
      The number of text units actually moved. This can be less than the number requested if either of the new text range endpoints is greater than or less than the endpoints retrieved by the ITextProvider::DocumentRange method. This value can be negative if navigation is happening in the backward direction.

    • MoveEndpointByRange

      void MoveEndpointByRange(TextPatternRangeEndpoint endpoint, ITextRangeProvider targetRange, TextPatternRangeEndpoint targetEndpoint)
      Moves one endpoint of the current text range to the specified endpoint of a second text range.

      If the endpoint being moved crosses the other endpoint of the same text range, that other endpoint is moved also, resulting in a degenerate (empty) range and ensuring the correct ordering of the endpoints (that is, the start is always less than or equal to the end).

      Parameters:
      endpoint - the endpoint
      targetRange - A second text range from the same text provider as the current text range.
      targetEndpoint - the target endpoint

    • MoveEndpointByUnit

      int MoveEndpointByUnit(TextPatternRangeEndpoint endpoint, TextUnit unit, int count)

      The endpoint is moved forward or backward, as specified, to the next available unit boundary. If the original endpoint was at the boundary of the specified text unit, the endpoint is moved to the next available text unit boundary, as shown in the following illustration.

      Illustration showing endpoints of a text range moving If the endpoint being moved crosses the other endpoint of the same text range, the other endpoint is also moved, resulting in a degenerate range and ensuring the correct ordering of the endpoint (that is, that the start is always less than or equal to the end).

      ITextRangeProvider::MoveEndpointByUnit deprecates up to the next supported text unit if the given text unit is not supported by the control.

      The order, from smallest unit to largest, is listed here.

      • Character
      • Format
      • Word
      • Line
      • Paragraph
      • Page
      • Document
      Range behavior when unit is TextUnit::Format TextUnit::Format as a unit value positions the boundary of a text range to expand or move the range based on shared text attributes (format) of the text within the range. However, using the format text unit should not move or expand a text range across the boundary of an embedded object, such as an image or hyperlink. For more info, see UI Automation Text Units or Text and TextRange Control Patterns.
      Parameters:
      endpoint - the endpoint
      unit - the unit
      count - The number of units to move. A positive value moves the endpoint forward. A negative value moves backward. A value of 0 has no effect.
      Returns:
      Receives the number of units actually moved, which can be less than the number requested if moving the endpoint runs into the beginning or end of the document.

    • RemoveFromSelection

      void RemoveFromSelection()
      Removes the text range from the collection of selected text ranges in a control that supports multiple, disjoint spans of selected text.

    • ScrollIntoView

      void ScrollIntoView(boolean alignToTop)
      Causes the text control to scroll vertically until the text range is visible in the viewport.

      ITextRangeProvider::ScrollIntoView respects both hidden and visible text. If the text range is hidden, the text control will scroll only if the hidden text has an anchor in the viewport.

      Parameters:
      alignToTop - TRUE if the text control should be scrolled so the text range is flush with the top of the viewport; FALSE if it should be flush with the bottom of the viewport.

    • Select

      void Select()
      Selects the span of text that corresponds to this text range, and removes any previous selection.