← Back to branch summary

~ubuntu-branches/ubuntu/precise/kompozer/precise

« back to all changes in this revision

Viewing changes to mozilla/editor/txtsvc/public/nsITextServicesDocument.h

  • Committer: Bazaar Package Importer
  • Author(s): Anthony Yarusso
  • Date: 2007-08-27 01:11:03 UTC
  • Revision ID: james.westby@ubuntu.com-20070827011103-2jgf4s6532gqu2ka
Tags: upstream-0.7.10
Import upstream version 0.7.10

Show diffs side-by-side

added added

removed removed

Lines of Context:
mozilla/editor/txtsvc/public/nsITextServicesDocument.h
 
1
/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
 
2
/* ***** BEGIN LICENSE BLOCK *****
 
3
 * Version: NPL 1.1/GPL 2.0/LGPL 2.1
 
4
 *
 
5
 * The contents of this file are subject to the Netscape Public License
 
6
 * Version 1.1 (the "License"); you may not use this file except in
 
7
 * compliance with the License. You may obtain a copy of the License at
 
8
 * http://www.mozilla.org/NPL/
 
9
 *
 
10
 * Software distributed under the License is distributed on an "AS IS" basis,
 
11
 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
 
12
 * for the specific language governing rights and limitations under the
 
13
 * License.
 
14
 *
 
15
 * The Original Code is mozilla.org code.
 
16
 *
 
17
 * The Initial Developer of the Original Code is 
 
18
 * Netscape Communications Corporation.
 
19
 * Portions created by the Initial Developer are Copyright (C) 1998
 
20
 * the Initial Developer. All Rights Reserved.
 
21
 *
 
22
 * Contributor(s):
 
23
 *
 
24
 *
 
25
 * Alternatively, the contents of this file may be used under the terms of
 
26
 * either the GNU General Public License Version 2 or later (the "GPL"), or
 
27
 * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
 
28
 * in which case the provisions of the GPL or the LGPL are applicable instead
 
29
 * of those above. If you wish to allow use of your version of this file only
 
30
 * under the terms of either the GPL or the LGPL, and not to allow others to
 
31
 * use your version of this file under the terms of the NPL, indicate your
 
32
 * decision by deleting the provisions above and replace them with the notice
 
33
 * and other provisions required by the GPL or the LGPL. If you do not delete
 
34
 * the provisions above, a recipient may use your version of this file under
 
35
 * the terms of any one of the NPL, the GPL or the LGPL.
 
36
 *
 
37
 * ***** END LICENSE BLOCK ***** */
 
38
 
 
39
#ifndef nsITextServicesDocument_h__
 
40
#define nsITextServicesDocument_h__
 
41
 
 
42
#include "nsISupports.h"
 
43
 
 
44
class nsIDOMDocument;
 
45
class nsIDOMRange;
 
46
class nsIPresShell;
 
47
class nsIEditor;
 
48
class nsString;
 
49
class nsITextServicesFilter;
 
50
 
 
51
/*
 
52
TextServicesDocument interface to outside world
 
53
*/
 
54
 
 
55
#define NS_ITEXTSERVICESDOCUMENT_IID            \
 
56
{ /* 019718E1-CDB5-11d2-8D3C-000000000000 */    \
 
57
0x019718e1, 0xcdb5, 0x11d2,                     \
 
58
{ 0x8d, 0x3c, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0 } }
 
59
 
 
60
 
 
61
/**
 
62
 * The nsITextServicesDocument presents the document in as a
 
63
 * bunch of flattened text blocks. Each text block can be retrieved
 
64
 * as an nsString (array of characters).
 
65
 */
 
