home *** CD-ROM | disk | FTP | other *** search
/ Acorn User 10 / AU_CD10.iso / Updates / Perl / Non-RPC / Docs / RISCOS-Library-Docs / Object.pm < prev    next >
Text File  |  1999-04-17  |  7KB  |  186 lines
  1. NAME
  2.     RISCOS::DrawFile::Object
  3.  
  4. SYNOPSIS
  5.     Abstract base class for DrawFile objects.
  6.  
  7. DESCRIPTION
  8.     `RISCOS::DrawFile::Object' provdes an abstract base class for
  9.     DrawFile objects to inherit from. It provides various methods,
  10.     some of which are inherited from `RISCOS::DrawFile::Common' and
  11.     hence are also can be used on entire DrawFiles. See `the
  12.     RISCOS::DrawFile::OpaqueObject manpage' for a minimal usable
  13.     implementation of a DrawFile object.
  14.  
  15.   Methods
  16.  
  17.     new <data>, [<split function>, ...]
  18.         Create a new DrawFile object. If `data' is not a reference
  19.         it is assumed to be packed data, and the first 4 bytes are
  20.         interpreted as an integer to get the object type. If a
  21.         second argument is provided, a reference to code is assumed
  22.         to be a split function with the same interface as
  23.         drawplus_split_type, and will be called to split the
  24.         extended object tag. If the second argument is a reference
  25.         to an array it is assumed to give (type, layer, flags,
  26.         spare), and these values are used in place of any derived
  27.         from the first 4 bytes.
  28.  
  29.         If *data* is a reference to an object of the same class as
  30.         the new object will become then it is `Clone()'ed and a list
  31.         containing the clone returned. This allows all derived
  32.         classes to easily implement a copy constructor.
  33.  
  34.         In scalar context `new' returns a blessed reference to the
  35.         new object. In array context `new' returns a list (object,
  36.         type, fonttable). *object* can be a reference to a list of
  37.         objects, and *fonttable* is normally `undef'. See
  38.         `RISCOS::DrawFile::FontTable' for the procedure to return a
  39.         fonttable if found.
  40.  
  41.         Subclasses are expected to treat *data* as based on its
  42.         type. If a subclass recieves a reference to a list rather
  43.         than a single blessed reference then it should return
  44.         immediately with that list, as `new' has been used as a copy
  45.         constructor.
  46.  
  47.     scalar  raw bytes from a DrawFile
  48.  
  49.     scalar reference
  50.             raw bytes from a DrawFile, with type, length and
  51.             bounding box stripped
  52.  
  53.     array reference
  54.             object dependent list of parameters to construct a new
  55.             object
  56.  
  57.  
  58.         If a second argument is proviced `new' sets the Layer, Flags
  59.         and Spare members of the object to the supplied/split
  60.         values. `new' never sets the Type member of the object - it
  61.         is the responsibility of the derived class to store the Type
  62.         member as if it needs to retain this information.
  63.  
  64.     PrePack <hash_reference>
  65.         is provided as a hook to perform calculations immediately
  66.         before saving a DrawFile. The hash reference is used to
  67.         store the names of fonts needed in the FontTable, keys are
  68.         font names, values the number of text objects that use that
  69.         font (see `PrePack' in `RISCOS::DrawFile::Text' if you
  70.         really must know). The default `PrePack' calls `BBox' and
  71.         returns this value. This ensures that if any objects have
  72.         been changed then their containing groups' bounding boxes
  73.         will be upadated to reflect this. Derived classes should
  74.         maintain this behaviour.
  75.  
  76.     Type
  77.         returns the objects type. The default method looks in
  78.         '`__TYPE'', which relies on the derived class storing it
  79.         there. If your derived class does not need to store the Type
  80.         you must override this method, typically with something like
  81.  
  82.             sub Type { 2; }
  83.  
  84.  
  85.         Most classes don't need to store the type, as most classes
  86.         deal with only one type of object. Exceptions include
  87.         `OpaqueObject', which stores all unknown object types, and
  88.         `Text', which implements normal text (type 1) and
  89.         transformed text (type 12).
  90.  
  91.     Layer [<new_layer>]
  92.         returns the current layer. If an argument is provided it is
  93.         used to set the ojbects layer, and the old layer is
  94.         returned.
  95.  
  96.     PackType [<type>]
  97.         packs the object's tag (type) into a 4 byte string. If the
  98.         object has a layer defined then DrawPlus extended tag format
  99.         is used.
  100.  
  101.         The tag is taken from the first argument if supplied, else
  102.         it is looked up as '`__TYPE''. Note that `new' in
  103.         `RISCOS::DrawFile::Object' does not set '<__TYPE>', instead
  104.         returning the value to the derived class.
  105.  
  106.     PackTypeSizeBBox <tag>, <size>, <bounding_box>
  107.         returns a 24 byte string for the header common to all
  108.         DrawFile objects (apart from FontTables).
  109.  
  110.         *type* is passed to `PackType' and the method `Size' is
  111.         called if *size* is undefined. If *bounding_box* is defined
  112.         then the object bounding box is taken from it - if
  113.         *bounding_box* is an array reference should point to 4
  114.         values, otherwise arguments three to six are taken to be the
  115.         bounding box. If *bounding_box* is undefined then the method
  116.         `BBox' is called, and (0,0,0,0) used if this returns
  117.         `undef'.
  118.  
  119.         Usually `PackTypeSizeBBox' can be called with no arguments
  120.         and it will do the right thing.
  121.  
  122.     Write <filehandle>, <fonttable>, ...
  123.         writes the object to the given filehandle. The default
  124.         implementation `print's the result of calling `Pack' with
  125.         the remainder of the argument list. `Write' should return
  126.         true unless there was an error.
  127.  
  128.  
  129.   Methods supplied by `RISCOS::DrawFile::Common'
  130.  
  131.     Clone
  132.         returns a copy of this object.
  133.  
  134.     BBox
  135.         returns a reference to an array giving the bounding box, or
  136.         `undef' if there is is no bounding box for this object
  137.         (*i.e.* font tables, empty paths, option objects). Note that
  138.         option objects and empty paths store a bounding box of
  139.         (0,0,0,0) when saved. `BBox' will attempt to call
  140.         `BBox_Calc' (which the derived class must provide) if the
  141.         bounding box is currently unknown.
  142.  
  143.         As the returned array reference is the internal copy of the
  144.         bounding box it must not be modified.
  145.  
  146.     Inside <bbox>
  147.  
  148.     InsideOrTouching <bbox>
  149.  
  150.     Intersect <bbox>
  151.  
  152.     IntersectOrTouching <bbox>
  153.  
  154.     Outside <bbox>
  155.         return a reference to the object if it has the correct
  156.         relationship with the bounding box (passed as an array
  157.         reference), `undef' if it does not.
  158.  
  159.  
  160.   Methods derived classes must supply
  161.  
  162.     In addition to the overriding above methods where appropriate
  163.     (in particular `Type') derived classes must provide the
  164.     following methods
  165.  
  166.     BBox_Calc
  167.         (re)calculates the bounding box, returning a reference to an
  168.         array, or undef if there is no bounding box. As it has no
  169.         idea about the data it contains `OpaqueObject' simply
  170.         returns the bounding box it was given when it was called.
  171.  
  172.     Size
  173.         returns the size of the object when saved in a DrawFile
  174.  
  175.     Pack <undef>, fonttable, ...
  176.         returns a scalar containing the object packed ready to save
  177.         into a DrawFile.
  178.  
  179.  
  180. BUGS
  181.     Not tested enough.
  182.  
  183. AUTHOR
  184.     Nicholas Clark <nick@unfortu.net>
  185.  
  186.