home *** CD-ROM | disk | FTP | other *** search
/ Acorn User 10 / AU_CD10.iso / Updates / Perl / Non-RPC / !Perl / riscos / RISCOS / DrawFile / Common.pm next >
Text File  |  1999-01-20  |  7KB  |  221 lines
  1. package RISCOS::DrawFile::Common;
  2.  
  3. use RISCOS::BBox qw(inside inside_or_touching intersect intersect_or_touching
  4.             outside);
  5. use RISCOS::Clone (Clone);
  6.  
  7. use strict;
  8. use vars qw ($VERSION @ISA @EXPORT_OK);
  9. use Carp;
  10.  
  11. $VERSION = 0.03;
  12. # 0.03 adds Translate
  13.  
  14. @ISA = 'Exporter';
  15. @EXPORT_OK = 'drawplus_split_type';
  16.  
  17. ### use SelfLoader;
  18. sub RISCOS::DrawFile::Common::drawplus_split_type ($);
  19. sub RISCOS::DrawFile::Common::BBox ;
  20. sub RISCOS::DrawFile::Common::Translate ($$$$);
  21. sub RISCOS::DrawFile::Common::Inside ($$);
  22. sub RISCOS::DrawFile::Common::InsideOrTouching ($$);
  23. sub RISCOS::DrawFile::Common::Intersect ($$);
  24. sub RISCOS::DrawFile::Common::IntersectOrTouching ($$);
  25. sub RISCOS::DrawFile::Common::Outside ($$);
  26. 1;
  27. ### __DATA__
  28. sub drawplus_split_type ($) {
  29.     return $_[0] & 0xFF unless wantarray;
  30.     unpack 'C4', pack 'I', $_[0];
  31. }
  32.  
  33. sub BBox {
  34.     my $self = shift;
  35.     defined $self->{'__BBOX'} ? $self->{'__BBOX'} : $self->BBox_Calc;
  36. }
  37.  
  38. sub Translate ($$$$) {
  39.     if (ref ($_[3]) eq 'CODE') {
  40.     &{$_[3]}($_[0], $_[1], $_[2]);
  41.     } elsif (not defined $_[3]) {
  42.     warn "Cannot translate $_[0] by ($_[1], $_[2])\n";
  43.     } elsif ($_[3] eq '') {
  44.     my $self = $_[0];
  45.     my $bbox = defined $self->{'__BBOX'} ? $self->{'__BBOX'}
  46.                          : $self->BBox_Calc;
  47.     if (defined $bbox) {
  48.         $$bbox[0] += $_[1];
  49.         $$bbox[1] += $_[2];
  50.         $$bbox[2] += $_[1];
  51.         $$bbox[3] += $_[2];
  52.     } else {
  53.         warn "Cannot translate $_[0] by ($_[1], $_[2])\n";
  54.     }
  55.     } else {
  56.     confess "Illegal third argument to translate ('$_[3]') when attempting to translate $_[0] by ($_[1], $_[2])";
  57.     }
  58.     ();
  59. }
  60.  
  61. sub Inside ($$) {
  62.     my $bbox = $_[0]->BBox();
  63.     ($bbox and inside $_[1], $bbox) ? $_[0] : ();
  64.     # Return ourself if we have a defined bbox, and if it is inside the supplied
  65.     # box
  66.     # Otherwise, if I've understood things correctly empty list () should be
  67.     # converted to undef in scalar context, and used correctly in list context
  68.     # Using undef will add (undef) to any list which is being accumulated from
  69.     # our return result.
  70. }
  71.  
  72. sub InsideOrTouching ($$) {
  73.     my $bbox = $_[0]->BBox();
  74.     ($bbox and inside_or_touching $_[1], $bbox) ? $_[0] : ();
  75. }
  76.  
  77. sub Intersect ($$) {
  78.     my $bbox = $_[0]->BBox();
  79.     ($bbox and intersect $_[1], $bbox) ? $_[0] : ();
  80. }
  81.  
  82. sub IntersectOrTouching ($$) {
  83.     my $bbox = $_[0]->BBox();
  84.     ($bbox and intersect_or_touching $_[1], $bbox) ? $_[0] : ();
  85. }
  86.  
  87. sub Outside ($$) {
  88.     my $bbox = $_[0]->BBox();
  89.     ($bbox and outside $_[1], $bbox) ? $_[0] : ();
  90. }
  91.  
  92. 1;
  93. __END__
  94.  
  95. =head1 NAME
  96.  
  97. RISCOS::DrawFile::Common
  98.  
  99. =head1 SYNOPSIS
  100.  
  101. Methods common to DrawFiles and objects within DrawFiles.
  102.  
  103. =head1 DESCRIPTION
  104.  
  105. C<RISCOS::DrawFile::Common> provides methods common to DrawFiles and to objects
  106. within DrawFiles. It provides one function C<drawplus_split_type>.
  107.  
  108. =head2 drawplus_split_type
  109.  
  110.     $type = drawplus_split_type 0x00010402;        # $type = 0x02
  111.     ($type, $layer, $flags, $spare) = drawplus_split_type $type;
  112.  
  113. C<drawplus_split_type> takes an integer and interprets it as a DrawPlus
  114. "extended tag". In scalar context it returns the standard draw type, in array
  115. context the list (type, layer, flags, spare), as described in the DrawPlus
  116. documentation.
  117.  
  118. =head2 Methods
  119.  
  120. =over 4
  121.  
  122. =item Clone
  123.  
  124. returns a copy of this object. Derived class implementors should see
  125. L<RISCOS::Clone> for the cloning teqnique, and the B<assumptions> it makes.
  126.  
  127. =item BBox
  128.  
  129. returns a reference to an array giving the bounding box, or C<undef> if there is
  130. is no bounding box for this object (I<i.e.> font tables, empty paths, option
  131. objects). Note that option objects and empty paths store a bounding box of
  132. (0,0,0,0) when saved. C<BBox> will attempt to call C<BBox_Calc> (which the
  133. derived class B<must> provide) if the bounding box is currently unknown.
  134.  
  135. As the returned array reference B<is> the internal copy of the bounding box it
  136. must not be modified.
  137.  
  138. =item Translate <x> <y> [<barf_func>]
  139.  
  140. translates the object by (I<x>, I<y>), or calls
  141. &I<barf_func> (I<object>, I<x>,  I<y>) for any object for which translation is
  142. not possible (I<i.e.> unknown objects and tagged objects, as the tag data might
  143. contain co-ordinate information. If I<barf_func> is undefined a warning is
  144. issued, while an empty string silences any warning, and assumes that altering
  145. the bounding box of any unknown object is sufficient to perform the translation.
  146.  
  147. =item Inside <bbox>
  148.  
  149. checks whether this object is entirely within the bounding box (passed as an
  150. array reference). Returns a reference to the object if it is, an empty list if
  151. it touches, intersects or lies outside the box. The empty list C<()> is
  152. converted to C<undef> in scalar context, whereas returning C<undef> in list
  153. context would generate a one element list C<(undef>) which can cause surprises.
  154.  
  155. =item InsideOrTouching <bbox>
  156.  
  157. checks whether this object is entirely within or touching the bounding box
  158. (passed as an array reference). Returns a reference to the object if it is,
  159. C<()> if it intersects or lies outside the box.
  160.  
  161. =item Intersect <bbox>
  162.  
  163. checks whether any of this object's bounding box is within the bounding box
  164. (passed as an array reference). Returns a reference to the object if it is,
  165. C<()> if it lies outside the box (including just touching the edge).
  166.  
  167. =item IntersectOrTouching <bbox>
  168.  
  169. checks whether any of this object's bounding box is within the bounding box, or
  170. is touching the box (passed as an array reference). Returns a reference to the
  171. object if it is, C<()> if it lies outside and is not touching the box.
  172.  
  173. =item Outside <bbox>
  174.  
  175. checks whether this object's bounding box is entirely outside the bounding box
  176. (passed as an array reference). Returns a reference to the object if it is,
  177. C<()> if any part of the bounding box touches or intersects the box.
  178.  
  179. =back
  180.  
  181. =head2 Methods derived classes must supply
  182.  
  183. In addition to the overriding above methods where appropriate (in particular
  184. C<Type>) derived classes (DrawFile and DrawFile objects) must provide the
  185. following methods. All objects within DrawFiles provide further classes as
  186. specifed in C<RISCOS::DrawFile::Object>.
  187.  
  188. =over 4
  189.  
  190. =item BBox_Calc
  191.  
  192. (re)calculates the bounding box, returning a reference to an array, or undef if
  193. there is no bounding box. As it has no idea about the data it contains
  194. C<OpaqueObject> simply returns the bounding box it was given when it was called.
  195.  
  196. =item PrePack <hash_reference>
  197.  
  198. a hook to perform calculations immediately before saving a DrawFile. The hash
  199. reference is used to store the names of fonts needed in the FontTable, keys are
  200. font names, values the number of text objects that use that font (see C<PrePack>
  201. in C<RISCOS::DrawFile::Text> if you really must know).
  202.  
  203. =item Pack <undef>, fonttable, ...
  204.  
  205. returns a scalar containing the object packed ready to save into a DrawFile.
  206.  
  207. =item Write <filehandle>, <fonttable>, ...
  208.  
  209. writes the object to the given filehandle. C<Write> should return true unless
  210. there was an error.
  211.  
  212. =back
  213.  
  214. =head1 BUGS
  215.  
  216. Not tested enough.
  217.  
  218. =head1 AUTHOR
  219.  
  220. Nicholas Clark <F<nick@unfortu.net>>
  221.