/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */ /* ***** BEGIN LICENSE BLOCK ***** * Version: NPL 1.1/GPL 2.0/LGPL 2.1 * * 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 the Initial Developer are Copyright (C) 1998 * the Initial Developer. All Rights Reserved. * * Contributor(s): * * Alternatively, the contents of this file may be used under the terms of * either the GNU General Public License Version 2 or later (the "GPL"), or * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"), * in which case the provisions of the GPL or the LGPL are applicable instead * of those above. If you wish to allow use of your version of this file only * under the terms of either the GPL or the LGPL, and not to allow others to * use your version of this file under the terms of the NPL, indicate your * decision by deleting the provisions above and replace them with the notice * and other provisions required by the GPL or the LGPL. If you do not delete * the provisions above, a recipient may use your version of this file under * the terms of any one of the NPL, the GPL or the LGPL. * * ***** END LICENSE BLOCK ***** */ #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" %} .