Public Member Functions | Properties
ShapeDrawingOptions Class Reference

Holds the set of options for visualization of shapefiles. More...

List of all members.

Public Member Functions

ShapeDrawingOptions Clone ()
 Creates a new instance of ShapeDrawingOptions class by copying all the properties.
void Deserialize (string newVal)
 Restores the state of object from the string.
bool DrawLine (IntPtr hdc, float x, float y, int Width, int Height, bool drawVertices, int clipWidth, int clipHeight, uint BackColor)
 Draws a line using the stored options on specified device context.
bool DrawLineVB (int hdc, float x, float y, int Width, int Height, bool drawVertices, int clipWidth, int clipHeight, uint BackColor)
 Draws a line using the stored options on the specified device context.
bool DrawPoint (IntPtr hdc, float x, float y, int clipWidth, int clipHeight, uint BackColor)
 Draws a point symbol using the stored options on the specified device context.
bool DrawPointVB (int hdc, float x, float y, int clipWidth, int clipHeight, uint BackColor)
 Draws a point symbol using the stored options on the specified device context.
bool DrawRectangle (IntPtr hdc, float x, float y, int Width, int Height, bool drawVertices, int clipWidth, int clipHeight, uint BackColor)
 Draws a rectangle using the stored options on the specified device context.
bool DrawRectangleVB (int hdc, float x, float y, int Width, int Height, bool drawVertices, int clipWidth, int clipHeight, uint BackColor)
 Draws a rectangle using the stored options on the specified device context.
bool DrawShape (IntPtr hdc, float x, float y, Shape Shape, bool drawVertices, int clipWidth, int clipHeight, uint BackColor)
 Draws a shape using the stored options on the specified device context.
bool DrawShapeVB (int hdc, float x, float y, Shape Shape, bool drawVertices, int clipWidth, int clipHeight, uint BackColor)
 Draws a shape using the stored options on the specified device context.
string get_ErrorMsg (int ErrorCode)
 Gets the text description of the specified error code.
string Serialize ()
 Saves the state of the class to the string.
void SetDefaultPointSymbol (tkDefaultPointSymbol symbol)
 Sets a predefined combination of properties to set the commonly used symbols.
void SetGradientFill (uint Color, short range)
 Provides a convenient way to set colors of the gradient fill.

Properties

bool AlignPictureByBottom [get, set]
 Gets or sets a value indicating whether hot spot of icons should be position at the bottom center. When set to false the hotspot will be at the center of icon.
tkVectorDrawingMode DrawingMode [get, set]
 The graphical mode to be used to render symbology.
bool DynamicVisibility [get, set]
 Gets or sets a value indicating whether the category will be displayed only for scale range specified by MinVisibleScale and MaxVisibleScale properties.
uint FillBgColor [get, set]
 Gets or sets the background color of the polygon fill.
bool FillBgTransparent [get, set]
 Gets or sets the value which indicates whether a background will be drawn when ShapeDrawingOptions.FillType is set to ftHatch.
uint FillColor [get, set]
 Gets or sets the fill color of the shape.
uint FillColor2 [get, set]
 Gets or sets the end color of the gradient fill.
tkGradientBounds FillGradientBounds [get, set]
 Gets or sets the the value which defines the bounds of the gradient fill.
tkGradientType FillGradientType [get, set]
 The type of the gradient to draw polygon fill of the point symbols and polygon shapes.
tkGDIPlusHatchStyle FillHatchStyle [get, set]
 The hatch style of the fill for point symbols and polygon shapes.
double FillRotation [get, set]
 Gets or sets the angle of rotation of the polygon fill in degrees.
float FillTransparency [get, set]
 Gets or sets the transparency of the fill. Ranges from 0 (transparent) to 255 (opaque).
tkFillType FillType [get, set]
 The type of the polygon fill. See the enumeration for details.
bool FillVisible [get, set]
 Gets or sets the value which indicates whether the fill is visible.
string FontName [get, set]
 The name of the font to use for drawing point symbols when ShapeDrawingOptions.PointType is equal to pstCharacter.
tkLabelFrameType FrameType [get, set]
 Gets or sets type of frame to be displayed around point when ShapeDrawingOptions.PointShape is set to ptSymbolFontCharacter.
