Selection

A selection has four pieces:

1) A position 2) An anchor 3) A focus 4) A user coordinate

The user coordinate should only ever be changed in direct response to actual user action and indicates where they ideally want the focus to be.

If they move in the horizontal direction, the x user coordinate should change. The y should not, even if the actual focus moved around (e.g. moving to a previous line while left arrowing).

If they move in a vertical direction, the y user coordinate should change. The x should not even if the actual focus moved around (e.g. going to the end of a shorter line while up arrowing).

The position, anchor, and focus are stored in opaque units. The user coordinate is EITHER grid coordinates (line, glyph) or screen coordinates (pixels).

Most methods on the selection move the position. This is not visible to the user, it is just an internal marker.

setAnchor() sets the anchor to the current position. setFocus() sets the focus to the current position.

The anchor is the part of the selection that doesn't move as you drag. The focus is the part of the selection that holds the caret and would move as you dragged around. (Open a program like Notepad and click and drag around. Your first click set the anchor, then as you drag, the focus moves around. The selection is everything between the anchor and the focus.)

The selection, while being fairly opaque, lets you do a great many things. Consider, for example, vim's 5dd command - delete five lines from the current position. You can do this by taking a selection, going to the beginning of the current line. Then dropping anchor. Then go down five lines and go to end of line. Then extend through the EOL character. Now delete the selection. Finally, restore the anchor and focus from the user coordinate, so their cursor on screen remains in the same approximate position.

The code can look something like this:

selection
	.moveHome
	.setAnchor
	.moveDown(5)
	.moveEnd
	.moveForward(&isEol)
	.setFocus
	.deleteContent
	.moveToUserCoordinate
	.setAnchor;

If you can think about how you'd do it on the standard keyboard, you can do it with this api. Everything between a setAnchor and setFocus would be like holding shift while doing the other things.

void selectBetween(Selection other);

Please note that this is just a handle to another object. Treat it as a reference type.

struct Selection {

this();

bool isEmpty();

void getContent(void delegate(scope const(char)[] text, TextStyle style) dg);

string getContentString();

Selection setAnchor();

Selection setFocus();

Selection setUserCoordinate(Point p);

Selection setUserXCoordinate();

Selection setUserYCoordinate();

Selection moveTo(Point p, bool setUserCoordinate);

Selection moveToStartOfDocument();

Selection moveToEndOfDocument();

Selection moveToStartOfLine(bool byRender, bool includeLeadingWhitespace);

Selection moveToEndOfLine(bool byRender);

Selection moveToIncludeAdjacentEndOfLineMarker();

Selection moveUp(int count, bool byRender);

Selection moveDown(int count, bool byRender);

Selection moveLeft(int count, bool byRender);

Selection moveRight(int count, bool byRender);

FindResult find(const(char)[] delegate(scope return const(char)[] buffer) predicate, int windowBufferSize, bool searchBackward);

struct FindResult;

Selection replaceContent(const(char)[] newText, TextLayouter.StyleHandle style);

void changeStyle(TextLayouter.StyleHandle delegate(TextStyle existing) newStyle);

}

Constructors

this this(): You cannot construct these yourself. Instead, use TextLayouter.selection to get it.

Members

Functions

changeStyle void changeStyle(TextLayouter.StyleHandle delegate(TextStyle existing) newStyle): Changes the style of the given selection. Gives existing styles in the selection to your delegate and you return a new style to assign to that block.
find FindResult find(const(char)[] delegate(scope return const(char)[] buffer) predicate, int windowBufferSize, bool searchBackward): Does a custom search through the text.
getContent void getContent(void delegate(scope const(char)[] text, TextStyle style) dg): Function to get the content of the selection. It is fed to you as a series of zero or more chunks of text and style information.
getContentString string getContentString(): Convenience function to get the content of the selection as a simple string.
isEmpty bool isEmpty(): Returns true if the selection is currently empty. An empty selection still has a position - where the cursor is drawn - but has no text inside it.
moveDown Selection moveDown(int count, bool byRender)
moveLeft Selection moveLeft(int count, bool byRender)
moveRight Selection moveRight(int count, bool byRender)
moveTo Selection moveTo(Point p, bool setUserCoordinate)
moveToEndOfDocument Selection moveToEndOfDocument()
moveToEndOfLine Selection moveToEndOfLine(bool byRender)
moveToIncludeAdjacentEndOfLineMarker Selection moveToIncludeAdjacentEndOfLineMarker(): If the position is abutting an end of line marker, it moves past it, to include it. If not, it does nothing.
moveToStartOfDocument Selection moveToStartOfDocument()
moveToStartOfLine Selection moveToStartOfLine(bool byRender, bool includeLeadingWhitespace)
moveUp Selection moveUp(int count, bool byRender)
replaceContent Selection replaceContent(const(char)[] newText, TextLayouter.StyleHandle style): Replaces the content of the selection. If you replace it with an empty newText, it will delete the content.
setAnchor Selection setAnchor()
setFocus Selection setFocus()
setUserCoordinate Selection setUserCoordinate(Point p)
setUserXCoordinate Selection setUserXCoordinate()
setUserYCoordinate Selection setUserYCoordinate(): These functions set the actual selection from the current internal position.

Structs

FindResult struct FindResult: Does a custom search through the text.

Selection

Constructors

Members

Functions

Structs

Meta

Source