The pdfGraphics section of the \pdftoolbox{} toolbox is for pdf-specific graphics macros.
You can use it to create colorful documents with illustrations, etc.

\subsection{Colors}

In {\tt pdfGraphics/colors.tex}, \pdftoolbox{} provides macros for coloring text and areas of your document.

\macroexp{\color <color space>{<code>}/cr\color {<name>}}
Switches the color of the document.
In its first form, {\it color space} corresponds to either {\tt rgb} or {\tt cmyk}, and {\it code} is either an rgb or cmyk code.
In its second form, if {\it name} is a predefined color name (see \gotomacro\definecolor), the color is switched to it.
\emacroexp

\macroexp{\localcolor <color space>{<code>}{<text>}/cr\localcolor {<name>}{<text>}}
Switches the color of {\it text}, according to the options provided (see \gotomacro\color).
\emacroexp

\macroexp{\definecolor {<name>}{<color space>}{<code>}}
Defines a color of name {\it name} whose space is {\it color space} (either {\tt rgb} or {\tt cmyk}) of code {\it code} (either an rgb or cmyk code).
\emacroexp

\macroexp{\letcolor {<new name>}{<name>}}
Defines a color of name {\it new name} to be equal to the existing color of name {\it name}.
\emacroexp

\macroexp{\definecolormacro {<name>}{<color space>}{<code>}}
Calls \gotomacro\definecolor, and also defines a macro of name {\it name} which is equivalent to \inlinecode|\localcolor <color space>{<code>}{#1}|.

The following colors are defined:

\centerline{\red{red} \blue{blue} \green{green} \yellow{yellow} \orange{orange} \purple{purple} \highlightbox{black}{\white{white}} \black{black} \darkgreen{darkgreen} \grey{grey}}
\emacroexp

\macroexp{\highlightbox <color space>{<code>}{<material>}/cr
\highlightbox {<name>}{<material>}}
Colors the background of the material {\it material} according to the color provided.
For example \inlinecode|\highlightbox {red}{pdfToolbox}| will yield \highlightbox{red}{pdfToolbox}.
\emacroexp

\macroexp{\coloredbox <color space>{<code>}{<material>}/cr
\coloredbox {<name>}{<material>}}
Like \gotomacro\highlightbox{} but adds a buffer of space around {\it material} in accordance with \macro\bufferwidth\anchormacro\bufferwidth{} and \macro\bufferheight\anchormacro\bufferheight.
For example the following code: \inlinecode|\coloredbox {red}{pdfToolbox}|; will yield \coloredbox{red}{pdfToolbox}.
\emacroexp

\macroexp{\framecoloredbox <color space>{<code>}{<material>}/cr
\framecoloredbox {<name>}{<material>}}
Like \gotomacro\coloredbox{} but adds a frame around {\it material} of width \macro\framewidth.
For example \inlinecode|\framecoloredbox {red}{pdfToolbox}| will yield \framecoloredbox{red}{pdfToolbox}.
\emacroexp

\macroexp{\framebox {<material>}}
Adds a frame around {\it material} with a buffer of \macro\bufferwidth{} and \macro\bufferheight{} of width \macro\framewidth.
\emacroexp

\macroexp{\curvedcolorbox {<stroke color>}{<bg color>}{<material>}{<curve control>}}
Creates a curved color framed box around {\it material} with frame color {\it stroke color} and background color {\it bg color} (which may be names or of the form \inlinecode|<color space>{<code>}|.
The curve's stroke width is determined by \macro\curvewidth, and the buffer around the material is determined by \macro\curvebuffer.

{\it control} is a sequence of $8$ symbols of the form \getmacrousageB{<bline><bldot><lline><tldot><tline><trdot><rline><brdot>} where each $\langle{\tt X\it dot}\rangle$ corresponds to whether or not a corner is curved or not
({\tt bl} for bottom left, {\tt tl} for top left, etc.), and each $\langle{\tt X\it line}\rangle$ corresponds to whether or not a border is drawn or not ({\tt b} for bottom, {\tt l} for left, etc.).
For a corner, {\tt.} corresponds to a curve and {\tt X} for a right corner.
For a border, {\tt-} corresponds to drawing the line and \inlinecode|_| to not.

A shadow of color \macro\boxshadowcolor{} is added to to the box, at an x and y offset of \macro\shadowxoff{} and \macro\shadowyoff{} respectively.

So for example:

\displaycode{%
\curvedcolorbox{blue}{red}{\color{white}pdfToolbox}{-.-.-.-.}&\cr
\curvedcolorbox{blue}{red}{\color{white}pdfToolbox}{-X-.-.-.}&\cr
\curvedcolorbox{blue}{red}{\color{white}pdfToolbox}{-.-X-.-.}&\cr
\curvedcolorbox{blue}{red}{\color{white}pdfToolbox}{-.-.-X-.}&\cr
\curvedcolorbox{blue}{red}{\color{white}pdfToolbox}{-.-.-.-X}&\cr
\curvedcolorbox{blue}{red}{\color{white}pdfToolbox}{_X-X_X-X}&\cr
\curvedcolorbox{blue}{red}{\color{white}pdfToolbox}{_._._._.}&\cr
\curvedcolorbox{blue}{red}{\color{white}pdfToolbox}{-X_X-X_X}&}
\emacroexp

\macroexp{\fakebold {<material>}}
Bolds the material {\it material} (essentially just thickening the stroke width according to \macro\fakeboldwidth).
\emacroexp

\macroexp{\flip {<material>}}
\quitvmode\flip{flips} {\it material} about its vertical axis.
\emacroexp

\subsection{Colorboxes}

In {\tt pdfGraphics/colorboxes.tex}, \pdftoolbox{} provides macros for pretty printing textboxes (ppboxes).
These are simply colored textboxes which can split across pages.
There are two kinds of pretty textboxes: {\tt ppbox}es and {\tt linedppbox}es.

\macroexp{\bppbox {<bg color>}{<stroke color>}{<fg color>}[<curve control>] ... \eppbox}
This creates a {\tt ppbox}, which is just a wrapper around \gotomacro\curvedcolorbox.
\emacroexp

\macroexp{\blinedppbox {<bg color>}{<stroke color>}{<fg color>} ... \elinedppbox}
This creates a colored textbox with a rule down the left side.
For example:

\blinedppbox{red}{black}{white}
This is a {\tt linedppbox} with a red background, black stroke, and white text.
\elinedppbox

The width of the rule is determined by \macro\pprulewd, the vertical buffer within the box (around the text) is determined by \macro\pprulevbuf, and the horizontal buffer on the left is \macro\pprulehbuf.
\emacroexp

\subsection{Illustrating}

In {\tt pdfGraphics/pdfdraw.tex}, \pdftoolbox{} provides macros for creating illustrations.

\bwarning
This feature scares me.
Its implementation is a mess and I am scared to change it; but I will need to at some point.
\eppbox

\macroexp{\bdrawing...\edrawing}
Begin a drawing environment.
The drawing environment is a plane as large as the drawings within it.
$(0,0)$ corresponds to the bottom left corner.
\emacroexp

\macroexp{\addnode {<text>}{<x>}{<y>}{<name>}}
Creates a node by the name of {\it name} with text {\it text} at coordinate $(x,y)$.
You can access the following values (called node-relative coordinates): {\tt<name>.left}, {\tt<name>.top}, {\tt<name>.right}, {\tt<name>.bottom}, {\tt<name>.xcenter}, {\tt<name>.ycenter}.
\emacroexp

\macroexp{\drawpath {<start x>}{<start y>}{<end x>}{<end y>}{<x off>}{<y off>}{<start cap>}{<end cap>}{<color>}}\hfill\break
Draws a line from $(\hbox{\it start x},\hbox{\it start y})$ to $(\hbox{\it end x},\hbox{\it end y})$.
This is offset by {\it off x} on the $x$-axis and {\it off y} on the $y$-axis (these are dimensions).
{\it start cap} is the linecap used at the starting point, and {\it end cap} is the linecap used at the end point (see \gotomacro\definelinecap).
The line is drawn in the color {\it color}.

The coordinates may be numeric values or node-relative coordinates (see \gotomacro\addnode).
\emacroexp

\macroexp{\drawbezier {<start x>}{<start y>}{<end x>}{<end y>}{<off>}{<curvature>}{<start cap>}{<end cap>}{<color>}}\hfill\break
Draws a curve from $(\hbox{\it start x},\hbox{\it start y})$ to $(\hbox{\it end x},\hbox{\it end y})$ with curvature {\it curvature}.
This is offset by {\it off}, which must be a pair of the form \inlinecode|{<x off>}{<y off>}| corresponding to the $x$-axis offset and $y$-axis offset respectively (dimensions).
{\it start cap} is the linecap used at the starting point, and {\it end cap} is the linecap used at the end point (see \gotomacro\definelinecap).
The line is drawn in the color {\it color}.

The coordinates may be numeric values or node-relative coordinates (see \gotomacro\addnode).
\emacroexp

\macroexp{\definelinecap {<name>}{<code>}{<width>}}
Defines a linecap by the name of {\it name}.
{\it code} is the code which draws the linecap (see \gotoanchor{internal-pdfdraw}{Internals of pdfDraw}), and {\it width} is the width of the linecap.

The provided linecaps are:

\def\drawlinecap#1{$\vcenter{\hbox to\csname linecap@#1@wd\endcsname pt{\pdfliteral{q \_pdfdraw_nattrans, 1 j 1 J \_pdfdraw_strokewidth\_space w \csname linecap@#1\endcsname\_space Q}\hfil}}$}
\centerline{\vbox{\tabskip=.5cm\halign{&\hfil\gdef\@@{#}{\tt\@@}: \tabskip=\z@&\_gobble{#}\drawlinecap\@@\tabskip=.5cm\cr
>&&<&&|-&&-|&&>>&&<<&&o&\cr
}}}

There is also an empty linecap {\tt-}.
\emacroexp

Outside of drawing environments, \pdftoolbox{} provides a macro to make diagrams, \macro\drawdiagram.
Its usage is \getmacrousageB{\drawdiagram {<table>}{<arrows>}}.
{\it table} is a normal \TeX{} alignment table (similar format as \macro\halign{}, without the preamble).
{\it arrows} is a collection of \gotomacro\diagarrow{} macro calls.

\macroexp{\diagarrow {<options>}}
Draws an arrow in a \macro\drawdiagram{} diagram.
{\it options} contains the following keys:
\blist
    \item {\tt from} (required): the cell from which to start the arrow.
        Cells start indexing at \inlinecode|{1,1}| for the top left cell where the first number is the row and the second the column;
    \item {\tt to} (required): the cell to end the arrow;
    \item {\tt left cap} (default {\tt-}): the start linecap;
    \item {\tt right cap} (default {\tt>}): the end linecap;
    \item {\tt color} (default {\tt black}): the color to draw the arrow in;
    \item {\tt x off} (default {\tt0pt}): the $x$-axis offset;
    \item {\tt y off} (default {\tt0pt}): the $y$-axis offset;
    \item {\tt text}: the text to add on the arrow;
    \item {\tt x distance} (default {\tt0pt}): the amount to move the text on the $x$-axis;
    \item {\tt y distance} (default {\tt0pt}): the amount to move the text on the $y$-axis;
    \item {\tt slide} (default {\tt.5}): where to place the text relative to the arrow;
    \item {\tt curve}: the amount to curve the arrow;
    \item {\tt dashed} (valueless): add to make the arrow line dashed;
    \item {\tt dotted} (valueless): add to make the arrow line dotted;
    \item {\tt origin orient}: the placement of the start of the arrow relative to the origin\hfill\break (a pair like \inlinecode|{left,bottom}|);
    \item {\tt dest orient}: the placement of the end of the arrow relative to the destination\hfill\break (a pair like \inlinecode|{left,bottom}|).
\elist
\emacroexp

So for example, 

\bgroup\parindent=\z@
\blisting
\drawdiagram{
    A&B\cr
    C&D
}{
    \diagarrow{from={1,1}, to={1,2}, left cap=<<}
    \diagarrow{from={1,2}, to={2,2}, color=rgb{1 0 0}, text={hello}, x distance=.5cm}
    \diagarrow{from={2,2}, to={2,1}, curve=10pt, origin orient={xcenter,bottom}, dest orient={xcenter,bottom}}
    \diagarrow{from={2,1}, to={1,1}, dashed, left cap=o, right cap=o}
}
\elisting
\egroup

Will yield

\centerline{\drawdiagram{
    A&B\cr
    C&D
}{
    \diagarrow{from={1,1}, to={1,2}, left cap=<<}
    \diagarrow{from={1,2}, to={2,2}, color=rgb{1 0 0}, text={hello}, x distance=.5cm}
    \diagarrow{from={2,2}, to={2,1}, curve=10pt, origin orient={xcenter,bottom}, dest orient={xcenter,bottom}}
    \diagarrow{from={2,1}, to={1,1}, dashed, left cap=o, right cap=o}
}}

Between each row of the diagram, space of width \macro\diagrowbuf{} is added.
Between each column, \macro\diagcolbuf.
The height of each row is at least \macro\diagrowheight{} and the width of each column is at least \macro\diagcolwidth.

\subsection{Listings}

In {\tt pdfGraphics/ptb-listings.tex}, \pdftoolbox{} provides macros for writing code listings.
The mechanism for how \pdftoolbox's listing works is greatly inspired by Petr Ol\v s\'ak's \url{https://ctan.org/pkg/optex?lang=en}{Op\TeX}.
The mechanism is largely the same, though the implementation may differ.

\macroexp{\setupverb}
This will set up a verbatim environment, essentially changing all special category codes to $12$.
\emacroexp

\macroexp{\blisting <first line> ... \elisting}
Writes {\tt...} in a verbatim environment, with syntax highlighting if set (see \gotomacro\loadsyntax{} and \gotomacro\setsyntax).
{\it first line} (the rest of the line after \macro\blisting) will be executed as normal (so you can set syntax here; see \gotomacro\setsyntax).
The line number of each line in the listing is stored in \macro\lstlinenum\anchormacro\lstlinennum, which is not reset after each listing.
\emacroexp

\macroexp{\listfile {<file>}[<start>-<end>]}
Creates a listing from file {\it file}.
Reads between lines {\it start} and {\it end} (inclusive).
If {\it start} isn't provided, starts from $1$.
If {\it end} isn't provided reads until the end (actually a large number).
\emacroexp

\macroexp{\loadsyntax {<language>}}
Loads in the necessary information for {\it language} syntax highlighting.
The information is input from the ptb-syntax file {\tt ptb-syntax-{\it language}}.
See the \gotoanchor{internal-listings}{internals of this section} for more information on how to write such a file.

Currently \pdftoolbox{} provides support for syntax highlighting of \TeX{} ({\it language} is {\tt TeX}) and of C ({\it language} is {\tt C}).
\emacroexp

\macroexp{\setsyntax {<language>}}
Sets the syntax to be used for syntax highlighting.
This must be used after \macro\loadsyntax{} for {\it language}.
\emacroexp

Some useful macros for customizing syntax highlighting are the following:
\blist
    \item \macro\lstlineskip: the space added between each line in the listing;
    \item \macro\lstvbuf: the space added before and after the listing;
    \item \macro\lstlinenumbuf: the kerning added between the number and code on each line in the listing;
    \item \macro\lstnumfontset: sets the font (and whatever else, e.g. color) of the numbers of each line in the listing;
    \item \macro\lstfontset: sets the font (and whatever else, e.g. color) of the content of each line;
    \item \macro\lststrut: the strut added to each line in the listing (for uniform spacing).
\elist

Some useful colors to be aware of:
\blist
    \item {\tt lst-fg}: the default foreground color of the listing;
    \item {\tt lst-bg}: the background color of the listing;
    \item {\tt lst-comment}: the colors of comments (must be activated in the ptb-syntax file);
    \item {\tt lst-number}: the colors of numbers (must be activated in the ptb-syntax file).
\elist

\pdftoolbox{} also provides a token list \macro\everylisting{} which is inserted before every listing.
So for example doing \inlinecode|\everylisting={\lstlinenum=0}| will reset the line numbering before each listing.