Unit
ExtHilit
Declaration (partial)
type
TCustomExtHighlighter = class(TPlusHighlighter);
TExtHighlighter = class(TCustomExtHighlighter);
Description
TExtHighlighter is a non visual component to achieve extended keyword and section highlighting in a TPlusMemo. Like TPlusMemo, it has Keywords and StartStopKeys properties, but the extension over the basic keywords and start-stop keys found in TPlusMemo enables complex nested and scoped algorithms, positional dependency, termination condition and collapsible property.
To use this component, place a TExtHighlighter on a form or datamodule. Set TPlusMemo.Highlighter Highlighter property to this TExtHighlighter instance (named "ExtHighlighter1" by default). Then define extended keywords and start-stop keys by double-clicking the Keywords or StartStopKeys properties in the Object Inspector.
TExtHighlighter is a descendant of TCustomExtHighlighter, from which it merely exposes properties and methods. TCustomExtHighligter is used as a base class for many specialized highlighter components. Those specialized highlighters sometimes also expose properties and methods of TCustomExtHighlighter, so they share some common functionality with TExtHighligter. Those common properties and methods are shown to apply to TExtHighlighter but they apply also to various highlighting components where this is indicated in those component's property and method lists.
Extended highlighting attributes
You will notice in the keywords editor window that keywords and start-stop keys each have new entries relative to those of TPlusMemo.Keywords and TPlusMemo.StartStopKeys: a scope value, priority level and positional dependency. In addition, for extended start-stop keys there is a new collapsible property and end at delimiter termination condition. Keyword occurrence events also permit applying special highlighting rules at run time. See Key events below.
The role of scope and priority is explained below. See topic TExtKeywordList class for information on positional dependency options. The collapsible functionality is presented in topic Collapsible blocks in TPlusMemo. Finally, delimiter termination condition is described in topic TExtStartStopList class.
Rules for complex dynamic highlighting
The new scope and priority parameters work together with "context number" in the following way:
If the SCOPE value of an element is different from zero, it will be a candidate for highlighting only if found inside of text already highlighted and marked with a CONTEXT NUMBER equal to this SCOPE value.
If the SCOPE value of a given element is zero, this element will be highlighted only when its PRIORITY is higher than the text where it is found. Normal, unlighted text is considered to have a SCOPE of 0 and PRIORITY of -1.
For example, if you want that <? and ?> considered a start-stop key and have some keywords in bold only when inside of it, simply set the CONTEXT NUMBER for this start-stop key to a given value (say 10), and also define your keywords with a SCOPE value equal to this number (10 in this example).
Key properties
| Active | A boolean property that controls if the effect of the TExtHighlighter is on or off. | |
| Keywords | A TExtKeywordList property that defines the keywords; | |
| Separators | A string property that contains the word delimiters; | |
| StartStopKeys | A TExtStartStopList property to define the start-stop keys; | |
| SubHighlighter | A TPlusHighglighter property to further achieve highlighting provided by another highlighter component. |
Key events
| OnKeyword | An event that occurs when a keyword is found, giving a chance to your application to reject it; | |
| OnStart | An event that occurs when a start key is found; like preceeding, your application can reject it; | |
| OnStop | Likewise, your application can reject the stop key just found. |
Run time usage
Keywords and start-stop keys can be defined at run time, using methods TExtHighlighter.Keywords.AddExtKeyword and TExtHighlighter.StartStopKeys.AddExStartStopKey respectively. Both of these methods have parameters similar to TPlusMemo.Keywords.AddKeyword TPlusMemo.StartStopKeys.AddStartStopKey, except for two additional ones to specify the desired SCOPE and PRIORITY parameters.
Keywords and start/stop keys can also be loaded from an external file, either in text ini file format, or in binary format. Such external file is normally generated by defining keywords or start/stop keys at design time in the extended keywords editor, then doing "File/Save List and attributes". You can load these key definitions at run time by doing (for a text ini file)
AStrings:= TStringList.Create;
AIniFile.ReadSectionValues('Keywords', AStrings);
ExtHighlighter1.Keywords.LoadFromIniStrings(AStrings)
AIniFile.ReadSectionValues('Sections', AStrings);
ExtHighlighter1.StartStopKeys.LoadFromIniStrings(AStrings);
AStrings.Free;
In the case of a binary file, the normal component streaming mechanism can be used. It entails creating a TReader object that is linked to a TStream which contains the data, and calling method Keywords.ReadData or StartStopKeys.ReadData with this TReader object. Similarly, for writing to a binary file, create a TWriter object and call Keywords.WriteData and/or StartStopKeys.WriteData with this writer object.