Monkeybread Xojo plugin - CDLegendBoxMBS methods

CDLegendBoxMBS.addKey(pos as Integer, text as string, colorvalue as color, lineWidth as Integer = -1, drawarea as CDDrawAreaMBS=nil)

Type	Topic	Plugin	Version	macOS	Windows	Linux	iOS	Targets
method	ChartDirector	MBS ChartDirector Plugin	11.1	✅ Yes	✅ Yes	✅ Yes	✅ Yes	All

Same as the other addKey method, but uses color instead of integer data type for passing color values.

See also:

addKey(pos as Integer, text as string, colorvalue as Integer, lineWidth as Integer = -1, drawarea as CDDrawAreaMBS=nil)
addKey(text as string, colorvalue as color, lineWidth as Integer = -1, drawarea as CDDrawAreaMBS=nil)
addKey(text as string, colorvalue as Integer, lineWidth as Integer = -1, drawarea as CDDrawAreaMBS=nil)

CDLegendBoxMBS.addKey(pos as Integer, text as string, colorvalue as Integer, lineWidth as Integer = -1, drawarea as CDDrawAreaMBS=nil)

Type	Topic	Plugin	Version	macOS	Windows	Linux	iOS	Targets
method	ChartDirector	MBS ChartDirector Plugin	8.2	✅ Yes	✅ Yes	✅ Yes	✅ Yes	All

Adds a custom entry to the legend box with a given legend entry priority.

See LegendBox for more information on legend entry priority system.

Argument Default Description

pos (Mandatory) The legend entry priority

text (Mandatory) The text of the legend entry.

color (Mandatory) The icon color of the legend entry.

lineWidth 0 The line width for legend entry that represents lines in line charts.

drawarea nil A DrawArea containing the data symbol represents the legend entry. This is primarily used for legend entries in line charts with data symbols, or in scatter charts.

Type	Topic	Plugin	Version	macOS	Windows	Linux	iOS	Targets
method	ChartDirector	MBS ChartDirector Plugin	11.1	✅ Yes	✅ Yes	✅ Yes	✅ Yes	All

Same as the other addKey method, but uses color instead of integer data type for passing color values.

Type	Topic	Plugin	Version	macOS	Windows	Linux	iOS	Targets
method	ChartDirector	MBS ChartDirector Plugin	8.2	✅ Yes	✅ Yes	✅ Yes	✅ Yes	All

Adds a custom entry to the legend box.

This method adds an entry within a legend entry priority of 1 (followed by 2, 3, 4, ... for repeated calls). This has higher priority than entries added automatically by ChartDirector for representing data sets. As a result, by default, the custom entry will appear before the automatic entries.

To control the order of the custom entry relative to the automatic entries, use LegendBox.addKey2.

See LegendBox for more information on legend entry priority system.

Argument Default Description

text (Mandatory) The text of the legend entry.

color (Mandatory) The icon color of the legend entry.

lineWidth 0 The line width for legend entry that represents lines in line charts.

drawarea nil A DrawArea containing the data symbol represents the legend entry. This is primarily used for legend entries in line charts with data symbols, or in scatter charts.

Type	Topic	Plugin	Version	macOS	Windows	Linux	iOS	Targets
method	ChartDirector	MBS ChartDirector Plugin	21.2	✅ Yes	✅ Yes	✅ Yes	✅ Yes	All

Adds a custom text to the legend box.

See also:

addText(text as string)

CDLegendBoxMBS.addText(text as string)

Type	Topic	Plugin	Version	macOS	Windows	Linux	iOS	Targets
method	ChartDirector	MBS ChartDirector Plugin	21.2	✅ Yes	✅ Yes	✅ Yes	✅ Yes	All

Adds a custom text to the legend box.

See also:

addText(pos as Integer, text as string)

CDLegendBoxMBS.getHTMLImageMap(url as string, queryFormat as string = "", extraAttr as string = "", offsetX as Integer = 0, offsetY as Integer = 0) as string

Type	Topic	Plugin	Version	macOS	Windows	Linux	iOS	Targets
method	ChartDirector	MBS ChartDirector Plugin	8.2	✅ Yes	✅ Yes	✅ Yes	✅ Yes	All

Generates an HTML image map for the legend.

By default, ChartDirector will add named data representation to the legend box. For pie charts, named sectors (sectors that have text labels) will be added. For xy charts, named data sets will be added. For polar charts, named layers will be added.

