Legends
Legends label data. While legends are useful in conjunction with line plots, arbitrary (custom) plots can be labeled with help of legends. Next to line plots, contour plots are another popular use for legends.
A legend object displays labels for an arbitrary number of data plots. Which plots are listed in the legend is fully configurable as well as the styling of legends and individual legend items.
Automatic Legend Creation
In the following example three line plots are added to a plot cube. A legend is created and added to the same plot cube. No further parameters are configured for the legend. By default, the legend will search all suitable objects in the plot cube and create legend items for them. The Tag property of the plot objects is used as legend item label texts. If the Tag property is null, a custom string is automatically generated with an upwards counting ID postfix.
The naming of the plots in the legend in the last example was created by LinePlot.CreateXPlots(). In order to quickly name individual plots in a legend, the names for legend items can be controlled be providing strings with the texts for all items to be created to the constructor of Legend. One item will be created for every string provided. The order of the items corresponds to the order of suitable nodes in the plot cube. In the next example, the legend is created with two strings; hence only two items exist in the legend for the first two objects found.
Note how the constructors string parameters control both: the text which appears on the legend items (overriding the Tag of the plots in this case) and the number of items to be displayed.
Note further that the position of the legend node object within the scene graph nodes is not of great importance. By default, legends consider all those objects as item data source which are contained in the same plot cube as the legend itself. If more control is needed about which plot objects are to be used, the root node of the subtree containing those plot objects can be given to the root parameter in the constructor of Legend.
Manual Legend Creation
For situations where more control is needed, every legend item can individually get added, removed or configured. Rather than letting the legend select from the collection of available plots automatically, the source plot for every legend item must be determined by the user explicitly.
The next example again creates some line plots. Legend items are configured for the first and the last plot object. Custom label texts are provided and the items are simply added to the Items collection of Legend.
Note, how both methods of legend item creation are combined. However, the constructor of Legend does only allow addressing of plot objects in the order of their appearance in the scene. The manual addition of individual legend items allows for arbitrary plots to be added in arbitrary order.
The second argument to the LegendItem constructor is the text which should be displayed for the plot object in the legend. If no text is given here, the default is used: the Tag property of the plot object. If we would have omitted the “last” label text in the example above, the tag for the last plot object would have appeared.
The need for a valid reference to the plot objects is also the reason, why the legend cannot be created right inside the object initializer for the plot cube (like done in the first legend example). In order to acquire a reference, the plot cube and the line plots must exist already. Therefore, we first create the plot cube and use it afterwards for the legend creation.
Dynamic Changes to Legend Items
Legends allow flexible (re-) configuration at runtime. Individual legend items can be configured after creation. In order to configure the background for one of the legend items and to change the label color of another legend item from the last example:
The scene graph structure gives full flexibility for changes to any legend objects. However, one has to make sure, the legend has been initially configured and all items are created already. Since, in order to locate all plot objects automatically, the legend and all those plot objects must exist in the scene already.
Therefore, legends create their items right before the actual frame rendering. If one needs to access item scene elements right after creation, Legend.Configure() must be called in order to force the creation and configuration of the full legend object. Afterwards, any parts of the legend can be accessed by the common ILNumerics node navigation and managing functions (See: Accessing and Managing Nodes).
A number of common configuration options exist for legends. These options are derived from ScreenObject and include the Movable, Border, Background, Anchor, Location, and Size properties (See also: World3D- and Screen2D Nodes)
New legend items can be added and removed from the legend after creation. The next example creates seven line plots and configures markers for all but the last. A legend is created which displays items for the first 6 line plots:
Now, we remove two legend items from the legend. Another item is inserted into the legend for the last line plot. Therefore, the Legend.Items collection is manipulated directly. Items for removal are fetched either by index or by predicate filter expression:
Note, after changes to the Legend.Items collections, Legend.Configure() needs to be called again. Configure() not only initially creates all legend items but (re-)configures legend item sizes, content and positions after any manipulations to the Items collection.
Interactivity and Legends
If the renderer supports user interaction, legends can be moved with the mouse. A North-South-West-East arrows cursor indicates that option when hovering over the legends background area.
In order to prevent the user from moving a legend interactively, the Movable property is set to false.