Core Plot (iOS)
Cocoa plotting framework for Mac OS X and iOS
CPTLegend Class Reference

A graph legend. More...

#import <CPTLegend.h>

+ Inheritance diagram for CPTLegend:
+ Collaboration diagram for CPTLegend:

Public Class Methods

Factory Methods
(id+ legendWithPlots:
 Creates and returns a new CPTLegend instance with legend entries for each plot in the given array. More...
 
(id+ 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 Instance Methods

(NSMutableArray *) - plots [implementation]
 An array of all plots associated with the legend. More...
 
(NSMutableArray *) - legendEntries [implementation]
 An array of all legend entries. More...
 
Initialization
(id- initWithPlots:
 Initializes a newly allocated CPTLegend object and adds legend entries for each plot in the given array. More...
 
(id- initWithGraph:
 Initializes a newly allocated CPTLegend object and adds legend entries for each plot in the given graph. More...
 
(id- initWithFrame: [implementation]
 Initializes a newly allocated CPTLegend object with the provided frame rectangle. More...
 
Plots
(NSArray *) - allPlots
 All plots associated with the legend. More...
 
(CPTPlot *) - plotAtIndex:
 Gets the plot at the given index in the plot array. More...
 
(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 touched 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- pointingDeviceUpEvent:atPoint: [implementation]
 Informs the receiver that the user has lifted their finger off the screen. 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
(id- 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...
 
(CPTNativeImage *) - imageOfLayer
 Gets an image of the layer contents. 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...
 
(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
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
NSArrayannotations
 An array of annotations attached to this layer. More...
 
- Properties inherited from CPTLayer
__cpt_weak 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...
 
NSSetsublayersExcludedFromAutomaticLayout
 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...
 
NSArrayrowHeights
 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...
 
NSArrayrowHeightsThatFit
 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...
 
NSArraycolumnWidths
 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...
 
NSArraycolumnWidthsThatFit
 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...
 
(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

- (void) addPlot: (CPTPlot *)  plot

Add a plot to the legend.

Parameters
plotThe plot.
- (NSArray *) allPlots

All plots associated with the legend.

Returns
An array of all plots associated with the legend.
- (id) 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.

- (id) initWithGraph: (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.
- (id) initWithPlots: (NSArray *)  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.
- (void) insertPlot: (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.
- (NSMutableArray *) legendEntries
implementation

An array of all legend entries.

+ (id) legendWithGraph: (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.
+ (id) legendWithPlots: (NSArray *)  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.
- (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.
- (NSMutableArray *) plots
implementation

An array of all plots associated with the legend.

- (CPTPlot *) plotWithIdentifier: (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.
- (BOOL) pointingDeviceDownEvent: (CPTNativeEvent *)  event
atPoint: (CGPoint interactionPoint 
implementation

Informs the receiver that the user has touched the screen.

If this legend has a delegate that responds to the -legend:legendEntryForPlot:wasSelectedAtIndex: and/or -legend:legendEntryForPlot:wasSelectedAtIndex: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.

- (void) removePlot: (CPTPlot *)  plot

Remove a plot from the legend.

Parameters
plotThe plot to remove.
- (void) removePlotWithIdentifier: (id<NSCopying>)  identifier

Remove a plot from the legend.

Parameters
identifierThe identifier of the plot to remove.
- (void) setLayoutChanged

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

Property Documentation

- (CGFloat) columnMargin
readwritenonatomicassign

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

- (NSArray *) 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.

- (NSArray *) columnWidthsThatFit
readnonatomicretain

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).

- (CPTLineStyle *) entryBorderLineStyle
readwritenonatomiccopy

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

- (CPTFill *) entryFill
readwritenonatomiccopy

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

- (CGFloat) entryPaddingBottom
readwritenonatomicassign

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

- (CGFloat) entryPaddingLeft
readwritenonatomicassign

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

- (CGFloat) entryPaddingRight
readwritenonatomicassign

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

- (CGFloat) entryPaddingTop
readwritenonatomicassign

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

- (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.

- (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.

- (BOOL) layoutChanged
readnonatomicassign

If YES, the legend layout needs to recalculated.

- (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.

- (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.

- (NSArray *) 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.

- (NSArray *) rowHeightsThatFit
readnonatomicretain

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).

- (CGFloat) rowMargin
readwritenonatomicassign

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

- (CPTLineStyle *) swatchBorderLineStyle
readwritenonatomiccopy

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

- (CPTFill *) swatchFill
readwritenonatomiccopy

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

- (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.

- (CPTTextStyle *) textStyle
readwritenonatomiccopy

The text style used to draw all legend entry titles.

- (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: