SynEdit Changes

Changes in SynEdit 4.99 (from 4.0 to 5.0)

edit

SynEdit.OnGutterClick / SynEdit.[Right]Gutter.OnGutterClick / SynEdit.[Right]Gutter.MouseDown/Up/Move

edit
  • SynEdit.Gutter.OnGutterClick and SynEdit.RightGutter.OnGutterClick would fire for their own, and the for the other gutter. They also reported the wrong gutter. Further SynEdit.Gutter.OnGutterClick was just the forwarded value for SynEdit.OnGutterClick.
    SynEdit.OnGutterClick remains in place, and reports the correct gutter as Sender. The 2 other have been replaced with SynEdit.[Right]Gutter.OnClick
  • OnGutterClick on gutterparts was renamed to OnClick
  • the MouseMove/MouseDown/MouseUp routines on the Gutter (and gutterparts) have been changed from public to protected. They are available for inherited classes. They can no longer be called from the outside.
  • MouseMove was called on a semi random gutterpart, after the mouse was released. It is now only called while the mouse is down, and on the gutter part for which the mouse was clicked.

MarkupInfo / Color-Attributes - Changes to inheritance

edit

The class inheritance for storing Markup/Highlight colors has changed.

The old structure was to rigid. It did not allow for individually publishing properties. As more new properties are added, the structure needs to be adapted.

Changes required:

  • OLD
    • TLazSynCustomTextAttributes: removed
    • TSynSelectedColor / TSynHighlighterAttributesModifier / TSynHighlighterAttributes
      • Those classes do no longer have the same inheritance.
  • NEW
    • Local variables used to store objects from Highlighters, Markup and others should now use
      • TLazCustomEditTextAttribute
      • Or TLazEditTextAttribute if you need access to the caption
  • NEW
    • Code creating Attributes (e.g. for properties)
      • Chose one of the classes marked with "{PUBLISH}" below
      • Or define a new class, that publishes the fields you need

Changes in custom higlighter, markup and gutter parts:

  • Several function have changed return values (e.g. function GetTokenAttribute). Overridden functions should be changed (in some cases they will keep working with the old result type, but if possible should still be changed)

OLD inheritance

  TSynSelectedColorMergeResult  // unit SynEditMiscClasses
  |  
  TSynSelectedColor             //unit SynEditMiscClasses
  |
  TSynHighlighterAttributesModifier  // unit SynEditHighlighter
  |
  TSynHighlighterAttributes          // unit SynEditHighlighter
  |
  TLazSynCustomTextAttributes        // unit SynEditHighlighter
  |
  TPersistent

NEW inheritance

  TSynSelectedColorMergeResult                     // unit SynEditMiscClasses;
  |  // Merge Attributes with modifiers
  |
  |
  |  TSynGutterColorAttributes {PUBLISH}                        //  unit SynGutterBase
  |  |
  |  |  TSynHighlighterAttributes_Eol {PUBLISH}               // unit SynEditHighlighter
  |  |  |
  |  |  TSynHighlighterAttributes {PUBLISH}                   // unit SynEditHighlighter
  |  |  |
  |  |  |   TSynGutterColorAttributesModifier {PUBLISH}        //  unit SynGutterBase 
  |  |  |   |
  |  |  |   |  TSynSelectedColor                    // unit SynEditMiscClasses;
  |  |  |   |  |  // May get deprecated. Sets some (old) default values. Other functionality moved to "Modifier"
  |  |  |   |  |
  |  |  |   |  TSynHighlighterAttributesModifier {PUBLISH}   // unit SynEditHighlighter
  |  |  |   |  |
  |  |  |   TLazEditTextAttributeModifier  //  unit LazEditTextAttributes
  |  |  |   |  // Adds storage for modifier (Alpha, Mask) / Access properties exist in the base class, but return defaults
  |  |  |   |
  |  TLazEditTextAttribute                 //  unit LazEditTextAttributes
  |  |  // "Storable": adds Name, Caption, and can store "property default" values
  |  |
  TLazCustomEditTextAttribute              //  unit LazEditTextAttributes
  |  // Base class for all attributes, defines ALL properties (except Caption, Name)
  |
  TPersistent

StorageMem & HL-Ranges

edit

Before 4.99 the data was stored in

Old New
TSynEditStorageMem TLazEditLineItems
TSynManagedStorageMem TLazEditLineItems
TSynManagedStorageMemList TLazEditChildLineItemsList
TSynHighlighterRangeList TLazHighlighterLineRangeList

