tvDMX version 1.2 (c) 1992 Randolph Beck
=====

This is a shareware product and may be distributed and copied for free.

Users must register their copy by sending $20 to:

Randolph Beck
tvDMX Registration
P.O. Box 56-0487
Orlando, FL 32856-0487

Registered users will receive a diskette with the full source code and
further documentation. Please include any questions or comments.
CompuServe members may contact the author at CIS: 72361,753.


Page 1. tvDMX OVERVIEW

Page 2. tvDMX CONCEPTS
The Data-Formatting Template

Page 3. USING tvDMX IN YOUR PROGRAMS
Data Windows
Using tvDMX as Field Editors

Page 5. ADVANCED FEATURES
Hidden and Read-Only Fields
Swapping Field Positions

Page 6. ASCENDANCY CHART

Page 7. UNITS

Page 8. DATA TEMPLATE CODES
Using Template Codes
Template Control Codes

Page 13. FYI
Important Virtual Methods
External Database Access
Global Functions in Unit DMXGIZMA

Page 16. USER RESPONSE FORM

tvDMX OVERVIEW Page 1
==============

This project was originally undertaken to enable programmers to quickly
design a browse-like data entry screen which users could operate in a
natural and intuitive way. It was completely redesigned for Turbo Vision.

The object-oriented framework of tvDMX can be extended to access any form
of data structure (including dBASE files and Streams and Collections).

tvDMX display formats use picture templates and grant the programmer full
control over the appearance of each field.

Features:

* programmable display formats for the major Pascal data types
* containment within a Turbo Vision scrolling view
* virtual methods provide maximum flexibility
* record structure and display format can be set at run-time
* hidden and read-only fields
* field display position order can differ from physical order


This document should give a quick introduction to tvDMX. Rather than
detail the inner workings, I decided to provide four sample programs
which you can examine:

SAMPLES.PAS displays several windows: Each with data in various formats.
Most of the scrolling data windows has an accompanying dialog window
which can be selected by pressing the key. This will give you an
idea of what tvDMX can do.

WORKSHOP.PAS is intended for your own experiments. It will give you an
idea of how easy it is to create a data window. WORKSHOP was written
so that you can easily modify the data structure and display formats.

FILESHOP.PAS manages data on disk via a TDosStream object --to show that
tvDMX operations are not limited to data in RAM.

DLGSHOP.PAS demonstrates how to integrate a tvDMX view into a dialog box.

The source code for each of these programs contains additional information
about its use and features.

tvDMX CONCEPTS Page 2
==============


The Data-Formatting Template
----------------------------

The default appearance of these views is usually column/row oriented.
You declare a record structure for the DMX initialization procedure in
a template string --which also determines the display format.
(You will see later how tvDMX can be used for field editors.)

A RECORD of STRING [20], INTEGER, and REAL may use this format:
' ssssssssssssssssssss | iiii | ($rrr,rrr.rr) '

And that would present a record in this way:
' Daniel D. Demo 154 $ 12,056.55 '


The template string in this example was entirely in lower case. If in
upper case, character-fields would be entered in upper case and
numeric-fields would be restricted to positive values.

The data TYPE of each field is determined by the characters in the string.
All primary Pascal data types are supported: BOOLEAN, BYTE, SHORTINT,
INTEGER, LONGINT, WORD, STRING, CHAR, arrays of CHAR, and REAL. The
programmer only needs to alter this one template string when changing the
data structure. (Template codes are listed on the Reference page.)

You can switch to SINGLE, DOUBLE or EXTENDED reals by changing TYPE
TREALNUM in RSET.PAS (registered version only).

