Main Page · Class Overview · Hierarchy · All Classes
Public Types | Public Functions | Signals | Protected Functions
QCPLegend Class Reference

Manages a legend inside a QCustomPlot. More...

Inheritance diagram for QCPLegend:
Inheritance graph

Public Types

enum  PositionStyle
enum  SelectablePart

Public Functions

 QCPLegend (QCustomPlot *parentPlot)
QPen borderPen () const
QBrush brush () const
QFont font () const
QColor textColor () const
PositionStyle positionStyle () const
QPoint position () const
bool autoSize () const
QSize size () const
QSize minimumSize () const
int paddingLeft () const
int paddingRight () const
int paddingTop () const
int paddingBottom () const
int marginLeft () const
int marginRight () const
int marginTop () const
int marginBottom () const
int itemSpacing () const
QSize iconSize () const
int iconTextPadding () const
QPen iconBorderPen () const
SelectableParts selectable () const
SelectableParts selected () const
QPen selectedBorderPen () const
QPen selectedIconBorderPen () const
QBrush selectedBrush () const
QFont selectedFont () const
QColor selectedTextColor () const
void setBorderPen (const QPen &pen)
void setBrush (const QBrush &brush)
void setFont (const QFont &font)
void setTextColor (const QColor &color)
void setPositionStyle (PositionStyle legendPositionStyle)
void setPosition (const QPoint &pixelPosition)
void setAutoSize (bool on)
void setSize (const QSize &size)
void setSize (int width, int height)
void setMinimumSize (const QSize &size)
void setMinimumSize (int width, int height)
void setPaddingLeft (int padding)
void setPaddingRight (int padding)
void setPaddingTop (int padding)
void setPaddingBottom (int padding)
void setPadding (int left, int right, int top, int bottom)
void setMarginLeft (int margin)
void setMarginRight (int margin)
void setMarginTop (int margin)
void setMarginBottom (int margin)
void setMargin (int left, int right, int top, int bottom)
void setItemSpacing (int spacing)
void setIconSize (const QSize &size)
void setIconSize (int width, int height)
void setIconTextPadding (int padding)
void setIconBorderPen (const QPen &pen)
void setSelectable (const SelectableParts &selectable)
void setSelected (const SelectableParts &selected)
void setSelectedBorderPen (const QPen &pen)
void setSelectedIconBorderPen (const QPen &pen)
void setSelectedBrush (const QBrush &brush)
void setSelectedFont (const QFont &font)
void setSelectedTextColor (const QColor &color)
QCPAbstractLegendItemitem (int index) const
QCPPlottableLegendItemitemWithPlottable (const QCPAbstractPlottable *plottable) const
int itemCount () const
bool hasItem (QCPAbstractLegendItem *item) const
bool hasItemWithPlottable (const QCPAbstractPlottable *plottable) const
bool addItem (QCPAbstractLegendItem *item)
bool removeItem (int index)
bool removeItem (QCPAbstractLegendItem *item)
void clearItems ()
QList< QCPAbstractLegendItem * > selectedItems () const
void reArrange ()
bool selectTestLegend (const QPointF &pos) const
QCPAbstractLegendItemselectTestItem (const QPoint pos) const
bool visible () const
QCustomPlotparentPlot () const
QCPLayerlayer () const
bool antialiased () const
void setVisible (bool on)
bool setLayer (QCPLayer *layer)
bool setLayer (const QString &layerName)
void setAntialiased (bool enabled)

Signals

void selectionChanged (QCPLegend::SelectableParts selection)

Protected Functions

virtual void updateSelectionState ()
virtual bool handleLegendSelection (QMouseEvent *event, bool additiveSelection, bool &modified)
virtual void applyDefaultAntialiasingHint (QCPPainter *painter) const
virtual void draw (QCPPainter *painter)
virtual void calculateAutoSize ()
virtual void calculateAutoPosition ()
QPen getBorderPen () const
QBrush getBrush () const
bool moveToLayer (QCPLayer *layer, bool prepend)
void applyAntialiasingHint (QCPPainter *painter, bool localAntialiased, QCP::AntialiasedElement overrideElement) const
virtual QRect clipRect () const

Detailed Description

