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 BASICMANAGERREPOSITORY_HXX
  21 #define BASICMANAGERREPOSITORY_HXX
  22
  23 #include <com/sun/star/frame/XModel.hpp>
  24 #include <com/sun/star/embed/XStorage.hpp>
  25 #include "basicdllapi.h"
  26
  27 class BasicManager;
  28
  29 //........................................................................
  30 namespace basic
  31 {
  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 ::com::sun::star::uno::Reference< ::com::sun::star::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 ::com::sun::star::uno::Reference< ::com::sun::star::frame::XModel >& _rxDocumentModel
  96         );
  97
  98         /** returns the application-wide BasicManager
  99
 100         @param _bCreate
 101             determines whether the BasicManager should be created (<TRUE/>) if it
 102             does not yet exist.
 103
 104         @attention
 105             If the BasicManager is newly created, then it is still owned by the repository.
 106             In particular, you are not allowed to delete it. Instead, call resetApplicationBasicManager
 107             to release the BasicManager.
 108         */
 109         static BasicManager* getApplicationBasicManager( bool _bCreate );
 110
 111         /** resets the application-wide BasicManager to <NULL/>
 112         */
 113         static void resetApplicationBasicManager();
 114
 115         /** registers a BasicManagerCreationListener instance which is notified whenever
 116             the repository creates a BasicManager instance.
 117
 118             Note that this listener is <em>not</em> called when somebody else
 119             creates BasicManager instances.
 120
 121             If the same listener is registered multiple times, it is also notified
 122             multiple times, and needs to be revoked once for each registration.
 123         */
 124         static  void    registerCreationListener(
 125                 BasicManagerCreationListener& _rListener
 126             );
 127
 128         /** reveokes a BasicManagerCreationListener instance which has previously
 129             been registered to be notified about created BasicManager instances.
 130         */
 131         static  void    revokeCreationListener(
 132                 BasicManagerCreationListener& _rListener
 133             );
 134     };
 135
 136 //........................................................................
 137 } // namespace basic
 138 //........................................................................
 139
 140 #endif // BASICMANAGERREPOSITORY_HXX
 141
 142 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */