Overview

Here is a quick tour of the Wax framework. By the end you should have a better understanding of how Wax interacts with Objective-C.

• Wax is a Lua bridge to Objective-C. This means you can write Lua that talks to Objective-C and you can write Objective-C that talks with Lua!

• Accessing a Cocoa class in Lua (via Wax) looks just like Objective-C

    NSString -- Returns the NSString class
    UIView -- Returns the UIView class

    UITableView -- This is just syntactic sugar for the line below.
    wax.class["UITableView"] -- This is the raw Wax call, you probably didn't need to know this

• When you create an instance of an Objective-C object DON'T call alloc, wax handles this for you.

    -- No need to call alloc, retain or release! ZOMG!
    local view = UIView.initWithFrame(CGRect(0, 0, 100, 100))

• To create an Objective-C class from Lua, call the function waxClass{CLASS\_NAME, PARENT_CLASS}. All subsequent functions (within the same file) you add to that Lua file will be automatically added to your new class as instance methods.

    waxClass{"MyClass", NSObject}

    -- Add protocols like this
    waxClass{"MyClass", NSObject, protocols = {"UITableViewDelegate", "UITableViewDataSource"}}

    -- REMEMBER! Protocols need to be added as strings (This is because they are not classes)

• Calling a Lua function with brackets {} instead of parenthesis () (like in the above call to waxClass) is just syntactic sugar for calling a function with a single table as the argument.

    waxClass{"MyClass", NSObject}
    -- is equivalent to...
    waxClass({"MyClass", NSObject})
    -- ...omitting the parenthesis is much more pretty, so that's how we roll.

• For waxClass functions, the first argument must be self. This is how Wax mimics Objective-C's object orientated model.

    waxClass{"MyClass", NSObject}

    -- Notice the first argument is self... this will hold the instance of `MyClass` 
    function storeWords(self, words)
      self.words = words
      
      -- Wax creates a `super` variable on the self object. 
      -- Use that to call a method on the object's super class.
      self.super:words(self)
    end

• Use a colon : instead of a dot . when you call any Objective-C method. This passes the calling object in as the first argument to the method.

    -- A method called with a colon : in Lua ...
    UIApplication:sharedApplication()

    -- ... is equivalent to this
    UIApplication.sharedApplication(UIApplication)

    -- So we just use the colon : to keep this DRY and readable!

• If an Objective-C method takes multiple arguments, the method call uses underscores _ instead of colons like Objective-C does.

  In Objective-C...

    [UIAlertView initWithTitle:@"title" message:@"message" delegate:nil];

With Wax...

    UIAlertView:initWithTitle_message_delegate("title", "message", nil)

• Wax DOESN'T use Objective-C properties. Wax forces Lua and Objective-C to only communicate with methods

    someView.frame -- This WON'T work. 

    -- You want to use the getter/setter methods instead
    someView:frame()
    someView:setFrame(someFrame)

• You can dynamically create member variables for any Objective-C object using the dot . operator. Unlike the colon : operator (used to call methods on an Objective-C class/instance) the dot . operator dynamically creates member variables on the Lua side of the object (The Objective-C side of the object has no knowledge of these variables). The member variables are available throughout the lifetime of the object.

    -- A method called with a colon : in Lua ...
    local view = UIView:init()

    view.someRandomVariable = "YEAH!"
    -- You can assign anything to an instance and it will stick around 

• Wax will try and coerce Objective-C objects into Lua primatives. It also does the reverse, if an Objective-C methods takes an NSString argument, you can just pass it a Lua string.

    local fileManager = NSFileManager:defaultManager()
    local contents = fileManager:directoryContentsAtPath(".")
    -- directoryContentsAtPath returns an NSArray, but Wax turns this into a Lua
    -- table, which is totally cooler.

    print(contents[1]) --> "info.plist"

    -- NSDictionaries become Lua tables
    -- NSArrays become Lua tables
    -- NSStrings become Lua strings
    -- NSNumbers become Lua numbers

• Sometimes you don't want an Objective-C object to be coerced, for that use the toobjc method.

    -- if you are trying to call an NSString method, this will fail ...
    local string = "a string"
    string:capitalizedString()
    -- ... because string is coerced into a Lua string

    -- Instead use toobjc, it will force string to be a NSString
    toobjc(string):capitalizedString()

• Enums, like UITableViewStylePlain, are hardcoded. For now the most commonly used ones are declared in APP_ROOT/wax/stdlib/enums.lua. In the future I hope to get BridgeSupport working for the iPhone so all enums & structs can be created automatically.

• To pass a selector, just use a string. For example in Objective-C selectors are written as @selector(this:is:a:method). In Wax they are written as this:is:a:method.

• Structs are also tricky, the most common ones are decalred in APP_ROOT/wax/wax-scripts/structs.lua. It is easy to add structs by following the pattern found in the structs.lua file.

    wax.struct.create("CGRect", "ffff", "x", "y", "width", "height")

    -- The creates a global function called CGRect that takes 4 float arguments,
    -- the second argument "ffff" is what defines the argument types.

    local rect = CGRect(1, 2, 3, 4)
    print(rect.x) --> 1
    rect.x = 200
    print(rect.x) --> 200