summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/generic/pstricks/psd-pict.tex
blob: 59fa301d2dd9991c54ee20f9ba523ba64bd9daf9 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
%% BEGIN psd-pict.tex

\part{Picture Tools\label{P-pictures}}

\Section{Pictures\label{S-pspic}}

The graphics objects and \n\rput{} and its variants do not change \TeX's
current point (i.e., they create a 0-dimensional box). If you string several
of these together (and any other 0-dimensional objects), they share the same
coordinate system, and so you can create a picture. For this reason, these
macros are called \emph{picture objects}.

If you create a picture this way, you will probably want to give the whole
picture a certain size. You can do this by putting the picture objects in a
\p{pspicture} environment, as in:
\begin{Ex}
  \object  \pspicture`*[baseline](\x0,\y0)'\c1
  <  picture objects>
  \object  \endpspicture
\end{Ex}
The picture objects are put in a box whose lower left-hand corner is at \c0
(by default, "(0,0)") and whose upper right-hand corner is at \c1.

By default, the baseline is set at the bottom of the box, but the optional
argument "[<baseline>]" sets the baseline fraction <baseline> from the bottom.
Thus, <baseline> is a number, generally but not necessarily between 0 and 1.
If you include this argument but leave it empty (\texttt{[\kern 1pt]}), then
the baseline passes through the origin.

Normally, the picture objects can extend outside the boundaries of the box.
However, if you include the "*", anything outside the boundaries is clipped.

Besides picture objects, you can put anything in a \n\pspicture{} that does
not take up space. E.g., you can put in font declarations and use \n\psset,
and you can put in braces for grouping. PSTricks will alert you if you include
something that does take up space.\footnote{%
When PSTricks picture objects are included in a \n\pspicture{} environment,
they gobble up any spaces that follow, and any preceding spaces as well,
making it less likely that extraneous space gets inserted. (PSTricks objects
always ignore spaces that follow. If you also want them to try to neutralize
preceding space when used outside the \n\pspicture{} environment (e.g., in a
\LaTeX{} "picture" environment), then use the command \Main\KillGlue. The
command \Main\DontKillGlue{} turns this behavior back off.)}

\LaTeX{} users can type
\begin{Ex}
  "\begin{pspicture}" \ldots\ "\end{pspicture}"
\end{Ex}
You can use PSTricks picture objects in a \LaTeX{} "picture" environment, and
you can use \LaTeX{} picture objects in a PSTricks {\UsageFont pspicture}
environment. However, the {\UsageFont pspicture} environment makes \LaTeX's
"picture" environment obsolete, and has a few small advantages over the
latter. Note that the arguments of the {\UsageFont pspicture} environment work
differently from the arguments of \LaTeX's "picture" environment (i.e., the
right way versus the wrong way).


\begin{drivers} The clipping option ("*") uses \n\pstVerb{} and
\n\pstverbscale.
\end{drivers}


\Section{Placing and rotating whatever\label{S-rput}}

PSTricks contains several commands for positioning and rotating an HR-mode
argument. All of these commands end in "put", and bear some similarity to
\LaTeX's "\put" command, but with additional capabilities. Like \LaTeX's
"\put" and unlike the box rotation macros described in Section
\ref{S-rotation}, these commands do not take up any space. They can be used
inside and outside \n\pspicture{} environments.

Most of the PSTricks "put" commands are of the form:
\begin{Ex}
  \Backslash <put>*<arg>"{<rotation>}(<coor>){<stuff>}"
\end{Ex}
With the optional "*" argument, <stuff> is first put in a
\begin{LVerb*}
  \psframebox*[boxsep=false]{<stuff>}
\end{LVerb*}
thereby blotting out whatever is behind <stuff>. This is useful for
positioning text on top of something else.

<arg> refers to other arguments that vary from one "put" command to another,
The optional <rotation> is the angle by which <stuff> should be rotated; this
arguments works pretty much the same for all "put" commands and is described
further below. The "(<coor>)" argument is the coordinate for positioning
<stuff>, but what this really means is different for each "put" command. The
"(<coor>)" argument is shown to be obligatory, but you can actually omit it if
you include the <rotation> argument.

The <rotation> argument should be an angle, as described in Section
\ref{S-coor}, but the angle can be preceded by an "*". This causes all the
rotations (except the box rotations described in Section \ref{S-rotation})
within which the \n\rput{} command is be nested to be undone before setting the
angle of rotation. This is mainly useful for getting a piece of text right
side up when it is nested inside rotations. For example,
\begin{MEx}[-1,-.5](2,2)
  \rput{34}{%
    \psframe(-1,0)(2,1)
    \rput[br]{*0}(2,1){\emph{stuff}}}
\end{MEx}

There are also some letter abbreviations for the command angles. These
indicate which way is up:
\begin{trivlist}\item[]
  \leavevmode
  \hbox to \hsize{\hfill
    \begin{tabular}{clr}
      \emph{Letter} & \emph{Short for} & \emph{Equiv.\ to}\\
      "U" & Up    & 0\\
      "L" & Left  & 90\\
      "D" & Down  & 180\\
      "R" & Right & 270\\
    \end{tabular}
    \hfill
    \begin{tabular}{clr}
      \emph{Letter} & \emph{Short for} & \emph{Equiv.\ to}\\
      "N" & North & *0\\
      "W" & West  & *90\\
      "S" & South & *180\\
      "E" & East  & *270
    \end{tabular}\hfill}
\end{trivlist}


This section describes just a two of the PSTricks "put" commands. The most
basic one command is
  \Mac  \rput`*[refpoint]{rotation}'\c~{stuff}
