1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/embedding/components/find/public/nsIWebBrowserFind.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,143 @@
1.4 +/* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
1.5 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.6 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.7 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.8 +
1.9 +#include "nsISupports.idl"
1.10 +
1.11 +#include "domstubs.idl"
1.12 +
1.13 +/* THIS IS A PUBLIC EMBEDDING API */
1.14 +
1.15 +
1.16 +/**
1.17 + * nsIWebBrowserFind
1.18 + *
1.19 + * Searches for text in a web browser.
1.20 + *
1.21 + * Get one by doing a GetInterface on an nsIWebBrowser.
1.22 + *
1.23 + * By default, the implementation will search the focussed frame, or
1.24 + * if there is no focussed frame, the web browser content area. It
1.25 + * does not by default search subframes or iframes. To change this
1.26 + * behaviour, and to explicitly set the frame to search,
1.27 + * QueryInterface to nsIWebBrowserFindInFrames.
1.28 + */
1.29 +
1.30 +[scriptable, uuid(2f977d44-5485-11d4-87e2-0010a4e75ef2)]
1.31 +interface nsIWebBrowserFind : nsISupports
1.32 +{
1.33 + /**
1.34 + * findNext
1.35 + *
1.36 + * Finds, highlights, and scrolls into view the next occurrence of the
1.37 + * search string, using the current search settings. Fails if the
1.38 + * search string is empty.
1.39 + *
1.40 + * @return Whether an occurrence was found
1.41 + */
1.42 + boolean findNext();
1.43 +
1.44 + /**
1.45 + * searchString
1.46 + *
1.47 + * The string to search for. This must be non-empty to search.
1.48 + */
1.49 + attribute wstring searchString;
1.50 +
1.51 + /**
1.52 + * findBackwards
1.53 + *
1.54 + * Whether to find backwards (towards the beginning of the document).
1.55 + * Default is false (search forward).
1.56 + */
1.57 + attribute boolean findBackwards;
1.58 +
1.59 + /**
1.60 + * wrapFind
1.61 + *
1.62 + * Whether the search wraps around to the start (or end) of the document
1.63 + * if no match was found between the current position and the end (or
1.64 + * beginning). Works correctly when searching backwards. Default is
1.65 + * false.
1.66 + */
1.67 + attribute boolean wrapFind;
1.68 +
1.69 + /**
1.70 + * entireWord
1.71 + *
1.72 + * Whether to match entire words only. Default is false.
1.73 + */
1.74 + attribute boolean entireWord;
1.75 +
1.76 + /**
1.77 + * matchCase
1.78 + *
1.79 + * Whether to match case (case sensitive) when searching. Default is false.
1.80 + */
1.81 + attribute boolean matchCase;
1.82 +
1.83 + /**
1.84 + * searchFrames
1.85 + *
1.86 + * Whether to search through all frames in the content area. Default is true.
1.87 + *
1.88 + * Note that you can control whether the search propagates into child or
1.89 + * parent frames explicitly using nsIWebBrowserFindInFrames, but if one,
1.90 + * but not both, of searchSubframes and searchParentFrames are set, this
1.91 + * returns false.
1.92 + */
1.93 + attribute boolean searchFrames;
1.94 +};
1.95 +
1.96 +
1.97 +
1.98 +/**
1.99 + * nsIWebBrowserFindInFrames
1.100 + *
1.101 + * Controls how find behaves when multiple frames or iframes are present.
1.102 + *
1.103 + * Get by doing a QueryInterface from nsIWebBrowserFind.
1.104 + */
1.105 +
1.106 +[scriptable, uuid(e0f5d182-34bc-11d5-be5b-b760676c6ebc)]
1.107 +interface nsIWebBrowserFindInFrames : nsISupports
1.108 +{
1.109 + /**
1.110 + * currentSearchFrame
1.111 + *
1.112 + * Frame at which to start the search. Once the search is done, this will
1.113 + * be set to be the last frame searched, whether or not a result was found.
1.114 + * Has to be equal to or contained within the rootSearchFrame.
1.115 + */
1.116 + attribute nsIDOMWindow currentSearchFrame;
1.117 +
1.118 + /**
1.119 + * rootSearchFrame
1.120 + *
1.121 + * Frame within which to confine the search (normally the content area frame).
1.122 + * Set this to only search a subtree of the frame hierarchy.
1.123 + */
1.124 + attribute nsIDOMWindow rootSearchFrame;
1.125 +
1.126 + /**
1.127 + * searchSubframes
1.128 + *
1.129 + * Whether to recurse down into subframes while searching. Default is true.
1.130 + *
1.131 + * Setting nsIWebBrowserfind.searchFrames to true sets this to true.
1.132 + */
1.133 + attribute boolean searchSubframes;
1.134 +
1.135 + /**
1.136 + * searchParentFrames
1.137 + *
1.138 + * Whether to allow the search to propagate out of the currentSearchFrame into its
1.139 + * parent frame(s). Search is always confined within the rootSearchFrame. Default
1.140 + * is true.
1.141 + *
1.142 + * Setting nsIWebBrowserfind.searchFrames to true sets this to true.
1.143 + */
1.144 + attribute boolean searchParentFrames;
1.145 +
1.146 +};
