» How does iPhone Wax work?

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's Lua Syntax

• In Wax Cocoa classes are referenced just like in 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
  

• To write your own Objective-C object, create a new file with a call to waxClass{CLASS_NAME, PARENT_CLASS} at the top.

  waxClass{"MyClass", NSObject}
  
  -- If you need to add protocols, add them 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.
  

• The waxClass function creates an Objective-C class via the Objective-C runtime. All subsequent functions (within the same file) you add to that Lua file will be automatically added to your new class as instance methods.

• 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 an 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!
  

• 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
  

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

  In Objective-C...

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

  With Wax...

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

• Wax will try and coerce Objective-C objects into Lua. 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 and NSSets 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
  
  -- This will force string to behave like an NSString
  toobjc(string):capitalizedString()
  

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

• 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
  

User Comments