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 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 0 : 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 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 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 0 : 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: */
|
