
plcolorbar: Plot color bar for image, shade or gradient plots 

DESCRIPTION:

    This function is used in examples 16 and 33. 

SYNOPSIS:

plcolorbar(p_colorbar_width, p_colorbar_height, opt, position, x, y, x_length, y_length, bg_color, bb_color, bb_style, low_cap_color, high_cap_color, cont_color, cont_width, n_labels, label_opts, labels, naxes, axis_opts, ticks, sub_ticks, n_values, values)

ARGUMENTS:

    p_colorbar_width (PLFLT *, output) :    Pointer to a location which
    contains (after the call) the labelled and decorated color bar
    width in adopted coordinates. 

    p_colorbar_height (PLFLT *, output) :    Pointer to a location which
    contains (after the call) the labelled and decorated color bar
    height in adopted coordinates. 

    opt (PLINT, input) :    opt contains bits controlling the overall
    color bar.  The orientation (direction of the maximum value) of
    the color bar is specified with PL_ORIENT_RIGHT, PL_ORIENT_TOP,
    PL_ORIENT_LEFT, or PL_ORIENT_BOTTOM.  If none of these bits are
    specified, the default orientation is toward the top if the
    colorbar is placed on the left or right of the viewport or toward
    the right if the colorbar is placed on the top or bottom of the
    viewport. If the PL_COLORBAR_BACKGROUND bit is set, plot a
    (semi-transparent) background for the color bar. If the
    PL_COLORBAR_BOUNDING_BOX bit is set, plot a bounding box for the
    color bar. The type of color bar must be specified with one of
    PL_COLORBAR_IMAGE, PL_COLORBAR_SHADE, or PL_COLORBAR_GRADIENT. If
    more than one of those bits is set only the first one in the above
    list is honored. The position of the (optional) label/title can be
    specified with PL_LABEL_RIGHT, PL_LABEL_TOP, PL_LABEL_LEFT, or
    PL_LABEL_BOTTOM.  If no label position bit is set then no label
    will be drawn. If more than one of this list of bits is specified,
    only the first one on the list is honored. End-caps for the color
    bar can added with PL_COLORBAR_CAP_LOW and PL_COLORBAR_CAP_HIGH.
    If a particular color bar cap option is not specified then no cap
    will be drawn for that end. As a special case for
    PL_COLORBAR_SHADE, the option PL_COLORBAR_SHADE_LABEL can be
    specified. If this option is provided then any tick marks and tick
    labels will be placed at the breaks between shaded segments. TODO:
    This should be expanded to support custom placement of tick marks
    and tick labels at custom value locations for any color bar type. 

    position (PLINT, input) :     position contains bits which control the
    overall position of the color bar and the definition of the
    adopted coordinates used for positions just like what is done for
    the position argument for pllegend. However, note that the
    defaults for the position bits (see below) are different than the
    pllegend case. The combination of the PL_POSITION_LEFT,
    PL_POSITION_RIGHT, PL_POSITION_TOP, PL_POSITION_BOTTOM,
    PL_POSITION_INSIDE, and PL_POSITION_OUTSIDE bits specifies one of
    the 16 possible standard positions (the 4 corners and centers of
    the 4 sides for both the inside and outside cases) of the color
    bar relative to the adopted coordinate system. The corner
    positions are specified by the appropriate combination of two of
    the PL_POSITION_LEFT, PL_POSITION_RIGHT, PL_POSITION_TOP, and
    PL_POSITION_BOTTOM bits while the sides are specified by a single
    value of one of those bits.  The adopted coordinates are
    normalized viewport coordinates if the PL_POSITION_VIEWPORT bit is
    set or normalized subpage coordinates if the PL_POSITION_SUBPAGE
    bit is set. Default position bits: If none of PL_POSITION_LEFT,
    PL_POSITION_RIGHT, PL_POSITION_TOP, or PL_POSITION_BOTTOM are set,
    then use PL_POSITION_RIGHT. If neither of PL_POSITION_INSIDE or
    PL_POSITION_OUTSIDE is set, use PL_POSITION_OUTSIDE. If neither of
    PL_POSITION_VIEWPORT or PL_POSITION_SUBPAGE is set, use
    PL_POSITION_VIEWPORT. 

    x (PLFLT, input) :      X offset of the color bar position in adopted
    coordinates from the specified standard position of the color bar.
    For positive x, the direction of motion away from the standard
    position is inward/outward from the standard corner positions or
    standard left or right positions if the
    PL_POSITION_INSIDE/PL_POSITION_OUTSIDE bit is set in position. 
    For the standard top or bottom positions, the direction of motion
    is toward positive X. 

    y (PLFLT, input) :      Y offset of the color bar position in adopted
    coordinates from the specified standard position of the color bar.
    For positive y, the direction of motion away from the standard
    position is inward/outward from the standard corner positions or
    standard top or bottom positions if the
    PL_POSITION_INSIDE/PL_POSITION_OUTSIDE bit is set in position. 
    For the standard left or right positions, the direction of motion
    is toward positive Y. 

    x_length (PLFLT, input) :     Length of the body of the color bar in
    the X direction in adopted coordinates. 

    y_length (PLFLT, input) :     Length of the body of the color bar in
    the Y direction in adopted coordinates. 

    bg_color (PLINT, input) :     The cmap0 color of the background for the
    color bar (PL_COLORBAR_BACKGROUND). 

    bb_color (PLINT, input) :     The cmap0 color of the bounding-box line
    for the color bar (PL_COLORBAR_BOUNDING_BOX). 

    bb_style (PLINT, input) :     The pllsty style number for the
    bounding-box line for the color bar (PL_COLORBAR_BACKGROUND). 

    low_cap_color (PLFLT, input) :    The cmap1 color of the low-end color
    bar cap, if it is drawn (PL_COLORBAR_CAP_LOW). 

    high_cap_color (PLFLT, input) :    The cmap1 color of the high-end
    color bar cap, if it is drawn  (PL_COLORBAR_CAP_HIGH). 

    cont_color (PLINT, input) :    The cmap0 contour color for
    PL_COLORBAR_SHADE plots. This is passed directly to plshades, so
    it will be interpreted according to the design of plshades. 

    cont_width (PLFLT, input) :    Contour width for PL_COLORBAR_SHADE
    plots. This is passed directly to plshades, so it will be
    interpreted according to the design of plshades. 

    n_labels (PLINT, input) :     Number of labels to place around the
    color bar. 

    label_opts (const PLINT *, input) :    Options for each of 
    n_labels labels. 

    labels (const char * const *, input) :    n_labels text labels for the
    color bar. No label is drawn if no label position is specified
    with one of the PL_COLORBAR_LABEL_RIGHT, PL_COLORBAR_LABEL_TOP,
    PL_COLORBAR_LABEL_LEFT, or PL_COLORBAR_LABEL_BOTTOM bits in the
    corresponding label_opts field. 

    n_axes (PLINT, input) :    Number of axis definitions provided. This
    value must be greater than 0. It is typically 1 (numerical axis
    labels are provided for one of the long edges of the color bar),
    but it can be larger if multiple numerical axis labels for the
    long edges of the color bar are desired. 

    axis_opts (const char * const *, input) :     An array of n_axes axis
    options (interpreted as for plbox) for the color bar's axis
    definitions. 

    ticks (const PLFLT *, input) :    An array of n_axes values of the
    spacing of the major tick marks (interpreted as for plbox) for the
    color bar's axis definitions. 

    sub_ticks (const PLINT *, input) :      An array of n_axes values of the
    number of subticks (interpreted as for plbox) for the color bar's
    axis definitions. 

    n_values (const PLINT *, input) :     An array containing the number of
    elements in each of the n_axes rows of the two-dimensional values
    array. 

    values (const PLFLT * const *, input) :    A two-dimensional array
    containing the numeric values for the data range represented by
    the color bar. For a row index of i_axis (where 0 < i_axis <
    n_axes), the number of elements in the row is specified by
    n_values[i_axis]. For PL_COLORBAR_IMAGE and PL_COLORBAR_GRADIENT
    the number of elements is 2, and the corresponding row elements of
    the values array are the minimum and maximum value represented by
    the colorbar.  For PL_COLORBAR_SHADE, the number and values of the
    elements of a row of the values array is interpreted the same as
    the nlevel and clevel arguments of plshades. 
