WebKit2GTK+ Reference Manual: WebKitFindController

## 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.