The New SynEdit Gutter (breaking change)

[pyscripter]

There is a lot of functionality that tries to fit into the limited space of the Gutter

• Bookmarks and other marks
• LIne Numbers
• Code folding symbols
• Line modification status (track changes)
• Other custom stuff (e.g. debug information as in the Delphi IDE).

The current system is inflexible and not easily extensible. The current properties, LeftOffset, RighOffset are insufficient for coping with the desired flexibility.

The New Gutter

The new gutter contains a collection of Bands accessible at design and run time through the published property Bands (TOwnedCollection). Each Band if of type TSynGutterBand the public interface of which is as follows:

  TSynGutterBand = class(TCollectionItem)
    function RealWidth: Integer;
    property LeftX: Integer read GetLeftX;
    property Editor: TPersistent read GetEditor;
    property Gutter: TSynGutter read GetSynGutter;
  published
    property Kind: TSynGutterBandKind read SetKind write FKind;
    property Visible: Boolean read GetVisible write SetVisible default True;
    property Width: Integer read GetWidth write SetWidth stored IsWidthStored;
    property Background: TSynGutterBandBackground read FBackground write SetBackground default gbbGutter;
    property OnPaintLines: TGutterBandPaintEvent read FOnPaintLines write SetOnPaintLines;
    property OnCLick: TGutterBandClickEvent read FOnClick write SetOnClick;
    property OnMouseCursor: TGutterMouseCursorEvent read FOnMouseCursor write SetOnMouseCursor;
  end;

The TSynGutterBandKind enumeration is defined as follows:

  TSynGutterBandKind = (gbkCustom, gbkMarks, gbkLineNumbers, gbkFold, gbkMargin, gbkTrackChanges);

The Gutter constructor creates four bands: gbkMarks, gbkLineNumbers, gbkFold, gbkMargin in that order. The bands can be rearranged and custom bands can be added at design time. The width and visibility of the gbkLineNumbers and gbkFold bands are automatically calculated from the relevant Gutter and CodeFolding options. For the other bands the Visible and Width properties are used. The Width is unscaled and RealWidth provides the width scaled for PPI.

Here is the design time editor:

The Background property is an enumeration defined as follows;

  TSynGutterBandBackground = (gbbNone, gbbGutter, gbbEditor);

The default is gbbGutter, which means that the standard Gutter background is painted before the band contents are painted transparently on top. gbbEditor applies the editor background instead and gbbNone can be used if you want to custom paint the Gutter background.

Here is an example in which the bands have been rearranged and the Fold band is painted with the editor background.

A new Gutter property allows you to access the Bands by kind:

    property Band[Kind: TSynGutterBandKind]: TSynGutterBand read GetBandByKind;

New Demo

A new demo SimpleIDEDemo, showcasing a custom band, has been added. This is a port of a similar demo from the original SynEdit repository. A new custom band that displays debugger information is created and uses the OnPaintLines, OnClick and OnMouseCursor events.

Breaking change

This is a breaking change. A number of Gutter properties (LeftOffset, RightOffset, RightMargin) have been removed and other properties have been added. What this means is that you have to reinstall the components and then in the IDE open the form(s) which contain SynEdit ignoring all errors and save them. That should be enough.

[JaFi-cz]

It souds good. How it will be in situatin when line has bookmark and you want to add another sign (breakpoint e.t.c.)?

[pyscripter]

How it will be in situatin when line has bookmark and you want to add another sign (breakpoint e.t.c.)?

You can either handle this through the Maks band (make it wider to accommodate more than one mark) or use a new custom band as in the simple IDE demo.

[MShark67]

These new changes look great. My gutter usage is limited to line numbers and bookmarks and in initial testing they both seem to work perfectly.

[JaFi-cz]

Don't you think about painting bookmarks instead of have ImageList? In the time of High DPI is Delphi image list limiting, cause it doesn't support vector graphics. I do painting numbered/unnumbered bookmarks e.t.c, dynamically long time already.

[pyscripter]

Currently the internal bookmark images are scaled for PPI, so they work OK in a per Monitor setting. You can also use your own ImageList for bookmarks and other marks, which could be a Virtual ImageList (based on svg images for instance) that scale perfectly.

[JaFi-cz]

