--- a/src/hbcore/inputfw/hbinputeditorinterface.cpp	Fri Sep 17 08:32:10 2010 +0300
+++ b/src/hbcore/inputfw/hbinputeditorinterface.cpp	Mon Oct 04 00:38:12 2010 +0300
@@ -38,28 +38,124 @@
 #include "hbinpututils.h"
 
 /*!
-@alpha
+@stable
 @hbcore
 \class HbEditorInterface
-\brief An interface for accessing editor specific input attributes.
+\brief The HbEditorInterface class provides an interface for accessing
+editor-specific input attributes.
+
+HbEditorInterface is an interface for different editor widget types, which
+do not always derive from the same base classes. The interface defines
+a set of properties that applications can modify to constrain the input
+characters that the user can enter into an editor widget. %HbEditorInterface
+gives applications a common way of setting properties for both %Hb and %Qt editors
+(such as HbLineEdit, HbTextEdit, QLineEdit). The interface is also used in
+input method code.
+
+HbEditorInterface does not store the editor widget properties locally or
+duplicate them. Its memory footprint is very small. You can create as many
+interfaces to the same editor as you require for your application.
+The HbInput framework maintains only one copy of the editor attributes for
+each editor. All interface instances for an editor use those attributes.
+
+With HbEditorInterface, you can control, for example, the following editor attributes:
 
-This class is an interface for accessing and manipulating editor attributes, such as input mode, text case,
-constraints, input filter and so on. It also contains some useful convenience and utility methods.
-This interface is meant to be used from both client application and input method code.
+<ul>
+<li>text case: lower case, upper case, automatic</li>
+<li>input mode type: numeric, handwriting, ...</li>
+<li>input constraints: Latin only, auto-completing, ...</li>
+<li>input filter: digits only, input lower case, phone number, URL, ...</li>
+<li>editor class type: e-mail, URL, username, password, phone number, ...</li>
+<li>extra dictionary to be used in predictive text input</li>
+<li>smiley theme</li>
+<li>custom button for an editor-specific or application-specific action</li>
+</ul>
+
+The interface also contains useful convenience functions to define the type of data
+that the user can enter into an editor. The convenience functions set all the necessary
+attributes for some commonly used editor cases:
+
+<ul>
+<li>setUpAsCompletingEmailField()</li>
+<li>setUpAsCompletingUrlField()</li>
+<li>setUpAsLatinAlphabetOnlyEditor()</li>
+</ul>
+
+\section _usecases_hbeditorinterface Using HbEditorInterface
+
+\subsection _uc_001_hbeditorinterface Creating and using HbEditorInterface
+
+The following example shows how to create an editor interface, attach an editor
+to it, and use some attributes.
+
+\code
+QLineEdit *lineEdit = new QLineEdit;           // Create an editor
+HbEditorInterface editorInterface(lineEdit);   // Create an editor interface and attach lineEdit to it
+editorInterface.setTextCase(HbTextCaseUpper);  // Set text case to upper case
+\endcode
 
-Following example shows how to create editor interface, attach editor to it and use some attributes.
+If the attached editor is deleted, the editor interface will start to return
+the same values as when a null pointer is passed to the constructor.
+
+When any of the values is changed, a signal modified() is emitted.
+
+\subsection _uc_002_hbeditorinterface Using the convenience functions
+
+The following example shows how to use a convenience function for configuring
+your editor to be a URL field. The convenience function sets the required
+attributes necessary for URL input.
 
-\snippet{unittest_hbinputeditorinterface/unittest_hbinputeditorinterface.cpp,1}
+\code
+HbLineEdit *myLineEdit = new HbLineEdit;         // Create an editor
+HbEditorInterface editorInterface2(myLineEdit);  // Create an editor interface to it
+editorInterface2.setUpAsCompletingUrlField();    // Use the convenience function to set the editor as an URL field 
+\endcode
+
+\subsection _uc_003_hbeditorinterface Setting input constraints
+
+Input constraints in the HbInput framework are defined by the enumeration HbEditorConstraint,
+which is defined in the header file hbinputdef.h. You can set several input constraints
+at the same time in a bit vector HbEditorConstraints, as in the following example:
+
+\code
+HbLineEdit *mySearchField = new HbLineEdit;         // Create an editor
+HbEditorInterface editorInterface3(mySearchField);  // Create an editor interface to it
 
-If the attached editor is deleted, the editor interface will start to return same values
-as when a null pointer is passed to the constructor.
+// Use the input constraint function to set the editor as an auto-completing field
+// and to prevent the change of the input mode
+editorInterface3.setInputConstraints(HbEditorConstraintAutoCompletingField | HbEditorConstraintFixedInputMode);
+\endcode
+
+One useful constraint is HbEditorConstraintIgnoreFocus. By default, a virtual 
+keyboard is shown when an editor gets the focus. If you want to use the editor
+as a read-only viewer, or prevent the virtual keyboard from opening for some
+other reason, you can set the HbEditorConstraintIgnoreFocus constraint. It prevents
+the editor from getting a focus event, and the virtual keyboard is not shown.
 
-When any of the values is changed, signal modified() is emitted.
+Here is an example of setting HbEditorConstraintIgnoreFocus:
+\code
+HbSomeViewerPointer *myViewer;                // Pointer to some kind of editor in read-only mode, so it is a viewer 
+HbEditorInterface editorInterface4(myViewer);  // Create an editor interface to it (viewer does not have to be
+                                               // an editor for this to work as long as it is derived from QObject)
+
+// Instruct the input framework to ignore viewer focus events
+editorInterface4.setInputConstraints(HbEditorConstraintIgnoreFocus);  
+\endcode
+
+\note Note that there are also some common editor attributes that cannot be
+set with HbEditorInterface, such as disabling the predictive mode. To set this
+and other input method hints in application code, use your editor's %Qt base class
+function, either QGraphicsItem::setInputMethodHints(Qt::InputMethodHints hints) for
+%Hb editors, or QWidget::setInputMethodHints(Qt::InputMethodHints hints) for
+%Qt editors. In input method code, use
+HbInputFocusObject::setInputMethodHints(Qt::InputMethodHints hints).
+
+\sa HbLineEdit, HbTextEdit, HbAbstractEdit
 */
 
 
 /*!
-Constructs the object and attaches given editor.
+Constructor. Attaches the given editor to the interface.
 */
 HbEditorInterface::HbEditorInterface(QObject *editor)
 {
@@ -70,7 +166,7 @@
 }
 
 /*!
-Destructs the object.
+Destructor.
 */
 HbEditorInterface::~HbEditorInterface()
 {
@@ -78,7 +174,7 @@
 }
 
 /*!
-Returns text case. Returned value is HbTextCase
+Returns the text case.
 
 \sa setTextCase
 */
@@ -95,10 +191,9 @@
 }
 
 /*!
-Sets text case.
+Sets the text case.
 
 \sa textCase
-\sa HbTextCase
 */
 void HbEditorInterface::setTextCase(HbTextCase textCase)
 {
@@ -111,9 +206,9 @@
 }
 
 /*!
-Returns active editor input mode.
+Returns the active editor input mode.
 
-\sa setInputMode
+\sa setMode
 */
 HbInputModeType HbEditorInterface::mode() const
 {
@@ -128,9 +223,9 @@
 }
 
 /*!
-Sets active editor input mode.
+Sets the active editor input mode.
 
-\sa inputMode
+\sa mode
 */
 void HbEditorInterface::setMode(HbInputModeType inputMode)
 {
@@ -179,8 +274,8 @@
 }
 
 /*!
-Returns active input filter. The input framework will always run any text it produces
-through the active filter before it is committed into editor buffer.
+Returns the active input filter. The input framework will always run any input text
+through the active filter before committing the text into the editor buffer.
 
 In some cases, the input framework also automatically sets the filter to match
 input method hints. The default filter can still be overridden.
@@ -200,7 +295,13 @@
 }
 
 /*!
-Sets active input filter. The ownership is not transferred.
+Sets the active input filter. The ownership is not transferred.
+
+The input framework will always run any input text through the active filter
+before committing the text into the editor buffer.
+
+In some cases, the input framework also automatically sets the filter to match
+input method hints. The default filter can still be overridden.
 
 \sa filter
 */
@@ -215,8 +316,8 @@
 }
 
 /*!
-Returns local digit type setting. If this value is set, it will override device wide
-digit type setting.
+Returns the local digit type setting. If this value is set, it will override
+the device-wide digit type setting.
 
 \sa setDigitType
 */
@@ -234,7 +335,8 @@
 }
 
 /*!
-Sets local digit type.
+Sets the local digit type. If this value is set, it will override the device-wide
+digit type setting.
 
 \sa digitType
 */