bool FrameVisible [get, set]
 Gets or sets a value indicating whether a frame will be drawn around point when ShapeDrawingOptions.PointShape is set to ptSymbolFontCharacter.
int LastErrorCode [get]
 Retrieves the numeric code of the last error that took place in the instance class.
uint LineColor [get, set]
 Gets or sets the line color of the shapes.
LinePattern LinePattern [get, set]
 Gets or sets line pattern for rendering polyline shapefile.
tkDashStyle LineStipple [get, set]
 Gets or sets the line style of the shapes.
float LineTransparency [get, set]
 Gets or sets the transparency of lines. Ranges from 0 (transparent) to 255 (opaque).
bool LineVisible [get, set]
 Gets or sets the value which indicates whether lines will be visible while drawing shapes.
float LineWidth [get, set]
 Gets or sets the width of the lines to draw shapes.
double MaxVisibleScale [get, set]
 Gets or sets maximum map scale at which the category is visible when ShapeDrawingOptions.DynamicVisibility is set to true.
double MinVisibleScale [get, set]
 Gets or sets minimum map scale at which the category is visible when ShapeDrawingOptions.DynamicVisibility is set to true.
Image Picture [get, set]
 Gets or sets the picture which will be used as texture brush (ShapeDrawingOptions.FillType = ftPicture) or point symbol (ShapeDrawingOptions.PointType = ptSymbolPicture).
double PictureScaleX [get, set]
 Gets or sets the coefficient for scaling picture horizontally.
double PictureScaleY [get, set]
 Gets or sets the coefficient for scaling picture vertically.
short PointCharacter [get, set]
 Get or sets the ANSI code of the text character to use as point symbol.
double PointRotation [get, set]
 Gets or sets the rotation of the point symbol in degrees.
tkPointShapeType PointShape [get, set]
 Gets or sets the predefined shape for the point symbol.
int PointSidesCount [get, set]
 Gets or sets the number of sides for some of the predefined symbols such as regular, star or cross.
float PointSidesRatio [get, set]
 Gets or sets the side ratio for some of the predefined point symbols such as regular, star and cross.
float PointSize [get, set]
 Gets or sets the size of the point symbol including predefined symbols, characters and pictures.
tkPointSymbolType PointType [get, set]
 Gets or sets the type of the point symbols.
string Tag [get, set]
 Gets or sets a string associated with the instance of class. Can store any information provided by developer.
bool UseLinePattern [get, set]
 Gets or set the value which indicates whether line pattern will be used to render polyline shapefile.
uint VerticesColor [get, set]
 Gets or sets the color of vertices for the shapes.
bool VerticesFillVisible [get, set]
 Gets or sets the value which indicates whether the fill for shape vertices will be drawn.
int VerticesSize [get, set]
 Gets or sets the size of the shapes's vertices.
tkVertexType VerticesType [get, set]
 Gets or sets the type of shape vertices.
bool VerticesVisible [get, set]
 Gets or sets the value which indicates whether vertices of the shape will be visible. The default values is false.
bool Visible [get, set]
 Gets or sets the values which indicates whether shapes will be visible.

Detailed Description

Holds the set of options for visualization of shapefiles.

dot_inline_dotgraph_57.png

Graph description

I. The class is used for rendering different types of shapefiles: point (multipoint), polyline, polygon. The set of options available for these types differ accordingly. The whole set options can be split into following groups:

The table shows relation between shape types and the set of options available for them.

Shapefile type Fill Outline Line pattern Point symbols Vertices
Point, MultiPoint + + - + -
Polyline - + + - +
Polygon + + - - +

Below the listed sets of options will be described in more detail. Fill options and point symbols provides different types of symbology, like standard, hatch, gradient, texture for fill; and standard, font character, picture for point symbols.

1. Fill options. They are applicable for polygon, point and multipoint shapefiles. Use ShapeDrawingOptions.FillType to change the type of fill.

