summaryrefslogtreecommitdiff
path: root/dom/base/nsISelection.idl
blob: de43521e1d5055592c2c3539f56259fa4ce8dd5f (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

#include "nsISupports.idl"

/* THIS IS A PUBLIC INTERFACE */

interface nsIDOMNode;
interface nsIDOMRange;
interface nsINode;

%{C++
namespace mozilla {
namespace dom {
class Selection;
} // namespace dom
} // namespace mozilla
%}

/**
 * Interface for manipulating and querying the current selected range
 * of nodes within the document.
 *
 * @version 1.0
 */

[builtinclass, uuid(e0a4d4b3-f34e-44bd-b1f2-4e3bde9b6915)]
interface nsISelection : nsISupports
{
    /**
     * Returns the node in which the selection begins.
     */
    readonly attribute nsIDOMNode anchorNode;

    /**
     * The offset within the (text) node where the selection begins.
     */
    readonly attribute long anchorOffset;

    /**
     * Returns the node in which the selection ends.
     */
    readonly attribute nsIDOMNode focusNode;

    /**
     * The offset within the (text) node where the selection ends.
     */
    readonly attribute long focusOffset;

    /**
     * Indicates if the selection is collapsed or not.
     */
    readonly attribute boolean isCollapsed;
    [noscript,notxpcom,nostdcall] boolean collapsed();

    /**
     * Returns the number of ranges in the selection.
     */
    readonly attribute long rangeCount;

    /**
     * Returns the range at the specified index.
     */
    nsIDOMRange getRangeAt(in long index);

    /**
     * Collapses the selection to a single point, at the specified offset
     * in the given DOM node. When the selection is collapsed, and the content
     * is focused and editable, the caret will blink there.
     * @param parentNode      The given dom node where the selection will be set
     * @param offset          Where in given dom node to place the selection (the offset into the given node)
     */
    void collapse(in nsIDOMNode parentNode, in long offset);
    [noscript] void collapseNative(in nsINode parentNode, in long offset);

    /**
     * Extends the selection by moving the selection end to the specified node and offset,
     * preserving the selection begin position. The new selection end result will always
     * be from the anchorNode to the new focusNode, regardless of direction.
     * @param parentNode      The node where the selection will be extended to
     * @param offset          Where in node to place the offset in the new selection end
     */
    void extend(in nsIDOMNode parentNode, in long offset);
    [noscript] void extendNative(in nsINode parentNode, in long offset);

    /**
     * Collapses the whole selection to a single point at the start
     * of the current selection (irrespective of direction).  If content
     * is focused and editable, the caret will blink there.
     */
    void collapseToStart();

    /**
     * Collapses the whole selection to a single point at the end
     * of the current selection (irrespective of direction).  If content
     * is focused and editable, the caret will blink there.
     */
    void collapseToEnd();

    /**
     * Indicates whether the node is part of the selection. If partlyContained 
     * is set to PR_TRUE, the function returns true when some part of the node 
     * is part of the selection. If partlyContained is set to PR_FALSE, the
     * function only returns true when the entire node is part of the selection.
     */
    boolean containsNode(in nsIDOMNode node, in boolean partlyContained);

    /**
     * Adds all children of the specified node to the selection.
     * @param parentNode  the parent of the children to be added to the selection.
     */
    void selectAllChildren(in nsIDOMNode parentNode); 

    /**
     * Adds a range to the current selection.
     */
    void addRange(in nsIDOMRange range);
 
    /**
     * Removes a range from the current selection.
     */
    void removeRange(in nsIDOMRange range);

    /**
     * Removes all ranges from the current selection.
     */
    void removeAllRanges();

    /**
     * Deletes this selection from document the nodes belong to.
     */
    void deleteFromDocument();

    /**
     * Returns the whole selection into a plain text string.
     */
    DOMString toString();

    /**
     * Modifies the selection.  Note that the parameters are case-insensitive.
     *
     * @param alter can be one of { "move", "extend" }
     *   - "move" collapses the selection to the end of the selection and
     *      applies the movement direction/granularity to the collapsed
     *      selection.
     *   - "extend" leaves the start of the selection unchanged, and applies
     *      movement direction/granularity to the end of the selection.
     * @param direction can be one of { "forward", "backward", "left", "right" }
     * @param granularity can be one of { "character", "word",
     *                                    "line", "lineboundary" }
     *
     * @returns NS_ERROR_NOT_IMPLEMENTED if the granularity is "sentence",
     * "sentenceboundary", "paragraph", "paragraphboundary", or
     * "documentboundary".  Returns NS_ERROR_INVALID_ARG if alter, direction,
     * or granularity has an unrecognized value.
     */
    void modify(in DOMString alter, in DOMString direction,
                in DOMString granularity);

%{C++
    /**
     * AsSelection() returns a pointer to Selection class if the instance is
     * derived from it.  Otherwise, nullptr but it should never happen
     * since Selection is the only class implementing nsISelection.
     */
    virtual mozilla::dom::Selection* AsSelection() = 0;
%}
};