The purpose

Gutter lanes allow for building a feature-rich SQL text editing user interface.

They can be used to mark some positions in the text, highlight the current statement, or indicate user-defined bookmarks or breakpoints.

Setting up gutter lanes

You can define lanes using the TextEditorOptions.GutterOptions.Lanes collection.

textEditor.TextEditorOptions.GutterOptions.Lanes: TacTextEditorLanes;

The TacTextEditorLanes class is a TCollection descendant, so you can use standard methods like Add, Insert, etc.

Lanes are displayed in the order in which they are defined in the Lanes collection, the first is the leftmost.

The TacTextEditorLane class contains only one relevant Width property. Other settings should be defined via the TacTextEditor.OnGetGutterLanePaintParams event.

On changing the width, quantity, or order of lanes, the overall gutter width is updated and the Text Editor is redrawn.

Rendering the lane

To draw a lane, the TextEditor asks for the rendering parameters via the OnGetGutterLanePaintParams event.

TacVisualLineState = (
  lsCurrent, // caret is on this line
  lsHover, // mouse cursor is over this line
  lsHoverLane, // mouse cursor is over the lane
  lsHoverGutter, // mouse cursor is over the gutter next to this line
  lsHoverText // mouse cursor is over the text area of this line
);

TacVisualLineStates = set of TacVisualLineState; 

TacGutterLanePaintParams = record 
  GutterLane: TacTextEditorLane; // (input) the rendered lane
  VisualLine: TacVisualLine; // (input) link to the current VisualLine object
  LineState: TacVisualLineStates; // (input) state of the currene line
  LaneImage: TGraphic;  // (output) assign image to be drawn
  PaintLaneImageFrame: Boolean; // (output) determines if image should be drawn with a border.
end;

TacGetGutterLanePaintParamsProc = procedure (ASender: TacTextEditor; var AParams: TacGutterLanePaintParams) of object; 

TacTextEditor = class(TCustomPanel, IDropTarget) 
  // skipped ... 
  published 
    property OnGetGutterLanePaintParams: TacGetGutterLanePaintParamsProc read FOnGetGutterLanePaintParams 
      write FOnGetGutterLanePaintParams;

In this event handler, you can read from the GutterLane, VisualLine, and LineState fields of the TacGutterLanePaintParams type parameter and write to the LaneImage and PaintLaneImageFrame fields if needed.

Mouse click handling

When the user clicks on the lane, the TextEditor.OnGutterLaneMouseDown event is fired.

TacGutterLaneMouseProcParams = record
  GutterLane: TacTextEditorLane; // the clicked lane
  VisualLine: TacVisualLine; // link to the current VisualLine object
  ShiftState: TShiftState; 
  MousePos: TPoint;
end;

TacGutterLaneMouseProc = procedure (ASender: TacTextEditor; var AParams: TacGutterLaneMouseProcParams) of object; 

TacTextEditor = class(TCustomPanel, IDropTarget)
  // skipped ... 
published 
  property OnGutterLaneMouseDown: TacGutterLaneMouseProc read FOnGutterLaneMouseDown write FOnGutterLaneMouseDown;

 

sql_text_editor_vcl.png