Ruby Cocoa

KosmicTask Help

Ruby Cocoa

Ruby Cocoa tasks access the Cocoa framework via the RubyCocoa bridge.

RubyCocoa provides a bridge between the Ruby and Objective-C programming languages.

Calling the Task Run Function

The entry point for Ruby Cocoa task can be a simple named function. The name of this function is configured using the Run Function task setting. Alternatively the entry point may consist of a named function within a named class. The class name is configured using the Run Class task setting.

require 'osx/cocoa'

class KosmicTask < OSX::NSObject

    #
    # task entry point
    #
    def kosmictask()
        return "Hello, kosmos!"
    end
end

When the task is executed the run class is instantiated and the run function is called.

Result Objects

Tasks written in Ruby Cocoa can return native Ruby objects or Cocoa objects as task results. The RubyCocoa bridge ensures that all objects are coerced as required.

require 'osx/cocoa'

def kosmictask()
    result =  OSX::NSString.stringWithString_("Hello, kosmos!")

    return result
end

Result File Handling

KosmicTask supports the returning of file contents within task results.

KosmicTask automatically looks for a kosmicFile record containing file paths within a dictionary type result object. If found, KosmicTask will return the contents of the file or files to the client.

For Ruby Cocoa powered tasks files are returned as results using the following syntax:

result = Hash.new()
result["kosmicFile"] = path
return result

A common usage scenario is that a task creates a temporary file (or files) whose contents are then returned to the client. KosmicTask therefore supports automatic temporary file creation and deletion. Temporary files created through KosmicTask are automatically deleted once the parent task has completed.

Ruby Cocoa powered tasks can create temporary files by calling the KosmicTaskController resultFileWithName_ function.

require 'osx/cocoa'

# KosmicTask controller
$taskController = OSX.NSClassFromString("KosmicTaskController")

def kosmictask()

    # create path to temp result file from taskController.
    # this file will be automatically deleted when the task ends.
    #
    # an alternative would be:
    # f = Tempfile.new('kosmictask')
    # f.close
    # path = f.path + "capture.png"
    #
    path = $taskController.resultFileWithName_("capture.png");

    # capture sceen shot to file
    system "screencapture -t png " + path

    # create our result hash
    result = Hash.new()

    # add keyed file path
    result["kosmicFile"] = path

    # add keyed info
    result["kosmicInfo"] = "file returned"

    return result
end

Logging and Debugging

Diagnostic and logging information can be written to a task's error stream using OSX::NSLog().

# send log value to stderr
OSX::NSLog("Goodbye, kosmos!")

NSObject Subclassing

Ruby objects can be subclassed directly from Cocoa's NSObject.

require 'osx/cocoa'

class KosmicTask < OSX::NSObject

    #
    # task entry point
    #
    def kosmictask()
        return "Hello, kosmos!"
    end
end

Runloop Management

When an Ruby Cocoa task is run the script runner is transformed into a fully fledged application complete with a run loop (an instance of NSRunLoop). This enables the task to utilise all the features of the Cocoa framework, many of which depend upon the existence of a run loop in order to perform correctly. As a result of its application based nature a task written in RubyCocoa will probably take longer to launch and consume more system resources than a regular Ruby task.

By default however the RubyCocoa task will exit its run loop whenever the task entry point exits unless it is requested to do otherwise. This is the case in the example above.

In order for the task to continue executing it is necessary to tell the task controller object (KosmicTaskController ) to keep the task running after the script entry point function has returned. KosmicTaskController is a predefined class that can be accessed within the task script by using the statement $taskController = OSX.NSClassFromString("KosmicTaskController").

To keep the task running call the KosmicTaskController keepTaskRunning static method. The task will then continue to process input events on its runloop until the KosmicTaskController stopTask_ static method is called. The task will then end and return its result to the client.

require 'osx/cocoa'

# KosmicTask controller
$taskController = OSX.NSClassFromString("KosmicTaskController")

class KosmicTask < OSX::NSObject

    #
    # task entry point
    #
    def kosmictask()

        OSX::NSTimer.scheduledTimerWithTimeInterval_target_selector_userInfo_repeats_(2, self, :timerFired, nil, true)

        # keep task running
        $taskController.keepTaskRunning()
    end

    #
    # task timer expired
    #
    def timerFired(timer)

        timer.invalidate()

        # stop the task
        $taskController.stopTask_("timer expired")
    end
end

System Framework Access

Ruby Cocoa tasks can access system frameworks using the statement OSX.require_framework "theFramework".

require 'osx/cocoa'

OSX.require_framework "AddressBook"

def kosmictask()

    person = OSX::ABAddressBook.sharedAddressBook().me()
    firstName = person.valueForProperty_(OSX::KABFirstNameProperty)

    return firstName
end

Ruby appscript

See the Ruby Usage document.