= !MapGuide RFC # - Title Goes Here =

This page contains an change request (RFC) for the !MapGuide Open Source project.  
More !MapGuide RFCs can be found on the [wiki:MapGuideRfcs RFCs] page.


== Status == 
 
||RFC Template Version||(1.0)|| 
||Submission Date||(Date/Time submitted)||
||Last Modified||(your name here) [[Timestamp]]||
||Author||(your name here)||
||RFC Status||(draft, proposed, frozen for vote, adopted, retracted, or rejected)||
||Implementation Status||(pending, under development, completed)||
||Proposed Milestone||(e.g. 1.1, 1.3)||
||Assigned PSC guide(s)||(when determined)||
||'''Voting History'''||(vote date)||
||+1||Bob, Andy, Haris||
||+0||Paul||
||-0||Tom, Bruce||
||-1||Jason (troublemaker)||
 
== Overview ==
The purpose of this RFC is two-fold.  

# One is to allow for rich text Labels from a variety of defined input formats.  
# The second is to allow SymbolDefinitions to describe their parameter information in usage context terms, thus allowing consuming applications to present more sophisticated workflows and customized user interfaces.

== Motivation ==
The next logical evolution of text/labeling in MapGuide is to permit rich text (multi-font, multi-line) capabilities.  This facilitates the customization of labels in a variety of ways, allowing for a higher degree of customization.  For example, if a particular label was too long to fit in its space (say, a short cul-de-sac having a very long name) a "narrow" variant of the font used might be selected to permit it to fit, or the geometry of the font might be appropriately condensed.

Additionally, the rich new functionality from the usage of SymbolDefinitions as presented by CompositeSymbolization presents a challenge due to its inherent flexibility (read complexity).  To enable users to harness its capabilities without getting lost in the myriad possibilities, a mechanism to allow for customizable User Interfaces and simplified workflows based on active options is highly desired.

== Proposed Solution ==
The proposed solution contains modifications to:
* The MDF Model,
* The MDF Parser,
* The Vector Symbolization Font Engine.

=== MDF Model Schema Modifications ===
The proposed modifications to the MDF Model schema lie in the SymbolDefinition specification.  While the current version of the SymbolDefinition schema is 1.0.0, if these changes are adopted then they will be present in the SymbolDefinition schema version 1.1.0.

The proposed changes can be divided into two distinct categories.

==== <Text> Modifications ====

This modification adds the ''optional'' sub element <Markup> to the <Text> schema element. <Markup> represents the element whose value denotes the type of rich text markup used, (and consequently what parser to be used,) to render the contents. 

Note: The separation of the markup format from the actual text content is to allow for the use cases where rich text formats do not have specific encoding tags that allow for runtime identification.  Not all markup formats can be reliably identified using heuristics.

To illustrate the schema changes, documentation has been removed from the schema snippets below for brevity and to remove unnecessary visual clutter.

The '''<Text>''' element schema changes ''from'':
<pre>
<xs:complexType name="Text">
  <xs:annotation><xs:documentation>A text string to include in the symbol definition.</xs:documentation></xs:annotation>
  <xs:complexContent>
  <xs:extension base="GraphicBase">
  <xs:sequence>
    <xs:element name="Content"             type="xs:string">
    <xs:element name="FontName"            type="xs:string" default="'Arial'" />
    <xs:element name="Bold"                type="xs:string" default="false"           minOccurs="0" />
    <xs:element name="Italic"              type="xs:string" default="false"           minOccurs="0" />
    <xs:element name="Underlined"          type="xs:string" default="false"           minOccurs="0" />
    <xs:element name="Height"              type="xs:string" default="4.0"             minOccurs="0" />
    <xs:element name="HeightScalable"      type="xs:string" default="true"            minOccurs="0" />
    <xs:element name="Angle"               type="xs:string" default="0.0"             minOccurs="0" />
    <xs:element name="PositionX"           type="xs:string" default="0.0"             minOccurs="0" />
    <xs:element name="PositionY"           type="xs:string" default="0.0"             minOccurs="0" />
    <xs:element name="HorizontalAlignment" type="xs:string" default="'Center'"        minOccurs="0" />
    <xs:element name="VerticalAlignment"   type="xs:string" default="'Halfline'"      minOccurs="0" />
    <xs:element name="Justification"       type="xs:string" default="'FromAlignment'" minOccurs="0" />
    <xs:element name="LineSpacing"         type="xs:string" default="1.05"            minOccurs="0" />
    <xs:element name="TextColor"           type="xs:string" default="ff000000"        minOccurs="0" />
    <xs:element name="GhostColor"          type="xs:string"                           minOccurs="0" />
    <xs:element name="Frame"               type="TextFrame"                           minOccurs="0" />
    <xs:element name="ExtendedData1"       type="ExtendedDataType"                    minOccurs="0" />
  </xs:sequence>
  </xs:extension>
  </xs:complexContent>
</xs:complexType>
</pre>

''to'' one that includes the '''<Markup>''' element, as follows:{{AnnoDL|TextSchema}}
<pre>
<xs:complexType name="Text">
  <xs:annotation><xs:documentation>A text string to include in the symbol definition.</xs:documentation></xs:annotation>
  <xs:complexContent>
  <xs:extension base="GraphicBase">
  <xs:sequence>
    <xs:element name="Markup"              type="xs:string" default="'Plain'"         minOccurs="0" />
    <xs:annotation><xs:documentation>The markup format of the string content.</xs:documentation></xs:annotation></xs:element>
    <xs:element name="Content"             type="xs:string"                                         />
    <xs:element name="FontName"            type="xs:string" default="'Arial'"                       />
    <xs:element name="Bold"                type="xs:string" default="false"           minOccurs="0" />
    <xs:element name="Italic"              type="xs:string" default="false"           minOccurs="0" />
    <xs:element name="Underlined"          type="xs:string" default="false"           minOccurs="0" />
    <xs:element name="Height"              type="xs:string" default="4.0"             minOccurs="0" />
    <xs:element name="HeightScalable"      type="xs:string" default="true"            minOccurs="0" />
    <xs:element name="Angle"               type="xs:string" default="0.0"             minOccurs="0" />
    <xs:element name="PositionX"           type="xs:string" default="0.0"             minOccurs="0" />
    <xs:element name="PositionY"           type="xs:string" default="0.0"             minOccurs="0" />
    <xs:element name="HorizontalAlignment" type="xs:string" default="'Center'"        minOccurs="0" />
    <xs:element name="VerticalAlignment"   type="xs:string" default="'Halfline'"      minOccurs="0" />
    <xs:element name="Justification"       type="xs:string" default="'FromAlignment'" minOccurs="0" />
    <xs:element name="LineSpacing"         type="xs:string" default="1.05"            minOccurs="0" />
    <xs:element name="TextColor"           type="xs:string" default="ff000000"        minOccurs="0" />
    <xs:element name="GhostColor"          type="xs:string"                           minOccurs="0" />
    <xs:element name="Frame"               type="TextFrame"                           minOccurs="0" />
    <xs:element name="ExtendedData1"       type="ExtendedDataType"                    minOccurs="0" />
  </xs:sequence>
  </xs:extension>
  </xs:complexContent>
</xs:complexType>
</pre>

==== <Parameter> Modifications ====

