R/text_grob.R

In ggpubr: 'ggplot2' Based Publication Ready Plots

#' @include utilities.R
NULL

#' Create a Text Graphical object
#' @description Create easily a customized text grob (graphical object). Wrapper around
#'   \code{\link[grid:grid.text]{textGrob}}.
#' @inheritParams grid::grid.text
#' @param color text font color.
#' @param face font face. Allowed values include one of \code{"plain", "bold",
#'   "italic", "bold.italic"}.
#' @param size font size (e.g.: size = 12)
#' @param lineheight line height (e.g.: lineheight = 2).
#' @param family font family.
#' @param ... other arguments passed to \link[grid:grid.text]{textGrob}.
#' @return  a text grob.
#' @examples
#'text <- paste("iris data set gives the measurements in cm",
#'              "of the variables sepal length and width",
#'              "and petal length and width, respectively,",
#'              "for 50 flowers from each of 3 species of iris.",
#'              "The species are Iris setosa, versicolor, and virginica.", sep = "\n")
#'
#'# Create a text grob
#'tgrob <- text_grob(text, face = "italic", color = "steelblue")
#'# Draw the text
#'as_ggplot(tgrob)
#'
#' @export
text_grob <- function(label, just = "centre", hjust = NULL, vjust = NULL, rot = 0,
                      color = "black", face = "plain", size = NULL, lineheight = NULL,
                      family = NULL, ...)
{

  gp <- grid::gpar(col = color, fontface = face, fontsize = size,
                   lineheight = lineheight, fontfamily = family)

  tgrob <- grid::textGrob(label = label, just = just, hjust = hjust, vjust = vjust,
                          rot = rot, gp = gp, ...)
  tgrob
}