offapi/com/sun/star/frame/XUntitledNumbers.idl

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19
  20
  21  module com {  module sun {  module star {  module frame {
  22
  23 /** knows all currently used and all free numbers for using with untitled
  24     but counted objects.
  25  */
  26 interface XUntitledNumbers : com::sun::star::uno::XInterface
  27 {
  28     /** callee has to lease a number before he can use it within in its own title.
  29
  30         Such number must be freed after using e.g. while the object was closed or
  31         gets another title (e.g. by saving a document to a real location on disc).
  32
  33         @param  xComponent
  34                 the component which has to be registered for the leased number.
  35
  36         @return the new number for these object or 0 if no further numbers are available.
  37
  38         @throws [IllegalArgumentException]
  39                 if an invalid object reference was provided to this method.
  40      */
  41     long leaseNumber ( [in] com::sun::star::uno::XInterface xComponent )
  42         raises (com::sun::star::lang::IllegalArgumentException);
  43
  44     /** has to be used to mark those numbers as "free for using".
  45
  46         If the registered component does not use such leased number any longer
  47         it has to be released so it can be used for new components.
  48
  49         Note: calling this method with an unknown (but normally valid number)
  50               has to be ignored. No exceptions - no errors.
  51
  52         @param  nNumber
  53                 specify number for release.
  54
  55         @throws [IllegalArgumentException]
  56                 if the given number is the special value 0.
  57      */
  58     void releaseNumber ( [in] long nNumber )
  59         raises (com::sun::star::lang::IllegalArgumentException);
  60
  61     /** does the same then releaseNumber () but it searches the corresponding
  62         number for the specified component and deregister it.
  63
  64         @param  xComponent
  65                 the component for deregistration.
  66
  67         @throws [IllegalArgumentException]
  68                 if an invalid object reference was provided to this method.
  69      */
  70     void releaseNumberForComponent ( [in] com::sun::star::uno::XInterface xComponent )
  71         raises (com::sun::star::lang::IllegalArgumentException);
  72
  73     /** returns the localized string value to be used for untitled objects in
  74         combination with the leased number.
  75
  76         Note: Such string already contains leading spaces/tabs etc. !
  77         The only thing which an outside code has todo then ... adding a leased number
  78         to the string.
  79
  80         @return the localized string for untitled components.
  81      */
  82     string getUntitledPrefix ();
  83 };
  84
  85
  86 }; }; }; };
  87
  88 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */