# -------------------------------------------------------------------------------------------------------------------------  #
  #  -----------------------------------------------------------------------------------------------------------------------   #
  #                                                                                                                            #
  #           File Name              :  gg_add_highlight_to_plot.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        :  ggplot2                                                                                #
  #           Packages Used via NS   :  NA                                                                                     #
  #                                                                                                                            #
  #  -----------------------------------------------------------------------------------------------------------------------   #
  #                                                                                                                            #
  #   gg_add_highlight_to_plot        ( PLOT, xlims, ylims, a=0.01 )                                                                        #
  #                                                                                                                            #
  #                                                                                                                            #
  #                                                     <END FUNCS>                                                            #
  #  -----------------------------------------------------------------------------------------------------------------------   #
  # -------------------------------------------------------------------------------------------------------------------------  #

# gg_add_highlight_to_plot.r
#
# From: http://stackoverflow.com/questions/21369550/add-a-transparent-window-keyhole-ggplot2-grid

    . <- function(PLOT, xlims, ylims, a=.01) {
    ## Adds a rectangular shaded region around the perimeter established by xlims & ylims
      # Plot should be a ggplot object
      # xlims, ylims should be the max/min of the highlight region. 
      # a : the alpha level of the highlighint area.  Value between 0 & 1

    require(ggplot2)

      PLOT + 
        geom_rect(mapping=aes(xmin=-Inf, xmax=min(xlims), ymin=-Inf, ymax=+Inf), fill="black", alpha=a) +
        geom_rect(mapping=aes(xmin=min(xlims), xmax=+Inf, ymin=max(ylims), ymax=+Inf), fill="black", alpha=a) +
        geom_rect(mapping=aes(xmin=min(xlims), xmax=+Inf, ymin=-Inf, ymax=min(ylims)), fill="black", alpha=a) +
        geom_rect(mapping=aes(xmin=max(xlims), xmax=+Inf, ymin=min(ylims), ymax=max(ylims)), fill="black", alpha=a) 
    }

## ----------------------------------------------- ##

    ## EXAMPLE : 
    if (FALSE)  
    {
      lib(ggplot2, quiet=TRUE)

      # Create a plot
      P <- ggplot(mtcars, aes(mpg, wt)) + geom_point(size=3) 
      ## Set the limits for x & y
      xlims <- c(20, 25)
      ylims <- c(3, 3.3)
    
      gg_add_highlight_to_plot(P, xlims, ylims)
    }


# ## Attempting with Annotate, but could not get it to work....  below is some scraps 
# 
# R <- ggplot() + geom_rect(mapping=aes(xmin=-Inf, xmax=min(xlims), ymin=-Inf, ymax=+Inf), fill="black", alpha=a)
# P + annotation_custom(grob=R)
# 
# 
# library(png)
# library(grid)
# img <- readPNG(system.file("img", "Rlogo.png", package="png"))
# g <- rasterGrob(img, interpolate=TRUE)
# 
# qplot(1:10, 1:10, geom="blank") +
#   annotation_custom(g, xmin=-Inf, xmax=Inf, ymin=-Inf, ymax=Inf) +
#   geom_point()