Changes between Version 19 and Version 20 of MapGuideRfc29


Ignore:
Timestamp:
09/19/07 15:08:12 (17 years ago)
Author:
waltweltonlair
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • MapGuideRfc29

    v19 v20  
    120120
    121121===== !StartOffset and !EndOffset Default Values in !LineUsage =====
    122 The !LineUsage element defines !StartOffset and !EndOffset elements which are used to control the offset of the symbol distribution at the start and end of a polyline.  The current !SymbolDefinition schema uses default values of zero for these elements.  The corrected behavior will be to not specify default values for these elements.  Here's an example where the original default values cause a problem:
     122The !LineUsage element defines !StartOffset and !EndOffset elements which are used to control the offset of the symbol distribution at the start and end of a polyline.  The current !SymbolDefinition schema uses default values of zero for these elements.  The corrected behavior will be to have the schema not specify default values for these elements.  Here's an example where specifying default values causes a problem:
    123123
    124124{{{
    125125<LineUsage>
     126   <StartOffset>0.0</StartOffset>
     127</LineUsage>
     128}}}
     129
     130In this case the user wants to only draw a symbol at the start of the polyline.  The !StartOffset is set to zero to indicate a symbol should be drawn at the start, and the !EndOffset is unspecified to indicate that no symbol should be drawn at the end.  The Repeat is also unspecified, which means the symbols should not be distributed within the polyline.
     131
     132Since the current schema documentation indicates that !StartOffset and !EndOffset have default values of zero, the previous snippet is equivalent to:
     133
     134{{{
     135<LineUsage>
     136   <StartOffset>0.0</StartOffset>
    126137   <EndOffset>0.0</EndOffset>
    127    <Repeat>1.0</Repeat>
    128138</LineUsage>
    129139}}}
    130140
    131 In this case the user wants the symbol distribution to repeat at an interval of 1 mm, and end exactly at the end of the polyline.  The !StartOffset is unspecified, and should therefore not be taken into account when computing the distribution.  The current schema documentation, however, indicates that the !StartOffset has a default value of zero if not specified, which implies that it actually should be taken into account.
    132 
    133 The proposed change in behavior is to only take into account the !StartOffset and/or !EndOffset elements if they are specified in the XML instance document.  In general here is the behavior:
    134 
    135 Repeat specified and greater than zero:
    136  * !StartOffset and !EndOffset both unspecified
    137   * symbols are distributed along the polyline using the Repeat value, with equal start and end offsets
    138   * the effective start and end offsets vary per polyline depending on its length
    139  * !StartOffset specified and !EndOffset unspecified
    140   * the symbol distribution has the specified start offset and repeats at the specified value
    141   * the effective end offset varies per polyline depending on its length
    142  * !StartOffset unspecified and !EndOffset specified
    143   * the symbol distribution has the specified end offset and repeats at the specified value
    144   * the effective start offset varies per polyline depending on its length
    145  * !StartOffset and !EndOffset both specified
    146   * the symbol distribution has the specified start and end offsets, and repeats at approximately the specified value
    147 
    148 Repeat less than or equal to zero (or unspecified):
    149  * !StartOffset and !EndOffset both unspecified
    150   * no symbols are drawn
    151  * !StartOffset specified and !EndOffset unspecified
    152   * a single symbol is drawn at the specified offset relative to the start of the polyline
    153  * !StartOffset unspecified and !EndOffset specified
    154   * a single symbol is drawn at the specified offset relative to the end of the polyline
    155  * !StartOffset and !EndOffset both specified
    156   * symbols are drawn at the specified offsets relative to the start and end of the polyline
     141and is what the stylization code will see.  The latter snippet means draw symbols at both the start and end of the polyline, and so the user ends up with the wrong behavior.
     142
     143The proposed schema change is to remove the default values for these elements and update the documentation.  The documentation will also state that only non-negative values are supported for these elements.
    157144
    158145
    … …  
    307294
    308295===== !StartOffset and !EndOffset Default Values in !LineUsage =====
    309 The schema documentation for the !StartOffset and !EndOffset elements in !LineUsage will be updated, and no default value will be specified for these elements.
     296The schema documentation for the !StartOffset and !EndOffset elements in !LineUsage will be updated, and no default values will be specified for these elements.
     297
     298As far as the code goes, the MdfModel::!LineUsage class will initialize these offsets to -1 to signal that they are unspecified.  The stylization code can then take this into account when it renders the actual line style.  For example, if the Repeat is unspecified (<=0), then an unspecified !StartOffset or !EndOffset element means do not draw a symbol at the start / end.  If the Repeat is specified (>0), then the code will assume default effective values for any unspecified offsets.  The effective values will vary based on things like the specified !VertexControl option and (in some cases) the polyline geometry.
    310299
    311300