You may add custom entries to the legend box by using LegendBox.addKey.

To control the ordering of the legend entries, ChartDirector employs a legend entry priority system. Each entry is given a priority number, and the entries are ordered according to ascending priority (unless reversed by using LegendBox.setReverse).

For a PieChart, the legend entry priority of a sector is 10000 x (sector_index + 1). The Nth sector has sector_index (N - 1). That means the ordering of the sectors in the legend box is the same as the data array.

For an XYChart, the base legend entry priority for a layer is 10000 x (layer_index + 1). Within a layer, the data set priority is 10 x (data_set_index + 1). For example, the legend entry priority for the 5th dataset in the 3rd layer will be 30050. That means the ordering of the data sets in the legend box follows the order in which the layers are created. For data sets within the same layer, the ordering follows the order in which the data sets are added. The ordering can be modified by using Layer.setLegendOrder.

For an PolarChart, the legend entry priority of a layer is 10000 x (layer_index + 1). That means the ordering of the layers in the legend box follows the order in which the layers are created.

For custom entries added using LegendBox.addKey2, you may control the legend entry priority. That means you may insert custom entries anywhere relative to the automatic entries added by ChartDirector.

CDLegendBoxMBS.getImageCoor(dataItem as Integer, offsetX as Integer = 0, offsetY as Integer = 0) as string

Type	Topic	Plugin	Version	macOS	Windows	Linux	iOS	Targets
method	ChartDirector	MBS ChartDirector Plugin	8.2	✅ Yes	✅ Yes	✅ Yes	✅ Yes	All

Gets the image map coordinates of an legend entry as HTML image map attributes.

The image map coordinates will be of the following format:

shape="rect" cords="[x1],[y1],[x2],[y2]"
where (x1, y1) and (x2, y2) are opposite corners of the box that enclosed the legend entry. The format is specially designed so that it can easily be included into HTML image maps.

This method should be called only after creating the chart image (eg. using BaseChart.makeChart, BaseChart.makeChart2 or BaseChart.makeChart3). The image map cannot be determined without creating the chart image first.

Argument Default Description

dataItem (Mandatory) The legend entry number, starting from 0. The first legend entry is 0. The nth legend entry is (n-1).

offsetX 0 An offset to be added to all x coordinates in the image map. This is useful if the current image will be shifted and inserted into another image. In this case, the image map will need to be shifted by the same offset.

offsetY 0 An offset to be added to all y coordinates in the image map. See offsetX above for description.

Return Value
A text string representing the coordinates of the legend entry in HTML image map attribute format.

CDLegendBoxMBS.setCols(noOfCols as Integer)

Type	Topic	Plugin	Version	macOS	Windows	Linux	iOS	Targets
method	ChartDirector	MBS ChartDirector Plugin	8.2	✅ Yes	✅ Yes	✅ Yes	✅ Yes	All

Sets the number of columns in the legend box.

Argument Default Description

noOfCols (Mandatory) The number of columns in the legend box. The special value AutoGrid (= -2) means the number of columns is automatically determined. If this argument is 0, the legend box will use a flow layout (from left to right and then top to bottom, in which the entries may not be vertically aligned).

CDLegendBoxMBS.setKeyBorder(edgeColor as color, raisedEffect as Integer = 0)

Type	Topic	Plugin	Version	macOS	Windows	Linux	iOS	Targets
method	ChartDirector	MBS ChartDirector Plugin	11.1	✅ Yes	✅ Yes	✅ Yes	✅ Yes	All

Same as the other setKeyBorder method, but uses color instead of integer data type for passing color values.

See also:

setKeyBorder(edgeColor as Integer, raisedEffect as Integer = 0)

Some examples using this method:

CDLegendBoxMBS.setKeyBorder(edgeColor as Integer, raisedEffect as Integer = 0)

Type	Topic	Plugin	Version	macOS	Windows	Linux	iOS	Targets
method	ChartDirector	MBS ChartDirector Plugin	8.2	✅ Yes	✅ Yes	✅ Yes	✅ Yes	All

Sets the default border color of the legend icon.

This method applies only to data sets of which the icons are rectangles showing the colors of the data sets. If the icon is a shape or symbol (such as for a line with data point symbols), the border color of the original shape or symbol is always used.

Argument Default Description

edgeColor (Mandatory) The border color.

