| blob | 60d251ae6d3982c180ff0e89c1415eaa5ce68850 |
1 <!-- This file is part of Shapes. -->
2 <!-- -->
3 <!-- Shapes is free software: you can redistribute it and/or modify -->
4 <!-- it under the terms of the GNU General Public License as published by -->
5 <!-- the Free Software Foundation, either version 3 of the License, or -->
6 <!-- any later version. -->
7 <!-- -->
8 <!-- Shapes is distributed in the hope that it will be useful, -->
9 <!-- but WITHOUT ANY WARRANTY; without even the implied warranty of -->
10 <!-- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -->
11 <!-- GNU General Public License for more details. -->
12 <!-- -->
13 <!-- You should have received a copy of the GNU General Public License -->
14 <!-- along with Shapes. If not, see <http://www.gnu.org/licenses/>. -->
15 <!-- -->
16 <!-- Copyright 2009, 2010 Henrik Tidefelt -->
18 <section id="types/text">
19 <title>Text</title>
20 <top>
21 <p>When it comes to text, <str-Shapes />' inheritance from <str-PDF /> is obvious. However, while the raw <str-PDF /> format uses bare integers and floats to encode the various parameters of rendered text, <str-Shapes /> puts a more human-friendly layer on top of this. This motivates the additional type in this section.</p>
22 </top>
24 <coretype name="Font">
25 <abstraction>
26 <p>A font face, used with <dynamic name="text_font" />.</p>
27 </abstraction>
28 <fields>
29 <type-field name="family">
30 <type><named-type name="String" /></type>
31 <description>The family name of the font.</description>
32 </type-field>
33 <type-field name="style">
34 <type><named-type name="String" /></type>
35 <description>The name of the face's style. May be empty.</description>
36 </type-field>
37 <type-field name="PostScript_name">
38 <type><named-type name="Symbol" /></type>
39 <description>A <named-type name="Symbol" /> corresponding to the PostScript name of the face. This is the key that would identify the font if it was not embedded in the produced <str-PDF /> file (currently <str-Shapes /> only supports embedded fonts), and may be seen in error messages.</description>
40 </type-field>
41 <!-- <type-field name="CIDFont?"> -->
42 <!-- <type><named-type name="Boolean" /></type> -->
43 <!-- <description>Whether the face support large character sets by the use of CIDs to select glyphs. Otherwise, the use of the font is limited to the characters available in the MacRoman encoding.</description> -->
44 <!-- </type-field> -->
45 <type-field name="kerning?">
46 <type><named-type name="Boolean" /></type>
47 <description>Whether the face's metrics support kern pairs. This may be true even if there are actually no kern pairs in the font, as long as it is not expected that there <em>should</em> have been at least some kern pairs.</description>
48 </type-field>
49 <type-method name="glyph">
50 <function>
51 <case>
52 <arguments>
53 <arg identifier="char"><type><named-type name="Character" /></type></arg>
54 </arguments>
55 <result>
56 <type>
57 <structure-type>
58 <field name="odd?"><type><named-type name="odd?" /></type></field>
59 <field name="paths"><type><named-type name="MultiPath" /></type></field>
60 <field name="advance"><type><named-type name="Length" /></type></field>
61 </structure-type>
62 </type>
63 </result>
64 <dynamic-references><dynamic name="text_size" /></dynamic-references>
65 <description>
66 <p>Return the paths that generate the image of the glyph corresponding to <arg name="char" />, along with the kind of painting/clipping operation that should be applied to the paths to generate the image, and by how much the text drawing position should be advanced after the glyph has been painted.</p>
67 </description>
68 </case>
69 </function>
70 </type-method>
71 </fields>
72 <description>
73 <p>Support for other fonts than the standard fonts of the <str-PDF /> standard (these are restricted to the characters in the MacRoman encoding) is only available if the <str-Shapes /> compiler has been built with the optional FreeType library.</p>
74 </description>
75 </coretype>
77 <coretype name="TextOperation">
78 <abstraction>
79 <p>An object to be used with <named-state-type name="Text" />.</p>
80 </abstraction>
81 <description>
82 <p>This type has several subtypes, but only one of them (<named-type name="KernedText" />) can be constructed by the user; other subtypes are currently only used internally in the <str-Shapes /> compiler.</p>
83 </description>
84 </coretype>
86 <coretype name="KernedText">
87 <isa><named-type name="TextOperation" /></isa>
88 <abstraction>
89 <p>A string of text, possibly with kerning distances inserted between some of the characters.</p>
90 </abstraction>
91 <fields>
92 <type-field name="list">
93 <type><named-type name="SingleList" /></type>
94 <description><p>A list of <named-type name="ConsPair" /> pairs of a horizontal position (of type <named-type name="Length" />) and a <named-type name="TextOperation" /> corresponding to the individual characters.</p></description>
95 </type-field>
96 </fields>
97 </coretype>
99 <coretype name="TextRenderingMode">
100 <abstraction>
101 <p>Indicate wheter to stroke and/or fill rendered text, used with <dynamic name="text_rendering" />.</p>
102 </abstraction>
103 <fields>
104 <type-field name="fill">
105 <type><named-type name="Boolean" /></type>
106 <description>Whether rendered text shall be filled.</description>
107 </type-field>
108 <type-field name="stroke">
109 <type><named-type name="Boolean" /></type>
110 <description>Whether rendered text shall be stroked.</description>
111 </type-field>
112 </fields>
113 <description>
114 <p>The text rendering modes os <str-Shapes /> correspond directly to the non-clipping text rendering modes in <str-PDF />. The clipping rendering modes are used internally, but are only accessible to users through <value name="clip" />.</p>
115 <p>See the design note in <dynamic name="text_render" /> for the motivation behind this type.</p>
116 </description>
117 </coretype>
119 </section>