[Rd] new function: showcolors {base}

[Wolfram Fischer - Z/I/M]

Thanks for the inputs!

I have adjusted the function:
- it shows now  a pie  or  lines and bars (default)
- it stops if there is no match for the searched color string
- it returns the list of the colors

Below you find the proposed new code.

Wolfram


#--- showcolors.R

showcolors <-
function(
      col   = "red" # pattern string for search in colors() or vector of colors
    , index = NULL  # numeric vector for subselection
    , pie   = FALSE # display as pie, otherwise as bars and lines
    , lwd   = 1     # line width for lines
    , cex   = 1.0
    , main  = NULL
    , sub   = NULL
    , plot  = TRUE
    , ...
){
    n.colors <- length( col )
    if( n.colors > 1 ){
        main <- deparse( substitute( col ) )
        title <- qt.colors <- col
    }else{
        qx.colors <- grep( col, colors() )
        if( length( qx.colors ) == 0 )
            stop( paste(sep=""
                , "There is no color name which matches ``", col, "''.\n" ) )
        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( plot ){
        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( -2, 2 ), y = c( 1, n.colors )
                , main = main, sub = sub, axes = FALSE, xlab = '', ylab = '' )
            text( x = rep( 0, n.colors ), y  = 1 : n.colors
                , labels= qt.colors, cex = cex )
                segments(
                      x0 = rep( -1.5, n.colors ), y0 = 1 : n.colors
                    , x1 = rep( -0.5, n.colors ), y1 = 1 : n.colors
                    , col = qt.colors, lwd = lwd, ... )
                rect(
                      xleft = rep(  0.5, n.colors )
                    , ybottom = 1 : n.colors - 0.4
                    , xright = rep( 1.5, n.colors )
                    , ytop = 1 : n.colors + 0.4
                    , col = qt.colors, ... )
        }
    }
    invisible( qt.colors )
}

#--- 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 given by a vector of colors)
  as lines or bars or in a pie.
}
\usage{
showcolors(col="red", index=NULL, pie=FALSE, lwd=1, cex=1,
           main=NULL, sub=NULL, plot=TRUE, \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}{logical. If \code{TRUE}, a colored pie is displayed.
        Alternatively, colored lines and bars are displayed.}
  \item{lwd}{line width for lines.}
  \item{cex}{the character size to be used for the labels.}
  \item{main}{an overall title for the plot.}
  \item{sub}{a sub title for the plot.}
  \item{plot}{logical. If \code{FALSE}, nothing is plotted.}
  \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}.

    By default, a pie with the colors found is drawn,
    labelled by the names of the colors.
}
\value{
    A vector of the color names to show.
}
\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=TRUE )
showcolors( "blue", index=26:50 )
}
\keyword{color}
\keyword{dplot}

#---