Instruction set reference
HIPE_OP_FIND_TEXT
Finds text in the style of a web browser's 'find on page' feature. All matches are highlighted, and the next one is selected and scrolled into view. The server replies with HIPE_OP_FIND_RESULT.
- location: Where to search. 0 searches the client's whole document. An element searches that element's content. An <iframe> that the client owns searches the content of the child client's frame. Frames nested inside the searched content are searched too, in the order they appear in the document.
- arg[0]: The text to find. An empty string removes the highlighting from the searched content and selects nothing.
- arg[1]: Search options. Any combination of these letters, or empty for none:
- b: find backwards, selecting the previous match instead of the next.
- c: match case. Without it, the search ignores case.
- w: whole words only. A match must begin and end at a word boundary.
Notes
The match selected is the first one after the current selection or text cursor within the searched content (or the last one before it, with b). If there's none, the search wraps round to the first (or last) match. If there's no selection there, the first (or last) match is selected. Sending the same instruction again therefore steps through the matches one by one. Any selection left in another frame within the searched content is removed, so the search always carries on from the latest match.
Keyboard focus doesn't move. A user can go on typing in a search box while the matches are being selected.
Each search replaces the highlighting within the searched content. Highlighting elsewhere (e.g. from a search of a different element) stays.
A client can only search its own content, including the frames of child clients it owns. It can't search the frame of its parent or of any other client.
At most 1000 matches are found. Beyond that, the reply's arg[3] is "+", and later matches aren't highlighted or reachable.
Text that can't be selected, because it has the style user-select: none, isn't searched, since a match there couldn't be selected. Use this to leave out e.g. line numbers, or a layer that repeats text shown elsewhere. The style is inherited, and user-select: text on a descendant makes its text searchable again.
Text is matched as it is laid out (as HIPE_OP_GET_CONTENT mode 2 reads it), including text in form fields, but a match can't span two frames.
Appearance
The highlighting is styled with the CSS ::search-text pseudo-element (from CSS Pseudo-Elements Level 4). It supports two properties:
- background-color: the highlight behind each match.
- color: the colour of the text within a match. If it isn't set, the text keeps its own colour.
The selected match is shown as the selection, so it's styled with ::selection instead.
The standard Hipe themes set ::search-text to suit their colours (e.g. black text on yellow). Without a rule, matches get a translucent yellow background and keep their own text colour, so they stay readable on light and dark backgrounds alike. For example, a theme or client can use:
::search-text { background-color: yellow; color: black; }
A client can override the theme for its own elements with a rule of its own (e.g. with HIPE_OP_ADD_STYLE_RULE). Each property is decided separately, so a client rule that sets only background-color still gets the theme's color: set both if the text colour matters.
A rule applies to the text directly inside the elements it selects, not to text inside their child elements: #editor::search-text doesn't style a match inside a <span> in the editor. To cover everything inside an element, include its descendants too:
#editor::search-text, #editor *::search-text { background-color: lime; color: black; }
A rule without an element selector, like the theme example above, applies everywhere.
color is also used where the text itself is invisible. For example, a code editor might have an editable layer with color: transparent above a syntax-highlighted copy of its text. There, color: black would draw matches in black over the copy, while a translucent background with color: transparent lets the copy's own colours show through:
#editor::search-text { background-color: rgba(255, 200, 60, 0.3); color: transparent; }