/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*-
 *
 * The contents of this file are subject to the Netscape Public
 * License Version 1.1 (the "License"); you may not use this file
 * except in compliance with the License. You may obtain a copy of
 * the License at http://www.mozilla.org/NPL/
 *
 * Software distributed under the License is distributed on an "AS
 * IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
 * implied. See the License for the specific language governing
 * rights and limitations under the License.
 *
 * The Original Code is mozilla.org code.
 *
 * The Initial Developer of the Original Code is Netscape
 * Communications Corporation.  Portions created by Netscape are
 * Copyright (C) 1998 Netscape Communications Corporation. All
 * Rights Reserved.
 *
 * Contributor(s): 
 */

#include "nsIEditorShell.idl"

%{C++
class nsIDOMWindowInternal;
class nsIEditorShell;
%}

/*----------------------------- nsIFindComponent ------------------------------
| This file describes the interface for Mozilla's pluggable "find" component  |
| that provides the implementation of the browser's "find in document"        |
| function (and perhaps will be generalized to support similar searching in   |
| other contexts).                                                            |
|                                                                             |
| The component itself is a singleton (one per executing application).  To    |
| handle searching on a per-document basis, this interface supplies a         |
| CreateContext() function that creates a search context (generally, on a     |
| per document, and thus per-browser-window, basis).                          |
|                                                                             |
| The component itself will "remember" the last string searched (via any      |
| context).  This way, a search in a new context (browser window) will be     |
| able to search for the same string (by default).                            |
|                                                                             |
| Clients (e.g., the browser window object) will generally use this interface |
| in this manner:                                                             |
|   1. Hold a reference to the singleton "find component".                    |
|   2. On initial search, ask that component to create a search "context."    |
|   3. Reset the context whenever the underlying web shell changes (but since |
|      a browser will usually reuse a single web shell, this won't be of      |
|      concern except in obscure cases).                                      |
|   4. Forward "find" and "find next" requests to the component, along        |
|      with the appropriate search context object.                            |
|   5. Release() the search context object and the find component when the    |
|      browser window closes.                                                 |
-----------------------------------------------------------------------------*/
[scriptable, uuid(a6cf90ee-15b3-11d2-932e-00805f8add32)]interface nsIFindComponent : nsISupports
{

    /*---------------------------- CreateContext ------------------------------
    | Create a "search context" for the given document.  Subsequent Find and  |
    | FindNext requests that provide the returned search context will find    |
    | the appropriate search string in aWebShell.                             |
    |                                                                         |
    | The editor that's passed in is only required for replace. If you pass   |
    | in a read-only webshell, then pass nsnull for the editor.               |
    |                                                                         |
    | The result is of the xpcom equivalent of an opaque type.  It's true type|
    | is defined by the implementation of this interface.  Clients ought never|
    | have to do QueryInterface to convert this to something more elaborate.  |
    | Clients do have to call Release() when they're no longer interested in  |
    | this search context.                                                    |
    -------------------------------------------------------------------------*/
    nsISupports createContext(in nsIDOMWindowInternal aWindow, in nsIEditorShell aEditor);

    /*--------------------------------- Find ----------------------------------
    | Finds the "first" occurrence of a string in the given search context    |
    | (i.e., document).                                                       |
    |                                                                         |
    | Please note that you don't provide the string to search for!            |
    |                                                                         |
    | This might seem odd, but that's the way it's designed.  Prompting the   |
    | user for the string (and for various search options such as "ignore     |
    | case" and "search backward") is up to the implementation of this        |
    | component.                                                              |
    -------------------------------------------------------------------------*/
    boolean find( in nsISupports aContext );

    /*------------------------------- FindNext --------------------------------
    | Finds the next occurrence (of the previously searched for string) in    |
    | the given search context (document).                                    |
    |                                                                         |
    | If no previous Find has been performed with this context, then the      |
    | find component will use the last find performed for any context.        |
    -------------------------------------------------------------------------*/
    boolean findNext( in nsISupports aContext );

    /*--------------------------------- Replace -------------------------------
    | Replace the currently selected text. It is intended that the string used|
    | for replacement is sourced internally to the component (e.g. from a     |
    | search/replace dialog).                                                 |
    |                                                                         |
    | Returns an error if the current context does not allow replacement.     |
    -------------------------------------------------------------------------*/
    void replace( in nsISupports aContext );

    /*------------------------------- ReplaceNext -----------------------------
    | Replaces the currently selected text, then searches for next occurrence |
    | (of previously searched for string) in the given search context         |
    | (document). If allOccurrences is TRUE, all occurrences of previously    |
    | searched for string will be replaced during this method call.
    -------------------------------------------------------------------------*/
    boolean replaceNext( in nsISupports aContext, in boolean allOccurrences );

    /*----------------------------- ResetContext ------------------------------
    | Reset the given search context to search a new web shell.  Generally,   |
    | this will be the equivalent of calling Release() on the old context and |
    | then creating a new one for aNewWebShell.                               |
    --------------------------------------------------------------------------*/
    void resetContext(in nsISupports aContext, in nsIDOMWindowInternal aWindow,
                                  in nsIEditorShell aEditor );
};

%{C++
#define NS_IFINDCOMPONENT_CONTRACTID "@mozilla.org/appshell/component/find;1"
#define NS_IFINDCOMPONENT_CLASSNAME "Mozilla Find Component"
%}
