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