Manages a legend inside a QCustomPlot.

Doesn't need to be instantiated externally, rather access QCustomPlot::legend


Member Enumeration Documentation

Defines where the legend is positioned inside the QCustomPlot axis rect.

Enumerator:
psManual 

Position is not changed automatically. Set manually via setPosition.

psTopLeft 

Legend is positioned in the top left corner of the axis rect with distance to the border corresponding to the currently set top and left margins.

psTop 

Legend is horizontally centered at the top of the axis rect with distance to the border corresponding to the currently set top margin.

psTopRight 

Legend is positioned in the top right corner of the axis rect with distance to the border corresponding to the currently set top and right margins.

psRight 

Legend is vertically centered at the right of the axis rect with distance to the border corresponding to the currently set right margin.

psBottomRight 

Legend is positioned in the bottom right corner of the axis rect with distance to the border corresponding to the currently set bottom and right margins.

psBottom 

Legend is horizontally centered at the bottom of the axis rect with distance to the border corresponding to the currently set bottom margin.

psBottomLeft 

Legend is positioned in the bottom left corner of the axis rect with distance to the border corresponding to the currently set bottom and left margins.

psLeft 

Legend is vertically centered at the left of the axis rect with distance to the border corresponding to the currently set left margin.

Defines the selectable parts of a legend

Enumerator:
spNone 

None.

spLegendBox 

The legend box (frame)

spItems 

Legend items individually (see selectedItems)


Constructor & Destructor Documentation

QCPLegend::QCPLegend ( QCustomPlot parentPlot) [explicit]

Constructs a new QCPLegend instance with parentPlot as the containing plot and default values. Under normal usage, QCPLegend needn't be instantiated outside of QCustomPlot. Access QCustomPlot::legend to modify the legend (set to invisible by default, see setVisible).


Member Function Documentation

void QCPLegend::setBorderPen ( const QPen &  pen)

Sets the pen, the border of the entire legend is drawn with.

void QCPLegend::setBrush ( const QBrush &  brush)

Sets the brush of the legend background.

void QCPLegend::setFont ( const QFont &  font)

Sets the default font of legend text. Legend items that draw text (e.g. the name of a graph) will use this font by default. However, a different font can be specified on a per-item-basis by accessing the specific legend item.

This function will also set font on all already existing legend items.

See also:
QCPAbstractLegendItem::setFont
void QCPLegend::setTextColor ( const QColor &  color)

Sets the default color of legend text. Legend items that draw text (e.g. the name of a graph) will use this color by default. However, a different colors can be specified on a per-item-basis by accessing the specific legend item.

This function will also set color on all already existing legend items.

See also:
QCPAbstractLegendItem::setTextColor
void QCPLegend::setPositionStyle ( PositionStyle  legendPositionStyle)

Sets the position style of the legend. If the legendPositionStyle is not psManual, the position is found automatically depending on the specific legendPositionStyle and the legend margins. If legendPositionStyle is psManual, the exact pixel position of the legend must be specified via setPosition. Margins have no effect in that case.

See also:
setMargin
void QCPLegend::setPosition ( const QPoint &  pixelPosition)

Sets the exact pixel Position of the legend inside the QCustomPlot widget, if setPositionStyle is set to psManual. Margins have no effect in that case.

void QCPLegend::setAutoSize ( bool  on)

Sets whether the size of the legend should be calculated automatically to fit all the content (plus padding), or whether the size must be specified manually with setSize.

If the autoSize mechanism is enabled, the legend will have the smallest possible size to still display all its content. For items with text wrapping (QCPPlottableLegendItem::setTextWrap) this means, they would become very compressed, i.e. wrapped at every word. To prevent this, set a reasonable setMinimumSize width.

void QCPLegend::setSize ( const QSize &  size)

Sets the size of the legend. Setting the size manually with this function only has an effect, if setAutoSize is set to false.

If you want to control the minimum size (or the text-wrapping width) while still leaving the autoSize mechanism enabled, consider using setMinimumSize.

See also:
setAutoSize, setMinimumSize
void QCPLegend::setSize ( int  width,
int  height 
)

This is an overloaded function.

void QCPLegend::setMinimumSize ( const QSize &  size)

