Firefox/Projects/Tabcandy/CodeGuide

The Intro

Welcome to the TabCandy intro. We've crafted this introduction out of the finest quality bits and stopped at no extreme to make your stay as comfortable as possible. Most of what you need to know is described here http://bit.ly/97OooK. Enjoy!

TabCandy changes the behavior of the browser in various places, and it also has a UI screen of its own. The TabCandy UI is an HTML webpage that lives inside a xul:deck, and is composed of all new files. Other changes to the browser are patches to existing browser files.

== What to Review In What Order ==

(1) The Patch (see below)
(2) The new files (JS: in browser/base/content/tabcandy, CSS: browser/themes/.../tabcandy)
- priority 1:
- app/ui.js - Navbar, Tabbar, Page, UIClass management singletons
- core/mirror.js - mirroring tab thumbnails to the tab canvases
- app/items.js - superclass for Group and TabItem "classes"
- app/tabitems.js - management of visual tabs in the TabCandy UI
- app/groups.js - class for group objects
- app/storage.js - Storage singleton wrapper for session store
- core/iq.js - iQ: our stripped down, Moz-specific version of jQuery
- core/utils.js - Utils utilities and Subscribable mix-in for observer binding
- core/tabs.js - TabManager singleton and BrowserTab class for wrapping browser tabs
- priority 2:
- app/drag.js - behavior for tab and group dragging
- app/trench.js - "trenches" are regions to which tabs and groups "snap" while being moved.
- app/infoitems.js - the "Welcome to TabCandy" info box
- core/stacktrace.js - debugging code which could be removed (?)

== Patch (Changed Files) ==

There is around 18k of patch; the things we've changed in the Firefox code base. The rest of the code is new. You can find it here:

https://bugzilla.mozilla.org/show_bug.cgi?id=574217#c12

Main Browser UI
- Create a deck in the browser.xul which contains all browser elements and the TabCandy iframe so it can switch between the main browser UI and TabCandy interface.
- A toolbar button is added to the tabstrip and placed on the left of 'All Tabs' button in the default set.
- A menu item is added to the 'View' menu.
Modified file: browser-sets.inc, browser-menubar.inc, browser.xul, browser.js

Window Title
- Show TabCandy title when user is in the tab candy interface.
Modified file: tabbrowser.xml

Tabs vs Visible Tabs
- Enable the bookmark all menu items when there are more than one visible tab on the tabstrip using the TabSelect and TabMove listeners.
Modified file: browser.js

- Allow users to bookmark all visible tabs instead of all tabs.
Modified files: browser-places.js

- Disable some menu items on the right-click context menu when there is only one visible tab on the tabstrip.
Modified file: browser.js

- Warns about how many visible tabs would be closed when using close other tabs feature.
Modified file: tabbrowser.xml

- Remove all visible tabs except the selected on.
Modified file: tabbrowser.xml

- Reload only the visible tabs rather than all tabs.
Modified file: tabbrowser.xml

- Check the visible tab's width to determine whether to display the close button on Tabs or not because some of the tabs are collapsed and their widths aren't relevant
Modified file: tabbrowser.xml

- Show only the visible tabs on the 'All tabs' button menu popup.
Modified file: tabbrowser.xml

Session Store
- Hide all the restored tabs and tab candy would display the appropriate visible tabs.
Modified file: nsSessionStore.js

TabSelect event
- TabSelect is no longer fired after certain steps. A try/catch block is used to catch an error for the TabSelect to work. See this bug more details: https://bugzilla.mozilla.org/show_bug.cgi?id=578147
Modified file: tabbrowser.xml

Remove last tab
- Last tab can be removed in the TabCandy interface so an extra condition is added to check the existence of the previousSibling of a tab when adding a new tab.
- Prevent clsoing the browser window when user is in the TabCandy interface and closes the last tab.
Modified file: tabbrowser.xml

== The New Files ==

The base directory for TabCandy lives at browser/base/content/tabcandy; this includes the html file, the JavaScript and the platform-independant CSS. The platform-dependant CSS and the images live in the various platform theme folders (such as browser/themes/pinstripe/browser/tabcandy).

The TabCandy UI page is tabcandy.html in the TabCandy base directory. This page loads tabcandy.js, which is an #include of all of the remaining JavaScript files in that directory. The main structure of the TabCandy JavaScript is broken into two main areas: app and core. The core is dedicated to lower-level tab watching, utilities, thumbnail creation, etc., with tabs.js being the most low-level. App is the high-level UI code, with ui.js being the most high-level of all.

Documentation comments are throughout the code (though not complete yet), and are available as HTML here:

http://hg.mozilla.org/labs/tabcandy/raw-file/tip/content/doc/files2/app/ui-js.html

Most of the "app" code concerns itself with managing the visual representations of the user's tabs, along with the groups used to organize them. These representations all descend from in the Item class; tabs are TabItems and groups are Groups. To help out with the individual items there are also singleton objects for managing them all, called TabItems, Groups, and Items, respectively. An Item, whether it's a TabItem or a Group, keeps track of its bounds on screen internally, and updates various elements on the DOM to depict its location on screen.

Additional "app" code manages the browser's tab bar (hiding and showing items to conform to whatever group the user is in) and handles the animated transition between the TabCandy UI and individual tabs. Most of the former resides in ui.js and groups.js, with the latter in ui.js and tabitems.js.