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