Sets the minimum size of the legend when setAutoSize is enabled.

If text wrapping is enabled in the legend items (e.g. QCPPlottableLegendItem::setTextWrap), this minimum size defines the width at which the wrapping will occur. Note that the wrapping will happen only at word boundaries, so the actual size might still be bigger than the size given here, but not smaller.

If setAutoSize is not enabled, the minimum size is ignored. Setting a smaller legend size with setSize manually, is not prevented.

See also:
setAutoSize, setSize, QCPPlottableLegendItem::setTextWrap
void QCPLegend::setMinimumSize ( int  width,
int  height 
)

This is an overloaded function.

void QCPLegend::setPaddingLeft ( int  padding)

Sets the left padding of the legend. Padding is the space by what the legend box is made larger than minimally needed for the content to fit. I.e. it's the space left blank on each side inside the legend.

void QCPLegend::setPaddingRight ( int  padding)

Sets the right padding of the legend. Padding is the space by what the legend box is made larger than minimally needed for the content to fit. I.e. it's the space left blank on each side inside the legend.

void QCPLegend::setPaddingTop ( int  padding)

Sets the top padding of the legend. Padding is the space by what the legend box is made larger than minimally needed for the content to fit. I.e. it's the space left blank on each side inside the legend.

void QCPLegend::setPaddingBottom ( int  padding)

Sets the bottom padding of the legend. Padding is the space by what the legend box is made larger than minimally needed for the content to fit. I.e. it's the space left blank on each side inside the legend.

void QCPLegend::setPadding ( int  left,
int  right,
int  top,
int  bottom 
)

Sets the padding of the legend. Padding is the space by what the legend box is made larger than minimally needed for the content to fit. I.e. it's the space left blank on each side inside the legend.

void QCPLegend::setMarginLeft ( int  margin)

Sets the left margin of the legend. Margins are the distances the legend will keep to the axis rect, when setPositionStyle is not psManual.

void QCPLegend::setMarginRight ( int  margin)

Sets the right margin of the legend. Margins are the distances the legend will keep to the axis rect, when setPositionStyle is not psManual.

void QCPLegend::setMarginTop ( int  margin)

Sets the top margin of the legend. Margins are the distances the legend will keep to the axis rect, when setPositionStyle is not psManual.

void QCPLegend::setMarginBottom ( int  margin)

Sets the bottom margin of the legend. Margins are the distances the legend will keep to the axis rect, when setPositionStyle is not psManual.

void QCPLegend::setMargin ( int  left,
int  right,
int  top,
int  bottom 
)

Sets the margin of the legend. Margins are the distances the legend will keep to the axis rect, when setPositionStyle is not psManual.

void QCPLegend::setItemSpacing ( int  spacing)

Sets the vertical space between two legend items in the legend.

See also:
setIconTextPadding, setPadding
void QCPLegend::setIconSize ( const QSize &  size)

Sets the size of legend icons. Legend items that draw an icon (e.g. a visual representation of the graph) will use this size by default.

void QCPLegend::setIconSize ( int  width,
int  height 
)

This is an overloaded function.

void QCPLegend::setIconTextPadding ( int  padding)

Sets the horizontal space in pixels between the legend icon and the text next to it. Legend items that draw an icon (e.g. a visual representation of the graph) and text (e.g. the name of the graph) will use this space by default.

See also:
setItemSpacing
void QCPLegend::setIconBorderPen ( const QPen &  pen)

Sets the pen used to draw a border around each legend icon. Legend items that draw an icon (e.g. a visual representation of the graph) will use this pen by default.

If no border is wanted, set this to Qt::NoPen.

void QCPLegend::setSelectable ( const SelectableParts &  selectable)

Sets whether the user can (de-)select the parts in selectable by clicking on the QCustomPlot surface. (When QCustomPlot::setInteractions contains iSelectLegend.)

However, even when selectable is set to a value not allowing the selection of a specific part, it is still possible to set the selection of this part manually, by calling setSelected directly.

See also:
SelectablePart, setSelected
void QCPLegend::setSelected ( const SelectableParts &  selected)

Sets the selected state of the respective legend parts described by SelectablePart. When a part is selected, it uses a different pen/font and brush. If some legend items are selected and selected doesn't contain spItems, those items become deselected.

