michael@0: /* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public
michael@0:  * License, v. 2.0. If a copy of the MPL was not distributed with this
michael@0:  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
michael@0:  
michael@0: #include "nsISupports.idl"
michael@0: 
michael@0: #include "domstubs.idl"
michael@0: 
michael@0: /* THIS IS A PUBLIC EMBEDDING API */
michael@0: 
michael@0: 
michael@0: /**
michael@0:  * nsIWebBrowserFind
michael@0:  *
michael@0:  * Searches for text in a web browser.
michael@0:  *
michael@0:  * Get one by doing a GetInterface on an nsIWebBrowser.
michael@0:  *
michael@0:  * By default, the implementation will search the focussed frame, or
michael@0:  * if there is no focussed frame, the web browser content area. It
michael@0:  * does not by default search subframes or iframes. To change this
michael@0:  * behaviour, and to explicitly set the frame to search, 
michael@0:  * QueryInterface to nsIWebBrowserFindInFrames.
michael@0:  */
michael@0: 
michael@0: [scriptable, uuid(2f977d44-5485-11d4-87e2-0010a4e75ef2)]
michael@0: interface nsIWebBrowserFind : nsISupports
michael@0: {
michael@0:     /**
michael@0:      * findNext
michael@0:      *
michael@0:      * Finds, highlights, and scrolls into view the next occurrence of the
michael@0:      * search string, using the current search settings. Fails if the
michael@0:      * search string is empty.
michael@0:      *
michael@0:      * @return  Whether an occurrence was found
michael@0:      */
michael@0: 	boolean		findNext();
michael@0: 
michael@0:     /**
michael@0:      * searchString
michael@0:      *
michael@0:      * The string to search for. This must be non-empty to search.
michael@0:      */
michael@0:     attribute wstring searchString;
michael@0:     
michael@0:     /**
michael@0:      * findBackwards
michael@0:      *
michael@0:      * Whether to find backwards (towards the beginning of the document).
michael@0:      * Default is false (search forward).
michael@0:      */
michael@0:     attribute boolean findBackwards;
michael@0: 
michael@0:     /**
michael@0:      * wrapFind
michael@0:      *
michael@0:      * Whether the search wraps around to the start (or end) of the document
michael@0:      * if no match was found between the current position and the end (or
michael@0:      * beginning). Works correctly when searching backwards. Default is
michael@0:      * false.
michael@0:      */
michael@0:     attribute boolean wrapFind;
michael@0: 
michael@0:     /**
michael@0:      * entireWord
michael@0:      *
michael@0:      * Whether to match entire words only. Default is false.
michael@0:      */
michael@0:     attribute boolean entireWord;
michael@0: 
michael@0:     /**
michael@0:      * matchCase
michael@0:      *
michael@0:      * Whether to match case (case sensitive) when searching. Default is false.
michael@0:      */
michael@0:     attribute boolean matchCase;
michael@0: 
michael@0:     /**
michael@0:      * searchFrames
michael@0:      *
michael@0:      * Whether to search through all frames in the content area. Default is true.
michael@0:      * 
michael@0:      * Note that you can control whether the search propagates into child or
michael@0:      * parent frames explicitly using nsIWebBrowserFindInFrames, but if one,
michael@0:      * but not both, of searchSubframes and searchParentFrames are set, this
michael@0:      * returns false.
michael@0:      */
michael@0:     attribute boolean searchFrames;
michael@0: };
michael@0: 
michael@0: 
michael@0: 
michael@0: /**
michael@0:  * nsIWebBrowserFindInFrames
michael@0:  *
michael@0:  * Controls how find behaves when multiple frames or iframes are present.
michael@0:  *
michael@0:  * Get by doing a QueryInterface from nsIWebBrowserFind.
michael@0:  */
michael@0:  
michael@0: [scriptable, uuid(e0f5d182-34bc-11d5-be5b-b760676c6ebc)]
michael@0: interface nsIWebBrowserFindInFrames : nsISupports
michael@0: {
michael@0:     /**
michael@0:      * currentSearchFrame
michael@0:      *
michael@0:      * Frame at which to start the search. Once the search is done, this will
michael@0:      * be set to be the last frame searched, whether or not a result was found.
michael@0:      * Has to be equal to or contained within the rootSearchFrame.
michael@0:      */
michael@0:     attribute nsIDOMWindow  currentSearchFrame;
michael@0: 
michael@0:     /**
michael@0:      * rootSearchFrame
michael@0:      *
michael@0:      * Frame within which to confine the search (normally the content area frame).
michael@0:      * Set this to only search a subtree of the frame hierarchy.
michael@0:      */
michael@0:     attribute nsIDOMWindow  rootSearchFrame;
michael@0:         
michael@0:     /**
michael@0:      * searchSubframes
michael@0:      *
michael@0:      * Whether to recurse down into subframes while searching. Default is true.
michael@0:      *
michael@0:      * Setting nsIWebBrowserfind.searchFrames to true sets this to true.
michael@0:      */
michael@0:     attribute boolean searchSubframes;
michael@0:     
michael@0:     /**
michael@0:      * searchParentFrames
michael@0:      *
michael@0:      * Whether to allow the search to propagate out of the currentSearchFrame into its
michael@0:      * parent frame(s). Search is always confined within the rootSearchFrame. Default
michael@0:      * is true.
michael@0:      *
michael@0:      * Setting nsIWebBrowserfind.searchFrames to true sets this to true.
michael@0:      */
michael@0:     attribute boolean searchParentFrames;
michael@0: 
michael@0: };