mapscript.txt

..  $Id$
    
    This is the new unified mapscript documentation prepared using
    reStructured Text.

    ***************************************************************
    RULE #1: No tabs in this document!
    RULE #2: Indent is 4 characters.
    RULE #3: There is no rule 3.

    Thank you.
    ***************************************************************
    
    reStructured Text is part of the Python docutils module
    
        http://docutils.sourceforge.net/
    
    Documentation on reStructured Text is found at

        http://docutils.sourceforge.net/rst.html

    First reST note is about comments: a double period begins a comment
    block (like a /* in C) and a double period on a line all by itself
    closes the comment block.
..

..  Below is our main heading (becomes H1).  Note that we require empty
    lines between every different reST element such as the empty line
    between the end of this comment and the begining of the heading.
..

*****************************************************************************
 Mapscript Development Documentation
*****************************************************************************

:Author: Sean Gillies
:Contact: sgillies@frii.com
:Revision: $Revision$
:Date: $Date$

..  The next heading encountered becomes our H2
..

=============================================================================
 Introduction
=============================================================================

This is language agnostic documentation for the mapscript interface to 
MapServer generated by SWIG.  This document is intended for developers
and to serve as a reference for writers of more extensive, language
specific documentation in DocBook format for the MDP.

-----------------------------------------------------------------------------
 Appendices
-----------------------------------------------------------------------------

Language-specific extensions are described in the following appendices

Python Appendix [`Text <python.txt>`__, `HTML <python.html>`__] 

-----------------------------------------------------------------------------
 Documentation Elements
-----------------------------------------------------------------------------

Classes will be documented in alphabetical order in the manner outlined below.
Attributes and methods will be formatted as definition lists with the
attribute or method as item, the type or return type as classifier, and a
concise description. To make the document as agnostic as possible, we refer to
the following types: int, float, and string.  There are yet no mapscript
methods that return arrays or sequences or accept array or sequence arguments.

We will use the SWIG term *immutable* to indicate that an attribute's value
is read-only.

------
fooObj
------

A paragraph or two about class fooObj.

Attributes
----------

attribute : type [access]
    Concise description of the attribute.

Attribute name are completely lower case.  Multiple words are
packed together like *outlinecolor*.

Note that because of the way that mapscript is generated many confusing,
meaningless, and even dangerous attributes are creeping into objects.  See
outputFormatObj.refcount for example.  Until we get a grip on the structure
members we are exposing to SWIG this problem will continue to grow.

Methods
-------

method(type mandatory_parameter [, type optional_parameter=default]) : type
    Description of the method including elaboration on the method
    arguments, the method's actions, and returned values.  Optional
    parameters and their default values are enclosed in brackets.

Class method names are camel case with a leading lower case character
like *getExpressionString*.


Next Generation Classes
-----------------------

By defining the preprocessor symbol *NEXT_GENERATION_API* when running
SWIG to produce wrapper code, one can use the 'next generation' mapscript
API.  For example

::

    swig -python -shadow -modern -DNEXT_GENERATION_API -o mapscript_wrap.c ../mapscript.i

The API changes in the next generation classes result
from efforts to merge the best of the PHP-Mapscript and SWIG mapscript
interfaces (Bugzilla issue 575 - 
http://mapserver.gis.umn.edu/bugs/show_bug.cgi?id=575).  As an example, see
the documentation of `layerObj.getShape`_.

Additionally, programmers can experiment with better mapscript class naming
by defining the symbol *NEXT_GENERATION_NAMES*.  

::

    swig -python -shadow -modern -DNEXT_GENERATION_NAMES -DNEXT_GENERATION_API -o mapscript_wrap.c ../mapscript.i

The next generation class names are in capitalized camel case form: *Map*,
*Layer*, *OutputFormat*, and so on rather than the standard *--Obj*
names which are not clearly distinguished from
class method names.  We're all using object-oriented languages, so the *Obj*
suffix is redundant.  It is also a cross-language convention (see CPAN and
the Python standard library) that package and class names be capitalized.
Forming class names in a way distinctly different from class attributes and
methods improves API clarity.

The features enabled by *NEXT_GENERATION_API* will almost certainly become
standard in a future release.  The next generation class names are more
controversial and more likely to remain an option for users.  Python users
want them, and can easily port existing code to use the new names.  For 
example:

::

    import mapscript
    
    # Rename the next generation classes for use with older code
    mapscript.mapObj = mapscript.Map

    # Continue with older code
    mapobj = mapscript.mapObj('foo.map')
    ...


Now that the style of the documentation has been introduced, on to the
classes themselves.

=============================================================================
 Mapscript Classes
=============================================================================

References to sections below will be added here as the documentation grows.

classObj_, colorObj_, imageObj_, labelObj_, outputFormatObj_, pointObj_,
rectObj_, shapeObj_, styleObj_

-----------------------------------------------------------------------------
 classObj
-----------------------------------------------------------------------------

An instance of classObj is associated with with one instance of layerObj_.

::

    +-------+ 0..*     1 +-------+
    | Class | <--------> | Layer |
    +-------+            +-------+

The other important associations for classObj are with styleObj_ and
labelObj_.

::

    +-------+ 1     0..* +-------+
    | Class | ---------> | Style |
    +-------+            +-------+

    +-------+ 1     0..1 +-------+
    | Class | ---------> | Label |
    +-------+            +-------+

Multiple class styles are now supported in 4.1.  See the styleObj_ section
for details on use of multiple class styles.

Attributes
----------

debug : int
    MS_TRUE or MS_FALSE

keyimage : string
    **TODO** Not sure what this attribute is for

label : labelObj_
    Definition of class labeling

layer : layerObj_ immutable
    Reference to the parent layer

maxscale : float
    The maximum scale at which class is drawn
    
minscale : float
    The minimum scale at which class is drawn

name : string
    Unique within a layer

numstyles : int immutable
    Number of styles for class
    
status : int
    MS_ON or MS_OFF.  Draw features of this class or do not.
    
template : string
    Template for queries

title : string
    Text used for legend labeling

type : int
    The layer type of its parent layer

Methods
-------

.. _new classObj:

new classObj(layerObj_ layer) : classObj_
    Create a new child classObj instance at the tail (highest index) of 
    the class array of the parent *layer*.

.. _createLegendIcon:
 
createLegendIcon(mapObj_ map, layerObj_ layer, int width, int height) : imageObj_
    Draw and return a new legend icon.

.. _drawLegendIcon:

drawLegendIcon(mapObj_ map, layerObj_ layer, int width, int height, imageObj_ dstImage, int dstX, int dstY) : int
    Draw the legend icon onto *dstImage* object at dstX, dstY.  Returns 
    MS_SUCCESS or MS_FAILURE.

.. _getExpressionString:
  
getExpressionString() : string
    Return a string representation of the expression enclosed in the quote
    characters appropriate to the expression type.

.. _classObj.getMetaData:

getMetaData(string key) : string
    Return the value of the classObj metadata at *key*.

.. _getStyle:

getStyle(int index) : styleObj_
    Return a reference to the styleObj at *index* in the styles array.

    See the styleObj_ section for more details on multiple class styles.

.. _insertStyle:

insertStyle(styleObj_ style [, int index=-1]) : int
    Insert a **copy** of *style* into the styles array at index *index*.
    Default is -1, or the end of the array.  Returns the index at which the 
    style was inserted.

.. _moveStyleDown:

moveStyleDown(int index) : int
    Swap the styleObj at *index* with the styleObj *index* + 1.
    
.. _moveStyleUp:

moveStyleUp(int index) : int
    Swap the styleObj at *index* with the styleObj *index* - 1.

.. _removeStyle:

removeStyle(int index) : styleObj_
    Remove the styleObj at *index* from the styles array and return a
    copy.

.. _setExpression:

setExpression(string expression) : int
    Set expression string where *expression* is a MapServer regular, logical
    or string expression.  Returns MS_SUCCESS or MS_FAILUIRE.
  
.. _classObj.setMetaData:

setMetaData(string key, string value) : int
    Insert *value* into the classObj metadata at *key*.  Returns MS_SUCCESS
    or MS_FAILURE.

-----------------------------------------------------------------------------
 colorObj
-----------------------------------------------------------------------------

Since the 4.0 release, MapServer colors are instances of colorObj.  A colorObj
may be a lone object or an attribute of other objects and have no other
associations.

Attributes
----------

blue : int
    Blue component of color in range [0-255]

green : int
    Green component of color in range [0-255]

red : int
    Red component of color in range [0-255]

Methods
-------

.. _`new colorObj`:

new colorObj([int red=0, int green=0, int blue=0]) : colorObj_ 
    Create a new instance.  The color arguments are optional.
    
.. _setRGB:

setRGB(int red, int green, int blue) : int 
    Set all three RGB components.  Returns MS_SUCCESS or MS_FAILURE.
    
.. _setHex:

setHex(string hexcolor) : int 
    Set the color to values specified in case-independent hexadecimal
    notation.  Calling setHex('#ffffff') assigns values of 255 to each
    color component.  Returns MS_SUCCESS or MS_FAILURE.
    
.. _toHex:

toHex() : string 
    Compliments setHex, returning a hexadecimal representation of the
    color components.
    
-----------------------------------------------------------------------------
 imageObj
-----------------------------------------------------------------------------

An image object is a wrapper for GD and GDAL images.

Attributes
----------

format : outputFormatObj_
    Image format.

height : int immutable
    Image height in pixels.
    
imagepath : string immutable
    If image is drawn by mapObj.draw(), this is the mapObj's web.imagepath.

imageurl : string immutable
    If image is drawn by mapObj.draw(), this is the mapObj's web.imageurl.

renderer : int 
    MS_RENDER_WITH_GD, MS_RENDER_WITH_SWF, MS_RENDER_WITH_RAWDATA,
    MS_RENDER_WITH_PDF, or MS_RENDER_WITH_IMAGEMAP

size : int
    I don't see where this is used.  Anyone?

width : int immutable
    Image width in pixels.


Methods
-------

.. _new imageObj:

new imageObj(int width, int height [, string driver=NULL [, string filename=NULL]]) : imageObj_
    Create new instance of imageObj.  If *filename* is specified, an imageObj
    is created from the file and any specified *width*, *height*, and
    *driver* parameters will be overridden by values of the image in 
    *filename*.  Otherwise, if *driver* is specified an imageObj is created
    using that driver.  See the *driver* attribute above for details.  If
    *filename* is not specified, then *width* and *height* should be specified.

.. _imageObj.save:

save(string filename [, mapObj parent_map=NULL]) : int
    Save image to *filename*.  The optional *parent_map* parameter must be
    specified if saving GeoTIFF images.


-----------------------------------------------------------------------------
 labelObj
-----------------------------------------------------------------------------

A labelObj is associated with a classObj, a scalebarObj, or a legendObj.

::

    +-------+ 0..1     1 +----------+
    | Label | <--------- | Class    |
    +-------+            | -------- |
                         | Scalebar |
                         | -------- |
                         | Legend   |
                         +----------+ 
                           
Attributes
----------

angle : float
    **TODO**

antialias : int
    MS_TRUE or MS_FALSE

autoangle : int
    MS_TRUE or MS_FALSE

autominfeaturesize: int
    MS_TRUE or MS_FALSE

backgroundcolor : colorObj_
    Color of background rectangle or billboard.

backgroundshadowcolor : colorObj_
    Color of background rectangle or billboard shadow.

backgroundshadowsizex : int
    Horizontal offset of drop shadow in pixels.

backgroundshadowsizey : int
    Vertical offset of drop shadow in pixels.

buffer : int
    Maybe this should've been named 'padding' since that's what it is:
    padding in pixels around a label.

color : colorObj_
    Foreground color.

font : string
    Name of TrueType font.

force : int
    MS_TRUE or MS_FALSE.

maxsize : int
    Maximum height in pixels for scaled labels.  See symbolscale attribute
    of layerObj_.

mindistance : int
    Minimum distance in pixels between duplicate labels.
    
minfeaturesize : int
    Features of this size of greater will be labeled.
    
minsize : int
    Minimum height in pixels.

offsetx : int
    Horizontal offset of label.

offsety : int
    Vertical offset of label.

outlinecolor : colorObj_
    Color of one point outline.

partials : int
    MS_TRUE (default) or MS_FALSE.  Whether or not labels can flow past
    the map edges.
    
postion : int
    MS_UL, MS_UC, MS_UR, MS_CL, MS_CC, MS_CR, MS_LL, MS_LC, MS_LR, or
    MS_AUTO.

shadowcolor : colorObj_
    Color of drop shadow.

shadowsizex : int
    Horizontal offset of drop shadow in pixels.

shadowsizey : int
    Vertical offset of drop shadow in pixels.

size : int
    Annotation height in pixels.

type : int
    MS_BITMAP or MS_TRUETYPE.

wrap : string
    Character on which legend text will be broken to make multi-line
    legends.
   
Methods
-------

None

-----------------------------------------------------------------------------
 layerObj
-----------------------------------------------------------------------------

A layerObj is associated with one mapObj and has no other existence [1]_.

::

    +-------+ 0..1     1 +-----+
    | Layer | <--------> | Map |
    +-------+            +-----+
   
The other important association for layerObj is with classObj

::

    +-------+ 1     0..1 +-------+
    | Layer | <--------> | Class |
    +-------+            +-------+


Methods
-------

**TODO**

.. _layerObj.getShape :

getShape(shapeObj_ shape, int tileindex, int shapeindex) : int
    Get a shape from layer data.
    
**NEXT_GENERATION_API** getShape(int shapeindex [, int tileindex=0]) : shapeObj_
    Get a shape from layer data using the next generation API.


-----------------------------------------------------------------------------
 legendObj
-----------------------------------------------------------------------------

x


-----------------------------------------------------------------------------
 lineObj
-----------------------------------------------------------------------------

A lineObj is composed of one or more pointObj_ instances.

::

    +------+ 0..1  1..* +-------+
    | Line | ---------> | Point |
    +------+            +-------+


-----------------------------------------------------------------------------
 mapObj
-----------------------------------------------------------------------------

A mapObj is primarily associated with instances of layerObj_.

::

     +-----+ 1     0..1 +-------+
     | Map | <--------> | Layer |
     +-----+            +-------+

Secondary associations are with legendObj_, scalebarObj_, referenceMapObj_,

::

     +-----+ 1     0..1 +----------+
     | Map | ---------> | Legend   |
     +-----+            | -------- |
                        | Scalebar |
                        | -------- |
                        | Legend   |
                        +----------+ 

and outputFormatObj_.

::

     +-----+ 1     1..* +--------------+
     | Map | ---------> | OutputFormat |
     +-----+            +------------- + 
                           

Attributes
----------

**TODO**

numoutputformats : int
    Number of output formats.

outputformat : outputFormatObj_
    The currently selected output format.

Methods
-------

**TODO**

appendOutputFormat(outputFormatObj_ format) : int
    Attach *format* to the map's output format list.  Returns the updated
    number of output formats.

getOutputFormat(string imagetype) : outputFormatObj_
    Return the output format corresponding to driver name *imagetype* or
    to format name *imagetype*.  This works exactly the same as the
    IMAGETYPE directive in a mapfile, is case insensitive and allows 
    an output format to be found either by driver (like 'GD/PNG') or
    name (like 'PNG24').

removeOutputFormat(string name) : int
    Removes the format named *name* from the map's output format list.
    Returns MS_SUCCESS or MS_FAILURE.


-----------------------------------------------------------------------------
 outputFormatObj
-----------------------------------------------------------------------------

An outputFormatObj is associated with a mapObj_ 

::

     +--------------+ 1..*     1 +-----+
     | OutputFormat | <--------- | Map |
     +--------------+            +-----+ 

and can also be an attribute of an imageObj_.

Attributes
----------

**TODO**

driver : string
    A string such as 'GD/PNG' or 'GDAL/GTiff'.

extension : string
    Format file extension such as 'png'.

imagemode : int
    MS_IMAGEMODE_PC256, MS_IMAGEMODE_RGB, MS_IMAGEMODE_RGBA, 
    MS_IMAGEMODE_INT16, MS_IMAGEMODE_FLOAT32, MS_IMAGEMODE_BYTE, or 
    MS_IMAGEMODE_NULL.
    
mimetype : string
    Format mimetype such as 'image/png'.
    
name : string
    A unique identifier.

renderer : int
    **TODO** what is renderer for?
   
transparent : int
    MS_ON or MS_OFF.

Methods
-------

.. _new outputFormatObj:

new outputFormatObj(string driver [, string name=driver]) : outputFormatObj_
    Create new instance.  If *name* is not provided, the value of *driver*
    is used as a name.
    
.. _getOption:

getOption(string key [, string value=""]) : string
    Return the option at *key* or *value* if *key* is not a valid
    hash index.

.. _setExtension:

setExtension(string extension) : void
    Set file extension for output format such as 'png' or 'jpg'.  Method 
    could probably be deprecated since the extension attribute is mutable.

setMimetype(string mimetype) : void
    Set mimetype for output format such as 'image/png' or 'image/jpeg'.
    Method could probably be deprecated since the mimetype attribute is
    mutable.
    
setOption(string key, string value) : void
    Set the option at *key* to *value*.
    

-----------------------------------------------------------------------------
 pointObj
-----------------------------------------------------------------------------

A pointObj instance may be associated with a lineObj_.

::

    +-------+ 1..*  0..1 +------+
    | Point | <--------- | Line |
    +-------+            +------+

Attributes
----------

m : float
    Measure.  Meaningful only for measured shapefiles.

x : float
    Easting
    
y : float
    Northing
    
Methods
-------

.. _new pointObj:

new pointObj([float x=0.0, float y=0.0]) : pointObj_
    Create new instance.  Easting and northing arguments are optional.

.. _distanceToPoint:

distanceToPoint(pointObj_ point) : float
    Returns the distance to *point*.
   
.. _distanceToSegment:

distanceToSegment(pointObj_ point1, pointObj_ point2) : float
    Returns the minimum distance to a hypothetical line segment connecting 
    *point1* and *point2*.
   
.. _distanceToShape:

distanceToShape(shapeObj_ shape) : float
    Returns the minimum distance to *shape*.

.. _pointObj.draw:

draw(mapObj_ map, layerObj_ layer, imageObj_ image, int classindex, string text) : int
    Draw the point using the styles defined by the *classindex* class of
    *layer* and labeled with string *text*.  Returns MS_SUCCESS or MS_FAILURE.

.. _pointObj.project:

project(projectionObj_ proj_in, projectionObj_ proj_out) : int
    Reproject point from *proj_in* to *proj_out*.  Transformation
    is done in place.  Returns MS_SUCCESS or MS_FAILURE.

------------------------------------------------------------------------------
 projectionObj
------------------------------------------------------------------------------

x

------------------------------------------------------------------------------
 rectObj
------------------------------------------------------------------------------

A rectObj may be a lone object or an attribute of another object and has no
other associations.
   
Attributes
----------

maxx : float
    Maximum easting
    
maxy : float
    Maximum northing

minx : float
    Minimum easting
    
miny : float
    Minimum northing
    
Methods
-------

.. _new rectObj:

new rectObj([float minx=0.0, float miny=0.0, float maxx=0.0, float maxy=0.0]) : rectObj_
    Create new instance.  The four easting and northing arguments
    are optional.

.. _rectObj.draw:

draw(mapObj_ map, layerObj_ layer, imageObj_ img, int classindex, string text) : int
    Draw rectangle into *img* using style defined by the *classindex* class
    of *layer*.  The rectangle is labeled with the string *text*.  Returns 
    MS_SUCCESS or MS_FAILURE.

.. _rectObj.project:

project(projectionObj_ proj_in, projectionObj_ proj_out) : int
    Reproject rectangle from *proj_in* to *proj_out*.  Transformation
    is done in place.  Returns MS_SUCCESS or MS_FAILURE.
    
.. _toPolygon:

toPolygon() : shapeObj_
    Convert to a polygon of five vertices.


-----------------------------------------------------------------------------
 referenceMapObj
-----------------------------------------------------------------------------

x


-----------------------------------------------------------------------------
 scalebarObj
-----------------------------------------------------------------------------

x


-----------------------------------------------------------------------------
 shapeObj
-----------------------------------------------------------------------------

Each feature of a layer's data is a shapeObj.  Each part of the shape is a
closed lineObj_.

::

    +-------+ 1    1..* +------+
    | Shape | --------> | Line |
    +-------+           +------+

Attributes
----------

bounds : rectObj_ immutable
    Bounding box of shape.
      
classindex : int
    The class index for features of a classified layer.
   
index : int immutable
    Feature index within the layer.

numlines : int immutable
    Number of parts.

numvalues : int immutable
    Number of shape attributes.

text : string
    Shape annotation.

tileindex : int immutable
    Index of tiled file for tileindexed layers.

type : int immutable
    MS_SHAPE_POINT, MS_SHAPE_LINE, MS_SHAPE_POLYGON, or MS_SHAPE_NULL.
 
values : p_p_char immutable
    This is a SWIG pointer to the underlying C array.  Users should access
    values through the getValue_ method.  
 
Methods
-------

.. _new shapeObj:

new shapeObj(int type) : shapeObj_
    Return a new shapeObj of the specified *type*.  See the type attribute
    above.

.. _shapeObj.add:

add(lineObj_ line) : int
    Add *line* (i.e. a part) to the shape.  Returns MS_SUCCESS or MS_FAILURE.

.. _contains:

contains(pointObj_ point) : int
    Returns MS_TRUE if the point is inside the shape, MS_FALSE otherwise.

copy(shapeObj_ shape_copy) : int
    Copy the shape to *shape_copy*.  Returns MS_SUCCESS or MS_FAILURE.

**NEXT_GENERATION_API** copy() : shapeObj_
    Return a copy of the shape.

distanceToPoint(pointObj_ point) : float
    Return distance to *point*.
    
distanceToShape(shapeObj_ shape) : float
    Return the minimum distance to *shape*.

.. _shapeObj.draw:

draw(mapObj_ map, layerObj_ layer, imageObj_ img) : int
    Draws the individual shape using layer.  Returns MS_SUCCESS or MS_FAILURE.

.. _shapeObj.get:

get(int index) : lineObj_
    Returns a reference to part at *index*.  Reference is valid
    only during the life of the shapeObj.

.. _getValue:

getValue(int i) : string
    Return the shape attribute at index *i*.

.. _shapeObj.intersects:

intersects(shapeObj_ shape) : int
    Returns MS_TRUE if the two shapes intersect, MS_FALSE otherwise.

.. _shapeObj.project:

project(projectionObj_ proj_in, projectionObj_ proj_out) : int
    Reproject shape from *proj_in* to *proj_out*.  Transformation
    is done in place.  Returns MS_SUCCESS or MS_FAILURE.

setBounds : void    
    Must be called to calculate new bounding box after new parts have been
    added.

    **TODO**: should return int and set msSetError.
    
-----------------------------------------------------------------------------
 styleObj
-----------------------------------------------------------------------------

An instance of styleObj is associated with one instance of classObj [2]_.

::

    +-------+ 0..*    1 +-------+
    | Style | <-------- | Class |
    +-------+           +-------+

Support for multiple class styles is a new feature in the current unstable
(4.1) Mapscript and in the next stable (4.2) release.  The initial feature
request and notes are archived at 
http://mapserver.gis.umn.edu/bugs/show_bug.cgi?id=548.

An instance of styleObj can exist outside of a classObj container and
needs to be explicitly inserted into the classObj for use in mapping.

::

    styleobj = new styleObj()
    classobj.insertStyle(styleobj)
    
It is important to understand that insertStyle_ inserts a **copy** of the
styleObj instance, not a reference to the instance itself.

Attributes
----------

backgroundcolor : colorObj_
    Background pen color.

color : colorObj_
    Foreground or fill pen color.

minsize : int
    Minimum pen or symbol width for scaling styles.
    
maxsize : int
    Maximum pen or symbol width for scaling.
    
offsetx : int
    Draw with pen or symbol offset from map data.
    
offsety : int
    Draw with pen or symbol offset from map data.
    
outlinecolor : colorObj_
    Outline pen color.

size : int
    Pixel width of the style's pen or symbol.

symbol : int
    The index within the map symbolset of the style's symbol.
    
symbolname : string immutable
    Name of the style's symbol.


Methods
-------

.. _new styleObj:

new styleObj() : styleObj_
    Returns new default style Obj instance.


-----------------------------------------------------------------------------
 symbolObj
-----------------------------------------------------------------------------

A symbolObj is associated with one symbolSetObj_.

::

    +--------+ 0..*    1 +-----------+
    | Symbol | <-------- | SymbolSet |
    +--------+           +-----------+

A styleObj_ will often refer to a symbolObj by name or index, but this is
not really an object association, is it?

Methods
-------

**TODO**

new symbolObj(string name) : symbolObj_
    Create new default symbol named *name*.


-----------------------------------------------------------------------------
 symbolSetObj
-----------------------------------------------------------------------------

A symbolSetObj is an attribute of a mapObj_ and is associated with instances
of symbolObj_.

::

    +-----------+ 1    0..* +--------+
    | SymbolSet | --------> | Symbol |
    +-----------+           +--------+

Attributes
----------

numsymbols : int immutable
    Number of symbols in the set.

Methods
-------

new symbolSetObj([string symbolfile]) : symbolSetObj_
    Create new instance.  If *symbolfile* is specified, symbols will be 
    loaded from the file.

appendSymbol(symbolObj_ symbol) : int
    Add a copy of *symbol* to the symbolset and return its index.

getSymbol(int index) : symbolObj_
    Returns a reference to the symbol at *index*.

getSymbolByName(string name) : symbolObj_
    Returns a reference to the symbol named *name*.

removeSymbol(int index) : symbolObj_
    Remove the symbol at *index* and return a copy of the symbol.


..  [1] This **really** needs to be changed in the future.  In fact a layer
    is much more re-useable than a map.  We don't keep redundant street
    data around for every map we draw.  We should likewise be able to attach
    the same layerObj to multiple mapObjs.

..  [2] See the comment about layerObj and mapObj above.  A styleObj is also
    a very reuseable thing.