What about case, when user increase Synedit font size? My users can do it simply with Ctrl+MouseWheel as in browser. In this case gutter line numbers and other items on the gutter should reflect editor font size too. And as oposite, when you decrease font size, bookmarks from image list will be painted wrong.
PPI doesn't solve this problem.

[pyscripter]

In PyScripter I offer the same functionality. But I adjust the Gutter font size along side the Editor Font size. I use something like:

procedure TEditorForm.EditorZoom(theZoom: Integer);
begin
  if not((theZoom > 1) and (SynEdit.Font.Size <= 2)) then
  begin
    SynEdit.Font.Size := SynEdit.Font.Size - theZoom;
    SynEdit.Gutter.Font.Size := Max(SynEdit.Font.Size - 1, 1);
  end;
end;

As for the bookmarks if you use your own Virtual ImageList you can adjust its size (width, height). But I admit is not perfect. The new Gutter allows to custom paint bands, Marks, Line Numbers anything you want. And the painting is clipped to the band, so you are not in danger of painting over other bands. Look at the OnPaintLines event handler of the bands.

[JaFi-cz]

Thank you for explanation

[MShark67]

I'm seeing a problem where the autosize of the linenumbers is incorrect if I change the editor font and have UseFontStyle set to false (which I think means to use the editor font in the gutter.) I think the situation is that TSynGutter.CalcCharWidth is called when the editor is created but not updated if the font of the editor changes. In my case the initial editor font is Consolas 10 and then I change it in code to Consolas 12, and after that the line number display is too narrow. I'm testing with 50,000 lines or so and scrolled to the bottom to show the issue best.
-Mark

[pyscripter]

Turned it to #91

[pyscripter]

Fixed. Please check

[MShark67]

Autosize fix looks great! This new bands system is very flexible and easy to understand. Nicely done!

I think there might be a minor issue with gbsMiddle in that it's using a fixed size of 2. I think that should be something like

Current version:

  if Gutter.BorderStyle = gbsMiddle then
    Offset := 2
  else
    Offset := 1;

New version:

  if Gutter.BorderStyle = gbsMiddle then
    Offset := Max(2, (ClipR.Right - ClipR.Left) div 2)
  else
    Offset := 1;

Also I wonder if for flexibility sake there should be a gbsLeft option. I don't need this, just something I was thinking while checking it out.
-Mark

[pyscripter]

Turned into #93 and fixed. I don't think gbsLeft is visually appealing and therefore useful.

[MShark67]

Thanks, and agreed on gbsLeft, I have no actual use for it. The nice thing is that someone could just use a custom band and do whatever they need to... excellent!

[JaFi-cz]

I am fighting with new Gutter.
Imagine, I have Text diff window where 2 windows are one next to other with synchronized move.
I need to paint lines numbers in gutter manually, cause line numbers corespond with real line numbers - when lines are missing in the original files, there are no line numbers.
Till now I painted line numbers in the Synedit.OnPaintTransient event and I set gutter width manually acording to number of digits.
How to do it now? Use custom band and it's OnPaint event? Or is there any easier way?

[pyscripter]

Painting the Gutter in the OnPaintTransient handler is not a good idea, since it will get called much more often than needed and may result in flicker. It is more suited for decorating text in the editor like your spell-checking. You can still do that if you want. A custom band will get you space in the gutter with adjustable and PPI-scaled width. The LeftX property will give you starting X offset of the band,

But the better and simpler way is to use the OnPaintLines event of Bands. Also that way you do not need to restore changes in the Canvas since the DC is saved before and restored after calling the handler. You can freely change fonts, brushes, pens etc. It also restricts painting (clipping) in the allocated space of the band (ClipR). You can custom paint any band including the standard ones. The SimpleIDE demo demonstrates how to add a custom band at design time and custom paint it.

Also you can add/remove/hide/resize bands programmatically (Gutter.Bands is a standard TCollection) or at design-time. Bands are collection Items and therefore have a unique ID (public property). Collection has a method FindItemId.

[JaFi-cz]

Finally solved using Synedit.OnGutterGetText event.
The solution using PaintTransient was from the past.

[pyscripter]

This should still work.
PaintTransient is very inefficient. It is called even with every mouse blink!