Objective-C

Use objc to call Objective-C classes from Lua. This gives your project access to system features beyond Codea’s built-in drawing, input, and sound commands.

Start small

Look up a class, create an object, and call its methods. Check the method’s parameter types: Lua values, native objects, selectors, and structs are passed in different ways. See Objective-C for conversions and examples.

Present native controls from the active view controller. Keep callback objects alive while native code uses them, and release observers or delegates when the project stops. System permissions and entitlements still apply.

Use Objective-C classes and system features from Lua.

Native Classes

To access a native Objective-C class, append its name to objc.

-- access the UIScreen class
UIScreen = objc.UIScreen

Constructor

If the native class has a new constructor, you can invoke it directly instead of calling the new method.

-- create an instance of NSDateComponents
dateComponents = objc.NSDateComponents()

Properties

Properties can be read and modified directly.

-- read the screen brightness
brightness = objc.UIScreen.mainScreen.brightness

-- change the screen brightness
objc.UIScreen.mainScreen.brightness = 0.5

Methods

Methods are invoked using the ‘:’ operator and their full selector name, including named arguments separated by underscores ‘_’ instead of colons. Note that the Objective-C method names must always end with an underscore in Codea. The underscores are required for Codea to find the corresponding signatures in Objective-C.

-- Calling a method with multiple arguments
controller:presentViewController_animated_completion_(newController, true, nil)

-- Calling a method with no argument
webView:goBack_()

Callbacks

Callbacks such as completion handlers with up to 7 arguments are supported by passing a function where each parameter is prefixed to indicate the corresponding native type.

The following prefixes are supported for callback arguments:

• c: char
• i: int, NSInteger
• uc: unsigned char
• ui: unsigned int, NSUInteger
• f: float
• d: double, CGFloat
• b: bool, BOOL
• s: char*
• o: NSObject, NSString, etc.

Note that only the first one or two characters are important in your argument names. bGranted and boolGranted will both work for a boolean argument, but for our examples, we decided to go with the second option.

Struct members are passed separately. For example, for an NSRange argument, you could use intLocation and intLength arguments.

Pointers for value types are also supported by prefixing them with p, (e.g. pboolStop). The actual value can be accessed and modified using .value.

Note that when using objc from within a callback, changes are not guaranteed to occur on the main thread. Consider using objc.async inside your callback if you need changes to happen on the main thread, such as modifying UIControls.

Automatic Conversions

Some Codea types will be converted to corresponding Objective types automatically when passed to native methods or properties.

• color: UIColor
• vec2: CGPoint

--- uiView: objc.UIView
uiView.backgroundColor = Color(255, 0, 0)

--- uiTextView: objc.UITextView
uiTextView:setContentOffset_(vec2(0, 100))

Conversions also happen in the other direction: a UIImage or UIColor returned from a native method arrives in Lua as a Codea image or color.

Disabling automatic conversion

Because the conversion happens on the way into Lua, a returned UIImage has already become a Codea image and can no longer be configured. Set objc.automaticBridging to false to receive the native object instead.

objc.automaticBridging = false

local native = objc.UIImage:systemImageNamed_("globe")
native = native:imageWithTintColor_(color(255, 0, 0))

objc.automaticBridging = true

img = objc.bridge(native)   -- convert it now

objc.bridge(value) performs the conversion explicitly, whatever the current setting is.

Prefer objc.withoutBridging(f), which restores the previous setting afterwards — including when f raises an error, where a bare flag would stay switched off for the rest of the session.

img = objc.withoutBridging(function()
    local native = objc.UIImage:systemImageNamed_("globe")
    native = native:imageWithTintColor_(color(255, 0, 0))
    return objc.bridge(native)
end)

Note

For SF Symbols specifically, prefer image.symbol(), which needs no objc at all.

Examples

Change the screen brightness to 50%

objc.UIScreen.mainScreen.brightness = 0.5

Request application review

scene = objc.app.keyWindow.windowScene
store = objc.SKStoreReviewController
store:requestReviewInScene_(scene)

Request notifications permission

center = objc.
    UNUserNotificationCenter.
    currentNotificationCenter
options = objc.enum.UNAuthorizationOptions
center:requestAuthorizationWithOptions_completionHandler_(
    options.badge | options.sound | options.alert,
    function(boolGranted, objError)
    if boolGranted then
        print("granted")
    elseif objError then
        print("error " .. objError.code)
    end
    end)

Enumerate words until the word stop is found

txt = "First second stop third fourth"
str = objc.string(txt)
str:enumerateSubstringsInRange_options_usingBlock_(
    objc.range(0, txt:len()),
    objc.enum.NSStringEnumerationOptions.byWords,
    function(objWord,
            isubstringLocation,
            iSubstringLength,
            iEnclosingLocation,
            iEnclosingLength,
            pboolStop)
        if objWord == "stop" then
            pboolStop.value = true
        else
            print(objWord)
        end
    end)

Here are some of the frameworks included with the Codea runtime.

Refer to Apple’s documentation for how to interact with them.

• ARKit
• AssetsLibrary
• AudioKit
• AudioToolbox
• AuthenticationServices
• CFNetwork
• CoreBluetooth
• CoreGraphics
• CoreHaptics
• CoreLocation
• CoreMedia
• CoreMIDI
• CoreML
• CoreMotion
• CoreText
• CoreVideo
• FileProvider
• GameController
• GameplayKit
• GLKit
• JavaScriptCore
• MapKit
• MediaPlayer
• MessageUI
• MLCompute
• NaturalLanguage
• OpenGLES
• PDFKit
• PencilKit
• ReplayKit
• Social
• Speech
• UIKit
• UserNotifications
• WebKit

For a more exhaustive list, use the example code below.

List all included system Frameworks

-- list all included system Frameworks
local bundles = objc.NSBundle.allFrameworks
local systemBundles = {}

for i, b in ipairs(bundles) do
    if string.find(
        b.bundlePath,
        "System/Library/Frameworks/") then
        table.insert(systemBundles, b.bundlePath)
    end
end

table.sort(systemBundles)

for i, bundle in ipairs(systemBundles) do
    print(bundle)
end