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