How to Enable Split-View Input for Text Editors in Symbian Qt Apps: Difference between revisions

From Qt Wiki
Jump to navigation Jump to search
No edit summary
No edit summary
Line 3: Line 3:
Symbian^3 OS release has supported partial screen text input keyboard (also known as '''split-view input''') from the beginning but the initial release Symbian^3 didn't much take that into use. Later Symbian Anna and Belle releases' applications actually utilize the feature in most applications for text input. '''In Qt 4.7.4 the split-view input is also supported by the Qt''' implementation allowing '''extremely easy utilization''' of this feature in Qt applications.
Symbian^3 OS release has supported partial screen text input keyboard (also known as '''split-view input''') from the beginning but the initial release Symbian^3 didn't much take that into use. Later Symbian Anna and Belle releases' applications actually utilize the feature in most applications for text input. '''In Qt 4.7.4 the split-view input is also supported by the Qt''' implementation allowing '''extremely easy utilization''' of this feature in Qt applications.


Here's an example where touch input keyboards are closed:<br />[[Image:http://www.developer.nokia.com/Community/Wiki/images/4/46/Split-view_input_vkb_closed_60p.png |Example with editor but touch input keyboards are closed]]
Here's an example where touch input keyboards are closed:
[[Image:http://www.developer.nokia.com/Community/Wiki/images/4/46/Split-view_input_vkb_closed_60p.png |Example with editor but touch input keyboards are closed]]


By default Symbian opens full screen virtual keyboard when user taps an editor:<br />[[Image:http://www.developer.nokia.com/Community/Wiki/images/4/4b/Fullscreen_input_60p.png |Full screen input keyboard in Symbian]]
By default Symbian opens full screen virtual keyboard when user taps an editor:
[[Image:http://www.developer.nokia.com/Community/Wiki/images/4/4b/Fullscreen_input_60p.png |Full screen input keyboard in Symbian]]


By default the text input keyboard takes up the whole screen when active. Prior to Qt 4.7.4 release there has also been no way to enable the partial screen text input keyboard in Qt apps without hacking deep into Avkon land. Starting from Qt 4.7.4 supporting partial screen text input keyboard becomes much easier. Application just needs to define one application attribute to achieve that virtual keyboard changes to split-view input as presented in following screen shots:
By default the text input keyboard takes up the whole screen when active. Prior to Qt 4.7.4 release there has also been no way to enable the partial screen text input keyboard in Qt apps without hacking deep into Avkon land. Starting from Qt 4.7.4 supporting partial screen text input keyboard becomes much easier. Application just needs to define one application attribute to achieve that virtual keyboard changes to split-view input as presented in following screen shots:


[[Image:http://www.developer.nokia.com/Community/Wiki/images/6/6a/Split-view_input_vkb_open_60p.png |Split-view input keyboard in Symbian - portrait]]<br />[[Image:http://www.developer.nokia.com/Community/Wiki/images/0/00/Split-view_input_vkb_open_in_landscape_60p.png |Split-view input keyboard in Symbian - portrait]]
[[Image:http://www.developer.nokia.com/Community/Wiki/images/6/6a/Split-view_input_vkb_open_60p.png |Split-view input keyboard in Symbian - portrait]]
[[Image:http://www.developer.nokia.com/Community/Wiki/images/0/00/Split-view_input_vkb_open_in_landscape_60p.png |Split-view input keyboard in Symbian - portrait]]


Already Qt 4.7.3 defines an ApplicationAttribute flag &quot;Qt::AA_S60DisablePartialScreenInputMode&amp;quot;:http://doc.qt.nokia.com/4.7-snapshot/qt.html#ApplicationAttribute-enum for disabling partial screen input mode. By default the flag is set to true. In Qt 4.7.3 the flag has no effect, but starting from Qt 4.7.4 the flag can be used ''by setting it to false'' to enable partial screen keyboard for text editors.
Already Qt 4.7.3 defines an ApplicationAttribute flag "Qt::AA_S60DisablePartialScreenInputMode":http://doc.qt.nokia.com/4.7-snapshot/qt.html#ApplicationAttribute-enum for disabling partial screen input mode. By default the flag is set to true. In Qt 4.7.3 the flag has no effect, but starting from Qt 4.7.4 the flag can be used ''by setting it to false'' to enable partial screen keyboard for text editors.


Enabling the partial screen keyboard can be done simply by setting the ''Qt::AA_S60DisablePartialScreenInputMode'' flag to false somewhere in the main.cpp by calling ''QCoreApplication::setAttribute()'' in following way:
Enabling the partial screen keyboard can be done simply by setting the ''Qt::AA_S60DisablePartialScreenInputMode'' flag to false somewhere in the main.cpp by calling ''QCoreApplication::setAttribute()'' in following way:
Line 19: Line 22:
If the cursor of the input widget would get obscured by the partial screen keyboard when it opens, the widget is automatically moved so that the cursor will be visible on plaint Qt Quick (using QML) and C++ graphics view-based UIs. Text input widgets on QWidget-based UIs will not get moved automatically. Instead, the application will receive a resize event. Then it is up to the application to make sure that the input widget will not get obscured by the keyboard.
If the cursor of the input widget would get obscured by the partial screen keyboard when it opens, the widget is automatically moved so that the cursor will be visible on plaint Qt Quick (using QML) and C++ graphics view-based UIs. Text input widgets on QWidget-based UIs will not get moved automatically. Instead, the application will receive a resize event. Then it is up to the application to make sure that the input widget will not get obscured by the keyboard.


From the above screenshots from the &quot;attached example application&amp;quot;:http://www.developer.nokia.com/Community/Wiki/images/6/6e/Split-ViewKeyboardForQtAppInSymbian.zip which illustrate how the partial screen text input keyboard looks like, when enabled.
From the above screenshots from the "attached example application":http://www.developer.nokia.com/Community/Wiki/images/6/6e/Split-ViewKeyboardForQtAppInSymbian.zip which illustrate how the partial screen text input keyboard looks like, when enabled.


You can try out the new functionality with Qt 4.7.4 for Symbian which is already available as a beta target with the latest version of Qt SDK. Since all it takes to enable the partial screen text input keyboard is to add one line of code, it is easy to test if it will cause some issues in your application.<br />Qt 4.7.4 is not available in Smart Installer yet, so deploying partial screen text input-enabled applications to Nokia Store will need to wait some more time. However, since the flag that is needed to enable partial screen text input keyboard is available already in Qt 4.7.3, there should not be any harm in setting the ''Qt::AA_S60DisablePartialScreenInputMode'' to false already now.
You can try out the new functionality with Qt 4.7.4 for Symbian which is already available as a beta target with the latest version of Qt SDK. Since all it takes to enable the partial screen text input keyboard is to add one line of code, it is easy to test if it will cause some issues in your application.
Qt 4.7.4 is not available in Smart Installer yet, so deploying partial screen text input-enabled applications to Nokia Store will need to wait some more time. However, since the flag that is needed to enable partial screen text input keyboard is available already in Qt 4.7.3, there should not be any harm in setting the ''Qt::AA_S60DisablePartialScreenInputMode'' to false already now.


One additional thing to note is that at the moment the application must have SwEvent capability in order to support predictive text input in partial screen input mode. SwEvent is one of the 13 capabilities for which Nokia Publish offers &quot;free Symbian Signed certifications&amp;quot;:https://www.developer.nokia.com/Distribute/Packaging_and_signing.xhtml, so any publisher can safely take this capability into use once he/she obtains a valid developer certificate from Nokia Publish.
One additional thing to note is that at the moment the application must have SwEvent capability in order to support predictive text input in partial screen input mode. SwEvent is one of the 13 capabilities for which Nokia Publish offers "free Symbian Signed certifications":https://www.developer.nokia.com/Distribute/Packaging_and_signing.xhtml, so any publisher can safely take this capability into use once he/she obtains a valid developer certificate from Nokia Publish.


== Resources ==
== Resources ==


* &quot;Download example as source package&amp;quot;:http://www.developer.nokia.com/Community/Wiki/images/6/6e/Split-ViewKeyboardForQtAppInSymbian.zip
* "Download example as source package":http://www.developer.nokia.com/Community/Wiki/images/6/6e/Split-ViewKeyboardForQtAppInSymbian.zip


[[Category:HowTo]]
[[Category:HowTo]]

Revision as of 10:54, 25 February 2015

h1. How to Enable Split-View Input for Text Editors in Symbian Qt Apps

Symbian^3 OS release has supported partial screen text input keyboard (also known as split-view input) from the beginning but the initial release Symbian^3 didn't much take that into use. Later Symbian Anna and Belle releases' applications actually utilize the feature in most applications for text input. In Qt 4.7.4 the split-view input is also supported by the Qt implementation allowing extremely easy utilization of this feature in Qt applications.

Here's an example where touch input keyboards are closed: Example with editor but touch input keyboards are closed

By default Symbian opens full screen virtual keyboard when user taps an editor: Full screen input keyboard in Symbian

By default the text input keyboard takes up the whole screen when active. Prior to Qt 4.7.4 release there has also been no way to enable the partial screen text input keyboard in Qt apps without hacking deep into Avkon land. Starting from Qt 4.7.4 supporting partial screen text input keyboard becomes much easier. Application just needs to define one application attribute to achieve that virtual keyboard changes to split-view input as presented in following screen shots:

Split-view input keyboard in Symbian - portrait Split-view input keyboard in Symbian - portrait

Already Qt 4.7.3 defines an ApplicationAttribute flag "Qt::AA_S60DisablePartialScreenInputMode":http://doc.qt.nokia.com/4.7-snapshot/qt.html#ApplicationAttribute-enum for disabling partial screen input mode. By default the flag is set to true. In Qt 4.7.3 the flag has no effect, but starting from Qt 4.7.4 the flag can be used by setting it to false to enable partial screen keyboard for text editors.

Enabling the partial screen keyboard can be done simply by setting the Qt::AA_S60DisablePartialScreenInputMode flag to false somewhere in the main.cpp by calling QCoreApplication::setAttribute() in following way:

QCoreApplication::setAttribute(Qt::AA_S60DisablePartialScreenInputMode, false);

If the cursor of the input widget would get obscured by the partial screen keyboard when it opens, the widget is automatically moved so that the cursor will be visible on plaint Qt Quick (using QML) and C++ graphics view-based UIs. Text input widgets on QWidget-based UIs will not get moved automatically. Instead, the application will receive a resize event. Then it is up to the application to make sure that the input widget will not get obscured by the keyboard.

From the above screenshots from the "attached example application":http://www.developer.nokia.com/Community/Wiki/images/6/6e/Split-ViewKeyboardForQtAppInSymbian.zip which illustrate how the partial screen text input keyboard looks like, when enabled.

You can try out the new functionality with Qt 4.7.4 for Symbian which is already available as a beta target with the latest version of Qt SDK. Since all it takes to enable the partial screen text input keyboard is to add one line of code, it is easy to test if it will cause some issues in your application. Qt 4.7.4 is not available in Smart Installer yet, so deploying partial screen text input-enabled applications to Nokia Store will need to wait some more time. However, since the flag that is needed to enable partial screen text input keyboard is available already in Qt 4.7.3, there should not be any harm in setting the Qt::AA_S60DisablePartialScreenInputMode to false already now.

One additional thing to note is that at the moment the application must have SwEvent capability in order to support predictive text input in partial screen input mode. SwEvent is one of the 13 capabilities for which Nokia Publish offers "free Symbian Signed certifications":https://www.developer.nokia.com/Distribute/Packaging_and_signing.xhtml, so any publisher can safely take this capability into use once he/she obtains a valid developer certificate from Nokia Publish.

Resources