ETPlugInRegistry class documentation

Authors

Uli Kusterer
Plug-in manager class used to register new plug-ins and obtain already registered plug-ins

Copyright: (C) 2004 Uli Kusterer

Software documentation for the ETPlugInRegistry class

ETPlugInRegistry : NSObject

Declared in:
ETPlugInRegistry.h

@group Plug-Ins

Each plug-in is represented by an NSMutableDictionary to which you can add your own entries as needed. The keys ETPlugInRegistry adds to this dictionary are:

bundle
NSBundle instance for this plug-in
identifier
Unique identifier for this plug-in (bundle identifier in current implementation), see -plugInIdentifierForBundle:
image
Icon (NSImage) of the plug-in (for display in toolbars etc.), see -plugInIconPathForBundle:
name
Display name of the plug-in (for display in lists, toolbars etc.), see -plugInNameForBundle:
path
Full path to the bundle.
class
Principal class (type Class) for this bundle, so you can instantiate it
instance
If -shouldInstantiatePlugInClass is YES, this contains an instance of the principal class, instantiated using alloc+init

ETPlugInRegistry is thread-safe.

Method summary

sharedRegistry 

+ (id) sharedRegistry;

@taskunit Initialization

Returns UKPluginsRegistry shared instance (singleton).

Returns UKPluginsRegistry shared instance (singleton).


loadPlugInAtPath: 

- (NSMutableDictionary*) loadPlugInAtPath: (NSString*)path;

Loads the plug-in bundle located at path .

If the plug-in has already been loaded, immediately returns the same plug-in than previously.

Every property list values associated to the plug-in schema, detailed in ETPlugInRegistry class description, are put in a dictionary which represents a plug-in object; eventual validity errors may be reported each time a value is read in NSBundle description values returned by -infoDictionary .

Raises an NSInvalidArgumentException if path is nil.


loadPlugInsFromPath: ofType: 

- (void) loadPlugInsFromPath: (NSString*)folder ofType: (NSString*)ext;

Finds plug-ins within folder path which are identified by an extension matching ext. Finally loads these plug-ins by calling -loadPlugInAtPath: .

Raises an NSInvalidArgumentException if folder or ext is nil.


loadPlugInsOfType: 

- (void) loadPlugInsOfType: (NSString*)ext;

@taskunit Loading Plug-Ins

Locates and loads plug-in bundles with extension ext in the application-dedicated directory inside the Application Support directory.

If the application's name (taken from NSExecutable in the plist package) is 'Typewriter', then Library/ApplicationSupport/Typewriter will be searched. This search will be repeated in each library per domain (user, system etc.).
This method takes in account the naming variation of the system directories between GNUstep and Mac OS X (e.g. Application Support vs ApplicationSupport).
See -searchPaths .

If the executable is a tool rather than an application, does nothing.

Normally this is the only method you need to call to load a plug-in.

Raises an NSInvalidArgumentException if ext is nil.

Locates and loads plug-in bundles with extension ext in the application-dedicated directory inside the Application Support directory.

If the application's name (taken from NSExecutable in the plist package) is 'Typewriter', then Library/ApplicationSupport/Typewriter will be searched. This search will be repeated in each library per domain (user, system etc.).
This method takes in account the naming variation of the system directories between GNUstep and Mac OS X (e.g. Application Support vs ApplicationSupport).
See -searchPaths .

If the executable is a tool rather than an application, does nothing.

Normally this is the only method you need to call to load a plug-in.

Raises an NSInvalidArgumentException if ext is nil.


loadedPlugIns 

- (NSArray*) loadedPlugIns;

@taskunit Accessing Plug-Ins

Returns the currently registered plug-ins (loaded by the way).

An empty array is returned when no plug-ins have been registered.

Returns the currently registered plug-ins (loaded by the way).

An empty array is returned when no plug-ins have been registered.


plugInIconPathForBundle: 

- (NSString*) plugInIconPathForBundle: (NSBundle*)bundle;

Returns the plug-in icon path from the given bundle info dictionary.

Valid image path keys in the plug-in property list are:

  • CFBundleIcon
  • NSPrefPaneIconFile
  • NSIcon
  • NSApplicationIcon

If there is no valid key, returns nil.


plugInIdentifierForBundle: 

- (NSString*) plugInIdentifierForBundle: (NSBundle*)bundle;

Returns the plug-in identifier from the given bundle info dictionary.

Valid identifier keys in the plug-in property list are:

  • CFBundleIdentifier

If there is no valid key, returns the bundle path.


plugInNameForBundle: 

- (NSString*) plugInNameForBundle: (NSBundle*)bundle;

@taskunit Retrieving Plug-In Schema Infos

Returns the plug-in name from the given bundle info dictionary.

Valid name keys in the plug-in property list are:

  • CFBundleName
  • NSPrefPaneIconLabel
  • ApplicationName
  • NSExecutable

If there is no valid key, returns Unknown.

Returns the plug-in name from the given bundle info dictionary.

Valid name keys in the plug-in property list are:

  • CFBundleName
  • NSPrefPaneIconLabel
  • ApplicationName
  • NSExecutable

If there is no valid key, returns Unknown.


searchPaths 

- (NSArray*) searchPaths;

Returns the paths where plug-ins should be searched by -loadPlugInsOfType: .

If the executable is a tool rather than an application, returns an empty array.

TODO: Allow to customize search paths.


setShouldInstantiatePlugInClass: 

- (void) setShouldInstantiatePlugInClass: (BOOL)instantiate;

Sets to YES if you want to have plug-in main class automatically instantiated when they are loaded, otherwise it's your responsability to retrieve the plug-in class and instantiate it. This is especially useful if a custom initializer is required to make the instantiation. For example:

Class plugInClass = [[registry loadPlugInAtPath: path] objectForKey: @"class"];
CustomObject *mainObject = [[plugInClass alloc] initWithCity: @"Somewhere"];

shouldInstantiatePlugInClass 

- (BOOL) shouldInstantiatePlugInClass;

@taskunit Loading Behavior

Returns whether plug-in class should be instantiated at loading time by the registry.

By default, returns YES.

Read -setShouldInstantiatePlugInClass: documentation to learn more.

Returns whether plug-in class should be instantiated at loading time by the registry.

By default, returns YES.

Read -setShouldInstantiatePlugInClass: documentation to learn more.