TextProtocol

public protocol TextProtocol

AtkText should be implemented by AtkObjects on behalf of widgets that have text content which is either attributed or otherwise non-trivial. AtkObjects whose text content is simple, unattributed, and very brief may expose that content via atk_object_get_name instead; however if the text is editable, multi-line, typically longer than three or four words, attributed, selectable, or if the object already uses the ‘name’ ATK property for other information, the AtkText interface should be used to expose the text content. In the case of editable text content, AtkEditableText (a subtype of the AtkText interface) should be implemented instead.

AtkText provides not only traversal facilities and change notification for text content, but also caret tracking and glyph bounding box calculations. Note that the text strings are exposed as UTF-8, and are therefore potentially multi-byte, and caret-to-byte offset mapping makes no assumptions about the character length; also bounding box glyph-to-offset mapping may be complex for languages which use ligatures.

The TextProtocol protocol exposes the methods and properties of an underlying AtkText instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see Text. Alternatively, use TextRef as a lighweight, unowned reference if you already have an instance you just want to use.

Show on GitHub
  • ptr

    Untyped pointer to the underlying AtkText instance.

    Declaration

    Swift

    var ptr: UnsafeMutableRawPointer! { get }
    Show on GitHub
  • text_ptr Default implementation

    Typed pointer to the underlying AtkText instance.

    Default Implementation

    Return the stored, untyped pointer as a typed pointer to the AtkText instance.

    Declaration

    Swift

    var text_ptr: UnsafeMutablePointer<AtkText>! { get }
    Show on GitHub

  • Required Initialiser for types conforming to TextProtocol

    Declaration

    Swift

    init(raw: UnsafeMutableRawPointer)
    Show on GitHub

Text signals

  • Connect a Swift signal handler to the given, typed TextSignalName signal

    Declaration

    Swift

    @discardableResult
@inlinable
func connect(signal s: TextSignalName, flags f: ConnectFlags = ConnectFlags(0), handler h: @escaping SignalHandler) -> Int

    Parameters

    signal

    The signal to connect
    flags

    The connection flags to use
    data

    A pointer to user data to provide to the callback
    destroyData

    A GClosureNotify C function to destroy the data pointed to by userData
    handler

    The Swift signal handler (function or callback) to invoke on the given signal

    Return Value

    The signal handler ID (always greater than 0 for successful connections)

    Show on GitHub

  • Connect a C signal handler to the given, typed TextSignalName signal

    Declaration

    Swift

    @discardableResult
@inlinable
func connect(signal s: TextSignalName, flags f: ConnectFlags = ConnectFlags(0), data userData: gpointer!, destroyData destructor: GClosureNotify? = nil, signalHandler h: @escaping GCallback) -> Int

    Parameters

    signal

    The signal to connect
    flags

    The connection flags to use
    data

    A pointer to user data to provide to the callback
    destroyData

    A GClosureNotify C function to destroy the data pointed to by userData
    signalHandler

    The C function to be called on the given signal

    Return Value

    The signal handler ID (always greater than 0 for successful connections)

    Show on GitHub

  • The “text-attributes-changed” signal is emitted when the text attributes of the text of an object which implements AtkText changes.

    Note

    This represents the underlying text-attributes-changed signal

    Declaration

    Swift

    @discardableResult
@inlinable
func onTextAttributesChanged(flags: ConnectFlags = ConnectFlags(0), handler: @escaping (_ unownedSelf: TextRef) -> Void) -> Int

    Parameters

    flags

    Flags
    unownedSelf

    Reference to instance of self
    handler

    The signal handler to call Run the given callback whenever the textAttributesChanged signal is emitted
    Show on GitHub
  • textAttributesChangedSignal Extension method

    Typed text-attributes-changed signal for using the connect(signal:) methods

    Declaration

    Swift

    static var textAttributesChangedSignal: TextSignalName { get }
    Show on GitHub

  • The “text-caret-moved” signal is emitted when the caret position of the text of an object which implements AtkText changes.

    Note

    This represents the underlying text-caret-moved signal

    Declaration

    Swift

    @discardableResult
@inlinable
func onTextCaretMoved(flags: ConnectFlags = ConnectFlags(0), handler: @escaping (_ unownedSelf: TextRef, _ arg1: Int) -> Void) -> Int

    Parameters

    flags

    Flags
    unownedSelf

    Reference to instance of self
    arg1

    The new position of the text caret.
    handler

    The signal handler to call Run the given callback whenever the textCaretMoved signal is emitted
    Show on GitHub
  • textCaretMovedSignal Extension method

    Typed text-caret-moved signal for using the connect(signal:) methods

    Declaration

    Swift

    static var textCaretMovedSignal: TextSignalName { get }
    Show on GitHub

  • The “text-changed” signal is emitted when the text of the object which implements the AtkText interface changes, This signal will have a detail which is either “insert” or “delete” which identifies whether the text change was an insertion or a deletion.

    Note

    This represents the underlying text-changed signal

    Declaration

    Swift

    @discardableResult
