Using the Multiple Accounts API
Auto Completion
By Scott MacGregor mscott@netscape.com and Jean-Francois Ducarroz ducarroz@netscape.comThis document is an intial straw man at a design for auto completion in seamonkey. Comments are greatly appreciated.
Design Goals and Overview
We want to design a new auto complete widget in conjunction with a set of auto completion APIs that would be generic enough to be used across applications such as mailnews compose (for entering email addresses) and in the browser (for completing urls in the url bar against session history, etc.). If we do it right, you should be able to declare an auto complete widget in your xul in conjunction with several attributes on that widget and everything else would just work! The application writer wouldn't have to write any extra JS or C++ code.
The auto complete engine is broken into 2 main components. The first is an auto complete widget. The second consists of a set of auto complete interfaces which need to be implemented by each auto complete search engine (i.e. mailnews, url history for the url bar, wallet, etc).
The Auto Complete Widget
Jean-Francois will fill this in more detail.....I'll take a quick stab at it.
The auto complete widget contains the text field the user can type in, displaying a blurr string for an exact auto completion match ontop of that text field. In addition, the widget will have the ability to create a menu popup containing a list of possible auto completion matches. The widget fires off two events: OnStartAutocomplete and OnStopAutoComplete. Every time an additional character is typed into the widget, it will fire an onStopAutoComplete to cancel any current auto complete searches. If the user hits return or
- timeout --> measured in ms. If the user pauses this long without typing an additional character, the widget will fire an OnStartAutoCompleteEvent.
- type --> The type of auto complete engine we want. Possible type values include: mailnewsCompose, wallet, sessionHistory, etc. the widget will use the type field to create an appropriate auto complete search engine under the covers.
In short, we can describe the auto complete widget in XBL which to my understanding will allow us to write JS associated with the attributes for the widget. This is where we can look at the type value for the widget and write the JS to instantiate an appropriate auto complete. XBL will also allow us to add our custom events as well. We need to think this out more.
Auto Complete Search Engine
Each auto complete search engine (mailnews compose, session history, etc) will implement the following auto complete session interface. The widget will fire events which will cause OnStartAutoComplete and OnStopAutoComplete to get called on the auto complete engine.
interface nsIAutoComplete : nsISupports
{
void onStartAutoComplete (in wstring aSearchText,
in nsIAutoCompleteResults aCurrentResults/* current search results */,
in nsISupports aContext,
in nsIAutoCompleteListener aListener);
void onStopAutoComplete ();
};
OnStartAutoComplete is given the current text we wish to auto complete against, a set of current search results and a listener which
we'll use to broadcast search results back to.
If the user types a few character and pauses, causing us to perform an auto complete search and then they type a few more characters, we would like reuse the orginal auto complete search results and just search within that subset. This is the purpose of the nsIAutoCompleteResults interface. It allows us to pass a collection of search results between the front end and the back end search engine. The interface will look something like:
interface nsIAutoCompleteResults : nsISupports
{
attribute wstring currentSearchText;
void addResult (in wstring);
void removeResult (in wstring);
wstring getResult (in long aResultToGet);
attribute long numberOfResults;
void clearResults();
/* we may also store information like the blurr string for a match in here */
};
We may also extend this interface to allow you to get an enumerator and then enumerate across the search results. Right now, you can
get the total # of matches and then extract each match one by one.
The auto complete listener will be implemented in JS that will be part of the XBL binding for the auto complete widget. If we do this design right, this should be the only implementation as the behavior should be generic across all instances of the auto complete widget.
interface nsIAutoCompleteListener : nsISupports
{
void onStartAutoComplete(in wstring aSearchText); // for progress purposes...we probably don't need this
void onStopAutoComplete(in nsIAutoCompleteResults, in long aStatus);
};
The JS implementation of the listener will take the search results and popuplate a menu popup if necessary in addition to setting
the blurr string on the auto complete widget.
Please comment!
Scott MacGregor Mon Mar 27 16:09:00 PDT 1999