A backslash ('\') may be used as a field delimiter, and is displayed as a
space character. (Other delimiters can be devised as well --please refer
to the ^D control code.)

The tilde ('~') character can be used to switch format-processing on and
off. This makes it possible to separate the text-literals from format and
control codes:

' ~Name:~ ssssssssssssssssssss\ ~SSN:~ ###-##-#### '

This is diplayed as:
' Name: Daniel D. Demo SSN: 012-34-5678 '

USING tvDMX IN YOUR PROGRAMS Page 3
============================

Data Windows
------------

Presumably you understand that a focused TScroller is owned by, and
operates within, an active TWindow. The TScroller also has several
peer-views: a TFrame and two TScrollBars. If you wished, you could add
more views to display additional information. This is how the
TDmxScroller object works, as well as its descendant TDmxEditor.

(A TDmxScroller object displays data in a scrolling window, and a
TDmxEditor object adds the ability to edit the data.)

Programmers can instantiate a TWindow view and insert a TDmxEditor object
just like using TScroller --with a few extra parameters. Then, for an
effective data window, field titles should be placed at the top, and a
record number indicator should be placed below.

The TDmxWindow object (a descendant of TWindow) coordinates the entire
process of inserting these extra views.

Initialization Syntax:

TDmxWindow.Init (var Bounds : TRect;
ATitle : TTitleStr;
ANumber : Integer;
ATemplate : String;
var AData;
BSize : LongInt;
var ALabels : String;
IndLen : Integer);

Bounds, ATitle and ANumber are the same parameters required for any
TWindow object.
ATemplate is a tvDMX data format template string.
AData refers to the data to be edited. Note that your data is not
part of this object.
BSize is the size of the entire data structure.
ALabels is the string which labels the fields over the editor.
IndLen is the length of a record number indicator view (usually about
five to ten bytes). The default indicator is placed just to the
left of the horizontal scroll bar.


Note: Since descendant objects are crucial to programmers who wish to
build upon the framework of tvDMX, it should be understood that
descendants of TDmxWindow must be written to initialize your descendants
of TDmxEditor.

Object TDmxWindow is declared in Unit StdDMX.
(Refer to the demo programs for sample usage.)

Page 4
Using tvDMX as Field Editors
----------------------------

It is only natural that a descendant of TDmxEditor would be written to
serve as a replacement for the TInputLine object.

Object TInputFields is a TDmxEditor derivative that: 1) Allocates memory
to hold the data fields; 2) Overrides the DataSize(), GetData() and
SetData() methods; 3) Uses a different palette suitable for Dialog boxes;
and 4) Has special handling of the cursor keys to operate more naturally
within a Dialog box.

TInputFields is rarely initialized directly. Instead, a special insertion
function was written to measure and initialize it with an accompanying
TLabel object:

Function InsertField (Dialog : PDialog;
Col, Row : Integer;
Fmt : Boolean;
ALabel,
ATemplate : String) : PView;

Dialog is a pointer to the dialog window into which these views are
inserted.
Col and Row are the upper left corner of the label.
Fmt orientation of the tvDMX editor view, relative to the label:
If TRUE, then the editor view is below the label; but
if FALSE, the editor view follows the label on same line.
ALabel is the string that will become the label.
ATemplate is the string that becomes the editor view.


This function returns a pointer to the TInputFields view. Usually, the
pointer will be discarded (this unit is compiled with extended syntax so
that the function can be implemented as a procedure), but there will be
occasions when the pointer is needed.

Examples:

InsertField (Dialog, 5,2, TRUE,
'~N~ame', 'SSSSSSSSSSSSSSSSSSSS');

InsertField (Dialog, 5,5, FALSE,
'~S~SN: ', '###-##-####')^.HelpCtx := 1000;

P := InsertField (Dialog, 5,6, FALSE, '', '$rrr,rrr.rr ');
{ note that a label is not required }



The dialog window examples in SAMPLES.PAS demonstrates the use and
operation of the InsertField() function. Press for a dialog window.

ADVANCED FEATURES Page 5
=================

Hidden and Read-Only Fields
---------------------------

Some programs use data with hidden fields. (dBASE files require a leading
byte at the beginning of each record.)

Some programs use fields which can be seen but not altered. (This may be
when the field is accessed by the program and not the user.)

Both of these situations are handled by control codes in the template
string that mark fields as Hidden or Read-Only.

Example: ^H + 'B' + #0 + ^R + ' iii |'...

^H + 'B' specifies a hidden BYTE field;
#0 marks a new field without a visible delimiter;
^R marks the next field as a Read-Only integer;
and so on...

Program users will recognize Read-Only fields because they have their own
color in the palette (when focused).


Swapping Field Positions
------------------------

Date fields are often arranged in Year-Month-Day order, but the
conventional display format is Month-Day-Year. The ^P control code makes
it possible to display and edit fields in a different order than in which
they are physically organized. This exchange is transparent to the user.

Unit DMXGIZMA contains fldDATE, a string constant that uses the ^P code to
display and edit a three-word date field. Here is how it works:

CONST fldDATE = ' WW-'^F^Z + ^U+char(12) + ^P+char(2) +
#0'ZW-'^Z + ^U+char(31) +
#0'ZZZW '^Z^F + ^P+char(-6) +
#0 + ^P+char(4);

fldDATE defines what is called a "complex field". The ^F control
code ensures that these three integer fields receive the same field
number. The ^P code uses the next character to adjust the data
pointer forward 2 bytes, backward 6 bytes, and then 4 bytes forward
again. This way, the YEAR-MONTH-DAY field can be displayed and
edited in MONTH-DAY-YEAR order, like this: ' 1-01-1992 '.
The ^U code is used to denote an upper limit for each field.
Refer to the section on control codes elsewhere in the documentation.

