Description:
POSITION changes the current editing position based on its first and only
parameter. Most editing operations are done at the current editing position. The
current edit position and the position of the cursor may not match. When changes
are made to a buffer, padding with spaces may occur to match the current screen
cursor position. The cursor is not updated when changing the position in a
window that is not the current window. If a marker is used as the parameter,
POSITION moves to the character position tied to the marker. Range positions go to
the beginning of the specified range. To position at the end of a range, use
POSITION (END_OF (range_variable)).Window positions move to the character in the
last cursor position in the window. When using a window variable as the
parameter, the window must be mapped. Whatever buffer is mapped to this window used as
a parameter becomes the current buffer.
When a buffer is passed, the last editing position of that buffer is restored.
Any integer from 1 to the number or records in the buffer plus 1 may be used
to specify which dynamic record to place the editing position on. A zero value
does not cause a position change.
BUFFER_BEGIN moves to the beginning of the current buffer; BUFFER_END to the
last character. LINE_BEGIN moves to the beginning of the current line; LINE_END
to the end. MOUSE moves the edit position to the character under the mouse
pointer during a button press or motion. The TEXT keyword indicates a free cursor
position should be located to the closest character. If the edit position is
currently bound to a character, positioning with TEXT keyword will have no effect.
Syntax:
POSITION { placeholder }
Valid placeholders are: BUFFER_BEGIN, LINE_BEGIN, MOUSE, BUFFER_END, LINE_END, TEXT, as well as
a buffer, integer, marker, range, or window value.
Example:
The following places the cursor in the new$window window.
POSITION (new$window);
Errors:
TPU$_BADKEY Invalid keyword.
TPU$_BADVALUE Integer must be between 1 and the length of the buffer plus 1.
TPU$_MOUSEINV Unknown mouse position.
TPU$_REQUIRESWINDOWS Must be in a windowed environment.
TPU$_UNKKEYWORD Invalid keyword.
TPU$_WINDNOTMAPPED Window is not mapped.
TPU$_WINDNOTVIS Window is occluded.
Related Builtins:
POSITION