# vgfx-format.h

Go to the documentation of this file.
00001 /*
00002  * vgfx-format.h
00003  *
00004  * Copyright (C) 2007  Thomas A. Vaughan
00006  *
00007  *
00008  * Redistribution and use in source and binary forms, with or without
00009  * modification, are permitted provided that the following conditions are met:
00010  *     * Redistributions of source code must retain the above copyright
00011  *       notice, this list of conditions and the following disclaimer.
00012  *     * Redistributions in binary form must reproduce the above copyright
00013  *       notice, this list of conditions and the following disclaimer in the
00014  *       documentation and/or other materials provided with the distribution.
00015  *     * Neither the name of the <organization> nor the
00016  *       names of its contributors may be used to endorse or promote products
00017  *       derived from this software without specific prior written permission.
00018  *
00019  * THIS SOFTWARE IS PROVIDED BY THOMAS A. VAUGHAN ''AS IS'' AND ANY
00020  * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
00021  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
00022  * DISCLAIMED. IN NO EVENT SHALL THOMAS A. VAUGHAN BE LIABLE FOR ANY
00023  * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
00024  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
00025  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
00026  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
00027  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
00028  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00029  *
00030  *
00031  * Do NOT use this header file!  Here only for documenting the vgfx request
00032  * format.
00033  */
00034
00035 /// \ingroup vgfx
00036 /*@{*/
00037
00038 ////////////////////////////////////////////////////////////////////////////////
00039 ///
00040 /// \defgroup vgfx_format vgfx Request Format
00041 ///
00042 /// \n
00043 /// This is a description of the vector graphics engine request format.  A
00044 /// request is a text stream passed into a vgfx::processRequest() call.
00045 ///
00046 /// A request is intended to be easy for humans to read and write, as well as
00047 /// for programs to write and parse.  The folium application (included in the
00048 /// folium package) is built on this vector graphics engine, and it constructs
00049 /// vgfx requests on the fly in response to user input.  This is to do things
00050 /// like add new pages to the folio, add a path consisting of bezier curves for
00051 /// pen strokes, etc.
00052 ///
00053 /// A request is a series of commands.  The entire request is treated as a
00054 /// single transaction: either all of the commands succeed, or none do.  If a
00055 /// request fails, the canvas (ObjectMap) remains in its clean pre-request
00056 /// state.  (NOTE: applications can ask to run in non-transactional mode if
00057 /// they'd like).
00058 ///
00059 /// The vector graphics engine deals with primitive vector graphics objects such
00060 /// as lines, curves, text, rectangles, etc.  These are called Primitive
00061 /// objects.  A group is a special Primitive : it contains child Primitive
00062 /// objects.  Groups can contain other groups recursively.
00063 ///
00064 /// The request acts on an ObjectMap.  An ObjectMap is \b not a representation
00065 /// of a 2D canvas!  Instead, an ObjectMap is a directory that contains all
00066 /// Primitives that have been created, indexed by ID.  Many objects may not
00067 /// be visible to an end application.
00068 /// As
00069 /// the owner of the ObjectMap, you can decide what objects you want to draw.
00070 ///
00071 /// Your \ref vgfx::ObjectMap is like a big directory, containing all of the
00072 /// \ref vgfx::Primitive objects you have defined.  You can use the registered
00073 /// Primitives to construct rich hierarchical sets of vector graphic composite
00074 /// objects, using Groups.
00075 ///
00076 /// What sorts of commands can you issue in a request?
00077 ///  - add vector graphics Primitive objects
00078 ///  - remove Primitive objects
00079 ///  - set properties on Primitive objects (set will create the property if
00080 ///     it doesn't already exist on the Primitive)
00081 ///  - remove properties from Primitive objects
00082 ///
00083 /// Every Primitive you create must have an ID that is unique within that
00084 /// ObjectMap.  An ID can be any string that meets these requirements:
00085 ///  - must be a non-empty string
00086 ///  - must contain ONLY letters and numbers
00087 ///  - must begin with a letter
00088 ///
00089 /// A request must begin with a "request {" line, and end with a single closing
00090 /// curly bracket.  Between the opening and closing you can list multiple
00091 /// commands.
00092 ///
00093 /// Here are some sample requests:
00094 ///
00095 /// \n
00096 /// This request asks that a line be created, with id "line001".  The line
00097 /// starts at (x0, y0) = (0, 0) (the default), and ends at (x1, y1) = (4, 4).
00098 /// \code
00099 /// request {
00100 ///     # note that any lines beginning with a hash mark are treated as comments
00101 ///
00102 ///     # this request creates a line
00103 ///     add line  id line001  x1 4  y1 4
00104 /// }
00105 /// \endcode
00106 ///
00107 /// \n
00108 /// Here is a request that creates a different line, with id "line002".
00109 /// \code
00110 /// request {
00111 ///     add line  id line002  x1 4  y1 -4
00112 /// }
00113 /// \endcode
00114 ///
00115 /// \n
00116 /// You could decide to create a group that contained both of these objects
00117 /// within it:
00118 /// \code
00119 /// request {
00121 ///             id      g001
00122 ///
00123 ///             object  tag first_line  id line001      x 1     y 1
00124 ///             object  tag second_line id line002      x 1     y 5
00125 ///     }
00126 /// }
00127 /// \endcode
00128 /// That creates a single Primitive, of type group, with ID "g001".  The
00129 /// group contains line001 starting at x=1, y=1 relative to the group
00130 /// origin, and line002 starting at x=1, y=-5 relative to the
00131 /// group origin.
00132 ///
00133 /// \n
00134 /// If you wanted, you could do all of that (create both lines and the group)
00135 /// in a single transaction:
00136 /// \code
00137 /// request {
00138 ///
00139 ///     add line  id line001  x1 4  y1 4
00140 ///
00141 ///     add line  id line002  x1 4  y1 -4
00142 ///
00144 ///             id      g001
00145 ///
00146 ///             object  tag first_line  id line001      x 1     y 1
00147 ///             object  tag second_line id line002      x 1     y 5
00148 ///     }
00149 /// }
00150 /// \endcode
00151 ///
00152 /// \n
00153 /// Note that objects have to be created before they can be referenced.  So a
00154 /// slightly re-ordered version of the above would fail:
00155 /// \code
00156 /// request {
00157 ///
00159 ///             id      g001
00160 ///
00161 ///             object  tag first_line  id line001      x 1     y 1             # error here!
00162 ///             object  tag second_line id line002      x 1     y 5
00163 ///     }
00164 ///
00165 ///     add line  id line001  x1 4  y1 4
00166 ///
00167 ///     add line  id line002  x1 4  y1 -4
00168 ///
00169 /// }
00170 /// \endcode
00171 /// That request would fail when parsing the group because the object with ID
00172 /// "line001" had not yet been defined.
00173 ///
00174 /// \n
00175 /// Objects are referred to by their ID, and are NOT copied.  You cannot remove
00176 /// a Primitive if there are other Primitives (groups) that refer to it.
00177 ///
00178 ////////////////////////////////////////////////////////////////////////////////
00179
00180 /*@{*/
00181
00182 ////////////////////////////////////////////////////////////////////////////////
00183 ///
00184 /// \defgroup vgfx_format_special       Special vgfx meta tags
00185 ///
00186 /// \n
00187 /// The vgfx engine is aware of some meta tags.  In general, any tags beginning
00188 /// with "vgfx" are reserved!  Don't use tags that begin with the \p vgfx prefix
00189 /// unless the vgfx library is supposed to know about them.
00190 ///
00191 /// Note that tags are recursively applied.  So if a group specifies a color
00192 /// (for instance), that color will be applied to all subobjects within the
00193 /// group unless they in turn override with an explicit color setting of
00194 /// their own.
00195 ///
00196 /// Here are the supported vgfx meta tags:
00197 ///  - \b vgfxClipHeight use this clip height
00198 ///  - \b vgfxClipWidth use this clip width
00199 ///  - \b vgfxColor change the line color to the value specified
00200 ///  - \b vgfxDrawBounds if true, groups will draw a rectangle around themselves
00201 ///             using the current pen color and thickness.  false by default.
00202 ///  - \b vgfxFillColor shapes will be filled with this color
00203 ///  - \b vgfxFont declares the font to be used for text primitives (see below).
00204 ///  - \b vgfxPath this is a persisted polygon path (a set of xy points).
00205 ///  - \b vgfxPrintable if true, this group will be printed.  Note that if a
00206 ///             group has no vgfxPrintable tag, it is assumed to be printable.
00207 ///             So this flag is usually only interesting if set to false.
00208 ///  - \b vgfxTextFlags declares flags to be used when rendering text (see below).
00209 ///  - \b vgfxThickness change the pen thickess to this value (cm)
00210 ///
00211 /// \n
00212 /// \b Fonts
00213 /// \n
00214 /// Font tags (\p vgfxFont) have a special value.  It is a single string that
00215 /// contains font information such as:
00216 ///  - \b faceName the face name of the font
00217 ///  - \b size the size of the font in points
00218 ///
00219 /// \n
00220 /// \b Text \b Flags
00221 /// \n
00222 /// Text flags (\p vgfxTextFlags) are a string that contain a list of flags, such
00223 /// as:
00224 ///  - \b center text should be centered
00225 ///  - \b left text should be left-justified
00226 ///  - \b right text should be right-justified
00227 ///
00228 ////////////////////////////////////////////////////////////////////////////////