Instance methods are preceded with a dash ("-") and static methods are preceded with a plus ("+").

Remember, in Objective-C, you message objects rather than invoke their methods. Messages are wrapped in brackets ("[" and "]") and the object to be messaged is on the left side, and the message package is on the right.

For example, to call the previous method on an object called myArray, you would do the following (see Listing 22-4).

[myArray insertObject:someObject atIndex:0];

Objective-C also allows you to chain messages together to pass the result of messages in as parameters of other messages, as in Listing 22-5.

[[myAppObject theArray] insertObject:[myAppObject objectToInsert] atIndex:0];

Protocols are declared via the @protocol keyword. For example, Listing 22-11 defines a protocol for XML serialization.

@protocol MyXMLSupport
- initFromXMLRepresentation:(NSXMLElement *)XMLElement;
- (NSXMLElement *)XMLRepresentation;
@end

By default, any methods declared in a protocol are required, but you can also specify that a method be optional with the @optional keyword, as in Listing 22-12.

@protocol MyProtocol
- (void)requiredMethod;
@optional
- (void)anOptionalMethod;
- (void)anotherOptionalMethod;
@required
- (void)anotherRequiredMethod;
@end

Protocols are one of the most extensive features in Objective-C, and you may find while binding an Objective-C library that a protocol is more complicated than the rules presented here. In that case, I recommend reviewing the section on protocols in Apple's Objective-C programming language documentation at http://developer.apple.com/library/mac/#documentation/Cocoa/Conceptual/ObjectiveC/Chapters/ocProtocols.html.

Now that we're seasoned Objective-C experts (sarcasm), let's look at actually compiling an Objective-C library so that we can use it in MonoTouch.

To change the base SDK target, click on the Project menu and then choose Edit Project Settings. Then, in the Base SDK setting, choose Latest iOS..., as shown in Figure 22-6.

Figure 22.6. Setting the Base SDK to be the latest iOS SDK in the Xcode project settings

This will set the library to build against the iOS SDK (as opposed to the Mac OSX SDK, which is usually the default). Due to a bug in Xcode, you may have to close the project and re-open it, for the SDK changes to go into effect.

Once the SDK is set, we need to build the library. First we need to set our build options (via the dropdown shown in Figure 22-7).

We'll want to change the Active Configuration to Release, since it's smaller and faster (and, at this point, the Objective-C code should already be tested and stabilized).

In the case of the Tapku library, we also need to change the Active Target to the TapkuLibrary. There is a second target called TapkuLibraryExtra, which will build another library with extra features in addition to the base library. For the purposes of this example, we only need the main library.

Finally, make sure that armv6 is selected, and then choose Device. Your build options should now look like Figure 22-7.

Figure 22.7. Proper build settings to compile a release build for the device

We're now ready to build. You can either select the Build menu, then Build, or you can just press Command(

When the build is complete, there should be a new folder called "build" in the src folder. In it will be the build outputs arranged into folders named per the configuration. You should see a folder called "Release-iphoneos," and in it, a file called libTapkuLibrary.a.

We want to also build for armv7, but unfortunately it'll put the .a file into the same output directory as the armv6 build, so rename this directory Release-iphoneos armv6 and copy it to a folder somewhere, then change your build version to armv7, and repeat the build steps. Then, rename the output directory Release-iphoneos armv7 and copy that folder to the same place you put the armv6 folder. Now you have both device architectures built.

Now that we have the library built for the device architectures, we also want to build one for the simulator, so change the build option to Simulator and rebuild. You should now see a Release-iphonesimulator folder in the build folder, along with the new library.

Now that we have our library built for all of our architectures, we need to stitch them all together into one single .a file. Mac OSX ships with a command utility called LIPO that allows you to combine multiple architectures of a library into a single "fat" assembly.

LIPO can be executed via a terminal window. To use LIPO to combine builds, use the -create argument and pass an -arch [archtype] [sourcefilename] argument for each architecture you want to include, and specify an -output [filename] argument to specify the output file. For example, the following command will combine an i386, ARMv6, and ARMv7 build into one library, as in Listing 22-13.

lipo -create -arch i386 "../Release-iphonesimulator/libTapkuLibrary.a"
        -arch armv6 "../Release-iphoneos armv6/libTapkuLibrary.a"
        -arch armv7 "../Release-iphoneos armv7/libTapkuLibrary.a"
        -output ./libTapkuLibrary.a

For more information on LIPO, check out the documentation at http://developer.apple.com/library/mac/#documentation/Darwin/Reference/ManPages/man1/lipo.1.html.

For example, the API definition file in Listing 22-14 is pulled from the btouch how-to on the MonoTouch.net site and provides a contract for the Cocos2D.Camera object.

using MonoTouch.Foundation;
namespace Cocos2D
{
        //---- Camera class contract
        [BaseType (typeof (NSObject))]
        interface Camera
        {
                //---- Property Definitions
                [Static, Export ("getZEye")] float ZEye { get; }

//----- Method Contracts
                [Export ("restore")] void Restore ();
                [Export ("locate")] void Locate ();
                [Export ("setEyeX:eyeY:eyeZ:")] void SetEyeXYZ (float x, float y
                        , float z);
                [Export ("setMode:")] void SetMode (CameraMode mode);
        }
}

When you run btouch, it will look at this API definition file and create a Camera class in the Cocos2D namespace and implement a read-only property called ZEye, and a number of methods. The property and methods will automatically call or invoke the appropriate items in the Objective-C library based on the attribution defined in the Interface.

As I mentioned before, the MonoTouch team has written a very good reference on how to write API Definition Files, which you can find at http://monotouch.net/Documentation/Binding_New_Objective-C_Types. Instead of rehashing their excellent work, I'm going to stick to a high-level look at the process and cover the practicalities of how to do this in practice. I recommend having that page open and, as we go through the exercise of binding the Tapku library, read the appropriate section for the type of item we are binding. That will serve as a reference for the discussion that will follow.

There's one thing missing in the previous example. Notice that the SetMode method takes a CameraMode type. I mentioned earlier that, in addition to the API definition file, you might want to write some extra code to help create a more useful binding to use. In this case, we would want to create a CameraMode enumeration that describes the camera mode that we pass to SetMode. So for instance, we might create an enums.cs file and place the Listing 22-15 in it.

public enum CameraMode
{
        FlyOver,
        Back,
        Follow
}

We could create a CameraMode.cs file rather than an enums.cs file, but we'd have to pass all our extra files btouch via command-line arguments when we execute it, so it's easier to just create one file for all enumerations.

In addition to enumerations, you might also need to define any other types, structs, and so on.

Additionally, you often need to add functionality to the classes that are generated via the API definition file. However, since the API definition file can only contain interfaces, not implementation, you can add functionality by creating a partial class definition. For instance, if we wanted to add a ToString method to the Cocos2D.Camera class, we could create write the following, and put it in a classes.cs file, as in Listing 22-16.

namespace Cocos2D
{
        public partial class Camera
        {
                //---- Provide a ToString method
                public override string ToString ()
                {
                        return String.Format ("ZEye: {0}", ZEye);
                }
        }
}

As with the enums.cs file, we would pass our classes.cs file as an argument when we run btouch, and it would get compiled into our assembly.

Now that we have a good understanding of how the pieces fit together, let's look at the practical exercise of actually creating the API definition file and associated code.

Wrapping an Objective-C library can be a big undertaking, especially if the library is large. For this reason, it's best to undertake it in stages. I recommend starting with just the pieces that you need. Let's start with Tapku's Coverflow control (TKCoverflowView).

In order to create an API definition file, you have to figure out what you're wrapping. In fact, this is the trickiest part of binding to Objective-C libraries. Even with good documentation, you almost always have to look at the source. We'll see an example of this in just a bit. Let's start with the documentation. You can find the Tapku documentation at https://github.com/devinross/tapkulibrary/wiki/. If you click on "Coverflow" under the "Classes Overview" section, it gives you a rundown of what constitutes the TKCoverflowView class.

Compared to most, this is actually pretty good documentation.

The first thing we want to do is create an interface for the TKCoverFlowView class; however, in looking at the documentation, it doesn't say what it derives from. Off to the code we go. If you open up the TKCoverflowView.h file in Xcode, you'll see that it has the declaration shown in Listing 22-17.

@interface TKCoverflowView : UIScrollView <UIScrollViewDelegate>

From this, we see that TKCoverflowView derives form UIScrollView, and implements the UIScrollViewDelegate protocol. So we can start our Tapku.cs API definition file as shown in Listing 22-18.

using System;
using MonoTouch.Foundation;
using MonoTouch.CoreFoundation;
namespace Tapku
{
        [BaseType(typeof(UIScrollView))]
        interface TKCoverFlow
        {

        }
}

By the way, if you haven't taken a look at the documents on creating an API definition file at http://monotouch.net/Documentation/Binding_New_Objective-C_Types, now is a good time to do so.

As you bind a class, you'll find that you often have to bind other things first. Tapku's cover flow control is no different. If we go back to the TKCoverflowView documentation, it looks like there are the following several other classes that we'll need to create before we finish the TKCoverflowView binding:

TKCoverView is pretty straightforward; it just has a couple of properties. However, the delegate and data source are a bit different. We want to be sophisticated, so we want to expose the delegate's methods as events on the TKCoverflowView class. Additionally, the data source is a protocol, so that's a little different as well.

@property (retain,nonatomic) UIImage *image;
@property (assign,nonatomic) float baseline;

// @interface TKCoverflowCoverView : UIView
[BaseType(typeof(UIView))]
interface TKCoverflowCoverView
{
        // @property (retain,nonatomic) UIImage *image;
        [Export("image", ArgumentSemantic.Retain)]
        UIImage Image { get; set; }

        // @property (assign,nonatomic) float baseline;
        [Export("baseline", ArgumentSemantic.Assign)]
        float Baseline { get; set; }
}

[Export("initWithFrame:")]
IntPtr Constructor(RectangleF frame);

// @interface TKCoverflowCoverView : UIView
[BaseType(typeof(UIView))]
interface TKCoverflowCoverView
{
        [Export("initWithFrame:")]
        IntPtr Constructor(RectangleF frame);

        // @property (retain,nonatomic) UIImage *image;
        [Export("image", ArgumentSemantic.Retain)]
        UIImage Image { get; set; }

        // @property (assign,nonatomic) float baseline;
        [Export("baseline", ArgumentSemantic.Assign)]
        float Baseline { get; set; }
}

// @protocol TKCoverflowViewDataSource <NSObject>
[BaseType (typeof (NSObject))]
[Model]
interface TKCoverflowViewDataSource
{
        // @required
        // - (TKCoverflowCoverView*) coverflowView:(TKCoverflowView*)coverflowView
                coverAtIndex:(int)index;
        [Export("coverflowView:coverAtIndex:"), Abstract]
        TKCoverflowCoverView GetCover(TKCoverflowView coverflowView, int index);
}

- (TKCoverflowCoverView*) coverflowView:(TKCoverflowView*)coverflowView coverAtIndex:(int)index

coverflowView:coverAtIndex:

// @protocol TKCoverflowViewDelegate <NSObject>
[BaseType (typeof (NSObject))]
[Model]
interface TKCoverflowViewDelegate
{
        // @required
        // - (void) coverflowView:(TKCoverflowView*)coverflowView
                coverAtIndexWasBroughtToFront:(int)index;
        [Export("coverflowView:coverAtIndexWasBroughtToFront:"), EventArgs ("Coverflow")
                , Abstract]
        void CoverWasBroughtToFront(TKCoverflowView coverflowView, int index);

        // @optional
        // - (void) coverflowView:(TKCoverflowView*)coverflowView
                coverAtIndexWasDoubleTapped:(int)index;
        [Export("coverflowView:coverAtIndexWasDoubleTapped:"), EventArgs ("Coverflow")]
        void CoverWasDoubleTapped(TKCoverflowView coverflowView, int index);

}

public event EventHandler<CoverflowEventArgs> CoverWasBroughtToFront;
public event EventHandler<CoverflowEventArgs> CoverWasDoubleTapped;

public class CoverflowEventArgs : EventArgs
{
        public CoverflowEventArgs (int index);
        public int Index { get; set; }
}

Events=new Type [] { typeof (TKCoverflowViewDelegate)}

// @interface TKCoverflowView : UIScrollView <UIScrollViewDelegate>
[BaseType(typeof(UIScrollView), Delegates=new string [] { "Delegate" }
        , Events=new Type [] { typeof (TKCoverflowViewDelegate)})]
interface TKCoverflowView
{
        //==== constructors
        [Export("initWithFrame:")]
        IntPtr Constructor(RectangleF frame);


        //==== Properties

        // @property (nonatomic, assign) CGSize coverSize; // default 224 x 224
        [Export("coverSize", ArgumentSemantic.Assign)]
        SizeF CoverSize { get; set; }

        // @property (nonatomic, assign) int numberOfCovers;
        [Export("numberOfCovers", ArgumentSemantic.Assign)]
        int NumberOfCovers { get; set; }

        // @property (nonatomic, assign) float coverSpacing;
        [Export("coverSpacing", ArgumentSemantic.Assign)]
        float CoverSpacing { get; set; }

        // @property (nonatomic, assign) float coverAngle;
        [Export("coverAngle", ArgumentSemantic.Assign)]
        float CoverAngle { get; set; }


        //==== Methods

        // - (TKCoverflowCoverView*) dequeueReusableCoverView;
        [Export("dequeueReusableCoverView")]
        TKCoverflowCoverView DequeueReusableCoverView();

        // - (TKCoverflowCoverView*) coverAtIndex:(int)index;
        [Export("coverAtIndex:")]
        TKCoverflowCoverView GetCover(int index);

        // - (int) indexOfFrontCoverView;
        // bind this as a read-only property
        [Export("indexOfFrontCoverView")]

int FrontCoverIndex { get; }

        // - (void) bringCoverAtIndexToFront:(int)index animated:(BOOL)animated;
        [Export("bringCoverAtIndexToFront:animated:")]
        void BringCoverToFront(int index, bool animated);


