tbl_obj_mark
[0|1] = tbl_obj_mark (toId, newRegion, primarySelection, doInvert)
This function begins or ends a mark operation on a rectangle of table objects.
toId: the table object id of the table object to start or end the mark on.
newRegion: [0|1]. If non-zero, start a separate table object selection. Only relevant on 3rd and successive odd numbered calls to tbl_obj_mark.
primary: may be 1, 0, or -1, to set, clear, or leave alone the primary selection.
doInvert: [0|1]. If non-zero, invert the selection in all views.
This function implements a finite state machine with three states: empty, marking, and bound. We start empty; the first call to tbl_obj_mark saves toid as the selection anchor and changes state to marking. The second call to tbl_obj_mark saves toid as the selection endpoint and changes state to bound.
A third call to tbl_obj_mark discards the previous endpoint and switches back to marking state; a fourth call switches back to bound.
Issuing the clear_mark command is the only way to get back to empty state.
If our state is marking or bound, we know two points: the anchor and the endpoint. Unless these two points are identical, we can invert the display region between them to clue the user in about what's marked.
tbl_obj_mark allows discontiguous rectangles of table objects to be selected. We handle discontiguity by checking for the newRegion flag on odd-numbered calls (state == empty or state == bound) and pushing the anchor and end points onto a stack before starting a new mark operation.
While our state is marking, the user may adjust the region endpoint by calling tbl_obj_markdrag; the state stays at marking, but the point (and hence the inverted region) changes.
Note that calling tbj_obj_mark will clear any text selection, and that selecting text will clear any table object selection.
Note that invoking the mark command also forces a state transition.
Returns 1 if successful. 0 (indicating failure) is returned when TOId doesn't identify a valid table object.