1/*************************************************************************
2 *
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * Copyright 2000, 2010 Oracle and/or its affiliates.
6 *
7 * OpenOffice.org - a multi-platform office productivity suite
8 *
9 * This file is part of OpenOffice.org.
10 *
11 * OpenOffice.org is free software: you can redistribute it and/or modify
12 * it under the terms of the GNU Lesser General Public License version 3
13 * only, as published by the Free Software Foundation.
14 *
15 * OpenOffice.org is distributed in the hope that it will be useful,
16 * but WITHOUT ANY WARRANTY; without even the implied warranty of
17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
18 * GNU Lesser General Public License version 3 for more details
19 * (a copy is included in the LICENSE file that accompanied this code).
20 *
21 * You should have received a copy of the GNU Lesser General Public License
22 * version 3 along with OpenOffice.org.  If not, see
23 * <http://www.openoffice.org/license.html>
24 * for a copy of the LGPLv3 License.
25 *
26 ************************************************************************/
27#ifndef __com_sun_star_view_XMultiSelectionSupplier_idl__
28#define __com_sun_star_view_XMultiSelectionSupplier_idl__
29
30#ifndef __com_sun_star_view_XSelectionSupplier_idl__
31#include <com/sun/star/view/XSelectionSupplier.idl>
32#endif
33#ifndef __com_sun_star_container_XEnumeration_idl__
34#include <com/sun/star/container/XEnumeration.idl>
35#endif
36
37//=============================================================================
38
39module com {  module sun {  module star {  module view {
40
41//=============================================================================
42
43/** makes it possible to append and remove objects from a selection.
44
45    <p>The method <method>XSelectionSupplier::setSelection</method> for an
46    instance that also supports <type>XMultiSelectionSupplier</method> should
47    be implemented that it also takes either a selectable object or a sequence
48    of selectable objects.</p>
49
50    <p>Adding an object more than once to a selection should not toggle the
51    selection for that object but only select it once</p>
52 */
53published interface XMultiSelectionSupplier: XSelectionSupplier
54{
55    //-------------------------------------------------------------------------
56
57    /** adds the object or the objects represented by <var>Selection</var> to the selection
58        of this <type>XMultiSelectionSupplier</type>.
59
60        @param Selection
61            either an Object that is selectable or a sequence of objects that are selectable.
62
63        @returns
64            <TRUE/>/, if <var>Selection</var> was added to the current selection.
65            <FALSE/>, if <var>Selection</var> or parts of <var>Selection</var> could not be
66            added to the current selection. For example, if the selection already contains
67            objects that are forbidden to be selected together with <var>Selection</var>
68
69        @throws com::sun::star::lang::IllegalArgumentException
70            If <var>Selection</var> is not a selectable object for this <type>XMultiSelectionSupplier</type>.
71            <p>Adding an object to the selection that is already part of the selection should not raise this exception</p>
72     */
73    boolean addSelection( [in] any Selection )
74                raises( com::sun::star::lang::IllegalArgumentException );
75
76    //-------------------------------------------------------------------------
77
78    /** remove the object or objects represented by <var>Selection</var> from the
79        selection of this <type>XMultiSelectionSupplier</type>.
80
81        @param Selection
82            either an Object that is selectable or a sequence of objects that are selectable.
83
84        @returns
85            <TRUE/>/, if <var>Selection</var> was added to the current selection.
86            <FALSE/>, if <var>Selection</var> or parts of <var>Selection</var> could not be
87            added to the current selection. For example, if the selection already contains
88            objects that are forbidden to be selected together with <var>Selection</var>.
89
90        @throws com::sun::star::lang::IllegalArgumentException
91            If <var>Selection</var> is not a selectable object for this <type>XMultiSelectionSupplier</type>.
92            <p>Removing an object from the selection that is not part of the selection should not raise this exception</p>
93     */
94    void removeSelection( [in] any Selection )
95                raises( com::sun::star::lang::IllegalArgumentException );
96
97    //-------------------------------------------------------------------------
98
99    /** clears the selection of this <type>XMultiSelectionSupplier</type>.
100    */
101    void clearSelection();
102
103    //-------------------------------------------------------------------------
104
105    /** returns the number of selected objects of this <type>XMultiSelectionSupplier</type>.
106    */
107    long getSelectionCount();
108
109    //-------------------------------------------------------------------------
110
111    /** @returns
112            a new object to enumerate the selection of this <type>XMultiSelectionSupplier</type>.
113            It returns NULL if there are no objects in the selection.
114     */
115    com::sun::star::container::XEnumeration createSelectionEnumeration();
116
117
118    /** @returns
119            a new object to enumerate the selection of this <type>XMultiSelectionSupplier</type>
120            in reverse order. If the order of the selected objects
121            It returns NULL if there are no objects in the selection.
122     */
123    com::sun::star::container::XEnumeration createReverseSelectionEnumeration();
124
125};
126
127//=============================================================================
128
129}; }; }; };
130
131#endif
132