@@ -249,21 +351,24 @@
 }
 
 /*!
-Adds action to this editor's list of actions on the first position.
+Adds \a action to this editor's list of actions on the first position.
 
-The action is used in virtual keyboards to define the application specific button. The
-keyboard will display a button using the text, icon and tooltip specified in the action.
+The action is used in virtual keyboards to define a custom button.
+The keyboard will display a button using the icon specified in the action.
 When the button is clicked, the action is triggered.
 
-If the action is already in the list, it will be removed before adding it again.
+If the action is already in the list, it will be removed before being added
+again.
 
-Hb input methods currently use only the first action in the list.
+%Hb input methods currently use only the first action in the list and display
+only the icon, not the text.
 Different input methods may display 0 or more than one button.
 
-Note that the custom button action is only a request to show it. Whether or not the
-virtual keyboard widget actually shows it depends on the situation and
-the active input method. That's why a function asigned to custom button should never
-be the only way to use a feature but only a shortcut.
+Note that the custom button action is only a request to show it. Whether
+or not the virtual keyboard widget actually shows the action depends on
+the situation and the active input method. That is why a function assigned
+to the custom button should never be the only way to use a feature, but
+only a shortcut.
 
 \sa insertAction
 \sa removeAction
@@ -275,8 +380,8 @@
 }
 
 /*!
-Inserts action to this editor's list of actions before the action before.
-If the action is already in the list, it will be removed before inserting it again.
+Inserts \a action to this editor's list of actions before the action \a before.
+If the action is already in the list, it will be removed before being inserted again.
 
 \sa addAction
 \sa removeAction
@@ -354,8 +459,8 @@
 }
 
 /*!
-Returns id value for attached extra user dictionary. Returns zero if no extra
-user dictinaries are attached to this editor.
+Returns the id value for the attached extra user dictionary. Returns zero if no extra
+user dictionaries are attached to this editor.
 
 \sa setExtraDictionaryId
 \sa HbUserDictionary
@@ -375,9 +480,9 @@
 }
 
 /*!
-Sets extra user dictionary id value. After setting this value those prediction
-engines that support extra dictionaries attach given dictionary to be
-part of prediction vocabulary.
+Sets the extra user dictionary id value. After setting this value those prediction
+engines that support extra dictionaries attach the given dictionary to be
+part of the prediction vocabulary.
 
 \sa extraDictionaryId
 \sa HbUserDictionary
@@ -394,7 +499,9 @@
 }
 
 /*!
-Returns editor class.
+Returns the editor class type.
+
+\sa setEditorClass
 */
 HbInputEditorClass HbEditorInterface::editorClass() const
 {
@@ -410,7 +517,9 @@
 }
 
 /*!
-Sets editor class.
+Sets the editor class type.
+
+\sa editorClass
 */
 void HbEditorInterface::setEditorClass(HbInputEditorClass editorClass)
 {
@@ -423,7 +532,7 @@
 }
 
 /*!
-Returns editor sepcific smiley theme.
+Returns the editor-specific smiley theme.
 
 \sa setSmileyTheme
 */
@@ -441,8 +550,8 @@
 }
 
 /*!
-Sets editor specific smiley theme. The smiley picker will display smileys provided
-by given theme.
+Sets the editor-specific smiley theme. The smiley picker will display smileys
+provided by \a theme.
 
 \sa smileyTheme
 */
@@ -457,7 +566,7 @@
 }
 
 /*!
-Finds and returns virtual keyboard host for this editor.
+Finds and returns a virtual keyboard host for the attached editor.
 */
 HbVkbHost *HbEditorInterface::vkbHost() const
 {
@@ -510,7 +619,8 @@
 }
 
 /*!
-Returns true if this instance is attached to same editor as given instance.
+Returns \c true if this instance is attached to the same editor
+as \a editorInterface.
 */
 bool HbEditorInterface::operator==(const HbEditorInterface &editorInterface) const
 {
@@ -518,7 +628,8 @@
 }
 
 /*!
-Returns true if this instance is not attached to same editor as given instance.
+Returns \c true if this instance is not attached to the same editor
+as \a editorInterface.
 */
 bool HbEditorInterface::operator!=(const HbEditorInterface &editorInterface) const
 {
@@ -526,7 +637,7 @@
 }
 
 /*!
-Returns pointer to the editor object this interface is attached to.
+Returns a pointer to the editor object attached to this interface.
 */
 QObject *HbEditorInterface::editor() const
 {
@@ -538,8 +649,9 @@
 }
 
 /*!
-Last focused state remembers the editor state exactly as it was when the focus is taken away. This is framework side
-API. There should never be need to use it from application code.
+The last focused state remembers the editor state exactly as it was when
+the focus was removed. This is for the framework side API, and there
+should never be need to call it from application code.
 
 \sa setLastFocusedState
 */
