Provided by: ivtools-dev_1.2.11a1-2_amd64 
NAME
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
representation. 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 reconstructed 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 instance. If the optional string
is supplied, the catalog forgets a specific name-to-object mapping, 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()
float GetVersion()
Return the values of constructor-specified parameters.
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* ReadBitmap(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 reading bitmaps and rasters have
accompanying operations that write and read only the ASCII data (i.e., omitting
transformation and other Unidraw format-specific data) that encodes their
information 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 definition and index number as stored in the global PropertySheet.
Each string in the X defaults database of the form
``<applicationName>.resource:definition'' sets a resource. The resource names and
their definitions are specified as follows:
brushi: Define the ith brush resource. The ReadBrush operation retrieves the brush
object for this resource given a definition. The definition usually 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 pixels. 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 definition
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 example, ``Indigo 48896 0 65280'' defines a color which is a
mixture of red and blue. You can define shades of gray by using equal proportions
of each primary color.
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 contains 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 definition 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 contain 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'' patterns never obscure underlying graphics. For
example, ``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 corresponding 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 MARK (see globals(3U)) into the
output stream. Skip searches for the same sequence in the given 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 registered 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. GetToken returns the number of characters matched.
SEE ALSO
Clipboard(3U), Command(3U), Component(3U), ControlInfo(3U), Creator(3U), EditorInfo(3U),
Graphic(3U), PropertySheet(3I), StateVar(3U), Tool(3U), TransferFunct(3U), World(3I),
globals(3U), istream(3C++), ostream(3C++)