new function: showcolors {base}

I propose to add a function that allows
to display colors selected by a text pattern
or by color vectors in a plot.

Wolfram Fischer

#--- showcolors.R

showcolors <-
function(
	  col	= "red"
	, index	= NULL
	, pie	= TRUE
	, lwd	= 6
	, cex	= 1.0
	, main	= NULL
	, sub	= NULL
	, ...
){
	n.colors <- length( col )
	if( n.colors > 1 ){
		main <- deparse( substitute( col ) )
		title <- qt.colors <- col
	}else{
		qx.colors <- grep( col, colors() )
		if( ! is.null( index ) ) qx.colors = qx.colors[ index ]
		else index = seq( along=qx.colors )
		if( is.null( main ) )  main <- paste( sep="", col
				, ' [', min(index), ':', max(index), ']' )
		qt.colors <- colors()[ qx.colors ]
		n.colors <- length( qt.colors )
	}

	if( pie ){
		pie( x = rep( 1, n.colors ), col = qt.colors, labels = qt.colors
			, main	= main, sub = sub, cex = cex, ... )
	}else{
		plot( type='n', x = c( -3, 3 ), y = c( 1, n.colors )
			, main = main, sub = sub, axes = FALSE, xlab = '', ylab = '' )
		segments(
			  x0 = rep( -0.5, n.colors ), y0 = 1 : n.colors
			, x1 = rep(  0.5, n.colors ), y1 = 1 : n.colors
			, col = qt.colors, lwd = lwd, ... )
		text( x = rep( -0.55, n.colors ), y  = 1 : n.colors
			, labels= qt.colors, cex = cex, pos = 2 )
	}
}

#--- showcolors.Rd

\name{showcolors}
\title{Displaying Colors}
\alias{showcolors}
\synopsis{
showcolors(col="red", \dots)
}
\description{
  \code{showcolors} displays selected colors
  (by searching color names containing a text pattern
  or by a vector of colors)
  in a pie or as bars.}
}
\usage{
showcolors(col="red", index=NULL, pie=TRUE, lwd=6, cex=1,
           main=NULL, sub=NULL, \dots)
}
\arguments{
  \item{col}{pattern string for search in \code{colors}.
	  	Alternatively, a vector of colors.}
  \item{index}{a numeric index for subselection
  		in the result of \code{col}.}
  \item{pie}{display colors in a pie.
  		Alternatively: display colors as bars.}
  \item{lwd}{line width for bars.}
  \item{main}{an overall title for the plot.}
  \item{sub}{a sub title for the plot.}
  \item{\dots}{graphical parameters can be given as arguments
  	to \code{plot}.}
}
\details{
	If \code{col} has length of 1 then all colors a displayed
	with names containing the text string \code{col}.
	The search is done by \code{grep}.
}
\seealso{
  \code{\link{colors}},
  \code{\link{palette}},
  \code{\link{rainbow}},
  \code{\link{grep}}.
}
\author{
	Wolfram Fischer
}
\examples{
showcolors()
showcolors( palette() )
showcolors( rainbow(24) )
showcolors( "yellow" )
showcolors( "yellow", pie=FALSE )
showcolors( "blue", index=26:50 )
}
\keyword{color}
\keyword{dplot}

#---