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_frame_XUntitledNumbers_idl__
28#define __com_sun_star_frame_XUntitledNumbers_idl__
29
30#ifndef __com_sun_star_uno_XInterface_idl__
31#include <com/sun/star/uno/XInterface.idl>
32#endif
33
34#ifndef __com_sun_star_lang_IllegalArgumentException_idl__
35#include <com/sun/star/lang/IllegalArgumentException.idl>
36#endif
37
38//=============================================================================
39
40 module com {  module sun {  module star {  module frame {
41
42constants UntitledNumbersConst
43{
44    const long INVALID_NUMBER = 0;
45};
46
47//=============================================================================
48/** knows all currently used and all free numbers for using with untitled
49    but counted objects.
50 */
51interface XUntitledNumbers : com::sun::star::uno::XInterface
52{
53    //-------------------------------------------------------------------------
54    /** calli has to lease a number befor he can use it within in its own title.
55
56        Such number must be freed after using e.g. while the object was closed or
57        get's another title (e.g. by saving a document to a real location on disc).
58
59        @param  xComponent
60                the component which has to be registered for the leased number.
61
62        @return the new number for these object or 0 if no further numbers are available.
63
64        @throws [IllegalArgumentException]
65                if an invalid object reference was provided to this method.
66     */
67    long leaseNumber ( [in] com::sun::star::uno::XInterface xComponent )
68        raises (com::sun::star::lang::IllegalArgumentException);
69
70    //-------------------------------------------------------------------------
71    /** has to be used to mark those number as "free for using".
72
73        If the reqistered component does not use such leased number any longer
74        it has to be released so it can be used for new components.
75
76        Note: calling this method with an unknown (but normaly valid number)
77              has to be ignored. No exceptions - no errors.
78
79        @param  nNumber
80                specify number for release.
81
82        @throws [IllegalArgumentException]
83                if the given number is the special value 0.
84     */
85    void releaseNumber ( [in] long nNumber )
86        raises (com::sun::star::lang::IllegalArgumentException);
87
88    //-------------------------------------------------------------------------
89    /** does the same then releaseNumber () but it searches the corresponding
90        number for the specified component and deregister it.
91
92        @param  xComponent
93                the component for deregistration.
94
95        @throws [IllegalArgumentException]
96                if an invalid object reference was provided to this method.
97     */
98    void releaseNumberForComponent ( [in] com::sun::star::uno::XInterface xComponent )
99        raises (com::sun::star::lang::IllegalArgumentException);
100
101    //-------------------------------------------------------------------------
102    /** returns the localized string value to be used for untitles objects in
103        combination with the leased number.
104
105        Note: Such string already contains leading spaces/tabs etcpp. !
106        The only thing which an outside code has todo then ... adding a leased number
107        to the string.
108
109        @return the localized string for untitled components.
110     */
111    string getUntitledPrefix ();
112};
113
114//=============================================================================
115
116}; }; }; };
117
118#endif
119