<refpoint> determines the reference point of <stuff>, and this reference point
is translated to \c{}.

By default, the reference point is the center of the box. This can be changed
by including one or two of the following in the optional <refpoint> argument:
\begin{center}
\begin{tabular}{rlcrl}
\multicolumn{2}{l}\emph{Horizontal} & & \multicolumn{2}{l}\emph{Vertical}\\
"l" & Left  & & "t" & Top\\
"r" & Right & & "b" & Bottom\\
    &       & & "B" & Baseline
\end{tabular}
\end{center}
Visually, here is where the reference point is set of the various combinations
(the dashed line is the baseline):
\begin{center}
\begin{pspicture}(-2.4,-.9)(2.4,1.9)
  \ttfamily\bfseries
  \psframe(-2,-.5)(2,1.5)
  \psline[linestyle=dashed](-2,0)(2,0)
  \uput[u](0,1.5){t}
  \uput[d](0,-.5){b}
  \rput*(0,0){B}
  \uput[l](-2,.5){l}
  \uput[l](-2,0){Bl}
  \uput[dl](-2,-.5){bl}
  \uput[ul](-2,1.5){tl}
  \uput[r](2,.5){r}
  \uput[r](2,0){Br}
  \uput[dr](2,-.5){br}
  \uput[ur](2,1.5){tr}
\end{pspicture}
\end{center}

There are numerous examples of \n\rput{} in this documentation, but for now
here is a simple one:
\begin{example**}
  \rput[b]{90}(-1,0){Here is a marginal note.}
\end{example**}

One common use of a macro such as \n\rput{} is to put labels on things.
PSTricks has a variant of \n\rput{} that is especially designed for labels:
  \Mac  \uput`*{labelsep}'[refangle]`{rotation}\c~'{stuff}
This places <stuff> distance <labelsep> from \c{}, in the direction
<refangle>.

The default value of <labelsep> is the dimension register
  \Mac \pslabelsep
You can also change this be setting the
\begin{Ex}
  \Par{labelsep=dim}
\end{Ex}
parameter (but remember that \n\uput{} does have an optional argument for
setting parameters).

Here is a simple example:
\begin{MEx}(3,2)
  \qdisk(1,1){1pt}
  \uput[45](1,1){(1,1)}
\end{MEx}

Here is a more interesting example where \n\uput{} is used to make a pie
chart:
\begin{example}
  \psset{unit=1.2cm}
  \pspicture(-2.2,-2.2)(2.2,2.2)
    \pswedge[fillstyle=solid,fillcolor=gray]{2}{0}{70}
    \pswedge[fillstyle=solid,fillcolor=lightgray]{2}{70}{200}
    \pswedge[fillstyle=solid,fillcolor=darkgray]{2}{200}{360}
    \SpecialCoor
    \psset{framesep=1.5pt}
    \rput(1.2;35){\psframebox*{\small\$9.0M}}
    \uput{2.2}[45](0,0){Oreos}
    \rput(1.2;135){\psframebox*{\small\$16.7M}}
    \uput{2.2}[135](0,0){Heath}
    \rput(1.2;280){\psframebox*{\small\$23.1M}}
    \uput{2.2}[280](0,0){M\&M}
  \endpspicture
