Classes

Class	Line #	Total Statements	% Filtered	Complexity	Uncovered Elements	TOTAL Coverage	Actions
Listener	52	0	-	0	0	-1.0 -	Show methods

Class Listener

Class Listener	Line # 52	Total Statements 0	% Filtered -	Complexity 0	Uncovered Elements 0	TOTAL Coverage -1.0 -

 

Contributing tests

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		*/
		- Uncovered Elements: 0 (0) Complexity: 0 Complexity Density: -
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		}