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