# -------------------------------------------------------------------------------------------------------------------------  #
  #  -----------------------------------------------------------------------------------------------------------------------   #
  #                                                                                                                            #
  #           File Name              :  ggsave.out.r                                                                           #
  #           Last Updated Funclist  :  19 Feb 2015,  1:05 PM (Thursday)                                                       #
  #                                                                                                                            #
  #           Author Name            :  Rick Saporta                                                                           #
  #           Author Email           :  RickSaporta@gmail.com                                                                  #
  #           Author URL             :  www.github.com/rsaporta                                                                #
  #                                                                                                                            #
  #           Packages Called        :  NA                                                                                     #
  #           Packages Used via NS   :  NA                                                                                     #
  #                                                                                                                            #
  #  -----------------------------------------------------------------------------------------------------------------------   #
  #                                                                                                                            #
  #   ggsave.out         ( nm, outDir=plots.p(), subFolder="", open=FALSE, plot=last_plot(), ext="png", width=8                #
  #                        , height=8, footnote=NULL, limitsize=TRUE )                                                         #
  #                                                                                                                            #
  #                                                                                                                            #
  #                                                     <END FUNCS>                                                            #
  #  -----------------------------------------------------------------------------------------------------------------------   #
  # -------------------------------------------------------------------------------------------------------------------------  #

ggsave.out <- function(nm, outDir=plots.p(), subFolder="", open=FALSE, plot = last_plot(), ext="png", width=8, height=8, footnote=NULL, limitsize=TRUE, units=c("in", "cm", "mm"), dpi=ifelse(powerpoint, 600, 300), powerpoint=FALSE) {

    require(grid)

    units <- match.arg(units)

    ## Allow for the first argument to be the gg graph object itself
    ## in which case the f.out will be the same as the object name
    if (!missing(nm)) {
      if (inherits(nm, c("gg", "gtable"))) {
        plot <- nm
        nm <- make.names(as.character(capture.output(substitute(nm))))

        if (grepl("^P\\..", nm))
          nm <- sub("^P\\.", "", nm)
      } else if (!is.character(nm)){
        stop ("'nm' must be a character name of a plot objer or the object itself")
      }
    } else {
      if (missing(plot))
        stop ("either 'nm' or 'plot' must be set")
      nm <- substitute(plot)
    }

    ## clean up nm -- namely no slashes
    nm <- gsub(regOr(c("/", "\\\\")), "_", nm)

    if (identical(subFolder, FALSE) || isNA(subFolder))
      subFolder <- NULL
    dir <- as.path(outDir, subFolder)
    if (!file.exists(dir))
      dir.create(dir)
    f.out <- as.path(dir, nm, ext=ext)


    if (missing(footnote) && is.null(footnote) &&  grepl("/orch/", outDir) && !isTRUE(powerpoint))
      footnote <- orchardFootNote()

    if ( isTRUE(footnote) ||  (is.character(footnote) && nchar(footnote) <= 15 && substr(tolower(footnote), 1, 4) == "orch" ) )
      footnote <- orchardFootNote()

    if (powerpoint) {
      if (missing(width))
        width <- unit(6, units=units)
      if (missing(height))
        height <- unit(4, units=units)
    }

    ## add in footnote
    if (FALSE) ## OLD: 
      g <- arrangeGrob(plot, sub=footnote)
    ## NEW: 
    g <- arrangeGrob(plot, bottom=footnote)

    ret <- try(ggsave(file=f.out, plot=g, width=width, height=height, units=units, dpi=dpi, limitsize=limitsize), silent=TRUE)
    if (isErr(ret)) {
      warning("as of Aug 2015 there is an issue with ggsave.out, specifically adding the footnote. It will be ignored")
      ret <- ggsave(file=f.out, plot=plot, width=width, height=height, units=units, limitsize=limitsize)
    }

    if (open)
      try(system(paste0("open '", path.expand(f.out), "'")))

    if (!is.null(ret))
      return(ret)

    return(f.out)
}