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 INCLUDED_BASCTL_SOURCE_INC_SCRIPTDOCUMENT_HXX
21 : #define INCLUDED_BASCTL_SOURCE_INC_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 :
252 : /** creates a script or dialog library in the document, or returns an existing one
253 :
254 : If <code>_rLibName</code> denotes an existing library which does not need to be created,
255 : then this library will automatically be loaded, and then returned.
256 : */
257 : ::com::sun::star::uno::Reference< ::com::sun::star::container::XNameContainer >
258 : getOrCreateLibrary( LibraryContainerType _eType, const OUString& _rLibName ) const;
259 :
260 : /** returns the names of the modules in a given script or dialog library of the document
261 : */
262 : ::com::sun::star::uno::Sequence< OUString >
263 : getObjectNames( LibraryContainerType _eType, const OUString& _rLibName ) const;
264 :
265 : /** retrieves a name for a newly to be created module or dialog
266 : */
267 : OUString createObjectName( LibraryContainerType _eType, const OUString& _rLibName ) const;
268 :
269 : /** loads a script or dialog library given by name, if there is such a library
270 : */
271 : void loadLibraryIfExists( LibraryContainerType _eType, const OUString& _rLibrary );
272 :
273 : /// retrieves the (combined) names of all script and dialog libraries
274 : ::com::sun::star::uno::Sequence< OUString >
275 : getLibraryNames() const;
276 :
277 : /** removes a given script module from the document
278 :
279 : @return
280 : <TRUE/> if and only if the removal was successful. When <FALSE/> is returned,
281 : this will reported as assertion in a non-product build.
282 : */
283 : bool removeModule( const OUString& _rLibName, const OUString& _rModuleName ) const;
284 :
285 : /** creates a module with the given name in the given library
286 : @param _rLibName
287 : the library name
288 : @param _rModName
289 : the name of the to-be-created module
290 : @param _bCreateMain
291 : determines whether or not a function Main should be created
292 : @param _out_rNewModuleCode
293 : the source code of the newly created module
294 : @return
295 : <TRUE/> if and only if the creation was successful
296 : */
297 : bool createModule( const OUString& _rLibName, const OUString& _rModName, bool _bCreateMain, OUString& _out_rNewModuleCode ) const;
298 :
299 : /** inserts a given piece as code as module
300 : @param _rLibName
301 : the name of the library to insert the module into. If a library with this name does
302 : not yet exist, it will be created.
303 : @param _rModName
304 : the name of the module to insert the code as. Must denote a name which is not yet
305 : used in the module library.
306 : @param _rModuleCode
307 : the code of the new module
308 : @return
309 : <TRUE/> if and only if the insertion was successful.
310 : */
311 : bool insertModule( const OUString& _rLibName, const OUString& _rModName, const OUString& _rModuleCode ) const;
312 :
313 : /** updates a given module with new code
314 : @param _rLibName
315 : the name of the library the modules lives in. Must denote an existing module library.
316 : @param _rModName
317 : the name of the module to update. Must denote an existing module in the given library.
318 : @param _rModuleCode
319 : the new module code.
320 : @return
321 : <TRUE/> if and only if the insertion was successful.
322 : */
323 : bool updateModule( const OUString& _rLibName, const OUString& _rModName, const OUString& _rModuleCode ) const;
324 :
325 : /// determines whether a module with the given name exists in the given library
326 : bool hasModule( const OUString& _rLibName, const OUString& _rModName ) const;
327 :
328 : /** retrieves a module's source
329 : @param _rLibName
330 : the library name where the module is located
331 : @param _rModName
332 : the module name
333 : @param _out_rModuleSource
334 : takes the module's source upon successful return
335 : @return
336 : <TRUE/> if and only if the code could be successfully retrieved, <FALSE/> otherwise
337 : */
338 : bool getModule( const OUString& _rLibName, const OUString& _rModName, OUString& _rModuleSource ) const;
339 :
340 : /** renames a module
341 : @param _rLibName
342 : the library where the module lives in. Must denote an existing library.
343 : @param _rOldName
344 : the old module name. Must denote an existing module.
345 : @param _rNewName
346 : the new module name
347 : @return
348 : <TRUE/> if and only if renaming was successful.
349 : */
350 : bool renameModule( const OUString& _rLibName, const OUString& _rOldName, const OUString& _rNewName ) const;
351 :
352 : /** removes a given dialog from the document
353 :
354 : @return
355 : <TRUE/> if and only if the removal was successful. When <FALSE/> is returned,
356 : this will reported as assertion in a non-product build.
357 : */
358 : bool removeDialog( const OUString& _rLibName, const OUString& _rDialogName ) const;
359 :
360 : /// determines whether a dialog with the given name exists in the given library
361 : bool hasDialog( const OUString& _rLibName, const OUString& _rDialogName ) const;
362 :
363 : /** retrieves a dialog
364 : @param _rLibName
365 : the library name where the module is located
366 : @param _rDialogName
367 : the dialog's name
368 : @param _out_rDialogSource
369 : takes the provider for the dialog's desription, upon successful return
370 : @return
371 : <TRUE/> if and only if the dialog could be successfully retrieved, <FALSE/> otherwise
372 : */
373 : bool getDialog(
374 : const OUString& _rLibName,
375 : const OUString& _rDialogName,
376 : ::com::sun::star::uno::Reference< ::com::sun::star::io::XInputStreamProvider >& _out_rDialogProvider
377 : ) const;
378 :
379 : /** renames a dialog
380 : @param _rLibName
381 : the library where the dialog lives in. Must denote an existing library.
382 : @param _rOldName
383 : the old dialog name. Must denote an existing dialog.
384 : @param _rNewName
385 : the new dialog name
386 : @param _rxExistingDialogModel
387 : the existing model of the dialog, if already loaded in the IDE
388 : @return
389 : <TRUE/> if and only if renaming was successful.
390 : */
391 : bool renameDialog(
392 : const OUString& _rLibName,
393 : const OUString& _rOldName,
394 : const OUString& _rNewName,
395 : const ::com::sun::star::uno::Reference< ::com::sun::star::container::XNameContainer >& _rxExistingDialogModel
396 : ) const;
397 :
398 : /** create a dialog
399 : @param _rLibName
400 : the library name where the module is located
401 : @param _rDialogName
402 : the dialog's name
403 : @param _out_rDialogSource
404 : takes the provider for the dialog's desription, upon successful return
405 : @return
406 : <TRUE/> if and only if the dialog could be successfully retrieved, <FALSE/> otherwise
407 : */
408 : bool createDialog(
409 : const OUString& _rLibName,
410 : const OUString& _rDialogName,
411 : ::com::sun::star::uno::Reference< ::com::sun::star::io::XInputStreamProvider >& _out_rDialogProvider
412 : ) const;
413 :
414 : /** inserts a given dialog into a given library
415 :
416 : @param _rLibName
417 : the name of the library to insert the dialog into. If a library with this name does
418 : not yet exist, it will be created.
419 : @param _rModName
420 : the name of the dialog to insert. Must denote a name which is not yet
421 : used in the dialog library.
422 : @param _rDialogProvider
423 : the provider of the dialog's description
424 : @return
425 : <TRUE/> if and only if the insertion was successful.
426 : */
427 : bool insertDialog(
428 : const OUString& _rLibName,
429 : const OUString& _rDialogName,
430 : const ::com::sun::star::uno::Reference< ::com::sun::star::io::XInputStreamProvider >& _rDialogProvider
431 : ) const;
432 :
433 : /** determines whether the document is read-only
434 :
435 : cannot be called if the document operates on the application-wide scripts
436 : */
437 : bool isReadOnly() const;
438 :
439 : /** determines whether the ScriptDocument instance operates on the whole application,
440 : as opposed to a real document
441 : */
442 : bool isApplication() const;
443 :
444 : /** determines whether the ScriptDocument instance operates on a real document,
445 : as opposed to the whole application
446 : */
447 0 : bool isDocument() const { return isValid() && !isApplication(); }
448 :
449 : /** marks the document as modified
450 : @precond
451 : the instance operates on a real document, not on the application
452 : @see isDocument
453 : */
454 : void setDocumentModified() const;
455 :
456 : /** determines whether the document is modified
457 : @precond
458 : the instance operates on a real document, not on the application
459 : @see isDocument
460 : */
461 : bool isDocumentModified() const;
462 :
463 : /** saves the document, if the instance refers to a real document
464 : @precond
465 : <code>isApplication</code> returns <FALSE/>
466 : */
467 : bool saveDocument(
468 : const ::com::sun::star::uno::Reference< ::com::sun::star::task::XStatusIndicator >& _rxStatusIndicator
469 : ) const;
470 :
471 : /// returns the location of a library given by name
472 : LibraryLocation
473 : getLibraryLocation( const OUString& _rLibName ) const;
474 :
475 : /// returns the title for the document
476 : OUString getTitle( LibraryLocation _eLocation, LibraryType _eType = LIBRARY_TYPE_ALL ) const;
477 :
478 : /** returns the title of the document
479 :
480 : to be used for valid documents only
481 : */
482 : OUString getTitle() const;
483 :
484 : /** returns the URL of the document
485 :
486 : to be used for valid documents only
487 : */
488 : OUString getURL() const;
489 :
490 : /** determines whether the document is currently the one-and-only application-wide active document
491 : */
492 : bool isActive() const;
493 :
494 : /** determines whether macro execution for this document is allowed
495 :
496 : only to be called for real documents (->isDocument)
497 : */
498 : bool allowMacros() const;
499 : };
500 :
501 :
502 : } // namespace basctl
503 :
504 :
505 : #endif // INCLUDED_BASCTL_SOURCE_INC_SCRIPTDOCUMENT_HXX
506 :
507 : /* vim:set shiftwidth=4 softtabstop=4 expandtab: */
|
