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