| 103 | ===== !SymbolInstance Usage and Geometry Contexts ===== |
| 104 | A symbol definition can contain multiple usages - !PointUsage, !LineUsage, and !AreaUsage - which describe how the symbol behaves in the context of 0D, 1D, and 2D geometry. !PointUsage can be used in the context of point, polyline, and polygon features. In the case of polylines and polygons you simply need to pick a point on the polyline / polygon at which to draw the symbol (e.g. the mid-point or centroid). !LineUsage can be used in the context of polyline and polygon features. In the case of polygons, the !LineUsage applies to the polygon edge. !AreaUsage can only be used in the context of polygon features. |
| 105 | |
| 106 | Now consider the following scenario. You have a polygon layer and you want to define both the fill and edge style using some predefined symbols. Assume each symbol definition has all three usages defined. To configure your layer you create two !SymbolInstances, each referencing the appropriate symbol definition. You want the first symbol to be used for the fill style - so have its !AreaUsage be the active usage - and the second symbol to be used for the edge style - so have its !LineUsage be the active usage. Using the current schema it's not possible to do this. There's no place to put information that specifies which usage in a symbol definition should be the active usage. |
| 107 | |
| 108 | The proposed solution to this is to add an optional !UsageContext element to !SymbolInstance that specifies which usage type should be the active usage. In the above example you would set the !UsageContext for the first !SymbolInstance to Area and for the second !SymbolInstance to Line. |
| 109 | |
| 110 | Now let's take this example further. Suppose the feature source for your layer contains multiple geometry types: points, polylines, and polygons. You need to be able to control the stylization for each of these types. You have some predefined symbols you'd like to use for each type: a symbol with a !PointUsage for the points (symbol A), one with a !LineUsage for the polylines (symbol B), one with a !LineUsage for the polygon edges (symbol C), and a final one with an !AreaUsage for the polygon fill (symbol D). To configure your layer you create !SymbolInstances referencing each of these symbols. As described above, you set the !UsageType on each !SymbolInstance to remove any redundancy about which usage in the symbol definition should be active. Now the code starts drawing features from the layer. The only applicable symbol for point features is symbol A, so those features draw as expected. For polyline features we have a problem though: symbols A, B, and C can all be used to style polyline features. The active usage for symbol A is Point, and therefore we could draw a single instance of symbol A at the polyline mid-point. The active usages for symbols B and C is Line, and therefore we would use those symbols as line styles for that polyline. (The active usage for symbol D is Area, and that doesn't apply to polylines.) The same problem happens with polygon features: in this case all four symbols can be used to style polygon features. The basic problem here is that there's no place in the schema to specify which geometry type a symbol instance should apply to. There's no way for the code to automatically determine which symbols should be used for different geometry types. |
| 111 | |
| 112 | The proposed solution to this is to add an optional !GeometryContext element to !SymbolInstance that specifies which geometry type the symbol instance applies to. In the above example you would set the !GeometryContext to Point for !SymbolInstance A, Polyline for !SymbolInstance B, and Polygon for !SymbolInstance C and D. |
| 113 | |
| 114 | Adding !UsageContext and !GeometryContext eliminates all ambiguity when it comes to determining how to apply symbol definitions to a given feature. |
| 115 | |
| 116 | |