The old classes were overly complex. The forced user-code to deal with several steps (capacity, count, move) for an insert. The old classes did not manage any initialisation, each class had to take care to manage ref-counts on managed types.

For 5.0 the classes provide a compatibility layer providing methods matching the old interface and functionality. The compatibility methods are marked deprecated and will be removed in 5.99

  • Old methods on TSynEditStorageMem
  • InsertRows / DeleteRows: (New names Insert/Delete)

Old: Used to Call: Capacity, Count, Move. Required user-code to handle ref-counts of managed data

New: No longer call any of those methods. Handling of Managed data is done by the "MemInit" of LazListClasses

  • Count

Old: read/write

New: read/only. Call insert/delete as appropriate

  • Capacity

Old: was called when internally changed

New: internal capacity changes are not notified (can be done by using the callback capacity in LazListClasses)

  • Old TSynManagedStorageMem
  • Same changes as in TSynEditStorageMem
  • TLazEditChildLineItemsList now calls: Insert/Delete/Move/Capacity

(Move and Capacity, only if Move on the parent was called by user-code / Capacity may change on its own)

  • TLazEditChildLineItemsList now calls: TextChanged (triggered by calling CallLineTextChanged in the parent)
  • New TGenLazEditParentLineItems
  • Helper for implementing a parent / previously had to be done in each parent.

TSynHighlighterRangeList

edit
  • Old TSynHighlighterRangeList
  • Custom subclasses need to follow the above rules
  • Some properties/methods were renamed (they should only be needed in the Highlighter base class / subclasses should rarely be affected)

procedure ClearReScanNeeded now called ValidateAll

procedure AdjustReScanStart now called UpdateFirstInvalidLine

property NeedsReScanStartIndex now called FirstInvalidLine

property NeedsReScanEndIndex now called LastInvalidLine

property NeedsReScanRealStartIndex now called UnsentValidationStartLine

  • TSynHighlighterRangeList replaced by TLazHighlighterLineRangeList
  • TSynHighlighterRangeList was made an abstract base class. This allows different subclasses to define their own storage.

Inheriting from TSynHighlighterRangeList

edit

It can no longer be subclassed and extended by setting its "ItemSize" to a larger value.

  • Old: inherit from TSynHighlighterRangeList and change ItemSize
  • New inherit from e.g.: specialize TGenLazHighlighterLineRangeShiftList<TRANGEDATA>
  • TRANGEDATA must now include space for the "FRange: Pointer"
  • GetRange/SetRange must be overridden to store/return this data

TGenLazHighlighterLineRangeShiftList / TGenInitLazHighlighterLineRangeShiftList

  • Implement GetRange/SetRange: In this case TRangeData must provide space for a pointer at offset 0 (zero)
  • Provide initialisation of data. This no longer needs to be done in move/insert/setcapacity

See c46a56d8b16f5afc1a4b44154120833ab2be472c for an example (this also shows how to use managed types)

Highlighters (Fold-Hl / TSynCustomHighlighterRange)

edit

TSynCustomHighlighterRanges

edit

TSynCustomFoldHighlighter used to store the range objects in TSynCustomHighlighterRanges using an AvlTree. It now uses TLazHighlighterRangesDictionary using TDictionary.

As a result any range derived from TSynCustomHighlighterRange must now support returning a hash (see TLazHighlighterRangeForDictionary).

See also: https://wiki.freepascal.org/SynEdit_Highlighter#Objects_as_Ranges_-_Incompatible_change_in_4.99

TSynCustomHighlighter

edit
  • TSynCustomHighlighter replaced by TLazEditCustomHighlighter and TLazEditCustomRangesHighlighter
  • Use TLazEditCustomHighlighter for variables/properties holding highlighters of any type
  • Use TLazEditCustomRangesHighlighter as new base class

Methods/Properties changed

edit
Old Method/Property New Notes
  • function GetTokenAttribute: TSynHighlighterAttributes
  • function GetEndOfLineAttribute: TSynHighlighterAttributes
  • function GetTokenAttribute: TLazEditTextAttribute
  • function GetEndOfLineAttribute: TLazEditTextAttribute
