/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
/*
 * This file is part of the LibreOffice project.
 *
 * 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/.
 *
 * This file incorporates work covered by the following license notice:
 *
 *   Licensed to the Apache Software Foundation (ASF) under one or more
 *   contributor license agreements. See the NOTICE file distributed
 *   with this work for additional information regarding copyright
 *   ownership. The ASF licenses this file to you under the Apache
 *   License, Version 2.0 (the "License"); you may not use this file
 *   except in compliance with the License. You may obtain a copy of
 *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
 */


 module com {  module sun {  module star {  module frame {

/** knows all currently used and all free numbers for using with untitled
    but counted objects.
 */
interface XUntitledNumbers : com::sun::star::uno::XInterface
{
    /** callee has to lease a number before he can use it within in its own title.

        Such number must be freed after using e.g. while the object was closed or
        gets another title (e.g. by saving a document to a real location on disc).

        @param  xComponent
                the component which has to be registered for the leased number.

        @return the new number for these object or 0 if no further numbers are available.

        @throws [IllegalArgumentException]
                if an invalid object reference was provided to this method.
     */
    long leaseNumber ( [in] com::sun::star::uno::XInterface xComponent )
        raises (com::sun::star::lang::IllegalArgumentException);

    /** has to be used to mark those numbers as "free for using".

        If the registered component does not use such leased number any longer
        it has to be released so it can be used for new components.

        Note: calling this method with an unknown (but normally valid number)
              has to be ignored. No exceptions - no errors.

        @param  nNumber
                specify number for release.

        @throws [IllegalArgumentException]
                if the given number is the special value 0.
     */
    void releaseNumber ( [in] long nNumber )
        raises (com::sun::star::lang::IllegalArgumentException);

    /** does the same then releaseNumber () but it searches the corresponding
        number for the specified component and deregister it.

        @param  xComponent
                the component for deregistration.

        @throws [IllegalArgumentException]
                if an invalid object reference was provided to this method.
     */
    void releaseNumberForComponent ( [in] com::sun::star::uno::XInterface xComponent )
        raises (com::sun::star::lang::IllegalArgumentException);

    /** returns the localized string value to be used for untitled objects in
        combination with the leased number.

        Note: Such string already contains leading spaces/tabs etc. !
        The only thing which an outside code has todo then ... adding a leased number
        to the string.

        @return the localized string for untitled components.
     */
    string getUntitledPrefix ();
};


}; }; }; };

/* vim:set shiftwidth=4 softtabstop=4 expandtab: */
