Core Plot (macOS)
Cocoa plotting framework for macOS, iOS, and tvOS
CPTLegend Class Reference

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 <NSKeyValueBindingCreation>
(void) + exposeBinding:
 
- 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 pressed the mouse button. More...
 
(BOOL- pointingDeviceUpEvent:atPoint: [implementation]
 Informs the receiver that the user has released the mouse button. 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 the mouse with the button pressed. More...
 
(BOOL- pointingDeviceCancelledEvent: [implementation]
 Informs the receiver that tracking of mouse moves 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]
 
(BOOL- scrollWheelEvent:fromPoint:toPoint: [implementation]
 
(nonnull 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:
 
- Public Instance Methods inherited from <NSKeyValueBindingCreation>
(NSArray *) - exposedBindings
 
(Class- valueClassForBinding:
 
(void) - bind:toObject:withKeyPath:options:
 
(NSArray *) - optionDescriptionsForBinding:
 
(NSDictionary *) - infoForBinding:
 
(void) - unbind:
 
- Public Instance Methods inherited from <NSCoding>
(id- initWithCoder:
 
(void) - encodeWithCoder:
 
- Public Instance Methods inherited from <CPTResponder>
(BOOL- scrollWheelEvent:fromPoint:toPoint:
 (Required) Informs the receiver that the user has moved the scroll wheel. More...
 

Properties

Formatting
CPTTextStyletextStyle
 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...
 
CPTLineStyleswatchBorderLineStyle
 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...
 
CPTFillswatchFill
 The background fill drawn behind each swatch. If nil (the default), no fill is drawn. More...
 
CPTLineStyleentryBorderLineStyle
 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...
 
CPTFillentryFill
 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
CPTLineStyleborderLineStyle
 The line style for the layer border. More...
 
CPTFillfill
 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
CPTAnnotationArrayannotations
 An array of annotations attached to this layer. More...
 
- Properties inherited from CPTLayer
CPTGraphgraph
 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, NSObjectidentifier
 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...
 
CPTShadowshadow
 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...
 
CPTSublayerSetsublayersExcludedFromAutomaticLayout
 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
 
NSStringfillMode
 
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...
 
CPTNumberArrayrowHeights
 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...
 
CPTNumberArrayrowHeightsThatFit
 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...
 
CPTNumberArraycolumnWidths
 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...
 
CPTNumberArraycolumnWidthsThatFit
 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
plotThe 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:

Parameters
newFrameThe 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
graphA 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
newPlotsAn 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
plotThe plot.
idxAn 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
graphThe 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
newPlotsAn 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
idxAn 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
identifierA 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 pressed the mouse button.

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
eventThe OS event.
interactionPointThe 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 released the mouse button.

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
eventThe OS event.
interactionPointThe 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
plotThe plot to remove.

◆ removePlotWithIdentifier:

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

Remove a plot from the legend.

Parameters
identifierThe 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: