1. Project Clover database Tue Dec 20 2016 21:24:09 CET
  2. Package org.xwiki.rendering.listener

File Listener.java

 

Code metrics

0
0
0
1
448
59
0
-
-
0
-

Classes

Class Line # Actions
Listener 52 0 - 0 0
-1.0 -
 

Contributing tests

No tests hitting this source file were found.

Source view

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.listener;
21   
22    import java.util.Collections;
23    import java.util.Map;
24   
25    import org.xwiki.filter.annotation.Default;
26    import org.xwiki.filter.annotation.Name;
27    import org.xwiki.rendering.syntax.Syntax;
28   
29    /**
30    * Contains callback events called when a document has been parsed and when it needs to be modified or rendered. More
31    * specifically when a document is parsed it generates an {@link org.xwiki.rendering.block.XDOM} object. That object has
32    * a {@link org.xwiki.rendering.block.XDOM#traverse(Listener)} method that accepts a {@link Listener} object. For each
33    * {@link org.xwiki.rendering.block.Block} element found in the document its
34    * {@link org.xwiki.rendering.block.Block#traverse} method is called leading to the generation of events from this
35    * interface.
36    * <p>
37    * Here's an example of usage:
38    * </p>
39    *
40    * <pre>
41    * &lt;code&gt;
42    * XDOM dom = parser.parse(source);
43    * MyListener listener = new MyListener(...);
44    * dom.traverse(listener);
45    * // At this stage all events have been sent to MyListener.
46    * &lt;/code&gt;
47    * </pre>
48    *
49    * @version $Id: f670163f92e691b94240f24d10212ca55aa62676 $
50    * @since 1.5M2
51    */
 
52    public interface Listener extends LinkListener, ImageListener
53    {
54    /**
55    * To use when there is no parameters.
56    */
57    Map<String, String> EMPTY_PARAMETERS = Collections.emptyMap();
58   
59    /**
60    * Start of the document.
61    *
62    * @param metadata the meta data to associate to the following events, see {@link MetaData}
63    * @since 3.0M2
64    */
65    void beginDocument(MetaData metadata);
66   
67    /**
68    * End of the document.
69    *
70    * @param metadata the meta data associated with the previous events, see {@link MetaData}
71    * @since 3.0M2
72    */
73    void endDocument(MetaData metadata);
74   
75    /**
76    * Start of MetaData (eg saving source from where the content is coming from).
77    *
78    * @param metadata the metadata
79    * @since 3.0M2
80    */
81    void beginMetaData(MetaData metadata);
82   
83    /**
84    * End of MetaData.
85    *
86    * @param metadata the metadata
87    * @since 3.0M2
88    */
89    void endMetaData(MetaData metadata);
90   
91    /**
92    * Start a group of elements. Groups are used to allow using standalone elements in list items, table cells, etc.
93    * They can also be used to set parameters on a group of standalone elements.
94    *
95    * @param parameters a generic list of parameters. Example: style="background-color: blue"
96    * @since 1.8.3
97    */
98    void beginGroup(@Default("") Map<String, String> parameters);
99   
100    /**
101    * End of the group.
102    *
103    * @param parameters a generic list of parameters. Example: style="background-color: blue"
104    * @since 1.8.3
105    */
106    void endGroup(@Default("") Map<String, String> parameters);
107   
108    /**
109    * End of a text formatting block.
110    *
111    * @param format the formatting type (bold, italic, etc)
112    * @param parameters a generic list of parameters. Example: style="background-color: blue"
113    * @see Format
114    */
115    void beginFormat(@Default("NONE") Format format, @Default("") Map<String, String> parameters);
116   
117    /**
118    * End of a text formatting block.
119    *
120    * @param format the formatting type (bold, italic, etc)
121    * @param parameters a generic list of parameters. Example: style="background-color: blue"
122    * @see Format
123    */
124    void endFormat(@Default("NONE") Format format, @Default("") Map<String, String> parameters);
125   
126    /**
127    * Start of a paragraph.
128    *
129    * @param parameters a generic list of parameters. Example: style="background-color: blue"
130    */
131    void beginParagraph(@Default("") Map<String, String> parameters);
132   
133    /**
134    * End of a paragraph.
135    *
136    * @param parameters a generic list of parameters. Example: style="background-color: blue"
137    */
138    void endParagraph(@Default("") Map<String, String> parameters);
139   
140    /**
141    * Start of a list.
142    *
143    * @param type the type of list (bulleted, numbered, etc)
144    * @param parameters a generic list of parameters for the list. Example: "style"/"background-color: blue"
145    * @see ListType
146    */
147    void beginList(@Default("BULLETED") ListType type, @Default("") Map<String, String> parameters);
148   
149    /**
150    * Start of a definition list. For example in HTML this is the equivalent of &lt;dl&gt;.
151    *
152    * @param parameters a generic list of parameters for the list. Example: "style"/"background-color: blue"
153    * @since 2.0RC1
154    */
155    void beginDefinitionList(@Default("") Map<String, String> parameters);
156   
157    /**
158    * End of a list.
159    *
160    * @param type the type of list (bulleted, numbered, etc)
161    * @param parameters a generic list of parameters for the list. Example: "style"/"background-color: blue"
162    * @see ListType
163    */
164    void endList(@Default("BULLETED") ListType type, @Default("") Map<String, String> parameters);
165   
166    /**
167    * End of a definition list. For example in HTML this is the equivalent of &lt;/dl&gt;.
168    *
169    * @param parameters a generic list of parameters for the list. Example: "style"/"background-color: blue"
170    * @since 2.0RC1
171    */
172    void endDefinitionList(@Default("") Map<String, String> parameters);
173   
174    /**
175    * Start of a list item.
176    */
177    void beginListItem();
178   
179    /**
180    * Start of a definition list term. For example in HTML this is the equivalent of &lt;dt&gt;.
181    *
182    * @since 1.6M2
183    */
184    void beginDefinitionTerm();
185   
186    /**
187    * Start of a definition list description. For example in HTML this is the equivalent of &lt;dd&gt;.
188    *
189    * @since 1.6M2
190    */
191    void beginDefinitionDescription();
192   
193    /**
194    * End of a list item.
195    */
196    void endListItem();
197   
198    /**
199    * End of a definition list term. For example in HTML this is the equivalent of &lt;/dt&gt;.
200    *
201    * @since 1.6M2
202    */
203    void endDefinitionTerm();
204   
205    /**
206    * End of a definition list description. For example in HTML this is the equivalent of &lt;/dd&gt;.
207    *
208    * @since 1.6M2
209    */
210    void endDefinitionDescription();
211   
212    /**
213    * Start of a table.
214    *
215    * @param parameters a generic list of parameters for the table.
216    * @since 1.6M2
217    */
218    void beginTable(@Default("") Map<String, String> parameters);
219   
220    /**
221    * Start of a table row.
222    *
223    * @param parameters a generic list of parameters for the table row.
224    * @since 1.6M2
225    */
226    void beginTableRow(@Default("") Map<String, String> parameters);
227   
228    /**
229    * Start of a table cell.
230    *
231    * @param parameters a generic list of parameters for the table cell.
232    * @since 1.6M2
233    */
234    void beginTableCell(@Default("") Map<String, String> parameters);
235   
236    /**
237    * Start of a table head cell.
238    *
239    * @param parameters a generic list of parameters for the table head cell.
240    * @since 1.6M2
241    */
242    void beginTableHeadCell(@Default("") Map<String, String> parameters);
243   
244    /**
245    * End of a table.
246    *
247    * @param parameters a generic list of parameters for the table.
248    * @since 1.6M2
249    */
250    void endTable(@Default("") Map<String, String> parameters);
251   
252    /**
253    * End of a table row.
254    *
255    * @param parameters a generic list of parameters for the table row.
256    * @since 1.6M2
257    */
258    void endTableRow(@Default("") Map<String, String> parameters);
259   
260    /**
261    * End of a table cell.
262    *
263    * @param parameters a generic list of parameters for the table cell.
264    * @since 1.6M2
265    */
266    void endTableCell(@Default("") Map<String, String> parameters);
267   
268    /**
269    * End of a table head cell.
270    *
271    * @param parameters a generic list of parameters for the table head cell.
272    * @since 1.6M2
273    */
274    void endTableHeadCell(@Default("") Map<String, String> parameters);
275   
276    /**
277    * Start of a section.
278    *
279    * @param parameters a generic list of parameters. Example: style="background-color: blue"
280    * @see org.xwiki.rendering.listener.HeaderLevel
281    */
282    void beginSection(@Default("") Map<String, String> parameters);
283   
284    /**
285    * End of a section.
286    *
287    * @param parameters a generic list of parameters. Example: style="background-color: blue"
288    * @see org.xwiki.rendering.listener.HeaderLevel
289    */
290    void endSection(@Default("") Map<String, String> parameters);
291   
292    /**
293    * Start of a header.
294    *
295    * @param level the header level (1, 2, 3, etc)
296    * @param id the header unique identifier
297    * @param parameters a generic list of parameters. Example: style="background-color: blue"
298    * @see org.xwiki.rendering.listener.HeaderLevel
299    * @since 1.9M1
300    */
301    void beginHeader(@Default("1") HeaderLevel level, String id, @Default("") Map<String, String> parameters);
302   
303    /**
304    * End of a header.
305    *
306    * @param level the header level (1, 2, 3, etc)
307    * @param id the header unique identifier
308    * @param parameters a generic list of parameters. Example: style="background-color: blue"
309    * @see org.xwiki.rendering.listener.HeaderLevel
310    * @since 1.9M1
311    */
312    void endHeader(@Default("1") HeaderLevel level, String id, @Default("") Map<String, String> parameters);
313   
314    /**
315    * Start of marker containing a macro definition. This is a special that Macro Blocks emits when they are executed
316    * so that it's possible to reconstruct the initial macro syntax even after Macros have been executed. This is used
317    * for exemple by the WYSIWYG editor to let use see the result of executing a macro and still let them modify the
318    * macro definition.
319    *
320    * @param name the macro name
321    * @param parameters the macro parameters
322    * @param content the macro content
323    * @param inline if true the macro is located in a inline content (like paragraph, etc.)
324    * @see #onMacro(String, java.util.Map, String, boolean)
325    */
326    void beginMacroMarker(String name, @Default("") Map<String, String> parameters, String content, boolean inline);
327   
328    /**
329    * End of marker containing a macro definition.
330    *
331    * @param name the macro name
332    * @param parameters the macro parameters
333    * @param content the macro content
334    * @param inline if true the macro is located in a inline content (like paragraph, etc.)
335    * @see #beginMacroMarker(String, java.util.Map, String, boolean)
336    */
337    void endMacroMarker(String name, @Default("") Map<String, String> parameters, String content, boolean inline);
338   
339    /**
340    * Start of a quotation. There are one or several quotation lines inside a quotation block.
341    *
342    * @param parameters a generic list of parameters for the quotation. Example: "style"/"background-color: blue"
343    */
344    void beginQuotation(@Default("") Map<String, String> parameters);
345   
346    /**
347    * End of a quotation.
348    *
349    * @param parameters a generic list of parameters for the quotation. Example: "style"/"background-color: blue"
350    */
351    void endQuotation(@Default("") Map<String, String> parameters);
352   
353    /**
354    * Start of a quotation line. There can be several quotation lines in a quotation block.
355    */
356    void beginQuotationLine();
357   
358    /**
359    * End of a quotation line.
360    */
361    void endQuotationLine();
362   
363    /**
364    * A new line or line break (it's up to the renderers to decide if it should be outputted as a new line or as a line
365    * break in the given syntax).
366    */
367    void onNewLine();
368   
369    /**
370    * A Macro.
371    *
372    * @param id the macro id (eg "toc" for the TOC macro)
373    * @param parameters the macro parameters
374    * @param content the macro content
375    * @param inline if true the macro is located in a inline content (like paragraph, etc.)
376    * @since 1.6M2
377    */
378    void onMacro(String id, @Default("") Map<String, String> parameters, String content,
379    @Name("inline") boolean inline);
380   
381    /**
382    * A word. Note that sentences ar broken into different events: word events, special symbols events, space events,
383    * etc. This allows fine-grained actions for listeners.
384    *
385    * @param word the word encountered
386    */
387    void onWord(String word);
388   
389    /**
390    * A space.
391    */
392    void onSpace();
393   
394    /**
395    * A special symbol ({@code *}, {@code <}, {@code >}, {@code =}, quote, etc). Any non alpha numeric character is a
396    * special symbol.
397    *
398    * @param symbol the symbol encountered
399    */
400    void onSpecialSymbol(char symbol);
401   
402    /**
403    * A reference/location in a page. In HTML for example this is called an Anchor. It allows pointing to that
404    * location, for example in links. Note that there is no wiki syntax for this in general and it's often generated by
405    * Macros (such as the TOC Macro).
406    *
407    * @param name the location name.
408    * @since 1.6M1
409    */
410    void onId(String name);
411   
412    /**
413    * Represents an horizontal line.
414    *
415    * @param parameters a generic list of parameters. Example: style="background-color: blue"
416    * @since 1.6M1
417    */
418    void onHorizontalLine(@Default("") Map<String, String> parameters);
419   
420    /**
421    * Represents an empty line between 2 standalone Blocks. A standalone block is block that is not included in another
422    * block. Standalone blocks are Paragraph, Standalone Macro, Lists, Table, etc.
423    *
424    * @param count the number of empty lines between 2 standalone Blocks
425    */
426    void onEmptyLines(@Default("1") int count);
427   
428    /**
429    * A portion of text.
430    *
431    * @param content the string to protected from rendering
432    * @param inline if true the text content is located in a inline content (like paragraph, etc.)
433    * @param parameters a generic list of parameters. Example: style="background-color: blue"
434    */
435    void onVerbatim(@Name("content") String content, boolean inline, @Default("") Map<String, String> parameters);
436   
437    /**
438    * Some text to inject directly into the listener output without parsing it. For example a HTML macro could inject
439    * directly some HTML entered by the user into the rendered HTML output. Note that it's not recommended to use this
440    * event in most cases since it can lead to invalid content being generated and in addition most listener
441    * implementations will not understand the injected text and will just ignore it.
442    *
443    * @param content the text to inject
444    * @param syntax the syntax in which the text is written. This is useful so that listener implementations can decide
445    * whether they can handle direct inject for that syntax
446    */
447    void onRawText(@Name("content") String content, Syntax syntax);
448    }