Skip to content
This repository

Desktop WebKit wrapper for HTML/CSS/JS applications.

branch: master


The MacGap project aims to provide HTML/JS/CSS developers an Xcode project for developing Native OSX Apps that run in OSX's WebView and take advantage of WebKit technologies. The project also exposes a basic JavaScript API for OS integration, such as display Growl notifications. The MacGap project is extremely lightweight and nimble, a blank application is about 0.3mb.


MacGap works on OSX 10.6 and 10.5.

Generate apps with the macgap generator, no compile necessary.

gem install macgap

macgap new myapp
macgap build myapp


MacGap exposes an object called macgap inside JavaScript. You can use it to alter the Dock icon and display Growl notifications, amongst other things. The API is documented below:


// Quit application;

// Activate application (bring to front);

// Hide application;

// Un-hide application;

// System bell;

// Bounce Dock icon of applications;

// Open URL in default browser"");

// Launch application"TextEdit");

// Set a custom user agent string'new user agent string');

// Get the system idle time. This example outputs the idle time to the console once per second.
    console.log( );
}, 1000);


// copy text to clipboard
macgap.clipboard.copy('this text will be copied to the clipboard');

// returns the contents of the clipboard
var clipboardContents = macgap.clipboard.paste();


// Open a new window{url:"public/index2.html", width: 400, height: 300});

// Resize window
macgap.window.resize({width: 400, height: 200});

// Get the window coordinates

// Move window (Bottom left is x:0 and y:0)
macgap.window.move({x:0, y: 200});

// Toggle fullscreen mode

// Maximize the window

// Minimize the window

// Return true if the window is currently maximized and false if it is not
var isWindowMaximized = macgap.window.isMaximized();


// Path to application

// Path to application's resources

// Path to the current user's documents directory.

// Path to the application's home directory. This is the application’s sandbox directory or the current user’s home directory (if the application is not in a sandbox).

// Path to the App's temp directory.


// Set the Dock's badge
macgap.dock.badge = "10";


// Play a sound"./my/sound.mp3")

// Play a system sound


// Send a Growl notification
  title: "Notify",
  content: "New Message!"


// Send a Native User notification
  title: "Notify",
  content: "New Message!"


// Return an array of installed font names

// Return an array of installed font families

// Return the fonts in the given font family.


// Mac OS X on wake event.
document.addEventListener('wake', function(){console.log('Wake!!')}, true);

// Mac OS X on sleep event.
document.addEventListener('sleep', function(){console.log('Sleep!!')}, true);

// Mac OS X app was activated.
document.addEventListener('appActivated', function(e {
    var appName =;
    var bundleURL =;
}, true);


// Add a menu item."File").submenu().addItem("Foo", "cmd+opt+g", function() { alert("Foo!"); })

// Menu item keyboard commands can include any of the following modifiers: caps, shift, cmd, ctrl, opt, alt

// Add a menu item separator."File").submenu().addSeparator();

// Remove a menu item or an entire menu."File").remove(); // Remove the file menu"File").submenu().getItem("Foo").remove(); // Remove the file menu's "foo" item

// Remove a menu item."File").submenu().getItem("Close").remove();

// Change the callback for a menu item."File").submenu().getItem("Foo").setCallback(function(){alert('Foo new');});

// Change the key command for a menu item."File").submenu().getItem("Foo").setKey('cmd-opt-ctrl-g');

// Change the title of a menu item."File").submenu().getItem("Foo").setTitle('Foonew');

// Add a new submenu for a menu item."File").submenu().getItem('Foo').addSubmenu().addItem("Foofoo", "cmd+opt+h", function() { alert("Foofoo!"); })

User Defaults:

// Get all user defaults. Returns a JSON string.

// example usage:

var defaults = JSON.parse( macgap.userDefaults.getUserDefaults() );

// Set the user default at the specified key. Objective-C is strongly typed, unlike JavaScript. For security, keys are automatically preceded with 'macgap.'. If this is omitted it will be added automatically. Thus the following two statements are functionally identical.

macgap.userDefaults.setString('macgap.mykey', 'mystring');
macgap.userDefaults.setString('mykey', 'mystring');

macgap.userDefaults.setInteger('macgap.mykey', 5);
macgap.userDefaults.setBool('macgap.mykey', 1);
macgap.userDefaults.setFloat('macgap.mykey', 12.345678);

// Get the user default for the specified key. Objective-C is strongly typed, unlike JavaScript.

// Remove the user default for the specified key.

// Be notified when the user defaults are changed. To see what was changed, store a local snapshot of the object and compare to it.
document.addEventListener('userDefaultsChanged', function(e) {
}, true);

User defaults added by JavaScript will be automatically namespaced by prefixing macgap.. This ensures it is not possible for JavaScript to modify or delete User Defaults which it did not create, as a security measure.

The User Defaults provide a large amount of interesting data that is now available to your JavaScript app.

It can also be used to implement an easy channel for communication between JavaScript and objects placed into the app using Interface Builder in Xcode eg Toolbars, buttons, preference windows. These can be bound directly to the User Defaults in Interface Builder, without writing any Objective-C code.

Offline Patterns

Desktop apps load immediately and work offline, whilst web apps have the advantage of being easily updated and remotely managed. MacGap gives you the best of both worlds via HTML5's offline APIs.

First you can define a refresh tag in index.html, which will immediately forward your WebView to a given address.

<meta http-equiv="refresh" content="0;url=">

Then use HTML5 offline APIs to cache your application locally. The first time your application launches, it'll download all the remote resources for use offline. Then during subsequent launches the locally cached resources will be used, and the application will fully function offline. If your remote application changes, then the cache manifest will be updated and application re-cached.


MacGap was forked/ported from Phonegap-mac. It's under the same license (MIT).

Custom Build

To build, make sure you have installed the latest Mac OSX Core Library. Download at

Just clone the repository and build in Xcode. The file public/index.html is loaded on startup.

Something went wrong with that request. Please try again.