raisedEffect 0 The 3D border width. For positive values, the border will appear raised. For negative values, the border will appear depressed. A zero value means the border will appear flat. This argument is also used to support Chart::glassEffect and Chart::softLighting effects.

See also:

setKeyBorder(edgeColor as color, raisedEffect as Integer = 0)

CDLegendBoxMBS.setKeySize(width as Integer = -1, height as Integer = -1, gap as Integer = -1)

Type	Topic	Plugin	Version	macOS	Windows	Linux	iOS	Targets
method	ChartDirector	MBS ChartDirector Plugin	8.2	✅ Yes	✅ Yes	✅ Yes	✅ Yes	All

Sets the size of the legend icon and its distance from the legend text.

Each legend entry consists of an icon and a text description. By default, the size of the icon and its distance from the text is determined automatically based on font size. This method can be used to override the default.

Argument Default Description

width (Mandatory) The width of the legend icon in pixels.

height -1 The height of the legend icon in pixels. -1 means the height is automatically determined.

gap -1 The distance between the legend icon and the legend text in pixels. -1 means the distance is automatically determined.

Some examples using this method:

CDLegendBoxMBS.setKeySpacing(keySpacing as Integer, lineSpacing as Integer = -1)

Type	Topic	Plugin	Version	macOS	Windows	Linux	iOS	Targets
method	ChartDirector	MBS ChartDirector Plugin	8.2	✅ Yes	✅ Yes	✅ Yes	✅ Yes	All

Sets the distance between two legend entries.

In horizontal legend layout, the legend entries will flow from left to right, top to bottom, with a horizontal gap between two legend entries. In vertical legend layout, the legend entries will flow from top to bottom, with one entry per line.

By default, the horizontal gap and the line spacing is automatically determined based on font size. This method can be used to set the horizontal gap and line spacing in pixels.

Argument Default Description

keySpacing (Mandatory) The horizontal gap between two legend entries for horizontal legend layout, expressed in pixels.

lineSpacing -1 The line spacing between two lines in the legend box, expressed in pixels. -1 means the line spacing is automatically determined.

Some examples using this method:

CDLegendBoxMBS.setLineStyleKey(b as boolean=true)

Type	Topic	Plugin	Version	macOS	Windows	Linux	iOS	Targets
method	ChartDirector	MBS ChartDirector Plugin	9.2	✅ Yes	✅ Yes	✅ Yes	✅ Yes	All

Determines whether to always use "line style legend keys" or not.

By default, ChartDirector will use a small colored square box as the legend key icon. This allows people to determine the colors for the data representations.

In some cases, colors alone cannot distinguish the data representations. For example, in a line chart with multiple lines, it is possible all lines are of the same color, and are distinguished by line styles (solid, dash, dotted, etc), etc), or the lines may be distinguished by data symbols (small circles, squares, etc) on the lines.

For charts with non-solid lines (eg. dash, dotted, etc) or lines with data symbols, ChartDirector will use "line style legend keys" for the lines. A line style legend key consist a of line with an optional data symbol, which reflects the line style and data symbol representing the data series.

This method can be used to force ChartDirector to always use the "line style legend keys".

Arguments:

Argument Default Description

b true A true value means to always use "line style legend keys". A false value means to automatically determined if "line style legend keys" should be used.

Some examples using this method:

CDLegendBoxMBS.setReverse(b as boolean=true)

Type	Topic	Plugin	Version	macOS	Windows	Linux	iOS	Targets
method	ChartDirector	MBS ChartDirector Plugin	8.2	✅ Yes	✅ Yes	✅ Yes	✅ Yes	All

Reverses the ordering of the legend entries.

By default, the legend entries are ordered based on ascending legend entry priority number. This method can be used to change the ordering to following descending legend entry priority number instead.

See LegendBox for more information on legend entry priority system.

Argument Default Description

b true A true value means the legend entries are ordered based on descending legend entry priority number. false value means the legend entries are ordered based on ascending legend entry priority number.

Argument	Default	Description
pos	(Mandatory)	The legend entry priority
text	(Mandatory)	The text of the legend entry.
color	(Mandatory)	The icon color of the legend entry.
lineWidth	0	The line width for legend entry that represents lines in line charts.
drawarea	nil	A DrawArea containing the data symbol represents the legend entry. This is primarily used for legend entries in line charts with data symbols, or in scatter charts.