home *** CD-ROM | disk | FTP | other *** search
/ Acorn User 10 / AU_CD10.iso / Updates / Perl / Non-RPC / Docs / RISCOS-Library-Docs / Common.pm < prev    next >
Text File  |  1999-04-17  |  5KB  |  122 lines
  1. NAME
  2.     RISCOS::DrawFile::Common
  3.  
  4. SYNOPSIS
  5.     Methods common to DrawFiles and objects within DrawFiles.
  6.  
  7. DESCRIPTION
  8.     `RISCOS::DrawFile::Common' provides methods common to DrawFiles
  9.     and to objects within DrawFiles. It provides one function
  10.     `drawplus_split_type'.
  11.  
  12.   drawplus_split_type
  13.  
  14.         $type = drawplus_split_type 0x00010402;        # $type = 0x02
  15.         ($type, $layer, $flags, $spare) = drawplus_split_type $type;
  16.  
  17.  
  18.     `drawplus_split_type' takes an integer and interprets it as a
  19.     DrawPlus "extended tag". In scalar context it returns the
  20.     standard draw type, in array context the list (type, layer,
  21.     flags, spare), as described in the DrawPlus documentation.
  22.  
  23.   Methods
  24.  
  25.     Clone
  26.         returns a copy of this object. Derived class implementors
  27.         should see the RISCOS::Clone manpage for the cloning
  28.         teqnique, and the assumptions it makes.
  29.  
  30.     BBox
  31.         returns a reference to an array giving the bounding box, or
  32.         `undef' if there is is no bounding box for this object
  33.         (*i.e.* font tables, empty paths, option objects). Note that
  34.         option objects and empty paths store a bounding box of
  35.         (0,0,0,0) when saved. `BBox' will attempt to call
  36.         `BBox_Calc' (which the derived class must provide) if the
  37.         bounding box is currently unknown.
  38.  
  39.         As the returned array reference is the internal copy of the
  40.         bounding box it must not be modified.
  41.  
  42.     Translate <x> <y> [<barf_func>]
  43.         translates the object by (*x*, *y*), or calls
  44.         &*barf_func* (*object*, *x*,  *y*) for any object for which
  45.         translation is not possible (*i.e.* unknown objects and
  46.         tagged objects, as the tag data might contain co-ordinate
  47.         information. If *barf_func* is undefined a warning is
  48.         issued, while an empty string silences any warning, and
  49.         assumes that altering the bounding box of any unknown object
  50.         is sufficient to perform the translation.
  51.  
  52.     Inside <bbox>
  53.         checks whether this object is entirely within the bounding
  54.         box (passed as an array reference). Returns a reference to
  55.         the object if it is, an empty list if it touches, intersects
  56.         or lies outside the box. The empty list `()' is converted to
  57.         `undef' in scalar context, whereas returning `undef' in list
  58.         context would generate a one element list `(undef') which
  59.         can cause surprises.
  60.  
  61.     InsideOrTouching <bbox>
  62.         checks whether this object is entirely within or touching
  63.         the bounding box (passed as an array reference). Returns a
  64.         reference to the object if it is, `()' if it intersects or
  65.         lies outside the box.
  66.  
  67.     Intersect <bbox>
  68.         checks whether any of this object's bounding box is within
  69.         the bounding box (passed as an array reference). Returns a
  70.         reference to the object if it is, `()' if it lies outside
  71.         the box (including just touching the edge).
  72.  
  73.     IntersectOrTouching <bbox>
  74.         checks whether any of this object's bounding box is within
  75.         the bounding box, or is touching the box (passed as an array
  76.         reference). Returns a reference to the object if it is, `()'
  77.         if it lies outside and is not touching the box.
  78.  
  79.     Outside <bbox>
  80.         checks whether this object's bounding box is entirely
  81.         outside the bounding box (passed as an array reference).
  82.         Returns a reference to the object if it is, `()' if any part
  83.         of the bounding box touches or intersects the box.
  84.  
  85.  
  86.   Methods derived classes must supply
  87.  
  88.     In addition to the overriding above methods where appropriate
  89.     (in particular `Type') derived classes (DrawFile and DrawFile
  90.     objects) must provide the following methods. All objects within
  91.     DrawFiles provide further classes as specifed in
  92.     `RISCOS::DrawFile::Object'.
  93.  
  94.     BBox_Calc
  95.         (re)calculates the bounding box, returning a reference to an
  96.         array, or undef if there is no bounding box. As it has no
  97.         idea about the data it contains `OpaqueObject' simply
  98.         returns the bounding box it was given when it was called.
  99.  
  100.     PrePack <hash_reference>
  101.         a hook to perform calculations immediately before saving a
  102.         DrawFile. The hash reference is used to store the names of
  103.         fonts needed in the FontTable, keys are font names, values
  104.         the number of text objects that use that font (see `PrePack'
  105.         in `RISCOS::DrawFile::Text' if you really must know).
  106.  
  107.     Pack <undef>, fonttable, ...
  108.         returns a scalar containing the object packed ready to save
  109.         into a DrawFile.
  110.  
  111.     Write <filehandle>, <fonttable>, ...
  112.         writes the object to the given filehandle. `Write' should
  113.         return true unless there was an error.
  114.  
  115.  
  116. BUGS
  117.     Not tested enough.
  118.  
  119. AUTHOR
  120.     Nicholas Clark <nick@unfortu.net>
  121.  
  122.