@inlinable
func onTextChanged(flags: ConnectFlags = ConnectFlags(0), handler: @escaping (_ unownedSelf: TextRef, _ arg1: Int, _ arg2: Int) -> Void) -> Int

    Parameters

    flags

    Flags
    unownedSelf

    Reference to instance of self
    arg1

    The position (character offset) of the insertion or deletion.
    arg2

    The length (in characters) of text inserted or deleted.
    handler

    The signal handler to call Run the given callback whenever the textChanged signal is emitted
    Show on GitHub
  • textChangedSignal Extension method

    Typed text-changed signal for using the connect(signal:) methods

    Declaration

    Swift

    static var textChangedSignal: TextSignalName { get }
    Show on GitHub
  • onTextInsert(flags:handler:) Extension method

    The “text-insert” signal is emitted when a new text is inserted. If the signal was not triggered by the user (e.g. typing or pasting text), the “system” detail should be included.

    Note

    This represents the underlying text-insert signal

    Declaration

    Swift

    @discardableResult
@inlinable
func onTextInsert(flags: ConnectFlags = ConnectFlags(0), handler: @escaping (_ unownedSelf: TextRef, _ arg1: Int, _ arg2: Int, _ arg3: String) -> Void) -> Int

    Parameters

    flags

    Flags
    unownedSelf

    Reference to instance of self
    arg1

    The position (character offset) of the insertion.
    arg2

    The length (in characters) of text inserted.
    arg3

    The new text inserted
    handler

    The signal handler to call Run the given callback whenever the textInsert signal is emitted
    Show on GitHub
  • textInsertSignal Extension method

    Typed text-insert signal for using the connect(signal:) methods

    Declaration

    Swift

    static var textInsertSignal: TextSignalName { get }
    Show on GitHub
  • onTextRemove(flags:handler:) Extension method

    The “text-remove” signal is emitted when a new text is removed. If the signal was not triggered by the user (e.g. typing or pasting text), the “system” detail should be included.

    Note

    This represents the underlying text-remove signal

    Declaration

    Swift

    @discardableResult
@inlinable
func onTextRemove(flags: ConnectFlags = ConnectFlags(0), handler: @escaping (_ unownedSelf: TextRef, _ arg1: Int, _ arg2: Int, _ arg3: String) -> Void) -> Int

    Parameters

    flags

    Flags
    unownedSelf

    Reference to instance of self
    arg1

    The position (character offset) of the removal.
    arg2

    The length (in characters) of text removed.
    arg3

    The old text removed
    handler

    The signal handler to call Run the given callback whenever the textRemove signal is emitted
    Show on GitHub
  • textRemoveSignal Extension method

    Typed text-remove signal for using the connect(signal:) methods

    Declaration

    Swift

    static var textRemoveSignal: TextSignalName { get }
    Show on GitHub

  • The “text-selection-changed” signal is emitted when the selected text of an object which implements AtkText changes.

    Note

    This represents the underlying text-selection-changed signal

    Declaration

    Swift

    @discardableResult
@inlinable
func onTextSelectionChanged(flags: ConnectFlags = ConnectFlags(0), handler: @escaping (_ unownedSelf: TextRef) -> Void) -> Int

    Parameters

    flags

    Flags
    unownedSelf

    Reference to instance of self
    handler

    The signal handler to call Run the given callback whenever the textSelectionChanged signal is emitted
    Show on GitHub
  • textSelectionChangedSignal Extension method

    Typed text-selection-changed signal for using the connect(signal:) methods

    Declaration

    Swift

    static var textSelectionChangedSignal: TextSignalName { get }
    Show on GitHub

Text Interface: TextProtocol extension (methods and fields)

  • Adds a selection bounded by the specified offsets.

    Declaration

    Swift

    @inlinable
func addSelection(startOffset: Int, endOffset: Int) -> Bool
    Show on GitHub

  • Get the ranges of text in the specified bounding box.

    Declaration

    Swift

    @inlinable
func getBoundedRanges<TextRectangleT>(rect: TextRectangleT, coordType: AtkCoordType, xClipType: AtkTextClipType, yClipType: AtkTextClipType) -> UnsafeMutablePointer<UnsafeMutablePointer<AtkTextRange>?>! where TextRectangleT : TextRectangleProtocol
    Show on GitHub
  • getCaretOffset() Extension method

    Gets the offset of the position of the caret (cursor).

    Declaration

    Swift

    @inlinable
