Navigation: ABC Library Reference > ConstantClass >====== ConstantClass Overview  ====== |    |
The ConstantClass provides an easy, flexible, and efficient way to “loop through” constant data. That is, the ConstantClass parses structures like the following so you can access each (unlabeled) data item discretely:
Errors GROUP,STATIC
Items USHORT(40) !item count
USHORT(Msg:RebuildKey) !begin item 1
BYTE(Level:Notify)
PSTRING('Invalid Key')
USHORT(Msg:RebuildFailed) !begin item 2
BYTE(Level:Fatal)
PSTRING('Key was not built')
!38 more USHORT,BYTE,PSTRING combinations
END
ConstantClass Concepts
The ConstantClass parses and loads constant data such as error messages or translation text from the GROUP structure that declares the data into other data structures or memory variables (one item at a time). It can also write all the constant data into a QUEUE or a FILE.
The ConstantClass intelligently handles irregular data–you can declare the constant text data with a series of strings of varying lengths so that no space is wasted. The ConstantClass also handles a variety of numeric datatypes including BYTE, SHORT, USHORT, and LONG.
The ConstantClass provides several ways to stop processing the constant data, including a simple item count, a text match, and a read-to-the-end option.
A single ConstantClass object can process multiple GROUP structures with the same (or incremental) layouts.
Declaring the Data
To use the ConstantClass, you must declare the constant data within a GROUP structure. The GROUP structure may declare a single sequence using any combination of the permitted datatypes, or a series of such sequences (the GROUP repeats the combination of datatypes as many times as needed). The ConstantClass permits CSTRING, PSTRING, BYTE, SHORT, USHORT, and LONG datatypes. The GROUP structure may contain an initial BYTE or USHORT that specifies how many times a sequence of datatypes is repeated. For example:
Errors GROUP,STATIC
Items BYTE(2) !optional item count
USHORT(Msg:RebuildKey) !begin first item
BYTE(Level:Notify)
PSTRING('Invalid Key') !end first item
USHORT(Msg:RebuildFailed) !begin second item
BYTE(Level:Fatal)
PSTRING('Key not built') !end second item
END
Here is another example of a structure the ConstantClass can handle:
Translation GROUP,STATIC !no item count
PSTRING('&Across') !default text
PSTRING() !translation text
PSTRING('Align all window Icons') !default text
PSTRING() !translation text
PSTRING('Arrange Icons') !default text
PSTRING('') !translation text
END
If the GROUP is declared within a procedure it must have the STATIC attribute. See the Language Reference for more information.
Describing the Data
The ConstantClass uses two methods to describe or understand the structure of the constant data it processes: the Init method and the AddItem method. The Init method (termination parameter) indicates whether or not the GROUP structure declares an item count as well as the datatype of the item count (see Init). The AddItem method identifies each repeating component of the GROUP structure as well as the target variable that receives the contents of the repeating component (see AddItem).
ConstantClass Relationship to Other Application Builder Classes
The TranslatorClass, ErrorClass, ToolbarClass, and PrintPreview classes all use the ConstantClass. These classes automatically instantiate the ConstantClass as needed.
ConstantClass ABC Template Implementation
All ABC Library references to the ConstantClass are encapsulated with ABC Library methods–the ABC Templates do not directly reference the ConstantClass.
ConstantClass Source Files
The ConstantClass source code is installed by default to the Clarion \LIBSRC. The specific ConstantClass source code and their respective components are contained in:
| ABUTIL.INC | ConstantClass declarations | |
| ABUTIL.CLW | ConstantClass method definitions |
ConstantClass Conceptual Example
The following example shows a typical sequence of statements to declare, instantiate, initialize, use, and terminate a ConstantClass object. The example loads translation pairs from a constant GROUP into two CSTRINGs, which are then passed as parameters to another TranslatorClass method. Note that the target CSTRINGs could just as easily be fields in a QUEUE or FILE buffer.
INCLUDE('ABUTIL.INC') !declare ConstantClass, TranslatorClass
Spanish GROUP !declare constant data
Items BYTE(50) !item count
PSTRING('One') !begin first item
PSTRING('Uno')
PSTRING('Two') !begin second item
PSTRING('Dos')
!48 more PSTRING pairs
END
LangQ QUEUE
Text CSTRING(50)
Repl CSTRING(50)
Done BYTE
END
Const ConstantClass !declare & instantiate Const object
Text CSTRING(255),AUTO !a variable to receive a constant value
Repl CSTRING(255),AUTO !a variable to receive a constant value
EndFlag BYTE !terminator flag
CODE
!process items one-at-a-time:
Const.Init(Term:BYTE) !initialize the Const object,
!the first BYTE contains item count
Const.AddItem(ConstType:PString, Text) !Describe constant structure and
Const.AddItem(ConstType:PString, Repl) ! variables to accept the values
Const.AddItem(ConstType:PString, EndFlag)
Const.TerminatorValue = 1 ! terminate when endFlag =1
Const.TerminatorField = 50 ! 50th field is the terminating field
Const.TerminatorInclude = True ! include the terminating record
Const.Set(Spanish) !pass constant data to Const obj
LOOP WHILE Const.Next()= Level:Benign !copy constant data one at a time
!do something with Text and Repl !to AddItem variables
END
Const.Kill !shut down Const object
!process all items at a time:
Const.Init(Term:BYTE) !re initialize the Const object,
!the first BYTE contains item count
Const.ConstantClass() !reset to default property values
Const.AddItem(ConstType:PString,LangQ.Text) !Describe constant structure and
Const.AddItem(ConstType:PString,LangQ.Repl) ! variables to accept the values
Const.Set(Spanish) !pass constant data to Const obj
Const.Next(LangQ) !copy all const items to LangQ
Const.Kill !shut down Const object