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