include/basic/basicmanagerrepository.hxx

   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 #ifndef INCLUDED_BASIC_BASICMANAGERREPOSITORY_HXX
  21 #define INCLUDED_BASIC_BASICMANAGERREPOSITORY_HXX
  22
  23 #include <basic/basicdllapi.h>
  24
  25 namespace com::sun::star::frame { class XModel; }
  26 namespace com::sun::star::uno { template <typename > class Reference; }
  27
  28 class BasicManager;
  29
  30
  31 namespace basic
  32 {
  33
  34
  35     //= BasicManagerRepository
  36
  37     /** specifies a callback for instances which are interested in BasicManagers
  38         created by the BasicManagerRepository.
  39     */
  40     class BASIC_DLLPUBLIC SAL_NO_VTABLE BasicManagerCreationListener
  41     {
  42     public:
  43         /** is called when a BasicManager has been created
  44
  45             @param  _rxForDocument
  46                 denotes the document for which the BasicManager has been created. If this is <NULL/>,
  47                 then the BasicManager is the application-wide BasicManager.
  48
  49             @param  _pBasicManager
  50                 denotes the BasicManager which has been created. The listener might for instance
  51                 decide to add global variables to it, or otherwise initialize it.
  52         */
  53         virtual void onBasicManagerCreated(
  54             const css::uno::Reference< css::frame::XModel >& _rxForDocument,
  55             BasicManager& _rBasicManager
  56         ) = 0;
  57
  58     protected:
  59         ~BasicManagerCreationListener() {}
  60     };
  61
  62
  63     //= BasicManagerRepository
  64
  65     class BASIC_DLLPUBLIC BasicManagerRepository
  66     {
  67     public:
  68         /** returns the BasicManager belonging to the given document
  69
  70             If the BasicManager does not yet exist, it is created. In this case, if the application's
  71             BasicManager does not yet exist, it is also created. This is necessary since
  72             the application's BasicManager acts as parent for all document's BasicManagers.
  73
  74             If you're interested in this case - the implicit creation of the application's BasicManager -,
  75             then you need to register as BasicManagerCreationListener.
  76
  77             @param _rxDocumentModel
  78                 denotes the document model whose BasicManager is to be retrieved. Must not be <NULL/>.
  79                 The document should support the XDocumentPropertiesSupplier
  80                 interface, for retrieving
  81                 its title, which is needed in some error conditions.
  82                 Also it <em>must</em> support the XStorageBasedDocument interface, since we
  83                 must be able to retrieve the document's storage. If this interface is <em>not</em>
  84                 supported, creating a new BasicManager will certainly fail.
  85
  86             @return
  87                 the BasicManager for this model.
  88
  89             @attention
  90                 The returned BasicManager instances is owned by the repository. In particular,
  91                 you are not allowed to delete it. Instead, the given model is observed: As soon
  92                 as it's closed, the associated BasicManager is deleted.
  93         */
  94         static BasicManager* getDocumentBasicManager(
  95             const css::uno::Reference< css::frame::XModel >& _rxDocumentModel
  96         );
  97
  98         /** returns the application-wide BasicManager
  99
 100         @attention
 101             If the BasicManager is newly created, then it is still owned by the repository.
 102             In particular, you are not allowed to delete it. Instead, call resetApplicationBasicManager
 103             to release the BasicManager.
 104         */
 105         static BasicManager* getApplicationBasicManager();
 106
 107         /** resets the application-wide BasicManager to <NULL/>
 108         */
 109         static void resetApplicationBasicManager();
 110
 111         /** registers a BasicManagerCreationListener instance which is notified whenever
 112             the repository creates a BasicManager instance.
 113
 114             Note that this listener is <em>not</em> called when somebody else
 115             creates BasicManager instances.
 116
 117             If the same listener is registered multiple times, it is also notified
 118             multiple times, and needs to be revoked once for each registration.
 119         */
 120         static  void    registerCreationListener(
 121                 BasicManagerCreationListener& _rListener
 122             );
 123
 124         /** revokes a BasicManagerCreationListener instance which has previously
 125             been registered to be notified about created BasicManager instances.
 126         */
 127         static  void    revokeCreationListener(
 128                 BasicManagerCreationListener& _rListener
 129             );
 130     };
 131
 132
 133 } // namespace basic
 134
 135
 136 #endif // INCLUDED_BASIC_BASICMANAGERREPOSITORY_HXX
 137
 138 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */