= !MapGuide RFC 31 - !SymbolDefinition Support for Edit Controls and Rich Text Support (Markup) =

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|| Aug 30, 2007||
||Last Modified||Vishal Bangia [[Timestamp]]||
||Author||Ben Trumbore, Vishal Bangia||
||RFC Status||adopted||
||Implementation Status||pending||
||Proposed Milestone||2.0||
||Assigned PSC guide(s)||(when determined)||
||'''Voting History'''||Oct 1/2007||
||+1||Tom, Paul, Andy, Bruce||
||+0||Jason, Bob||
||-0||||
||-1||||
||Abstain||Haris||
 
== 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 following ''optional'' sub elements to the <Text> schema element -
 * <Markup> : denotes the type of rich text markup used, (and consequently what parser to be used,) to render the contents. 
 * <Overlined> :  denotes the text style attribute to create a line that runs on the top of the text. Similar in usage and context to Underline.
 * <!ObliqueAngle> : denotes the skew or shear angle to be applied to the text.
 * <!TrackSpacing> : denotes the width scale applied to inter character spacing independent of the Font character spacing. 
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'':
{{{
<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>
}}}

''to'' one that includes the '''<Markup>, <Overlined>, <!ObliqueAngle> and <!TrackSpacing>''' elements, as follows:
{{{
<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="Overlined"           type="xs:string" default="false"           minOccurs="0" > 
    <xs:annotation><xs:documentation>Specifies if the text should be overlined. This must evaluate to True or False</xs:documentation><xs:annotation></xs:element>
    
    <xs:element name="ObliqueAngle"        type=”xs:string” default="0.0"             minOccurs="0" >
    <xs:annotation><xs:documentation>A numeric value between -85.0 and 85.0 representing the angle in degrees forward (for positive) or backwards (for negative)
    that the text should be obliqued (a la shear or skew transform.)</xs:documentation><xs:annotation></xs:element>
    
    <xs:element name="TrackSpacing"        type=”xs:string” default="1.0"             minOccurs="0" >
    <xs:annotation><xs:documentation>A numeric value between 0.75 and 10.0, representing the text “tracking” factor to apply to inter-character spacing, 
    effectively a multiplier of each character’s advance width. Values less than 1.0 condense the text, spacing individual characters closer together than normally 
    dictated by the font, whereas values greater than 1.0 expand the text, spacing characters farther apart.  The outline of individual characters is not altered by
    this element, only the spacing between them and adjacent characters.</xs:documentation><xs:annotation></xs:element>

    <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="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="ExtendedData1"       type="ExtendedDataType"                    minOccurs="0" />
  </xs:sequence>
  </xs:extension>
  </xs:complexContent>
</xs:complexType>
}}}

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

The second modification proposed is the set of values that can be present in the '''<!DataType>''' element.
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". 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''
 * Overlined: ''a Boolean determining if text is displayed overlined''
 * !ObliqueAngle : ''a Real skew angle for text, in degrees''
 * !TrackSpacing : ''a Real scale value that is applied to the inter character spacing for the font''
 * !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.
The schema for '''<!DataType>''' changes from the current version.
{{{
  <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>
}}}

To include the new '''<!DataType>''' values.
{{{
  <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>
}}}


==== 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).''
{{{
<?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>
      <Overlined>True</Overlined>
      <ObliqueAngle>25</ObliqueAngle>
      <TrackSpacing>2.0</TrackSpacing>
      <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</DataType>
      <DisplayName>Angle</DisplayName>
      <Description>Rotation in degrees applied to the label</Description>
    </Parameter>
  </ParameterDefinition>
</SimpleSymbolDefinition>
}}}

=== 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.