New return type. Instances should still be created with the various subclasses as before.
The base class now provides a complete interface for access
  • function GetRange: Pointer; virtual
  • procedure SetRange(Value: Pointer); virtual
  • procedure ResetRange; virtual
  • function GetRange: Pointer; virtual; abstract
  • procedure SetRange(Value: Pointer); virtual; abstract
  • procedure ResetRange; virtual; abstract
Those are now abstract. Don't call the base class.
  • procedure SetCurrentLines
  • procedure DoCurrentLinesChanged; virtual
private / no longer virtual
  • property KnownLines:
  • property AttachedLines
  • property KnownRanges
- removed / no replacement.
Can be implemented within each sub class if needed. Example to retrieve from KnownLines - 226d55fa33ea46967e55a28d381e339e60771f20
  • procedure StartAtLineIndex
  • procedure InitForScanningLine
no longer virtual
  • procedure SetLine
  • procedure StartAtLineIndex
  • procedure SetAlternativeLineTextForGetTokens(...)
  • procedure InitForScanningLine
  • property CurrentLineText: string
  • property LinePtr: Pchar
  • property LineIndex: TLineIdx
Use StartAtLineIndex for scanning lines. To get tokens for an alternative text use SetAlternativeLineTextForGetTokens
Inherited classes should overwrite InitForScanningLine.
The line-text and index are now available through the listed properties.
  • procedure ScanRanges
  • function PerformScan
  • function PrepareLines
  • function DoPrepareLines
Needs to support "AMaxTime" for idle-scanning
  • procedure ScanAllRanges
- Call MarkUnprepared and Prepare
  • function NeedScan: Boolean
  • function FirstUnpreparedLine: IntIdx
  • function UpdateRangeInfoAtLine(Index: Integer): Boolean
  • function UpdateRangeInfoAtEOL: Boolean
  • FIsInNextToEOL
  • property IsInNextToEOL: Boolean
  • function StartCodeFoldBlock(...): TSynCustomCodeFoldBlock
  • function StartCodeFoldBlock(...): BOOLEAN
The old result was not initialized. And there was in many cases no instance of TSynCustomCodeFoldBlock that could have been returned. The result now indicates if the block was created (e.g. it did not have enabled=false).
Inherited methods that use the result must be updated.
Inherited methods that tried to use the TSynCustomCodeFoldBlock instance were already broken, since this was an uninizialized pointer (not nil, but random)
  • FAttributeChangeNeedScan
  • procedure RequestFullRescan
  • procedure AfterAttachedToRangeList
  • procedure BeforeDetachedFromRangeList
  • procedure DoAttachedToLines
  • procedure DoDetachingFromLines
  • procedure HookAttrChangeEvent
  • procedure UnhookAttrChangeEvent
  • senrHighlightAttribChanged
  • senrHighlightRescanNeeded
Listen to senrHighlightAttribChanged / senrHighlightRescanNeeded on the lines instance.
  • property CommentAttribute
  • property IdentifierAttribute
  • property KeywordAttribute
  • property StringAttribute
  • property SymbolAttribute
  • property WhitespaceAttribute
  • function GetDefaultAttribute(Index: integer): TSynHighlighterAttributes
  • GetTokenClassAttribute
  • GetTokenClassAttributeEx
  • class function GetCapabilities
- removed
  • function SaveToRegistry(RootKey: HKEY; Key: string): boolean;
  • function LoadFromRegistry(RootKey: HK
  • function UseUserSettings(settingIndex: integer): boolean;
  • procedure EnumUserSettings(settings: TStrings);
  • function LoadFromFile(AFileName: String): boolean
  • function SaveToFile(AFileName: String): boolean
removed - Settings should be streamed using RTTI and need no support in the highlighter classes themself.
Only some sub-classes have implementations, and those have not been maintained and have in some cases become incomplete.
  • fDefaultFilter
  • fDefaultFilterInitialValue
  • function IsFilterStored: Boolean;
  • function GetInitialDefaultFileFilterMask: string; virtual
  • procedure SetSampleSource(Value: string)
  • function GetSampleSource: string; virtual
removed - SampleSource is now a read-only property
Subclasses that need to change their sample-source can implement their own way of setting it. GetSampleSource can then return that value.
  • function GetWordBreakChars: TCharSet; virtual
  • property WordBreakChars
property is now read-only
  • property DrawDividerLevel: Integer
  • property DividerDrawConfig
  • function AddSpecialAttribute(
  • procedure AddAttribute
Create Attribute and add.