wiki:MapGuideRfc31

Context Navigation

Version 8 (modified by vishalbangia, 17 years ago) ( diff )
Date added

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 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	draft
Implementation Status	pending
Proposed Milestone	1.3
Assigned PSC guide(s)	(when determined)
Voting History	(vote date)
+1
+0
-0
-1

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:

<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> element, 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="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.<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". 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.

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

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.

Note: See TracWiki for help on using the wiki.

Download in other formats:

Plain Text