dot_inline_dotgraph_58.png
 Shapefile sf = some_shapefile;
 ShapeDrawingOptions options = sf.DefaultDrawingOptions;
 Utils utils = new Utils();
 
 // standard fill
 options.FillType = tkFillType.ftStandard;
 options.FillColor = utils.ColorByName(tkMapColor.Red);
 
 // hatch fill
 options.FillType = tkFillType.ftHatch;
 options.FillBgTransparent = true;
 options.FillHatchStyle = tkGDIPlusHatchStyle.hsHorizontal;
 
 // gradient for each shape
 options.FillType = tkFillType.ftGradient;
 options.FillColor2 = Utils.ColorByName(tkMapColor.Blue);
 options.FillGradientBounds = tkGradientBounds.gbPerShape;
 
 // texture
 options.FillType =tkFillType.ftTexture;
 Image img = new Image();
 img.Open("some_arguments");
 options.Picture = img;

2. Point symbols. They are applicable for point (multipoint) shapefiles only. Use ShapeDrawingOptions.PointType to change the type of symbol.

dot_inline_dotgraph_59.png
 Shapefile sf = some_shapefile;
 ShapeDrawingOptions options = sf.DefaultDrawingOptions;
 options.FillColor = utils.ColorByName(tkMapColor.Red);
 Utils utils = new Utils();
 
 // standard symbol
 options.PointType = tkPointSymbolType.ptSymbolStandard;
 options.PointShape = tkPointShapeType.ptShapeStar;
 options.PointSidesCount = 5;
 
 // the same using predefined symbols (a short for 3 calls listed above)
 options.SetDefaultPointSymbol(tkDefaultPointSymbol.dpsStar);
 
 // font character
 options.PointType = tkPointSymbolType.ptSymbolFontCharacter;
 options.PointCharacter = (short)'a';
 options.FontName = "Arial";
 
 // picture
 options.PointType = tkPointSymbolType.ptSymbolPicture;
 Image img = new Image();
 img.Open("some_arguments");
 options.Picture = img;
 options.PointRotation = 45.0;   // rotate picture by 45 degrees

3. Outline, line pattern and vertices. Outline options applicable for all shapefile types, line patterns - for polylines only, vertices - for polylines and polygons.

dot_inline_dotgraph_60.png

II. The drawing options for shapefile are split into:

  1. Default drawing options (Shapefile.DefaultDrawingOptions).
  2. Drawing options for shapefile categories (ShapefileCategory.DrawingOptions).

The shapes that doesn't belong to any visualization category will be painted with default options. To return the index of the category a shape belongs to, call Shapefile.get_ShapeCategory(). The value -1 means that default drawing options will be used.

 Shapefile sf = some_shapefile;
 
 // specifies a visualization category
 ShapefileCategory ct = sf.Categories.Add("Thick");
 ct.DrawingOptions.LineWidth = 4.0;
 
 // let's add first 10 shapes to it
 for (int i = 0; i < 10; i++) {
     sf.put_ShapeCategory(i, 0);  // 0 - the index of category
 }
 
 // now let's set the width for the rest lines
 sf.DefaultDrawingOptions.LineWidth = 2.0;

The class also provides a set of methods to draw map legend on the device context other than AxMap: DrawShape(), DrawLine(), DrawPoint(), DrawRectangle().

New API 4.8:
Added in version 4.8
Examples:
IntersectionLength.cs, MarkPoints.cs, and Segmentation.cs.

Member Function Documentation

Creates a new instance of ShapeDrawingOptions class by copying all the properties.

Returns:
The reference to the new instance of the ShapeDrawingOptions class or NULL reference on failure.
void ShapeDrawingOptions.Deserialize ( string  newVal)

Restores the state of object from the string.

Parameters:
newValA string generated by ShapeDrawingOptions.Serialize() method.
bool ShapeDrawingOptions.DrawLine ( IntPtr  hdc,
float  x,
float  y,
int  Width,
int  Height,
bool  drawVertices,
int  clipWidth,
int  clipHeight,
uint  BackColor 
)

Draws a line using the stored options on specified device context.

The method can be used to draw map legend.

Parameters:
hdcThe handle of the device context. Can be obtained with .NET Graphics.GetHDC() method.
xThe x coordinate of the upper left corner of the drawing.
yThe y coordinate of the upper left corner of the drawing.
WidthThe width of the drawing.
HeightThe height of the drawing.
drawVerticesA value which indicates whether or not vertices of the line will be drawn.
clipWidthThe width of the clipping rectangle.
clipHeightThe height of the clipping rectangle.
BackColorThe back color of the device context the drawing is performed at. The value should be specified to ensure correct blending when semi-transparent colors are used.
Returns:
True on success and false otherwise.
bool ShapeDrawingOptions.DrawLineVB ( int  hdc,
float  x,
float  y,
int  Width,
int  Height,
bool  drawVertices,
int  clipWidth,
int  clipHeight,
uint  BackColor 
)