@@ -555,7 +667,8 @@
 }
 
 /*!
-Sets last focused state. This is framework side API, there should neever be need to call it from application code.
+Sets the last focused state. This is for the framework side API, and
+there should never be need to call it from application code.
 
 \sa lastFocusedState
 */
@@ -568,8 +681,10 @@
     }
 }
 
+
 /*!
-A convenience method for setting up the editor as completing email field.
+A convenience function for setting up the editor as an auto-completing
+e-mail address field.
 */
 void HbEditorInterface::setUpAsCompletingEmailField()
 {
@@ -583,7 +698,8 @@
 }
 
 /*!
-A convenience method for setting up the editor as completing url field.
+A convenience function for setting up the editor as an auto-completing
+URL field.
 */
 void HbEditorInterface::setUpAsCompletingUrlField()
 {
@@ -596,14 +712,17 @@
 }
 
 /*!
-A convenience method for setting up the editor as latin alphabet editor. In this mode, the input framework
-will use global input language if it is naturally capable of producing latin aplhabets. Otherwise
-it will switch locally to english language (is is assumed that english is always available).
-It is also recommended that prediction is disabled in latin only editors. That's because predictive mode in
-latin alphabet editor is controversial (which prediction database should be used if global language doesn't
-apply and we locally to switch to english? If we used english database, that would lead to situation
-where some global languages use their native prediction databases and some don't).
-That's why this method disables predictive input by default.
+A convenience function for setting up the editor as a Latin alphabet editor.
+In this mode, the input framework will use the global input language if
+it is naturally capable of producing Latin alphabets. Otherwise it will switch
+locally to English (is is assumed that English is always available).
+
+It is also recommended that prediction is disabled in Latin-only editors.
+That is because the predictive mode in a Latin alphabet editor is controversial:
+which prediction database should be used if the global language does not
+apply and we switch to English locally? Using the English database would lead
+to a situation where some global languages use their native prediction databases
+and some do not. To avoid this, the function disables predictive input by default.
 */
 void HbEditorInterface::setUpAsLatinAlphabetOnlyEditor()
 {
@@ -613,10 +732,12 @@
 }
 
 /*!
-Returns true if connected editor is configured to behave as numeric editor. In Qt 4.6 and beyond, numeric
-editors have one of these input method hints set: Qt::ImhDigitsOnly, Qt::ImhDialableCharactersOnly or Qt::ImhFormattedNumbersOnly.
-If either Qt::ImhLowercaseOnly or Qt::ImhUppercaseOnly is also set, then the editor is not numeric editor and
-this method returns false.
+Returns \c true if the connected editor is configured to behave as
+a numeric editor. In Qt 4.6 and beyond, numeric editors have one of these
+input method hints set: Qt::ImhDigitsOnly, Qt::ImhDialableCharactersOnly,
+or Qt::ImhFormattedNumbersOnly. If either Qt::ImhLowercaseOnly or
+Qt::ImhUppercaseOnly is also set, then the editor is not a numeric editor
+and this function returns \c false.
 */
 bool HbEditorInterface::isNumericEditor() const
 {
@@ -625,7 +746,7 @@
 }
 
 /*!
-Returns true if predictive input mode is allowed in attached editor.
+Returns \c true if the predictive input mode is allowed in the attached editor.
 */
 bool HbEditorInterface::isPredictionAllowed() const
 {
@@ -633,15 +754,29 @@
 }
 
 /*!
-Returns true if there is existing data record for given object. This method can
-be used for testing whether someone has set editor data for given object without
-creating a data record for it. This is usually not needed on application side.
+Returns \c true if there is an existing data record for \a object. This function can
+be used for testing whether someone has set editor data for a given object without
+creating a data record for it. This is usually not needed on the application side.
 */
 bool HbEditorInterface::isConnected(QObject *object)
 {
     return HbEditorInterfacePrivateCache::instance()->isConnected(object);
 }
 
+/*!
+ * \fn void HbEditorInterface::modified()
+ * 
+ * This signal is emitted when any of the editor settings is changed. 
+ */
+
+/*!
+ * \fn void HbEditorInterface::cursorPositionChanged(int oldPos, int newPos)
+ * 
+ * This signal is emitted when the cursor position in the attached editor
+ * is changed. 
+ */
+
+
 /// @cond
 
 void HbEditorInterface::backendModified()