        //==== Prototype properties

        // @property (nonatomic, assign) id <TKCoverflowViewDelegate> delegate;
        // hides the underlying delegate property, so we need to add the new attribute
        [Export("delegate", ArgumentSemantic.Assign), New]
        TKCoverflowViewDelegate Delegate { get; set; }

        // @property (nonatomic, assign) id <TKCoverflowViewDataSource> dataSource;
        [Export("dataSource", ArgumentSemantic.Assign)]
        TKCoverflowViewDataSource DataSource { get; set; }

}

[Export("indexOfFrontCoverView")]
int FrontCoverIndex { get; }

[Export("delegate", ArgumentSemantic.Assign), New]
TKCoverflowViewDelegate Delegate { get; set; }

This is as far as you need to take the binding to get it to work. However, if you want maximum flexibility in how to wire up the delegate methods in MonoTouch, you should follow the weak-delegate pattern. I cover the pattern extensively in Chapter 6, but briefly, it allows the consumers of the library to either assign a strongly-typed-delegate on the object, or use any class that has the appropriate methods.

Following the weak-delegate pattern is very easy; we just have to do the following tweaks:

For example, our delegate property declarations following the weak-delegate pattern would look like Listing 22-33.

[Export ("delegate", ArgumentSemantic.Assign), New][NullAllowed]
NSObject WeakDelegate { get; set; }

[Wrap ("WeakDelegate"), New]
TKCoverflowViewDelegate Delegate { get; set; }

Very simple!

That seemed like a lot, because I narrated the process fairly thoroughly, but the entire binding necessary for a complete Tapku Coverflow usage is now done. I've included it here to show the entire thing altogether. I've stripped out the comments for brevity (see Listing 22-34).

using System;
using System.Drawing;
using MonoTouch.UIKit;
using MonoTouch.ObjCRuntime;
using MonoTouch.Foundation;
using MonoTouch.CoreFoundation;

namespace Tapku
{
        [BaseType(typeof(UIScrollView), Delegates=new string [] { "Delegate" }
                , Events=new Type [] { typeof (TKCoverflowViewDelegate)})]
        interface TKCoverflowView
        {
                [Export("initWithFrame:")]
                IntPtr Constructor(RectangleF frame);

                [Export("coverSize", ArgumentSemantic.Assign)]
                SizeF CoverSize { get; set; }

                [Export("numberOfCovers", ArgumentSemantic.Assign)]
                int NumberOfCovers { get; set; }

                [Export("coverSpacing", ArgumentSemantic.Assign)]
                float CoverSpacing { get; set; }

                [Export("coverAngle", ArgumentSemantic.Assign)]
                float CoverAngle { get; set; }

                [Export("dequeueReusableCoverView")]
                TKCoverflowCoverView DequeueReusableCoverView();

[Export("coverAtIndex:")]
                TKCoverflowCoverView GetCover(int index);

                [Export("indexOfFrontCoverView")]
                int FrontCoverIndex { get; }

                [Export("bringCoverAtIndexToFront:animated:")]
                void BringCoverToFront(int index, bool animated);

                [Export ("delegate", ArgumentSemantic.Assign), New][NullAllowed]
                NSObject WeakDelegate { get; set; }

                [Wrap ("WeakDelegate"), New]
                TKCoverflowViewDelegate Delegate { get; set; }
                [Export("dataSource", ArgumentSemantic.Assign)]
                TKCoverflowViewDataSource DataSource { get; set; }

        }

        [BaseType(typeof(UIView))]
        interface TKCoverflowCoverView
        {
                [Export("initWithFrame:")]
                IntPtr Constructor(RectangleF frame);

                [Export("image", ArgumentSemantic.Retain)]
                UIImage Image { get; set; }

                [Export("baseline", ArgumentSemantic.Assign)]
                float Baseline { get; set; }
        }

        [BaseType (typeof (NSObject))]
        [Model]
        interface TKCoverflowViewDataSource
        {
                [Export("coverflowView:coverAtIndex:"), Abstract]
                TKCoverflowCoverView GetCover(TKCoverflowView coverflowView, int index);
        }

        [BaseType (typeof (NSObject))]
        [Model]
        interface TKCoverflowViewDelegate
        {
                [Export("coverflowView:coverAtIndexWasBroughtToFront:")
                        , EventArgs ("Coverflow"), Abstract]
                void CoverWasBroughtToFront(TKCoverflowView coverflowView, int index);

                [Export("coverflowView:coverAtIndexWasDoubleTapped:")
                        , EventArgs ("Coverflow")]
                void CoverWasDoubleTapped(TKCoverflowView coverflowView, int index);

        }
}

Now that we have a completed binding, lets run btouch to generate our DLL.