FindController
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 theWebView
with the providedfind_options
. The number of matches will be provided by theFindController
::counted-matches signal.- Parameters:
search_text – the text to look for
find_options – a bitmask with the
FindOptions
used in the searchmax_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()
orcount_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 eithersearch()
orcount_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 withfind_controller
.Looks for
search_text
in theWebView
associated withfind_controller
since the beginning of the document highlighting up tomax_match_count
matches. The outcome of the search will be asynchronously provided by theFindController
::found-text andFindController
::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/orsearch_previous()
. TheFindController
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
thenFindController
::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 searchmax_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()
orcount_matches()
is a programming error.
- search_previous() None
Looks for the previous occurrence of the search text.
Calling this method before
search()
orcount_matches()
is a programming error.
Properties
- class FindController
-
- props.options: FindOptions
The options to be used in the search operation.
- props.text: str
The current search text for this
FindController
.
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 tocount_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()
orsearch_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()
orsearch_previous()
.- Parameters:
match_count – the number of matches found of the search text