func getCaretOffset() -> Int
    Show on GitHub
  • getCharacterAt(offset:) Extension method

    Gets the specified text.

    Declaration

    Swift

    @inlinable
func getCharacterAt(offset: Int) -> gunichar
    Show on GitHub
  • getCharacterCount() Extension method

    Gets the character count.

    Declaration

    Swift

    @inlinable
func getCharacterCount() -> Int
    Show on GitHub

  • If the extent can not be obtained (e.g. missing support), all of x, y, width, height are set to -1.

    Get the bounding box containing the glyph representing the character at a particular text offset.

    Declaration

    Swift

    @inlinable
func getCharacterExtents(offset: Int, x: UnsafeMutablePointer<gint>! = nil, y: UnsafeMutablePointer<gint>! = nil, width: UnsafeMutablePointer<gint>! = nil, height: UnsafeMutablePointer<gint>! = nil, coords: AtkCoordType)
    Show on GitHub
  • getDefaultAttributes() Extension method

    Creates an AtkAttributeSet which consists of the default values of attributes for the text. See the enum AtkTextAttribute for types of text attributes that can be returned. Note that other attributes may also be returned.

    Declaration

    Swift

    @inlinable
func getDefaultAttributes() -> UnsafeMutablePointer<AtkAttributeSet>!
    Show on GitHub
  • getNSelections() Extension method

    Gets the number of selected regions.

    Declaration

    Swift

    @inlinable
func getNSelections() -> Int
    Show on GitHub

  • Gets the offset of the character located at coordinates x and y. x and y are interpreted as being relative to the screen or this widget’s window depending on coords.

    Declaration

    Swift

    @inlinable
func getOffsetAtPoint(x: Int, y: Int, coords: AtkCoordType) -> Int
    Show on GitHub

  • Get the bounding box for text within the specified range.

    If the extents can not be obtained (e.g. or missing support), the rectangle fields are set to -1.

    Declaration

    Swift

    @inlinable
func getRangeExtents<TextRectangleT>(startOffset: Int, endOffset: Int, coordType: AtkCoordType, rect: TextRectangleT) where TextRectangleT : TextRectangleProtocol
    Show on GitHub

  • Creates an AtkAttributeSet which consists of the attributes explicitly set at the position offset in the text. start_offset and end_offset are set to the start and end of the range around offset where the attributes are invariant. Note that end_offset is the offset of the first character after the range. See the enum AtkTextAttribute for types of text attributes that can be returned. Note that other attributes may also be returned.

    Declaration

    Swift

    @inlinable
func getRunAttributes(offset: Int, startOffset: UnsafeMutablePointer<gint>!, endOffset: UnsafeMutablePointer<gint>!) -> UnsafeMutablePointer<AtkAttributeSet>!
    Show on GitHub

  • Gets the text from the specified selection.

    Declaration

    Swift

    @inlinable
func getSelection(selectionNum: Int, startOffset: UnsafeMutablePointer<gint>!, endOffset: UnsafeMutablePointer<gint>!) -> String!
    Show on GitHub

  • Gets a portion of the text exposed through an AtkText according to a given offset and a specific granularity, along with the start and end offsets defining the boundaries of such a portion of text.

    If granularity is ATK_TEXT_GRANULARITY_CHAR the character at the offset is returned.

    If granularity is ATK_TEXT_GRANULARITY_WORD the returned string is from the word start at or before the offset to the word start after the offset.

    The returned string will contain the word at the offset if the offset is inside a word and will contain the word before the offset if the offset is not inside a word.

    If granularity is ATK_TEXT_GRANULARITY_SENTENCE the returned string is from the sentence start at or before the offset to the sentence start after the offset.

    The returned string will contain the sentence at the offset if the offset is inside a sentence and will contain the sentence before the offset if the offset is not inside a sentence.

    If granularity is ATK_TEXT_GRANULARITY_LINE the returned string is from the line start at or before the offset to the line start after the offset.

    If granularity is ATK_TEXT_GRANULARITY_PARAGRAPH the returned string is from the start of the paragraph at or before the offset to the start of the following paragraph after the offset.

    Declaration

    Swift

    @inlinable
func getStringAt(offset: Int, granularity: AtkTextGranularity, startOffset: UnsafeMutablePointer<gint>!, endOffset: UnsafeMutablePointer<gint>!) -> String!
    Show on GitHub

  • Gets the specified text.

    Declaration

    Swift

    @inlinable
func getText(startOffset: Int, endOffset: Int) -> String!
    Show on GitHub

  • Gets the specified text.

    get_text_after_offset is deprecated: Please use atk_text_get_string_at_offset() instead.

    Declaration

    Swift

    @available(*, deprecated)
