Debian Codegraph @

src/af/xap/cocoa/xap_CocoaPlugin.h

raw
1 /* -*- mode: C++; tab-width: 4; c-basic-offset: 4; -*- */
2
3 /* AbiSource Application Framework
4 * Copyright (C) 2004-2005 Francis James Franklin
5 *
6 * This program is free software; you can redistribute it and/or
7 * modify it under the terms of the GNU General Public License
8 * as published by the Free Software Foundation; either version 2
9 * of the License, or (at your option) any later version.
10 *
11 * This program is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 * GNU General Public License for more details.
15 *
16 * You should have received a copy of the GNU General Public License
17 * along with this program; if not, write to the Free Software
18 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
19 * 02110-1301 USA.
20 */
21
22 #ifndef XAP_COCOAPLUGIN_H
23 #define XAP_COCOAPLUGIN_H
24
25 #define XAP_COCOAPLUGIN_INTERFACE 20050925 /** The current version of the CocoaPlugin API. */
26
27 #import <Cocoa/Cocoa.h>
28
29 #import "xap_CocoaCompat.h"
30
31 @class XAP_CocoaPlugin;
32
33 @protocol XAP_CocoaPlugin_Tool;
34 @protocol XAP_CocoaPlugin_ToolProvider;
35
36 /**
37 * \protocol XAP_CocoaPlugin_ToolInstance XAP_CocoaPlugin.h "XAP_CocoaPlugin.h"
38 *
39 * A class which has a toolbar button and, optionally, a menu item associated with
40 * a specific tool. The class also manages size and image information which can be
41 * saved to and loaded from a configuration file, if desired.
42 */
43 @protocol XAP_CocoaPlugin_ToolInstance
44
45 /**
46 * Information about what this tool actually is, rather than what it looks like, can
47 * be obtained from the tool which created this instance.
48 *
49 * \return The tool associated with this object.
50 */
51 - (id <NSObject, XAP_CocoaPlugin_Tool>)tool;
52
53 /**
54 * The XAP_CocoaPlugin_ToolInstance object manages a button and, optionally, a menu
55 * item.
56 *
57 * \return The button managed by this object.
58 */
59 - (NSView *)toolbarButton;
60
61 /**
62 * The XAP_CocoaPlugin_ToolInstance object may manage a menu item for use in case the
63 * button disappears off the end of the toolbar.
64 *
65 * \return The menu item managed by this object, or nil if there is no menu item.
66 */
67 - (NSMenuItem *)toolbarMenuItem;
68
69 /**
70 * The XAP_CocoaPlugin_ToolInstance manages a set of configuration strings.
71 *
72 * \return The string describing the width of the button - should be @"auto" if it is
73 * the same as the default setting.
74 */
75 - (NSString *)configWidth;
76
77 /**
78 * The XAP_CocoaPlugin_ToolInstance manages a set of configuration strings.
79 *
80 * \return The string describing the height of the button - should be @"auto" if it is
81 * the same as the default setting.
82 */
83 - (NSString *)configHeight;
84
85 /**
86 * The XAP_CocoaPlugin_ToolInstance manages a set of configuration strings.
87 *
88 * \return The string describing the image used by the button, if any image is used at all.
89 * Should be @"auto" if it is the same as the default setting.
90 */
91 - (NSString *)configImage;
92
93 /**
94 * The XAP_CocoaPlugin_ToolInstance manages a set of configuration strings.
95 *
96 * \return The string describing the alternative image used by the button, if any image
97 * is used at all. Should be @"auto" if it is the same as the default setting.
98 */
99 - (NSString *)configAltImage;
100
101 /**
102 * The XAP_CocoaPlugin_ToolInstance manages a set of configuration strings.
103 *
104 * \param width The width setting which has been read from a configuration file.
105 */
106 - (void)setConfigWidth:(NSString *)width;
107
108 /**
109 * The XAP_CocoaPlugin_ToolInstance manages a set of configuration strings.
110 *
111 * \param height The height setting which has been read from a configuration file.
112 */
113 - (void)setConfigHeight:(NSString *)height;
114
115 /**
116 * The XAP_CocoaPlugin_ToolInstance manages a set of configuration strings.
117 *
118 * \param image The image setting (i.e., filename) which has been read from a
119 * configuration file.
120 */
121 - (void)setConfigImage:(NSString *)image;
122
123 /**
124 * The XAP_CocoaPlugin_ToolInstance manages a set of configuration strings.
125 *
126 * \param altImage The alternative image setting (i.e., filename) which has been
127 * read from a configuration file.
128 */
129 - (void)setConfigAltImage:(NSString *)altImage;
130 @end
131
132 /**
133 * \protocol XAP_CocoaPlugin_Tool XAP_CocoaPlugin.h "XAP_CocoaPlugin.h"
134 *
135 * A class which provides information about a specific tool. Any given tool
136 * may have any number of buttons (or menu items) in any number of toolbars;
137 * the XAP_CocoaPlugin_Tool object is used to create instances of these.
138 */
139 @protocol XAP_CocoaPlugin_Tool
140
141 /**
142 * Each tool, for a given provider, has a unique identifier.
143 *
144 * \return The unique identifier for this tool.
145 */
146 - (NSString *)identifier;
147
148 /**
149 * The description is the tooltip or menu item name for this tool.
150 *
151 * \return A description of this tool.
152 */
153 - (NSString *)description;
154
155 /**
156 * When a tool is added to a tool provider, the provider sends a setProvider: message to the tool.
157 *
158 * \param provider The tool provider which has assumed ownership of this tool, or nil if the
159 * provider has removed the tool from its list. (Internal use only.)
160 */
161 - (void)setProvider:(id <NSObject, XAP_CocoaPlugin_ToolProvider>)provider;
162
163 /**
164 * The tool provider which owns the tool.
165 *
166 * \return The tool provider which owns the tool, or nil if none does.
167 */
168 - (id <NSObject, XAP_CocoaPlugin_ToolProvider>)provider;
169
170 /**
171 * Multiple toolbar buttons can be created for a particular tool. This method instantiates a new
172 * tool object which manages a toolbar button and, optionally, a menu item.
173 *
174 * \return A tool object which manages a toolbar button and, optionally, a menu item.
175 */
176 - (id <NSObject, XAP_CocoaPlugin_ToolInstance>)tool;
177 @end
178
179 /**
180 * \protocol XAP_CocoaPlugin_ToolProvider XAP_CocoaPlugin.h "XAP_CocoaPlugin.h"
181 *
182 * A class which provides a set of available tools which can be used to create a
183 * toolbar.
184 */
185 @protocol XAP_CocoaPlugin_ToolProvider
186
187 /**
188 * Get the name of the provider.
189 *
190 * \return The name identifying the provider.
191 */
192 - (NSString *)name;
193
194 /**
195 * Get the tool with the specified identifier.
196 *
197 * \param identifier The identifier of the tool which is desired.
198 *
199 * \return The specified tool, or nil if the identifier is not matched.
200 */
201 - (id <NSObject, XAP_CocoaPlugin_Tool>)toolWithIdentifier:(NSString *)identifier;
202
203 /**
204 * Get the identifiers of the tools provided.
205 *
206 * \return The identifiers of the tools provided.
207 */
208 - (NSArray *)toolIdentifiers;
209
210 /**
211 * See whether the provider provides a specific tool, and get the description (tooltip).
212 *
213 * \param identifier The internal identifier of the desired tool.
214 *
215 * \return The description (the tooltip) of the tool if the identifier is recognized, otherwise nil.
216 */
217 - (NSString *)toolDescription:(NSString *)identifier;
218
219 @end
220
221 /**
222 * \protocol XAP_CocoaPlugin_SimpleXML XAP_CocoaPlugin.h "XAP_CocoaPlugin.h"
223 *
224 * A simple call-back interface for SAX-style XML parsing.
225 */
226 @protocol XAP_CocoaPlugin_SimpleXML
227
228 /**
229 * Called on start of a new element.
230 *
231 * \param name The element name.
232 * \param attributes The element's attributes as a dictionary.
233 *
234 * \return This method should return YES normally, but NO in order to stop parsing.
235 */
236 - (BOOL)startElement:(NSString *)name attributes:(NSDictionary *)attributes;
237
238 /**
239 * Called on end of a element.
240 *
241 * \param name The element name.
242 *
243 * \return This method should return YES normally, but NO in order to stop parsing.
244 */
245 - (BOOL)endElement:(NSString *)name;
246
247 /**
248 * Called with text data.
249 *
250 * \param data The character data.
251 *
252 * \return This method should return YES normally, but NO in order to stop parsing.
253 */
254 - (BOOL)characterData:(NSString *)data;
255
256 @end
257
258 /**
259 * \protocol XAP_CocoaPlugin_MenuItem XAP_CocoaPlugin.h "XAP_CocoaPlugin.h"
260 *
261 * A reference to a context menu item.
262 */
263 @protocol XAP_CocoaPlugin_MenuItem
264
265 /**
266 * \param label Set the label of the context menu item.
267 */
268 - (void)setLabel:(NSString *)label;
269
270 /**
271 * \return The label of the context menu item.
272 */
273 - (NSString *)label;
274
275 #if 0 // YAGNI
276 /**
277 * \param aSelector Set the method which is called when the call-back is triggered, or
278 * nil if no method is to be called.
279 */
280 - (void)setAction:(SEL)aSelector;
281
282 /**
283 * \return The method which is called when the call-back is triggered, or nil if none.
284 */
285 - (SEL)action;
286
287 /**
288 * \param target Set a new target object for the action when the call-back is triggered, or
289 * nil if no method is to be called.
290 */
291 - (void)setTarget:(id <NSObject>)target;
292
293 /**
294 * \return The new target object for the action when the call-back is triggered, or nil if none.
295 */
296 - (id <NSObject>)target;
297 #endif
298
299 /**
300 * \param anInt An integer which can be used to identify this particular object.
301 */
302 - (void)setTag:(NSInteger)anInt;
303
304 /**
305 * \return The integer used to identify this particular object.
306 */
307 - (NSInteger)tag;
308
309 /**
310 * \param state To have a check (tick) beside the menu item, set the state to NSOnState, otherwise
311 * set it to NSOffState. The default is NSOffState.
312 */
313 - (void)setState:(int)state;
314
315 /**
316 * \return Returns YES if the menu item is checked (ticked).
317 */
318 - (int)state;
319
320 /**
321 * \param enabled YES if the menu item should be enabled, or NO if the menu item should be greyed
322 * (i.e., non-selectable). The default is YES.
323 */
324 - (void)setEnabled:(BOOL)enabled;
325
326 /**
327 * \return Returns YES if the menu item is selectable.
328 */
329 - (BOOL)isEnabled;
330
331 @end
332
333 /**
334 * \protocol XAP_CocoaPlugin_FramelessDocument XAP_CocoaPlugin.h "XAP_CocoaPlugin.h"
335 *
336 * Plug-in API for manipulating documents which do not have windows. Typically these
337 * loaded from a file. See XAP_CocoaPlugin's importDocumentFromFile:importOptions: method.
338 */
339 @protocol XAP_CocoaPlugin_FramelessDocument
340
341 /**
342 * Save the document in the document file format suggested by the path's extension
343 * (e.g., .html, .txt).
344 *
345 * \param path The output file path. This should have an appropriate extension.
346 * \param options A dictionary mapping of NSString keys to NSString values; these
347 * options are passed to the exporter. May be nil.
348 *
349 * \return Returns YES on success, NO on failure.
350 */
351 - (BOOL)exportDocumentToFile:(NSString *)path exportOptions:(NSDictionary *)options;
352
353 @end
354
355 /**
356 * \protocol XAP_CocoaPlugin_Document XAP_CocoaPlugin.h "XAP_CocoaPlugin.h"
357 *
358 * Plug-in API for manipulating documents which are on-screen. The current document, if any,
359 * or a list of available documents can be obtained via XAP_CocoaPlugin's currentDocument
360 * and documents methods.
361 *
362 * Please bear in mind that documents can be closed, so if you keep these references to
363 * documents lying around for future use then you should check that the documents they refer
364 * to still exist using the documentStillExists method.
365 *
366 * This is really a reference to a document window, and not to the specific document itself.
367 */
368 @protocol XAP_CocoaPlugin_Document
369
370 /**
371 * It is quite possible for document windows to be closed by the user. If you retain document
372 * references then it's a good idea to check that the document window still exists.
373 *
374 * \return Returns YES if the document window still exists; otherwise NO.
375 */
376 - (BOOL)documentStillExists;
377
378 /**
379 * \return The title of the document, or, if the window no longer exists, the string
380 * "(This document no longer exists!)".
381 */
382 - (NSString *)title;
383
384 /**
385 * Selects and returns the current word, if any.
386 *
387 * \return The current word, or nil if none could be selected.
388 */
389 - (NSString *)selectWord;
390
391 /**
392 * Returns the current selection, if any.
393 *
394 * \return The currently selected text, or nil if none is selected.
395 */
396 - (NSString *)selectedText;
397
398 /**
399 * Insert a text string into the document.
400 *
401 * \param text The string to insert.
402 */
403 - (void)insertText:(NSString *)text;
404
405 /* Mail Merge interface
406 */
407 - (NSString *)documentMailMergeSource; // may return nil
408 - (void)setDocumentMailMergeSource:(NSString *)path;
409
410 - (void)insertDocumentMailMergeField:(NSString *)field_name;
411
412 - (NSArray *)documentMailMergeFields;
413 - (void)setDocumentMailMergeFields:(NSArray *)field_array;
414 - (void)unsetDocumentMailMergeFields;
415
416 /* value_dictionary maps (NSString *) keys [field names] to (NSString *) values.
417 */
418 - (void)setDocumentMailMergeValues:(NSDictionary *)value_dictionary;
419
420 @end
421
422 /**
423 * \protocol XAP_CocoaPluginDelegate XAP_CocoaPlugin.h "XAP_CocoaPlugin.h"
424 *
425 * In order for AbiWord to interact with the plug-in, the plug-in needs to implement
426 * this protocol. As a minimum, the bundle's principal class must implement the
427 * NSObject protocol and the XAP_CocoaPluginDelegate's
428 * pluginCanRegisterForAbiWord:version:interface: method.
429 */
430 @protocol XAP_CocoaPluginDelegate
431
432 /**
433 * This will be called immediately after initialization;
434 *
435 * If the bundle's principal class implements *only* this method, it must immediately set
436 * the real XAP_CocoaPluginDelegate object as AbiWord's delegate using XAP_CocoaPlugin's
437 * setDelegate: method.
438 *
439 * The plug-in should not activate - wait for XAP_CocoaPluginDelegate's pluginActivate:
440 * method to be called.
441 *
442 * \param AbiWord The main interface to AbiWord.
443 * \param version This is the AbiWord version string (e.g., "2.2.5").
444 * \param interface This is the date (YYYYMMDD) that the CocoaPlugin API was last changed.
445 *
446 * \return Should return NO if for some reason the plug-in won't work with the current
447 * version of AbiWord.
448 */
449 - (BOOL)pluginCanRegisterForAbiWord:(XAP_CocoaPlugin *)AbiWord version:(NSString *)version interface:(unsigned long)interface;
450
451 /**
452 * Returns whether the plug-in is active or not.
453 *
454 * \return Should return YES if the plug-in is active; otherwise NO.
455 */
456 - (BOOL)pluginIsActive;
457
458 /**
459 * This is a request for the plug-in to activate.
460 */
461 - (void)pluginActivate; /* Add menuitems etc. */
462
463 /**
464 * This is a request for the plug-in to deactivate. The plug-in *must* comply.
465 */
466 - (void)pluginDeactivate; /* Remove them... */
467
468 /**
469 * The plug-in should attempt to save all files, etc., since it is about to be asked to
470 * deactivate. Returning NO will not necessarily prevent the request to deactivate.
471 *
472 * \return Should return NO *only* if the user has answered "Cancel" to an alert about
473 * an unsaved document; otherwise YES.
474 */
475 - (BOOL)pluginCanDeactivate;
476
477 /**
478 * AbiWord will call this if the focus changes to a different document, or different window
479 * or panel, or if the current document is closed.
480 */
481 - (void)pluginCurrentDocumentHasChanged;
482
483 /**
484 * The name of the plug-in.
485 *
486 * \return The name of the plug-in.
487 */
488 - (NSString *)pluginName;
489
490 /**
491 * The name(s) of the plug-in author(s).
492 *
493 * \return The name(s) of the plug-in author(s).
494 */
495 - (NSString *)pluginAuthor;
496
497 /**
498 * The version of the plug-in.
499 *
500 * \return The version of the plug-in.
501 */
502 - (NSString *)pluginVersion;
503
504 /**
505 * A short description of what the plug-in does.
506 *
507 * \return A short description of what the plug-in does.
508 */
509 - (NSString *)pluginDescription;
510
511 /**
512 * A short description of how to use the plug-in.
513 *
514 * \return A short description of how to use the plug-in.
515 */
516 - (NSString *)pluginUsage;
517
518 @end
519
520 /**
521 * \class XAP_CocoaPlugin XAP_CocoaPlugin.h "XAP_CocoaPlugin.h"
522 *
523 * This class provides the main interface between the plug-in and AbiWord.
524 */
525 @interface XAP_CocoaPlugin : NSObject
526 {
527 id <NSObject, XAP_CocoaPluginDelegate> m_delegate; /** The plug-in's delegate, by default the bundle's principal class. */
528 }
529
530 /**
531 * (For internal use only.)
532 */
533 - (id)init;
534
535 /**
536 * (For internal use only.)
537 */
538 - (void)dealloc;
539
540 /**
541 * (For internal use only.)
542 *
543 * .Abi plug-ins are bundles; loadBundle attempts to load the bundle specified to initWithPath,
544 * returns NO if the bundle is already loaded (to avoid duplication) or if it can't be loaded.
545 * The plug-in's principal class is initialized with init and is set as the delegate, and must
546 * conform therefore to the XAP_CocoaPluginDelegate protocol (or set a new delegate when
547 * pluginCanRegisterForAbiWord:version:interface: is called).
548 */
549 - (BOOL)loadBundleWithPath:(NSString *)path;
550
551 /**
552 * If the plug-in bundle's principal class does not implement the XAP_CocoaPluginDelegate
553 * protocol, then, when the pluginCanRegisterForAbiWord:version:interface: method is called, it
554 * should set a new delegate object which does implement the protocol.
555 *
556 * \param delegate The new delegate (must not be nil). The delegate is not retained.
557 *
558 * \see XAP_CocoaPluginDelegate
559 */
560 - (void)setDelegate:(id <NSObject, XAP_CocoaPluginDelegate>)delegate;
561
562 /**
563 * The plug-in's delegate.
564 *
565 * \return The delegate object - the bundle's principal class, unless the plug-in has
566 * substituted another.
567 */
568 - (id <NSObject, XAP_CocoaPluginDelegate>)delegate;
569
570 /**
571 * Add a menu item to the end of the Tools menu.
572 *
573 * This is an NSMenuItem object that the plug-in makes itself (or loads from a nib file) and
574 * so can have submenus etc. This procedure for adding menu items to AbiWord's main menu
575 * does not use AbiWord's cross-platform method for adding menu items (which may not currently
576 * work anyway - I'm not sure).
577 *
578 * \param menuItem The menu item to add to the Tools menu.
579 */
580 - (void)appendMenuItem:(NSMenuItem *)menuItem;
581
582 /**
583 * Remove a menu item from the end of the Tools menu.
584 *
585 * \param menuItem The menu item to remove from the Tools menu.
586 */
587 - (void)removeMenuItem:(NSMenuItem *)menuItem;
588
589 /**
590 * Get a reference to the current document window, if any.
591 *
592 * Please bear in mind that documents can be closed, so be careful when keeping references
593 * to documents lying around for future use.
594 *
595 * Note: These are really references to document windows, and sometimes the actual documents
596 * can change even though the document window is the same.
597 *
598 * \return Returns a reference to the currently active document window; or nil if none.
599 */
600 - (id <NSObject, XAP_CocoaPlugin_Document>)currentDocument; // may return nil;
601
602 /**
603 * Get an array of references to the current document windows, if any.
604 *
605 * Please bear in mind that documents can be closed, so be careful when keeping references
606 * to documents lying around for future use.
607 *
608 * Note: These are really references to document windows, and sometimes the actual documents
609 * can change even though the document window is the same.
610 *
611 * \return Returns an array of references to the available document windows.
612 */
613 - (NSArray *)documents; // array of id <NSObject, XAP_CocoaPlugin_Document>
614
615 /**
616 * Pops up a File Open dialog for the user to select a source file for mail merge.
617 *
618 * \return Returns the path of the selected mail merge source file; or nil if none selected.
619 */
620 - (NSString *)selectMailMergeSource; // may return nil
621
622 /**
623 * Loads a mail merge source file and builds an array of arrays containing the fields.
624 *
625 * \param path The file name of the mail merge source file.
626 *
627 * \return Returns an NSMutableArray whose objects are NSMutableArray of NSString, the first
628 * row holding the field names, the rest being records; returns nil on failure.
629 */
630 - (NSMutableArray *)importMailMergeSource:(NSString *)path;
631
632 /**
633 * Open the specified document without creating a document window. This can be useful for
634 * automated document processing (printing, conversion, etc.).
635 *
636 * \param path The input file path.
637 * \param options A dictionary mapping of NSString keys to NSString values; these
638 * options are passed to the importer. May be nil.
639 *
640 * \return Returns the frameless document on success, nil on failure.
641 *
642 * \see XAP_CocoaPlugin_FramelessDocument
643 */
644 - (id <NSObject, XAP_CocoaPlugin_FramelessDocument>)importDocumentFromFile:(NSString *)path importOptions:(NSDictionary *)options;
645
646 /**
647 * Add a menu item to the context menu.
648 * You should retain the returned context menu item object, since the menu item is removed from
649 * the context menu when the object is deleted.
650 *
651 * \param label The label of the menu item in the context menu.
652 *
653 * \return A reference to a context menu item object.
654 *
655 * \see XAP_CocoaPlugin_MenuItem
656 */
657 - (id <NSObject, XAP_CocoaPlugin_MenuItem>)contextMenuItemWithLabel:(NSString *)label;
658
659 /**
660 * Get a list of all the tool providers.
661 * Each tool provider is of type id <NSObject, XAP_CocoaPlugin_ToolProvider>.
662 *
663 * \return The tool providers.
664 */
665 - (NSArray *)toolProviders;
666
667 /**
668 * Find a tool provider by name.
669 * (TODO: If plug-ins are registering tool providers, we need to implement a notification
670 * system to update toolbar systems.)
671 *
672 * \param name The name of the tool provider to find.
673 *
674 * \return The tool provider, or nil if none is registered with the given name.
675 */
676 - (id <NSObject, XAP_CocoaPlugin_ToolProvider>)toolProvider:(NSString *)name;
677
678 /**
679 * Find a file in one of AbiWord's resource locations.
680 * This looks in the user's AbiSuite folder first, then the system AbiSuite folder, and
681 * finally the AbiWord bundle's Resources folder. Must be a regular file.
682 *
683 * \param relativePath A filename or relative path, e.g., "MyPlugin/config.xml".
684 *
685 * \return The full path to the specified resource, or nil if not found.
686 */
687 - (NSString *)findResourcePath:(NSString *)relativePath;
688
689 /**
690 * Generate a path in the user's AbiSuite resource location.
691 *
692 * \param relativePath A filename or relative path, e.g., "MyPlugin/config.xml".
693 *
694 * \return The full path to the specified resource.
695 */
696 - (NSString *)userResourcePath:(NSString *)relativePath;
697
698 /**
699 * Parse an XML file using a simple XML call-back interface.
700 *
701 * \param path The path to the XML file.
702 * \param callback An object which implements the XAP_CocoaPlugin_SimpleXML protocol.
703 *
704 * \return A string with an error message on failure, or nil on success.
705 */
706 - (NSString *)parseFile:(NSString *)path simpleXML:(id <XAP_CocoaPlugin_SimpleXML>)callback;
707
708 @end
709
710 #endif /* XAP_COCOAPLUGIN_H */