Catalog - stores and retrieves named objects
SYNOPSIS
#include <Unidraw/catalog.h>
DESCRIPTION
A catalog provides independent name-to-object mappings for
component subjects, commands, tools, and editor info
objects. Once named, an object can be retrieved later,
even if the application has been exited and restarted.
The catalog thus provides a means for saving objects in
non-volatile form for subsequent retrieval.
PUBLIC OPERATIONS
Catalog(const char* domainName, Creator*, float version)
Construct a catalog, supplying an application-
unique domain name, a creator object, and a version
number. Unidraw objects may use the domain name
for file type checking purposes, and they may rely
on the version number to handle evolving storage
formats.
virtual boolean Save(EditorInfo*, const char*)
virtual boolean Save(Component*, const char*)
virtual boolean Save(Command*, const char*)
virtual boolean Save(Tool*, const char*)
Save an object instance under the specified name.
The catalog stores a textual representation for the
object in a file with the given name; therefore a
name with embedded slashes corresponds to the path
name for the file containing the textual represen-
tation. These operations return false if the file
could not be written.
virtual boolean Retrieve(const char*, EditorInfo*&)
virtual boolean Retrieve(const char*, Component*&)
virtual boolean Retrieve(const char*, Command*&)
virtual boolean Retrieve(const char*, Tool*&)
Retrieve an object instance having the specified
name. The catalog reconstructs an instance of the
object from the corresponding file when the
instance is first retrieved. Subsequent retrievals
with the same name return a reference to the
instance already in memory. These operations
return false if the instance could not be recon-
structed from the file.
virtual void Forget(EditorInfo*, const char* = nil)
virtual void Forget(Component*, const char* = nil)
virtual void Forget(Command*, const char* = nil)
virtual void Forget(Tool*, const char* = nil)
Forget the name-to-object mapping for the given
which is useful when an instance has been saved
under different names.
virtual const char* GetName(EditorInfo*)
virtual const char* GetName(Component*)
virtual const char* GetName(Command*)
virtual const char* GetName(Tool*)
Get a name associated with an instance. These
operations do not specify which name is returned
for instances that have been saved under more than
one name.
virtual boolean Valid(const char*, EditorInfo*&)
virtual boolean Valid(const char*, Component*&)
virtual boolean Valid(const char*, Command*&)
virtual boolean Valid(const char*, Tool*&)
Return whether the given name has an instance
already associated with it (i.e., it has been saved
or retrieved) and if so return that instance in the
second parameter.
virtual Component* Copy(Component*)
virtual Command* Copy(Command*)
virtual Tool* Copy(Tool*)
Copy an instance by saving it under a temporary
name, then retrieving it, and finally forgetting
the temporary name. A component, command, or tools
subclass can use the corresponding function to
implement their Copy function easily, possibly at
the expense of run-time performance.
virtual boolean Exists(const char*)
Return whether a file with the given name exists.
A return value of true does not necessarily mean
that an object has been saved under the specified
name.
virtual boolean Writable(const char*)
Return whether it is permitted to save an object
under the given name.
void SetClipboard(Clipboard*)
Clipboard* GetClipboard()
Set or get a globally-accessible clipboard object.
void SetEditorInfo(EditorInfo*)
EditorInfo* GetEditorInfo()
Set or get a globally-accessible editor info
object.
const char* GetName()
Creator* GetCreator()
Return the values of constructor-specified parame-
ters.
float FileVersion()
Return the Unidraw version number of the file being
read currently.
const char* GetAttribute(const char*)
Return the value of a user preference with the
given name as stored in the global PropertySheet.
This operation is equivalent to the World operation
of the same name.
void WriteVersion(int, ostream&)
void WriteClassId(ClassId, ostream&, int id = 0)
void WriteComponent(Component*, ostream&)
void WriteCommand(Command*, ostream&)
void WriteTool(Tool*, ostream&)
void WriteStateVar(StateVar*, ostream&)
void WriteTransferFunct(TransferFunct*, ostream&)
void WriteBgFilled(boolean, ostream&)
void WriteBrush(PSBrush*, ostream&)
void WriteColor(PSColor*, ostream&)
void WriteFont(PSFont*, ostream&)
void WritePattern(PSPattern*, ostream&)
void WriteTransformer(Transformer*, ostream&)
void WriteString(const char*, ostream&)
void WriteControlInfo(ControlInfo*, ostream&)
void WriteEditorInfo(EditorInfo*, ostream&)
void WriteBitmap(Bitmap*, ostream&)
void WriteBitmapData(Bitmap*, ostream&)
void WriteGraymap(Raster*, ostream&)
void WriteGraymapData(Raster*, ostream&)
void WriteRaster(Raster*, ostream&)
void WriteRasterData(Raster*, ostream&)
int ReadVersion(istream&)
ClassId ReadClassId(istream&, int& id)
Component* ReadComponent(istream&)
Command* ReadCommand(istream&)
Tool* ReadTool(istream&)
StateVar* ReadStateVar(istream&)
TransferFunct* ReadTransferFunct(istream&)
int ReadBgFilled(istream&)
PSBrush* ReadBrush(istream&)
PSColor* ReadColor(istream&)
PSFont* ReadFont(istream&)
PSPattern* ReadPattern(istream&)
Transformer* ReadTransformer(istream&)
char* ReadString(istream&)
ControlInfo* ReadControlInfo(istream&)
EditorInfo* ReadEditorInfo(istream&)
Bitmap* ReadBitmapData(istream&)
Raster* ReadGraymap(istream&)
Raster* ReadGraymapData(istream&)
Raster* ReadRaster(istream&)
Raster* ReadRasterData(istream&)
Write and read information via streams. Catalog-
managed classes use these operations in their Write
and Read functions to write and read the objects
they contain. The operations for writing and read-
ing bitmaps and rasters have accompanying opera-
tions that write and read only the ASCII data
(i.e., omitting transformation and other Unidraw
format-specific data) that encodes their informa-
tion content.
PSBrush* ReadBrush(const char* definition, int index)
PSColor* ReadColor(const char* definition, int index)
PSFont* ReadFont(const char* definition, int index)
PSPattern* ReadPattern(const char*, int index)
Return a PostScript paint object corresponding to
the value of a user preference with the given defi-
nition and index number as stored in the global
PropertySheet. Each string in the X defaults
database of the form ``<application-
Name>.resource:definition'' sets a resource. The
resource names and their definitions are specified
as follows:
brushi: Define the ith brush resource. The Read-
Brush operation retrieves the brush object for this
resource given a definition. The definition usu-
ally specifies two numbers: a 16-bit hexadecimal
number to define the brush's line style (each 1 bit
draws a dash and each 0 bit produces a gap), and a
decimal integer to define the brush's width in pix-
els. For example, ``ffff 1'' defines a single
pixel wide solid line. If the definition specifies
only the string ``none'', then it defines the
nonexistent brush.
fgcolori: Define the ith foreground color resource.
The ReadColor operation retrieves the color object
for this resource given a definition. The defini-
tion contains a string defining the name of the
color, optionally followed by three decimal numbers
between 0 and 65535 to define the red, green, and
blue components of the color's intensity. The
intensities override the name; that is, the catalog
will look the name up in the database of common
colors only if you omit the intensities. For exam-
ple, ``Indigo 48896 0 65280'' defines a color which
is a mixture of red and blue. You can define shades
bgcolori: The background color resource definition
is specified in the same manner as the foreground
color.
fonti: Define the ith font resource. The ReadFont
operation retrieves the font object for this
resource given a definition. The definition con-
tains three strings separated by whitespace. The
first string defines the font's name, the second
string the corresponding print font, and the third
string the print size. For example, ``8x13bold
Courier-Bold 13'' defines the third font entry.
patterni: Define the ith pattern resource. The
ReadPattern operation retrieves the pattern object
for this resource given a definition. The defini-
tion can specify the pattern for a 16x16 bitmap, a
8x8 bitmap, a 4x4 bitmap, a grayscale number, or
the string ``none''. You specify the 16x16 bitmap
with sixteen 16-bit hexadecimal numbers, the 8x8
bitmap with eight 8-bit hexadecimal numbers, the
4x4 bitmap with a single 16-bit hexadecimal number,
and the grayscale number with a single floating
point number. The floating point number must con-
tain a period to distinguish itself from the single
hexadecimal number, and it must lie between 0.0 and
1.0, where 0.0 corresponds to a solid pattern and
1.0 to a clear pattern. On the printer, the bitmap
patterns appear as bitmaps, the grayscale patterns
appear as halftoned shades, and the ``none'' pat-
terns never obscure underlying graphics. For exam-
ple, ``pattern8:8421'' defines a diagonally hatched
pattern.
PSBrush* FindNoneBrush()
PSBrush* FindBrush(int, int)
PSColor* FindColor(const char*, int = 0, int = 0, int = 0)
PSFont* FindFont(const char*, const char*, const char*)
PSPattern* FindNonePattern()
PSPattern* FindGrayLevel(float)
PSPattern* FindPattern(int[], int)
Return a PostScript paint object with the corre-
sponding attributes. These operations return a new
paint object if no object with the given attributes
already exists; otherwise the operations return an
existing instance with matching attributes.
void Skip(istream&)
void Mark(ostream&)
Mark injects a synchronization sequence defined by
input stream and position the stream immediately
after that sequence.
PROTECTED OPERATIONS
void Register(EditorInfo*, const char*)
void Register(Component*, const char*)
void Register(Command*, const char*)
void Register(Tool*, const char*)
Register an object under a particular name in the
catalog's internal maps. Objects are normally reg-
istered automatically when they are stored or
retrieved.
int GetToken(istream&, char* buf, int buf_size)
Search an input stream for a sequence of characters
defined in the buffer buf of size buf_size. GetTo-
ken returns the number of characters matched.
SEE ALSO
Clipboard(3U), Command(3U), Component(3U), Con-
trolInfo(3U), Creator(3U), EditorInfo(3U), Graphic(3U),
PropertySheet(3I), StateVar(3U), Tool(3U), Transfer-
Funct(3U), World(3I), globals(3U), istream(3C++),
ostream(3C++)
Man(1) output converted with
man2html