FindController

class FindController(**properties: Any)

Superclasses: Object

Controls text search in a WebView.

A FindController is used to search text in a WebView. You can get a FindController with get_find_controller(), and later use it to search for text using search(), or get the number of matches using count_matches(). The operations are asynchronous and trigger signals when ready, such as FindController::found-text, FindController::failed-to-find-text or FindController::counted-matches<!– –>.

Methods

class FindController
count_matches(search_text: str, find_options: int, max_match_count: int) → None

Counts the number of matches for search_text.

Counts the number of matches for search_text found in the WebView with the provided find_options. The number of matches will be provided by the FindController::counted-matches signal.

Parameters:

  • search_text – the text to look for

  • find_options – a bitmask with the FindOptions used in the search

  • max_match_count – the maximum number of matches allowed in the search

get_max_match_count() → int

Gets the maximum number of matches to report.

Gets the maximum number of matches to report during a text lookup. This number is passed as the last argument of search() or count_matches().

get_options() → int

Gets the FindOptions for the current search.

Gets a bitmask containing the FindOptions associated with the current search.

get_search_text() → str

Gets the text that find_controller is searching for.

Gets the text that find_controller is currently searching for. This text is passed to either search() or count_matches().

get_web_view() → WebView

Gets the WebView this find controller is associated to.

Do not dereference the returned instance as it belongs to the FindController.

search(search_text: str, find_options: int, max_match_count: int) → None

Looks for search_text associated with find_controller.

Looks for search_text in the WebView associated with find_controller since the beginning of the document highlighting up to max_match_count matches. The outcome of the search will be asynchronously provided by the FindController::found-text and FindController::failed-to-find-text signals.

To look for the next or previous occurrences of the same text with the same find options use search_next() and/or search_previous(). The FindController will use the same text and options for the following searches unless they are modified by another call to this method.

Note that if the number of matches is higher than max_match_count then FindController::found-text will report %G_MAXUINT matches instead of the actual number.

Callers should call search_finish() to finish the current search operation.

Parameters:

  • search_text – the text to look for

  • find_options – a bitmask with the FindOptions used in the search

  • max_match_count – the maximum number of matches allowed in the search

search_finish() → None

Finishes a find operation.

Finishes a find operation started by search(). It will basically unhighlight every text match found.

This method will be typically called when the search UI is closed/hidden by the client application.

search_next() → None

Looks for the next occurrence of the search text.

Calling this method before search() or count_matches() is a programming error.

search_previous() → None

Looks for the previous occurrence of the search text.

Calling this method before search() or count_matches() is a programming error.

Properties

class FindController
props.max_match_count: int

The maximum number of matches to report for a given search.

props.options: FindOptions

The options to be used in the search operation.

props.text: str

The current search text for this FindController.

props.web_view: WebView

The WebView this controller is associated to.

Signals

class FindController.signals
counted_matches(match_count: int) → None

This signal is emitted when the FindController has counted the number of matches for a given text after a call to count_matches().

Parameters:

match_count – the number of matches of the search text

failed_to_find_text() → None

This signal is emitted when a search operation does not find any result for the given text. It will be issued if the text is not found asynchronously after a call to search(), search_next() or search_previous().

found_text(match_count: int) → None

This signal is emitted when a given text is found in the web page text. It will be issued if the text is found asynchronously after a call to search(), search_next() or search_previous().

Parameters:

match_count – the number of matches found of the search text