Documentation

ETPlugInRegistry class documentation

ETPlugInRegistry : NSObject

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

AuthorsGenerated by qmathe
Declared inETPlugInRegistry.h

Overview

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.


Initialization

+ (id) sharedRegistry

Returns UKPluginsRegistry shared instance (singleton).

Returns UKPluginsRegistry shared instance (singleton).

    Loading Plug-Ins

    - (void) loadPlugInsOfType: (NSString *)ext

    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.

      - (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.

        - (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.

          Accessing Plug-Ins

          - (NSArray *) loadedPlugIns

          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.

            Loading Behavior

            - (BOOL) shouldInstantiatePlugInClass

            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.

              - (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"];
              
                - (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.

                  Retrieving Plug-In Schema Infos

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

                  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.

                    - (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.

                      - (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.