Locations

A location is a number that names one element of your frame. Instructions act on the element named by their location field. Location 0 is the body element.

Who gives an element its location

Your application does, through libhipe, without asking the display server. Each session has its own pool of numbers. An element gets a location only when you give it one:

How the element is created	How it gets its location
`HIPE_OP_APPEND_TAG`, `HIPE_OP_INSERT_TAG`	Automatically. Read it with `hipe_newest_location()` straight after sending.
Markup (`HIPE_OP_SET_TEXT` / `HIPE_OP_APPEND_TEXT` mode 3)	Reserve numbers with `hipe_reserve_location()` or `hipe_reserve_locations()`, write `hipe-loc="N"` on the elements, and list the numbers in `arg[2]`, e.g. with `hipe_send_markup()`.
Anything else: markup elements without `hipe-loc`, elements the HTML parser adds, elements created by the user's editing or pasting	None. They can't be named in instructions.

Lookups (HIPE_OP_GET_BY_ID, HIPE_OP_GET_FIRST_CHILD, HIPE_OP_GET_LAST_CHILD, HIPE_OP_GET_NEXT_SIBLING, HIPE_OP_GET_PREV_SIBLING) return an element's location, or 0 if it has none. They never give an element a location.

Each element has at most one location and each location names at most one element, so two locations are equal exactly when they name the same element.

Numbering markup

hipe_loc rows = hipe_reserve_locations(session, 3);
hipe_loc list[3] = {rows, rows+1, rows+2};
/* markup: <div hipe-loc="(rows)">...</div><div hipe-loc="(rows+1)">...</div>... */
hipe_send_markup(session, fileList, markup, 0, list, 3);
hipe_send(session, HIPE_OP_EVENT_REQUEST, 0, rows, 1, "click"); /* usable straight away */

Case	Result
A listed number is on an element	The element gets that location. The `hipe-loc` attribute is removed.
A listed number is on no element (the HTML parser dropped the element, or the number wasn't used)	The location names no element: instructions sent to it do nothing. Free it as usual. The server reports it (see "Errors and notices").
A listed number is on two elements	The first gets it. Reported.
A `hipe-loc` number that isn't listed	Ignored, and the attribute is removed.
A listed number is already in use, or the list is malformed	Fatal: your application is disconnected (see "Errors and notices").

hipe-loc never stays in the document. It is removed as markup is inserted, and HIPE_OP_SET_ATTRIBUTE refuses it. So HTML you pass through, such as text a user pasted, can't take over your locations.

A list in arg[2] (and in HIPE_OP_FREE_LOCATION) is comma-separated numbers and ranges, with no spaces: "57", "57,58,93", "1000-1499", "57,1000-1499". Each number may appear once.

Freeing locations

Free a location with HIPE_OP_FREE_LOCATION when you no longer need it. Many at once: arg[0] = "1000-1499". All of a session's locations are freed when it closes.

Locations in removed content stay in use until you free them. Only your application knows which copies of a number it still holds, so a number never becomes free by itself. When HIPE_OP_SET_TEXT replaces an element's contents, or an element is deleted, locations inside it still name the removed elements while anything keeps them (for example the undo history, which may bring them back); instructions sent to them have no visible effect. Once nothing keeps them, they name no element. To re-render a region, free its old locations in one instruction and reserve new ones.

Freeing a location also takes it off its element. If the element comes back into the document later (for example, the user undoes the deletion of a paragraph), it comes back with no location, so it can never be confused with an element you have since given that number.

Locations and events

Event requests belong to the element, not its location number: an event is reported with the location the element has when the event happens.
Freeing a location you still want events from silences them: after HIPE_OP_FREE_LOCATION the element's events are no longer reported.
A location number reused for another element never receives the old element's events.

Limits

Limit	Value
Locations in use in one frame	4,194,304. Going over is fatal.
Location numbers	1 and up, below 2⁶³ (the top bit is reserved). libhipe always gives valid numbers.

Errors and notices

Kind	What happens
Fatal: a number already in use, a malformed list, too many locations	The server sends `HIPE_OP_SERVER_DENIED` with the reason and disconnects. libhipe prints the reason to stderr, and `hipe_last_error()` returns it.
Not fatal: a listed number found on no element, or used twice	The server sends `HIPE_OP_SERVER_NOTICE`. libhipe prints it to stderr.