SynEdit Changes

This is the current revision of SynEdit Changes, edited by Martin at .

/* TSynCustomHighlighter */

Changes in SynEdit 4.99 (from 4.0 to 5.0)

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

MarkupInfo / Color-Attributes - Changes to inheritance

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:

Changes in custom higlighter, markup and gutter parts:

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

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

  • 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)

  • 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)
  • Helper for implementing a parent / previously had to be done in each parent.

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

Inheriting from TSynHighlighterRangeList

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

  • 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)

TSynCustomHighlighterRanges

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

  • Use TLazEditCustomHighlighter for variables/properties holding highlighters of any type
  • Use TLazEditCustomRangesHighlighter as new base class

Methods/Properties changed

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.