Xceed Chart for WinForms v4.4 Documentation
Welcome to Xceed Chart for WinForms v4.4 / User Guide / Series / XY Scatter Series / Shape Series

In This Topic
    Shape Series
    In This Topic

    Shape charts are created by using an instance of the ShapeSeries object. It is derived from the XYScatterSeries base class and inherits all its functionality. 

    The shape series is a versatile rendering series. For each shape series, the user can specify the style of the shapes (bar, sphere, pyramid, etc.), as well as the X, Y, and Z coordinates of the shape and its size along the X, Y, and Z dimensions. It can be used to display XYZ scatter bubbles, and XY and XYZ scatter bar charts. It can also be used for the rendering of custom (user-defined) charts and composite objects. 

    The following image was rendered with several instances of the shape series. 



    figure 1.

    Creating the Shape Series

    An instance of the ShapeSeries class can be obtained from the SeriesCollection.Add method. The method will add the newly created series to the series collection and return a reference to it. If the user wants to save the reference for further use, it must be explicitly cast to the ShapeSeries type. The following code will create a ShapeSeries object in the series collection and save the returned reference:

    VB.NET  

    ' there is one chart created by default

    Dim chart As Chart = CType(chartControl1.Charts(0), Chart)

     

    ' add a shape series to it

    Dim shape As ShapeSeries = CType(chart.Series.Add(SeriesType.Shape), ShapeSeries)

    C#  
    // there is one chart created by default
    Chart chart = (Chart)chartControl1.Charts[0];
    // add a shape series to it
    ShapeSeries shape = (ShapeSeries)chart.Series.Add(SeriesType.Shape);

    Passing Data to the Shape Series

    Once the shape series is created, you can add data to it. The Shape series uses the Values data series of the Series class for the shape's Y center position and the XValues data series of XYScatterSeries for the shape's X center position. The helper methods provided by the Series and XYScatterSeries classes can be used to insert values in the data series that are to be used. 

    In addition to the standard Values and XValues data series, the bubble series also adds another data series of type Double:

    ZValues
    : Holds the Z-coordinate of the sizes.


    XSizes
    : Holds the size of the shapes in the X-dimension.


    YSizes
    : Holds the size of the shapes in the Y-dimension.


    ZSizes
    : Holds the size of the shapes in the Z-dimension.

    In addition to the standard helper methods for feeding data inherited from the Series class (see the One Value Series Functionality topic) and the XYScatterSeries class (see the XY Scatter Series Functionality topic), the ShapeeSeries implements the following routines. 

    public void AddShape(double y, double x, double z, double xsize, double ysize, double zsize) - Adds a new shape.

    public void AddShape(double y, double x, double z, double xsize, double ysize, double zsize, string label) - Adds a new shape with assigned label.

    public void AddShape(double y, double x, double z, double xsize, double ysize, double zsize, string label, FillEffect pointFE) - Adds a new shape with assigned label and fill effect.

    public void AddShape(double y, double x, double z, double xsize, double ysize, double zsize, string label, FillEffect pointFE, LineProperties pointBorder) - Adds a new shape with assigned label and fill effect and border. 

    For example, you can add data to a simple shape chart with the following code:

    VB.NET  

    shape.AddShape(10, 10, 1, 1, 2, 1)

    shape.AddShape(20, 30, 2, 1, 2, 1)

    shape.AddShape(0, 0, 3, 2, 1, 2)

    C#  
    shape.AddShape(10, 10, 1, 1, 2, 1);
    shape.AddShape(20, 30, 2, 1, 2, 1);
    shape.AddShape(0, 0, 3, 2, 1, 2);

    A labeled shape can be created like this:

    VB.NET  

    shape.AddShape(10, 10, 1, 1, 2, 1, "Shape 1")

    shape.AddShape(20, 30, 2, 1, 2, 1, "Shape 2")

    shape.AddShape(0, 0, 3, 2, 1, 2, "Shape 3")

     

    ' show only the labels in the data labels

    shape.DataLabels.Mode = DataLabelsMode.Every

    shape.DataLabels.Format = "<label>"

    C#  

    shape.AddShape(10, 10, 1, 1, 2, 1, "Shape 1");
    shape.AddShape(20, 30, 2, 1, 2, 1, "Shape 2");
    shape.AddShape(0, 0, 3, 2, 1, 2, "Shape 3");

     

    // show only the labels in the data labels
    shape.DataLabels.Mode = DataLabelsMode.Every;
    shape.DataLabels.Format = "<label>";

    A shape series with different fill effects is also easy to create:

    VB.NET  

    shape.AddShape(10, 10, 1, 1, 2, 1, "Shape 1", New FillEffect(Color.Red))

    shape.AddShape(20, 30, 2, 1, 2, 1, "Shape 2", New FillEffect(Color.Green))

    shape.AddShape(0, 0, 3, 2, 1, 2, "Shape 3", New FillEffect(Color.Blue))

     

    ' show only the labels in the data labels

    shape.DataLabels.Mode = DataLabelsMode.Every

    shape.DataLabels.Format = "<label>"

     

    ' instruct the bubble to use the data point fill effects

    shape.Appearance.FillMode = AppearanceFillMode.DataPoints

    C#  
    shape.AddShape(10, 10, 1, 1, 2, 1, "Shape 1", new FillEffect(Color.Red));
    shape.AddShape(20, 30, 2, 1, 2, 1, "Shape 2", new FillEffect(Color.Green));
    shape.AddShape(0, 0, 3, 2, 1, 2, "Shape 3", new FillEffect(Color.Blue));
    // show only the labels in the data labels
    shape.DataLabels.Mode = DataLabelsMode.Every;
    shape.DataLabels.Format = "<label>";
    // instruct the bubble to use the data point fill effects
    shape.Appearance.FillMode = AppearanceFillMode.DataPoints; 

    Controlling the Shape Style

    The shape of the bubbles can be controlled from the ShapeStyle property. It is of type BarStyle and accepts the following values (for details, see BarStyle Enumeration): 

    Bar
    Cylinder
    Cone
    InvertedCone
    Pyramid
    InvertedPyramid
    Ellipsoid
    SmoothEdgeBar
    CutEdgeBar 
     

    For example, the following code will display the shapes as smooth-edge bars:

    VB.NET  
    shape.ShapeStyle = BarStyle.SmoothEdgeBar
    C#  
    shape.ShapeStyle = BarStyle.SmoothEdgeBar;

    Controlling the Appearance of the Shape

    By default all shapes are displayed with the filling specified by the FillEffect object accessible through the ShapeFillEffect property and the border specified by the LineProperties object accessible through the ShapeBorder property. The following example will display all shapes in green with a blue border.

    VB.NET  

    shape.ShapeFillEffect.SetSolidColor(Color.Green)

    shape.ShapeBorder.Color = Color.Blue

    C#  
    shape.ShapeFillEffect.SetSolidColor(Color.Green);
    shape.ShapeBorder.Color = Color.Blue;

    Please refer to the Series Appearance topic, which describes how to apply individual fillings and lines to the series data points.

    Shape Size Units

    The size of the shape along the X,Y, and Z dimensions can be specified in two ways. By default it is specified in Scale units, which means that the actual size of the shape may decrease if the range scaled by the axes is increased. A common requirement for shapes is to have a size independent of the axis scale; for example, the XYZ scatter Bubble needs to have its sizes specified in this way. 

    The XSizesUnits, YSizesUnits, and ZSizesUnits properties of the ShapeSeries class help you specify the type of units used for shape sizes. They are of type MeasurementUnits, but can only accept the Scale and Model settings.

    Scaling Considerations and the Shape Series

    The UseXValues and UseZValues flags of the ShapeSeries class determine whether the shape series must use the provided X and Z center coordinates or use default ones (0, 1, 2, etc). If you intend to set them to true, make sure that you switch the X and Depth axis to a Value Scale mode (Numeric, Date-Time, or Logarithmic) in order to scale the coordinates correctly.

    VB.NET  

    shape.UserXValues = True

    shape.UserZValues = True

     

    chart.Axis(StandardAxis.PrimaryX).ScaleMode = AxisScaleMode.Numeric

    chart.Axis(StandardAxis.Depth).ScaleMode = AxisScaleMode.Numeric

    C#  

    shape.UserXValues = true;
    shape.UserZValues = true;

     

    chart.Axis(StandardAxis.PrimaryX).ScaleMode = AxisScaleMode.Numeric;
    chart.Axis(StandardAxis.Depth).ScaleMode = AxisScaleMode.Numeric;

    Shape Series Formatting Commands

    The ShapeSeries class extends the formatting command set inherited from the XYScatterSeries base class with the following formatting commands:

    <zvalue> - The current data point zvalue (Z coordinate).
    <xsize> - The current data point x size (size along the X dimension).
    <ysize> - The current data point y size (size along the Y dimension).
    <zsize> - The current data point z size (size along the Z dimension). 

    The following code will display the shape sizes in the legend:

    VB.NET  

    shape.Legend.Mode = SeriesLegendMode.DataPoints

    shape.Legend.Format = "<xsize> <ysize> <zsize>"

    C#  
    shape.Legend.Mode = SeriesLegendMode.DataPoints;
    shape.Legend.Format = "<xsize> <ysize> <zsize>";

    Related Examples

    Windows Forms: Series\Shape\Standard Shape
    Windows Forms: Series\Shape\3D Modeling with shapes

    See Also

    ShapeSeries