The entire selection mechanism is handled automatically when QCustomPlot::setInteractions contains iSelectLegend. You only need to call this function when you wish to change the selection state manually.

This function can change the selection state of a part even when setSelectable was set to a value that actually excludes the part.

emits the selectionChanged signal when selected is different from the previous selection state.

Note that it doesn't make sense to set the selected state spItems here when it wasn't set before, because there's no way to specify which exact items to newly select. Do this by calling QCPAbstractLegendItem::setSelected directly on the legend item you wish to select.

See also:
SelectablePart, setSelectable, selectTest, setSelectedBorderPen, setSelectedIconBorderPen, setSelectedBrush, setSelectedFont
void QCPLegend::setSelectedBorderPen ( const QPen &  pen)

When the legend box is selected, this pen is used to draw the border instead of the normal pen set via setBorderPen.

See also:
setSelected, setSelectable, setSelectedBrush
void QCPLegend::setSelectedIconBorderPen ( const QPen &  pen)

Sets the pen legend items will use to draw their icon borders, when they are selected.

See also:
setSelected, setSelectable, setSelectedFont
void QCPLegend::setSelectedBrush ( const QBrush &  brush)

When the legend box is selected, this brush is used to draw the legend background instead of the normal brush set via setBrush.

See also:
setSelected, setSelectable, setSelectedBorderPen
void QCPLegend::setSelectedFont ( const QFont &  font)

Sets the default font that is used by legend items when they are selected.

This function will also set font on all already existing legend items.

See also:
setFont, QCPAbstractLegendItem::setSelectedFont
void QCPLegend::setSelectedTextColor ( const QColor &  color)

Sets the default text color that is used by legend items when they are selected.

This function will also set color on all already existing legend items.

See also:
setTextColor, QCPAbstractLegendItem::setSelectedTextColor
QCPAbstractLegendItem * QCPLegend::item ( int  index) const

Returns the item with index i.

See also:
itemCount

Returns the QCPPlottableLegendItem which is associated with plottable (e.g. a QCPGraph*). If such an item isn't in the legend, returns 0.

See also:
hasItemWithPlottable
int QCPLegend::itemCount ( ) const

Returns the number of items currently in the legend.

See also:
item
bool QCPLegend::hasItem ( QCPAbstractLegendItem item) const

Returns whether the legend contains item.

bool QCPLegend::hasItemWithPlottable ( const QCPAbstractPlottable plottable) const

Returns whether the legend contains a QCPPlottableLegendItem which is associated with plottable (e.g. a QCPGraph*). If such an item isn't in the legend, returns false.

See also:
itemWithPlottable

Adds item to the legend, if it's not present already.

Returns true on sucess, i.e. if the item wasn't in the list already and has been successfuly added.

The legend takes ownership of the item.

bool QCPLegend::removeItem ( int  index)

Removes the item with index index from the legend.

Returns true, if successful.

See also:
itemCount, clearItems

This is an overloaded function.

Removes item from the legend.

Returns true, if successful.

See also:
clearItems

Removes all items from the legend.

Returns the legend items that are currently selected. If no items are selected, the list is empty.

See also:
QCPAbstractLegendItem::setSelected, setSelectable

If setAutoSize is true, the size needed to fit all legend contents is calculated and applied. Finally, the automatic positioning of the legend is performed, depending on the setPositionStyle setting.

bool QCPLegend::selectTestLegend ( const QPointF &  pos) const

Returns whether the point pos in pixels hits the legend rect.

See also:
selectTestItem
QCPAbstractLegendItem * QCPLegend::selectTestItem ( const QPoint  pos) const

When the point pos in pixels hits a legend item, the item is returned. If no item is hit, 0 is returned.

See also:
selectTestLegend
void QCPLegend::selectionChanged ( QCPLegend::SelectableParts  selection) [signal]

This signal is emitted when the selection state of this legend has changed.

See also:
setSelected, setSelectable
void QCPLegend::updateSelectionState ( ) [protected, virtual]

Updates the spItems part of the selection state of this legend by going through all child items and checking their selected state.

