home *** CD-ROM | disk | FTP | other *** search
/ Acorn User 10 / AU_CD10.iso / Updates / Perl / Non-RPC / Docs / RISCOS-Library-Docs / Draw.pm < prev    next >
Text File  |  1999-04-17  |  7KB  |  187 lines
  1. NAME
  2.     RISCOS::Draw -- perl interface to the Draw module
  3.  
  4. SYNOPSIS
  5.         use RISCOS::Draw qw(what split_path_block path_bbox);
  6.         # Convert join name to number, default to bevelled
  7.         $join = what ('join', 'bevelled', $join);
  8.         # Split scalar containing path into array of path elements
  9.         @path = split_path_block $block;
  10.         $bbox = path_bbox $block, $width;
  11.  
  12.  
  13. DESCRIPTION
  14.     `RISCOS::Draw' provides an interface to the Draw module, which
  15.     provides "an implementation of PostScript type drawing". At
  16.     present only functions necessary to calculate path bounding
  17.     boxes have been implemented, principally for use by the DrawFile
  18.     Path object.
  19.  
  20.   Subroutines
  21.  
  22.     what <type> <default> <values...>
  23.         `what' converts names of options into the appropriate
  24.         numeric constants. Arguments passed as numbers are faulted
  25.         if they do not correspond to a named option. *type* can
  26.         either be a reference to a typeglob (which supplies a hash
  27.         to convert from name to number and an array from number to
  28.         name) or a string to use lookup tables provided by this
  29.         package. `RISCOS::Draw' provides these tables:
  30.  
  31.             non-zero        0
  32.             negative        1
  33.             even-odd        2
  34.             positive        3
  35.  
  36.             non-boundary exterior    4
  37.             boundary exterior    8
  38.             boundary interior    16
  39.             non-boundary interior    32
  40.  
  41.             butt            0
  42.             round            1
  43.             square            2
  44.             triangle        3
  45.  
  46.             mitred            0
  47.             round            1
  48.             bevelled        2
  49.  
  50.             end            0
  51.             continue        1
  52.             move            2
  53.             move_same_wind        3
  54.             close_gap        4
  55.             close            5
  56.             bezier            6
  57.             gap_same_sub        7
  58.             line            8
  59.  
  60.  
  61.         *default* is a default value (string or text) to use for any
  62.         undefined values passed as arguments. Numeric defaults are
  63.         deliberately not checked for validity. In array context
  64.         `what' returns an array corresponding to the converted
  65.         arguments. In scalar context `what' returns only the first
  66.         value.
  67.  
  68.     unwhat <type> <default> <values...>
  69.         `unwhat' provides the reverse conversion to `what',
  70.         converting numeric values to text. Any undefined values are
  71.         converted to the (unchecked) supplied default.In scalar
  72.         context it returns the first conversion only, in array
  73.         context a list of conversions.
  74.  
  75.     split_dash_block <block>
  76.         Splits a dash block into an array of integers, which should
  77.         be regarded as a single value followed by a list. The first
  78.         value is the offset of the start of the dash pattern in the
  79.         list. The list itself gives the length of dash segments in
  80.         user units.
  81.  
  82.     pack_dash_block <packed_block>
  83.  
  84.     pack_dash_block <array_ref>
  85.  
  86.     pack_dash_block <start> <array_ref>
  87.         Packs an array of integers into a block to pass to `Draw'
  88.         SWIs or to store in a DrawFile. If a single array reference
  89.         is passed it is assumed to point to an array `($start,
  90.         @lengths)' (which is passed to shift). If two arguments are
  91.         passed the first is taken to be the start index, the second
  92.         a reference to an array of dash lengths. If a single scalar
  93.         is passed it is assumed to be already packed and is returned
  94.         verbatim.
  95.  
  96.     split_path_block <path_block>
  97.         splits the scalar containing a series of `Draw' path
  98.         elements into an array, with each element containing the a
  99.         single move, line or curve. Concatenating the array with
  100.         `join ''' will give the original scalar, except that the
  101.         terminating end-of-path marker `"\0\0\0\0"' (and any
  102.         trailing garbage) will be absent. If passed a reference to
  103.         an array, then this array (or a reference to it) is
  104.         returned.
  105.  
  106.         In array context returns this array, in scalar context
  107.         returns a reference to it.
  108.  
  109.     pack_path_block <reference>
  110.  
  111.     pack_path_block path elements...
  112.         packs the path block supplied. In scalar context returns the
  113.         path block, in array context returns the path block as if
  114.         split by `split_path_block'.
  115.  
  116.         If the first argument is scalar reference it is assumed to
  117.         point to an already packed path block and `split_path_block'
  118.         is called if necessary.
  119.  
  120.         If the first argument is an array reference, it is
  121.         dereferenced and replaces the argument list, else the
  122.         supplied argument list is processed.
  123.  
  124.         For each entry in turn, if it is an array reference it is
  125.         assumed to point to an array of integer values to be used as
  126.         path/move type and co-ordinates, which are `pack'ed with the
  127.         template `'I*'' and added to the output array. Otherwise the
  128.         entry is assumed to be already packed and added to the
  129.         output array verbatim.
  130.  
  131.         A final `"\0\0\0\0"' is added to the output list if
  132.         necessary.
  133.  
  134.         In array context the output array is returned, in scalar
  135.         context it is concatenated with `join '''.
  136.  
  137.     path_bbox <path> [<winding> <plot_type> <thickness> <join> <start_cap> <end_cap> <dash> <flatness> <transform>
  138.         calculates the bounding box of *path*, returning a reference
  139.         to an array in scalar context, or the array itself in array
  140.         context. `undef' or an empty list are returned if an error
  141.         occurs (including supplying an empty path). All arguments
  142.         except *path* are optional, and will default to sane values
  143.         if not supplied.
  144.  
  145.         *path* is either a scalar if it is already packed as a
  146.         block, or a reference to be passed to `pack_path_block'.
  147.  
  148.         *winding* defaults to 0 (non-zero), and is one of the four
  149.         values in the `Draw' winding table (distinct from the two
  150.         used by `DrawFile').
  151.  
  152.         *plot* is the plot type to pass to the SWI, and defaults to
  153.         'boundary'.
  154.  
  155.         *thickness* is the line thickness in user units, which
  156.         defaults to 0 (thin)
  157.  
  158.         *join* is either a scalar to lookup in the join table
  159.         (default bevelled, mitre limit defaults to 10), or a scalar
  160.         reference to select mitred joins with this as the mitre
  161.         limit.
  162.  
  163.         *start_cap* and *end_cap* are each either scalars to lookup
  164.         in the cap table (default butt, triangle is width × 1,
  165.         length × 2) or an array ref to select triangle caps with
  166.         `[width, length]'.
  167.  
  168.         *dash* is either a scalar to be used verbatim as the dash
  169.         block, or an array reference of the form `[$Offset,
  170.         @Values]' to pass to `pack_dash_block'. The default is
  171.         continuous lines.
  172.  
  173.         *flatness* defaults to 0, which is normally appropriate
  174.  
  175.         *transform* is a reference to the transformation matrix to
  176.         use, defaulting to none
  177.  
  178.  
  179. BUGS
  180.     Definitely not tested enough yet. Some bits not tested at all, I
  181.     believe. Bounding box calculations and sufficient
  182.     packing/unpacking to manipulate DrawFiles does work.
  183.  
  184. AUTHOR
  185.     Nicholas Clark <nick@unfortu.net>
  186.  
  187.