|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
IWemListenerInline | Line # 64 | 0 | - | 0 | 0 | - |
-1.0
|
||||||||||||||||||||||||||||||||||||||||||||||||||||
No Tests | |||
1 | /* | |
2 | * See the NOTICE file distributed with this work for additional | |
3 | * information regarding copyright ownership. | |
4 | * | |
5 | * This is free software; you can redistribute it and/or modify it | |
6 | * under the terms of the GNU Lesser General Public License as | |
7 | * published by the Free Software Foundation; either version 2.1 of | |
8 | * the License, or (at your option) any later version. | |
9 | * | |
10 | * This software is distributed in the hope that it will be useful, | |
11 | * but WITHOUT ANY WARRANTY; without even the implied warranty of | |
12 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | |
13 | * Lesser General Public License for more details. | |
14 | * | |
15 | * You should have received a copy of the GNU Lesser General Public | |
16 | * License along with this software; if not, write to the Free | |
17 | * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA | |
18 | * 02110-1301 USA, or see the FSF site: http://www.fsf.org. | |
19 | */ | |
20 | package org.xwiki.rendering.wikimodel; | |
21 | ||
22 | /** | |
23 | * This method re-groups all methods used to notify about in-line elements. All | |
24 | * inline elements should be "wrapped" in a formats. | |
25 | * | |
26 | * <pre> | |
27 | * So a normal sequence of notifications is: | |
28 | * * beginFormat(...) | |
29 | * - onWord(...) | |
30 | * - onSpace(...) | |
31 | * - onReference(...) | |
32 | * - onWord(...) | |
33 | * - ... | |
34 | * * endFormat(...) | |
35 | * * beginFormat(...) | |
36 | * - onWord(...) | |
37 | * - ... | |
38 | * * endFormat(...) | |
39 | * </pre> | |
40 | * | |
41 | * All inline elements can be splitted in the following categories: | |
42 | * <dl> | |
43 | * <dt>Simple text elements</dt> | |
44 | * <dd>These elements are notified using the following set of methods: | |
45 | * {@link #onNewLine()}, {@link #onSpace(String)}, {@link #onWord(String)} and | |
46 | * {@link #onSpecialSymbol(String)}. This methods cover "simple text" and in sum | |
47 | * they are used to represent all types of "natural" elements in the text - | |
48 | * words, spaces, new lines and special symbols. Using only these methods it is | |
49 | * possible to cover all combinations of all unicode characters. Parsers use | |
50 | * these methods to notify about all non-interpreted symbols and their | |
51 | * combinations. These methods calls can be considered as the base of any text | |
52 | * documents.</dd> | |
53 | * <dt>Logical in-line elements</dt> | |
54 | * <dd>These elements require interpretation of some syntax-specific formatting | |
55 | * and are notified using the following methods: {@link #onEscape(String)}, | |
56 | * {@link #onLineBreak()}, {@link #onReference(String)}/ | |
57 | * {@link #onReference(WikiReference)}, | |
58 | * {@link #onVerbatimInline(String, WikiParameters)}</dd> | |
59 | * </dl> | |
60 | * | |
61 | * @version $Id: b97f8796cf471ac389bcb13ea2475e3a9079e2e7 $ | |
62 | * @since 4.0M1 | |
63 | */ | |
64 | public interface IWemListenerInline | |
65 | { | |
66 | /** | |
67 | * This method is called at the beginning of a sequence of in-line elements | |
68 | * having the specified formatting parameters. | |
69 | * | |
70 | * @param format the object defining formatting parameters of in-line | |
71 | * elements. | |
72 | */ | |
73 | void beginFormat(WikiFormat format); | |
74 | ||
75 | /** | |
76 | * This method is called to notify about the end of a sequence of in-line | |
77 | * elements having common formatting parameters. | |
78 | * | |
79 | * @param format the formatting object defining how contained in-line | |
80 | * elements should be formatted | |
81 | */ | |
82 | void endFormat(WikiFormat format); | |
83 | ||
84 | /** | |
85 | * Escaped symbols. More frequently the given string has just one symbol. | |
86 | * | |
87 | * @param str the escaped sequence of characters | |
88 | */ | |
89 | void onEscape(String str); | |
90 | ||
91 | /** | |
92 | * This method is called to notify that an free standing image was found in | |
93 | * the parsed wiki document. | |
94 | * | |
95 | * @param ref the reference the reference | |
96 | */ | |
97 | void onImage(String ref); | |
98 | ||
99 | /** | |
100 | * This method is called to notify that a structured reference was found in | |
101 | * the text | |
102 | * | |
103 | * @param ref the reference the reference | |
104 | */ | |
105 | void onImage(WikiReference ref); | |
106 | ||
107 | /** | |
108 | * This method is called to notify about a forced line break found in the | |
109 | * text. Note that the line break symbol can be found in the middle of a | |
110 | * "physical" line so this event is not equals to the {@link #onNewLine()} | |
111 | * notification. | |
112 | * | |
113 | * @see #onNewLine() | |
114 | */ | |
115 | void onLineBreak(); | |
116 | ||
117 | /** | |
118 | * This method is called to notify that the parsed block contains a new line | |
119 | * sequence ("\r\n" or "\r" or "\n" character sequence). Note that the new | |
120 | * line symbols are not the same as a forced line break sequence notified by | |
121 | * the {@link #onLineBreak()} event. | |
122 | * | |
123 | * @see #onSpace(String) | |
124 | * @see #onWord(String) | |
125 | * @see #onSpecialSymbol(String) | |
126 | * @see #onLineBreak() | |
127 | */ | |
128 | void onNewLine(); | |
129 | ||
130 | /** | |
131 | * This method is called to notify that an URI (an implicit reference) was | |
132 | * found in the parsed wiki document. | |
133 | * | |
134 | * @param ref the URI | |
135 | */ | |
136 | void onReference(String ref); | |
137 | ||
138 | /** | |
139 | * This method is called to notify that a structured reference was found in | |
140 | * the text | |
141 | * | |
142 | * @param ref the reference the reference | |
143 | */ | |
144 | void onReference(WikiReference ref); | |
145 | ||
146 | /** | |
147 | * This method is called to notify about a sequence of space symbols (like | |
148 | * " " or "\t" symbols). | |
149 | * | |
150 | * @param str the sequence of space characters | |
151 | * @see #onWord(String) | |
152 | * @see #onSpecialSymbol(String) | |
153 | * @see #onNewLine() | |
154 | */ | |
155 | void onSpace(String str); | |
156 | ||
157 | /** | |
158 | * This method is called to notify about a sequence of special characters. | |
159 | * Special symbols are characters which are not interpreted as a part of a | |
160 | * word (letters or digits) or as a space. Note that the handling of these | |
161 | * symbols requires special attention because these symbols most frequently | |
162 | * used to define text formatting. Various wiki syntaxes use combinations of | |
163 | * these sequences to define structural elements in wiki documents. | |
164 | * | |
165 | * <pre> | |
166 | * The full list of possible special symbols: | |
167 | * "!", "\"", "#", "$", "%", "&", "'", "(", | |
168 | * ")", "*", "+", ",", "-", ".", "/", ":", | |
169 | * ";", "<", "=", ">", "?", "@", "[", "\\", | |
170 | * "]", "^", "_", "`", "{", "|", "}", "~" | |
171 | * </pre> | |
172 | * | |
173 | * @param str the sequence of special symbols | |
174 | * @see #onSpace(String) | |
175 | * @see #onWord(String) | |
176 | * @see #onNewLine() | |
177 | */ | |
178 | void onSpecialSymbol(String str); | |
179 | ||
180 | /** | |
181 | * This method is called to notify about not-interpreted in-line sequence of | |
182 | * characters which should be represented in the final text "as is". | |
183 | * | |
184 | * @param str the sequence of non-interpreted characters | |
185 | * @param params TODO | |
186 | */ | |
187 | void onVerbatimInline(String str, WikiParameters params); | |
188 | ||
189 | /** | |
190 | * This method is called to notify about a "word" found in the document. | |
191 | * Words are formed by all characters which are not considered as spaces or | |
192 | * special symbols. | |
193 | * | |
194 | * <pre> | |
195 | * Words are formed by the all characters excluding the following ones: | |
196 | * | |
197 | * "\t", "\n", "\r", " ", | |
198 | * "!", "\"", "#", "$", "%", "&", "'", "(", | |
199 | * ")", "*", "+", ",", "-", ".", "/", ":", | |
200 | * ";", "<", "=", ">", "?", "@", "[", "\\", | |
201 | * "]", "^", "_", "`", "{", "|", "}", "~" | |
202 | * </pre> | |
203 | * | |
204 | * @param str the sequence of characters forming a word | |
205 | * @see #onSpace(String) | |
206 | * @see #onSpecialSymbol(String) | |
207 | * @see #onNewLine() | |
208 | */ | |
209 | void onWord(String str); | |
210 | } |
|