Instruction set reference
HIPE_OP_CARAT_POSITION
This instruction relates to the current position of the text entry carat (cursor position, or range of selected text) in an input element such as a textarea tag, or in an element with the contenteditable attribute.
The instruction may be sent to the server in order to move the text cursor position or select a range of text. It can also be received from the server in response to a HIPE_OP_GET_CARAT_POSITION instruction, to get the current text entry and/or selection position.
- location: The element for which to set the text entry carat position.
- arg[0]: Character offset of the selection's anchor: the point where the selection starts.
- arg[1]: Character offset of the selection's focus: the point where it ends, which is where the cursor is. If no text should be selected (simple cursor), use the same value as arg[0], or leave this argument empty. If arg[1] is less than arg[0], the selection is made backwards, as if the user had selected from right to left.
- arg[2]: Optional. Pass "1" to scroll the selection into view. Otherwise the view is not scrolled.
Offsets
Offsets count characters, starting from 0 before the first character. A character is a Unicode code point, which may be several bytes long in UTF-8: an offset is never a byte count.
For input and textarea elements, offsets index the element's value. For other elements, they index the element's text as it is laid out: the same text that HIPE_OP_GET_CONTENT returns in mode 2. In this text, line-break tags such as <br> and the boundaries between block elements (such as consecutive div tags) each count as one line-break character, and runs of spaces that are displayed as a single space count once. Elements styled display:none don't count.
Negative offsets count from the end of the text: -1 is the position after the last character, -2 the position before the last character, and so on. This is useful for placing the cursor at (or near) the end of the text without first having to query its length. For example, arg[0] = "0" and arg[1] = "-1" selects all the text. Offsets beyond the text are clamped to it.
Notes
If arg[0] is empty, the instruction is ignored. HIPE_OP_GET_CARAT_POSITION replies with empty arguments when the element contains neither the cursor nor selected text, so sending back what it returned never moves the selection. Arguments that aren't whole numbers are also ignored.
Setting the carat in an element with the contenteditable attribute also gives that element keyboard focus.
Some positions can't hold a cursor, and the display engine moves the cursor to the nearest one that can. For example, in a contenteditable element whose text ends with a line break, the position after that final line break has no line to appear on, so the cursor is placed before it. Similarly, a character that the user sees as one symbol may be made of several code points (such as some flags, or a letter with a separately encoded accent), and the cursor can't be placed between them.