MarkzFrame Portable Framework

The following is only partial documentation of MarkzFrame---a cross-platform

framework that is currently being integrated in stand-alone readers within Quark
and Adobe plug-ins. Note that the classes and methods described here are
already implemented in some of the plug-in code, so this framework is far from an
“idea”. It is real code that works.

Only a small part of the framework is documented here, the purpose is to

familiarize everyone with its possibilities.

Base Class

Every class in MarkzFrame is derived from a base class called MZObject. The
purpose of the base class is memory management. Inside the MZObject is a usage
counter, which can be manipulated by the application. This counter can be
incremented and decremented throughout the application, and by doing so,
MarkzFrame knows when it is able to permanently delete the object.

Hence, objects can be “retained” by various portions of the code by incrementing

the usage counter. Once it is done using the object, it decrements the counter,
and if the counter decrements to zero, the object is deleted. Not only does this
allow the same instance of the object to be passed around, it also guards against
memory leaks. When the application terminates, a debug check can be performed
to make sure all objects have been disposed properly.

Since every object in MarkzFrame is derived from MZObject, the following

methods apply to every class in the framework:

MZObject * retain (void);

“Retains” the object by incrementing its usage counter. The function returns
“itself”, which can be ignored, or stored somewhere. A newly created object
automatically has its usage counter set to ‘1’.

void release (void);

“Releases” the object be decrementing its usage counter. If the usage counter
decrements to zero, the object is deleted.

Note that by balanced pairs of retain() and release(), there is no need for an
application to ever use the “delete” keyword, as objects are automatically
released when the usage counter goes to zero.

This scheme is highly beneficial in debug mode, as the system will catch an
attempt to release a deleted object, as well as catch memory leaks when the
application quits.
Dictionaries and Arrays
A highlight of MarkzFrame is its high level dictionary and array objects. A
dictionary object presents a value pair collection of objects that can be “looked
up” with a known key. A dictionary object is essentially a database of arbitrary
objects, each with a unique “name” associated to it.

For example, a document reader module would typically create a dictionary of all
elements in a document. The lookup key “fonts” would return an array of all used
fonts; the key “images” would return an array of images, etc.

An array object is dynamic collection of objects that can be accessed via an index.
For instance, an array of images would contain a list of images that can be
randomly accessed, from 0 to n images – 1.

As in all MarkzFrame classes, both MZDictionary and MZArray are derived from
MZObject.

MZDictionary (Value pair “lookup” array)

Methods

void put (MZStr key, MZObject *obj);

MZObject * get (MZStr key);

The “put” function adds any object to the dictionary, associated with the key.
Later, this object can be retrieved by passing the key to the “get” method.
Example:

MyDictionary->put (“magenta”, colorObj);

…then:
colorObj = MyDictionary->get(“magenta”);

MZObject * get (long index);

An alternative method to retrieve an object, by its index, if known (zero-based).

long count (void);

Returns the number of objects currently in the dictionary.

MZArray (a variable length array of objects)

Methods

void addElement (MZObject *element);

Appends an object to the array.

void insertElement (MZObject *element, long beforePosition);

Inserts an object before the stated position (zero-based).

MZObject * elementAt (long index);

Returns the nth element in the array, which is an object that was added earlier.
The index is zero-based.

void remove (long index);

void remove (MZObject *obj);

Removes an object. The first method removes the nth object, while the second
method locates the object that matches obj and removes it.

void clear (void);

Clears all objects in the array.

MZString (High-level string class)

A great deal of code is spent on string manipulation. The MZString accommodates

nearly all functionality that is needed for this purpose. And, like all MarkzFrame
objects, the MZString is derived from MZObject, which makes it easy to debug and
detect memory leaks.

MZString – constructors

MZString::MZString (void) – Creates an empty (zero-length) string.

MZString::MZString (MZStr str) – Creates a string from the c-string str.

MZString::MZString (MZStr str, long length) – Creates a string from str of length
characters length.

MZString::MZString (MZUStr ustr) – Creates a string from a Unicode string (zero-

terminated).

MZString::MZString (MZUStr ustr, long length) – Creates a string from a Unicode

string of length characters.

Methods

MZStr getData (void);

MZUStr getUData (void);
Returns the string itself. For getData(), the resulting data is a c-string, while
getUData() returns a Unicode string.

long size (void);

Returns the current length of the string.

long indexOf (char chr, startPosition = 0, ignoreCase = false);

long indexOf (MZStr str, startPosition = 0, ignoreCase = false);

Returns the position of the first character found (first method) or the string
(second method). If not found, the result is –1. The startPosition parameter is
optional, and can be set to the character to start the search. If the optional
parameter ignoreCase is false, the search is case-sensitive.

MZBoolean equals (MZStr str, ignoreCase = false);

MZBoolean startsWith (MZStr str, ignoreCase = false);
MZBoolean endsWith (MZStr str, ignoreCase = false);

Compares for a match (equals), compares a match for the string’s prefix
(startsWith) or its suffix (endsWith). In each method, the ignoreCase is optional,
defaulting to false.

void concat (MZStr str);

void concat (MZStr str, long length);
void concat (MZStr str, long position, long length);

Concatenates (appends) a string to the existing string. Identical functions exist for
Unicode strings.

void insert (MZStr str, long position);

void insert (MZStr str, long position, long length);

Inserts a string into the existing string, beginning at position (zero-based). The
second method allows a length parameter.