\end{example}

You can use the following abbreviations for <refangle>, which indicate the
direction the angle points:%
\footnote{Using the abbreviations when applicable is more efficient.}%
\footnote{%
There is an obsolete command \n\Rput\MainIndex{\Rput}{} that has the same
syntax as \n\uput{} and that works almost the same way, except the <refangle>
argument has the syntax of \n\rput's <refpoint> argument, and it gives the
point in <stuff> that should be aligned with \c{}. E.g.,
\begin{Ex}
  "\qdisk(4,0){2pt}"\qdisk(4,0){2pt}\Rput[tl](4,0){$(x,y)$}\\
  "\Rput[tl](4,0){$(x,y)$}"
\end{Ex}
Here is the equivalence between \n\uput's <refangle> abbreviations and
\n\Rput's <refpoint> abbreviations:
\begin{center}
  \ttfamily
  \begin{tabular}{rcccccccc}
    \n\uput & r & u & l & d & ur & ul & dr & dl \\
    \n\Rput & l & b & r & t & bl & br & tr & rl \\
  \end{tabular}
\end{center}
Some people prefer \n\Rput's convention for specifying the position of <stuff>
over \n\uput's.}%
\begin{trivlist}\item[]
  \leavevmode
  \hbox to \hsize{\hfill
    \begin{tabular}{clr}
      \emph{Letter} & \emph{Short for} & \emph{Equiv.\ to}\\
      "r" & right &   0\\
      "u" & up    &  90\\
      "l" & left  & 180\\
      "d" & down  & 270\\
    \end{tabular}
    \hfill
    \begin{tabular}{clr}
      \emph{Letter} & \emph{Short for} & \emph{Equiv.\ to}\\
      "ur" & up-right   &  45\\
      "ul" & up-left    & 135\\
      "dl" & down-left  & 225\\
      "dr" & down-right & 315
    \end{tabular}\hfill}
\end{trivlist}
The first example could thus have been written:
\begin{MEx}(3,2)
  \qdisk(1,1){1pt}
  \uput[ur](1,1){(1,1)}
\end{MEx}

\begin{drivers} The rotation macros use \n\pstVerb{} and \n\pstrotate.
\end{drivers}


\Section{Repetition\label{S-loops}}

The macro
  \Mac  \multirput`*[refpoint]{angle}\c0'\c1{int}{stuff}
is a variant of \n\rput{} that puts down <int> copies, starting at \c0 and
advancing by \c1 each time. \c0 and \c1 are always interpreted as Cartesian
coordinates. For example:
\begin{MEx}(4,1.3)
  \multirput(.5,0)(.3,.1){12}{*}
\end{MEx}

If you want copies of pure graphics, it is more efficient to use
  \Mac  \multips`{angle}\c0'\c1{int}{graphics}
<graphics> can be one or more of the pure graphics objects described in Part
\ref{P-graphics}, or \n\pscustom. Note that \n\multips{} has the same syntax as
\n\multirput, except that there is no <refpoint> argument (since the graphics
are zero dimensional anyway). Also, unlike \n\multirput, the coordinates can
be of any type. An "Overfull \hbox" warning indicates that the <graphics>
argument contains extraneous output or space. For example:
\begin{MEx}[0,-.25](4,.25)
  \def\zigzag{\psline(0,0)(.5,1)(1.5,-1)(2,0)}%
  \psset{unit=.25,linewidth=1.5pt}
  \multips(0,0)(2,0){8}{\zigzag}
\end{MEx}

PSTricks can heavily benefit of a much more general loop macro, called
\n\multido.
\File{multido} You must input the file "multido.tex" or "multido.sty". See the
documentation "multido.doc" for details. Here is a sample of what you can do:
\begin{example}
  \begin{pspicture}(-3.4,-3.4)(3.4,3.4)
    \newgray{mygray}{0}  % Initialize `mygray' for benefit
    \psset{fillstyle=solid,fillcolor=mygray}  % of this line.
    \SpecialCoor
    \degrees[1.1]
    \multido{\n=0.0+.1}{11}{%
      \newgray{mygray}{\n}
      \psset{fillcolor=mygray}%
      \rput{\n}{\pswedge{3}{-.05}{.05}}
      \uput{3.2}[\n](0,0){\small\n}}
  \end{pspicture}
\end{example}

All of these loop macros can be nested.


\Section{Axes\label{S-axes}}

\File{pst-plot}
The axes command described in this section is defined in "pst-plot.tex" /
"pst-plot.sty", which you must input first. "pst-plot.tex", in turn, will
automatically input "multido.tex", which is used for putting the labels on the
axes.

The macro for making axes is:
  \Mac  \psaxes`*[par]{arrows}\c0\c1'\c2

The coordinates must be Cartesian coordinates. They work the same way as with
\n\psgrid. That is, if we imagine that the axes are enclosed in a rectangle,
\c1 and \c2 are opposing corners of the rectangle. (I.e., the x-axis extends
from \x1 to \x2 and the y-axis extends from \y1 to \y2.) The axes intersect at
\c0. For example:
\begin{MEx*}(4,3)
  \psaxes[linewidth=1.2pt,labels=none,
    ticks=none]{<->}(2,1)(0,0)(4,3)
  "\psset{nodesep=3pt}
  "\pnode(4,3){B}
  "\rput*[tr](4,2.3){\rnode{A}{\c2}}
  "\ncline{->}{A}{B}
  "\pnode(2,1){B}
  "\rput*[br](1.3,1.7){\rnode{A}{\c0}}
  "\ncline{->}{A}{B}
  "\pnode(0,0){B}
  "\rput*[bl](0,-.9){\rnode{A}{\c1}}
  "\ncline{->}{A}{B}
\end{MEx*}

If \c0 is omitted, then the origin is \c1. If both \c0 and \c1 are omitted,
"(0,0)" is used as the default. For example, when the axes enclose a single
orthont, only \c2 is needed:
\begingroup
\psset{unit=.8}
\begin{MEx}[-.5,-.5](4,2)
  "\small
  \psaxes{->}(4,2)
\end{MEx}
\endgroup

Labels (numbers) are put next to the axes, on the same side as \x1 and \y1.
Thus, if we enclose a different orthont, the numbers end up in the right
place:
\begingroup
\psset{unit=.8}
\begin{MEx}[-.5,-2](4,.5)
  "\small
  \psaxes{->}(4,-2)
\end{MEx}
\endgroup

Also, if you set the \p{arrows} parameter, the first arrow is used for the
tips at <x1> and <y1>, while the second arrow is used for the tips at <x2> and
<y2>. Thus, in the preceding examples, the arrowheads ended up in the right
place too.\footnote{%
Including a first arrow in these examples would have had no effect because
arrows are never drawn at the origin.}

When the axes don't just enclose an orthont, that is, when the origin is not
at a corner, there is some discretion as to where the numbers should go. The
rules for positioning the numbers and arrows described above still apply, and
so you can position the numbers as you please by switching <y1> and <y2>, or
<x1> and <x2>. For example, compare
\begingroup
\psset{unit=.8}
\begin{MEx}[-1.5,-.5](2.5,2.5)
  "\small
  \psaxes{<->}(0,0)(-2.5,0)(2.5,2.5)
\end{MEx}
\endgroup
with what we get when <x1> and <x2> are switched:
\begingroup
\psset{unit=.8}
\begin{MEx}[-1.5,-.5](2.5,2.5)
  "\small
  \psaxes{<->}(0,0)(2.5,0)(-2.5,2.5)
\end{MEx}
\endgroup

\n\psaxes{} puts the ticks and numbers on the axes at regular intervals, using
the following parameters:
\newbox\axesbox
\MainParIndex{Ox}
\MainParIndex{Dx}
\MainParIndex{dx}
\MainParIndex{Oy}
\MainParIndex{Dy}
\MainParIndex{dy}
\setbox\axesbox=\hbox{%
  \large
  \begin{tabular}{|c|c|c|l|}
    \hline
    \emph{Horitontal}  & \emph{Vertical} & \emph{Dflt} &
      \emph{Description}\\[2pt]
    \p{Ox=num} & \p{Oy=num} & "0"   & Label at origin.\\
    \p{Dx=num} & \p{Dy=num} & "1"   & Label increment.\\
    \p{dx=dim} & \p{dy=dim} & "0pt" & Dist btwn labels.\\
    \hline
  \end{tabular}}
\addtoquickref{center}{%
  {\large\textbf{Axes label parameters}}\par
  \leavevmode\box\axesbox}
\begin{center}
\leavevmode\copy\axesbox
\end{center}
When \p{dx} is 0, "Dx\psxunit" is used instead, and similarly for \p{dy}.
Hence, the default values of "0pt" for \p{dx} and \p{dy} are not as peculiar
as they seem.

You have to be very careful when setting \p{Ox}, \p{Dx}, \p{Oy} and \p{Dy} to
non-integer values. "multido.tex" increments the labels using rudimentary
fixed-point arithmetic, and it will come up with the wrong answer unless
\p{Ox} and \p{Dx}, or \p{Oy} and \p{Dy}, have the same number of digits to the
right of the decimal. The only exception is that \p{Ox} or \p{Oy} can always
be an integer, even if \p{Dx} or \p{Dy} is not. (The converse does not work,
however.)%
\footnote{For example, \p{Ox=1.0} and \p{Dx=1.4} is okay, as is \p{Ox=1} and
\p{Dx=1.4}, but \p{Ox=1.4} and \p{Dx=1}, or \p{Ox=1.4} and \p{Dx=1.15}, is not
okay. If you get this wrong, PSTricks won't complain, but you won't get the
right labels either.}

Note that \n\psaxes's first coordinate argument determines the physical
position of the origin, but it doesn't affect the label at the origin. E.g.,
if the origin is at "(1,1)", the origin is still labeled "0" along each axis,
unless  you explicitly change \p{Ox} and \p{Oy}. For example:
\begin{MEx}[-2,0](2,3)
  \psaxes[Ox=-2](-2,0)(2,3)
\end{MEx}

The ticks and labels use a few other parameters as well:
\begin{description}

\pitem[labels=all/x/y/none]
  To specify whether labels appear on both axes, the x-axis, the y-axis, or
neither.

\pitem[showorigin=true/false]
  If "true", then labels are placed at the origin, as long as the label
doesn't end up on one of the axes. If "false", the labels are never placed at
the origin.

\pitem[ticks=all/x/y/none]
  To specify whether ticks appear on both axes, the x-axis, the y-axis, or
neither.

\pitem[tickstyle=full/top/bottom]
  For example, if \p{tickstyle=top}, then the ticks are only on the side of
the axes away from the labels. If \p{tickstyle=bottom}, the ticks are on the
same side as the labels. "full" gives ticks extending on both sides.

\pitem[ticksize=dim]
  Ticks extend <dim> above and/or below the axis.

\end{description}

The distance between ticks and labels is \n\pslabelsep, which you can change
with the \p{labelsep} parameter.

The labels are set in the current font (ome of the examples above were
preceded by "\small" so that the labels would be smaller). You can do fancy
things with the labels by redefining the commands:
\begin{Ex}
  \object  \pshlabel
  \object  \psvlabel
\end{Ex}
E.g., if you want change the font of the horizontal labels, but not the
vertical labels, try something like
\begin{LVerb}
  \def\pshlabel#1{\small #1}
\end{LVerb}

You can choose to have a frame instead of axes, or no axes at all (but you
still get the ticks and labels), with the parameter:
\begin{Ex}
  \Par{axesstyle=axes/frame/none}
\end{Ex}
The usual \p{linestyle}, \p{fillstyle} and related paremeters apply.

For example:
\begin{MEx}[-3,-.5](.5,3)
  \psaxes[Dx=.5,dx=1,tickstyle=top,axesstyle=frame](-3,3)
\end{MEx}

The \n\psaxes{} macro is pretty flexible, but PSTricks contains some other
tools for making axes from scratch. E.g., you can use \n\psline{} and
\n\psframe{} to draw axes and frames, respectively, \n\multido{} to generate
labels (see the documentation for "multido.tex"), and \n\multips{} to make
ticks.

\endinput

%% END psd-pict.tex