Add m-esr52 at 52.6.0

1 files changed, 409 insertions, 0 deletions

diff --git a/dom/xul/templates/nsIXULTemplateBuilder.idl b/dom/xul/templates/nsIXULTemplateBuilder.idl
new file mode 100644
index 000000000..755b57e57
--- /dev/null
+++ b/dom/xul/templates/nsIXULTemplateBuilder.idl
@@ -0,0 +1,409 @@
+/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+#include "domstubs.idl"
+
+interface nsIAtom;
+interface nsIContent;
+interface nsIXULBuilderListener;
+interface nsIXULTemplateResult;
+interface nsIXULTemplateRuleFilter;
+interface nsIXULTemplateQueryProcessor;
+interface nsIRDFResource;
+interface nsIRDFCompositeDataSource;
+interface nsIDOMDataTransfer;
+
+/**
+ * A template builder, given an input source of data, a template, and a
+ * reference point, generates a list of results from the input, and copies
+ * part of the template for each result. Templates may generate content
+ * recursively, using the same template, but with the previous iteration's
+ * results as the reference point. As an example, for an XML datasource the
+ * initial reference point would be a specific node in the DOM tree and a
+ * template might generate a list of all child nodes. For the next iteration,
+ * those children would be used to generate output for their child nodes and
+ * so forth.
+ *
+ * A template builder is attached to a single DOM node; this node is called
+ * the root node and is expected to contain a XUL template element as a direct
+ * child. Different template builders may be specialized in the manner in
+ * which they generate and display the resulting content from the template.
+ *
+ * The structure of a template is as follows:
+ *
+ * <rootnode datasources="" ref="">
+ *   <template>
+ *     <queryset>
+ *       <query>
+ *       </query>
+ *       <rule>
+ *         <conditions>...</conditions>
+ *         <bindings>...</bindings>
+ *         <action>...</action>
+ *       </rule>
+ *     </queryset>
+ *   </template>
+ * </rootnode>
+ *
+ * The datasources attribute on the root node is used to identify the source
+ * of data to be used. The ref attribute is used to specify the reference
+ * point for the query. Currently, the datasource will either be an
+ * nsIRDFDataSource or a DOM node. In the future, other datasource types may
+ * be used.
+ *
+ * The <queryset> element contains a single query and one or more <rule>
+ * elements. There may be more than one <queryset> if multiple queries are
+ * desired, and this element is optional if only one query is needed -- in
+ * that case the <query> and <rule>s are allowed to be children of the
+ * <template> node
+ *
+ * The contents of the query are processed by a separate component called a
+ * query processor. This query processor is expected to use this query to
+ * generate results when asked by the template builder. The template builder
+ * then generates output for each result based on the <rule> elements.
+ *
+ * This allows the query processor to be specific to a particular kind of
+ * input data or query syntax, while the template builder remains independent
+ * of the kind of data being used. Due to this, the query processor will be
+ * supplied with the datasource and query which the template builder handles
+ * in an opaque way, while the query processor handles these more
+ * specifically.
+ *
+ * Results implement the nsIXULTemplateResult interface and may be identified
+ * by an id which must be unique within a given set of query results.
+ *
+ * Each query may be accompanied by one or more <rule> elements. These rules
+ * are evaluated by the template builder for each result produced by the
+ * query. A rule consists of conditions that cause a rule to be either
+ * accepted or rejected. The condition syntax allows for common conditional
+ * handling; additional filtering may be applied by adding a custom filter
+ * to a rule with the builder's addRuleFilter method.
+ *
+ * If a result passes a rule's conditions, this is considered a match, and the
+ * content within the rule's <action> body is inserted as a sibling of the
+ * <template>, assuming the template builder creates real DOM content. Only
+ * one rule will match a result. For a tree builder, for example, the content
+ * within the action body is used to create the tree rows instead. A matching
+ * result must have its ruleMatched method called. When a result no longer
+ * matches, the result's hasBeenRemoved method must be called.
+ *
+ * Optionally, the rule may have a <bindings> section which may be used to
+ * define additional variables to be used within an action body. Each of these
+ * declared bindings must be supplied to the query processor via its
+ * addBinding method. The bindings are evaluated after a rule has matched.
+ *
+ * Templates may generate content recursively, using the previous iteration's
+ * results as reference point to invoke the same queries. Since the reference
+ * point is different, different output will typically be generated.
+ *
+ * The reference point nsIXULTemplateResult object for the first iteration is
+ * determined by calling the query processor's translateRef method using the
+ * value of the root node's ref attribute. This object may be retrieved later
+ * via the builder's rootResult property.
+ *
+ * For convenience, each reference point as well as all results implement the
+ * nsIXULTemplateResult interface, allowing the result objects from each
+ * iteration to be used directly as the reference points for the next
+ * iteration.
+ *
+ * When using multiple queries, each may generate results with the same id.
+ * More than one of these results may match one of the rules in their
+ * respective queries, however only the result for the earliest matching query
+ * in the template becomes the active match and generates output. The
+ * addResult, removeResult, replaceResult and resultBindingChanged methods may
+ * be called by the query processor to indicate that the set of valid results
+ * has changed, such that a different query may match. If a different match
+ * would become active, the content for the existing match is removed and the
+ * content for the new match is generated. A query processor is not required
+ * to provide any support for updating results after they have been generated.
+ *
+ * See http://wiki.mozilla.org/XUL:Templates_Plan for details about templates.
+ */
+[scriptable, uuid(A583B676-5B02-4F9C-A0C9-CB850CB99818)]
+interface nsIXULTemplateBuilder : nsISupports
+{
+    /**
+     * The root node in the DOM to which this builder is attached.
+     */
+    readonly attribute nsIDOMElement root;
+
+    /**
+     * The opaque datasource object that is used for the template. This object
+     * is created by the getDataSource method of the query processor. May be
+     * null if the datasource has not been loaded yet. Set this attribute to
+     * use a different datasource and rebuild the template.
+     *
+     * For an RDF datasource, this will be the same as the database. For XML
+     * this will be the nsIDOMNode for the datasource document or node for
+     * an inline reference (such as #name). Other query processors may use
+     * other types for the datasource.
+     */
+    attribute nsISupports datasource;
+
+    /**
+     * The composite datasource that the template builder observes
+     * and uses to create content. This is used only for RDF queries and is
+     * maintained for backwards compatibility. It will be the same object as
+     * the datasource property. For non-RDF queries, it will always be null.
+     */
+    readonly attribute nsIRDFCompositeDataSource database;
+
+    /**
+     * The virtual result representing the starting reference point,
+     * determined by calling the query processor's translateRef method
+     * with the root node's ref attribute as an argument.
+     */
+    readonly attribute nsIXULTemplateResult rootResult;
+
+    /**
+     * The query processor used to generate results.
+     */
+    [noscript] readonly attribute nsIXULTemplateQueryProcessor queryProcessor;
+
+    /**
+     * Force the template builder to rebuild its content. All existing content
+     * will be removed first. The query processor's done() method will be
+     * invoked during cleanup, followed by its initializeForBuilding method
+     * when the content is to be regenerated.
+     * 
+     */
+    void rebuild();
+
+    /**
+     * Reload any of our RDF datasources that support nsIRDFRemoteDatasource. 
+     *
+     * @note This is a temporary hack so that remote-XUL authors can
+     *       reload remote datasources. When RDF becomes remote-scriptable,
+     *       this will no longer be necessary.
+     */
+    void refresh();
+
+    /**
+     * Inform the template builder that a new result is available. The builder
+     * will add this result to the set of results. The query node that the
+     * new result applies to must be specified using the aQueryNode parameter.
+     *
+     * The builder will apply the rules associated with the query to the new
+     * result, unless a result with the same id from an earlier query
+     * supersedes it, and the result's RuleMatched method will be called if it
+     * matches.
+     *
+     * @param aResult the result to add
+     * @param aQueryNode the query that the result applies to
+     *
+     * @throws NS_ERROR_NULL_POINTER if aResult or aQueryNode are null
+     */
+    void addResult(in nsIXULTemplateResult aResult, in nsIDOMNode aQueryNode);
+
+    /**
+     * Inform the template builder that a result no longer applies. The builder
+     * will call the remove content generated for the result, if any. If a different
+     * query would then match instead, it will become the active match. This
+     * method will have no effect if the result isn't known to the builder.
+     *
+     * @param aResult the result to remove
+     *
+     * @throws NS_ERROR_NULL_POINTER if aResult is null
+     */
+    void removeResult(in nsIXULTemplateResult aResult);
+
+    /**
+     * Inform the template builder that one result should be replaced with
+     * another. Both the old result (aOldResult) and the new result
+     * (aNewResult) must have the same id. The query node that the new result
+     * applies to must be specified using the aQueryNode parameter.
+     *
+     * This method is expected to have the same effect as calling both
+     * removeResult for the old result and addResult for the new result.
+     *
+     * @param aOldResult the old result
+     * @param aNewResult the new result
+     * @param aQueryNode the query that the new result applies to
+     *
+     * @throws NS_ERROR_NULL_POINTER if either argument is null, or
+     *         NS_ERROR_INVALID_ARG if the ids don't match
+     */
+    void replaceResult(in nsIXULTemplateResult aOldResult,
+                       in nsIXULTemplateResult aNewResult,
+                       in nsIDOMNode aQueryNode);
+
+    /**
+     * Inform the template builder that one or more of the optional bindings
+     * for a result has changed. In this case, the rules are not reapplied as
+     * it is expected that the same rule will still apply. The builder will
+     * resynchronize any variables that are referenced in the action body.
+     *
+     * @param aResult the result to change
+     *
+     * @throws NS_ERROR_NULL_POINTER if aResult is null
+     */
+    void resultBindingChanged(in nsIXULTemplateResult aResult);
+
+    /**
+     * Return the result for a given id. Only one such result is returned and
+     * is always the result with that id associated with the active match.
+     * This method will return null is there is no result for the id.
+     *
+     * @param aId the id to return the result for
+     */
+    nsIXULTemplateResult getResultForId(in AString aId);
+
+    /**
+     * Retrieve the result corresponding to a generated element, or null is
+     * there isn't one.
+     *
+     * @param aContent element to result the result of
+     */
+    nsIXULTemplateResult getResultForContent(in nsIDOMElement aElement);
+
+    /**
+     * Returns true if the node has content generated for it. This method is
+     * intended to be called only by the RDF query processor. If aTag is set,
+     * the content must have a tag name that matches aTag. aTag may be ignored
+     * for builders that don't generate real DOM content.
+     *
+     * @param aNode node to check
+     * @param aTag tag that must match
+     */
+    boolean hasGeneratedContent(in nsIRDFResource aNode, in nsIAtom aTag);
+
+    /**
+     * Adds a rule filter for a given rule, which may be used for specialized
+     * rule filtering. Any existing filter on the rule is removed. The default
+     * conditions specified inside the <rule> tag are applied before the
+     * rule filter is applied, meaning that the filter may be used to further
+     * filter out results but not reaccept results that have already been
+     * rejected.
+     *
+     * @param aRule the rule to apply the filter to
+     * @param aFilter the filter to add
+     */
+    void addRuleFilter(in nsIDOMNode aRule, in nsIXULTemplateRuleFilter aFilter);
+
+    /**
+     * Called to initialize a XUL content builder on a particular root
+     * element. This element presumably has a ``datasources''
+     * attribute, which the builder will parse to set up the template
+     * builder's datasources.
+     */
+    [noscript] void init(in nsIContent aElement);
+
+    /**
+     * Invoked lazily by a XUL element that needs its child content built.
+     * If aForceCreation is true, then the contents of an element will be
+     * generated even if it is closed. If false, the element will only
+     * generate its contents if it is open. This behaviour is used with menus.
+     */
+    [noscript] void createContents(in nsIContent aElement,
+                                   in boolean aForceCreation);
+
+    /**
+     * Add a listener to this template builder. The template builder
+     * holds a strong reference to the listener.
+     */
+    void addListener(in nsIXULBuilderListener aListener);
+
+    /**
+     * Remove a listener from this template builder.
+     */
+    void removeListener(in nsIXULBuilderListener aListener);
+};
+
+/**
+ * nsIXULTreeBuilderObserver
+ *  This interface allows clients of the XULTreeBuilder to define domain 
+ *  specific handling of specific nsITreeView methods that 
+ *  XULTreeBuilder does not implement.
+ */
+[scriptable, uuid(57CED9A7-EC0B-4A0E-8AEB-5DA32EBE951C)]
+interface nsIXULTreeBuilderObserver : nsISupports
+{
+    const long DROP_BEFORE = -1;
+    const long DROP_ON = 0;
+    const long DROP_AFTER = 1;
+    /**
+     * Methods used by the drag feedback code to determine if a drag is allowable at
+     * the current location. To get the behavior where drops are only allowed on
+     * items, such as the mailNews folder pane, always return false whe
+     * the orientation is not DROP_ON.
+     */
+    boolean canDrop(in long index, in long orientation, in nsIDOMDataTransfer dataTransfer);
+
+    /**
+     * Called when the user drops something on this view. The |orientation| param
+     * specifies before/on/after the given |row|.
+     */
+    void onDrop(in long row, in long orientation, in nsIDOMDataTransfer dataTransfer);
+ 
+    /** 
+     * Called when an item is opened or closed. 
+     */
+    void onToggleOpenState (in long index);
+
+    /** 
+	 * Called when a header is clicked.
+     */
+    void onCycleHeader(in wstring colID, in nsIDOMElement elt);
+
+    /**
+     * Called when a cell in a non-selectable cycling column (e.g. 
+     * unread/flag/etc.) is clicked.
+     */
+    void onCycleCell(in long row, in wstring colID);
+
+    /** 
+     * Called when selection in the tree changes
+     */
+    void onSelectionChanged();
+
+    /**
+     * A command API that can be used to invoke commands on the selection.  
+     * The tree will automatically invoke this method when certain keys 
+     * are pressed.  For example, when the DEL key is pressed, performAction 
+     * will be called with the "delete" string. 
+     */
+    void onPerformAction(in wstring action);
+
+    /**
+     * A command API that can be used to invoke commands on a specific row.
+     */
+    void onPerformActionOnRow(in wstring action, in long row);
+
+    /**
+     * A command API that can be used to invoke commands on a specific cell.
+     */
+    void onPerformActionOnCell(in wstring action, in long row, in wstring colID);
+};
+
+[scriptable, uuid(06b31b15-ebf5-4e74-a0e2-6bc0a18a3969)]
+interface nsIXULTreeBuilder : nsISupports
+{
+    /**
+     * Retrieve the RDF resource associated with the specified row.
+     */
+    nsIRDFResource getResourceAtIndex(in long aRowIndex);
+
+    /**
+     * Retrieve the index associated with specified RDF resource.
+     */
+    long getIndexOfResource(in nsIRDFResource resource);
+
+    /** 
+     * Add a Tree Builder Observer to handle Tree View 
+     * methods that the base builder does not implement. 
+     */
+    void addObserver(in nsIXULTreeBuilderObserver aObserver);
+
+    /** 
+     * Remove an Tree Builder Observer.
+     */
+    void removeObserver(in nsIXULTreeBuilderObserver aObserver);
+
+    /** 
+     * Sort the contents of the tree using the specified column.
+     */
+    void sort(in nsIDOMElement aColumnElement);
+};
+