The second modification proposed is the set of values that can be present in the '''<DataType>''' element.<br>
Currently the meaning for '''<DataType>''' is 
* '''"An optional data type declaration for the parameter."'''.
The proposed change would extend that meaning to be  
* '''"An optional explicit declaration of data type or ''data usage context''"

In layman terms, that would imply that the DataType element could be used to define a value such as "Angle" which describes the usage of a more basic type like "double".<br> Furthermore, this rich description of the data type can allow consuming applications to afford more targeted user worklows and UI controls.

The following documented values are proposed for the <DataType> element.
* Angle: ''a Real counterclockwise rotation, in degrees''
* FillColor: ''a Color applied to the interior of a polygon or symbol''
* LineColor: ''a Color applied to the edge of a polygon or symbol, or to a line''
* LineWeight: ''a Real line thickness, in millimeters''
* Content: ''a String that is displayed in a symbol''
* Markup: ''a String name of a rich text format used to interpret Content''
* FontName: ''a String determining the font for text''
* Bold: ''a Boolean determining if text is displayed in bold font''
* Italic: ''a Boolean determining if text is displayed in italic font''
* Underlined: ''a Boolean determining if text is displayed underlined''
* FontHeight: ''a Real height for text, in millimeters''
* HorizontalAlignment: ''a String evaluating to a horizontal alignment enumeration''
* VerticalAlignment: ''a String evaluating to a vertical alignment enumeration''
* Justification: ''a String evaluating to a justification enumeration''
* LineSpacing: ''a Real vertical distance between text lines, in millimeters''
* TextColor: ''a Color applied to text''
* GhostColor: ''a Color applied to the background in the neighborhood of text''
* FrameLineColor: ''a Color applied to the edge of a rectangle surrounding text''
* FrameFillColor: ''a Color applied to the interior of a rectangle surrounding text''
* StartOffset: ''a Real distance from a line feature's start to its first label, in millimeters''
* EndOffset: ''a Real distance from a line feature's end to its last label, in millimeters''
* RepeatX: ''a Real distance between a line feature's labels or an area feature's labels (horizontally), in millimeters''
* RepeatY: ''a Real distance between an area feature's labels (vertically), in millimeters''

The changes proposed above affect the DataType values. <br> 
The schema for '''<DataType>''' changes from the current version.
<pre>
  <xs:simpleType name="DataType">
  <xs:annotation>
  <xs:documentation>Enumerates the allowed DataType values.</xs:documentation> 
  </xs:annotation>
  <xs:restriction base="xs:string">
  <xs:enumeration value="String" /> 
  <xs:enumeration value="Boolean" /> 
  <xs:enumeration value="Integer" /> 
  <xs:enumeration value="Real" /> 
  <xs:enumeration value="Color" /> 
  </xs:restriction>
  </xs:simpleType>
</pre>

To include the new '''<DataType>''' values.
<pre>
  <xs:simpleType name="DataType">
  <xs:annotation>
  <xs:documentation>Enumerates the allowed DataType values.</xs:documentation> 
  </xs:annotation>
  <xs:restriction base="xs:string">
  <xs:enumeration value="String" /> 
  <xs:enumeration value="Boolean" /> 
  <xs:enumeration value="Integer" /> 
  <xs:enumeration value="Real" /> 
  <xs:enumeration value="Color" />
  <xs:enumeration value="Angle" />
  <xs:enumeration value="FillColor" />
  <xs:enumeration value="LineColor" />
  <xs:enumeration value="LineWeight" />
  <xs:enumeration value="Content" />
  <xs:enumeration value="Markup" />
  <xs:enumeration value="Bold" />
  <xs:enumeration value="Italic" />
  <xs:enumeration value="Underlined" />
  <xs:enumeration value="FontHeight" />
  <xs:enumeration value="HorizontalAlignment" />
  <xs:enumeration value="VerticalAlignment" />
  <xs:enumeration value="Justification" />
  <xs:enumeration value="LineSpacing" />
  <xs:enumeration value="TextColor" />
  <xs:enumeration value="GhostColor" />
  <xs:enumeration value="FrameLineColor" />
  <xs:enumeration value="FrameFillColor" />
  <xs:enumeration value="StartOffset" />
  <xs:enumeration value="EndOffset" />
  <xs:enumeration value="RepeatX" />
  <xs:enumeration value="RepeatY" />
  </xs:restriction>
  </xs:simpleType>
</pre>

Note: Vec Sym ''will'' add some more values to the above enumeration.

==== Example ====
The following example presents a simple symbol definition that employs the changes proposed by this RFC.

''Notes: The usage of '''rtf''' in the markup preposes that the user has the added capability to process the encoded contents in the consuming application (i.e. a '''rtf''' reader and writer).''
<pre>
<?xml version="1.0" encoding="UTF-8"?>
<SimpleSymbolDefinition xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="SymbolDefinition-1.0.0.xsd" version="1.0.0">
  <Name>AnnotationLabel</Name>
  <Description></Description>
  <Graphics>
    <Text>
      <Content>%LBL_TEXT_CONTENT%</Content>
      <Markup>'Rtf'</Markup> 
      <FontName>'Arial'</FontName>
      <Bold>True</Bold>
      <Italic>False</Italic>
      <Underlined>False</Underlined>
      <Height>3</Height>
      <HeightScalable>False</HeightScalable>
      <Angle>%LBL_ROTATION%</Angle>
      <PositionX>0.0</PositionX>
      <PositionY>0.0</PositionY>
      <HorizontalAlignment>Left</HorizontalAlignment>
      <VerticalAlignment>Baseline</VerticalAlignment>
      <TextColor>ff000000</TextColor>
    </Text>
  </Graphics>
  <ParameterDefinition>
    <Parameter>
      <Identifier>LBL_TEXT_CONTENT</Identifier>
      <DefaultValue>'Undefined'</DefaultValue>
      <DataType>Content</DataType>
      <DisplayName>Interstate Highway Number</DisplayName>
      <Description>The interstate name displayed</Description>
    </Parameter>
    <Parameter>
      <Identifier>LBL_ROTATION</Identifier>
      <DefaultValue>0.0</DefaultValue>
      <DataType>Angle_Degrees</DataType>
      <DisplayName>Angle</DisplayName>
      <Description>Rotation in degrees applied to the label</Description>
    </Parameter>
  </ParameterDefinition>
</SimpleSymbolDefinition>
</pre>

=== The MDF Parser Modifications ===
The MDF Model uses the :
* Text class to store text element information.
The above class would require new methods to get and set the markup contents.
* There is no code change required for the DataType changes as it only affects the documentation/usage of the element.

The MDF Parser uses the IOText class to read and write the XML text definitions. It would be updated to handle reading and writing of the new Markup element, including proper versioning support.

=== The Font Engine Modifications ===
The RS_FontEngine will be enhanced to support the parsing and display of rich text formatted strings.  Parsing will be done with a generic rich text parser interface which may be implemented for a variety of markup protocols.  Rendering will be done with the currently implemented SE rendering engine.

== Implications ==

This RFC does not directly impact the API, though it allows labels and symbol definitions to contain markup that permits a richer expression of labels.

== Test Plan ==

Unit tests will verify the integrity of MDF Model values, and the ability to communicate both plain and rich text through the pipeline to the rendering components.

== Funding/Resources ==

Autodesk to provide resources / funding.