.XY ADD BAR LAYER

This subroutine adds a Bar layer to the "current" chart spec.

.XY ADD BAR LAYER

Usage:

      PASS         <data_combine_method>      FIELD            SHARE? N
      PASS         <bar_color_style>          FIELD            SHARE? N
      PASS         <auto_link>                FIELD            SHARE? N
      GOSUB    0CD .XY ADD BAR LAYER
      *        Check for error
      IF       0CD .XY ADD BAR LAYER          NE

Description:

This subroutine adds a Bar layer to the "current" chart spec and optionally links the "current" dataset to it, if there is one. You must have initialized the chart as an XY Chart via .CHART INITIALIZE for this to have any effect.

This subroutine is used to add one or more bar layers to your chart. An XY chart must have at least one Layer.

This routine receives three optional values, a <data_combine_method>, a <bar_color_style> and <auto_link>.

If we are only going to have one data set on our chart, then the <data_combine_method> does not really apply. If we have multiple data sets, then the <data_combine_method> will determine how they will be shown. Valid values are:

side - The data sets are combined by plotting the bars side by side.

stack - The data sets are combined by stacking up the bar segments.

overlay - The data sets are combined similar to stacked bars. However, in overlay, one data set is assumed to already include the other data set. For example, if the data sets are "average" and "peak", the "peak" cannot be stacked on top of "average", because the "peak" already contains "average". In the Overlay style, only "peak - average" is stacked on top of "average", and so the total bar length will be "peak".

percentage - The data sets are combined similar to stacked bars, except that the data in a bar are scaled so that they sum to 100. In other words, all stacked bars will be of the same length. A bar segment within a bar represents the percentage of the data item relative to sum of all the data items in the stacked bar.

If blank or not passed, then each data set will be plotted in it's own layer.

<bar_color_style> must be either blank or 'multiple'. Blank means that every bar in the layer will be the same color. 'Multiple' means that each bar can have a different color. You can set each bar via .XY SET BAR CLR, but if you don't Chart Director will assign unique colors automatically.

<auto_link> must be one of On, Off, True or False. If not passed, or set to On or True, then if you have created your data set before calling this subroutine, a default data group and data template will be created and linked to your data set automatically. This can be helpful if you only have one dataset to link. If you have multiple data sets, you might find it easier to manually create your data group (.LAYER ADD DATA GROUP) and template (.LAYER ADD DATASET TM) and then link it (.LAYER LINK DATASET TM). Note that if you plan to repeatedly generate the same chart with different data, the automatic linking will cause problems because when you add the layer on the next iteration, it will link to your previous data set. In this case, you should turn off automatic linking and manage it manually.

See Datasets Overview for more information on working with Layers, Data Groups, Data Templates, Data Sets and Data Points.