\name{ColorBar}
\alias{ColorBar}
\title{Draws a Color Bar}
\description{
Generates a color bar to use as colouring function for map plots and optionally draws it (horizontally or vertically) to be added to map multipanels or plots. It is possible to draw triangles at the ends of the colour bar to represent values that go beyond the range of interest. A number of options is provided to adjust the colours and the position and size of the components. The drawn colour bar spans a whole figure region and is compatible with figure layouts.\cr\cr
The generated colour bar consists of a set of breaks that define the length(brks) - 1 intervals to classify each of the values in each of the grid cells of a two-dimensional field. The corresponding grid cell of a given value of the field will be coloured in function of the interval it belongs to.\cr\cr
The only mandatory parameters are 'var_limits' or 'brks' (in its second format, see below).
}
\usage{
ColorBar(brks = NULL, cols = NULL, vertical = TRUE,
         subsampleg = NULL, bar_limits = NULL, var_limits = NULL,
         triangle_ends = NULL, color_fun = clim.colors,
         plot = TRUE, draw_ticks = TRUE, draw_separators = FALSE,
         triangle_ends_scale = 1, extra_labels = NULL,
         title = NULL, title_scale = 1, label_scale = 1,
         tick_scale = 1, extra_margin = rep(0, 4),
         label_digits = 4, ...)
}
\arguments{
  \item{brks}{
'brks' can be provided in two formats:\cr
a) A single value with the number of breaks to be generated automatically, between the minimum and maximum specified in 'var_limits' (both inclusive). Hence the parameter 'var_limits' is mandatory if 'brks' is provided with this format. If 'bar_limits' is additionally provided, values only between 'bar_limits' will be generated. The higher the value of 'brks', the smoother the plot will look.\cr
b) A vector with the actual values of the desired breaks. Values will be reordered by force to ascending order. If provided in this format, no other parameters are required to generate/plot the colour bar.\cr\cr

This parameter is optional if 'var_limits' is specified. If 'brks' not specified but 'cols' is specified, it will take as value length(cols) + 1. If 'cols' is not specified either, 'brks' will take 21 as value.\cr\cr
  }
  \item{cols}{
Vector of length(brks) - 1 valid colour identifiers, for each interval defined by the breaks. This parameter is optional and will be filled in with a vector of length(brks) - 1 colours generated with the function provided in 'color_fun' (\code{clim.colors} by default).\cr
'cols' can have one additional colour at the beginning and/or at the end with the aim to colour field values beyond the range of interest represented in the colour bar. If any of these extra colours is provided, parameter 'triangle_ends' becomes mandatory in order to disambiguate which of the ends the colours have been provided for.\cr
  }
  \item{vertical}{
TRUE/FALSE for vertical/horizontal colour bar (disregarded if plot = FALSE).
  }
  \item{subsampleg}{
The first of each subsampleg breaks will be ticked on the colorbar.\cr
Takes by default an approximation of a value that yields a readable tick arrangement (extreme breaks always ticked). See the code of the function for details or use 'extra_labels' for customized tick arrangements.
  }


  \item{cex}{
Multiplicative factor to increase the ticks size, optional.
  }
  \item{...}{
    Arguments to be passed to the method. Only accepts the following
    graphical parameters:
      
    adj ann ask bg bty cex.lab cex.main cex.sub cin col.axis col.lab col.main col.sub cra crt csi cxy err family fg fig fin font font.axis font.lab font.main font.sub lend lheight ljoin lmitre lty lwd mai mex mfcol mfrow mfg mkh oma omd omi page pch pin plt pty smo srt tck tcl usr xaxp xaxs xaxt xlog xpd yaxp yaxs yaxt ylbias ylog

    For more information about the parameters see `par`
  }
}
\examples{
cols <- c("dodgerblue4", "dodgerblue1", "forestgreen", "yellowgreen", "white",
          "white", "yellow", "orange", "red", "saddlebrown")
lims <- seq(-1, 1, 0.2)
ColorBar(lims, cols)
}
\author{
History:\cr
0.1  -  2012-04  (V. Guemas, \email{virginie.guemas at ic3.cat})  -  Original code\cr
0.2  -  2013-04  (I. Andreu-Burillo, \email{isabel.andreu-burillo at ic3.cat})  -  Vert option\cr
1.0  -  2013-09  (N. Manubens, \email{nicolau.manubens at ic3.cat})  -  Formatting to CRAN\cr
1.1  -  2013-09  (C. Prodhomme \email{chloe.prodhomme at ic3.cat})  -  Add cex option
}
\keyword{dplot}
