%% BEGIN psd-text.tex

\part{Text Tricks\label{P-text}}

\Section{Framed boxes\label{S-framebox}}

The macros for framing boxes take their argument, put it in an "\hbox", and
put a PostScript frame around it. (They are analogous to \LaTeX's "\fbox").
Thus, they are composite objects rather than pure graphics objects. In
addition to the graphics parameters for \n\psframe, these macros use the
following parameters:
\begin{description}

\pitem[framesep=dim]
  Distance between each side of a frame and the enclosed box.

\pitem[boxsep=true/false]
  When "true", the box that is produced is the size of the frame or whatever
that is drawn around the object. When "false", the box that is produced is the
size of whatever is inside, and so the frame is ``transparent'' to \TeX. This
parameter only applies to \n\psframebox, \n\pscirclebox, and \n\psovalbox.

\end{description}

Here are the three box-framing macros:
\begin{description}

\oitem  \psframebox{stuff}

  A simple frame (perhaps with rounded corners) is drawn using \n\psframe. The
"*" option is of particular interest. It generates a solid frame whose color
is \p{fillcolor} (rather than \p{linecolor}, as with the closed graphics
objects). Recall that the default value of \p{fillcolor} is "white", and so
this has the effect of blotting out whatever is behind the box. For example,
\begin{MEx}(3,2)
  \pspolygon[fillcolor=gray,fillstyle=crosshatch*](0,0)(3,0)
    (3,2)(2,2)
  \rput(2,1){\psframebox*[framearc=.3]{Label}}
\end{MEx}

\oitem  \psdblframebox{stuff}

  This draws a double frame. It is just a variant of \n\psframebox, defined by
\begin{LVerb}
  \newpsobject{psdblframebox}{psframebox}{doublesep=\pslinewidth}
\end{LVerb}
For example,
\begin{example}
  \psdblframebox[linewidth=1.5pt]{%
    \parbox[c]{6cm}{\raggedright A double frame is drawn
    with the gap between lines equal to \texttt{doublesep}}}
\end{example}

\oitem  \psshadowbox{stuff}

  This draws a single frame, with a shadow.
\begin{example**}
  \psshadowbox{\textbf{Great Idea!!}}
\end{example**}
You can get the shadow with \n\psframebox{} just be setting the \p{shadowsize}
parameter, but with \n\psframebox{} the dimensions of the box won't reflect the
shadow (which may be what you want!).

\oitem  \pscirclebox{stuff}

  This draws a circle. With \p{boxsep=true}, the size of the box is close to
but may be larger than the size of the circle. For example:
\begin{example**}
  \pscirclebox{\begin{tabular}{c} You are \\ here \end{tabular}}
\end{example**}
is distributed with
\oitem  \cput<{angle}\c~>{stuff}

  This combines the functions of \n\pscirclebox{} and \n\rput. It is like
\begin{LVerb*}
  \rput{<angle>}(x0,y0){\pscirclebox*[<par>]{<stuff>}}
\end{LVerb*}
but it is more efficient. Unlike the \n\rput{} command, there is no argument
for changing the reference point; it is always the center of the box. Instead,
there is an optional argument for changing graphics parameters. For example
\begin{MEx*}(2,1)
  \cput[doubleline=true](1,.5){\large $K_1$}
\end{MEx*}

\oitem  \psovalbox{stuff}

  This draws an ellipse. If you want an oval with square sides and rounded
corners, then use \n\psframebox{} with a positive value for \p{rectarc} or
\p{linearc} (depending on whether \p{cornersize} is "relative" or "absolute").
Here is an example that uses \p{boxsep=false}:
\begin{example**}
  "\parbox{\marginparwidth}{
  At the introductory price of
  \psovalbox[boxsep=false,linecolor=darkgray]{\$13.99},
  it pays to act now!
  "}
\end{example**}

\oitem  \psdiabox{stuff}

  \n\psdiabox{} draws a diamond.
\begin{example**}
  \psdiabox[shadow=true]{\Large\textbf{Happy?}}
\end{example**}

\oitem  \pstribox{stuff}

  \n\pstribox{} draws a triangle.
\begin{example**}
  \pstribox[trimode=R,framesep=5pt]{\Large\textbf{Begin}}
\end{example**}
  The triangle points in the direction:
\begin{Ex}
  \Par{trimode=*U/D/R/L}
\end{Ex}
If you include the optional "*", then an equilateral triangle is drawn,
otherwise, you get the minimum-area isosceles triangle.
\begin{example**}
  \pstribox[trimode=*U]{\Huge Begin}
\end{example**}

\end{description}

You can define variants of these box framing macros using the \n\newpsobject{}
command.

If you want to control the final size of the frame, independently of the
material inside, nest <stuff> in something like \LaTeX's "\makebox" command.


\Section{Clipping\label{S-clipping}}

The command
  \Mac  \clipbox`[dim]'{stuff}
puts <stuff> in an "\hbox" and then clips around the boundary of the box, at a
distance <dim> from the box (the default is "0pt").

The \n\pspicture{} environment also lets you clip the picture to the boundary.

The command
  \Mac  \psclip{graphics} \ldots\ \Main\endpsclip
sets the clipping path to the path drawn by the graphics object(s), until the
\n\endpsclip{} command is reached.  \n\psclip{} and \n\endpsclip{} must be
properly nested with respect to \TeX{} grouping. Only pure graphics (those
described in Part \ref{P-graphics} and \n\pscustom) are permitted. An
"Overfull \hbox" warning indicates that the <graphics> argument contains
extraneous output or space. Note that the
graphics objects otherwise act as usual, and the \n\psclip{} does not otherwise
affect the surrounded text. Here is an example:
\begin{example**}
  \parbox{4.5cm}{%
   \psclip{\psccurve[linestyle=none](-3,-2)
     (0.3,-1.5)(2.3,-2)(4.3,-1.5)(6.3,-2)(8,-1.5)(8,2)(-3,2)}
  "\def\baselinestretch{.85}\small
   ``One of the best new plays I have seen all year: cool, poetic,
   ironic \ldots'' proclaimed \emph{The Guardian} upon the London
   premiere of this extraordinary play about a Czech director and
   his actress wife, confronting exile in America.\vspace{-1cm}
   \endpsclip}
\end{example**}

If you don't want the outline to be painted, you need to include
\p{linestyle=none} in the parameter changes. You can actually include more
than one graphics object in the argument, in which case the clipping path is
set to the intersection of the paths.

\n\psclip{} can be a useful tool in picture environments. For example, here it
is used to shade the region between two curves:
\begin{MEx}(4,4)
  \psclip{%
    \pscustom[linestyle=none]{%
      \psplot{.5}{4}{2 x div}
      \lineto(4,4)}
    \pscustom[linestyle=none]{%
      \psplot{0}{3}{3 x x mul 3 div sub}
      \lineto(0,0)}}
  \psframe*[linecolor=gray](0,0)(4,4)
  \endpsclip
  \psplot[linewidth=1.5pt]{.5}{4}{2 x div}
  \psplot[linewidth=1.5pt]{0}{3}{3 x x mul 3 div sub}
  \psaxes(4,4)
\end{MEx}

\begin{drivers}
  The clipping macros use \n\pstverbscale{} and \n\pstVerb. Don't be surprised
if PSTricks's clipping does not work or causes problem---it is never robust.
"\endpsclip" uses "initclip". This can interfere with other clipping
operations, and especially if the \TeX{} document is converted to an
Encapsulated PostScript file. The command \n\AltClipMode{} causes \n\psclip{}
and \n\endpsclip{} to use "gsave" and "grestore" instead. This bothers some
drivers, especially if \n\psclip{} and \n\endpsclip{} do not end up on the same
page.
\end{drivers}

\Section{Rotation and scaling boxes\label{S-rotation}}

There are versions of the standard box rotation macros:
\begin{Ex}
  \object  \rotateleft{stuff}
  \object  \rotateright{stuff}
  \object  \rotatedown{stuff}
\end{Ex}
<stuff> is put in an "\hbox" and then rotated or scaled, leaving the
appropriate amount of spaces. Here are a few uninteresting examples:
\begin{example**}
  \Large\bfseries \rotateleft{Left} \rotatedown{Down} \rotateright{Right}
\end{example**}


There are also two box scaling macros:
\begin{description}

\mitem  \psscalebox{num1 `num2'}{stuff}

  If you give two numbers in the first argument, <num1> is used to scale
horizontally and <num2> is used to scale vertically. If you give just one
number, the box is scaled by the same in both directions. You can't scale by
zero, but negative numbers are OK, and have the effect of flipping the box
around the axis. You never know when you need to do something like
\psscalebox{-1 1}{this} ("\psscalebox{-1 1}{this}").

\mitem  \psscaleboxto\c~{stuff}

  This time, the first argument is a (Cartesian) coordinate, and the box is
scaled to have width \x{} and height (plus depth) \y{}. If one of the
dimensions is 0, the box is scaled by the same amount in both directions. For
example:
\begin{example**}
  \psscaleboxto(4,2){Big and long}
\end{example**}

\end{description}

PSTricks defines LR-box environments for all these box rotation and scaling
commands:
\begin{LVerb}
  \pslongbox{Rotateleft}{\rotateleft}
  \pslongbox{Rotateright}{\rotateright}
  \pslongbox{Rotatedown}{\rotatedown}
  \pslongbox{Scalebox}{\psscalebox}
  \pslongbox{Scaleboxto}{\psscaleboxto}
\end{LVerb}

Here is an example where we \n\Rotatedown{} for the answers to exercises:
\begin{example**}
  "\parbox{4cm}{\raggedright\noindent\hsize 4cm
  Question: How do Democrats organize a firing squad?

  \begin{Rotatedown}
    \parbox{\hsize}{Answer: First they get in a circle, \ldots\hss}%
  \end{Rotatedown}
  "}
\end{example**}

See the documentation of the "fancybox" package for tips on rotating
a \LaTeX{} "table" or "figure" environment, and other boxes.

\endinput

%% END psd-text.tex
