A graph legend. More...

#import <CPTLegend.h>

Inheritance diagram for CPTLegend:

Collaboration diagram for CPTLegend:

Public Class Methods
Factory Methods
(nonnull instancetype)	+ legendWithPlots:
	Creates and returns a new CPTLegend instance with legend entries for each plot in the given array. More...

(nonnull instancetype)	+ legendWithGraph:
	Creates and returns a new CPTLegend instance with legend entries for each plot in the given graph. More...

Public Class Methods inherited from CALayer
(id)	+ layer

Public Class Methods inherited from NSObject
(id)	+ alloc

(Class)	+ class

(void)	+ initialize

(void)	+ load

(id)	+ new

Public Class Methods inherited from <NSSecureCoding>
(BOOL)	+ supportsSecureCoding:

Public Instance Methods
Initialization
(nonnull instancetype)	- initWithPlots:
	Initializes a newly allocated CPTLegend object and adds legend entries for each plot in the given array. More...

(nonnull instancetype)	- initWithGraph:
	Initializes a newly allocated CPTLegend object and adds legend entries for each plot in the given graph. More...

(nonnull instancetype)	- initWithFrame: `[implementation]`
	Initializes a newly allocated CPTLegend object with the provided frame rectangle. More...

Plots
(nonnull CPTPlotArray *)	- allPlots
	All plots associated with the legend. More...

(nullable CPTPlot *)	- plotAtIndex:
	Gets the plot at the given index in the plot array. More...

(nullable CPTPlot *)	- plotWithIdentifier:
	Gets the plot with the given identifier from the plot array. More...

(void)	- addPlot:
	Add a plot to the legend. More...

(void)	- insertPlot:atIndex:
	Add a plot to the legend at the given index in the plot array. More...

(void)	- removePlot:
	Remove a plot from the legend. More...

(void)	- removePlotWithIdentifier:
	Remove a plot from the legend. More...

User Interaction
(BOOL)	- pointingDeviceDownEvent:atPoint: `[implementation]`
	Informs the receiver that the user has started touching the screen. More...

(BOOL)	- pointingDeviceUpEvent:atPoint: `[implementation]`
	Informs the receiver that the user has ended touching the screen. More...

Public Instance Methods inherited from CPTBorderedLayer
(void)	- renderBorderedLayerAsVectorInContext:
	Draws the fill and border of a CPTBorderedLayer into the given graphics context. More...

(void)	- sublayerMarginLeft:top:right:bottom: `[implementation]`
	Increases the sublayer margin on all four sides by half the width of the border line style. More...

Public Instance Methods inherited from CPTAnnotationHostLayer
(void)	- addAnnotation:
	Adds an annotation to the receiver. More...

(void)	- removeAnnotation:
	Removes an annotation from the receiver. More...

(void)	- removeAllAnnotations
	Removes all annotations from the receiver. More...

(BOOL)	- pointingDeviceDraggedEvent:atPoint: `[implementation]`
	Informs the receiver that the user has moved their finger while touching the screen. More...

(BOOL)	- pointingDeviceCancelledEvent: `[implementation]`
	Informs the receiver that tracking of touches has been cancelled for any reason. More...

Public Instance Methods inherited from CPTLayer
(nullable instancetype)	- initWithCoder:
	Returns an object initialized from data in a given unarchiver. More...

(nonnull instancetype)	- initWithLayer:
	Override to copy or initialize custom fields of the specified layer. More...

(nonnull instancetype)	- init `[implementation]`
	Initializes a newly allocated CPTLayer object with an empty frame rectangle. More...

(void)	- logLayers
	Logs this layer and all of its sublayers. More...

(BOOL)	- pointingDeviceDownEvent:atPoint: `[implementation]`

(BOOL)	- pointingDeviceUpEvent:atPoint: `[implementation]`

(BOOL)	- pointingDeviceDraggedEvent:atPoint: `[implementation]`

(BOOL)	- pointingDeviceCancelledEvent: `[implementation]`

(nullable CPTNativeImage *)	- imageOfLayer
	Gets an image of the layer contents. More...

(void)	- setNeedsDisplayAllLayers
	Recursively marks this layer and all sublayers as needing to be redrawn. More...

(void)	- renderAsVectorInContext:
	Draws layer content into the provided graphics context. More...

(void)	- recursivelyRenderInContext:
	Draws layer content and the content of all sublayers into the provided graphics context. More...

(void)	- layoutAndRenderInContext:
	Updates the layer layout if needed and then draws layer content and the content of all sublayers into the provided graphics context. More...

(nonnull NSData *)	- dataForPDFRepresentationOfLayer
	Draws layer content and the content of all sublayers into a PDF document. More...

(void)	- applySublayerMaskToContext:forSublayer:withOffset:
	Recursively sets the clipping path of the given graphics context to the sublayer masking paths of its superlayers. More...

(void)	- applyMaskToContext:
	Sets the clipping path of the given graphics context to mask the content. More...

(void)	- pixelAlign
	Align the receiver’s position with pixel boundaries. More...

(void)	- layoutSublayers `[implementation]`
	Updates the layout of all sublayers. Sublayers fill the super layer’s bounds minus any padding. More...

Public Instance Methods inherited from CALayer
(BOOL)	- containsPoint:

(void)	- drawInContext:

(id)	- init

(id)	- initWithLayer

(void)	- layoutSublayers

(void)	- setNeedsDisplay

(void)	- setNeedsDisplayInRect:

(void)	- setNeedsLayout

Public Instance Methods inherited from NSObject
(Class)	- classForCoder

(id)	- copy

(void)	- dealloc

(void)	- finalize

(id)	- init

(id)	- mutableCopy

Public Instance Methods inherited from <NSObject>
(NSString *)	- description

(NSUInteger)	- hash

(BOOL)	- isEqual:

User Interaction

Properties
Formatting
CPTTextStyle *	textStyle
	The text style used to draw all legend entry titles. More...

CGSize	swatchSize
	The size of the graphical swatch. If swatchSize is (`0.0`, `0.0`), swatches will be drawn using a square `150%` of the text size on a side. More...

CPTLineStyle *	swatchBorderLineStyle
	The line style for the border drawn around each swatch. If nil (the default), no border is drawn. More...

CGFloat	swatchCornerRadius
	The corner radius for each swatch. Default is `0.0`. More...

CPTFill *	swatchFill
	The background fill drawn behind each swatch. If nil (the default), no fill is drawn. More...

CPTLineStyle *	entryBorderLineStyle
	The line style for the border drawn around each legend entry. If nil (the default), no border is drawn. More...

CGFloat	entryCornerRadius
	The corner radius for the border around each legend entry. Default is `0.0`. More...

CPTFill *	entryFill
	The background fill drawn behind each legend entry. If nil (the default), no fill is drawn. More...

CGFloat	entryPaddingLeft
	Amount to inset the swatch and title from the left side of the legend entry. More...

CGFloat	entryPaddingTop
	Amount to inset the swatch and title from the top of the legend entry. More...

CGFloat	entryPaddingRight
	Amount to inset the swatch and title from the right side of the legend entry. More...

CGFloat	entryPaddingBottom
	Amount to inset the swatch and title from the bottom of the legend entry. More...

Properties inherited from CPTBorderedLayer
CPTLineStyle *	borderLineStyle
	The line style for the layer border. More...

CPTFill *	fill
	The fill for the layer background. More...

BOOL	inLayout
	Set to YES when changing the layout of this layer. Otherwise, if masking the border, all layout property changes will be passed to the superlayer. More...

Properties inherited from CPTAnnotationHostLayer
CPTAnnotationArray *	annotations
	An array of annotations attached to this layer. More...

Properties inherited from CPTLayer
CPTGraph *	graph
	The graph for the layer. More...

CGFloat	paddingLeft
	Amount to inset the left side of each sublayer. More...

CGFloat	paddingTop
	Amount to inset the top of each sublayer. More...

CGFloat	paddingRight
	Amount to inset the right side of each sublayer. More...

CGFloat	paddingBottom
	Amount to inset the bottom of each sublayer. More...

id< NSCopying, NSCoding, NSObject >	identifier
	An object used to identify the layer in collections. More...

CGFloat	contentsScale
	The scale factor applied to the layer. More...

BOOL	useFastRendering
	If YES, subclasses should optimize their drawing for speed over precision. More...

CPTShadow *	shadow
	The shadow drawn under the layer content. If nil (the default), no shadow is drawn. More...