These advanced features are demonstrated in program SAMPLES.PAS.

ASCENDANCY CHART Page 6
================

+-------------+
| TObject |
+-------------+
|
+-------------+
| TView |
+-------------+
|
+-------------+
| TScroller |
+-------------+
|
|
+-------------------+
| |
| TDmxScroller |
| (unit tvDMX) |
| |
+-------------------+
|
|
+-------------------+
| |
| TDmxEditor |
| (unit tvDMX) |
| |
+-------------------+
|
|
+-----------+-----------+
| |
+-------------------+ +-------------------+
| | | |
| TDmxEditBuf | | TDmxEditDlg |
| (unit tvDMXBUF) | | (unit StdDMX) |
| | | |
+-------------------+ +-------------------+
| |
| |
+-------------------+ +-------------------+
| | | |
| TDmxStreamBuf | | TInputFields |
| (unit tvDMXBUF) | | (unit StdDMX) |
| | | |
+-------------------+ +-------------------+
|
|
+-------------------+
| |
| TDmxExpBuf |
| (unit tvDMXBUF) |
| |
+-------------------+

UNITS Page 7
=====


Unit RSET contains untyped constants and data types. No objects,
procedures, functions, or typed-constants are included.


Unit DMXGIZMA has several functions:

procedure AssignWinRect (var Bounds : TRect; MaxX, MaxY : Integer);
function DmxStrLen (S : string) : Integer;
function NextWindowNumber : Integer;

All DMX-specific constants and types are also declared here.


Unit tvDMX contains:

object TDmxLabels --a view which displays field titles

object TDmxRecNum --a view which displays the record number

object TDmxScroller --the link between object TScroller and DMX
(allows scrolling, but no editing)

object TDmxEditor --a data editor object
(descendant of object TDmxScroller)


Unit StdDMX contains:

object TDmxEditDlg --TDmxEditor derivative for dialog boxes

object TInputFields --TInputLine replacement for all data types

object TDmxViewer --TWindow descendant that initializes and
INSERTs a TDmxScroller object

object TDmxWindow --TDmxViewer descendant that initializes and
INSERTs a TDmxEditor object


Unit tvDMXBUF contains buffered tvDMX objects:

object TDmxEditBuf --TDmxEditor derivative which holds a buffer for
editing external data;

object TDmxStreamBuf --TDmxStreamBuf derivative for stream data;

object TDmxExpBuf --descendant of TDmxStreamBuf that expands as
records are appended (see FILESHOP.PAS)

objects TDmxBufWin and TDmxExpBufWin
--TDmxWindow descendants for control of the
previous two objects

DATA TEMPLATE CODES Page 8
===================


Field codes:

'S' --STRING field
'#' --STRING field (numbers only)
'C' --CHARacter field (can be used for CHAR arrays)
'0' --CHARacter field (numbers only)
'X' --BOOLEAN value field
'B' --BYTE field
'J' --SHORTINT field
'W' --WORD field
'I' --INTEGER field
'L' --LONGINT field
'R' --REAL number field (uses TYPE TREALNUM in RSET.PAS)
'N' --dBASE-formatted numeric CHAR field
'H' --HEXadecimal numeric entry


Field code modifier:

'Z' --zero modifier to force leading zeroes


Field control codes:

^A --show all zero values in all fields
^D --use the next character as a field delimiter
^F --start/end complex field
^H --hidden field
^P --display position modifier
^R --read-only field
^S --"skip" field (cursor will skip over it)
^U --set field's upperlimit (1 to 255 only)
^V --set field's default value
^X --special BOOLEAN field
^Z --show zeroes if this field is empty

'~' --switch string-literals on/off


Field Delimiters:

#0 --technical field delimiter (not displayed)
'\' --displayed as a space
'|' --displayed as a solid vertical line (#179)
#179 or #186 may also be used as delimiters

Using Template Codes Page 9
--------------------

STRING Fields:

's' regular STRING field
'S' STRING field (forces upper case)
'#' STRING field (numbers only)

These codes are used for normal Turbo Pascal STRING types.
If the '#' code is used then only spaces or numeric characters
('0'..'9') can be entered.

Examples: 'ssssssssssssssssssss'
'~Name:~ SSSSSSSSSSSSSSSSSSSS'
' ###-##-#### '


CHAR Fields:

'c' CHAR field
'C' CHAR field (forces upper case)
'0' CHAR field (numbers only)

Editing keys will operate in the same manner as STRING fields when
the field contains more than one character. (Use these codes for
dBASE file structures.)
If the '0' code is used then only spaces or numeric characters
('0'..'9') can be entered.

Examples: 'C'
'cccccccccccccccccccc'
'~Name:~ CCCCCCCCCCCCCCCCCCCC'
' 000-00-0000 '


BOOLEAN Fields:

'X' regular BOOLEAN field
^X indicates special BOOLEAN field

A regular BOOLEAN field will display the character ShowTRUE (as
defined in unit DMXGIZMA) or ShowFALSE, depending upon the value of
that field. A special BOOLEAN field has no indicator of its own
but will display the template only if the data is TRUE.

Examples: 'X'
'[X]'
'~TRUE~' + ^X

Page 10
INTEGER Fields:

'B' BYTE field
'J'/'j' SHORTINT field
'W' WORD field
'I'/'i' INTEGER field
'L'/'l' LONGINT field

'Z'/'z' ZERO modifier to display leading zeroes

The value of each field is limited to the natural limit of its
field TYPE, regardless of the displayed width of its template.
Upper case codes signify that negative numbers are not permitted.
(Case is not relevant for BYTE and WORD fields.)

The 'Z' modifier can be used to force the display of a leading zero
as long as the data type is in one of the template characters.

Examples: 'BBB'
'WWWWW'
'ZZZZW'
'ii,iii'
'%WZW'
'LLL,LLL,LLL'


REAL Number Fields:

'R'/'r' REAL number field

REAL numbers are declared like other numeric fields except that
parentheses '('/')' can be used to enclose the template. These
will be displayed only if the value is a negative number.

Floating point numbers other than of TYPE REAL can be used if
TYPE TREALNUM is changed in RSET.PAS. (See RSET.PAS.)

Examples: '($rrr,rrr.rr)'
'RRRRR.RRR'


Hexadecimal Fields:

'H' Hexadecimal numeric field

Used for displaying and editing data in hexadecimal formats. The
size and type of the field is dependent upon the number of H's.
This code is used extensively in unit tvDMXHEX.PAS.

Examples: 'HH'
'HHHH'
'HHHH:HHHH'

Page 11
dBASE-formatted numeric CHAR Fields:

'n' positive or negative values
'N' positive values only

These fields are stored as character arrays but are edited like
the numeric fields. This may be formatted like any numeric field
except that parentheses cannot be used.
dBASE date fields can be formatted using 'Z' modifiers and a
system of ^P codes. (See fldNDATE in FILESHOP.PAS.)

Examples: 'nnn'
'ZZN'
'nnnnn.nnn'
'$NNN,NNN.NN'


Template Control Codes
----------------------

Switch to Literals:

'~'

Switches DMX template interpretation to codes or literals. This
permits all characters to be used in a template string.

Examples: '~Name:~ SSSSSSSSSSSSSSSSSSSS'
'$RR,RRR.RR ~CR~'


Special Field Attributes:

^A show zeroes in all fields
^H Hidden field
^R Read-Only field
^S Skip field (cursor will skip over it)
^Z show zeroes if this field is empty

Every field has its own field-access attribute. They may be
combined if desired. ^A will function as a ^Z for each field.
Note that Hidden or Skip fields can still be zeroized when the
record is zeroized, unless it is also marked as Read-Only.


Define Template Delimiter:

^D + CHAR

Uses the following character as a field delimiter.

Examples: ^D + '-'
^D + #255

Page 12
Start/End Complex Field:

^F

Begins or ends a complex field. Each field within a complex field
is given the same field number so that the combined structure can
be treated as a singular item.

Example: ^F + ' BB | BB | WWWW ' + ^F


Position Modifier:

^P + CHAR

Sets the position within the record (and also the record size) to
another point relative to the number of bytes indicated by the
SHORTINT value of the following character. This is used by
fldDATE constant to swap the diplay positions of a date record from
Year-Month-Day to Month-Day-Year.
^P can also be used as an alternative to hidden fields.

Examples: ^P + char(20)
^P + char(-4)


Set Field Upper Limit:

^U + CHAR

The next character will be the field's upper limit (up to 255).
This is used by fldDATE to limit months to 12 and days to 31.

Example: ^U + char(12)


Set Field Default Value:

^V + CHAR

The following character will be the field's default value, which
is set when it is zeroized. Normally this would be zero for numerics
and spaces for character fields.

Example: ^V + '0'

FYI Page 13
===


Important Virtual Methods
-------------------------

The following is a short list of some of the virtual methods that may
be overridden in descendant objects.


Function TDmxEditor.DataAt (RecNum : integer) : pointer; VIRTUAL;

Returns a pointer to the given data record.
By overriding this function, a program can alter the manner in which
the database is organized. This method is used exclusively for data
retrieval --which gives programs the ability to access over 64k.

The objects in unit tvDMXBUF.PAS override this method to retrieve data
records from external sources, but they use a buffer to store enough
data to reduce delay from disk access while scrolling.

This object simply returns a pointer to the position in the database
from (RecNum * RecordSize).


Procedure TDmxEditor.EvaluateField; VIRTUAL;

Called AFTER each FIELD is edited. It adjusts internal fields and
calls DrawField() to redraw the field in the regular color.
Programmers who wish to override this method should call its ancestor
in the descendant object.


Procedure TDmxEditor.EvaluateRecord; VIRTUAL;

Called AFTER each RECORD is edited. The default method does nothing
and may be overrided entirely.


Procedure TDmxEditor.SetUpField; VIRTUAL;

Called BEFORE each FIELD is edited. May call RecInd^.DrawView(), if
a record number indicator view is linked.
Programmers who wish to override this method should call its ancestor
in the descendant object.


Procedure TDmxEditor.SetUpRecord; VIRTUAL;

Called BEFORE each RECORD is edited.
This can be intercepted to display special information (eg: record
number) or to rearrange the record before editing.
Programmers who wish to override this method should call its ancestor
in the descendant object.

Page 14

External Database Access
------------------------

TDmxEditBuf is a descendant of TDmxEditor that uses a circular buffer
to edit data from a source other than in RAM.

It retrieves each record individually when accessed. The buffer is
used only for quick page draws.

This object can be found in unit tvDMXBUF. It uses several abstract
methods and must not be instantiated as is. Objects TDmxStreamBuf and
TDmxExpBuf are usable descendants. Object TDmxExpBuf is demonstrated
in program FILESHOP.PAS.

Descendants MUST override functions SeekRec(), ReadRec() and WriteRec():


Function TDmxEditBuf.SeekRec (RecNum : integer) : boolean; VIRTUAL;
Override: Always

This abstract virtual method is called before reading or writing a
record. It must seek to the given record position. It is important
that you remember that the first record is numbered 0.
It should seek to RecNum+1 if the database is structured with record
number 1 as the first record.


Function TDmxEditBuf.ReadRec (var RecData ) : boolean; VIRTUAL;
Override: Always

Abstract virtual method called to retrieve record RecData. It must
return a record exactly the size that is determined by the template.


Function TDmxEditBuf.WriteRec (var RecData ) : boolean; VIRTUAL;
Override: Always

Abstract virtual method called by EvaluateRecord() to store record
RecData if a change was made.


These functions must perform their record operations at the current
record position and return TRUE if the operation succeeded or FALSE if
it failed. It is the programmer's responsibility to retain the error
code for use by the ErrorFunc() method.

TDmxEditBuf.ErrorFunc() is a virtual method that may be overridden for
special handling of database errors.

Please refer to file tvDMXBUF for more information.

Page 15

Global Functions in Unit DMXGIZMA
---------------------------------


Procedure AssignWinRect (var Bounds : TRect; MaxX, MaxY : integer);

Assigns Bounds to fit into the desktop, with MaxX and MaxY as the
maximum desired width and height. Bounds is cut and moved to a
cascaded position behind the currently active window. (This is
similar to what happens when a new file is loaded into the TP IDE.)


Function DmxStrLen (S : string) : integer;

Returns the length of the visible portions of a template string.


Function NextWindowNumber : integer;

Returns the next available (unused) window number.


Procedure TrimDialog (Window : PWindow);

Shrinks and centers a dialog window to ease the design process.
The dialog window should be initialized with the maximum size
allowable. TrimDialog() can be called after the controls are
inserted to resize the window down to the maximum size needed.
See program DLGSHOP.PAS for sample usage.

USER RESPONSE FORM Page 16
==================

If you have a printer: Please take a few moments to complete
as much of this form as possible.

(This form is duplicated in file REGISTER.TXT.)

Name _____________________________________________
Company _____________________________________________
Address _____________________________________________
City ____________________________, State _________
Zip ____________________________


How long have you been using Turbo Vision? ______

Which version of Turbo Pascal are you using? _____

List any programming tools/add-ins that you use:
___ AnsiView
___ Blaise: ________________________________________
___ Btrieve
___ DMX (original) --upgrade fee only $10
___ Paradox Engine
___ Topaz
___ TurboPower: ____________________________________

Others:



Print this form and send it with $20 registration fee to:

Randolph Beck
tvDMX Registration
P.O. Box 56-0487
Orlando, FL 32856-0487

----------------------------------------------------------------------

Add any additional questions or comments...