SChartLegend Class Reference

Inherits from UIView
Declared in SChartLegend.h
Availability Standard
Premium
Related samples

Overview

Series data can be displayed in a legend on a ShinobiChart. The SChartLegend is a UIView-based object that represents the legend as a visual item on the chart. The legend may appear in a number of preset positions within the chart.

  • SChartLegendPlacementOutsidePlotArea: Configures the legend to be placed outside of the plot area.
  • SChartLegendPlacementInsidePlotArea: Configures the legend to be placed inside of the plot area.
  • SChartLegendPlacementOnPlotAreaBorder: Configures the legend to be placed on the plot area border.

The placement of the legend inside or outside the plot area has different effects. See the placement property for more information.

Irrespective of how the plot area behaves, we can anchor the legend to several preset positions in the chart area:

  • SChartLegendPositionTopRight: Configures the legend to be anchored in the top right of the chart area.
  • SChartLegendPositionMiddleRight: Configures the legend to be anchored vertically center on the right of the chart area.
  • SChartLegendPositionBottomRight: Configures the legend to be anchored in the bottom right of the chart area.
  • SChartLegendPositionBottomMiddle: Configures the legend to be anchored in the center at the bottom of the chart area.
  • SChartLegendPositionBottomLeft: Configures the legend to be anchored in the bottom left of the chart area.
  • SChartLegendPositionMiddleLeft: Configures the legend to be anchored vertically center on the left of the chart area.
  • SChartLegendPositionTopLeft: Configures the legend to be anchored in the top left of the chart area.
  • SChartLegendPositionTopMiddle: Configures the legend to be anchored in the center at the top of the chart area.

See the position property for more information.

To create a custom legend object, you can subclass SChartLegend and override its drawLegend method. You can then assign the new legend object to [ShinobiChart legend].

Any instance of SChartSeries will adopt the SChartLegendItem protocol, which means that series can also customize how they appear in the legend. SChartLegendItem allows a series to specify the title or symbol which should represent it in the legend. For radial series, it allows the series to specify how each slice should be represented. See the protocol’s API documentation for more information.

More information about using SChartLegend can be found in the user guide, and in our tutorial ‘The making of a legend’.

Tasks

Initialisation

Drawing the legend

Formatting the legend

Styling

Legend items

Properties

autosizeLabels

If this is set to YES, legend labels will autosize to fit their text.

@property (nonatomic, assign) BOOL autosizeLabels

Discussion

Note that the legend frame will still be overridden if the frame is set manually, but this setting will override any value of fixedWidthRatio that has been set on the legend.

By default, this property is set to YES;

Declared In

SChartLegend.h

fixedWidthRatio

Defines a fixed ratio of the width of the overall chart which the legend will take up.

@property (nonatomic, strong, nullable) NSNumber *fixedWidthRatio

Discussion

If this value is not set, the width of the chart will be auto-calculated. By default, this property is set to nil.

Note that if autosizeLabels is set to YES (the default value) then this property will be ignored.

Declared In

SChartLegend.h

labels

The labels which are contained within the legend.

@property (nonatomic, retain) NSMutableArray *labels

Declared In

SChartLegend.h

maxSeriesPerLine

The maximum number of series which are shown per row in horizontal legends.

@property (nonatomic, assign) NSInteger maxSeriesPerLine

Discussion

By default, this property is set to 4;

Declared In

SChartLegend.h

placement

The position of the legend relative to the chart plot area.

@property (nonatomic, assign) SChartLegendPlacement placement

Discussion

The options available are:

  • SChartLegendPlacementOutsidePlotArea: Configures the legend to be placed outside of the plot area.
  • SChartLegendPlacementInsidePlotArea: Configures the legend to be placed inside of the plot area.
  • SChartLegendPlacementOnPlotAreaBorder: Configures the legend to be placed on the plot area border.

If the legend is drawn outside of the plot area, the plot area will shrink to accommodate the legend without obscuring the chart plot. If the legend is drawn inside the plot area, the plot area will expand as though the legend is not there - with the legend displaying over it.

If the legend is drawn on the plot area border, the plot area will shrink to accomodate half of the legend. In this case, the legend will half overlap with the chart, and half be drawn outside the plot area.

Declared In

SChartLegend.h

position

Specifies the positioning of the legend on the chart.

@property (nonatomic, assign) SChartLegendPosition position

Discussion

The options available are:

  • SChartLegendPositionTopRight: Configures the legend to be anchored in the top right of the chart area.
  • SChartLegendPositionMiddleRight: Configures the legend to be anchored vertically center on the right of the chart area.
  • SChartLegendPositionBottomRight: Configures the legend to be anchored in the bottom right of the chart area.
  • SChartLegendPositionBottomMiddle: Configures the legend to be anchored in the center at the bottom of the chart area.
  • SChartLegendPositionBottomLeft: Configures the legend to be anchored in the bottom left of the chart area.
  • SChartLegendPositionMiddleLeft: Configures the legend to be anchored vertically center on the left of the chart area.
  • SChartLegendPositionTopLeft: Configures the legend to be anchored in the top left of the chart area.
  • SChartLegendPositionTopMiddle: Configures the legend to be anchored in the center at the top of the chart area.

Declared In

SChartLegend.h

style

Manages the appearance of the legend.

@property (nonatomic, retain) SChartLegendStyle *style

Declared In

SChartLegend.h

symbolWidth

The width that each symbol in the legend should have, in points.

@property (nonatomic, retain) NSNumber *symbolWidth

Discussion

If this is not set by the user, each symbol will automatically take up half of the width of the legend (with the chart series label/text taking up the other half).

By default, this property is set to 24;

Declared In

SChartLegend.h

symbols

The symbols which are contained within the legend.

@property (nonatomic, retain) NSMutableArray *symbols

Declared In

SChartLegend.h

title

Sets a title for the legend.

@property (nullable, nonatomic, retain) NSString *title

Declared In

SChartLegend.h

Instance Methods

drawLegend

The main function called by the chart to construct the legend.

- (void)drawLegend

Discussion

Override this function to create a custom legend.

Declared In

SChartLegend.h

initWithChart:

Initializes the legend with a reference to the chart.

- (instancetype)initWithChart:(ShinobiChart *)_chart

Parameters

_chart

The chart which will contain the legend.

Return Value

An initialized legend object, or nil if the legend couldn’t be created.

Declared In

SChartLegend.h

reload

Causes the legend to redraw itself. Changes in series styling will not be updated within the legend until this method has been called.

- (void)reload

Declared In

SChartLegend.h