% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/latex-grob.R
\name{latex_grob}
\alias{latex_grob}
\alias{grid.latex}
\title{Create a grid grob from a LaTeX expression}
\usage{
latex_grob(
  tex,
  x = grid::unit(0.5, "npc"),
  y = grid::unit(0.5, "npc"),
  default.units = "npc",
  hjust = 0.5,
  vjust = 0.5,
  rot = 0,
  math_font = "",
  max_width = 0,
  tex_style = "",
  input_mode = c("mixed", "math"),
  render_mode = c("typeface", "path"),
  debug = FALSE,
  name = NULL,
  gp = grid::gpar()
)

grid.latex(tex, ...)
}
\arguments{
\item{tex}{Character string of LaTeX math code.}

\item{x, y}{Position in grid coordinates.}

\item{default.units}{Units for x, y if given as numeric.}

\item{hjust, vjust}{Horizontal/vertical justification. Accepts the
usual numeric values in \verb{[0, 1]}. As a convenience, \code{hjust} also
accepts the strings \code{"left"}/\code{"bbleft"}, \code{"center"}/\code{"centre"}/
\code{"middle"}/\code{"bbcentre"}, and \code{"right"}/\code{"bbright"}; \code{vjust} accepts
\code{"bottom"}, \code{"center"}/\code{"centre"}/\code{"middle"}, \code{"top"}, and
\code{"baseline"}. \code{"baseline"} aligns the formula's math baseline with
the anchor point — handy for placing a formula in flowing text.}

\item{rot}{Rotation angle in degrees, counter-clockwise (default: 0).
Matches the \code{rot} parameter of \code{\link[grid]{textGrob}}.}

\item{math_font}{Name of the math font to use (e.g., \code{"stix"}).
Use \code{""} (default) for Lete Sans Math, which pairs with R's
default sans-serif text font.
See \code{\link{available_math_fonts}} for loaded fonts.}

\item{max_width}{Numeric maximum width in big points for automatic
line wrapping.  Use \code{0} (default) for no wrapping.}

\item{tex_style}{Character: TeX style override. One of \code{""}
(default; let the parser decide), \code{"display"}, \code{"text"},
\code{"script"}, or \code{"scriptscript"}. See
\code{\link{latex_grob}} for the semantics of each value.}

\item{input_mode}{How \code{tex} is interpreted before being parsed.
\code{"mixed"} wraps the input in \code{\\text{...}} so the string
reads as ordinary text and \code{$...$} (or \code{\\(...\\)}) opens
math mode, matching document-level LaTeX semantics. Useful for labels
that arrive from external sources mixing prose and math without explicit
\code{\\text{}} markers. \code{"math"} (default) is the standard
MicroTeX behaviour --- the whole string is treated as math, so unwrapped
prose renders as spaced math italics. The default can be changed globally via
\code{\link{latex_options}(input_mode = "mixed")}. See \code{\link{latex_wrap}}
for details on the wrapping process.}

\item{render_mode}{Character string: \code{"typeface"} (default) renders
glyphs as native text using the math font, producing
selectable/accessible text in PDF and SVG output.
Bundled math fonts and any registered via \code{\link{load_font}}
are read directly from their OTF files --- no system-wide font
install is required.
Falls back to path mode automatically on devices that lack the
R \eqn{\geq} 4.3 glyph engine (e.g., the base \code{pdf()} device).
For selectable PDF output, prefer \code{\link[grDevices]{cairo_pdf}}.
\code{"path"} renders math symbols as filled vector paths (works on
all devices but text is not selectable in PDF/SVG).}

\item{debug}{Logical; if \code{TRUE}, draws diagnostic overlays on the
grob --- the full bounding box (dashed gray), the baseline (solid
red), the depth line (dashed gray), and a small dot at each
MicroTeX draw record's origin. Useful for checking positioning and
diagnosing vertical alignment.}

\item{name}{Optional grob name.}

\item{gp}{Graphical parameters (see \code{\link[grid]{gpar}}).
Common entries: \code{col} (formula foreground), \code{fontfamily}
/ \code{fontface} (text font), \code{fontsize} / \code{cex}
(formula size), and \code{lineheight} (multi-line spacing). See
\code{\link{latex_grob}} for how each of these flows through
MicroTeX.}

\item{...}{Additional arguments passed to \code{\link{latex_grob}}.}
}
\value{
A \code{grid} grob of class \code{"latexgrob"}.

Invisibly returns the grob.
}
\description{
Parses a LaTeX math expression and returns a grid grob object
that renders the formula using native grid graphics primitives.
The grob supports standard grid queries such as \code{grobWidth()},
\code{grobHeight()}, \code{grobX()}, and \code{grobY()}.

A convenience wrapper that creates a \code{\link{latex_grob}} and
immediately draws it on the current device via
\code{\link[grid]{grid.draw}}.
}
\details{
\subsection{Controlling TeX style with \code{tex_style}}{

\code{tex_style} selects the size-and-spacing regime MicroTeX applies to
the whole expression. It changes the \emph{style} (display vs. text), not
the font size --- size is always set via \code{gp$fontsize} / \code{gp$cex};
style-dependent shrinking (for \code{"script"} and \code{"scriptscript"}) is
applied on top of that size.
\itemize{
\item \code{""} (default): let the parser choose based on the delimiters in
\code{tex}. Inline delimiters (single \code{$}, or \verb{\\(...\\)}) produce
\code{"text"} style; display delimiters (double \verb{$$}, or \verb{\[...\]})
produce \code{"display"} style. If the string has no delimiters,
MicroTeX defaults to \code{"text"} style.
\item \code{"display"}: force display style. Large operators (\verb{\\sum},
\verb{\\int}, \verb{\\prod}) render at their full size, limits are placed
above/below rather than as subscripts/superscripts, and fractions
use full-size numerators and denominators. Useful when you want a
display-style equation inline in a label, legend, or
\code{element_latex()} title.
\item \code{"text"}: force text (inline) style. Big operators shrink to their
inline size and limits attach as scripts. The right choice for
formulas embedded in a line of prose.
\item \code{"script"}: force script style --- the size normally used for
first-level subscripts and superscripts. Produces a smaller,
tighter layout; mainly useful for callouts or sub-labels where a
compact equation is wanted.
\item \code{"scriptscript"}: force scriptscript style --- the smallest style,
used by TeX for doubly-nested scripts. Rarely needed on its own;
primarily for very dense annotations.
}

\code{tex_style} applies to the entire expression. To override the style
of a sub-expression from within \code{tex}, use the inline TeX commands
\verb{\\displaystyle}, \verb{\\textstyle}, \verb{\\scriptstyle}, or
\verb{\\scriptscriptstyle}.
}

\subsection{Graphical parameters (\code{gp})}{
\itemize{
\item \code{col}: default foreground color for the formula. Individual
elements can still be overridden with an inline \verb{\\textcolor}
command in the LaTeX string.
\item \code{fontfamily} / \code{fontface}: control the appearance of text inside
\verb{\\text} and \verb{\\mbox} blocks. For example, \code{gpar(fontfamily = "serif")} renders \verb{\\text} content in R's serif family. Any font
available to R's graphics system works --- base families
(\code{"sans"}, \code{"serif"}, \code{"mono"}) as well as fonts registered via
\pkg{showtext} or \pkg{systemfonts}. Math symbols always use the
selected math font (see \code{math_font}).

\code{fontfamily} \emph{also} drives MicroTeX's layout metrics for non-math
text: the matching system font is resolved via \pkg{systemfonts},
a minimal metrics file is generated on first use and cached under
\code{tools::R_user_dir("gridmicrotex", "cache")}, so MicroTeX's
spacing of \verb{\\text} blocks stays in sync with what \pkg{grid}
actually draws. When \code{fontfamily} is unset, the R default
(\code{"sans"}) is used. No manual font loading is required for text
fonts; \code{\link[=load_font]{load_font()}} remains only for adding custom \strong{math}
fonts.
\item \code{fontsize} / \code{cex}: formula size is \code{fontsize * cex} big points
(default 20 * 1). Both math and text scale together. The effective
size is baked into the parsed layout, so downstream viewports that
inherit \code{cex} will not re-scale the grob (matching \code{textGrob}
semantics when \code{gp} is set explicitly).
\item \code{lineheight}: controls multi-line spacing (default 1.2). The
inter-line gap is \code{(lineheight - 1) * fontsize} big points.
}
}
}
\examples{
\donttest{
  g <- latex_grob(r"($\fcolorbox{red}{yellow}{\frac{a}{b}}$)",
                  x = grid::unit(0.3, "npc"),
                  y = grid::unit(0.3, "npc"),
                  gp = grid::gpar(fontsize = 30))
  grid::grid.draw(g)
  # Red formula
  grid::grid.draw(latex_grob("$x^{2}$",
                             x = grid::unit(0.3, "npc"),
                             y = grid::unit(0.8, "npc"),
                             gp = grid::gpar(col = "red")))

                             # Rotated formula
  grid::grid.draw(latex_grob(r"($\colorbox{BurntOrange}{x^{2}} + y^{2}$)",
                             x = grid::unit(0.6, "npc"),
                             y = grid::unit(0.3, "npc"),
                             gp = grid::gpar(fontsize = 24),
                             rot = 45))

  grid.latex(r"($\textcolor{red}{x^{2}} + y^{2} = z^{2}$)",
             x = grid::unit(0.6, "npc"),
             y = grid::unit(0.8, "npc"),)
}
}
\seealso{
\code{\link{grid.latex}}, \code{\link{latex_dims}},
\code{\link{geom_latex}}, \code{\link{available_math_fonts}},
\code{\link{latex_wrap}}, \code{\link{latex_options}}
}
