content/xul/templates/public/nsIXULTemplateBuilder.idl@129ffea94266
content/xul/templates/public/nsIXULTemplateBuilder.idl
Sat, 03 Jan 2015 20:18:00 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Sat, 03 Jan 2015 20:18:00 +0100
- branch
- TOR_BUG_3246
- changeset 7
- 129ffea94266
- permissions
- -rw-r--r--
Conditionally enable double key logic according to:
private browsing mode or privacy.thirdparty.isolate preference and
implement in GetCookieStringCommon and FindCookie where it counts...
With some reservations of how to convince FindCookie users to test
condition and pass a nullptr when disabling double key logic.
1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
2 /* This Source Code Form is subject to the terms of the Mozilla Public
3 * License, v. 2.0. If a copy of the MPL was not distributed with this
4 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
6 #include "domstubs.idl"
8 interface nsIAtom;
9 interface nsIContent;
10 interface nsIXULBuilderListener;
11 interface nsIXULTemplateResult;
12 interface nsIXULTemplateRuleFilter;
13 interface nsIXULTemplateQueryProcessor;
14 interface nsIRDFResource;
15 interface nsIRDFCompositeDataSource;
16 interface nsIDOMDataTransfer;
18 /**
19 * A template builder, given an input source of data, a template, and a
20 * reference point, generates a list of results from the input, and copies
21 * part of the template for each result. Templates may generate content
22 * recursively, using the same template, but with the previous iteration's
23 * results as the reference point. As an example, for an XML datasource the
24 * initial reference point would be a specific node in the DOM tree and a
25 * template might generate a list of all child nodes. For the next iteration,
26 * those children would be used to generate output for their child nodes and
27 * so forth.
28 *
29 * A template builder is attached to a single DOM node; this node is called
30 * the root node and is expected to contain a XUL template element as a direct
31 * child. Different template builders may be specialized in the manner in
32 * which they generate and display the resulting content from the template.
33 *
34 * The structure of a template is as follows:
35 *
36 * <rootnode datasources="" ref="">
37 * <template>
38 * <queryset>
39 * <query>
40 * </query>
41 * <rule>
42 * <conditions>...</conditions>
43 * <bindings>...</bindings>
44 * <action>...</action>
45 * </rule>
46 * </queryset>
47 * </template>
48 * </rootnode>
49 *
50 * The datasources attribute on the root node is used to identify the source
51 * of data to be used. The ref attribute is used to specify the reference
52 * point for the query. Currently, the datasource will either be an
53 * nsIRDFDataSource or a DOM node. In the future, other datasource types may
54 * be used.
55 *
56 * The <queryset> element contains a single query and one or more <rule>
57 * elements. There may be more than one <queryset> if multiple queries are
58 * desired, and this element is optional if only one query is needed -- in
59 * that case the <query> and <rule>s are allowed to be children of the
60 * <template> node
61 *
62 * The contents of the query are processed by a separate component called a
63 * query processor. This query processor is expected to use this query to
64 * generate results when asked by the template builder. The template builder
65 * then generates output for each result based on the <rule> elements.
66 *
67 * This allows the query processor to be specific to a particular kind of
68 * input data or query syntax, while the template builder remains independent
69 * of the kind of data being used. Due to this, the query processor will be
70 * supplied with the datasource and query which the template builder handles
71 * in an opaque way, while the query processor handles these more
72 * specifically.
73 *
74 * Results implement the nsIXULTemplateResult interface and may be identified
75 * by an id which must be unique within a given set of query results.
76 *
77 * Each query may be accompanied by one or more <rule> elements. These rules
78 * are evaluated by the template builder for each result produced by the
79 * query. A rule consists of conditions that cause a rule to be either
80 * accepted or rejected. The condition syntax allows for common conditional
81 * handling; additional filtering may be applied by adding a custom filter
82 * to a rule with the builder's addRuleFilter method.
83 *
84 * If a result passes a rule's conditions, this is considered a match, and the
85 * content within the rule's <action> body is inserted as a sibling of the
86 * <template>, assuming the template builder creates real DOM content. Only
87 * one rule will match a result. For a tree builder, for example, the content
88 * within the action body is used to create the tree rows instead. A matching
89 * result must have its ruleMatched method called. When a result no longer
90 * matches, the result's hasBeenRemoved method must be called.
91 *
92 * Optionally, the rule may have a <bindings> section which may be used to
93 * define additional variables to be used within an action body. Each of these
94 * declared bindings must be supplied to the query processor via its
95 * addBinding method. The bindings are evaluated after a rule has matched.
96 *
97 * Templates may generate content recursively, using the previous iteration's
98 * results as reference point to invoke the same queries. Since the reference
99 * point is different, different output will typically be generated.
100 *
101 * The reference point nsIXULTemplateResult object for the first iteration is
102 * determined by calling the query processor's translateRef method using the
103 * value of the root node's ref attribute. This object may be retrieved later
104 * via the builder's rootResult property.
105 *
106 * For convenience, each reference point as well as all results implement the
107 * nsIXULTemplateResult interface, allowing the result objects from each
108 * iteration to be used directly as the reference points for the next
109 * iteration.
110 *
111 * When using multiple queries, each may generate results with the same id.
112 * More than one of these results may match one of the rules in their
113 * respective queries, however only the result for the earliest matching query
114 * in the template becomes the active match and generates output. The
115 * addResult, removeResult, replaceResult and resultBindingChanged methods may
116 * be called by the query processor to indicate that the set of valid results
117 * has changed, such that a different query may match. If a different match
118 * would become active, the content for the existing match is removed and the
119 * content for the new match is generated. A query processor is not required
120 * to provide any support for updating results after they have been generated.
121 *
122 * See http://wiki.mozilla.org/XUL:Templates_Plan for details about templates.
123 */
124 [scriptable, uuid(A583B676-5B02-4F9C-A0C9-CB850CB99818)]
125 interface nsIXULTemplateBuilder : nsISupports
126 {
127 /**
128 * The root node in the DOM to which this builder is attached.
129 */
130 readonly attribute nsIDOMElement root;
132 /**
133 * The opaque datasource object that is used for the template. This object
134 * is created by the getDataSource method of the query processor. May be
135 * null if the datasource has not been loaded yet. Set this attribute to
136 * use a different datasource and rebuild the template.
137 *
138 * For an RDF datasource, this will be the same as the database. For XML
139 * this will be the nsIDOMNode for the datasource document or node for
140 * an inline reference (such as #name). Other query processors may use
141 * other types for the datasource.
142 */
143 attribute nsISupports datasource;
145 /**
146 * The composite datasource that the template builder observes
147 * and uses to create content. This is used only for RDF queries and is
148 * maintained for backwards compatibility. It will be the same object as
149 * the datasource property. For non-RDF queries, it will always be null.
150 */
151 readonly attribute nsIRDFCompositeDataSource database;
153 /**
154 * The virtual result representing the starting reference point,
155 * determined by calling the query processor's translateRef method
156 * with the root node's ref attribute as an argument.
157 */
158 readonly attribute nsIXULTemplateResult rootResult;
160 /**
161 * The query processor used to generate results.
162 */
163 [noscript] readonly attribute nsIXULTemplateQueryProcessor queryProcessor;
165 /**
166 * Force the template builder to rebuild its content. All existing content
167 * will be removed first. The query processor's done() method will be
168 * invoked during cleanup, followed by its initializeForBuilding method
169 * when the content is to be regenerated.
170 *
171 */
172 void rebuild();
174 /**
175 * Reload any of our RDF datasources that support nsIRDFRemoteDatasource.
176 *
177 * @note This is a temporary hack so that remote-XUL authors can
178 * reload remote datasources. When RDF becomes remote-scriptable,
179 * this will no longer be necessary.
180 */
181 void refresh();
183 /**
184 * Inform the template builder that a new result is available. The builder
185 * will add this result to the set of results. The query node that the
186 * new result applies to must be specified using the aQueryNode parameter.
187 *
188 * The builder will apply the rules associated with the query to the new
189 * result, unless a result with the same id from an earlier query
190 * supersedes it, and the result's RuleMatched method will be called if it
191 * matches.
192 *
193 * @param aResult the result to add
194 * @param aQueryNode the query that the result applies to
195 *
196 * @throws NS_ERROR_NULL_POINTER if aResult or aQueryNode are null
197 */
198 void addResult(in nsIXULTemplateResult aResult, in nsIDOMNode aQueryNode);
200 /**
201 * Inform the template builder that a result no longer applies. The builder
202 * will call the remove content generated for the result, if any. If a different
203 * query would then match instead, it will become the active match. This
204 * method will have no effect if the result isn't known to the builder.
205 *
206 * @param aResult the result to remove
207 *
208 * @throws NS_ERROR_NULL_POINTER if aResult is null
209 */
210 void removeResult(in nsIXULTemplateResult aResult);
212 /**
213 * Inform the template builder that one result should be replaced with
214 * another. Both the old result (aOldResult) and the new result
215 * (aNewResult) must have the same id. The query node that the new result
216 * applies to must be specified using the aQueryNode parameter.
217 *
218 * This method is expected to have the same effect as calling both
219 * removeResult for the old result and addResult for the new result.
220 *
221 * @param aOldResult the old result
222 * @param aNewResult the new result
223 * @param aQueryNode the query that the new result applies to
224 *
225 * @throws NS_ERROR_NULL_POINTER if either argument is null, or
226 * NS_ERROR_INVALID_ARG if the ids don't match
227 */
228 void replaceResult(in nsIXULTemplateResult aOldResult,
229 in nsIXULTemplateResult aNewResult,
230 in nsIDOMNode aQueryNode);
232 /**
233 * Inform the template builder that one or more of the optional bindings
234 * for a result has changed. In this case, the rules are not reapplied as
235 * it is expected that the same rule will still apply. The builder will
236 * resynchronize any variables that are referenced in the action body.
237 *
238 * @param aResult the result to change
239 *
240 * @throws NS_ERROR_NULL_POINTER if aResult is null
241 */
242 void resultBindingChanged(in nsIXULTemplateResult aResult);
244 /**
245 * Return the result for a given id. Only one such result is returned and
246 * is always the result with that id associated with the active match.
247 * This method will return null is there is no result for the id.
248 *
249 * @param aId the id to return the result for
250 */
251 nsIXULTemplateResult getResultForId(in AString aId);
253 /**
254 * Retrieve the result corresponding to a generated element, or null is
255 * there isn't one.
256 *
257 * @param aContent element to result the result of
258 */
259 nsIXULTemplateResult getResultForContent(in nsIDOMElement aElement);
261 /**
262 * Returns true if the node has content generated for it. This method is
263 * intended to be called only by the RDF query processor. If aTag is set,
264 * the content must have a tag name that matches aTag. aTag may be ignored
265 * for builders that don't generate real DOM content.
266 *
267 * @param aNode node to check
268 * @param aTag tag that must match
269 */
270 boolean hasGeneratedContent(in nsIRDFResource aNode, in nsIAtom aTag);
272 /**
273 * Adds a rule filter for a given rule, which may be used for specialized
274 * rule filtering. Any existing filter on the rule is removed. The default
275 * conditions specified inside the <rule> tag are applied before the
276 * rule filter is applied, meaning that the filter may be used to further
277 * filter out results but not reaccept results that have already been
278 * rejected.
279 *
280 * @param aRule the rule to apply the filter to
281 * @param aFilter the filter to add
282 */
283 void addRuleFilter(in nsIDOMNode aRule, in nsIXULTemplateRuleFilter aFilter);
285 /**
286 * Called to initialize a XUL content builder on a particular root
287 * element. This element presumably has a ``datasources''
288 * attribute, which the builder will parse to set up the template
289 * builder's datasources.
290 */
291 [noscript] void init(in nsIContent aElement);
293 /**
294 * Invoked lazily by a XUL element that needs its child content built.
295 * If aForceCreation is true, then the contents of an element will be
296 * generated even if it is closed. If false, the element will only
297 * generate its contents if it is open. This behaviour is used with menus.
298 */
299 [noscript] void createContents(in nsIContent aElement,
300 in boolean aForceCreation);
302 /**
303 * Add a listener to this template builder. The template builder
304 * holds a strong reference to the listener.
305 */
306 void addListener(in nsIXULBuilderListener aListener);
308 /**
309 * Remove a listener from this template builder.
310 */
311 void removeListener(in nsIXULBuilderListener aListener);
312 };
314 /**
315 * nsIXULTreeBuilderObserver
316 * This interface allows clients of the XULTreeBuilder to define domain
317 * specific handling of specific nsITreeView methods that
318 * XULTreeBuilder does not implement.
319 */
320 [scriptable, uuid(57CED9A7-EC0B-4A0E-8AEB-5DA32EBE951C)]
321 interface nsIXULTreeBuilderObserver : nsISupports
322 {
323 const long DROP_BEFORE = -1;
324 const long DROP_ON = 0;
325 const long DROP_AFTER = 1;
326 /**
327 * Methods used by the drag feedback code to determine if a drag is allowable at
328 * the current location. To get the behavior where drops are only allowed on
329 * items, such as the mailNews folder pane, always return false whe
330 * the orientation is not DROP_ON.
331 */
332 boolean canDrop(in long index, in long orientation, in nsIDOMDataTransfer dataTransfer);
334 /**
335 * Called when the user drops something on this view. The |orientation| param
336 * specifies before/on/after the given |row|.
337 */
338 void onDrop(in long row, in long orientation, in nsIDOMDataTransfer dataTransfer);
340 /**
341 * Called when an item is opened or closed.
342 */
343 void onToggleOpenState (in long index);
345 /**
346 * Called when a header is clicked.
347 */
348 void onCycleHeader(in wstring colID, in nsIDOMElement elt);
350 /**
351 * Called when a cell in a non-selectable cycling column (e.g.
352 * unread/flag/etc.) is clicked.
353 */
354 void onCycleCell(in long row, in wstring colID);
356 /**
357 * Called when selection in the tree changes
358 */
359 void onSelectionChanged();
361 /**
362 * A command API that can be used to invoke commands on the selection.
363 * The tree will automatically invoke this method when certain keys
364 * are pressed. For example, when the DEL key is pressed, performAction
365 * will be called with the "delete" string.
366 */
367 void onPerformAction(in wstring action);
369 /**
370 * A command API that can be used to invoke commands on a specific row.
371 */
372 void onPerformActionOnRow(in wstring action, in long row);
374 /**
375 * A command API that can be used to invoke commands on a specific cell.
376 */
377 void onPerformActionOnCell(in wstring action, in long row, in wstring colID);
378 };
380 [scriptable, uuid(06b31b15-ebf5-4e74-a0e2-6bc0a18a3969)]
381 interface nsIXULTreeBuilder : nsISupports
382 {
383 /**
384 * Retrieve the RDF resource associated with the specified row.
385 */
386 nsIRDFResource getResourceAtIndex(in long aRowIndex);
388 /**
389 * Retrieve the index associated with specified RDF resource.
390 */
391 long getIndexOfResource(in nsIRDFResource resource);
393 /**
394 * Add a Tree Builder Observer to handle Tree View
395 * methods that the base builder does not implement.
396 */
397 void addObserver(in nsIXULTreeBuilderObserver aObserver);
399 /**
400 * Remove an Tree Builder Observer.
401 */
402 void removeObserver(in nsIXULTreeBuilderObserver aObserver);
404 /**
405 * Sort the contents of the tree using the specified column.
406 */
407 void sort(in nsIDOMElement aColumnElement);
408 };