CGSize	shadowMargin
	The maximum margin size needed to fully enclose the layer shadow. More...

BOOL	masksToBorder
	If YES, a sublayer mask is applied to clip sublayer content to the inside of the border. More...

CGPathRef	outerBorderPath
	A drawing path that encompasses the outer boundary of the layer border. More...

CGPathRef	innerBorderPath
	A drawing path that encompasses the inner boundary of the layer border. More...

CGPathRef	maskingPath
	A drawing path that encompasses the layer content including any borders. Set to `NULL` when no masking is desired. More...

CGPathRef	sublayerMaskingPath
	A drawing path that encompasses the layer content excluding any borders. Set to `NULL` when no masking is desired. More...

CPTSublayerSet *	sublayersExcludedFromAutomaticLayout
	A set of sublayers that should be excluded from the automatic sublayer layout. More...

Properties inherited from CALayer
CGPoint	anchorPoint

CGRect	bounds

CGFloat	contentsScale

CGFloat	cornerRadius

id	delegate

CGRect	frame

BOOL	masksToBounds

BOOL	needsDisplayOnBoundsChange

BOOL	opacity

BOOL	opaque

Properties inherited from <CAMediaTiming>
BOOL	autoreverses

CFTimeInterval	beginTime

CFTimeInterval	duration

NSString *	fillMode

float	repeatCount

id	repeatDuration

float	speed

CFTimeInterval	timeOffset

Layout
BOOL	layoutChanged
	If YES, the legend layout needs to recalculated. More...

NSUInteger	numberOfRows
	The desired number of rows of legend entries. If zero (`0`) (the default), the number of rows will be automatically determined. If both numberOfRows and numberOfColumns are greater than zero but their product is less than the total number of legend entries, some entries will not be shown. More...

NSUInteger	numberOfColumns
	The desired number of columns of legend entries. If zero (`0`) (the default), the number of columns will be automatically determined. If both numberOfRows and numberOfColumns are greater than zero but their product is less than the total number of legend entries, some entries will not be shown. More...

BOOL	equalRows
	If YES (the default) each row of legend entries will have the same height, otherwise rows will be sized to best fit the entries. More...

BOOL	equalColumns
	If YES each column of legend entries will have the same width, otherwise columns will be sized to best fit the entries. Default is NO, meaning columns will be sized for the best fit. More...

CPTNumberArray *	rowHeights
	The desired height of each row of legend entries, including the swatch and title. Each element in this array should be an NSNumber representing the height of the corresponding row in device units. Rows are numbered from top to bottom starting from zero (`0`). If nil, all rows will be sized automatically. If there are more rows in the legend than specified in this array, the remaining rows will be sized automatically. Default is nil. More...

CPTNumberArray *	rowHeightsThatFit
	The computed best-fit height of each row of legend entries, including the swatch and title. Each element in this array is an NSNumber representing the height of the corresponding row in device units. Rows are numbered from top to bottom starting from zero (`0`). More...

CPTNumberArray *	columnWidths
	The desired width of each column of legend entries, including the swatch, title, and title offset. Each element in this array should be an NSNumber representing the width of the corresponding column in device units. Columns are numbered from left to right starting from zero (`0`). If nil, all columns will be sized automatically. If there are more columns in the legend than specified in this array, the remaining columns will be sized automatically. Default is nil. More...

CPTNumberArray *	columnWidthsThatFit
	The computed best-fit width of each column of legend entries, including the swatch, title, and title offset. Each element in this array is an NSNumber representing the width of the corresponding column in device units. Columns are numbered from left to right starting from zero (`0`). More...

CGFloat	columnMargin
	The margin between columns, specified in device units. Default is `10.0`. More...

CGFloat	rowMargin
	The margin between rows, specified in device units. Default is `5.0`. More...

CGFloat	titleOffset
	The distance between each swatch and its title, specified in device units. Default is `5.0`. More...

CPTLegendSwatchLayout	swatchLayout
	Where to draw the legend swatch relative to the title. Default is CPTLegendSwatchLayoutLeft. More...

(void)	- setLayoutChanged
	Marks the receiver as needing to update the layout of its legend entries. More...

Detailed Description

A graph legend.

The legend consists of one or more legend entries associated with plots. Each legend entry is made up of a graphical “swatch” that corresponds with the plot and a text title or label to identify the data series to the viewer. The swatches provide a visual connection to the plot. For instance, a swatch for a scatter plot might include a line segment drawn in the line style of the plot along with a plot symbol while a swatch for a pie chart might only show a rectangle or other shape filled with the background fill of the corresponding pie slice.

The plots are not required to belong to the same graph, although that is the usual case. This allows creation of a master legend that covers multiple graphs.

See also: See Legends for a list of animatable properties.

Method Documentation

◆ addPlot:

- (void) addPlot: (nonnull CPTPlot *) plot

Add a plot to the legend.

Parameters

plot The plot.

◆ allPlots

- (nonnull CPTPlotArray *) allPlots

All plots associated with the legend.

Returns: An array of all plots associated with the legend.

◆ initWithFrame:

- (nonnull instancetype) initWithFrame: (CGRect) newFrame

implementation

Initializes a newly allocated CPTLegend object with the provided frame rectangle.

This is the designated initializer. The initialized layer will have the following properties:

layoutChanged = YES
textStyle = default text style
swatchSize = (0.0, 0.0)
swatchBorderLineStyle = nil
swatchCornerRadius = 0
swatchFill = nil
entryBorderLineStyle = nil
entryCornerRadius = 0
entryFill = nil
entryPaddingLeft = 0
entryPaddingTop = 0
entryPaddingRight = 0
entryPaddingBottom = 0
numberOfRows = 0
numberOfColumns = 0
equalRows = YES
equalColumns = NO
rowHeights = nil
rowHeightsThatFit = nil
columnWidths = nil
columnWidthsThatFit = nil
columnMargin = 10.0
rowMargin = 5.0
titleOffset = 5.0
swatchLayout = CPTLegendSwatchLayoutLeft
paddingLeft = 5.0
paddingTop = 5.0
paddingRight = 5.0
paddingBottom = 5.0
needsDisplayOnBoundsChange = YES

Parameters

newFrame The frame rectangle.

Returns: The initialized CPTLegend object.

Reimplemented from CPTBorderedLayer.

◆ initWithGraph:

- (nonnull instancetype) initWithGraph: (nullable __kindof CPTGraph *) graph

Initializes a newly allocated CPTLegend object and adds legend entries for each plot in the given graph.

Parameters

graph A graph.

Returns: The initialized CPTLegend object.

◆ initWithPlots:

- (nonnull instancetype) initWithPlots: (nullable CPTPlotArray *) newPlots

Initializes a newly allocated CPTLegend object and adds legend entries for each plot in the given array.

Parameters

newPlots An array of plots.

Returns: The initialized CPTLegend object.

◆ insertPlot:atIndex:

- (void) insertPlot:	(nonnull CPTPlot *)	plot
atIndex:	(NSUInteger)	idx

Add a plot to the legend at the given index in the plot array.

Parameters

plot	The plot.
idx	An index within the bounds of the plot array.

◆ legendWithGraph:

+ (nonnull instancetype) legendWithGraph: (nullable __kindof CPTGraph *) graph

Creates and returns a new CPTLegend instance with legend entries for each plot in the given graph.

Parameters

graph The graph.

Returns: A new CPTLegend instance.

◆ legendWithPlots:

+ (nonnull instancetype) legendWithPlots: (nullable CPTPlotArray *) newPlots

Creates and returns a new CPTLegend instance with legend entries for each plot in the given array.

Parameters

newPlots An array of plots.

Returns: A new CPTLegend instance.

◆ plotAtIndex:

- (nullable CPTPlot *) plotAtIndex: (NSUInteger) idx

Gets the plot at the given index in the plot array.

Parameters

idx	An index within the bounds of the plot array.

Returns: The plot at the given index.

◆ plotWithIdentifier:

- (nullable CPTPlot *) plotWithIdentifier: (nullable id<NSCopying>) identifier

Gets the plot with the given identifier from the plot array.

Parameters

identifier A plot identifier.

Returns: The plot with the given identifier or nil if it was not found.

◆ pointingDeviceDownEvent:atPoint:

- (BOOL) pointingDeviceDownEvent:	(nonnull CPTNativeEvent *)	event
atPoint:	(CGPoint)	interactionPoint

implementation

Informs the receiver that the user has started touching the screen.

If this legend has a delegate that responds to the -legend:legendEntryForPlot:touchDownAtIndex: or -legend:legendEntryForPlot:touchDownAtIndex:withEvent: methods, the legend entries are searched to find the plot and index of the one whose swatch or title contains the interactionPoint. The delegate method will be called and this method returns YES if the interactionPoint is within a legend entry. This method returns NO if the interactionPoint is too far away from all of the legend entries.

Parameters

event	The OS event.
interactionPoint	The coordinates of the interaction.

Returns: Whether the event was handled or not.

Reimplemented from CPTAnnotationHostLayer.

◆ pointingDeviceUpEvent:atPoint:

- (BOOL) pointingDeviceUpEvent:	(nonnull CPTNativeEvent *)	event
atPoint:	(CGPoint)	interactionPoint

implementation

Informs the receiver that the user has ended touching the screen.

If this legend has a delegate that responds to the -legend:legendEntryForPlot:touchUpAtIndex: or -legend:legendEntryForPlot:touchUpAtIndex:withEvent: methods, the legend entries are searched to find the plot and index of the one whose swatch or title contains the interactionPoint. The delegate method will be called and this method returns YES if the interactionPoint is within a legend entry. This method returns NO if the interactionPoint is too far away from all of the legend entries.

If the bar being released is the same as the one that was pressed (see -pointingDeviceDownEvent:atPoint: ), if the delegate responds to the -legend:legendEntryForPlot:wasSelectedAtIndex: and/or -legend:legendEntryForPlot:wasSelectedAtIndex:withEvent: methods, these will be called.

Parameters

event	The OS event.
interactionPoint	The coordinates of the interaction.

Returns: Whether the event was handled or not.

Reimplemented from CPTAnnotationHostLayer.

◆ removePlot:

- (void) removePlot: (nonnull CPTPlot *) plot

Remove a plot from the legend.

Parameters

plot	The plot to remove.

◆ removePlotWithIdentifier:

- (void) removePlotWithIdentifier: (nullable id<NSCopying>) identifier

Remove a plot from the legend.

Parameters

identifier The identifier of the plot to remove.

◆ setLayoutChanged

- (void) setLayoutChanged

Marks the receiver as needing to update the layout of its legend entries.

Property Documentation

◆ columnMargin

- (CGFloat) columnMargin

readwritenonatomicassign

The margin between columns, specified in device units. Default is 10.0.

◆ columnWidths

- (nullable CPTNumberArray *) columnWidths

readwritenonatomiccopy

The desired width of each column of legend entries, including the swatch, title, and title offset. Each element in this array should be an NSNumber representing the width of the corresponding column in device units. Columns are numbered from left to right starting from zero (0). If nil, all columns will be sized automatically. If there are more columns in the legend than specified in this array, the remaining columns will be sized automatically. Default is nil.

◆ columnWidthsThatFit

- (nullable CPTNumberArray *) columnWidthsThatFit

readnonatomicassign

The computed best-fit width of each column of legend entries, including the swatch, title, and title offset. Each element in this array is an NSNumber representing the width of the corresponding column in device units. Columns are numbered from left to right starting from zero (0).

◆ entryBorderLineStyle

- (nullable CPTLineStyle *) entryBorderLineStyle

readwritenonatomiccopy

The line style for the border drawn around each legend entry. If nil (the default), no border is drawn.

◆ entryFill

- (nullable CPTFill *) entryFill

readwritenonatomiccopy

The background fill drawn behind each legend entry. If nil (the default), no fill is drawn.

◆ entryPaddingBottom

- (CGFloat) entryPaddingBottom

readwritenonatomicassign

Amount to inset the swatch and title from the bottom of the legend entry.

◆ entryPaddingLeft

- (CGFloat) entryPaddingLeft

readwritenonatomicassign

Amount to inset the swatch and title from the left side of the legend entry.

◆ entryPaddingRight

- (CGFloat) entryPaddingRight

readwritenonatomicassign

Amount to inset the swatch and title from the right side of the legend entry.

◆ entryPaddingTop

- (CGFloat) entryPaddingTop

readwritenonatomicassign

Amount to inset the swatch and title from the top of the legend entry.

◆ equalColumns

- (BOOL) equalColumns

readwritenonatomicassign

