vgfx-format.h

Go to the documentation of this file.

/*
 * vgfx-format.h
 *
 * Copyright (C) 2007  Thomas A. Vaughan
 * All rights reserved.
 *
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *     * Redistributions of source code must retain the above copyright
 *       notice, this list of conditions and the following disclaimer.
 *     * Redistributions in binary form must reproduce the above copyright
 *       notice, this list of conditions and the following disclaimer in the
 *       documentation and/or other materials provided with the distribution.
 *     * Neither the name of the <organization> nor the
 *       names of its contributors may be used to endorse or promote products
 *       derived from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THOMAS A. VAUGHAN ''AS IS'' AND ANY
 * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED. IN NO EVENT SHALL THOMAS A. VAUGHAN BE LIABLE FOR ANY
 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 *
 * Do NOT use this header file!  Here only for documenting the vgfx request
 * format.
 */

/// \ingroup vgfx
/*@{*/

////////////////////////////////////////////////////////////////////////////////
///
/// \defgroup vgfx_format vgfx Request Format
///
/// \n
/// This is a description of the vector graphics engine request format.  A
/// request is a text stream passed into a vgfx::processRequest() call.
///
/// A request is intended to be easy for humans to read and write, as well as
/// for programs to write and parse.  The folium application (included in the
/// folium package) is built on this vector graphics engine, and it constructs
/// vgfx requests on the fly in response to user input.  This is to do things
/// like add new pages to the folio, add a path consisting of bezier curves for
/// pen strokes, etc.
///
/// A request is a series of commands.  The entire request is treated as a
/// single transaction: either all of the commands succeed, or none do.  If a
/// request fails, the canvas (ObjectMap) remains in its clean pre-request
/// state.  (NOTE: applications can ask to run in non-transactional mode if
/// they'd like).
///
/// The vector graphics engine deals with primitive vector graphics objects such
/// as lines, curves, text, rectangles, etc.  These are called Primitive
/// objects.  A group is a special Primitive : it contains child Primitive
/// objects.  Groups can contain other groups recursively.
///
/// The request acts on an ObjectMap.  An ObjectMap is \b not a representation
/// of a 2D canvas!  Instead, an ObjectMap is a directory that contains all
/// Primitives that have been created, indexed by ID.  Many objects may not
/// be visible to an end application.
/// As
/// the owner of the ObjectMap, you can decide what objects you want to draw.
///
/// Your \ref vgfx::ObjectMap is like a big directory, containing all of the
/// \ref vgfx::Primitive objects you have defined.  You can use the registered
/// Primitives to construct rich hierarchical sets of vector graphic composite
/// objects, using Groups.
///
/// What sorts of commands can you issue in a request?
///  - add vector graphics Primitive objects
///  - remove Primitive objects
///  - set properties on Primitive objects (set will create the property if
///     it doesn't already exist on the Primitive)
///  - remove properties from Primitive objects
///
/// Every Primitive you create must have an ID that is unique within that
/// ObjectMap.  An ID can be any string that meets these requirements:
///  - must be a non-empty string
///  - must contain ONLY letters and numbers
///  - must begin with a letter
///
/// A request must begin with a "request {" line, and end with a single closing
/// curly bracket.  Between the opening and closing you can list multiple
/// commands.
///
/// Here are some sample requests:
///
/// \n
/// This request asks that a line be created, with id "line001".  The line
/// starts at (x0, y0) = (0, 0) (the default), and ends at (x1, y1) = (4, 4).
/// \code
/// request {
///     # note that any lines beginning with a hash mark are treated as comments
///
///     # this request creates a line
///     add line  id line001  x1 4  y1 4
/// }
/// \endcode
///
/// \n
/// Here is a request that creates a different line, with id "line002". 
/// \code
/// request {
///     add line  id line002  x1 4  y1 -4
/// }
/// \endcode
///
/// \n
/// You could decide to create a group that contained both of these objects
/// within it:
/// \code
/// request {
///     add group {
///             id      g001
///
///             object  tag first_line  id line001      x 1     y 1
///             object  tag second_line id line002      x 1     y 5
///     }
/// }
/// \endcode
/// That creates a single Primitive, of type group, with ID "g001".  The
/// group contains line001 starting at x=1, y=1 relative to the group
/// origin, and line002 starting at x=1, y=-5 relative to the
/// group origin.
///
/// \n
/// If you wanted, you could do all of that (create both lines and the group)
/// in a single transaction:
/// \code
/// request {
///
///     add line  id line001  x1 4  y1 4
///
///     add line  id line002  x1 4  y1 -4
///
///     add group {
///             id      g001
///
///             object  tag first_line  id line001      x 1     y 1
///             object  tag second_line id line002      x 1     y 5
///     }
/// }
/// \endcode
///
/// \n
/// Note that objects have to be created before they can be referenced.  So a
/// slightly re-ordered version of the above would fail:
/// \code
/// request {
///
///     add group {
///             id      g001
///
///             object  tag first_line  id line001      x 1     y 1             # error here!
///             object  tag second_line id line002      x 1     y 5
///     }
///
///     add line  id line001  x1 4  y1 4
///
///     add line  id line002  x1 4  y1 -4
///
/// }
/// \endcode
/// That request would fail when parsing the group because the object with ID
/// "line001" had not yet been defined.
///
/// \n
/// Objects are referred to by their ID, and are NOT copied.  You cannot remove
/// a Primitive if there are other Primitives (groups) that refer to it.
///
////////////////////////////////////////////////////////////////////////////////

/*@{*/

////////////////////////////////////////////////////////////////////////////////
///
/// \defgroup vgfx_format_special       Special vgfx meta tags
///
/// \n
/// The vgfx engine is aware of some meta tags.  In general, any tags beginning
/// with "vgfx" are reserved!  Don't use tags that begin with the \p vgfx prefix
/// unless the vgfx library is supposed to know about them.
///
/// Note that tags are recursively applied.  So if a group specifies a color
/// (for instance), that color will be applied to all subobjects within the
/// group unless they in turn override with an explicit color setting of
/// their own.
///
/// Here are the supported vgfx meta tags:
///  - \b vgfxClipHeight use this clip height
///  - \b vgfxClipWidth use this clip width
///  - \b vgfxColor change the line color to the value specified
///  - \b vgfxDrawBounds if true, groups will draw a rectangle around themselves
///             using the current pen color and thickness.  false by default.
///  - \b vgfxFillColor shapes will be filled with this color
///  - \b vgfxFont declares the font to be used for text primitives (see below).
///  - \b vgfxPath this is a persisted polygon path (a set of xy points).
///  - \b vgfxPrintable if true, this group will be printed.  Note that if a
///             group has no vgfxPrintable tag, it is assumed to be printable.
///             So this flag is usually only interesting if set to false.
///  - \b vgfxTextFlags declares flags to be used when rendering text (see below).
///  - \b vgfxThickness change the pen thickess to this value (cm)
///
/// \n
/// \b Fonts
/// \n
/// Font tags (\p vgfxFont) have a special value.  It is a single string that
/// contains font information such as:
///  - \b faceName the face name of the font
///  - \b size the size of the font in points
///
/// \n
/// \b Text \b Flags
/// \n
/// Text flags (\p vgfxTextFlags) are a string that contain a list of flags, such
/// as:
///  - \b center text should be centered
///  - \b left text should be left-justified
///  - \b right text should be right-justified
///
////////////////////////////////////////////////////////////////////////////////