Branch data Line data Source code
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 SCRIPTDOCUMENT_HXX
21 : : #define 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 BasicManager;
32 : : class SfxListener;
33 : :
34 : : //........................................................................
35 : : namespace basctl
36 : : {
37 : : //........................................................................
38 : :
39 : : //====================================================================
40 : : //= LibraryContainerType
41 : : //====================================================================
42 : : enum LibraryContainerType
43 : : {
44 : : E_SCRIPTS,
45 : : E_DIALOGS
46 : : };
47 : :
48 : : enum LibraryLocation
49 : : {
50 : : LIBRARY_LOCATION_UNKNOWN,
51 : : LIBRARY_LOCATION_USER,
52 : : LIBRARY_LOCATION_SHARE,
53 : : LIBRARY_LOCATION_DOCUMENT
54 : : };
55 : :
56 : : enum LibraryType
57 : : {
58 : : LIBRARY_TYPE_UNKNOWN,
59 : : LIBRARY_TYPE_MODULE,
60 : : LIBRARY_TYPE_DIALOG,
61 : : LIBRARY_TYPE_ALL
62 : : };
63 : :
64 : : //====================================================================
65 : : //= ScriptDocument
66 : : //====================================================================
67 : : class ScriptDocument_Impl;
68 : :
69 : : class ScriptDocument;
70 : : typedef ::std::vector< ScriptDocument > ScriptDocuments;
71 : :
72 : : /** encapsulates a document which contains Basic scripts and dialogs
73 : : */
74 : 0 : class ScriptDocument
75 : : {
76 : : private:
77 : : ::boost::shared_ptr< ScriptDocument_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 ::rtl::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 : 0 : 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 ::rtl::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 ::rtl::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 ::rtl::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< ::rtl::OUString >
264 : : getObjectNames( LibraryContainerType _eType, const ::rtl::OUString& _rLibName ) const;
265 : :
266 : : /** retrieves a name for a newly to be created module or dialog
267 : : */
268 : : ::rtl::OUString
269 : : createObjectName( LibraryContainerType _eType, const ::rtl::OUString& _rLibName ) const;
270 : :
271 : : /** loads a script or dialog library given by name, if there is such a library
272 : : */
273 : : void loadLibraryIfExists( LibraryContainerType _eType, const ::rtl::OUString& _rLibrary );
274 : :
275 : : /// retrieves the (combined) names of all script and dialog libraries
276 : : ::com::sun::star::uno::Sequence< ::rtl::OUString >
277 : : getLibraryNames() const;
278 : :
279 : : /** removes a given script module from the document
280 : :
281 : : @return
282 : : <TRUE/> if and only if the removal was successful. When <FALSE/> is returned,
283 : : this will reported as assertion in a non-product build.
284 : : */
285 : : bool removeModule( const ::rtl::OUString& _rLibName, const ::rtl::OUString& _rModuleName ) const;
286 : :
287 : : /** creates a module with the given name in the given library
288 : : @param _rLibName
289 : : the library name
290 : : @param _rModName
291 : : the name of the to-be-created module
292 : : @param _bCreateMain
293 : : determines whether or not a function Main should be created
294 : : @param _out_rNewModuleCode
295 : : the source code of the newly created module
296 : : @return
297 : : <TRUE/> if and only if the creation was successful
298 : : */
299 : : bool createModule( const ::rtl::OUString& _rLibName, const ::rtl::OUString& _rModName, bool _bCreateMain, ::rtl::OUString& _out_rNewModuleCode ) const;
300 : :
301 : : /** inserts a given piece as code as module
302 : : @param _rLibName
303 : : the name of the library to insert the module into. If a library with this name does
304 : : not yet exist, it will be created.
305 : : @param _rModName
306 : : the name of the module to insert the code as. Must denote a name which is not yet
307 : : used in the module library.
308 : : @param _rModuleCode
309 : : the code of the new module
310 : : @return
311 : : <TRUE/> if and only if the insertion was successful.
312 : : */
313 : : bool insertModule( const ::rtl::OUString& _rLibName, const ::rtl::OUString& _rModName, const ::rtl::OUString& _rModuleCode ) const;
314 : :
315 : : /** updates a given module with new code
316 : : @param _rLibName
317 : : the name of the library the modules lives in. Must denote an existing module library.
318 : : @param _rModName
319 : : the name of the module to update. Must denote an existing module in the given library.
320 : : @param _rModuleCode
321 : : the new module code.
322 : : @return
323 : : <TRUE/> if and only if the insertion was successful.
324 : : */
325 : : bool updateModule( const ::rtl::OUString& _rLibName, const ::rtl::OUString& _rModName, const ::rtl::OUString& _rModuleCode ) const;
326 : :
327 : : /// determines whether a module with the given name exists in the given library
328 : : bool hasModule( const ::rtl::OUString& _rLibName, const ::rtl::OUString& _rModName ) const;
329 : :
330 : : /** retrieves a module's source
331 : : @param _rLibName
332 : : the library name where the module is located
333 : : @param _rModName
334 : : the module name
335 : : @param _out_rModuleSource
336 : : takes the module's source upon successful return
337 : : @return
338 : : <TRUE/> if and only if the code could be successfully retrieved, <FALSE/> otherwise
339 : : */
340 : : bool getModule( const ::rtl::OUString& _rLibName, const ::rtl::OUString& _rModName, ::rtl::OUString& _rModuleSource ) const;
341 : :
342 : : /** renames a module
343 : : @param _rLibName
344 : : the library where the module lives in. Must denote an existing library.
345 : : @param _rOldName
346 : : the old module name. Must denote an existing module.
347 : : @param _rNewName
348 : : the new module name
349 : : @return
350 : : <TRUE/> if and only if renaming was successful.
351 : : */
352 : : bool renameModule( const ::rtl::OUString& _rLibName, const ::rtl::OUString& _rOldName, const ::rtl::OUString& _rNewName ) const;
353 : :
354 : : /** removes a given dialog from the document
355 : :
356 : : @return
357 : : <TRUE/> if and only if the removal was successful. When <FALSE/> is returned,
358 : : this will reported as assertion in a non-product build.
359 : : */
360 : : bool removeDialog( const ::rtl::OUString& _rLibName, const ::rtl::OUString& _rDialogName ) const;
361 : :
362 : : /// determines whether a dialog with the given name exists in the given library
363 : : bool hasDialog( const ::rtl::OUString& _rLibName, const ::rtl::OUString& _rDialogName ) const;
364 : :
365 : : /** retrieves a dialog
366 : : @param _rLibName
367 : : the library name where the module is located
368 : : @param _rDialogName
369 : : the dialog's name
370 : : @param _out_rDialogSource
371 : : takes the provider for the dialog's desription, upon successful return
372 : : @return
373 : : <TRUE/> if and only if the dialog could be successfully retrieved, <FALSE/> otherwise
374 : : */
375 : : bool getDialog(
376 : : const ::rtl::OUString& _rLibName,
377 : : const ::rtl::OUString& _rDialogName,
378 : : ::com::sun::star::uno::Reference< ::com::sun::star::io::XInputStreamProvider >& _out_rDialogProvider
379 : : ) const;
380 : :
381 : : /** renames a dialog
382 : : @param _rLibName
383 : : the library where the dialog lives in. Must denote an existing library.
384 : : @param _rOldName
385 : : the old dialog name. Must denote an existing dialog.
386 : : @param _rNewName
387 : : the new dialog name
388 : : @param _rxExistingDialogModel
389 : : the existing model of the dialog, if already loaded in the IDE
390 : : @return
391 : : <TRUE/> if and only if renaming was successful.
392 : : */
393 : : bool renameDialog(
394 : : const ::rtl::OUString& _rLibName,
395 : : const ::rtl::OUString& _rOldName,
396 : : const ::rtl::OUString& _rNewName,
397 : : const ::com::sun::star::uno::Reference< ::com::sun::star::container::XNameContainer >& _rxExistingDialogModel
398 : : ) const;
399 : :
400 : : /** create a dialog
401 : : @param _rLibName
402 : : the library name where the module is located
403 : : @param _rDialogName
404 : : the dialog's name
405 : : @param _out_rDialogSource
406 : : takes the provider for the dialog's desription, upon successful return
407 : : @return
408 : : <TRUE/> if and only if the dialog could be successfully retrieved, <FALSE/> otherwise
409 : : */
410 : : bool createDialog(
411 : : const ::rtl::OUString& _rLibName,
412 : : const ::rtl::OUString& _rDialogName,
413 : : ::com::sun::star::uno::Reference< ::com::sun::star::io::XInputStreamProvider >& _out_rDialogProvider
414 : : ) const;
415 : :
416 : : /** inserts a given dialog into a given library
417 : :
418 : : @param _rLibName
419 : : the name of the library to insert the dialog into. If a library with this name does
420 : : not yet exist, it will be created.
421 : : @param _rModName
422 : : the name of the dialog to insert. Must denote a name which is not yet
423 : : used in the dialog library.
424 : : @param _rDialogProvider
425 : : the provider of the dialog's description
426 : : @return
427 : : <TRUE/> if and only if the insertion was successful.
428 : : */
429 : : bool insertDialog(
430 : : const ::rtl::OUString& _rLibName,
431 : : const ::rtl::OUString& _rDialogName,
432 : : const ::com::sun::star::uno::Reference< ::com::sun::star::io::XInputStreamProvider >& _rDialogProvider
433 : : ) const;
434 : :
435 : : /** determines whether the document is read-only
436 : :
437 : : cannot be called if the document operates on the application-wide scripts
438 : : */
439 : : bool isReadOnly() const;
440 : :
441 : : /** determines whether the ScriptDocument instance operates on the whole application,
442 : : as opposed to a real document
443 : : */
444 : : bool isApplication() const;
445 : :
446 : : /** determines whether the ScriptDocument instance operates on a real document,
447 : : as opposed to the whole application
448 : : */
449 : 0 : bool isDocument() const { return isValid() && !isApplication(); }
450 : :
451 : : /** marks the document as modified
452 : : @precond
453 : : the instance operates on a real document, not on the application
454 : : @see isDocument
455 : : */
456 : : void setDocumentModified() const;
457 : :
458 : : /** determines whether the document is modified
459 : : @precond
460 : : the instance operates on a real document, not on the application
461 : : @see isDocument
462 : : */
463 : : bool isDocumentModified() const;
464 : :
465 : : /** saves the document, if the instance refers to a real document
466 : : @precond
467 : : <code>isApplication</code> returns <FALSE/>
468 : : */
469 : : bool saveDocument(
470 : : const ::com::sun::star::uno::Reference< ::com::sun::star::task::XStatusIndicator >& _rxStatusIndicator
471 : : ) const;
472 : :
473 : : /// returns the location of a library given by name
474 : : LibraryLocation
475 : : getLibraryLocation( const ::rtl::OUString& _rLibName ) const;
476 : :
477 : : /// returns the title for the document
478 : : ::rtl::OUString
479 : : getTitle( LibraryLocation _eLocation, LibraryType _eType = LIBRARY_TYPE_ALL ) const;
480 : :
481 : : /** returns the title of the document
482 : :
483 : : to be used for valid documents only
484 : : */
485 : : ::rtl::OUString
486 : : getTitle() const;
487 : :
488 : : /** returns the URL of the document
489 : :
490 : : to be used for valid documents only
491 : : */
492 : : ::rtl::OUString
493 : : getURL() const;
494 : :
495 : : /** determines whether the document is currently the one-and-only application-wide active document
496 : : */
497 : : bool isActive() const;
498 : :
499 : : /** determines whether macro execution for this document is allowed
500 : :
501 : : only to be called for real documents (->isDocument)
502 : : */
503 : : bool allowMacros() const;
504 : : };
505 : :
506 : : //........................................................................
507 : : } // namespace basctl
508 : : //........................................................................
509 : :
510 : : // convenience ... better would be all classes in the project are in
511 : : // the same namespace ...
512 : : using ::basctl::ScriptDocument;
513 : : using ::basctl::ScriptDocuments;
514 : : using ::basctl::E_SCRIPTS;
515 : : using ::basctl::E_DIALOGS;
516 : : using ::basctl::LibraryLocation;
517 : : using ::basctl::LIBRARY_LOCATION_UNKNOWN;
518 : : using ::basctl::LIBRARY_LOCATION_USER;
519 : : using ::basctl::LIBRARY_LOCATION_SHARE;
520 : : using ::basctl::LIBRARY_LOCATION_DOCUMENT;
521 : : using ::basctl::LibraryType;
522 : : using ::basctl::LIBRARY_TYPE_UNKNOWN;
523 : : using ::basctl::LIBRARY_TYPE_MODULE;
524 : : using ::basctl::LIBRARY_TYPE_DIALOG;
525 : : using ::basctl::LIBRARY_TYPE_ALL;
526 : :
527 : : #endif // SCRIPTDOCUMENT_HXX
528 : :
529 : : /* vim:set shiftwidth=4 softtabstop=4 expandtab: */
|
