home *** CD-ROM | disk | FTP | other *** search
/ Acorn User 10 / AU_CD10.iso / Updates / Perl / Non-RPC / Docs / RISCOS-Library-Docs / Container.pm < prev    next >
Text File  |  1999-04-17  |  9KB  |  247 lines
  1. NAME
  2.     RISCOS::DrawFile::Container
  3.  
  4. SYNOPSIS
  5.     Abstract base class for classes that hold other DrawFile
  6.     objects.
  7.  
  8. DESCRIPTION
  9.     `RISCOS::DrawFile::Container' provides an abstract base class
  10.     for classes that hold other DrawFile objects (groups, tagged
  11.     objects and DrawFiles themselves. `RISCOS::DrawFile::Container'
  12.     itself is not a `RISCOS::DrawFile::Object', as not all classes
  13.     which derive from it are objects found in DrawFiles.
  14.  
  15.   Methods
  16.  
  17.     new <contents>
  18.         creates a new object. If *contents* is an array reference it
  19.         is dereferenced. The array of objects (if any) is used as
  20.         the container's contents.
  21.  
  22.     Stuff [<new_contents>]
  23.         returns a reference to the array of contents. If
  24.         *new_contents* are given, then these replace the existing
  25.         contents (and the old contents are returned). If
  26.         *new_contents* is an array reference it is automatically
  27.         dereferenced first.
  28.  
  29.     MoreStuff [<additional_contents>]
  30.         adds *new_contents* existing contents, returning a reference
  31.         to the array of contents. If *additional_contents* is an
  32.         array reference it is automatically dereferenced first.
  33.  
  34.     Do <what>, arguments...
  35.         recursively does something to all contained objects.
  36.  
  37.         For each contained item:
  38.  
  39.     *       If it has a `Do' method, calls it with the arguments passed
  40.             to this method.
  41.  
  42.     *       If <what> is a code reference, calls it as
  43.  
  44.                 &what (object, arguments...)
  45.  
  46.  
  47.             else looks for a method *what* in the object, and if
  48.             found calls that method with the arguments given
  49.  
  50.  
  51.         `Do' returns the list of all results returned from all
  52.         called subroutines.
  53.  
  54.         This method is extremely powerful. For example, to set all
  55.         line widths to thin in the object `$draw'
  56.  
  57.             $draw->Do('Width', 0);
  58.  
  59.  
  60.         To change all occurrences of the font 'Homerton.Medium' to
  61.         'AvantG.Book' in all text objects you could do:
  62.  
  63.             $draw->Do(sub {$_[0]->Font ('AvantG.Book')
  64.                      if $_[0]->can('Font')
  65.                     and $_[0]->Font() eq 'Homerton.Medium'});
  66.  
  67.  
  68.         (note that if you pass code you need to check that the
  69.         method exists with `can' before you try to call it) but
  70.         you'd be much better off with
  71.  
  72.             $draw->ChangeString('Font','Homerton.Medium','AvantG.Book');
  73.  
  74.  
  75.         (see below)
  76.  
  77.     DoToAll <what>, arguments...
  78.         is like `Do' except that it also calls the named method or
  79.         code reference on contained containers, unlike `Do' which
  80.         only calls it on objects which do not possess their own `Do'
  81.         to recurse to. Unless you want to alter contained Groups or
  82.         Tag objects in some way, you probably don't want to call
  83.         `DoToAll' as it will return an possibly unhelpful list of
  84.         results - for example if the result array is all objects
  85.         inside a bounding box you may get objects within groups
  86.         multiple times; once when the check is performed on the
  87.         object itself, and again within each group that also meets
  88.         the test condition.
  89.  
  90.     Replace <what>, arguments...
  91.         is like `Do' except it *replaces* the contents of each
  92.         container with the return values of *what*, so *what* had
  93.         better be returning DrawFile objects. If a container
  94.         contains at least one object afterwards it returns a
  95.         reference to itself, whereas an empty container returns
  96.         `undef'. Beware that this way a container (*e.g.* an entire
  97.         DrawFile) can end up deleting itself, so do check the return
  98.         value, before your script crashes when attempting to call a
  99.         method on a now undefined scalar.
  100.  
  101.     Change <method_name>, <test_value> arguments...
  102.         is similar to `Do', but can only take a named method. The
  103.         method is called with no arguments in scalar context, and if
  104.         the result is *numerically* equal (`==') to *test_value* the
  105.         method is called again with the arguments supplied.
  106.  
  107.         So to change all 4 point lines to 6
  108.  
  109.             $draw->Change('Width', 2560, 3840);
  110.  
  111.  
  112.         (without having to ungroup or regroup anything...)
  113.  
  114.     ChangeString <method_name>, <test_value> arguments...
  115.         is identical to `Change' except that the comparison is for a
  116.         string (`eq').
  117.  
  118.             $draw->ChangeString('Font','Homerton.Medium','AvantG.Book');
  119.  
  120.  
  121.     BBox
  122.         returns a reference to an array giving the bounding box, or
  123.         `undef' if there is no bounding box for this object (*e.g.*
  124.         an empty group, a tagged empty path). `BBox' will call
  125.         `BBox_Calc' if the bounding box is currently unknown.
  126.  
  127.         As the returned array reference is the internal copy of the
  128.         bounding box it must not be modified.
  129.  
  130.     BBox_Calc
  131.         recalculates and returns the bounding box, by calling
  132.         `BBox_Calc' for each contained object and merging the
  133.         bounding boxes. `BBox_Calc' will return `undef' if no
  134.         contained object returned a valid bounding box. (This is far
  135.         more elegant than returning (int_max, int_max, int_min,
  136.         int_min), as is the wont of `Draw_ProcessPath' when
  137.         presented with an empty path - yes, we're trapping this one,
  138.         and `Font_ScanString' when given an empty string).
  139.  
  140.     PrePack <hash_reference>
  141.         is provided as a hook to perform calculations immediately
  142.         before saving a DrawFile. The hash reference is used to
  143.         store the names of fonts needed in the FontTable by
  144.         `RISCOS::DrawFile::Text' objects. `PrePack' calls `PrePack'
  145.         for each contained object, and merges the bounding boxes.
  146.  
  147.     Size
  148.         returns the size of the object when saved in a DrawFile, by
  149.         summing the results of calling `Size' on the contents.
  150.  
  151.     Pack <undef>, fonttable, ...
  152.         returns a scalar containing the object packed ready to save
  153.         into a DrawFile, by concatenating the results of calling
  154.         `Pack' on the contents.
  155.  
  156.     Write <filehandle>, <fonttable>, ...
  157.         writes the object to the given filehandle. The default
  158.         implementation calls `Write' with the remainder of the
  159.         argument list for each item in the contents, returning false
  160.         if any call to `Write' did not return true.
  161.  
  162.     Second_Font_Table
  163.         prints a warning that a second font table has been found,
  164.         and returns an empty list. Mostly of use to the DrawFile
  165.         class.
  166.  
  167.     Objfunc
  168.         returns a reference to a hash of code references, keyed by
  169.         object type. This hash determines the correct object
  170.         constructor to call when the DrawFile data is split into
  171.         objects. Mostly of use to the DrawFile class.
  172.  
  173.     Unknown_Obj
  174.         prints a warning that an unknown object type has been found,
  175.         and returns the result of calling
  176.         `RISCOS::DrawFile::OpaqueObject'. Mostly of use to the
  177.         DrawFile class.
  178.  
  179.     _split_drawobjs <data>, <split>, <fonttable>, <sub_constructors>, <duplicate_fonttable>, <unknown_object>
  180.         splits the data passed as a scalar reference into a list of
  181.         DrawFile objects. *split* is a split function as described
  182.         in `new' in `RISCOS::DrawFile::Object'. *fonttable* is
  183.         initially `undef', but for recursive calls is replaced with
  184.         the fonttable object once found. *sub_constructors* is a
  185.         hash or array reference used to find code to construct
  186.         objects keyed by type. Usually this is supplied by calling
  187.         `Objfunc', but a custom hash/array can be used.
  188.         *duplicate_fonttable* is called as a constructor when a
  189.         second fonttable is found. Usually this is a reference to
  190.         `&Second_Font_Table'. *unknown_object* is called as a
  191.         constructor for any object type not found in
  192.         *sub_constructors*. Usually this is a reference to
  193.         *&Unknown_Obj*.
  194.  
  195.         `_split_drawobjs' returns a list ([objects], undef,
  196.         fonttable) as for a DrawFile object constructor.
  197.  
  198.         This method is used by groups and DrawFile objects to split
  199.         their contents into objects. It probably isn't needed by
  200.         anyone else.
  201.  
  202.     Do <what>, arguments...
  203.         recursively does something to all contained objects.
  204.  
  205.         For each contained item:
  206.  
  207.     *       If it has a `Do' method, calls it with the arguments passed
  208.             to this method.
  209.  
  210.     *       If <what> is a code reference, calls it as
  211.  
  212.                 &what (I<object>, I<arguments...>
  213.  
  214.  
  215.             else looks for a method *what* in the object, and if
  216.             found calls that method with the arguments given
  217.  
  218.  
  219.         `Do' returns the list of all results returned from all
  220.         called subroutines.
  221.  
  222.         This method is extremely powerful. For example, to set all
  223.         line widths to thin in the object `$draw'
  224.  
  225.             $draw->Do('Width', 0);
  226.  
  227.  
  228.         To change all occurrences of the font 'Homerton.Medium' to
  229.         'AvantG.Book' in all text objects:
  230.  
  231.             $draw->Do(sub {$_[0]->Font ('AvantG.Book')
  232.                      if $_[0]->can('Font')
  233.                     and $_[0]->Font() eq 'Homerton.Medium'});
  234.  
  235.  
  236.         (note that if you pass code you need to check that the
  237.         method exists with `can' before you try to call it)
  238.  
  239.  
  240. BUGS
  241.     Currently doesn't allow derived classes to limit the number of
  242.     objects that they can hold. (`TagObject's only hold one object)
  243.  
  244. AUTHOR
  245.     Nicholas Clark <nick@unfortu.net>
  246.  
  247.