fix bold
[PyX/mjg.git] / manual / box.tex
bloba39bd6e2b713b724c635a0cffed3adcc90a42575
1 \chapter{Module box: convex box handling}
2 \label{module:box}
4 This module has a quite internal character, but might still be useful
5 from the users point of view. It might also get further enhanced to
6 cover a broader range of standard arranging problems.
8 In the context of this module a box is a convex polygon having
9 optionally a center coordinate, which plays an important role for the
10 box alignment. The center might not at all be central, but it should
11 be within the box. The convexity is necessary in order to keep the
12 problems to be solved by this module quite a bit easier and
13 unambiguous.
15 Directions (for the alignment etc.) are usually provided as pairs
16 (dx, dy) within this module. It is required, that at least one of
17 these two numbers is unequal to zero. No further assumptions are taken.
19 \section{Polygon}
21 A polygon is the most general case of a box. It is an instance of the
22 class \verb|polygon|. The constructor takes a list of points (which
23 are (x, y) tuples) in the keyword argument \verb|corners| and
24 optionally another (x, y) tuple as the keyword argument \verb|center|.
25 The corners have to be ordered counterclockwise. In the following list
26 some methods of this \verb|polygon| class are explained:
28 \begin{description}
29 \raggedright
30 \item[\texttt{path(centerradius=None, bezierradius=None,
31 beziersoftness=1)}:] returns a path of the box; the center might be
32 marked by a small circle of radius \verb|centerradius|; the corners
33 might be rounded using the parameters \verb|bezierradius| and
34 \verb|beziersoftness|. For each corner of the box there may be one value
35 for beziersoftness and two bezierradii. For convenience, it is not necessary
36 to specify the whole list (for beziersoftness) and the whole list of
37 lists (bezierradius) here. You may give a single value and/or a 2-tuple instead.
38 \item[\texttt{transform(*trafos)}:] performs a list of transformations
39 to the box
40 \item[\texttt{reltransform(*trafos)}:] performs a list of
41 transformations to the box relative to the box center
43 \begin{figure}
44 \centerline{\includegraphics{boxalign}}
45 \caption{circle and line alignment examples (equal direction and
46 distance)}
47 \label{fig:boxalign}
48 \end{figure}
50 \item[\texttt{circlealignvector(a, dx, dy)}:] returns a vector (a
51 tuple (x, y)) to align the box at a circle with radius \verb|a| in
52 the direction (\verb|dx|, \verb|dy|); see figure~\ref{fig:boxalign}
53 \item[\texttt{linealignvector(a, dx, dy)}:] as above, but align at a
54 line with distance \verb|a|
55 \item[\texttt{circlealign(a, dx, dy)}:] as circlealignvector, but
56 perform the alignment instead of returning the vector
57 \item[\texttt{linealign(a, dx, dy)}:] as linealignvector, but
58 perform the alignment instead of returning the vector
59 \item[\texttt{extent(dx, dy)}:] extent of the box in the direction
60 (\verb|dx|, \verb|dy|)
61 \item[\texttt{pointdistance(x, y)}:] distance of the point (\verb|x|,
62 \verb|y|) to the box; the point must be outside of the box
63 \item[\texttt{boxdistance(other)}:] distance of the box to the box
64 \verb|other|; when the boxes are overlapping, \verb|BoxCrossError| is
65 raised
66 \item[\texttt{bbox()}:] returns a bounding box instance appropriate to
67 the box
68 \end{description}
70 \section{Functions working on a box list}
72 \begin{description}
73 \raggedright
74 \item[\texttt{circlealignequal(boxes, a, dx, dy)}:] Performs a circle
75 alignment of the boxes \verb|boxes| using the parameters \verb|a|,
76 \verb|dx|, and \verb|dy| as in the \verb|circlealign| method. For the
77 length of the alignment vector its largest value is taken for all
78 cases.
79 \item[\texttt{linealignequal(boxes, a, dx, dy)}:] as above, but
80 performing a line alignment
81 \item[\texttt{tile(boxes, a, dx, dy)}:] tiles the boxes \verb|boxes|
82 with a distance \verb|a| between the boxes (in addition the maximal box
83 extent in the given direction (\verb|dx|, \verb|dy|) is taken into
84 account)
85 \end{description}
87 \section{Rectangular boxes}
89 For easier creation of rectangular boxes, the module provides the
90 specialized class \verb|rect|. Its constructor first takes four
91 parameters, namely the x, y position and the box width and height.
92 Additionally, for the definition of the position of the center, two
93 keyword arguments are available. The parameter \verb|relcenter| takes
94 a tuple containing a relative x, y position of the center (they are
95 relative to the box extent, thus values between \verb|0| and
96 \verb|1| should be used). The parameter \verb|abscenter| takes a tuple
97 containing the x and y position of the center. This values are
98 measured with respect to the lower left corner of the box. By
99 default, the center of the rectangular box is set to this lower left
100 corner.