Instruction set reference
HIPE_OP_SET_TEXT
Send this instruction to the display server to populate a tag element with the specified text string. Any existing child elements are discarded.
- location: The tag element to be populated with text.
- arg[0]: Text to be placed in the tag element.
- arg[1]: Text mode: "0" (the default, also used if the argument is empty), "1", "2" or "3". See the table below.
- arg[2]: Mode 3 only: the locations used in the markup's hipe-loc attributes, e.g. "57,1000-1499". See "Locations".
Text modes
In modes 0, 1 and 2, the characters <, >, " and ' are shown as typed. Text that looks like an HTML tag, such as <b>, is never treated as markup, so there is no need to remove such things from arg[0]. These modes differ in what happens to & and to newlines, carriage returns and tabs. In mode 3, arg[0] is HTML.
| Mode | & | Newlines, carriage returns and tabs | Text read back with HIPE_OP_GET_CONTENT |
|---|---|---|---|
| "0" | Shown as typed. | Not converted. | The same as arg[0]. |
| "1" | Shown as typed. | Converted: a newline becomes a line break, a carriage return an empty paragraph, a tab a wide space. | Differs from arg[0]: the newlines and carriage returns are now elements, not characters, and each tab is a wide space character. |
| "2" | Starts a character entity: × shows as ×, & as &. | Not converted. | arg[0] with its entities replaced by the characters they stand for. |
| "3" | Starts a character entity, as in mode 2. | Not converted. | The text of the elements arg[0] created. HIPE_OP_GET_CONTENT mode 1 returns them as HTML. |
Mode 3: markup
- arg[0] is HTML, and the tags and attributes in it are created as written, including class. Write a literal < or & in its text as < or &.
- The markup stays inside the element: unclosed tags are closed at the end of arg[0], and a closing tag can't end the element itself.
- To use an element later (request its events, set its attributes or source, get a frame key for an iframe, draw on a canvas), give it a location: write hipe-loc="N" on it with a number reserved by hipe_reserve_location(), and list the number in arg[2]. hipe_send_markup() does the listing for you. Other elements created this way have no location. See "Locations".
- Tags that do nothing in a Hipe frame, such as script, do nothing here either. See "Tags, attributes and styles".
Where newlines and tabs are not converted (modes 0 and 2), how they look depends on the element. Most elements show any run of spaces, tabs and newlines as a single space, as HTML normally does. An element that keeps whitespace, such as a pre tag or one styled with white-space: pre, shows them as line breaks and tab stops.
Also in modes 0 and 2, a carriage return is stored as a newline, and a carriage return followed by a newline is stored as one newline.
In every mode, the character U+2029 starts a new paragraph, with a gap or an indent set by CSS, in any element. See "Paragraph breaks" on the "Tags, attributes and styles" page.
Which mode to use
- Mode 0 for most text, and for any text that will be read back or edited and must come back the same, such as a source file shown in a pre tag. To show a symbol, put the character itself in the text: arguments are UTF-8. Also for the CSS of a style tag: modes 1 and 2 would change it.
- Mode 1 for showing text you don't control, such as an error message or a command's output, in an ordinary element with its line breaks and tabs visible and no styling of your own.
- Mode 2 for text you write yourself, where you want symbols by name, such as a calculator button labelled ×. Don't use it for text that may contain & for any other reason: some older entity names are recognised without their closing semicolon, so ¶m shows as ¶m and ×, as ×,.
- Mode 3 for formatted text sent in one instruction, such as syntax-highlighted code as span tags with classes, or HTML you already have.
Notes
Some tags like the input tag don't accept text directly. The input tag requires text to be supplied through a special value attribute. Use HIPE_OP_SET_ATTRIBUTE instead for such tags.