Added argument to provide additional options to tikzpicture.

* Added an argument pictureOptions to the R function `tikz`.
* Added the argument to the C function `TikZ_Setup` and the
  structure tikzDevDesc.
* Made use of the argument, if provided, in the the C
  function `TikZ_StartDevice`.
* Added R documentation and rebuild documentation with roxygen.
* Added argument to vignette (in sec. 3.2 'Usage')

Author: hbuschme

R/tikz.R

@@ -112,6 +112,8 @@
 #' @param verbose A logical value indicating whether diagnostic messages are
 #'  printed when measuring dimensions of strings. Defaults to `TRUE` in
 #'  interactive mode only, to `FALSE` otherwise.
+#' @param pictureOptions A character string that contains additional options 
+#'  provided to the tikzpicture environment. Defaults to the empty string.
 #'
 #' @return `tikz()` returns no values.
 #'
@@ -221,7 +223,8 @@ tikz <- function(file = ifelse(onefile, "./Rplots.tex", "./Rplot%03d.tex"),
                  symbolicColors = getOption("tikzSymbolicColors"), colorFileName = "%s_colors.tex",
                  maxSymbolicColors = getOption("tikzMaxSymbolicColors"),
                  timestamp = TRUE,
-                 verbose = interactive()) {
+                 verbose = interactive(),
+                 pictureOptions = "") {
   tryCatch(
     {
       # Ok, this sucks. We copied the function signature of pdf() and got `file`
@@ -308,7 +311,7 @@ tikz <- function(file = ifelse(onefile, "./Rplots.tex", "./Rplot%03d.tex"),
     TikZ_StartDevice, file, width, height, onefile, bg, fg, baseSize, lwdUnit,
     standAlone, bareBones, documentDeclaration, packages, footer, console,
     sanitize, engine, symbolicColors, colorFileName, maxSymbolicColors,
-    timestamp, verbose
+    timestamp, verbose, pictureOptions
   )
 
   invisible()

man/tikz.Rd

@@ -172,6 +172,7 @@ SEXP TikZ_StartDevice ( SEXP args ){
   int maxSymbolicColors = asInteger(CAR(args)); args = CDR(args);
   Rboolean timestamp = asLogical(CAR(args)); args = CDR(args);
   Rboolean verbose = asLogical(CAR(args)); args = CDR(args);
+  const char *pictureOptions = CHAR(asChar(CAR(args))); args = CDR(args);
 
   /* Ensure there is an empty slot avaliable for a new device. */
   R_CheckDeviceAvailable();
@@ -203,7 +204,7 @@ SEXP TikZ_StartDevice ( SEXP args ){
     if( !TikZ_Setup( deviceInfo, fileName, width, height, onefile, bg, fg, baseSize, lwdUnit,
         standAlone, bareBones, documentDeclaration, packages,
         footer, console, sanitize, engine, symbolicColors, colorFileName,
-        maxSymbolicColors, timestamp, verbose ) ){
+        maxSymbolicColors, timestamp, verbose, pictureOptions ) ){
       /*
        * If setup was unsuccessful, destroy the device and return
        * an error message.
@@ -249,7 +250,8 @@ static Rboolean TikZ_Setup(
   const char *packages, const char *footer,
   Rboolean console, Rboolean sanitize, int engine,
   Rboolean symbolicColors, const char* colorFileName,
-  int maxSymbolicColors, Rboolean timestamp, Rboolean verbose){
+  int maxSymbolicColors, Rboolean timestamp, Rboolean verbose,
+  const char *pictureOptions ){
 
   /*
    * Create tikzInfo, this variable contains information which is
@@ -315,6 +317,7 @@ static Rboolean TikZ_Setup(
   tikzInfo->onefile = onefile;
   tikzInfo->timestamp = timestamp;
   tikzInfo->verbose = verbose;
+  tikzInfo->pictureOptions = calloc_strcpy(pictureOptions);
 
   /* initialize strings, just to be on the safe side */
   strscpy(tikzInfo->drawColor, "drawColor");
@@ -2291,7 +2294,9 @@ static void TikZ_CheckState(pDevDesc deviceInfo)
 
     if ( tikzInfo->bareBones != TRUE )
     {
-      printOutput(tikzInfo, "\\begin{tikzpicture}[x=1pt,y=1pt]\n");
+      printOutput(tikzInfo, "\\begin{tikzpicture}[x=1pt,y=1pt%s%s]\n",
+        tikzInfo->pictureOptions[0] != '\0' ? "," : "",
+        tikzInfo->pictureOptions);
 
       if( tikzInfo->symbolicColors && tikzInfo->outColorFileName)
         printOutput(tikzInfo, "\\InputIfFileExists{%s}{}{}\n", tikzInfo->outColorFileName);

src/tikzDevice.c

@@ -93,6 +93,7 @@ typedef struct {
   char fillColor[32];
   Rboolean timestamp;
   Rboolean verbose;
+  char *pictureOptions;
 } tikzDevDesc;
 
 
@@ -114,7 +115,8 @@ static Rboolean TikZ_Setup(
     const char *packages, const char *footer,
     Rboolean console, Rboolean sanitize, int engine,
     Rboolean symbolicColors, const char *colorFileName,
-    int maxSymbolicColors, Rboolean timestamp, Rboolean verbose );
+    int maxSymbolicColors, Rboolean timestamp, Rboolean verbose,
+    const char *pictureOptions );
 
 
 /* Graphics Engine function hooks. Defined in GraphicsDevice.h . */

src/tikzDevice.h

@@ -740,7 +740,13 @@ formatR::usage(tikz)
 
   \item[footer]
     See \autoref{sec:options}, ``Options That Affect Package Behavior.''
-\end{flexlabelled}
+
+  \item[pictureOptions]
+    A character string containing additional options which are provided
+    to the \code{'tikzpicture'} environment, e.g., 
+    \code{'font=\\\\sffamily'}. The \code{bareBones} argument needs to
+    be \code{FALSE} for this to have an effect.
+  \end{flexlabelled}
 
 The first six options should be familiar to anyone who has used the default
 graphics devices shipped with \lang{R}. The options \code{standAlone}