If no items are selected and the current selected state contains spItems, it is removed and the selectionChanged signal is emitted. If at least one item is selected and the current selection state does not contain spItems, it is added and the signal is emitted, too.

This function is called in the QCPAbstractLegendItem::setSelected functions to propagate their change to the parent legend.

bool QCPLegend::handleLegendSelection ( QMouseEvent *  event,
bool  additiveSelection,
bool &  modified 
) [protected, virtual]

Handles the selection event and returns true when the selection event hit any parts of the legend. If the selection state of any parts of the legend was changed, the output parameter modified is set to true.

When additiveSelecton is true, any new selections become selected in addition to the recent selections. The recent selections are not cleared. Further, clicking on one object multiple times in additive selection mode, toggles the selection of that object on and off.

To indicate that an event deselects the legend (i.e. the parts that are deselectable by the user, see setSelectable), pass 0 as event.

void QCPLegend::applyDefaultAntialiasingHint ( QCPPainter painter) const [protected, virtual]

A convenience function to easily set the QPainter::Antialiased hint on the provided painter before drawing main legend elements.

This is the antialiasing state the painter passed to the draw method is in by default.

This function takes into account the local setting of the antialiasing flag as well as the overrides set e.g. with QCustomPlot::setNotAntialiasedElements.

See also:
setAntialiased

Implements QCPLayerable.

void QCPLegend::draw ( QCPPainter painter) [protected, virtual]

Draws the legend with the provided painter.

Implements QCPLayerable.

void QCPLegend::calculateAutoSize ( ) [protected, virtual]

Goes through similar steps as draw and calculates the width and height needed to fit all items and padding in the legend. The new calculated size is then applied to the mSize of this legend.

void QCPLegend::calculateAutoPosition ( ) [protected, virtual]

Sets the position dependant on the setPositionStyle setting and the margins.

QPen QCPLegend::getBorderPen ( ) const [protected]

Returns the pen used to paint the border of the legend, taking into account the selection state of the legend box.

QBrush QCPLegend::getBrush ( ) const [protected]

Returns the brush used to paint the background of the legend, taking into account the selection state of the legend box.

void QCPLayerable::setVisible ( bool  on) [inherited]

Sets the visibility of this layerable object. If an object is not visible, it will not be drawn on the QCustomPlot surface, and user interaction with it (e.g. click/selection) is not possible.

bool QCPLayerable::setLayer ( QCPLayer layer) [inherited]

Sets the layer of this layerable object. The object will be placed on top of the other objects already on layer.

Returns true on success, i.e. if layer is a valid layer.

bool QCPLayerable::setLayer ( const QString &  layerName) [inherited]

This is an overloaded function.

Sets the layer of this layerable object by name

Returns true on success, i.e. if layerName is a valid layer name.

void QCPLayerable::setAntialiased ( bool  enabled) [inherited]

Sets whether this object will be drawn antialiased or not.

Note that antialiasing settings may be overridden by QCustomPlot::setAntialiasedElements and QCustomPlot::setNotAntialiasedElements.

bool QCPLayerable::moveToLayer ( QCPLayer layer,
bool  prepend 
) [protected, inherited]

Moves this layerable object to layer. If prepend is true, this object will be prepended to the new layer's list, i.e. it will be drawn below the objects already on the layer. If it is false, the object will be appended.

Returns true on success, i.e. if layer is a valid layer.

void QCPLayerable::applyAntialiasingHint ( QCPPainter painter,
bool  localAntialiased,
QCP::AntialiasedElement  overrideElement 
) const [protected, inherited]

Sets the QPainter::Antialiasing render hint on the provided painter, depending on the localAntialiased value as well as the overrides QCustomPlot::setAntialiasedElements and QCustomPlot::setNotAntialiasedElements. Which override enum this function takes into account is controlled via overrideElement.

QRect QCPLayerable::clipRect ( ) const [protected, virtual, inherited]

Returns the clipping rectangle of this layerable object. By default, this is the viewport of the parent QCustomPlot. Specific subclasses may reimplement this function to provide different clipping rects.

The returned clipping rect is set on the painter before the draw function of the respective object is called.

Reimplemented in QCPAbstractItem, and QCPAbstractPlottable.


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