WebKitFindController: WebKit2GTK+ Reference Manual

## WebKitFindController WebKitFindController — Controls text search in a WebKitWebView |

## Functions

void | webkit_find_controller_search ()
void | webkit_find_controller_search_finish ()
void | webkit_find_controller_search_next ()
void | webkit_find_controller_search_previous ()
const gchar * | webkit_find_controller_get_search_text ()
void | webkit_find_controller_count_matches ()
guint32 | webkit_find_controller_get_options ()
guint | webkit_find_controller_get_max_match_count ()
WebKitWebView * | webkit_find_controller_get_web_view ()

## Properties

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

## Signals

void | counted-matches | Run Last
void | failed-to-find-text | Run Last
void | found-text | Run Last

## Types and Values

| WebKitFindController
enum | WebKitFindOptions

## Object Hierarchy

        GObject
        ╰── WebKitFindController

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

## Functions

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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()`.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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()`.

#### Parameters

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 dereference the returned instance as it belongs to the WebKitFindController.

#### Parameters

find_controller | the WebKitFindController |

#### Returns

the WebKitWebView.

[transfer none]

## Types and Values

### WebKitFindController

    typedef struct _WebKitFindController WebKitFindController;

### enum WebKitFindOptions

Enum values used to specify search options.

#### Members

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

## Property Details

### The `“max-match-count”` property

      “max-match-count”          guint

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

Flags: Read

Default value: 0

### The `“options”` property

      “options”                  WebKitFindOptions

The options to be used in the search operation.

Flags: Read

### The `“text”` property

      “text”                     gchar *

The current search text for this WebKitFindController.

Flags: Read

Default value: NULL

### The `“web-view”` property

      “web-view”                 WebKitWebView *

The WebKitWebView this controller is associated to.

Flags: Read / Write / Construct Only

## Signal Details

### The `“counted-matches”` signal

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

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()`.

#### Parameters

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

Flags: Run Last

### The `“failed-to-find-text”` signal

    void
    user_function (WebKitFindController *find_controller,
                   gpointer              user_data)

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()`.

#### Parameters

find_controller | the WebKitFindController |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“found-text”` signal

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

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()`.

#### Parameters

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

Flags: Run Last