FireTray/README.md

Firetray
=======

Overview
--------

Js-ctypes rewrite of the binary XPCOM version of **Firetray**.

Features
--------

* for all applications:
  * show/hide a single or all windows
  * restore windows to their previous state, position, size
  * restore each window to its original virtual desktop/workspace
  * activate restored windows
  * hide to tray on close
  * hide to tray on minimize
  * start minimized to tray
  * show icon only when hidden to tray
  * mouse scroll on tray icon shows/hides
  * GTK-themable icons
  * StatusNotifierItem support (can be disabled by `with_appindicator` hidden pref)
  * customizable tray icons
  * popup menu (show/hide individual windows, open new windows, quit)
  * command-line `-firetrayShowHide` option (useful for window manager's keyboard shortcuts)
  * command-line `-firetrayPresent` option (activates windows)
  * middle click on the tray icon activates last registered window

* for mail applications:
  * display unread message count in tray icon
  * display biff in tray icon for new messages
  * include/exclude mail accounts to/from messages count
  * include/exclude folders types to/from messages count
  * count in sub-folders recursively
  * handle [Exquilla](https://addons.mozilla.org/fr/thunderbird/addon/exquilla-exchange-web-services/) accounts
  * restrict message count to favorite folders
  * trigger external program on message count change

* for applications embedding chat (currently only Thunderbird)
  * display additional system tray status icon


Notes
-----

* Under Linux:
  * GTK+ 2.20+ required.
  * libappindicator3 can be used for StatusNotifierItem (KDE, Unity).
* Under Windows, few features are not yet implemented.
* Firetray temporarily unsets:
  * the `tabs.warnOnClose` built-in preference, which otherwise disrupts the handeling of the close event
  * `mail.biff.show_tray_icon` for mail applications
* Experimental non-customizable keyboard shortcut for hiding all windows set to: `accel-shift-w`

References
----------

* if you're looking for other mozilla-desktop integration:
  * Paul Neulinger's [Gnome-shell-Thunderbird integration](https://github.com/tanwald/gnome-shell-extension-thunderbird-integration "gnome-shell-thunderbird integration")
  * Mike Conley's
    [Unity-Thunderbird integration](http://mozillalabs.com/messaging/messaging-menu/
    "Unity-Thunderbird integration")
  * discontinued [Mozilla New Mail Icon (Biff)](https://addons.mozilla.org/fr/thunderbird/addon/new-mail-icon/)

* [Alltray](http://alltray.trausch.us/ "alltray") launches any applications
  into tray

KNOWN BUGS
----------

* windows aren't restored with the same z-order, but there is [no means to correct that under Linux](https://bugzilla.mozilla.org/show_bug.cgi?id=156333 "GetZOrderDOMWindowEnumerator is broken on Linux")

* notifications for excluded mail account servers are not
  disabled. Newmailalerts are
  [hard-coded](http://mxr.mozilla.org/comm-central/find?string=content/newmailalert)
  and we can't easily disable them on a per-server basis (only globally, see
  `mail.biff.show_alert`). The proper way would probably be to disable default
  notifications globally, and handle notifications ourselves. This is out of
  the scope of this addon, but you may want to give a try to the
  [MailAlert extension](https://addons.mozilla.org/en-US/thunderbird/addon/mailbox-alert/)

* child windows (compose message, preferences, ...)  are not handled by
  Firetray. For ex., they are not hidden along with there top-level window.

* because of `getNumNewMessages()`'s
  [strange behaviour](https://bugzilla.mozilla.org/show_bug.cgi?id=727460),
  it's impossible to display an accurate count of *new messages*. The best we
  can do is display a biff icon.

* POP users should set
  [http://kb.mozillazine.org/Thunderbird_:_FAQs_:_Automatically_Download_Messages](Automatically
  download new messages) to see new message. See
  [this discussion](https://github.com/foudfou/FireTray/issues/20).

* some features [do not work well under Unity/Compiz](https://github.com/foudfou/FireTray/issues/22).

Acknowledgment
--------------

* Some code borrowed from [Mike Conley](http://mzl.la/messagingmenu "Thanks Mike").
* Some code borrowed from
  [Nils Maier](https://addons.mozilla.org/fr/firefox/addon/minimizetotray-revived/
  "MinToTrayR addon page").
* kind support from Neil Deaking, Bobby Holley
* default icons borrowed from Mozilla, Pidgin, Tango Desktop Project
FireTray v0.4.0a2 2011-09-24 06:00:31 -04:00			`Firetray`
* refactor handeling of 'close_hides': eventListeners("close") never removed from windows. Pros: reads much simpler. Cons: unnecessary eventListeners (but not harmful either). * experimental kb shortcut for hiding all windows (whatever the value of 'close_hises') * bumped to version 8.* (FF, TB) 2011-08-27 21:35:55 -04:00			`=======`
* remember and correct window positions when hiding/showing * fix: prevent multiple handler/icon creations * closing a window hides all windows * add option for 'close_hides' (work in progress) 2011-08-15 16:39:25 -04:00
* refactor handeling of 'close_hides': eventListeners("close") never removed from windows. Pros: reads much simpler. Cons: unnecessary eventListeners (but not harmful either). * experimental kb shortcut for hiding all windows (whatever the value of 'close_hises') * bumped to version 8.* (FF, TB) 2011-08-27 21:35:55 -04:00			`Overview`
			`--------`

FireTray v0.4.0a2 2011-09-24 06:00:31 -04:00			`Js-ctypes rewrite of the binary XPCOM version of Firetray.`
* refactor handeling of 'close_hides': eventListeners("close") never removed from windows. Pros: reads much simpler. Cons: unnecessary eventListeners (but not harmful either). * experimental kb shortcut for hiding all windows (whatever the value of 'close_hises') * bumped to version 8.* (FF, TB) 2011-08-27 21:35:55 -04:00
* fix pref pane (UIOptions) * addon shutdown (close ctypes libs) on xpcom-will-shutdown * ctypes libs that import glib also export it so it can be closed later 2012-01-15 14:47:47 -05:00			`Features`
			`--------`

			`* for all applications:`
			`* show/hide a single or all windows`
update README, TODO 2012-03-16 05:26:25 -04:00			`* restore windows to their previous state, position, size`
			`* restore each window to its original virtual desktop/workspace`
			`* activate restored windows`
			`* hide to tray on close`
			`* hide to tray on minimize`
			`* start minimized to tray`
			`* show icon only when hidden to tray`
			`* mouse scroll on tray icon shows/hides`
update README 2012-05-13 10:23:43 -04:00			`* GTK-themable icons`
Add 'with_appindicator' hidden pref. This may be useful for StatusNotifierItem-ready environments which still support ICCCM/EWMH, whereby FireTray may be less limited. We'll just make it a hidden pref for now as the related UI is a nightmare. 2014-12-30 19:03:05 -05:00			* StatusNotifierItem support (can be disabled by `with_appindicator` hidden pref)
update README 2012-09-07 12:22:51 -04:00			`* customizable tray icons`
			`* popup menu (show/hide individual windows, open new windows, quit)`
update README 2012-12-14 04:40:38 -05:00			* command-line `-firetrayShowHide` option (useful for window manager's keyboard shortcuts)
			* command-line `-firetrayPresent` option (activates windows)
update README 2012-05-13 10:23:43 -04:00			`* middle click on the tray icon activates last registered window`
* fix pref pane (UIOptions) * addon shutdown (close ctypes libs) on xpcom-will-shutdown * ctypes libs that import glib also export it so it can be closed later 2012-01-15 14:47:47 -05:00
			`* for mail applications:`
update README 2012-05-13 10:23:43 -04:00			`* display unread message count in tray icon`
update README 2012-09-07 12:22:51 -04:00			`* display biff in tray icon for new messages`
update README, TODO 2012-03-16 05:26:25 -04:00			`* include/exclude mail accounts to/from messages count`
			`* include/exclude folders types to/from messages count`
update README.md 2012-04-08 19:58:21 -04:00			`* count in sub-folders recursively`
update README 2012-09-07 12:22:51 -04:00			`* handle [Exquilla](https://addons.mozilla.org/fr/thunderbird/addon/exquilla-exchange-web-services/) accounts`
			`* restrict message count to favorite folders`
			`* trigger external program on message count change`

			`* for applications embedding chat (currently only Thunderbird)`
			`* display additional system tray status icon`

* fix pref pane (UIOptions) * addon shutdown (close ctypes libs) on xpcom-will-shutdown * ctypes libs that import glib also export it so it can be closed later 2012-01-15 14:47:47 -05:00
* refactor handeling of 'close_hides': eventListeners("close") never removed from windows. Pros: reads much simpler. Cons: unnecessary eventListeners (but not harmful either). * experimental kb shortcut for hiding all windows (whatever the value of 'close_hises') * bumped to version 8.* (FF, TB) 2011-08-27 21:35:55 -04:00			`Notes`
			`-----`

Update README. 2014-12-30 18:56:42 -05:00			`* Under Linux:`
			`* GTK+ 2.20+ required.`
			`* libappindicator3 can be used for StatusNotifierItem (KDE, Unity).`
			`* Under Windows, few features are not yet implemented.`
Temporarily unset pref mail.biff.show_tray_icon for mail applications. 2014-05-23 16:03:46 -04:00			`* Firetray temporarily unsets:`
			* the `tabs.warnOnClose` built-in preference, which otherwise disrupts the handeling of the close event
			* `mail.biff.show_tray_icon` for mail applications
* refactor handeling of 'close_hides': eventListeners("close") never removed from windows. Pros: reads much simpler. Cons: unnecessary eventListeners (but not harmful either). * experimental kb shortcut for hiding all windows (whatever the value of 'close_hises') * bumped to version 8.* (FF, TB) 2011-08-27 21:35:55 -04:00			* Experimental non-customizable keyboard shortcut for hiding all windows set to: `accel-shift-w`

add unread messages counting facility (messaging-related) 2011-09-07 10:24:14 -04:00			`References`
			`----------`

* refactor handeling of 'close_hides': eventListeners("close") never removed from windows. Pros: reads much simpler. Cons: unnecessary eventListeners (but not harmful either). * experimental kb shortcut for hiding all windows (whatever the value of 'close_hises') * bumped to version 8.* (FF, TB) 2011-08-27 21:35:55 -04:00			`* if you're looking for other mozilla-desktop integration:`
			`* Paul Neulinger's [Gnome-shell-Thunderbird integration](https://github.com/tanwald/gnome-shell-extension-thunderbird-integration "gnome-shell-thunderbird integration")`
add unread messages counting facility (messaging-related) 2011-09-07 10:24:14 -04:00			`* Mike Conley's`
			`[Unity-Thunderbird integration](http://mozillalabs.com/messaging/messaging-menu/`
			`"Unity-Thunderbird integration")`
begin implementation for text icon 2011-09-09 16:14:40 -04:00			`* discontinued [Mozilla New Mail Icon (Biff)](https://addons.mozilla.org/fr/thunderbird/addon/new-mail-icon/)`
add unread messages counting facility (messaging-related) 2011-09-07 10:24:14 -04:00
			`* [Alltray](http://alltray.trausch.us/ "alltray") launches any applications`
			`into tray`
* refactor handeling of 'close_hides': eventListeners("close") never removed from windows. Pros: reads much simpler. Cons: unnecessary eventListeners (but not harmful either). * experimental kb shortcut for hiding all windows (whatever the value of 'close_hises') * bumped to version 8.* (FF, TB) 2011-08-27 21:35:55 -04:00
			`KNOWN BUGS`
			`----------`
* remember and correct window positions when hiding/showing * fix: prevent multiple handler/icon creations * closing a window hides all windows * add option for 'close_hides' (work in progress) 2011-08-15 16:39:25 -04:00
cleaning 2011-08-27 11:40:27 -04:00			`* windows aren't restored with the same z-order, but there is [no means to correct that under Linux](https://bugzilla.mozilla.org/show_bug.cgi?id=156333 "GetZOrderDOMWindowEnumerator is broken on Linux")`
* refactor handeling of 'close_hides': eventListeners("close") never removed from windows. Pros: reads much simpler. Cons: unnecessary eventListeners (but not harmful either). * experimental kb shortcut for hiding all windows (whatever the value of 'close_hises') * bumped to version 8.* (FF, TB) 2011-08-27 21:35:55 -04:00
update README/TODO about disbabling newmailalerts for excluded accounts 2011-11-27 21:52:41 -05:00			`* notifications for excluded mail account servers are not`
			`disabled. Newmailalerts are`
			`[hard-coded](http://mxr.mozilla.org/comm-central/find?string=content/newmailalert)`
typo + bump maxVersion for seamonkey 2012-02-03 16:25:40 -05:00			`and we can't easily disable them on a per-server basis (only globally, see`
update README/TODO about disbabling newmailalerts for excluded accounts 2011-11-27 21:52:41 -05:00			`mail.biff.show_alert`). The proper way would probably be to disable default
			`notifications globally, and handle notifications ourselves. This is out of`
			`the scope of this addon, but you may want to give a try to the`
			`[MailAlert extension](https://addons.mozilla.org/en-US/thunderbird/addon/mailbox-alert/)`
update README/TODO + bump maxVersion to 10.* for FF and TB 2011-11-24 17:12:13 -05:00
* fix UI updating when toggling hides_single_window, show_icon_on_hide * add popup menu items for hidden windows to be shown individually I'm not quite satisfied with the global design/partitioning of the code accross namespaces. Some ideas to explore: extract code related to the popup menu, don't "wrap" window-related function into the Handler. 2012-01-20 17:44:57 -05:00			`* child windows (compose message, preferences, ...) are not handled by`
			`Firetray. For ex., they are not hidden along with there top-level window.`

prevent usage of msg count with type 'new messages' There seems to be no consistent way to count new messages. Tried with 'BiffState', 'NumNewBiffMessages', 'NewMessages'... either the proper event is not fired, or the count is incorrect at a specific event... It was even non-trivial to display an accurate biff. 2012-02-20 18:09:40 -05:00			* because of `getNumNewMessages()`'s
			`[strange behaviour](https://bugzilla.mozilla.org/show_bug.cgi?id=727460),`
			`it's impossible to display an accurate count of new messages. The best we`
			`can do is display a biff icon.`

update README with pop3 comments 2012-03-22 13:38:30 -04:00			`* POP users should set`
			`[http://kb.mozillazine.org/Thunderbird_:_FAQs_:_Automatically_Download_Messages](Automatically`
			`download new messages) to see new message. See`
			`[this discussion](https://github.com/foudfou/FireTray/issues/20).`

bump to v0.4.2 2012-05-12 09:42:55 -04:00			`* some features [do not work well under Unity/Compiz](https://github.com/foudfou/FireTray/issues/22).`

* refactor handeling of 'close_hides': eventListeners("close") never removed from windows. Pros: reads much simpler. Cons: unnecessary eventListeners (but not harmful either). * experimental kb shortcut for hiding all windows (whatever the value of 'close_hises') * bumped to version 8.* (FF, TB) 2011-08-27 21:35:55 -04:00			`Acknowledgment`
			`--------------`

			`* Some code borrowed from [Mike Conley](http://mzl.la/messagingmenu "Thanks Mike").`
FireTray v0.4.0a2 2011-09-24 06:00:31 -04:00			`* Some code borrowed from`
update README with pop3 comments 2012-03-22 13:38:30 -04:00			`[Nils Maier](https://addons.mozilla.org/fr/firefox/addon/minimizetotray-revived/`
FireTray v0.4.0a2 2011-09-24 06:00:31 -04:00			`"MinToTrayR addon page").`
* fix openBrowserWindow() when called from GtkMenuItem * add openMailMessage() to popup menu * add start_hidden option * fix getXWindowDesktop() 2012-01-14 19:02:00 -05:00			`* kind support from Neil Deaking, Bobby Holley`
* convert tabbox/tabpanels to prefpanes (preference UI) (thx Tango for icons!) * change order of menu items for mail apps * fix hide chat prefs when non-chat app 2012-09-06 13:07:22 -04:00			`* default icons borrowed from Mozilla, Pidgin, Tango Desktop Project`