Draws a line using the stored options on the specified device context.

The method can be used to draw map legend.

Parameters:
hdcThe handle of the device context.
xThe x coordinate of the upper left corner of the drawing.
yThe y coordinate of the upper left corner of the drawing.
WidthThe width of the drawing.
HeightThe height of the drawing.
drawVerticesA value which indicates whether or not vertices of the line will be drawn.
clipWidthThe width of the clipping rectangle.
clipHeightThe height of the clipping rectangle.
BackColorThe back color of the device context the drawing is performed at. The value should be specified to ensure correct blending when semi-transparent colors are used.
Returns:
True on success and false otherwise.
bool ShapeDrawingOptions.DrawPoint ( IntPtr  hdc,
float  x,
float  y,
int  clipWidth,
int  clipHeight,
uint  BackColor 
)

Draws a point symbol using the stored options on the specified device context.

The method can be used to draw map legend.

Parameters:
hdcThe handle of the device context. Can be obtained with .NET Graphics.GetHDC() method.
xThe x coordinate of the upper left corner of the drawing.
yThe y coordinate of the upper left corner of the drawing.
clipWidthThe width of the clipping rectangle.
clipHeightThe height of the clipping rectangle.
BackColorThe back color of the device context the drawing is performed at. The value should be specified to ensure correct blending when semi-transparent colors are used.
Returns:
True on success and false otherwise.
bool ShapeDrawingOptions.DrawPointVB ( int  hdc,
float  x,
float  y,
int  clipWidth,
int  clipHeight,
uint  BackColor 
)

Draws a point symbol using the stored options on the specified device context.

The method can be used to draw map legend.

Parameters:
hdcThe handle of the device context.
xThe x coordinate of the upper left corner of the drawing.
yThe y coordinate of the upper left corner of the drawing.
clipWidthThe width of the clipping rectangle.
clipHeightThe height of the clipping rectangle.
BackColorThe back color of the device context the drawing is performed at. The value should be specified to ensure correct blending when semi-transparent colors are used.
Returns:
True on success and false otherwise.
bool ShapeDrawingOptions.DrawRectangle ( IntPtr  hdc,
float  x,
float  y,
int  Width,
int  Height,
bool  drawVertices,
int  clipWidth,
int  clipHeight,
uint  BackColor 
)

Draws a rectangle using the stored options on the specified device context.

The method can be used to draw map legend.

Parameters:
hdcThe handle of the device context. Can be obtained with .NET Graphics.GetHDC() method.
xThe x coordinate of the upper left corner of the drawing.
yThe y coordinate of the upper left corner of the drawing.
WidthThe width of the drawing.
HeightThe height of the drawing.
drawVerticesA value which indicates whether or not vertices of the rectangle will be drawn.
clipWidthThe width of the clipping rectangle.
clipHeightThe height of the clipping rectangle.
BackColorThe back color of the device context the drawing is performed at. The value should be specified to ensure correct blending when semi-transparent colors are used.
Returns:
True on success and false otherwise.
bool ShapeDrawingOptions.DrawRectangleVB ( int  hdc,
float  x,
float  y,
int  Width,
int  Height,
bool  drawVertices,
int  clipWidth,
int  clipHeight,
uint  BackColor 
)

Draws a rectangle using the stored options on the specified device context.

The method can be used to draw map legend.

Parameters:
hdcThe handle of the device context. Can be obtained with .NET Graphics.GetHDC() method.
xThe x coordinate of the upper left corner of the drawing.
yThe y coordinate of the upper left corner of the drawing.
WidthThe width of the drawing.
HeightThe height of the drawing.
drawVerticesA value which indicates whether or not vertices of the rectangle will be drawn.
clipWidthThe width of the clipping rectangle.
clipHeightThe height of the clipping rectangle.
BackColorThe back color of the device context the drawing is performed at. The value should be specified to ensure correct blending when semi-transparent colors are used.
Returns:
True on success and false otherwise.
bool ShapeDrawingOptions.DrawShape ( IntPtr  hdc,
float  x,
float  y,
Shape  Shape,
bool  drawVertices,
int  clipWidth,
int  clipHeight,
uint  BackColor 
)

