WebKitFindController

WebKitFindController — Controls text search in a WebKitWebView

Synopsis

                    WebKitFindController;
enum                WebKitFindOptions;
void                webkit_find_controller_search       (WebKitFindController *find_controller,
                                                         const gchar *search_text,
                                                         guint32 find_options,
                                                         guint max_match_count);
void                webkit_find_controller_search_finish
                                                        (WebKitFindController *find_controller);
void                webkit_find_controller_search_next  (WebKitFindController *find_controller);
void                webkit_find_controller_search_previous
                                                        (WebKitFindController *find_controller);
const gchar *       webkit_find_controller_get_search_text
                                                        (WebKitFindController *find_controller);
void                webkit_find_controller_count_matches
                                                        (WebKitFindController *find_controller,
                                                         const gchar *search_text,
                                                         guint32 find_options,
                                                         guint max_match_count);
guint32             webkit_find_controller_get_options  (WebKitFindController *find_controller);
guint               webkit_find_controller_get_max_match_count
                                                        (WebKitFindController *find_controller);
WebKitWebView *     webkit_find_controller_get_web_view (WebKitFindController *find_controller);

Object Hierarchy

  GObject
   +----WebKitFindController

Properties

  "max-match-count"          guint                 : Read
  "options"                  WebKitFindOptions     : Read
  "text"                     gchar*                : Read
  "web-view"                 WebKitWebView*        : Read / Write / Construct Only

Signals

  "counted-matches"                                : Run Last
  "failed-to-find-text"                            : Run Last
  "found-text"                                     : Run Last

Description

A WebKitFindController is used to search text in a WebKitWebView. You can get a WebKitWebView's WebKitFindController with webkit_web_view_get_find_controller(), and later use it to search for text using webkit_find_controller_search(), or get the number of matches using webkit_find_controller_count_matches(). The operations are asynchronous and trigger signals when ready, such as "found-text", "failed-to-find-text" or "counted-matches".

Details

WebKitFindController

typedef struct _WebKitFindController WebKitFindController;


enum WebKitFindOptions

typedef enum {
  WEBKIT_FIND_OPTIONS_NONE,

  WEBKIT_FIND_OPTIONS_CASE_INSENSITIVE =                   1 << 0,
  WEBKIT_FIND_OPTIONS_AT_WORD_STARTS =                     1 << 1,
  WEBKIT_FIND_OPTIONS_TREAT_MEDIAL_CAPITAL_AS_WORD_START = 1 << 2,
  WEBKIT_FIND_OPTIONS_BACKWARDS =                          1 << 3,
  WEBKIT_FIND_OPTIONS_WRAP_AROUND =                        1 << 4,
} WebKitFindOptions;

Enum values used to specify search options.

WEBKIT_FIND_OPTIONS_NONE

no search flags, this means a case sensitive, no wrap, forward only search.

WEBKIT_FIND_OPTIONS_CASE_INSENSITIVE

case insensitive search.

WEBKIT_FIND_OPTIONS_AT_WORD_STARTS

search text only at the begining of the words.

WEBKIT_FIND_OPTIONS_TREAT_MEDIAL_CAPITAL_AS_WORD_START

treat capital letters in the middle of words as word start.

WEBKIT_FIND_OPTIONS_BACKWARDS

search backwards.

WEBKIT_FIND_OPTIONS_WRAP_AROUND

if not present search will stop at the end of the document.

webkit_find_controller_search ()

void                webkit_find_controller_search       (WebKitFindController *find_controller,
                                                         const gchar *search_text,
                                                         guint32 find_options,
                                                         guint max_match_count);

Looks for search_text in the WebKitWebView 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 "found-text" and "failed-to-find-text" signals.

To look for the next or previous occurrences of the same text with the same find options use webkit_find_controller_search_next() and/or webkit_find_controller_search_previous(). The WebKitFindController 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 "found-text" will report G_MAXUINT matches instead of the actual number.

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

find_controller :

the WebKitFindController

search_text :

the text to look for

find_options :

a bitmask with the WebKitFindOptions used in the search

max_match_count :

the maximum number of matches allowed in the search

webkit_find_controller_search_finish ()

void                webkit_find_controller_search_finish
                                                        (WebKitFindController *find_controller);

Finishes a find operation started by webkit_find_controller_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.

find_controller :

a WebKitFindController

webkit_find_controller_search_next ()

void                webkit_find_controller_search_next  (WebKitFindController *find_controller);

Looks for the next occurrence of the search text.

Calling this method before webkit_find_controller_search() or webkit_find_controller_count_matches() is a programming error.

find_controller :

the WebKitFindController

webkit_find_controller_search_previous ()

void                webkit_find_controller_search_previous
                                                        (WebKitFindController *find_controller);

Looks for the previous occurrence of the search text.

Calling this method before webkit_find_controller_search() or webkit_find_controller_count_matches() is a programming error.

find_controller :

the WebKitFindController

webkit_find_controller_get_search_text ()

const gchar *       webkit_find_controller_get_search_text
                                                        (WebKitFindController *find_controller);

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

find_controller :

the WebKitFindController

Returns :

the text to look for in the WebKitWebView.

webkit_find_controller_count_matches ()

void                webkit_find_controller_count_matches
                                                        (WebKitFindController *find_controller,
                                                         const gchar *search_text,
                                                         guint32 find_options,
                                                         guint max_match_count);

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

find_controller :

the WebKitFindController

search_text :

the text to look for

find_options :

a bitmask with the WebKitFindOptions used in the search

max_match_count :

the maximum number of matches allowed in the search

webkit_find_controller_get_options ()

guint32             webkit_find_controller_get_options  (WebKitFindController *find_controller);

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

find_controller :

the WebKitFindController

Returns :

a bitmask containing the WebKitFindOptions associated with the current search.

webkit_find_controller_get_max_match_count ()

guint               webkit_find_controller_get_max_match_count
                                                        (WebKitFindController *find_controller);

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

find_controller :

the WebKitFindController

Returns :

the maximum number of matches to report.

webkit_find_controller_get_web_view ()

WebKitWebView *     webkit_find_controller_get_web_view (WebKitFindController *find_controller);

Gets the WebKitWebView this find controller is associated to. Do not unref the returned instance as it belongs to the WebKitFindController.

find_controller :

the WebKitFindController

Returns :

the WebKitWebView. [transfer none]

Property Details

The "max-match-count" property

  "max-match-count"          guint                 : Read

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

Default value: 0


The "options" property

  "options"                  WebKitFindOptions     : Read

The options to be used in the search operation.


The "text" property

  "text"                     gchar*                : Read

The current search text for this WebKitFindController.

Default value: NULL


The "web-view" property

  "web-view"                 WebKitWebView*        : Read / Write / Construct Only

The WebKitWebView this controller is associated to.

Signal Details

The "counted-matches" signal

void                user_function                      (WebKitFindController *find_controller,
                                                        guint                 match_count,
                                                        gpointer              user_data)            : Run Last

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

find_controller :

the WebKitFindController

match_count :

the number of matches of the search text

user_data :

user data set when the signal handler was connected.

The "failed-to-find-text" signal

void                user_function                      (WebKitFindController *find_controller,
                                                        gpointer              user_data)            : Run Last

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 webkit_find_controller_search(), webkit_find_controller_search_next() or webkit_find_controller_search_previous().

find_controller :

the WebKitFindController

user_data :

user data set when the signal handler was connected.

The "found-text" signal

void                user_function                      (WebKitFindController *find_controller,
                                                        guint                 match_count,
                                                        gpointer              user_data)            : Run Last

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 webkit_find_controller_search(), webkit_find_controller_search_next() or webkit_find_controller_search_previous().

find_controller :

the WebKitFindController

match_count :

the number of matches found of the search text

user_data :

user data set when the signal handler was connected.