basctl/source/inc/scriptdocument.hxx

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