Draws a shape using the stored options on the specified device context.

The method can be used to draw map legend.

Parameters:
hdcThe handle of the device context. Can be obtained with .NET Graphics.GetHDC() method.
xThe x coordinate of the upper left corner of the drawing.
yThe y coordinate of the upper left corner of the drawing.
ShapeA shape to draw. Point, polyline and polygon shapes are supported.
drawVerticesA value which indicates whether or not vertices of the line will be drawn.
clipWidthThe width of the clipping rectangle.
clipHeightThe height of the clipping rectangle.
BackColorThe back color of the device context the drawing is performed at. The value should be specified to ensure correct blending when semi-transparent colors are used.
Returns:
True on success and false otherwise.
bool ShapeDrawingOptions.DrawShapeVB ( int  hdc,
float  x,
float  y,
Shape  Shape,
bool  drawVertices,
int  clipWidth,
int  clipHeight,
uint  BackColor 
)

Draws a shape using the stored options on the specified device context.

The method can be used to draw map legend.

Parameters:
hdcThe handle of the device context.
xThe x coordinate of the upper left corner of the drawing.
yThe y coordinate of the upper left corner of the drawing.
ShapeA shape to draw. Point, polyline and polygon shapes are supported.
drawVerticesA value which indicates whether or not vertices of the line will be drawn.
clipWidthThe width of the clipping rectangle.
clipHeightThe height of the clipping rectangle.
BackColorThe back color of the device context the drawing is performed at. The value should be specified to ensure correct blending when semi-transparent colors are used.
Returns:
True on success and false otherwise.
string ShapeDrawingOptions.get_ErrorMsg ( int  ErrorCode)

Gets the text description of the specified error code.

Parameters:
ErrorCodeThe numeric error code retrieved by ShapeDrawingOptions.LastErrorCode property.
Returns:
The description of the error.

Saves the state of the class to the string.

Returns:
A string with the state or an empty string on failure.

Sets a predefined combination of properties to set the commonly used symbols.

This method changes PointType, PointShape, PointSidesCount, PointRotation and PointSidesRatio properties.

Parameters:
symbolThe predefined symbol to be set.
void ShapeDrawingOptions.SetGradientFill ( uint  Color,
short  range 
)

Provides a convenient way to set colors of the gradient fill.

Parameters:
ColorThe central color of the gradient.
rangeThe range of colors of each channel the gradient covers. The values should be within 0-255.

Property Documentation

Gets or sets a value indicating whether hot spot of icons should be position at the bottom center. When set to false the hotspot will be at the center of icon.

New API 4.9.1:
Added in version 4.9.1

The graphical mode to be used to render symbology.

Gets or sets a value indicating whether the category will be displayed only for scale range specified by MinVisibleScale and MaxVisibleScale properties.

New API 4.9.3:
Added in version 4.9.3

Gets or sets the background color of the polygon fill.

It is used for polygon shapes when hatch fill is chosen.

See also:
FillType

Gets or sets the value which indicates whether a background will be drawn when ShapeDrawingOptions.FillType is set to ftHatch.

Gets or sets the fill color of the shape.

The color is used for point and polygon shapes when ShapeDrawingOptions.FillType is equal to ftSimple or ftHatch, or the gradient starting color is ShapeDrawingOptions.FillType is equal to ftGradient.

Examples:
SelectByDistance.cs, ShapefileToDrawingLayer.cs, and SplitByAttribute.cs.

Gets or sets the end color of the gradient fill.

It is used when ShapeDrawingOptions.FillType is equal to ftGradient.

Examples:
AddCategoryRange.cs.

Gets or sets the the value which defines the bounds of the gradient fill.

The type of the gradient to draw polygon fill of the point symbols and polygon shapes.

See also:
FillType, FillColor, FillColor2.

The hatch style of the fill for point symbols and polygon shapes.

See also:
FillType, FillBgColor, FillBgTransparent.
Examples:
AddCategoryRange.cs.

Gets or sets the angle of rotation of the polygon fill in degrees.

Affects the rotation of gradient and texture fill.

See also:
FillType

Gets or sets the transparency of the fill. Ranges from 0 (transparent) to 255 (opaque).

The type of the polygon fill. See the enumeration for details.

