1# text-attribute
2
3Any string literal that is intended to be displayed on the
4diagram can be followed by zero or more of the following
5keywords, in any order:
6
7  * **above**
8  * **aligned**
9  * **below**
10  * **big**
11  * **bold**
12  * **center**
13  * **italic**
14  * **ljust**
15  * **rjust**
16  * **small**
17
18## Attributes "above" and "below"
19
20The "`above`" and "`below`" keywords control the location of the
21text above or below the center point of the object with which
22the text is associated.  If there is just one text on the object
23and the "`above`" and "`below`" keywords are omitted, the text is
24placed directly over the center of the object.  This causes
25the text to appear in the middle of lines:
26
27~~~~ pikchr indent
28  line "on the line" wid 150%
29~~~~
30
31So if there is just a single text label on a line, you probably
32want to include either the "`above`" or "`below`" keyword.
33
34~~~~ pikchr indent
35  line "above" above; move; line "below" below
36~~~~
37
38If there are two texts on the object, they straddle the center point
39above and below, even without the use of the "`above`" and "`below`"
40keywords:
41
42~~~~ pikchr indent
43  line wid 300% "text without \"above\"" "text without \"below\""
44~~~~
45
46The "`above`" and "`below`" attributes do not stack or accumulate.
47Each "`above`" or "`below`" overrides any previous "`above`" or "`below`"
48for the same text.
49
50If there are multiple texts and all are marked "`above`" or "`below`", then
51all are placed above or below the center point, in order of appearance.
52
53~~~~ pikchr indent
54  line width 200% "first above" above "second above" above
55  move
56  line same "first below" below "second below" below
57~~~~
58
59## Attributes "ljust" and "rjust"
60
61As the "`above`" and "`below`" keywords control up and down positioning of
62the text, so the "`ljust`" and "`rjust`" keywords control left and right
63positioning.
64
65For a line, the "`ljust`" means that the left side of the text is flush
66against the center point of the line.  And "`rjust`" means that the right
67side of the text is flush against the center point of the line.
68(In the following diagram, the red dot is at the center of the line.)
69
70~~~~ pikchr indent
71   line wid 200% "ljust" ljust above "rjust" rjust below
72   dot color red at previous.c
73~~~~
74
75For a block object, "`ljust`" shifts the text to be left justified
76against the left edge of the block (with a small margin) and
77"`rjust`" puts the text against the right side of the object (with
78the same margin).
79
80~~~~ pikchr indent
81   box "ljust" ljust "longer line" ljust "even longer line" ljust fit
82   move
83   box "rjust" rjust "longer line" rjust "even longer line" rjust fit
84~~~~
85
86The behavior of "`ljust`" and "`rjust`" for block objects in Pikchr differs
87from legacy PIC.
88In PIC, text is always justified around the center point, as in lines.
89But this means there is no easy way to left justify multiple lines of
90text within a "box" or "file", and so the behavior was changed for
91Pikchr.
92
93Pikchr allows two texts to fill the same vertical slot if one is
94"`ljust`" and the other is "`rjust`".
95
96~~~~ pikchr indent
97  box wid 300% \
98     "above-ljust" above ljust \
99     "above-rjust" above rjust \
100     "centered" center \
101     "below-ljust" below ljust \
102     "below-rjust" below rjust
103~~~~
104
105## Attribute "center"
106
107The "`center`" attribute cancels all prior "`above`", "`below`",
108"`ljust`", and "`rjust`" attributes for the current text.
109
110## Attributes "bold" and "italic"
111
112The "`bold`" and "`italic`" attributes cause the text to use a bold or
113an italic font.  Fonts can be both bold and italic at the same time.
114
115~~~~ pikchr indent
116  box "bold" bold "italic" italic "bold-italic" bold italic fit
117~~~~
118
119## Attribute "aligned"
120
121The "`aligned`" attribute causes text associated with a straight line
122to be rotated to align with that line.
123
124~~~~ pikchr indent
125  arrow go 150% heading 30 "aligned" aligned above
126  move to 1cm east of previous.end
127  arrow go 150% heading 170 "aligned" aligned above
128  move to 1cm east of previous.end
129  arrow go 150% north "aligned" aligned above
130~~~~
131
132To display rotated text not associated with a line attach the
133text to a line that is marked "`invisible`"
134
135~~~~ pikchr indent
136  box ht 200% wid 50%
137  line invis from previous.s to previous.n "rotated text" aligned
138~~~~
139
140## Attributes "big" and "small"
141
142The "`big`" and "`small`" attributes cause the text to be a little larger
143or a little smaller, respectively.  Two "`big`" attributes cause the
144text to be larger still, as do two "`small`" attributes.  But the text
145size does not increase or decrease beyond two "`big`" or "`small`" keywords.
146
147~~~~ pikchr indent
148  box "small small" small small "small" small \
149    "(normal)" italic \
150    "big" big "big big" big big ht 200%
151~~~~
152
153A "`big`" keyword cancels any prior "`small`" keywords on the same text,
154and a "`small`" keyword cancels any prior "`big`" keywords.
155