@inlinable
func getTextAfter(offset: Int, boundaryType: AtkTextBoundary, startOffset: UnsafeMutablePointer<gint>!, endOffset: UnsafeMutablePointer<gint>!) -> String!
    Show on GitHub

  • Gets the specified text.

    If the boundary_type if ATK_TEXT_BOUNDARY_CHAR the character at the offset is returned.

    If the boundary_type is ATK_TEXT_BOUNDARY_WORD_START the returned string is from the word start at or before the offset to the word start after the offset.

    The returned string will contain the word at the offset if the offset is inside a word and will contain the word before the offset if the offset is not inside a word.

    If the boundary type is ATK_TEXT_BOUNDARY_SENTENCE_START the returned string is from the sentence start at or before the offset to the sentence start after the offset.

    The returned string will contain the sentence at the offset if the offset is inside a sentence and will contain the sentence before the offset if the offset is not inside a sentence.

    If the boundary type is ATK_TEXT_BOUNDARY_LINE_START the returned string is from the line start at or before the offset to the line start after the offset.

    get_text_at_offset is deprecated: This method is deprecated since ATK version 2.9.4. Please use atk_text_get_string_at_offset() instead.

    Declaration

    Swift

    @available(*, deprecated)
@inlinable
func getTextAt(offset: Int, boundaryType: AtkTextBoundary, startOffset: UnsafeMutablePointer<gint>!, endOffset: UnsafeMutablePointer<gint>!) -> String!
    Show on GitHub

  • Gets the specified text.

    get_text_before_offset is deprecated: Please use atk_text_get_string_at_offset() instead.

    Declaration

    Swift

    @available(*, deprecated)
@inlinable
func getTextBefore(offset: Int, boundaryType: AtkTextBoundary, startOffset: UnsafeMutablePointer<gint>!, endOffset: UnsafeMutablePointer<gint>!) -> String!
    Show on GitHub

  • Removes the specified selection.

    Declaration

    Swift

    @inlinable
func removeSelection(selectionNum: Int) -> Bool
    Show on GitHub

  • Makes a substring of text visible on the screen by scrolling all necessary parents.

    Declaration

    Swift

    @inlinable
func scrollSubstringTo(startOffset: Int, endOffset: Int, type: AtkScrollType) -> Bool
    Show on GitHub

  • Move the top-left of a substring of text to a given position of the screen by scrolling all necessary parents.

    Declaration

    Swift

    @inlinable
func scrollSubstringToPoint(startOffset: Int, endOffset: Int, coords: AtkCoordType, x: Int, y: Int) -> Bool
    Show on GitHub
  • setCaret(offset:) Extension method

    Sets the caret (cursor) position to the specified offset.

    In the case of rich-text content, this method should either grab focus or move the sequential focus navigation starting point (if the application supports this concept) as if the user had clicked on the new caret position. Typically, this means that the target of this operation is the node containing the new caret position or one of its ancestors. In other words, after this method is called, if the user advances focus, it should move to the first focusable node following the new caret position.

    Calling this method should also scroll the application viewport in a way that matches the behavior of the application’s typical caret motion or tab navigation as closely as possible. This also means that if the application’s caret motion or focus navigation does not trigger a scroll operation, this method should not trigger one either. If the application does not have a caret motion or focus navigation operation, this method should try to scroll the new caret position into view while minimizing unnecessary scroll motion.

    Declaration

    Swift

    @inlinable
func setCaret(offset: Int) -> Bool
    Show on GitHub

  • Changes the start and end offset of the specified selection.

    Declaration

    Swift

    @inlinable
func setSelection(selectionNum: Int, startOffset: Int, endOffset: Int) -> Bool
    Show on GitHub
  • caretOffset Extension method

    Gets the offset of the position of the caret (cursor).

    Declaration

    Swift

    @inlinable
var caretOffset: Int { get nonmutating set }
    Show on GitHub
  • characterCount Extension method

    Gets the character count.

    Declaration

    Swift

    @inlinable
var characterCount: Int { get }
    Show on GitHub
  • defaultAttributes Extension method

    Creates an AtkAttributeSet which consists of the default values of attributes for the text. See the enum AtkTextAttribute for types of text attributes that can be returned. Note that other attributes may also be returned.

    Declaration

    Swift

    @inlinable
var defaultAttributes: UnsafeMutablePointer<AtkAttributeSet>! { get }
    Show on GitHub
  • nSelections Extension method

    Gets the number of selected regions.

    Declaration

    Swift

    @inlinable
var nSelections: Int { get }
    Show on GitHub