Examples:
AddCategoryRange.cs, and CreateBuffer.cs.

Gets or sets the value which indicates whether the fill is visible.

Affects the drawing of point symbols and polygon shapes.

Examples:
Segmentation.cs.
string ShapeDrawingOptions.FontName [get, set]

The name of the font to use for drawing point symbols when ShapeDrawingOptions.PointType is equal to pstCharacter.

Gets or sets type of frame to be displayed around point when ShapeDrawingOptions.PointShape is set to ptSymbolFontCharacter.

New API 4.9.1:
Added in version 4.9.1

Gets or sets a value indicating whether a frame will be drawn around point when ShapeDrawingOptions.PointShape is set to ptSymbolFontCharacter.

New API 4.9.1:
Added in version 4.9.1

Retrieves the numeric code of the last error that took place in the instance class.

The usage of this property clears the error code.

Gets or sets the line color of the shapes.

Affects the drawing of all shape types.

Examples:
IntersectionLength.cs, MinimalDistance.cs, Segmentation.cs, and ShapefileToDrawingLayer.cs.

Gets or sets line pattern for rendering polyline shapefile.

Examples:
IntersectionLength.cs, LinePattern.cs, and Tracking.cs.

Gets or sets the line style of the shapes.

Affects the drawing of all shape types.

Examples:
Segmentation.cs.

Gets or sets the transparency of lines. Ranges from 0 (transparent) to 255 (opaque).

Gets or sets the value which indicates whether lines will be visible while drawing shapes.

This affects drawing of polylines, as well as the drawing of outline of points symbols and polygons.

Gets or sets the width of the lines to draw shapes.

Examples:
IntersectionLength.cs, MinimalDistance.cs, PointIcons.cs, and Segmentation.cs.

Gets or sets maximum map scale at which the category is visible when ShapeDrawingOptions.DynamicVisibility is set to true.

New API 4.9.3:
Added in version 4.9.3

Gets or sets minimum map scale at which the category is visible when ShapeDrawingOptions.DynamicVisibility is set to true.

New API 4.9.3:
Added in version 4.9.3

Gets or sets the picture which will be used as texture brush (ShapeDrawingOptions.FillType = ftPicture) or point symbol (ShapeDrawingOptions.PointType = ptSymbolPicture).

The property affects the drawing of point symbols and polygons.

Examples:
MarkPoints.cs, and PointIcons.cs.

Gets or sets the coefficient for scaling picture horizontally.

Gets or sets the coefficient for scaling picture vertically.

Get or sets the ANSI code of the text character to use as point symbol.

Gets or sets the rotation of the point symbol in degrees.

Gets or sets the predefined shape for the point symbol.

It is used when ShapeDrawingOptions.PointType is equal to ptSymbolStandard.

Gets or sets the number of sides for some of the predefined symbols such as regular, star or cross.

This value is used when ShapeDrawingOptions.PointType is equal to ptSymbolStandard.

Gets or sets the side ratio for some of the predefined point symbols such as regular, star and cross.

This value is used when ShapeDrawingOptions.PointType is equal to ptSymbolStandard.

Gets or sets the size of the point symbol including predefined symbols, characters and pictures.

Gets or sets the type of the point symbols.

The possible values include predefined symbols, text characters and pictures.

Examples:
MarkPoints.cs, and PointIcons.cs.
string ShapeDrawingOptions.Tag [get, set]

Gets or sets a string associated with the instance of class. Can store any information provided by developer.

Gets or set the value which indicates whether line pattern will be used to render polyline shapefile.

This property won't be set to true unless line pattern with at least one line exists.

Examples:
IntersectionLength.cs, LinePattern.cs, and Tracking.cs.

Gets or sets the color of vertices for the shapes.

See also:
VerticesVisible

Gets or sets the value which indicates whether the fill for shape vertices will be drawn.

See also:
VerticesVisible

Gets or sets the size of the shapes's vertices.

Gets or sets the type of shape vertices.

Gets or sets the value which indicates whether vertices of the shape will be visible. The default values is false.

The visibility of point symbols for point shapefiles is not affected by this property.

bool ShapeDrawingOptions.Visible [get, set]

Gets or sets the values which indicates whether shapes will be visible.

Examples:
PointIcons.cs.
 All Classes Files Functions Enumerations Properties Events