Class | Line # | Actions | |||||
---|---|---|---|---|---|---|---|
IWemListenerInline | 59 | 0 | - | 0 | 0 |
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 inline elements should be "wrapped" in a | |
24 | * 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: {@link #onNewLine()}, {@link #onSpace(String)}, | |
45 | * {@link #onWord(String)} and {@link #onSpecialSymbol(String)}. This methods cover "simple text" and in sum they are | |
46 | * used to represent all types of "natural" elements in the text - words, spaces, new lines and special symbols. | |
47 | * Using only these methods it is possible to cover all combinations of all unicode characters. Parsers use these | |
48 | * methods to notify about all non-interpreted symbols and their combinations. These methods calls can be considered | |
49 | * as the base of any text documents.</dd> | |
50 | * <dt>Logical in-line elements</dt> | |
51 | * <dd>These elements require interpretation of some syntax-specific formatting and are notified using the following | |
52 | * methods: {@link #onEscape(String)}, {@link #onLineBreak()}, {@link #onReference(String)}/ | |
53 | * {@link #onReference(WikiReference)}, {@link #onVerbatimInline(String, WikiParameters)}</dd> | |
54 | * </dl> | |
55 | * | |
56 | * @version $Id: 32b3c08d9a4dda24d42ff73ab691e6e649169ebd $ | |
57 | * @since 4.0M1 | |
58 | */ | |
59 | public interface IWemListenerInline | |
60 | { | |
61 | /** | |
62 | * This method is called at the beginning of a sequence of in-line elements having the specified formatting | |
63 | * parameters. | |
64 | * | |
65 | * @param format the object defining formatting parameters of in-line elements. | |
66 | */ | |
67 | void beginFormat(WikiFormat format); | |
68 | ||
69 | /** | |
70 | * This method is called to notify about the end of a sequence of in-line elements having common formatting | |
71 | * parameters. | |
72 | * | |
73 | * @param format the formatting object defining how contained in-line elements should be formatted | |
74 | */ | |
75 | void endFormat(WikiFormat format); | |
76 | ||
77 | /** | |
78 | * Escaped symbols. More frequently the given string has just one symbol. | |
79 | * | |
80 | * @param str the escaped sequence of characters | |
81 | */ | |
82 | void onEscape(String str); | |
83 | ||
84 | /** | |
85 | * This method is called to notify that an free standing image was found in the parsed wiki document. | |
86 | * | |
87 | * @param ref the reference the reference | |
88 | */ | |
89 | void onImage(String ref); | |
90 | ||
91 | /** | |
92 | * This method is called to notify that a structured reference was found in the text | |
93 | * | |
94 | * @param ref the reference the reference | |
95 | */ | |
96 | void onImage(WikiReference ref); | |
97 | ||
98 | /** | |
99 | * This method is called to notify about a forced line break found in the text. Note that the line break symbol can | |
100 | * be found in the middle of a "physical" line so this event is not equals to the {@link #onNewLine()} | |
101 | * notification. | |
102 | * | |
103 | * @see #onNewLine() | |
104 | */ | |
105 | void onLineBreak(); | |
106 | ||
107 | /** | |
108 | * This method is called to notify that the parsed block contains a new line sequence ({@code "\r\n"} or {@code | |
109 | * "\r"} or {@code "\n"} character sequence). Note that the new line symbols are not the same as a forced line break | |
110 | * sequence notified by the {@link #onLineBreak()} event. | |
111 | * | |
112 | * @see #onSpace(String) | |
113 | * @see #onWord(String) | |
114 | * @see #onSpecialSymbol(String) | |
115 | * @see #onLineBreak() | |
116 | */ | |
117 | void onNewLine(); | |
118 | ||
119 | /** | |
120 | * This method is called to notify that an URI (an implicit reference) was found in the parsed wiki document. | |
121 | * | |
122 | * @param ref the URI | |
123 | */ | |
124 | void onReference(String ref); | |
125 | ||
126 | /** | |
127 | * This method is called to notify that a structured reference was found in the text | |
128 | * | |
129 | * @param ref the reference the reference | |
130 | */ | |
131 | void onReference(WikiReference ref); | |
132 | ||
133 | /** | |
134 | * This method is called to notify about a sequence of space symbols (like {@code " "} or {@code "\t"} symbols). | |
135 | * | |
136 | * @param str the sequence of space characters | |
137 | * @see #onWord(String) | |
138 | * @see #onSpecialSymbol(String) | |
139 | * @see #onNewLine() | |
140 | */ | |
141 | void onSpace(String str); | |
142 | ||
143 | /** | |
144 | * This method is called to notify about a sequence of special characters. Special symbols are characters which are | |
145 | * not interpreted as a part of a word (letters or digits) or as a space. Note that the handling of these symbols | |
146 | * requires special attention because these symbols most frequently used to define text formatting. Various wiki | |
147 | * syntaxes use combinations of these sequences to define structural elements in wiki documents. <p> The full list | |
148 | * of possible special symbols: | |
149 | * <pre>{@code | |
150 | * "!", "\"", "#", "$", "%", "&", "'", "(", | |
151 | * ")", "*", "+", ",", "-", ".", "/", ":", | |
152 | * ";", "<", "=", ">", "?", "@", "[", "\\", | |
153 | * "]", "^", "_", "`", "{", "|", "}", "~" | |
154 | * }</pre> | |
155 | * | |
156 | * @param str the sequence of special symbols | |
157 | * @see #onSpace(String) | |
158 | * @see #onWord(String) | |
159 | * @see #onNewLine() | |
160 | */ | |
161 | void onSpecialSymbol(String str); | |
162 | ||
163 | /** | |
164 | * This method is called to notify about not-interpreted in-line sequence of characters which should be represented | |
165 | * in the final text "as is". | |
166 | * | |
167 | * @param str the sequence of non-interpreted characters | |
168 | * @param params the list of parameters for this event | |
169 | */ | |
170 | void onVerbatimInline(String str, WikiParameters params); | |
171 | ||
172 | /** | |
173 | * This method is called to notify about a "word" found in the document. Words are formed by all characters which | |
174 | * are not considered as spaces or special symbols. <p> Words are formed by the all characters excluding the | |
175 | * following ones: | |
176 | * <pre>{@code | |
177 | * "\t", "\n", "\r", " ", | |
178 | * "!", "\"", "#", "$", "%", "&", "'", "(", | |
179 | * ")", "*", "+", ",", "-", ".", "/", ":", | |
180 | * ";", "<", "=", ">", "?", "@", "[", "\\", | |
181 | * "]", "^", "_", "`", "{", "|", "}", "~" | |
182 | * }</pre> | |
183 | * | |
184 | * @param str the sequence of characters forming a word | |
185 | * @see #onSpace(String) | |
186 | * @see #onSpecialSymbol(String) | |
187 | * @see #onNewLine() | |
188 | */ | |
189 | void onWord(String str); | |
190 | } |