void delChars (long position, long length);

Deletes the character(s) at position for the specified length.

void numToString (long intValue);

void numToString (double doubleValue, int decimals);

Appends a numeric representation to the string. In the first method, a whole

(signed) integer is appended; in the second method, a double value is appended,
with the number of decimals specified.

double stringToNum (void);

double stringToNum (long fromPosition);

Returns a numeric value of the string. Decoding occurs until the a non-numeric
character is encountered, or the end of the string, whichever comes first. The
returned value is a double, but can be coerced to an integer if the string value is
known to be a whole number.

void toCString (MZStr str);

void toPString (MZStr str);

Sets the buffer str to the existing string. The first method copies to a c-string, the
second method copies to a pascal string.

File Handling
One of the most problematic areas of portability is file handling. Under Mac OS-9,
for instance, the FSSpec structure is used to identify a file, whereas this is
incompatible with the Windows pathname model. Even the Unix-based OS-X is
somewhat incompatible with Windows since it uses the forward slash (/) and is
unfamiliar with the Windows convention of device notation (e.g., “C:\pathname”).

Additional problems arise if we consider data streams beyond the hard drive, such
as web-based files and internet URL’s.

MarkzFrame solves these incompatibilities with MZUrl object:

MZUrl (Universal File Identifier)

The MZUrl object contains sufficient information to identify a file location, be it the
hard drive, or an internet file, even a memory-based file, regardless of platform.
The object allows implements constructors, as follows.

MZUrl::MZUrl (MZStr path) – Creates a file identifier from a pathname, which is an

ASCII string. The path can be a native path or an internet URL. The implantation
code will correctly parse the path to identify the file.

MZUrl::MZUrl (MZUrl *basedOn, MZStr path) – Creates a file identifier of a file path,
relative to the basedOn file.

MZUrl::MZUrl (MZStr filename, long dir1, long dir2) – Creates a file based on the
OS-9 “FSSpec” parameters.

MZUrl Methods

MZBoolean exists (void);

Returns TRUE if the file pointed to by the MZUrl exists, FALSE if the file does not
exist.
MZInputStream* openStream (void);

Creates an MZInputStream, an object that can read data from a file stream
(documented below). The stream is based on the file location identified in the
MZUrl. If the stream cannot be created (i.e., the file does not exist), openStream()
returns NULL.

MZOutputStream* openOutStream (void);

Creates an MZOutputStream, an object that can write data to a file. If the file does
not exist, one is created.

MZArray* enumFiles (MZBoolean includeSubfolders,

MZFileFilter *filter);

Returns an array of MZUrl’s containing all the files within a directory pointed to by
the MZUrl. If includeSubfolders is TRUE, subfolders within the director are also
iterated. The filter parameter is optional, and contains a special class to examine
each file encountered, accepting or rejecting it to the resulting list. The function
result is an MZArray, which is an object containing an array of other objects
(documented later).

The MZInputStream (an object that reads file data)

The MZInputStream is a high-level, portable object that allows random access to a

data file. Usually, an MZInputStream is created by calling the openStream()
method of an MZUrl.

Methods

long read (fileData data, long byteSize, long *bytesRead);

long read (fileData data, long *byteSize, long);
long read (MZStrPtr str, long &byteSize);

These three methods read data from the stream, returning non-zero if
unsuccessful. The first two read generic, binary data (fileData is basically an
unsigned char*). The third method loads a string object with byteSize bytes.

long setFPos (long position);

long getFPos (void);

Sets/gets the file position.

long getEOF (void);

loid setEOF (long eof);

Gets/sets the end-of-file marker of the stream.

void skip (long count);

Skips count bytes form the current position without reading any data.

MZFileDlog – An Open / Save File Dialog

The MZFileDlog invokes the platform-specific “GetFile” or “PutFile” dialog. Its

methods are portable across platforms.

Methods

void setAcceptedExtension (MZStr extension);

Sets a file extension to be accepted in the file list (such as “.txt”, “.gif”, etc.). You
can set as many extensions as you want. Setting none results in the acceptance
of all file types.

void setAcceptedType (long type);

Sets a file (Mac) type to be accepted in the file list. On the PC, this value is
ignored. You can set as many file types as you want. Setting none results in the
acceptable of all types.

MZUrl * getFile (MZStr prompt, MZFileFilter *filter);

Invokes the “getFile” dialog, native to the OS. The prompt is displayed in the
appropriate place (e.g., “Open Document”, “Locate File…”, etc.). The filter
parameter is an optional object that can be subclassed to accept types as they
are encountered. If the user selects a file, an MZUrl object is returned. If no file is
accepted, getFile returns NULL. The resulting MZUrl, if any, can be used to open a
file stream.

MZUrl *putFile (MZStr prompt, MZStr defName);

Invokes the “putFile” (save) dialog, native to the OS. The prompt is displayed in
the appropriate place, and defName is the default name for the file to be saved
(which can be NULL for no name). If the user doesn’t cancel, putFile returns an
MZUrl object representing the file target. This object can be subsequently used to
create an output stream.

MZArray * getMultipleFiles (MZStr prompt, MZFileFilter *filter);

Same as getFile except the user can select more than one file (control-click for PC,
command-click for Mac). If the user does not cancel, getMultipleFiles returns an
array of MZUrl objects representing the path for each file (see MZArray class).