| Search Locate Previous Next | Contents |
The class specification is used by #.CPro.Build to construct a number of class variables detailing its events, properties etc. It is also used by the Designer to determine how the class appears in design mode, and to offer the developer simple on-line help (the ‘Cuecard’ section). It may be erased from the workspace in a runtime system, and you may choose to reduce it to a bare minimum in classes where no further modifications are planned.
It is structured as a vector of text vectors (vtv) in standard .INI form with the following sections.
Required Section for Use by the Designer
The Name entry is required, all other keywords may be omitted if not applicable. Classes with no Type specified appear at the top level on the ‘New’ object menu in the Designer. If Style is omitted the object will be designed as a simple captioned rectangle. Other built-in styles such as ‘Button’ may be appropriate, or you may use a custom design function (see the CB class for an example) if required.
[Design] Name= © appears in designer right-mouse menu Type= © used to group controls in the designer Style= © omitted, or one of ... Button Group Form Placeholder © such as MRU class Custom © needs Design function in class. Sizeable=0 © Display without sizing handles. Transparent=1 © ignores mouse down except on edges Size=h,w © fix size at creation © N.B. either h or w may be zilde to allow sizing in that dimension only Colour=R G B © colour of placeholder Pattern=8 x 8 bitmap © background bitmap for forms GridColour=R G B © sets colour of form background bitmap RightMouseHandler=myfn © Over-ride for standard designer menu LeftMouseHandler=myfn © Over-ride for locator Parent=1 © required for objects that can be parents
Most of the other settings are not frequently used – browse some classes to see how they affect the behaviour of the class in design view. For example the HSEP and VSEP are only sizeable in one direction, the TI uses a placeholder style, and the PL is transparent to mouse clicks, so that other objects may be added within it.
Functions Intended for use by the Application
Many classes have so-called ‘Public’ functions which are intended for application use. For example the TreeView has an extensive library of calls to add and remove branches, list the children of a node, and so on. For each entry in this section, you may add a matching entry for the function itself. This will be used in compiling the help file for the class, and will be shown by the designer if available.
[Public Functions] FirstFn arg © First Function Second 'abc' © Second function [FirstFn] This takes a scalar integer and ...
It is good to show the sample syntax for the function, as this is used in the Designer when you use the ‘Paste Function ...’ option in the Event-Table editor.
Other Sections Used by Class.ParseSpec
For a class to operate correctly, #.CPro.Make must add the correct event handlers so that actions which you enter in the Behaviour table in the designer are fired when the event occurs. For example if you want the class to support context-sensitive help (the user may hit <F1> in an edit field) then define any free event number (3000 and above by convention) as an HR event and have a KeyPress handler queue this event on the object when it detects the correct keypress. You can have as many of these class-specific ‘dummy’ events as you require, but make sure they have unique numbers within any one class.
[Events] HR=3001 © Help Request
Class properties are used by the Designer to build the ‘property-watcher’, and may be fully defined at design time, or may give an APL expression which is re-evaluated whenever required to update the control. For example:
[Properties] Text: User © The text you typed Selection: User © The selected bit Text Colour: Runtime © A valid colour triple ... Readonly=0: Bool © Readonly field
Property-types User and Runtime are special, as they always take an APL expression as the value. See the notes on Using the Designer for more details. The other types are fixed when you design the control and may be chosen from:
If you need a type which is not easily classified as one of these (for example a numeric pair) then you may define your own maintenance function for it in the class. See Class-specific property types for more details.
[Read Events] Text=36 © User property 1 Selection=2 3003 © User property 2
You must include an entry on the Read-Events list for every User property in the class. This list is used by Causeway to fire the Read function in the class whenever the appropriate event fires. You may choose to have the Read function run on several events, and these events may be standard Dyalog events (for example 36 is ‘Changed’) or may be queued from within the class. You may only give the event numbers here.
Optional Sections for Additional Class Documentation
You may add as many other sections to the specification as you need. If a section called [Cue Card] exists it will be used by the designer to offer pop-up help on the class. You may include HTML tags here – for the moment they will be screened out by the Designer, but they are used in the helpfile compilation and may be shown on the cue-card in a future release.
[Cue Card] Shown in the Designer. May spread over several lines. [Release Notes] Release notes here [QA] Script to be run by Class.Seatrial to check out the class.
Use Class.SaveSpec 'cls' to save the specification as an ASCII text file. As an alternative to the standard Dyalog editor, try Class.Ted, e.g.
#.Class.Ted 'AC.specification'
... which provides a simple word-wrapping text editor.