66
class nsITextServicesDocument  : public nsISupports{
 
67
public:
 
68
 
 
69
  NS_DEFINE_STATIC_IID_ACCESSOR(NS_ITEXTSERVICESDOCUMENT_IID)
 
70
 
 
71
  typedef enum { eDSNormal=0, eDSUndlerline } TSDDisplayStyle;
 
72
 
 
73
  typedef enum { eBlockNotFound=0, // There is no text block (TB) in or before the selection (S).
 
74
                 eBlockOutside,    // No TB in S, but found one before/after S.
 
75
                 eBlockInside,     // S extends beyond the start and end of TB.
 
76
                 eBlockContains,   // TB contains entire S.
 
77
                 eBlockPartial     // S begins or ends in TB but extends outside of TB.
 
78
  } TSDBlockSelectionStatus;
 
79
 
 
80
  /**
 
81
   * Initializes the text services document to use a particular
 
82
   * DOM document.
 
83
   * @param aDOMDocument is the document to use. It is AddRef'd
 
84
   * by this method.
 
85
   * @param aPresShell is the presentation shell to use when
 
86
   * setting the selection. It is AddRef'd by this method.
 
87
   */
 
88
  NS_IMETHOD InitWithDocument(nsIDOMDocument *aDOMDocument, nsIPresShell *aPresShell) = 0;
 
89
 
 
90
  /**
 
91
   * Get the DOM document for the document in use.
 
92
   * @return aDocument the dom document [OUT]
 
93
   */
 
94
  NS_IMETHOD GetDocument(nsIDOMDocument **aDocument) = 0;
 
95
 
 
96
  /**
 
97
   * Initializes the text services document to use a particular
 
98
   * editor. The text services document will use the DOM document
 
99
   * and presentation shell used by the editor.
 
100
   * @param aEditor is the editor to use. The editor is AddRef'd
 
101
   * by this method.
 
102
   */
 
103
  NS_IMETHOD InitWithEditor(nsIEditor *aEditor) = 0;
 
104
 
 
105
  /**
 
106
   * Sets the range/extent over which the text services document
 
107
   * will iterate. Note that InitWithDocument() or InitWithEditor()
 
108
   * should have been called prior to calling this method. If this
 
109
   * method is never called, the text services defaults to iterating
 
110
   * over the entire document.
 
111
   *
 
112
   * @param aDOMRange is the range to use. aDOMRange must point to a
 
113
   * valid range object.
 
114
   */
 
115
  NS_IMETHOD SetExtent(nsIDOMRange* aDOMRange) = 0;
 
116
 
 
117
  /**
 
118
   * Gets the range that the text services document
 
119
   * is currently iterating over. If SetExtent() was never
 
120
   * called, this method will return a range that spans the
 
121
   * entire body of the document.
 
122
   *
 
123
   * @param aDOMRange will contain an AddRef'd pointer to the range.
 
124
   */
 
125
  NS_IMETHOD GetExtent(nsIDOMRange** aDOMRange) = 0;
 
126
 
 
127
  /**
 
128
   * Expands the end points of the range so that it spans complete words.
 
129
   * This call does not change any internal state of the text services document.
 
130
   *
 
131
   * @param aDOMRange the range to be expanded/adjusted.
 
132
   */
 
133
  NS_IMETHOD ExpandRangeToWordBoundaries(nsIDOMRange *aRange) = 0;
 
134
 
 
135
  /**
 
136
   * Sets the filter to be used while iterating over content.
 
137
   * @param aFilter filter to be used while iterating over content.
 
138
   */
 
139
  NS_IMETHOD SetFilter(nsITextServicesFilter *aFilter) = 0;
 
140
 
 
141
  /**
 
142
   * Returns true if the document can be modified with calls
 
143
   * to DeleteSelection() and InsertText().
 
144
   * @param aCanEdit is true if the document can be modified,
 
145
   * false if it can't.
 
146
   */
 
147
  NS_IMETHOD CanEdit(PRBool *aCanEdit) = 0;
 
148
 
 
149
  /**
 
150
   * Returns the text in the current text block.
 
151
   * @param aStr will contain the text.
 
152
   */
 
153
 
 
154
  NS_IMETHOD GetCurrentTextBlock(nsString *aStr) = 0;
 
155
 
 
156
  /**
 
157
   * Tells the document to point to the first text block
 
158
   * in the document. This method does not adjust the current
 
159
   * cursor position or selection.
 
160
   */
 
161
 
 
162
  NS_IMETHOD FirstBlock() = 0;
 
163
 
 
164
  /**
 
165
   * Tells the document to point to the last text block in the
 
166
   * document. This method does not adjust the current cursor
 
167
   * position or selection.
 
168
   */
 
169
 
 
170
  NS_IMETHOD LastBlock() = 0;
 
171
 
 
172
  /**
 
173
   * Tells the document to point to the first text block that
 
174
   * contains the current selection or caret.
 
175
   * @param aSelectionStatus will contain the text block selection status
 
176
   * @param aSelectionOffset will contain the offset into the
 
177
   * string returned by GetCurrentTextBlock() where the selection
 
178
   * begins.
 
179
   * @param aLength will contain the number of characters that are
 
180
   * selected in the string.
 
181
   */
 
182
 
 
183
  NS_IMETHOD FirstSelectedBlock(TSDBlockSelectionStatus *aSelectionStatus, PRInt32 *aSelectionOffset, PRInt32 *aSelectionLength) = 0;
 
184
 
 
185
  /**
 
186
   * Tells the document to point to the last text block that
 
187
   * contains the current selection or caret.
 
188
   * @param aSelectionStatus will contain the text block selection status
 
189
   * @param aSelectionOffset will contain the offset into the
 
190
   * string returned by GetCurrentTextBlock() where the selection
 
191
   * begins.
 
192
   * @param aLength will contain the number of characters that are
 
193
   * selected in the string.
 
194
   */
 
195
 
 
196
  NS_IMETHOD LastSelectedBlock(TSDBlockSelectionStatus *aSelectionStatus, PRInt32 *aSelectionOffset, PRInt32 *aSelectionLength) = 0;
 
197
 
 
198
  /**
 
199
   * Tells the document to point to the text block before
 
200
   * the current one. This method will return NS_OK, even
 
201
   * if there is no previous block. Callers should call IsDone()
 
202
   * to check if we have gone beyond the first text block in
 
203
   * the document.
 
204
   */
 
205
 
 
206
  NS_IMETHOD PrevBlock() = 0;
 
207
 
 
208
  /**
 
209
   * Tells the document to point to the text block after
 
210
   * the current one. This method will return NS_OK, even
 
211
   * if there is no next block. Callers should call IsDone()
 
212
   * to check if we have gone beyond the last text block
 
213
   * in the document.
 
214
   */
 
215
 
 
216
  NS_IMETHOD NextBlock() = 0;
 
217
 
 
218
  /**
 
219
   * IsDone() will always set aIsDone == PR_FALSE unless
 
220
   * the document contains no text, PrevBlock() was called
 
221
   * while the document was already pointing to the first
 
222
   * text block in the document, or NextBlock() was called
 
223
   * while the document was already pointing to the last
 
224
   * text block in the document.
 
225
   * @param aIsDone will contain the result.
 
226
   */
 
227
 
 
228
  NS_IMETHOD IsDone(PRBool *aIsDone) = 0;
 
229
 
 
230
  /**
 
231
   * SetSelection() allows the caller to set the selection
 
232
   * based on an offset into the string returned by
 
233
   * GetCurrentTextBlock(). A length of zero places the cursor
 
234
   * at that offset. A positive non-zero length "n" selects
 
235
   * n characters in the string.
 
236
   * @param aOffset offset into string returned by GetCurrentTextBlock().
 
237
   * @param aLength number characters selected.
 
238
   */
 
239
 
 
240
  NS_IMETHOD SetSelection(PRInt32 aOffset, PRInt32 aLength) = 0;
 
241
 
 
242
  /**
 
243
   * Scrolls the document so that the current selection is visible.
 
244
   */
 
245
 
 
246
  NS_IMETHOD ScrollSelectionIntoView() = 0;
 
247
 
 
248
  /**
 
249
   * Deletes the text selected by SetSelection(). Calling
 
250
   * DeleteSelection with nothing selected, or with a collapsed
 
251
   * selection (cursor) does nothing and returns NS_OK.
 
252
   */
 
253
 
 
254
  NS_IMETHOD DeleteSelection() = 0;
 
255
 
 
256
  /**
 
257
   * Inserts the given text at the current cursor position.
 
258
   * If there is a selection, it will be deleted before the
 
259
   * text is inserted.
 
260
   */
 
261
 
 
262
  NS_IMETHOD InsertText(const nsString *aText) = 0;
 
263
 
 
264
  /**
 
265
   * Sets the display style for the text selected by SetSelection().
 
266
   * @param aStyle is the style to apply to the selected text.
 
267
   */
 
268
 
 
269
  NS_IMETHOD SetDisplayStyle(TSDDisplayStyle aStyle) = 0;
 
270
 
 
271
  /**
 
272
   * Returns the DOM range for a given offset and length
 
273
   * @param aOffset offset into string returned by GetCurrentTextBlock().
 
274
   * @param aLength number characters selected.
 
275
   * @param aDOMRange the DOM range that represents the offset and length
 
276
   */
 
277
  NS_IMETHOD GetDOMRangeFor(PRInt32 aOffset, PRInt32 aLength, nsIDOMRange** aRange) = 0;
 
278
};
 
279
 
 
280
#endif // nsITextServicesDocument_h__
 
281