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:

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 */

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

Errors and notices