If YES each column of legend entries will have the same width, otherwise columns will be sized to best fit the entries. Default is NO, meaning columns will be sized for the best fit.

◆ equalRows

- (BOOL) equalRows

readwritenonatomicassign

If YES (the default) each row of legend entries will have the same height, otherwise rows will be sized to best fit the entries.

◆ layoutChanged

- (BOOL) layoutChanged

readnonatomicassign

If YES, the legend layout needs to recalculated.

◆ numberOfColumns

- (NSUInteger) numberOfColumns

readwritenonatomicassign

The desired number of columns of legend entries. If zero (0) (the default), the number of columns will be automatically determined. If both numberOfRows and numberOfColumns are greater than zero but their product is less than the total number of legend entries, some entries will not be shown.

◆ numberOfRows

- (NSUInteger) numberOfRows

readwritenonatomicassign

The desired number of rows of legend entries. If zero (0) (the default), the number of rows will be automatically determined. If both numberOfRows and numberOfColumns are greater than zero but their product is less than the total number of legend entries, some entries will not be shown.

◆ rowHeights

- (nullable CPTNumberArray *) rowHeights

readwritenonatomiccopy

The desired height of each row of legend entries, including the swatch and title. Each element in this array should be an NSNumber representing the height of the corresponding row in device units. Rows are numbered from top to bottom starting from zero (0). If nil, all rows will be sized automatically. If there are more rows in the legend than specified in this array, the remaining rows will be sized automatically. Default is nil.

◆ rowHeightsThatFit

- (nullable CPTNumberArray *) rowHeightsThatFit

readnonatomicassign

The computed best-fit height of each row of legend entries, including the swatch and title. Each element in this array is an NSNumber representing the height of the corresponding row in device units. Rows are numbered from top to bottom starting from zero (0).

◆ rowMargin

- (CGFloat) rowMargin

readwritenonatomicassign

The margin between rows, specified in device units. Default is 5.0.

◆ swatchBorderLineStyle

- (nullable CPTLineStyle *) swatchBorderLineStyle

readwritenonatomiccopy

The line style for the border drawn around each swatch. If nil (the default), no border is drawn.

◆ swatchFill

- (nullable CPTFill *) swatchFill

readwritenonatomiccopy

The background fill drawn behind each swatch. If nil (the default), no fill is drawn.

◆ swatchLayout

- (CPTLegendSwatchLayout) swatchLayout

readwritenonatomicassign

Where to draw the legend swatch relative to the title. Default is CPTLegendSwatchLayoutLeft.

◆ swatchSize

- (CGSize) swatchSize

readwritenonatomicassign

The size of the graphical swatch. If swatchSize is (0.0, 0.0), swatches will be drawn using a square 150% of the text size on a side.

◆ textStyle

- (nullable CPTTextStyle *) textStyle

readwritenonatomiccopy

The text style used to draw all legend entry titles.

◆ titleOffset

- (CGFloat) titleOffset

readwritenonatomicassign

The distance between each swatch and its title, specified in device units. Default is 5.0.

The documentation for this class was generated from the following files:

Source/CPTLegend.h
Source/CPTLegend.m

Public Class Methods

Public Instance Methods

Properties

Layout

Detailed Description

Method Documentation

◆ addPlot:

◆ allPlots

◆ initWithFrame:

◆ initWithGraph:

◆ initWithPlots:

◆ insertPlot:atIndex:

◆ legendWithGraph:

◆ legendWithPlots:

◆ plotAtIndex:

◆ plotWithIdentifier:

◆ pointingDeviceDownEvent:atPoint:

◆ pointingDeviceUpEvent:atPoint:

◆ removePlot:

◆ removePlotWithIdentifier:

◆ setLayoutChanged

Property Documentation

◆ columnMargin

◆ columnWidths

◆ columnWidthsThatFit

◆ entryBorderLineStyle

◆ entryFill

◆ entryPaddingBottom

◆ entryPaddingLeft

◆ entryPaddingRight

◆ entryPaddingTop

◆ equalColumns

◆ equalRows

◆ layoutChanged

◆ numberOfColumns

◆ numberOfRows

◆ rowHeights

◆ rowHeightsThatFit

◆ rowMargin

◆ swatchBorderLineStyle

◆ swatchFill

◆ swatchLayout

◆ swatchSize

◆ textStyle

◆ titleOffset