API Reference

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:

App:

// Quit application
macgap.app.terminate();

// Activate application (bring to front)
macgap.app.activate();

// Hide application
macgap.app.hide();

// Un-hide application
macgap.app.unhide();

// System bell
macgap.app.beep();

// Bounce Dock icon of applications
macgap.app.bounce();

// Open URL in default browser
macgap.app.open("http://google.com");

// Launch application
macgap.app.launch("TextEdit");

// Set a custom user agent string
macgap.app.setCustomUserAgent('new user agent string');

// Get the system idle time. This example outputs the idle time to the console once per second.
window.setInterval(function(){
	console.log( macgap.app.systemIdleTime() );
}, 1000);

Clipboard:

// 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();

Window:

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

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

// Get the window coordinates
macgap.window.getX();
macgap.window.getY();

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

// Toggle fullscreen mode
macgap.window.toggleFullscreen();

// Maximize the window
macgap.window.maximize();

// Minimize the window
macgap.window.minimize();

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

Path:

// Path to application
macgap.path.application;

// Path to application's resources
macgap.path.resource;

// Path to the current user's documents directory.
macgap.path.documents;

// Path to the app's library directory.
macgap.path.library;

// 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).
macgap.path.home;

// Path to the App's temp directory.
macgap.path.temp;

Dock:

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

Sound:

// Play a sound
macgap.sound.play("./my/sound.mp3")

// Play a system sound
macgap.sound.playSystem("funk");

Growl:

// Send a Growl notification
macgap.growl.notify({
  title: "Notify",
  content: "New Message!"
});

Notice:

// Send a Native User notification
macgap.notice.notify({
  title: "Notify",
  content: "New Message!"
});

Fonts:

// Return an array of installed font names
macgap.fonts.availableFonts();

// Return an array of installed font families
macgap.fonts.availableFontFamilies();

// Return the fonts in the given font family.
macgap.fonts.availableMembersOfFontFamily('Helvetica');

Events:

// 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 {
    console.log(e.data);
    var appName = e.data.localizedName;
    var bundleURL = e.data.bundleURL;
}, true);

Menus:

// Add a menu item.
macgap.menu.getItem("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.
macgap.menu.getItem("File").submenu().addSeparator();

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

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

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

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

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

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

User Defaults:

// Get an array of all user defaults keys. The value of each may be retrieved using one of the four getter functions described below.
macgap.userDefaults.getUserDefaultsKeys();

// Get all user defaults set previously by your MacGap JavaScript. Returns a JSON string.
macgap.userDefaults.getMyDefaults();

// example usage:
var defaults = JSON.parse( macgap.userDefaults.getMyDefaults() );

// 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.
macgap.userDefaults.getString('macgap_mykey');
macgap.userDefaults.getInteger('macgap_mykey');
macgap.userDefaults.getBool('macgap_mykey');
macgap.userDefaults.getFloat('macgap_mykey');

// Remove the user default for the specified key.
macgap.userDefaults.removeObjectForKey('macgap_mykey');

// Be notified when the user defaults are changed. To see what was changed, store a local snapshot of the object and compare to it. Only items with a key beginning with `macgap_` are returned, although any key may have triggered the event. For example, since the window's x,y position is stored in the User Defaults, this event will fire every time the app window is moved.
document.addEventListener('userDefaultsChanged', function(e) {
	console.log(e.data);
}, true);

When removing or setting user defaults from JavaScript, the provided key must be prefixed with macgap_. If this is ommitted the key 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.

They 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, and controlled directly from JavaScript.