Skip to content

Latest commit

 

History

History
186 lines (136 loc) · 5.68 KB

README.md

File metadata and controls

186 lines (136 loc) · 5.68 KB
Raw

Menubar WebKit

menubar-webkit helps you create Mac menubar app using HTML and JavaScript without writing any Objective-C code. menubar-webkit exposes an JavaScript object called mw to provide system functions.

Screenshot

API

APIs may change rapidly before 1.0.

mw.platform // returns "mac" or "windows"

// App info (configurable in Xcode)
mw.appVersion
mw.appBundleVersion

// Enable/disable Web Inspector
mw.debug = true

// Open/close the popup window
mw.openPopup()
mw.closePopup()

// Quit application
mw.quit()

// Open URL in default browser
mw.openURL("http://pomotodo.com")

// Set menubar icon
mw.setMenubarIcon("data:image/png;base64,iVBORw...SuQmCC")
mw.setMenubarHighlightedIcon("data:image/png;base64,iVBORw...SuQmCC")
mw.resetMenubarIcon()

// Auto start with system
mw.setAutoStart(true) // not implemented yet

// Send system notification
mw.notify({
  title: "Pomotodo",
  content: "Break is over!",
  time: "2038-01-19T03:14:07Z", // (optional) delivery date for scheduled notification, in ISO 8601
  popupOnClick: true // popup when clicking notification
})

// Remove all scheduled notifications
mw.removeAllScheduledNotifications()

// Remove all delivered notifications from notification center
mw.removeAllDeliveredNotifications()

// Open new window
// "url" is relative to "app" folder
// Notice: You can only open one window at the same time,
// or the later window will replace the former window.
mw.newWindow({
  url: "about.html",
  width: 600,
  height: 400,

  // optional options
  x: 100, y: 100, // x and y should both be provided, "center" is also a valid value
  border: true, // whether the window has a border, default is true
  shadow: true, // whether the window has a shadow, default is true
  alwaysOnTop: false, // whether the window should always on top, default is false
  alpha: 1.0 // the alpha value of the window, between 0 and 1, default is 1.0
})

// Close new window
mw.closeWindow()

// Pin/unpin pop-up window (won’t close when click outside the window)
mw.pin()
mw.unpin()

// Exchange messages between webviews
mw.emit("MessageName", "payload")
mw.on("MessageName", function(message) {
	console.log(message)
})

// Show a context menu
mw.showMenu({
  items: [
    {label: "Test", click: function() { console.log("I am completely operational") } },
    {type: "separator"},
    {label: "Exit", click: function() { console.log("LIFE FUNCTION TERMINATED") } }
  ],
  x: 100,
  y: 200
])

Global Shortcuts

// Set global keyboard shortcut
mw.addKeyboardShortcut({
  keycode: 0x7A, // F1 key
  modifierFlags: 0, // no modifier key
  callback: function suchCallback() {
    console.log("wow")
    mw.openPopup()
  }
})

// Clear global keyboard shortcut
mw.clearKeyboardShortcut()

Please follow NSEvent Class Reference for documentation about modifier flags.

Also, Menubar Webkit allows you to record shortcuts via native components in Preferences window.

Preferences

mw.setupPreferences([
  {"label": "General",  "identifier": "general",  "icon": "NSPreferencesGeneral", "height": 192},
  {"label": "Account",  "identifier": "account",  "icon": "NSUserAccounts",       "height": 102},
  {"label": "Shortcut", "identifier": "shortcut", "icon": "NSAdvanced",           "height": 120}
])

// Must be called after mw.setupPreferences()
mw.openPreferences()
mw.closePreferences()

Menubar WebKit also provides some native components for preferences.

More detail: Preferences.md

Auto Update

// Check for update
mw.checkUpdate("https://rawgit.com/HackPlan/menubar-webkit/master/updater/SampleAppcast.xml")
mw.checkUpdateInBackground("https://rawgit.com/HackPlan/menubar-webkit/master/updater/SampleAppcast.xml")

More detail: AutoUpdate.md

Integrating Web App

app/index.html is the portal of your menubar app. app/preferences/[identifier].html are the preference pages (for example, app/preferences/general.html).

To build your app:

  1. Delete the current app folder
  2. Put your files into the app folder
  3. Install CocoaPods
  4. cd into the project folder and run pod install
  5. Open menubar-webkit.xcworkspace in Xcode
  6. Build and have fun!

Remember that Menubar WebKit is still a WIP. When the project is stable enough, I will definitely simplify the build process.

FAQ

  • Can I use local storage? Yes.
  • Can I use WebSQL? Yes.
  • Is Menubar WebKit compatible with Mac App Store? Absolutely yes.

Credits

Menubar WebKit was created by LIU Dongyuan (@xhacker) in the development of Pomotodo for Mac.

Some of the code are taken from:

Used third-party libraries:

Contribution

Pull requests are welcome! If you want to do something big, please open an issue first.

License

MIT