Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/HackPlan/quark-shell-mac

Quark Shell for Mac helps web developers to create native-like Mac menubar app using HTML and JavaScript without writing any native code.
https://github.com/HackPlan/quark-shell-mac

mac menubar webkit

Last synced: 18 days ago
JSON representation

Quark Shell for Mac helps web developers to create native-like Mac menubar app using HTML and JavaScript without writing any native code.

Awesome Lists containing this project

README 

        
# Quark Shell for Mac



**Quark Shell** helps you create cross-platform (currently Mac-only, Windows version coming soon) menubar/tray app using HTML and JavaScript without writing any native code. Quark Shell exposes a JavaScript object called ``quark`` to provide system functions. **Quark Shell for Mac** is based on WebKit.



Screenshot



## 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:



0. Delete the current ``app`` folder

0. Put your files into ``app`` folder

0. Open ``quark-shell.xcworkspace`` in Xcode

0. Change bundle name and bundle identifier (see [Issue #50](https://github.com/HackPlan/quark-shell-mac/issues/50) for details)

0. Build and have fun!



Remember that Quark Shell is still a WIP. When the project is stable enough, the build process will be simplified.



## API



APIs may change rapidly before 1.0.



```js

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



// App info (configurable in Xcode)

quark.appVersion

quark.appBundleVersion



// Enable/disable Web Inspector

quark.debug = true



// Manipulate the popup window

quark.openPopup()

quark.closePopup()

quark.togglePopup()

quark.resizePopup({width: 326, height: 623})



// Quit application

quark.quit()



// Open URL in default browser

quark.openURL("https://pomotodo.com/")



// Set menubar icon

quark.setMenubarIcon("data:image/png;base64,iVBORw...SuQmCC")

quark.setMenubarHighlightedIcon("data:image/png;base64,iVBORw...SuQmCC")

quark.resetMenubarIcon()



// Set menubar icon click action

quark.setClickAction(function () { console.log("Don’t click me!"); })

quark.setSecondaryClickAction(function () { console.log("What did I say?"); })



// Set menubar label

quark.setLabel("03:14 AM")



// Auto launch at login

// You also need to change bundle identifier "com.hackplan.quark-shell-helper" to a proper one in quark-shell-helper.xcodeproj and QSHWebViewDelegate.m

quark.setLaunchAtLogin(true)



// Send system notification

quark.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

quark.removeAllScheduledNotifications()



// Remove all delivered notifications from notification center

quark.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.

quark.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

quark.closeWindow()



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

quark.pin()

quark.unpin()



// Exchange messages between webviews

quark.emit("MessageName", "payload")

quark.on("MessageName", function(message) {

	console.log(message)

})



// Show a context menu

quark.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



```js

// Set global keyboard shortcut

quark.addKeyboardShortcut({

  keycode: 0x7A, // F1 key

  modifierFlags: 0, // no modifier key

  callback: function suchCallback() {

    console.log("wow")

    quark.togglePopup()

  }

})



// Clear global keyboard shortcut

quark.clearKeyboardShortcut()

```



Please follow [NSEvent Class Reference](https://developer.apple.com/library/mac/documentation/Cocoa/Reference/ApplicationKit/Classes/NSEvent_Class/Reference/Reference.html#//apple_ref/doc/constant_group/Modifier_Flags) for documentation about modifier flags.



Also, Quark Shell for Mac allows you to record shortcuts via [native components in Preferences window](Docs/Preferences.md#native-components).



### Preferences



```js

quark.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 quark.setupPreferences()

quark.openPreferences()

quark.closePreferences()

```



Quark Shell for Mac also provides some native components for preferences.



More detail: [Preferences.md](Docs/Preferences.md)



### Auto Updating



```js

// Check for update

quark.checkUpdate("https://rawgit.com/HackPlan/quark-shell-mac/master/updater/SampleAppcast.xml")

quark.checkUpdateInBackground("https://rawgit.com/HackPlan/quark-shell-mac/master/updater/SampleAppcast.xml")

```



More detail: [AutoUpdate.md](Docs/AutoUpdate.md)



## FAQ

* Can I use **local storage**? Yes.

* Can I use **WebSQL**? Yes.

* Can I use **IndexedDB**? No, because we are using NSWebView. A future Yosemite-only version using WKWebView will support IndexedDB.

* Is Quark Shell compatible with Mac App Store? Absolutely yes.



## Story



Quark Shell was originally Menubar WebKit. It was created for [Pomotodo for Mac](https://pomotodo.com/apps). Later on, we decided to create a Windows version based on Atom Shell. The project was highly inspired by [Atom Shell (now Electron)](https://github.com/atom/electron), [node-webkit (now nw.js)](https://github.com/nwjs/nw.js), and [MacGap](https://github.com/MacGapProject/MacGap1). As a cross-platform project, Menubar WebKit is no longer an appropriate name, so we started to use Quark Shell.



## Credits



**Quark Shell for Mac** was created by **[LIU Dongyuan (@xhacker)](https://github.com/xhacker)** in the development of [Pomotodo for Mac](https://pomotodo.com).



Some of the code are taken from:



* [MacGap](https://github.com/maccman/macgap) by [@maccman](https://github.com/maccman)

* [Bang](https://github.com/jesseXu/Bang) by [@jesseXu](https://github.com/jesseXu)

* [Cordova OS X](https://github.com/apache/cordova-osx) by [Apache](http://www.apache.org)



Used third-party libraries:



* [MASShortcut](https://github.com/shpakovski/MASShortcut) by [@shpakovski](https://github.com/shpakovski)

* [RHPreferences](https://github.com/heardrwt/RHPreferences) by [@heardrwt](https://github.com/heardrwt)

* [Sparkle](https://github.com/sparkle-project/Sparkle) by [contributors](https://github.com/sparkle-project/Sparkle/graphs/contributors)

* [StartAtLoginController](https://github.com/alexzielenski/StartAtLoginController) by [@alexzielenski](https://github.com/alexzielenski)



## Contribution



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



## License



MIT