home *** CD-ROM | disk | FTP | other *** search
/ Acorn User 10 / AU_CD10.iso / Updates / Perl / Non-RPC / Docs / RISCOS-Library-Docs / DrawFile.pm < prev    next >
Text File  |  1999-04-17  |  4KB  |  95 lines
  1. NAME
  2.     RISCOS::DrawFile
  3.  
  4. SYNOPSIS
  5.     A class to manipulate DrawFiles
  6.  
  7. DESCRIPTION
  8.     `RISCOS::DrawFile' provides a class to manipulate DrawFiles. It
  9.     is derived from `RISCOS::DrawFile::Container' (which provides
  10.     all the really cool methods), and provides the following
  11.     additional methods.
  12.  
  13.     new [<contents>, [<creator>, [<oldfont>, [<filetype>]]]]
  14.  
  15.     new <filename>, [<split_function>]
  16.         creates a new DrawFile. If the first argument is `undef' or
  17.         a reference to an array it is taken to be an array of
  18.         objects derived from <RISCOS::DrawFile::Object> which are to
  19.         be used as the contents. Otherwise the first argument is
  20.         passed to `RISCOS::File::load', so *filename* can actually
  21.         be a filehandle, or the file data to use.
  22.  
  23.         *creator* defaults to `"PerlDraw$VERSION"', which at 12
  24.         characters can cause problems for some drawing programs
  25.         (*e.g.* DrawPlus prior to 2.41). *oldfont* if defined should
  26.         be a reference to an array of fonts found when loading the
  27.         DrawFile and isn't really used, as
  28.         `RISCOS::DrawFile::TextObject' objects each store their own
  29.         font. *filetype* defaults to 0xAFF (DrawFile).
  30.  
  31.         *split_function* is passed as the second argument to
  32.         `RISCOS::DrawFile::Object::new' for each object found in the
  33.         DrawFile to process the DrawFile object type to extract
  34.         layer information. If defined this should either be a code
  35.         reference, or the string '`+'' to use
  36.         `RISCOS::DrawFile::Common::drawplus_split_type'
  37.  
  38.     Write <filename>
  39.  
  40.     Write <filehandle>
  41.         writes the DrawFile to the given filename or filehandle, and
  42.         attempts to set the file's filetype to the type set/returned
  43.         with `FileType'. Calling this Write as a class method will
  44.         write an empty DrawFile:
  45.  
  46.             Write RISCOS::DrawFile ('DrawFile')    # Write a blank DrawFile
  47.             RISCOS::DrawFile->Write ('DrawFile')   # There's More Than One Way To Do It
  48.  
  49.  
  50.     Major
  51.         returns the major version number of this DrawFile, which
  52.         will always be 201. `new' will correctly refuse to load
  53.         DrawFiles with any other major version number.
  54.  
  55.     Minor [<version>]
  56.         returns the minor version number of this DrawFile. If an
  57.         defined argument is supplied sets the minor verion to this,
  58.         and returns the old value.
  59.  
  60.     Creator [<creator>]
  61.         returns the creator string for this DrawFile. If an defined
  62.         argument is supplied sets the creator, and returns the old
  63.         value. Creator strings are truncated or padded with spaces
  64.         to give 12 characters when the DrawFile is written out. Note
  65.         that 12 character creator names can cause problems for
  66.         poorly written programs.
  67.  
  68.     FileType [<filetype>]
  69.         returns the filetype that `Write' will give this file. If
  70.         *filetype* is supplied this value is set, and the old value
  71.         returned. The value is stored verbatim, relying on
  72.         `RISCOS::File::settype' to do any conversion necessary. If
  73.         the filetype is `undef' then `Write' will not attempt to set
  74.         the filetype.
  75.  
  76.         Note that while `RISCOS::DrawFile' has no problem loading
  77.         Equasor files, the file written out will have the FontTable
  78.         as first object, rather than the tagged empty path that
  79.         Equasor expects, and so Equasor will refuse to recognise the
  80.         file. Regrettably the transparency that `RISCOS::DrawFile'
  81.         by automaticaly tabulating fonts and creating a FontTable
  82.         means that it is not possible for this general purpose class
  83.         to ensure that the FontTable is at a specific loation within
  84.         the file. (Well, not without breaking various other programs
  85.         that wrongly expect the FontTable to be the very first
  86.         object in a file. RTFM carefully.)
  87.  
  88.  
  89. BUGS
  90.     Not tested enough. Especially `Pack'
  91.  
  92. AUTHOR
  93.     Nicholas Clark <nick@unfortu.net>
  94.  
  95.