NOTICE: Unfortunately due to changes in Firefox 15 and up, we are no longer able to update ClickReader. We are sorry to say that we no longer have the resources to update it. If anyone would like to do this, source code and documentation can be found below.
ClickReader began as a project called CLiCk Speak, which was developed by Charles Chen. Central Washington University then developed an extension called PT Reader, which used code from the original CLiCk Speak extension. ClickReader is based on both of these projects.
ClickReader is actually a bundle of three separate extensions: CLC-Utilites, CLC-TTS and ClickReader. CLC-Utilites and CLC-TTS were originally developed by Charles Chen and are largely unmodified. CLC-Utilities contains utility functions that are used to navigate the DOM, highlight text and other utility functions. CLC-TTS contains functions that allow for an interface between the operating system's native text-to-speech engine(SAPI in Windows and Apple TTS in Mac OS X). The well written documentation on his website for developers is still largely correct for these two extensions.
The ClickReader extension contains the code for the user interface and makes calls to each of the other two extensions to highlight the text as well as speak the current text. It also tracks mouse clicks and saves and loads users' prefernce variables to/from their profile.
ClickReader File Structure
Cwu_ptr_AtomicObject.js contains a set of variables which point to the current atomic object and the previous atomic object in the page’s DOM(document object model) and functions to manipulate that position(such as navigateForward, navigateBackward, moveAtomicObjectToCursor, etc) as well as functions to access properties of the current atomic object(such as isSpeakable). To quote Charles Chen’s CLC website “The term "Atomic Object" as I have used it in this document means a DOM-Obj that cannot be further subdivided. In other words, it is a DOM-Obj that has no child nodes or where the child nodes must not be treated individually (as in the case of MathML nodes where the children of the main "math" element must be considered in the context of the main "math" element and Select nodes where the Option elements under it only make sense in the context of being a choice in the Select box).”
Cwu_ptr_dom.js provides methods to interact with the DOM and objects that are part of the DOM. None of the methods in this file are called when a page is loaded. They are strictly used for access to and manipulation of the DOM, which is loaded by Firefox.
Cwu_ptr_events.js provides a method that is called whenever the mouse is clicked (mouseClickEventHandler) and also helps to track the current cursor position and if it has been altered by the user. It also contains a function (mouseClickInit) which is called each time a new page is loaded to add mouseclick listeners to that page.
Cwu_ptr_fetch.js contains methods to “fetch” atomic objects from the DOM. It is mostly used by the AtomicObject file, but is also used elsewhere.
The cwu_ptr_main.js file contains a method that is initially called from the browser.xul file to initialize the application (initialize_Reader). It also contains a method which is called each time a new page is loaded into the browser (pageLoadEventHandler), which then calls a function to initialize the page (initializePage). It also contains a method (shutdown) which is called when ClickReader is shut down (when the browser is closed).
Cwu_ptr_mathml.js is a set of functions that deal with speaking math ML content in the webpage. These methods have not been thoroughly tested and are left over from the PT Reader extension in case a user wants to read math ML content.
The cwu_ptr_preferences.js file contains variables that can be set by the user to affect the text to speech voice, such as speed, pitch, volume etc. It also contains methods which read the user’s configuration settings from disk, if they have previously saved any settings. The user can change these settings and variables by clicking on the options/settings button and using the ui which appears. There are also methods related to saving options or resetting all options. Another set of files which relates to the options window and related actions for this preference dialog can be found in the content\prefs directory.
Cwu_ptr_prefObserver.js contains methods which are used to watch if any of the preferences have changed and notify any listeners.
Cwu_ptr_sentence.js deals with the reading of an entire sentence and how to parse the text of the webpage into sentences. SpeakNextSentence is called to determine if there is a valid sentence to read and if there is, it will highlight the sentence (SelectSentence) and read it aloud (speakSentence). There is also a method for matching the current sentence with the cursor position.
The cwu_ptr_speakbutton.js file is called whenever the user requests for either the page to be read or a selection of text to be read. If the user clicks on the “Speak page” button the BeginSpeaking method is called, the speak button is hidden in the toolbar(by calling showPauseButton) and the pause button appears. When the reader finishes reading the page or when the user clicks on the pause button, the pause button is hidden and the speak page button reappears. Both of these buttons are always present in the toolbar, but in order to make it seem as though the button is changing, one is always hidden from view. The reading of the page is started by making a call to Navigation.AutoRead(). This file also contains a method(SpeakSelectedHtml) which is called when the user clicks on the Speak Selection button.
Cwu_ptr_tts.js contains methods related to starting the text-to-speech engine. These methods start the tts engine that is associated with the user’s operating system. The tts engine only needs to be initialized once each time the browser is started.
Cwu_ptr_utils.js contains several utility methods that are used by ClickReader, such as determining the user’s operating system and determining the installation directory of the application.
The cwu_ptr_WindowAdjust.js file contains methods for manipulating the browser window, such as adjusting the size of the window, scrolling the page so that the text which is being read shows on the screen, adjusting focus and highlighting text.
Under the content directory is another directory called modules. This directory contains files html.js and xhtml.js which are used to parse either an html or an xhtml file, respectively.
The icons directory under the prefs directory contains images of the icons that are displayed in the preferences window. It also contains a css file, ClickReader_prefWindow.css, which defines several styles that are used in the layout of the text in the preferences window; most of these styles are used in the Help pane.
The locale directory, located under the chrome directory, contains dtd files that are used to customize a Firefox extension for a specific locale. Most of the time, this will entail a translation of words used in the UI, but could also be used to account for cultural differences, such as the use of the metric or imperial system of measurement. In each of these dtd files, many entities are defined, which all contain strings. These entities and dtd files are referenced in separate xul files. For example, in the cwu.ptr.Browser.xul file, one of the first lines is <!DOCTYPE overlay SYSTEM "chrome://cwu_ptr/locale/ClickReader.dtd" >. This tells Firefox that wherever a reference to an entity exists in the xul file (ie &ClickReader.SubMenu.speak;) that its definition can be found in the given dtd file. Upon running the extension Firefox will substitute the entity found in the xul file with the proper string for the user’s preferred language (if possible).
Under the locale directory, there is one directory, en-us, which contains the United States English translation of ClickReader; in this directory there are two files. ClickReader.dtd contains all of the text, labels and accesskeys that are a part of the UI for ClickReader; specifically text and access keys for the ClickReader menu under the Firefox Tools menu, right-click context menus and the ClickReader toolbar. This file is referenced in the cwu.ptr.browser.xul.
ClickReader_preferences.dtd contains all labels and their associated accesskeys for everything contained in the preferences/options window. There are actually four separate xul files which use this one dtd file; they are located in the prefs directory and are named Ptr-prefWindow.xul, Ptr-GeneralSettingsPreferences.xul, Ptr-HelpPreferences.xul and Ptr-VoicePreferences.xul. This dtd file is commented to distinguish different portions of the preferences/options window and the corresponding files.
XPCOM and CLC.dll
The specific file which needs to be recompiled, CLC.dll, can be found in the components directory of the clc_tts extension. If this file is not recompiled for a new version of Firefox, the entire extension will not work and can even cause Firefox to become unresponsive and/or crash.
There are several steps that are necessary to generate the dll file. The first is to obtain a copy of the source code for the CLC Visual Studio C++ Project and copy it to the local hard drive. This source code is contained in a folder named CLC_sapi_dll_1.1_src. Inside of the project folder are many files, including CLC.sln and two directories named Release and Debug. After the project files have all been copied, open the CLC.sln file in Visual Studio.
In order to include this code with the DLL, a new version of the Gecko SDK must be downloaded from the following site: https://developer.mozilla.org/en/Gecko_SDK. There are several different versions available; the newest version for Windows should be downloaded and unzipped to the C:\gecko-sdk directory, which may need to be created.
The next step is to set several project options in Visual Studio. If all of the original project files have been copied correctly and they have been opened in the same version of Visual Studio, the following steps may have already been completed.
First, open the project properties dialog by going to the Visual Studio Project menu and clicking on “Properties”. Next, under the Configuration Properties section on the left part of the screen, expand the C/C++ category and then click on General. In the “Additional Include Directories” on the right part of the screen, type “C:\gecko-sdk\include”.
Similarly, expand the Linker category and then click on the General section. In the “Additional Library Directories” section add the bin and lib directories from the Gecko SDK, making sure that they are delineated by a semicolon, ie “C:\gecko-sdk\bin”;”C:\gecko-sdk\lib”.
Starting with Firefox 13, all binary components must use Address Space Layout Randomization(ASLR). “ASLR is an important defense-in-depth mechanism that makes it more difficult to successfully exploit a security vulnerability.”( http://blog.kylehuey.com/post/18120485831/address-space-layout-randomization-now-mandatory-for). The official Visual Studio documentation states that this option in Visual Studio “Specifies whether to generate an executable image that can be randomly rebased at load-time by using the address space layout randomization (ASLR) feature of Windows Vista.” (http://msdn.microsoft.com/en-us/library/bb384887%28v=vs.90%29.aspx)
To enable this feature in Visual Studio, click on the Advanced category under the Linker section of the Project Properties Window, as seen in the picture below. Next, set the Randomized Base Address to “Enable Image Randomization(/DYNAMICBASE)” by clicking on the dropdown menu. If this option is not selected, the extension will not work in Firefox 13 and up.
The last step to create the dll file is to simply build the project by selecting “Rebuild Solution” from the Build menu. The dll file will likely be created in the following location: CLC_sapi_dll_1.1_src\Debug\clc.dll. It could also be created in the Release directory, depending on the project’s configuration. Ensure that the date the file was last modified corresponds to the time when the project was built. After locating the newly created clc.dll file, it should be copied to the Components directory of the clc_tts extension.
There is one other file, CLC_SAPI.xpt, that is also part of the XPCOM interface. Normally, this file does not need to be updated for new versions of Firefox. However, if it does need to be updated, this file can be generated by using the xpidl.py file found in the \sdk\bin directory of the Gecko SDK. Instructions can be found on the Mozilla website at https://developer.mozilla.org/en/XPIDL/pyxpidl.