basctl/source/inc/scriptdocument.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 #pragma once
  21
  22 #include <com/sun/star/script/XLibraryContainer.hpp>
  23 #include <com/sun/star/frame/XModel.hpp>
  24 #include <com/sun/star/task/XStatusIndicator.hpp>
  25 #include <com/sun/star/io/XInputStreamProvider.hpp>
  26
  27 #include <memory>
  28 #include <vector>
  29
  30 class SfxListener;
  31
  32 class BasicManager;
  33
  34
  35 namespace basctl
  36 {
  37
  38     enum LibraryContainerType
  39     {
  40         E_SCRIPTS,
  41         E_DIALOGS
  42     };
  43
  44     enum LibraryLocation
  45     {
  46         LIBRARY_LOCATION_UNKNOWN,
  47         LIBRARY_LOCATION_USER,
  48         LIBRARY_LOCATION_SHARE,
  49         LIBRARY_LOCATION_DOCUMENT
  50     };
  51
  52     enum class LibraryType
  53     {
  54         Module,
  55         Dialog,
  56         All
  57     };
  58
  59     class ScriptDocument;
  60     typedef std::vector< ScriptDocument >  ScriptDocuments;
  61
  62     /** encapsulates a document which contains Basic scripts and dialogs
  63     */
  64     class ScriptDocument
  65     {
  66     private:
  67         class Impl;
  68         std::shared_ptr<Impl> m_pImpl;
  69
  70     private:
  71         /** creates a ScriptDocument instance which operates on the application-wide
  72             scripts and dialogs
  73         */
  74                     ScriptDocument();
  75
  76     public:
  77         enum SpecialDocument { NoDocument };
  78         /** creates a ScriptDocument instance which does refers to neither the application-wide,
  79             nor a specific real document's scripts.
  80
  81             This constructor might come handy when you need some kind of uninitialized
  82             ScriptDocument, which you do not want to operate on (yet), but initialize later
  83             by assignment.
  84
  85             <member>isValid</member> will return <FALSE/> for a ScriptDocument constructed
  86             this way.
  87         */
  88         explicit    ScriptDocument( SpecialDocument _eType );
  89
  90         /** creates a ScriptDocument instance which refers to a document given as
  91             XModel
  92
  93             @param _rxDocument
  94                 the document. Must not be <NULL/>.
  95         */
  96         explicit    ScriptDocument( const css::uno::Reference< css::frame::XModel >& _rxDocument );
  97
  98         /** returns a reference to a shared ScriptDocument instance which
  99             operates on the application-wide scripts and dialogs
 100         */
 101         static const ScriptDocument&
 102                     getApplicationScriptDocument();
 103
 104         /** returns a (newly created) ScriptDocument instance for the document to
 105             which a given BasicManager belongs
 106
 107             If the basic manager is the application's basic manager, then the (shared)
 108             ScriptDocument instance which is responsible for the application is returned.
 109
 110             @see getApplicationScriptDocument
 111         */
 112         static ScriptDocument
 113                     getDocumentForBasicManager( const BasicManager* _pManager );
 114
 115         /** returns a (newly created) ScriptDocument instance for the document
 116             with a given caption or URL
 117
 118             If there is no document with the given caption, then the (shared)
 119             ScriptDocument instance which is responsible for the application is returned.
 120
 121             @see getApplicationScriptDocument
 122         */
 123         static ScriptDocument
 124                     getDocumentWithURLOrCaption( std::u16string_view _rUrlOrCaption );
 125
 126         /** operation mode for getAllScriptDocuments
 127         */
 128         enum ScriptDocumentList
 129         {
 130             /** all ScriptDocuments, including the dedicated one which represents
 131                 the application-wide scripts/dialogs.
 132             */
 133             AllWithApplication,
 134             /** real documents only, sorted lexicographically by their title (using the sys locale's default
 135                 collator)
 136             */
 137             DocumentsSorted
 138         };
 139
 140         /** returns the set of ScriptDocument instances, one for each open document which
 141             contains Basic/Dialog containers; plus an additional instance for
 142             the application, if desired
 143
 144             Documents which are not visible - i.e. do not have a visible frame.
 145
 146             @param _bIncludingApplication
 147                 <TRUE/> if the application-wide scripts/dialogs should also be represented
 148                 by a ScriptDocument
 149         */
 150         static ScriptDocuments
 151                     getAllScriptDocuments( ScriptDocumentList _eListType );
 152
 153         // comparison
 154                 bool operator==( const ScriptDocument& _rhs ) const;
 155         bool operator!=( const ScriptDocument& _rhs ) const { return !( *this == _rhs ); }
 156
 157         /// retrieves a (pretty simple) hash code for the document
 158         sal_Int32   hashCode() const;
 159
 160         /** determines whether the document is actually able to contain Basic/Dialog libraries
 161
 162             Note that validity does not automatically imply the document can be used for active
 163             work. Instead, it is possible the document is closed already (or being closed currently).
 164             In this case, isValid will return <TRUE/>, but isAlive will return <FALSE/>.
 165
 166             @return
 167                 <TRUE/> if the instance refers to a document which contains Basic/Dialog libraries,
 168                 or the application as a whole, <FALSE/> otherwise.
 169
 170             @see isAlive
 171         */
 172         bool        isValid() const;
 173
 174         /** determines whether the document instance is alive
 175
 176             If the instance is not valid, <FALSE/> is returned.
 177
 178             If the instance refers to a real document, which is already closed, or just being closed,
 179             the method returns <FALSE/>.
 180
 181             If the instance refers to the application, <TRUE/> is returned.
 182
 183             @see isValid
 184         */
 185         bool        isAlive() const;
 186
 187         bool        isInVBAMode() const;
 188         /// returns the BasicManager associated with this instance
 189         BasicManager*
 190                     getBasicManager() const;
 191
 192         /** returns the UNO component representing the document which the instance operates on
 193
 194             Must not be used when the instance operates on the application-wide
 195             Basic/Dialog libraries.
 196         */
 197         css::uno::Reference< css::frame::XModel >
 198                     getDocument() const;
 199
 200         /** returns the UNO component representing the document which the instance operates on
 201
 202             May be used when the instance operates on the application-wide
 203             Basic/Dialog libraries, in this case it returns <NULL/>.
 204         */
 205         css::uno::Reference< css::frame::XModel >
 206                     getDocumentOrNull() const;
 207
 208         /** returns the Basic or Dialog library container of the document
 209
 210             If the document is not valid, <NULL/> is returned.
 211         */
 212         css::uno::Reference< css::script::XLibraryContainer >
 213                     getLibraryContainer( LibraryContainerType _eType ) const;
 214
 215         /** determines whether there exists a library of the given type, with the given name
 216         */
 217         bool        hasLibrary( LibraryContainerType _eType, const OUString& _rLibName ) const;
 218
 219         /** returns a script or dialog library given by name
 220
 221             @param _eType
 222                 the type of library to load
 223             @param _rLibName
 224                 the name of the script library
 225             @param _bLoadLibrary
 226                 <TRUE/> if and only if the library should be loaded.
 227
 228             @throws NoSuchElementException
 229                 if there is no script library with the given name
 230         */
 231         css::uno::Reference< css::container::XNameContainer >
 232                     getLibrary( LibraryContainerType _eType, const OUString& _rLibName, bool _bLoadLibrary ) const;
 233
 234         /** creates a script or dialog library in the document, or returns an existing one
 235
 236             If <code>_rLibName</code> denotes an existing library which does not need to be created,
 237             then this library will automatically be loaded, and then returned.
 238         */
 239         css::uno::Reference< css::container::XNameContainer >
 240                     getOrCreateLibrary( LibraryContainerType _eType, const OUString& _rLibName ) const;
 241
 242         /** returns the names of the modules in a given script or dialog library of the document
 243         */
 244         css::uno::Sequence< OUString >
 245                     getObjectNames( LibraryContainerType _eType, const OUString& _rLibName ) const;
 246
 247         /** retrieves a name for a newly to be created module or dialog
 248         */
 249         OUString    createObjectName( LibraryContainerType _eType, const OUString& _rLibName ) const;
 250
 251         /** loads a script or dialog library given by name, if there is such a library
 252         */
 253         void        loadLibraryIfExists( LibraryContainerType _eType, const OUString& _rLibrary );
 254
 255         /// retrieves the (combined) names of all script and dialog libraries
 256         css::uno::Sequence< OUString >
 257                     getLibraryNames() const;
 258
 259         /** removes a given script module from the document
 260
 261             @return
 262                 <TRUE/> if and only if the removal was successful. When <FALSE/> is returned,
 263                 this will reported as assertion in a non-product build.
 264         */
 265         bool        removeModule( const OUString& _rLibName, const OUString& _rModuleName ) const;
 266
 267         /** creates a module with the given name in the given library
 268             @param  _rLibName
 269                 the library name
 270             @param  _rModName
 271                 the name of the to-be-created module
 272             @param  _bCreateMain
 273                 determines whether or not a function Main should be created
 274             @param  _out_rNewModuleCode
 275                 the source code of the newly created module
 276             @return
 277                 <TRUE/> if and only if the creation was successful
 278         */
 279         bool        createModule( const OUString& _rLibName, const OUString& _rModName, bool _bCreateMain, OUString& _out_rNewModuleCode ) const;
 280
 281         /** inserts a given piece as code as module
 282             @param  _rLibName
 283                 the name of the library to insert the module into. If a library with this name does
 284                 not yet exist, it will be created.
 285             @param  _rModName
 286                 the name of the module to insert the code as. Must denote a name which is not yet
 287                 used in the module library.
 288             @param  _rModuleCode
 289                 the code of the new module
 290             @return
 291                 <TRUE/> if and only if the insertion was successful.
 292         */
 293         bool        insertModule( const OUString& _rLibName, const OUString& _rModName, const OUString& _rModuleCode ) const;
 294
 295         /** updates a given module with new code
 296             @param  _rLibName
 297                 the name of the library the modules lives in. Must denote an existing module library.
 298             @param  _rModName
 299                 the name of the module to update. Must denote an existing module in the given library.
 300             @param  _rModuleCode
 301                 the new module code.
 302             @return
 303                 <TRUE/> if and only if the insertion was successful.
 304         */
 305         bool        updateModule( const OUString& _rLibName, const OUString& _rModName, const OUString& _rModuleCode ) const;
 306
 307         /// determines whether a module with the given name exists in the given library
 308         bool        hasModule( const OUString& _rLibName, const OUString& _rModName ) const;
 309
 310         /** retrieves a module's source
 311             @param  _rLibName
 312                 the library name where the module is located
 313             @param  _rModName
 314                 the module name
 315             @param  _out_rModuleSource
 316                 takes the module's source upon successful return
 317             @return
 318                 <TRUE/> if and only if the code could be successfully retrieved, <FALSE/> otherwise
 319         */
 320         bool        getModule( const OUString& _rLibName, const OUString& _rModName, OUString& _rModuleSource ) const;
 321
 322         /** renames a module
 323             @param  _rLibName
 324                 the library where the module lives in. Must denote an existing library.
 325             @param  _rOldName
 326                 the old module name. Must denote an existing module.
 327             @param  _rNewName
 328                 the new module name
 329             @return
 330                 <TRUE/> if and only if renaming was successful.
 331         */
 332         bool        renameModule( const OUString& _rLibName, const OUString& _rOldName, const OUString& _rNewName ) const;
 333
 334         /** removes a given dialog from the document
 335
 336             @return
 337                 <TRUE/> if and only if the removal was successful. When <FALSE/> is returned,
 338                 this will reported as assertion in a non-product build.
 339         */
 340         bool        removeDialog( const OUString& _rLibName, const OUString& _rDialogName ) const;
 341
 342         /// determines whether a dialog with the given name exists in the given library
 343         bool        hasDialog( const OUString& _rLibName, const OUString& _rDialogName ) const;
 344
 345         /** retrieves a dialog
 346             @param  _rLibName
 347                 the library name where the module is located
 348             @param  _rDialogName
 349                 the dialog's name
 350             @param  _out_rDialogSource
 351                 takes the provider for the dialog's description, upon successful return
 352             @return
 353                 <TRUE/> if and only if the dialog could be successfully retrieved, <FALSE/> otherwise
 354         */
 355         bool        getDialog(
 356                         const OUString& _rLibName,
 357                         const OUString& _rDialogName,
 358                         css::uno::Reference< css::io::XInputStreamProvider >& _out_rDialogProvider
 359                     ) const;
 360
 361         /** renames a dialog
 362             @param  _rLibName
 363                 the library where the dialog lives in. Must denote an existing library.
 364             @param  _rOldName
 365                 the old dialog name. Must denote an existing dialog.
 366             @param  _rNewName
 367                 the new dialog name
 368             @param _rxExistingDialogModel
 369                 the existing model of the dialog, if already loaded in the IDE
 370             @return
 371                 <TRUE/> if and only if renaming was successful.
 372         */
 373         bool        renameDialog(
 374                         const OUString& _rLibName,
 375                         const OUString& _rOldName,
 376                         const OUString& _rNewName,
 377                         const css::uno::Reference< css::container::XNameContainer >& _rxExistingDialogModel
 378                     ) const;
 379
 380         /** create a dialog
 381             @param  _rLibName
 382                 the library name where the module is located
 383             @param  _rDialogName
 384                 the dialog's name
 385             @param  _out_rDialogSource
 386                 takes the provider for the dialog's description, upon successful return
 387             @return
 388                 <TRUE/> if and only if the dialog could be successfully retrieved, <FALSE/> otherwise
 389         */
 390         bool        createDialog(
 391                         const OUString& _rLibName,
 392                         const OUString& _rDialogName,
 393                         css::uno::Reference< css::io::XInputStreamProvider >& _out_rDialogProvider
 394                     ) const;
 395
 396         /** inserts a given dialog into a given library
 397
 398             @param  _rLibName
 399                 the name of the library to insert the dialog into. If a library with this name does
 400                 not yet exist, it will be created.
 401             @param  _rModName
 402                 the name of the dialog to insert. Must denote a name which is not yet
 403                 used in the dialog library.
 404             @param  _rDialogProvider
 405                 the provider of the dialog's description
 406             @return
 407                 <TRUE/> if and only if the insertion was successful.
 408         */
 409         bool        insertDialog(
 410                         const OUString& _rLibName,
 411                         const OUString& _rDialogName,
 412                         const css::uno::Reference< css::io::XInputStreamProvider >& _rDialogProvider
 413                     ) const;
 414
 415         /** determines whether the document is read-only
 416
 417             cannot be called if the document operates on the application-wide scripts
 418         */
 419         bool        isReadOnly() const;
 420
 421         /** determines whether the ScriptDocument instance operates on the whole application,
 422             as opposed to a real document
 423         */
 424         bool        isApplication() const;
 425
 426         /** determines whether the ScriptDocument instance operates on a real document,
 427             as opposed to the whole application
 428         */
 429         bool        isDocument() const { return isValid() && !isApplication(); }
 430
 431         /** marks the document as modified
 432             @precond
 433                 the instance operates on a real document, not on the application
 434             @see isDocument
 435         */
 436         void        setDocumentModified() const;
 437
 438         /** determines whether the document is modified
 439             @precond
 440                 the instance operates on a real document, not on the application
 441             @see isDocument
 442         */
 443         bool        isDocumentModified() const;
 444
 445         /** saves the document, if the instance refers to a real document
 446             @precond
 447                 <code>isApplication</code> returns <FALSE/>
 448         */
 449         void        saveDocument(
 450                         const css::uno::Reference< css::task::XStatusIndicator >& _rxStatusIndicator
 451                     ) const;
 452
 453         /// returns the location of a library given by name
 454         LibraryLocation
 455                     getLibraryLocation( const OUString& _rLibName ) const;
 456
 457         /// returns the title for the document
 458         OUString    getTitle( LibraryLocation _eLocation, LibraryType _eType = LibraryType::All ) const;
 459
 460         /** returns the title of the document
 461
 462             to be used for valid documents only
 463         */
 464         OUString    getTitle() const;
 465
 466         /** determines whether the document is currently the one-and-only application-wide active document
 467         */
 468         bool        isActive() const;
 469
 470         /** determines whether macro execution for this document is allowed
 471
 472             only to be called for real documents (->isDocument)
 473         */
 474         bool    allowMacros() const;
 475     };
 476
 477
 478 } // namespace basctl
 479
 480
 481 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */