Usage of nsIXULTemplateResult Interface

 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

 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)

 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)

 Translate a ref attribute string into a result. This is used as the
 reference point by the template builder when generating the first level
 of content. For recursive generation, the result from the parent
 generation phase will be used directly as the reference so a translation
 is not needed. This allows all levels to be generated using objects that
 all implement the nsIXULTemplateResult interface.

 This method may be called before initializeForBuilding, so the
 implementation may use the supplied datasource if it is needed to
 translate the reference.

 @param aDatasource datasource for the data
 @param aRefString the ref attribute string

 @return the translated ref

nsIXULTemplateResult translateRef(in nsISupports aDatasource, in AString aRefString)

 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 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 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 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)

 Compare two results to determine their order, used when sorting results.
 This method should return -1 when the left result is less than the right,
 0 if both are equivalent, and 1 if the left is greater than the right.
 The comparison should only consider the values for the specified
 variable.

 If the comparison variable is null, the results may be
 sorted in a natural order, for instance, based on the order the data in
 stored in the datasource.

 This method must only be called with results that were created by this
 query processor.

 @param aLeft the left result to compare
 @param aRight the right result to compare
 @param aVar variable to compare

 @param returns -1 if less, 0 if equal, or 1 if greater

PRInt32 compareResults(in nsIXULTemplateResult aLeft, in nsIXULTemplateResult aRight, in nsIAtom aVar)

 Generate the results of a query and return them in an enumerator. The
 enumerator must contain nsIXULTemplateResult objects. If there are no
 results, an empty enumerator must be returned.

 The datasource will be the same as the one passed to the earlier
 initializeForBuilding method. The context reference (aRef) is a reference
 point used when calculating results.

 The value of aQuery must be the result of a previous call to compileQuery
 from this query processor. This method may be called multiple times,
 typically with different values for aRef.

 @param aDatasource datasource for the data
 @param aRef context reference value used as a starting point
 @param aQuery the compiled query returned from query compilation

 @returns an enumerator of nsIXULTemplateResult objects as the results

 @throws NS_ERROR_INVALID_ARG if aQuery is invalid

nsISimpleEnumerator generateResults(in nsISupports aDatasource, in nsIXULTemplateResult aRef, in nsISupports aQuery)

 Compare two results to determine their order, used when sorting results.
 This method should return -1 when the left result is less than the right,
 0 if both are equivalent, and 1 if the left is greater than the right.
 The comparison should only consider the values for the specified
 variable.

 If the comparison variable is null, the results may be
 sorted in a natural order, for instance, based on the order the data in
 stored in the datasource.

 This method must only be called with results that were created by this
 query processor.

 @param aLeft the left result to compare
 @param aRight the right result to compare
 @param aVar variable to compare

 @param returns -1 if less, 0 if equal, or 1 if greater

PRInt32 compareResults(in nsIXULTemplateResult aLeft, in nsIXULTemplateResult aRight, in nsIAtom aVar)

 Evaluate a result and return true if the result is accepted by this
 filter, or false if it is rejected. Accepted results will have output
 generated for them for the rule. Rejected results will not, but they
 may still match another rule.

 @param aRef the result to examine
 @param aRule the rule node

 @return true if the rule matches

boolean match(in nsIXULTemplateResult aRef, in nsIDOMNode aRule)