Architecture

components/avim.js

Defines a singleton XPCOM service, AVIM, that attaches an overlay to every window that is opened. There are a number of overlays corresponding to a particular application. (A distinction is made between each major overhaul of Firefox’s UI, because AVIM’s UI needs to go in different places.) In most cases, an application-specific overlay will load, in turn loading the overlay content/avim.xul, which includes two “chrome scripts”, content/avim.js and content/frame.js.

components/transformer.js

Defines the singleton XPCOM service AVIMTransformerService. It contains the core logic that modifies a word based on the selected input method. The service maintains no state across invocations of its sole method, applyKey(). This is the most opaque code in the extension, dating back to Hieu Dang’s AVIM script. Any help simplifying or documenting the logic would be appreciated. Other than the lastWordInString() function in content/frame.js, all Vietnamese-specific code is centralized in this file. Unfortunately, XPCOM scripts are evaluated in the system’s default text encoding (usually something like ISO Latin-1 or MacRoman), so all Vietnamese characters in string literals must be escaped.

content/avim.js

Manages AVIM’s basic UI: the toolbar button, status bar button, and menu items. It responds to the Ctrl key being pressed twice in a row (to toggle AVIM on and off). In Electrolysis windows, it loads content/frame.js once for every tab and acts as a message-based conduit between content/frame.js and AVIMTransformerService.

content/frame.js

It is loaded once per window as a “chrome script” and, in Electrolysis windows, once per tab process as a “frame script”. It responds to keypress events by editing the contents of the focused editor. For the built-in XUL and HTML plain text and rich text controls, it uses nsIEditor and related XPCOM components to talk directly to the internal editor machinery. For custom editors, such as online word processors, as well as for the script monitor, frame.js executes a dedicated “content script” in an unprivileged Sandbox. In all cases, frame.js relies on content/avim.js to relay data to and from AVIMTransformerService, because Electrolysis tab processes don’t load XPCOM components supplied by extensions.

content/editors/ directory

The content scripts live in the content/editors/ directory. A content script is intended to be called once per keystroke. It has direct access to Web content, so it must be locked down in an unprivileged context. The Silverlight content script is slightly different in that it registers its own keypress event handlers on individual plugin instances.

The Google Docs and Scintilla/SciMoz support scripts are lazily paged in when required. Because they don’t access Web content directly, they are loaded as privileged subscripts without the use of a Sandbox. They each define a function that is stored for the lifetime of frame.js and called repeatedly in response to keypress events.

Miscellany

There are separate XUL interfaces and scripts for the Options dialog (or Preferences window on the Mac) and any associated dialogs. The Mudim monitor is an overlay applied to about:addons; it displays a <notification> in the host tab when both AVIM and Mudim are enabled and turned on.