API Documentation

Documentation for developing SailfishOS applications

EnterKey QML Type

Controls the appearance and behaviour of the Enter key in the software input panel More...

Import Statement: import Sailfish.Silica 1.0

List of all members, including inherited members

Properties

enabled : bool
highlighted : bool
iconSource : url
text : string

Signals

onClicked()

Detailed Description

The EnterKey attached property exposes properties to control the appearance and behavior of the Enter key in the software input panel.

In Sailfish OS, when a page displays a series of one-line text fields, pressing the Enter key when a text field has keyboard focus should move the focus from one field to the next, or close the keyboard if the field is the last (or only) text field on the page. Also, the icon for the Enter key in the on-screen keyboard should change depending on the behavior to be applied.

Here is an example with three text fields that configures the appearance and behavior of the Enter key in this manner:

 import QtQuick 2.2
 import Sailfish.Silica 1.0

 Dialog {
     Column {
         width: parent.width

         DialogHeader {}

         TextField {
             width: parent.width
             placeholderText: "First name"
             label: placeholderText

             // Only allow Enter key to be pressed when text has been entered
             EnterKey.enabled: text.length > 0

             // Show 'next' icon to indicate pressing Enter will move the
             // keyboard focus to the next text field in the page
             EnterKey.iconSource: "image://theme/icon-m-enter-next"

             // When Enter key is pressed, move the keyboard focus to the
             // next field
             EnterKey.onClicked: lastNameField.focus = true
         }

         TextField {
             id: lastNameField

             width: parent.width
             placeholderText: "Last name"
             label: placeholderText

             EnterKey.enabled: text.length > 0
             EnterKey.iconSource: "image://theme/icon-m-enter-next"
             EnterKey.onClicked: emailField.focus = true
         }

         TextField {
             id: emailField

             width: parent.width
             placeholderText: "Email"
             label: placeholderText

             EnterKey.enabled: text.length > 0

             // Show 'next' icon to indicate pressing Enter will close the
             // on-screen keyboard
             EnterKey.iconSource: "image://theme/icon-m-enter-close"

             // When Enter key is pressed, close the on-screen keyboard
             EnterKey.onClicked: focus = false
         }
     }
 }

The app may also choose to perform some other action when the Enter key is pressed for the last field. For example, if the above page was used to create an account using the given details, pressing Enter in the last field could accept the dialog in order to create an account:

 Dialog {
     id: dialog

     Column {
         // [code for DialogHeader and two text fields]

         TextField {
             id: emailField

             width: parent.width
             placeholderText: "Email"
             label: placeholderText

             EnterKey.enabled: text.length > 0
             EnterKey.iconSource: "image://theme/icon-m-enter-close"

             // When Enter key is pressed, accept the dialog
             EnterKey.onClicked: dialog.accept()
         }
     }

     // when the dialog is accepted, create the account
     onAccepted: createAccount()
 }

Property Documentation

enabled : bool

The Enter key is enabled if this is true. This can be used to disable the Enter key until valid input is given.

The default value is true.

highlighted : bool

The Enter key is highlighted if this is true. This can be used to draw user attention to the Enter key when a certain condition is met and the user can move forward.

The default value is false.

iconSource : url

Replaces the Enter key's label with an icon from the given file path.

Icons supported by the theme:

"image://theme/icon-m-enter-close" - Enter key will close the keyboard
"image://theme/icon-m-enter-next" - Enter key will move focus to the next text editor
"image://theme/icon-m-enter-accept" - Enter key will trigger action, e.g. accept a dialog

For example, this uses the "next" icon from the Jolla theme.

 import QtQuick 2.2
 import Sailfish.Silica 1.0

 TextField {
     width: parent.width
     placeholderText: "First Name"

     EnterKey.enabled: text.length > 0
     EnterKey.iconSource: "image://theme/icon-m-enter-next"
     EnterKey.onClicked: lastName.focus = true
 }

text : string

Set this property to override the Enter key's text. Note that the Enter key size varies and the text may not fit if it is long.

Signal Documentation

onClicked()

This signal handler is called if the user clicks on the software input panel's Enter key or the hardware keyboard's Return or Enter key.