Skip to main content
Sign In

Assistive Technology Partners home page.

Assistive Technology Partners Banner Image
 

ClickReader Information for Developers


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

Inside of the ClickReader.xpi file are four directories as well as additional files.  The directories are chrome, which contains the majority of files which can be updated/changed for newer versions of ClickReader, defaults, which contains a directory called prefs that has one javascript file called cwu_ptr_Prefs.js that contains a list of preference variables for ClickReader, and xsl, which contains various xslt documents.  At the top level, there is also an install.rdf file for the ClickReader extension as well as a chrome.manifest file.  The chrome.manifest file defines the locations of the content, skin and locale directories as well as the location of the style and overlay documents for the extension; it should not need to be modififed.

The most important of all of these directories is chrome.  This directory contains three other directories: content, which contains all of the javascript and xul files for ClickReader, locale which contains files related to different language versioning and skin, which contains the icons for the ClickReader toolbar as well as a css file related to these icons.

Content Directory

The content directory contains the most important files for the ClickReader application.  One of these files is cwu.ptr.Browser.xul; it defines all of the elements of the user interface including right-click menu items, shortcut keys, the toolbar and all its buttons, declares all javascript files that must be included with the application and defines event actions for all user input(from right click menu items, button clicks, shortcut keys pressed, etc).  All of the labels and access keys for the menu items and toolbar buttons are implemented so that they can be easily translated to another language.  The actual US English text can be found in another file in the locale directory, as described below.

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.

Cwu_ptr_namespace.js  creates the global cwu_ptr namespace.   Cwu_ptr is short for Central Washington University Portable Textbook Reader, and the name is leftover from the modified PT Reader code.  This file should load first with the Overlay.xul so the namespace is available to the other Javascript objects.

Cwu_ptr_navigation.js contains methods which allow for navigation throughout the page.  These include going to the next paragraph(NextParagraph) or previous paragraph(PreviousParagraph).  It also contains a method called AutoRead, which recursively calls itself through the use of javascript timeouts to fake multithreading and reads the contents of the page.  The AutoRead function is eventually called through a series of other function calls when the Begin Speaking button is pressed, the item is selected from the context menu or when the shortcut key combination is pressed.

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 content directory contains another directory named prefs.  This directory contains files that are used when the user clicks on the ClickReader options/settings button.  Ptr-Prefwindow.xul defines the look and feel of the entire preferences dialog window.  There are other xul files which define the look of each tab or pane of the window, which can be changed by clicking on the corresponding icons on the top of the window.  These are Ptr-GeneralSettingsPreferences.xul, Ptr-HelpPreferences.xul and Ptr-VoicePreferences.xul.  There are also corresponding Javascript files for each of these xul files which contain methods related to responding to user interaction with the elements in the tabs as well as initializing each preference if it was previously changed and saved by the user.

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.

Locale Directory

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

ClickReader uses XPCOM as an interface between the javascript code in the CLC-TTS extension and the Windows native SAPI TTS engine.  When a new version of Firefox is released, a new version of XPCOM must be compiled for the extension.  Mozilla always releases a new version of the Gecko SDK(which contains the XPCOM interface code) each time a new version of Firefox is released.

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.

ctypes

It may be possible to rewrite the ClickReader extension in the future so that it doesn't require recompilation for new versions of Firefox by using ctypes in the javascript code.  Due to budget and time constraints, this has not been attempted.