Changes between Version 1 and Version 2 of MapGuideRfc31


Ignore:
Timestamp:
08/30/07 11:28:07 (17 years ago)
Author:
vishalbangia
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • MapGuideRfc31

    v1 v2  
    2222 
    2323== Overview ==
    24 
    25 This section brefly describes the problem set, and the proposed solution in general terms.  It should be deliberately short, a couple of sentences or so.
     24The purpose of this RFC is two-fold. 
     25
     26# One is to allow for rich text Labels from a variety of defined input formats. 
     27# 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.
    2628
    2729== Motivation ==
    28 
    29 This is the most important part of the RFC.  It describes the problem domain in detail.  Focusing on this will allow reviewers to fully understand why the proposed change is being made, and potentially suggest different/better ways of accomplishing the desired results.  The more time we spend on understanding the problem, the better our solution will be.
     30The 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.
     31
     32Additionally, 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.
    3033
    3134== Proposed Solution ==
    32 
    33 This is a more detailed description of the actual changes desired.  The contents of this section will vary based on the target of the RFC, be it a technical change, website change, or process change.  For example, for a technical change, items such as files, XML schema changes, and API chances would be identified.  For a process change, the new process would be laid out in detail.  For a website change, the files affected would be listed.
     35The proposed solution contains modifications to:
     36* The MDF Model,
     37* The MDF Parser,
     38* The Vector Symbolization Font Engine.
     39
     40=== MDF Model Schema Modifications ===
     41The 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.
     42
     43The proposed changes can be divided into two distinct categories.
     44
     45==== <Text> Modifications ====
     46
     47This 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.
     48
     49Note: 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.
     50
     51To illustrate the schema changes, documentation has been removed from the schema snippets below for brevity and to remove unnecessary visual clutter.
     52
     53The '''<Text>''' element schema changes ''from'':
     54<pre>
     55<xs:complexType name="Text">
     56  <xs:annotation><xs:documentation>A text string to include in the symbol definition.</xs:documentation></xs:annotation>
     57  <xs:complexContent>
     58  <xs:extension base="GraphicBase">
     59  <xs:sequence>
     60    <xs:element name="Content"             type="xs:string">
     61    <xs:element name="FontName"            type="xs:string" default="'Arial'" />
     62    <xs:element name="Bold"                type="xs:string" default="false"           minOccurs="0" />
     63    <xs:element name="Italic"              type="xs:string" default="false"           minOccurs="0" />
     64    <xs:element name="Underlined"          type="xs:string" default="false"           minOccurs="0" />
     65    <xs:element name="Height"              type="xs:string" default="4.0"             minOccurs="0" />
     66    <xs:element name="HeightScalable"      type="xs:string" default="true"            minOccurs="0" />
     67    <xs:element name="Angle"               type="xs:string" default="0.0"             minOccurs="0" />
     68    <xs:element name="PositionX"           type="xs:string" default="0.0"             minOccurs="0" />
     69    <xs:element name="PositionY"           type="xs:string" default="0.0"             minOccurs="0" />
     70    <xs:element name="HorizontalAlignment" type="xs:string" default="'Center'"        minOccurs="0" />
     71    <xs:element name="VerticalAlignment"   type="xs:string" default="'Halfline'"      minOccurs="0" />
     72    <xs:element name="Justification"       type="xs:string" default="'FromAlignment'" minOccurs="0" />
     73    <xs:element name="LineSpacing"         type="xs:string" default="1.05"            minOccurs="0" />
     74    <xs:element name="TextColor"           type="xs:string" default="ff000000"        minOccurs="0" />
     75    <xs:element name="GhostColor"          type="xs:string"                           minOccurs="0" />
     76    <xs:element name="Frame"               type="TextFrame"                           minOccurs="0" />
     77    <xs:element name="ExtendedData1"       type="ExtendedDataType"                    minOccurs="0" />
     78  </xs:sequence>
     79  </xs:extension>
     80  </xs:complexContent>
     81</xs:complexType>
     82</pre>
     83
     84''to'' one that includes the '''<Markup>''' element, as follows:{{AnnoDL|TextSchema}}
     85<pre>
     86<xs:complexType name="Text">
     87  <xs:annotation><xs:documentation>A text string to include in the symbol definition.</xs:documentation></xs:annotation>
     88  <xs:complexContent>
     89  <xs:extension base="GraphicBase">
     90  <xs:sequence>
     91    <xs:element name="Markup"              type="xs:string" default="'Plain'"         minOccurs="0" />
     92    <xs:annotation><xs:documentation>The markup format of the string content.</xs:documentation></xs:annotation></xs:element>
     93    <xs:element name="Content"             type="xs:string"                                         />
     94    <xs:element name="FontName"            type="xs:string" default="'Arial'"                       />
     95    <xs:element name="Bold"                type="xs:string" default="false"           minOccurs="0" />
     96    <xs:element name="Italic"              type="xs:string" default="false"           minOccurs="0" />
     97    <xs:element name="Underlined"          type="xs:string" default="false"           minOccurs="0" />
     98    <xs:element name="Height"              type="xs:string" default="4.0"             minOccurs="0" />
     99    <xs:element name="HeightScalable"      type="xs:string" default="true"            minOccurs="0" />
     100    <xs:element name="Angle"               type="xs:string" default="0.0"             minOccurs="0" />
     101    <xs:element name="PositionX"           type="xs:string" default="0.0"             minOccurs="0" />
     102    <xs:element name="PositionY"           type="xs:string" default="0.0"             minOccurs="0" />
     103    <xs:element name="HorizontalAlignment" type="xs:string" default="'Center'"        minOccurs="0" />
     104    <xs:element name="VerticalAlignment"   type="xs:string" default="'Halfline'"      minOccurs="0" />
     105    <xs:element name="Justification"       type="xs:string" default="'FromAlignment'" minOccurs="0" />
     106    <xs:element name="LineSpacing"         type="xs:string" default="1.05"            minOccurs="0" />
     107    <xs:element name="TextColor"           type="xs:string" default="ff000000"        minOccurs="0" />
     108    <xs:element name="GhostColor"          type="xs:string"                           minOccurs="0" />
     109    <xs:element name="Frame"               type="TextFrame"                           minOccurs="0" />
     110    <xs:element name="ExtendedData1"       type="ExtendedDataType"                    minOccurs="0" />
     111  </xs:sequence>
     112  </xs:extension>
     113  </xs:complexContent>
     114</xs:complexType>
     115</pre>
     116
     117==== <Parameter> Modifications ====
     118
     119The second modification proposed is the set of values that can be present in the '''<DataType>''' element.<br>
     120Currently the meaning for '''<DataType>''' is
     121* '''"An optional data type declaration for the parameter."'''.
     122The proposed change would extend that meaning to be 
     123* '''"An optional explicit declaration of data type or ''data usage context''"
     124
     125In 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.
     126
     127The following documented values are proposed for the <DataType> element.
     128* Angle: ''a Real counterclockwise rotation, in degrees''
     129* FillColor: ''a Color applied to the interior of a polygon or symbol''
     130* LineColor: ''a Color applied to the edge of a polygon or symbol, or to a line''
     131* LineWeight: ''a Real line thickness, in millimeters''
     132* Content: ''a String that is displayed in a symbol''
     133* Markup: ''a String name of a rich text format used to interpret Content''
     134* FontName: ''a String determining the font for text''
     135* Bold: ''a Boolean determining if text is displayed in bold font''
     136* Italic: ''a Boolean determining if text is displayed in italic font''
     137* Underlined: ''a Boolean determining if text is displayed underlined''
     138* FontHeight: ''a Real height for text, in millimeters''
     139* HorizontalAlignment: ''a String evaluating to a horizontal alignment enumeration''
     140* VerticalAlignment: ''a String evaluating to a vertical alignment enumeration''
     141* Justification: ''a String evaluating to a justification enumeration''
     142* LineSpacing: ''a Real vertical distance between text lines, in millimeters''
     143* TextColor: ''a Color applied to text''
     144* GhostColor: ''a Color applied to the background in the neighborhood of text''
     145* FrameLineColor: ''a Color applied to the edge of a rectangle surrounding text''
     146* FrameFillColor: ''a Color applied to the interior of a rectangle surrounding text''
     147* StartOffset: ''a Real distance from a line feature's start to its first label, in millimeters''
     148* EndOffset: ''a Real distance from a line feature's end to its last label, in millimeters''
     149* RepeatX: ''a Real distance between a line feature's labels or an area feature's labels (horizontally), in millimeters''
     150* RepeatY: ''a Real distance between an area feature's labels (vertically), in millimeters''
     151
     152The changes proposed above affect the DataType values. <br>
     153The schema for '''<DataType>''' changes from the current version.
     154<pre>
     155  <xs:simpleType name="DataType">
     156  <xs:annotation>
     157  <xs:documentation>Enumerates the allowed DataType values.</xs:documentation>
     158  </xs:annotation>
     159  <xs:restriction base="xs:string">
     160  <xs:enumeration value="String" />
     161  <xs:enumeration value="Boolean" />
     162  <xs:enumeration value="Integer" />
     163  <xs:enumeration value="Real" />
     164  <xs:enumeration value="Color" />
     165  </xs:restriction>
     166  </xs:simpleType>
     167</pre>
     168
     169To include the new '''<DataType>''' values.
     170<pre>
     171  <xs:simpleType name="DataType">
     172  <xs:annotation>
     173  <xs:documentation>Enumerates the allowed DataType values.</xs:documentation>
     174  </xs:annotation>
     175  <xs:restriction base="xs:string">
     176  <xs:enumeration value="String" />
     177  <xs:enumeration value="Boolean" />
     178  <xs:enumeration value="Integer" />
     179  <xs:enumeration value="Real" />
     180  <xs:enumeration value="Color" />
     181  <xs:enumeration value="Angle" />
     182  <xs:enumeration value="FillColor" />
     183  <xs:enumeration value="LineColor" />
     184  <xs:enumeration value="LineWeight" />
     185  <xs:enumeration value="Content" />
     186  <xs:enumeration value="Markup" />
     187  <xs:enumeration value="Bold" />
     188  <xs:enumeration value="Italic" />
     189  <xs:enumeration value="Underlined" />
     190  <xs:enumeration value="FontHeight" />
     191  <xs:enumeration value="HorizontalAlignment" />
     192  <xs:enumeration value="VerticalAlignment" />
     193  <xs:enumeration value="Justification" />
     194  <xs:enumeration value="LineSpacing" />
     195  <xs:enumeration value="TextColor" />
     196  <xs:enumeration value="GhostColor" />
     197  <xs:enumeration value="FrameLineColor" />
     198  <xs:enumeration value="FrameFillColor" />
     199  <xs:enumeration value="StartOffset" />
     200  <xs:enumeration value="EndOffset" />
     201  <xs:enumeration value="RepeatX" />
     202  <xs:enumeration value="RepeatY" />
     203  </xs:restriction>
     204  </xs:simpleType>
     205</pre>
     206
     207Note: Vec Sym ''will'' add some more values to the above enumeration.
     208
     209==== Example ====
     210The following example presents a simple symbol definition that employs the changes proposed by this RFC.
     211
     212''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).''
     213<pre>
     214<?xml version="1.0" encoding="UTF-8"?>
     215<SimpleSymbolDefinition xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="SymbolDefinition-1.0.0.xsd" version="1.0.0">
     216  <Name>AnnotationLabel</Name>
     217  <Description></Description>
     218  <Graphics>
     219    <Text>
     220      <Content>%LBL_TEXT_CONTENT%</Content>
     221      <Markup>'Rtf'</Markup>
     222      <FontName>'Arial'</FontName>
     223      <Bold>True</Bold>
     224      <Italic>False</Italic>
     225      <Underlined>False</Underlined>
     226      <Height>3</Height>
     227      <HeightScalable>False</HeightScalable>
     228      <Angle>%LBL_ROTATION%</Angle>
     229      <PositionX>0.0</PositionX>
     230      <PositionY>0.0</PositionY>
     231      <HorizontalAlignment>Left</HorizontalAlignment>
     232      <VerticalAlignment>Baseline</VerticalAlignment>
     233      <TextColor>ff000000</TextColor>
     234    </Text>
     235  </Graphics>
     236  <ParameterDefinition>
     237    <Parameter>
     238      <Identifier>LBL_TEXT_CONTENT</Identifier>
     239      <DefaultValue>'Undefined'</DefaultValue>
     240      <DataType>Content</DataType>
     241      <DisplayName>Interstate Highway Number</DisplayName>
     242      <Description>The interstate name displayed</Description>
     243    </Parameter>
     244    <Parameter>
     245      <Identifier>LBL_ROTATION</Identifier>
     246      <DefaultValue>0.0</DefaultValue>
     247      <DataType>Angle_Degrees</DataType>
     248      <DisplayName>Angle</DisplayName>
     249      <Description>Rotation in degrees applied to the label</Description>
     250    </Parameter>
     251  </ParameterDefinition>
     252</SimpleSymbolDefinition>
     253</pre>
     254
     255=== The MDF Parser Modifications ===
     256The MDF Model uses the :
     257* Text class to store text element information.
     258The above class would require new methods to get and set the markup contents.
     259* There is no code change required for the DataType changes as it only affects the documentation/usage of the element.
     260
     261The 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.
     262
     263=== The Font Engine Modifications ===
     264The 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.
    34265
    35266== Implications ==
    36267
    37 This section allows discussion of the repercussions of the change, such as whether there will be any breakage in backwards compatibility, if documentation will need to be updated, etc.
     268This RFC does not directly impact the API, though it allows labels and symbol definitions to contain markup that permits a richer expression of labels.
    38269
    39270== Test Plan ==
    40271
    41 How the proposed change will be tested, if applicable.  New unit tests should be detailed here???
     272Unit 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.
    42273
    43274== Funding/Resources ==
    44275
    45 This section will confirm that the proposed feature has enough support to proceed.  This would typically mean that the entity making the changes would put forward the RFC, but a non-developer could act as an RFC author if they are sure they have the funding to cover the change.
     276Autodesk to provide resources / funding.