RNMGraphics: NONMEM graphics

#' @description \code{setGraphParams} may be used to change graphical settings in a manner similar 
#' to the \code{lattice} package's function \code{trellis.par.set}, while \code{getGraphParams} 
#' is similar to \code{trellis.par.get}. Settings apply globally and to all plots generated by 
#' this package, and don't just apply to devices.
#' @details At the moment, the following fields exist:
#' 
#' \code{plot.symbol} - The plot points which appear in scatter plots.
#'  
#' \code{superpose.symbol} - The plot points which appear in scatter plots whenever a grouping variable is used. 
#' 
#' \code{plot.line} - The plot lines which appear in scatter plots, whenever lines are chosen to connect data rather than points.
#' 
#' \code{plot.text} - The plot labels that appear in scatter plots when type \code{"i"} is used.
#' 
#' \code{loess.line} - The loess smoother curve which can be added to scatter plots.
#' 
#' \code{histogram} - The fill colour and outline colour of histogram rectangles.
#' 
#' \code{refline} - The reference lines that can be added to many plots.
#' 
#' \code{barchart} - The fill colours of polygons used in \code{nmBarchart}.
#' 
#' \code{axis.text} - The text that appears in y- and x-axis labels.
#' 
#' \code{box.rectangle} - The rectangles in box plots.
#' 
#' \code{title.text} - The plot main title text.
#' 
#' \code{grid} - The reference/background grid text.
#' 
#' \code{strip.bg} - Strip background settings
#' 
#' \code{layout.heights} - Equivalent to the lattice setting of the same name
#' 
#' \code{layout.widths} - Equivalent to the lattice setting of the same name
#' 
#' \code{strip} - Strip function to use 
#' 
#' \code{panelLayout} - Currently unused
#' 
#' \code{panelMisc} - Miscellaneous controls over lattice panels 
#' 
#' \code{legend} - Settings for the legend.
#' 
#' @name Graphical parameters
#' @aliases setAllGraphParams getAllGraphParams setGraphParams getGraphParams
#' @param settings A full list of graphical parameters.  See the documentation for RNMGraphics.
#' @title Change and Retrieve Graphical Parameters
#' @return \code{setGraphParams} returns nothing.  \code{getGraphParams} 
#' returns a list with the configuration for the particular field/option chose, 
#' and \code{getAllGraphParams} returns a list (of lists) with all current configuration information.
#' @note Some of these settings and their implementations will almost certainly change in forthcoming releases.
#' @author Mango Solutions
#' @keywords utilities
#' @export
#' @examples 
#' \dontrun{ 
#' nmScatterPlot(mtcars, xVars = "wt", yVars = "mpg, disp")
#' plot.symbol <- getGraphParams("plot.symbol")
#' old.plot.symbol <- plot.symbol
#' plot.symbol$col <- "black"; plot.symbol$pch = 1
#' setGraphParams("plot.symbol", plot.symbol)
#' nmScatterPlot(mtcars, xVars = "wt", yVars = "mpg, disp")
#' setGraphParams("plot.symbol", old.plot.symbol)
#' }
#' 

setAllGraphParams <- function(settings)
{
	for(i in seq_along(settings)) {
		setGraphParams(names(settings)[i], settings[[i]])
	}
}

#' @name Graphical parameters
#' @aliases setAllGraphParams getAllGraphParams setGraphParams getGraphParams
#' @export
#' @examples
#' # getAllGraphParams
#' res <- getAllGraphParams()

getAllGraphParams <- function()
{
	.RNMGraphicsEnv$graphPars
}

#' @name Graphical parameters
#' @aliases setAllGraphParams getAllGraphParams setGraphParams getGraphParams
#' @param field A string with the name of the field/option (e.g. loess.line) that the user wishes to change or retrieve
#' @export
#' @examples 
#' # setGraphParams
#' setGraphParams("plot.text", list(alpha=1000, cex=1000, col="orange"))
#' getGraphParams("plot.text")


setGraphParams <- function(field, setting)
{
	# TODO: implement a mapping here so that the list names don't have to coincide with lattice settings
	
	RNMGraphicsStopifnot(field %in% names(.RNMGraphicsEnv$graphPars), msg = "Setting is not in the available graphics options")
	
		# allow the user to replace a subset of the settings
	x <- getGraphParams(field)
	changedSettings <- intersect(names(setting), names(x))
	x[changedSettings] <- setting[changedSettings]
	.RNMGraphicsEnv$graphPars[[field]] <- x
	
	
}

#' @name Graphical parameters
#' @aliases setAllGraphParams getAllGraphParams setGraphParams getGraphParams
#' @export
#' @examples
#' # getGraphParams
#' res <- getGraphParams("legend")


getGraphParams <- function(field)
{
	RNMGraphicsStopifnot(field %in% names(.RNMGraphicsEnv$graphPars), msg = "Setting is not in the available graphics options")
	.RNMGraphicsEnv$graphPars[[field]]
}

getStripFun <- function()
{
	# do.call(strip.custom, getGraphParams("strip"))
	.RNMGraphicsEnv$graphPars[["strip"]]$stripfun
}