| RMC_AddBarSeries function. |
| Add a bar chart series to a region of an existing chart |
|
| Syntax |
|
nResult (LONG) = RMC_AddBarSeries(
ByVal nCtrlId (LONG),
ByVal nRegion (LONG),
Optional ByRef nFirstDataValue (DOUBLE),
Optional ByVal nDataValuesCount (LONG),
Optional ByVal nType (LONG),
Optional ByVal nStyle (LONG),
Optional ByVal nIsLucent (LONG),
Optional Byval nColor (LONG),
Optional ByVal nIsHorizontal (LONG),
Optional ByVal nWhichDataAxis (LONG),
Optional ByVal nValueLabelOn (LONG),
Optional ByVal nPointsPerColumn (LONG),
Optional ByVal nHatchMode (LONG)
)
|
|
| Parameter |
| nCtrlId (LONG) |
| | Unique ID of the chart control, to which the series belongs. |
| nRegion (LONG) |
| | Region to which the series belongs. |
| nFirstDataValue (DOUBLE) |
| | The first element of an one-dimensional array,
which holds the series data. If you want to add the data later with RMC_SetSeriesData(),
simply pass 0.
Please note one anomaly: If the type of the series is RMC_FLOATINGBAR or RMC_FLOATINGBARGROUP,
you must pass for each single bar a pair of two data values, where the first value holds the starting point of the
bar and the second value holds the data which determines the length of the bar. Example: Imagine the data axis has a range
from 1 to 10 and you want to draw a floating bar which starts at 2 and ends at 9. In this case you must pass the data
pair 2,7 for this bar.
|
| nDataValuesCount (LONG) |
| | The total number of elements in the data array or zero,
if you want to add the data later. |
| nType (LONG) |
| | Type of the series as a chart type constant. If omitted or 0: RMC_BARSINGLE. |
| nStyle (LONG) |
| | Style of the bar series as a chart style constant.
If omitted or 0: RMC_BAR_FLAT |
| nIsLucent (LONG) |
| | If TRUE, the transparency of the bars is switched on,
if FALSE the bars are opaque. If omitted or 0: FALSE |
| nColor (LONG) |
| | Color of the bars as a Color...constant or as a RGB value. If omitted or 0:
One of the internal color values, which corresponds to the series index, where the first added series has the index 1,
the second the index 2 and so on.
Note: If the type of the series is RMC_BARSINGLE, all bars normally will have the same color, as defined
with nColor. You can have different colors for each single bar: if you choose for nColor the
constant ColorTransparent, each bar will have a different color. If you don't define a own color table with
RMC_SetSingleBarColors(), the internal color table will
be used: because these are only nine different colors, they will be circular repeated if your series has more the
nine bars. |
| nIsHorizontal (LONG) |
| | If TRUE, the bars are drawn horizontal, if FALSE vertical.
If omitted or 0: FALSE |
| nWhichDataAxis (LONG) |
| | Decides, to which data axis the series is connected.
1 for the first, 2 for the second axis (if existent). First and second means the order, in which the axis via
RMC_AddDataAxis() was added to the region. If omitted or 0: 1 |
| nValueLabelOn (LONG) |
| |
You can switch off value labels with the constant RMC_VLABEL_NONE or switch on with one of the following constants:
- If the series type is RMC_BARSINGLE or RMC_BARGROUP: RMC_VLABEL_DEFAULT or
RMC_VLABEL_ABSOLUTE, which both show the absolute value of each bar.
- If the series type is RMC_BARSTACKED: RMC_VLABEL_DEFAULT or RMC_VLABEL_ABSOLUTE
will both show the absolute value of each bar, RMC_VLABEL_PERCENT shows the percent value and
RMC_VLABEL_TWIN shows both, absolute and percent values.
- If the series type is RMC_BARSTACKED100: RMC_VLABEL_DEFAULT or RMC_VLABEL_PERCENT
will both show the percent value of each bar, RMC_VLABEL_ABSOLUTE shows the absolute value and
RMC_VLABEL_TWIN shows both, absolute and percent values.
Note: You can disable painting a value label for bars, which have zero values, with the
constants RMC_VLABEL_DEFAULT_NOZERO, RMC_VLABEL_PERCENT_NOZERO, RMC_VLABEL_ABSOLUTE_NOZERO and
RMC_VLABEL_TWIN_NOZERO. |
| nPointsPerColumn (LONG) |
| | How many data points shall be painted in each existent column.
If omitted or 0: 1
See Remarks |
| nHatchMode (LONG) |
| | Normally solid colors are used to fill the bars or the bar segments.
In case of grouped or stacked bars it might be usefull (specially when printing) to fill the bars with a hatch brush instead
of a solid brush. In this case use this parameter. There are three possible values:
- RMC_HATCHBRUSH_OFF: Only solid brushes are used to fill the objects. This is the default.
- RMC_HATCHBRUSH_ON: Hatch brushes instead of solid brushes are used to fill the objects. Ten different hatch brushes
are defined in an internal array. Series 1 gets the first brush, series 2 the second and so on.
- RMC_HATCHBRUSH_ONPRINTING: If showing the chart on the screen (or exporting it to a bitmap), solid brushes are used.
If sending the chart to the printer, hatch brushes are used.
Hatch brushes should only be used with the non-gradient styles. It's nearly impossible to find a good
balance between the gradient effect and the hatch brushes, and if it might be ok for the screen, it's not ok for
the printer. Also use hatch brushes only with the more lighter colors, not with the dark ones.
|
|
| Return value |
| 0 |
| | No error, function succeeded. |
| RMC_ERROR_CTRLID |
| | Wrong control ID (0 or no chart with this control ID was found). |
| RMC_ERROR_MAXREGION |
| | The region index exceeds the maximum possible numbers of regions (6) within a chart control. |
| RMC_ERROR_WRONGREGION |
| | The region index is inexistent in the chart control. |
| RMC_ERROR_MAXSERIES |
| | The actual series exceeds the maximum possible numbers of series (15) within a region. |
| RMC_ERROR_ALLOC |
| | Error while allocating memory for the data. |
| Remarks |
| |
The "points per column" parameter affects only bar charts with the type RMC_BARSINGLE. RMC_BARGROUP, RMC_BARSTACKED and RMC BARSTACKED100
have per definitonem more then one data point per column (RMC_BARGROUP side by side, the stacked bars on top of each other).
Normally you will define a label axis with as much columns as you have data points; in this case set nPointsPerColumn to 1 (or omit it, so it defaults to 1).
But imagine the following: you want to draw whatever for the first and the second half of a year on a monthly basis.
You could add a label axis with two columns (and labels), add a bar series with type RMC_BARSINGLE and 12 data values
and set nPointsPerColumn to 6. The resultant chart could look like this:
|