Caret Ownership

Within a frame, only one object can contain the keyboard focus. This property must be maintained when a frame contains multiple buffers in multiple views, and when a single buffer contains other buffers as items.

When a buffer is active, it will usually display the current selection, or a line indicating the insertion point; this line is called the caret. Keyboard focus is a matter of caret ownership: only the the buffer which has the keyboard focus can display a caret.

When a buffer contains other buffers, it keeps track of caret ownership among the sub-buffers it contains. When the caret is taken away from the main buffer, it will take away caret ownership from the appropriate sub-buffer, etc.

When a buffer or snip is draw, an argument to the drawing method specifies whether the caret should be drawn with the data. This argument can be any of (in increasing order):

• wx:const-snip-draw-no-caret -- The caret should not be drawn at all.
• wx:const-snip-draw-show-inactive-caret -- The caret should be drawn as ``inactive''; i.e., items may be identified as the local current selection, but the real keyboard focus is elsewhere.
• wx:const-snip-draw-show-caret -- The caret should be drawn to show keyboard focus ownership.

The ``inactive caret'' display mode is useful for showing selection ranges in editor buffers that do not have the focus. This ``inactive caret'' mode must be distinct from ``no caret'' mode: when buffers are embedded and only the locally-active buffer should show its selection.