Instruction set reference
HIPE_OP_GET_CONTENT
Requests the inner content of an element. The server responds with a HIPE_OP_CONTENT_RETURN instruction containing the requested content.
- location: The element whose content is being requested.
- arg[0]: Selects the format the content should be returned in:
- 0 (or left blank) — unformatted plain text (default): all the text inside the element, exactly as stored, whether or not it is displayed. Line breaks are included only where the text itself contains them; line-break tags such as <br> are not converted.
- 1 — content formatted as HTML.
- 2 — content formatted as plain text as it is laid out (preserving line breaks etc., unlike mode 0): block elements and line-break tags such as <br> become line breaks. Elements styled display:none are left out (see notes).
- 3 — the element's value attribute, rather than its inner content. This is needed for form elements such as <input> and <textarea>, where the user-entered text is held in value rather than as child content of the element.
- 4 — the changes to the element's text (as mode 0 returns it) since this client's previous mode 4 request for the element, rather than the whole text. The first request returns the whole text. See HIPE_OP_CONTENT_RETURN for the reply. Modes 0 to 3 each return a plain copy of the content; mode 4 returns a richer reply that says what changed.
- arg[1]: For mode 4 only. Pass full to get the whole text and start again from it, instead of the changes. Do this after changing the element's text yourself (e.g. replacing it with HIPE_OP_SET_TEXT), since changes are reported relative to the text of the previous mode 4 reply, which your own copy no longer matches.
Notes
Mode 4 is for editors and other clients that keep their own copy of a large text. Reading only the changes saves transferring, decoding and comparing the whole text after every edit. Apply each reply to your copy (replace arg[2] characters at arg[1] with arg[0], or replace everything when arg[3] is full), and the copy stays exactly equal to the element's text. The display server keeps the last text it returned in mode 4 for each element (freed with the location, e.g. by HIPE_OP_FREE_LOCATION).
Modes 0 and 2 both return text whether or not it is currently visible on screen, including text in an element or frame that is hidden or has never been shown. They differ in what they include: mode 0 returns every piece of text inside the element, including text inside elements styled display:none, while mode 2 leaves those out. Text styled visibility:hidden is included by both.
Mode 0 is the most faithful way to read back text that must not be lost, such as the contents of an editor. For an editable element using contenteditable="plaintext-only", line breaks are stored as real newline characters, so mode 0 returns them.