Xojo Documentation Xojo Documentation

Cocoa Plugins

Building a plugin for the Cocoa target requires a Mach-O dynamic library (.dylib). This is the same as the Carbon Mach-O target, but should be done using GCC or Xcode, simply because the Cocoa target will become Universal within the next 6 months. CodeWarrior does not support Universal Binaries.

The updated plugins SDK contains an Xcode template that will build a dynamic library. It has been tested with Xcode 2.2 and GCC 3.3 and 4. Some changes include the ability to have rb_plugin.h and REALplugin.h compile in a plain C environment. This allows rb_plugin.h to be included in an Objective-C build.

Also included are two example plugins that support Cocoa. The DialControl has been updated to show how to write a non-native control that is CoreGraphics based. The PNG Utilities plugin has been included and updated to show image manipulation in CoreGraphics with the Cocoa platform layer additions.

Now, onto the nitty-gritty.

Creating a Prefix Header for Cocoa

Previously, you would just use one of the headers in the Includes folder. However, this may not work specifically for your existing plugin. There are a few options that can be toggled in the prefix header that will affect what is available to your plugin. RBCocoaHeaders.h can be used, but can also be customized to your needs:

COCOA - If defined to true, the Cocoa-specific APIs will be available. FLAT_C_PLUGIN_HEADERS - Determines if the headers should avoid overloaded functions, which aren't valid for C. If true, an existing plugin may need to be updated to use the non-conflicting names. ALLOW_CARBON_IN_COCOA - Certain functions, such as the FolderItem functions, rely on Carbon definitions such as FSRef or FSSpec. If defined to true, Carbon APIs will be included.

Plugins in the IDE

All Mac plugins must be Cocoa and 64-bit in order to be recognized by the IDE.

Graphics Additions

CGContextRef REALGraphicsGetCGContext( REALgraphics context );

Returns the CGContext for the graphics in question. Can return NULL if not part of a Picture or passed into the Paint event. This is because in Cocoa the way to get the context outside of the Paint event requires -[NSView lockFocus] and -[NSView unlockFocus] in a pair. Simply asking for the handle gives no location to do the Unlock. The lock and unlock focus can be done on the handle of the control (REALGetControlHandle).

Picture Additions

Two new picture types:

• pictureCGBitmapContext- Returns the internal CGContextRef that is a bitmap context.
• pictureCGImage- Returns the composited CGImageRef of the picture in question. This picture will already have transparency or masks calculated, and is ready to draw. Do not hold onto this picture -- if needed, create a copy of the picture.

Plugin Controls

Plugin controls behave in two ways in Cocoa, due to how Cocoa's events are propogated (NSView isa NSResponder, thus must be subclassed to override the events).

If you return an NSView from the RBControlBehaviour.controlHandleGetter function:

• You will only receive constructor, destructor, open, close, stateChanged, enableMenuItemsFunction, menuItemActionFunction, and drawOffscreen on the RBControlBeahviour.
• Your control will automatically be resized based on the lock properties, hidden as needed (tabs, visibility).
• Disabling/Enabling must be done by you (NSControl defines the setEnabled method, and REALbasic only assumes NSView).

If you return NULL, or don't implement the controlHandleGetter function:

• You will receive all the methods on the RBControlBehaviour structure.
• Your control will automatically be resized based on the lock properties, hidden as needed (tabs, visibility).
• Disabling/Enabling must be done by you (NSControl defines the setEnabled method, and REALbasic only assumes NSView).
• A custom NSView subclass is what will be returned from REALGetControlHandle.

Reporting Bugs

Please file all bug reports against Cocoa plugins using the Plugin SDK category.