New PhoneGap feature: ActionSheet support

A while back David Roe had sent me a patch for an implementation of the ActionSheet control for PhoneGap. He was using it in an application of his, and probably due to my plea for patches from the PhoneGap community at large, he submitted this little tid-bit to me. Since I’ve been making some pretty big strides toward implementing a unified callback and event dispatch mechanism within PhoneGap, I refactored a bit of it, and created a generic Dialog class for PhoneGap.

Currently only button dialogs are supported, but in the future I’d like to create a variety of dialogs that PhoneGap application developers can use; date pickers, scroll picker widgets, and so forth. The API is as simple as I could make it, while still keeping in mind that other platforms may not have a native control to accomplish these features.

Basically I was thinking “What would I want to put in an action sheet”, and I came up with:

1. A list of buttons, maybe with different colours
2. A date / time picker, maybe with a different start date
3. A scroll-wheely value selector
4. ….

Here’s the desired API I came up with for a very complex usage:

dialog.openButtonDialog(
    {
        label: "First button",
        type: "default",
        onClick: function() { ... }
    },
    {
        label: "Second button",
        type: "cancel",
        onClick: function() { ... }
    }
)

which would result in the following GAP command:

gap://Dialog.openButtonDialog/First button/Second button?type_0=default&type_1=cancel&onclick_0=...

and so on. With the event callback system I built, the onclick handlers will be given their own callback ID if they’ve been specified. Additionally, the following syntax is supported as well, for more simple uses:

dialog.openButtonDialog(
    "First button",
    "Second button",
    {
        onClick: function(index, label) { ... }
    }
)

so you just give it a list of buttons, all shown as a default type, and the function would be called no matter what button was pressed.

This second form is necessary as you’d probably use it for the other types of action sheets:

dialog.openDatePicker(
    new Date("2009-02-14"),
    { onClick: function(newDate) { ... } }
);
dialog.openScrollPicker(
    "Value 1",
    "Value 2",
    "Value 3",
    { onClick: function(value) { ... } }
);

Those most recent examples aren’t implemented yet, but it shows how this particular class can be extended in the future. And they’re all potentially supported on other platforms as well.

Does all this sound reasonable? Please leave comments if you have any thoughts on the matter.

Check out the documentation of the Objective-C Dialog implementation, and the JavaScript Dialog interface to it. If you want to play with this before I push it into the official branch, you can try it in my experimental UIControls branch.