You.i Engine
CYIKeyboardInputBridge Class Referenceabstract

Detailed Description

Provides access to the system software keyboard.

This class provides two-way communication with the system software keyboard. The software keyboard can be shown or hidden and this state can be queried. The current text and cursor position can also be set on the system keyboard, which is important if the platform provides suggestions or auto correct. Input can be received using the CYIKeyboardInputBridge::Receiver.

Note
Interaction with the software keyboard is provided automatically by using CYITextEditView.

An instance of this class must be obtained through CYIInputBridgeLocator.

See also
CYIInputBridgeLocator
CYITextEditView

#include <platform/YiKeyboardInputBridge.h>

Classes

class  Receiver
 Provides an interface to interact with the system software keyboard. More...
 

Public Types

enum  InputType {
  InputType::Text,
  InputType::TextWithoutSuggestions,
  InputType::Phone,
  InputType::Number,
  InputType::Email,
  InputType::URI,
  InputType::Password
}
 The preferred input type. More...
 
enum  ReturnKeyType {
  ReturnKeyType::Default,
  ReturnKeyType::Go,
  ReturnKeyType::Search,
  ReturnKeyType::Next,
  ReturnKeyType::Done
}
 The preferred return key type. More...
 
enum  InputModifiers {
  InputModifiers::None = 0x0,
  InputModifiers::NoSuggestions = 0x1,
  InputModifiers::MaskInput = 0x2
}
 The preferred modifiers for the platform keyboard. More...
 

Public Member Functions

 CYIKeyboardInputBridge ()
 
virtual ~CYIKeyboardInputBridge ()
 
void ResetKeyboard (Receiver *pSource)
 
virtual bool ShowKeyboard (Receiver *pSource)
 
virtual bool HideKeyboard ()
 
bool IsKeyboardShowing () const
 
bool IsHardwareKeyboardAvailable () const
 
void OnTextChanged (const CYIString &text, Receiver *pSource)
 
void OnCursorPositionChanged (size_t cursor, Receiver *pSource)
 
void OnCursorPositionWillChange (Receiver *pSource)
 
ReceiverGetCurrentReceiver ()
 
void ShowSelectionMenu (bool textSelected, YI_RECT rect)
 
void HideSelectionMenu ()
 

Public Attributes

CYISignal KeyboardShown
 
CYISignal KeyboardHidden
 

Protected Types

enum  KeyboardTextInputDirection {
  KeyboardTextInputDirection::LeftToRight,
  KeyboardTextInputDirection::RightToLeft,
  KeyboardTextInputDirection::Unknown
}
 The keyboard text input direction. More...
 

Protected Member Functions

virtual bool HasAccessoryImageSupport () const
 
virtual void AddAccessoryImageUrl (const CYIUrl &url)
 
virtual void RemoveAccessoryImageUrl (const CYIUrl &url)
 
virtual void ResetKeyboardInternal ()=0
 
virtual bool ShowKeyboardInternal (Receiver *pSource)=0
 
virtual bool HideKeyboardInternal ()=0
 
virtual bool IsKeyboardShowingInternal () const =0
 
virtual bool IsHardwareKeyboardAvailableInternal () const =0
 
virtual void OnCursorPositionWillChangeInternal ()=0
 
virtual void OnCursorPositionChangedInternal (size_t start, size_t end)=0
 
virtual void OnTextChangedInternal (const CYIString &rText)=0
 
virtual void ShowSelectionMenuInternal (bool textSelected, YI_RECT rect)=0
 
virtual void HideSelectionMenuInternal ()=0
 
virtual void OnKeyboardShown ()
 
virtual void OnKeyboardHidden ()
 
virtual void SetCurrentReceiver (Receiver *pReceiver)
 
virtual KeyboardTextInputDirection GetCurrentKeyboardTextInputDirection () const
 

Static Protected Member Functions

static CYIKeyboardInputBridge::KeyboardTextInputDirection GetDirectionFromLanguageCode (const CYIString &languageCode)
 

Protected Attributes

CYISignal< KeyboardTextInputDirectionKeyboardTextInputDirectionChanged
 

Member Enumeration Documentation

◆ InputModifiers

The preferred modifiers for the platform keyboard.

This bitmask may be used to tell the platform keyboard if it is expected to behave a particular way.

See also
CYITextEditView::GetInputModifiers
CYITextEditView::SetInputModifiers
Enumerator
None 

No modifiers are applied to the platform keyboard.

NoSuggestions 

The platform keyboard is expected to not display input suggestions to the user.

MaskInput 

Requests that the platform keyboard mask its input. This is distinct from CYITextEditView::EnablePasswordMode, which enables masking for the CYISceneView rather than the platform keyboard.

Note
Platform-specific notes:
  • Android mobile: There is no text to mask on the standard mobile keyboard layout. Text is displayed in the text field.
  • Fire TV: Numeric and Email types are not supported for input masking.
  • iOS: There is no text to mask on the standard mobile keyboard layout. Text is displayed in the text field. Masking on-screen keyboard input this way disables on-screen keyboard suggestions across all input views for the duration of the app.
  • Tizen: There is no text to mask on the standard Tizen keyboard layout. Text is displayed in the text field. Masking on-screen keyboard input this way disables on-screen keyboard suggestions across all input views for the duration of the app.
  • tvOS: Masking input this way on an Email field changes the on-screen keyboard to a standard tvOS text keyboard.

◆ InputType

The preferred input type.

This will alter the type of keyboard shown by the system, if applicable. Suggestions and auto-correct may also be affected.

Note
This does not directly affect the type of characters that can be input. The displayed keyboard may have a restricted character set but this is not guaranteed. Input from a hardware keyboard is always unrestricted.
See also
CYIKeyboardInputBridge::Receiver::GetInputType
Enumerator
Text 

Display a keyboard with a full character set and typical QWERTY layout. Suggestions and auto-correct are present if available on the platform.

TextWithoutSuggestions 
Deprecated:
This enum value is deprecated and may be removed in a future release. CYIKeyboardInputBridge::InputType::Text and CYITextEditView::SetInputModifiers should be used instead.

Display a keyboard with a full character set and typical QWERTY layout. Suggestions and auto-correct are off.

Phone 

Display a keyboard specialized for entering phone numbers. The displayed keyboard may also have a restricted character set. Suggestions and auto-correct are typically not present.

Number 

Display a keyboard specialized for entering numbers. The displayed keyboard may also have a restricted character set. Suggestions and auto-correct are typically not present.

Email 

Displays a keyboard specialized for entering email addresses. If suggestions or auto-correct are available they will be tailored for email addresses.

URI 

Displays a keyboard specialized for entering URIs. If suggestions or auto-correct are available they will be tailored for URIs.

Password 
Deprecated:
This enum value is deprecated and may be removed in a future release. CYITextEditView::SetInputModifiers should be used with another CYIKeyboardInputBridge::InputType instead.
Note
Does not automatically mask characters. CYIPasswordTextEditView must be used for masked input.
See also
CYIPasswordTextEditView

◆ KeyboardTextInputDirection

The keyboard text input direction.

This enum indicates the text direction based on the keyboard text input source language.

See also
CYIKeyboardInputBridge::GetCurrentKeyboardTextInputDirection
CYIKeyboardInputBridge::KeyboardTextInputDirectionChanged
Enumerator
LeftToRight 

Indicates Left to Right direction.

RightToLeft 

Indicates Right to Left direction.

Unknown 

Indicates that direction couldn't be determined.

◆ ReturnKeyType

The preferred return key type.

This will alter the type of return key to be used by the system keyboard, if applicable. It will also modify the behaviour when the return key is used.

See also
CYIKeyboardInputBridge::Receiver::GetReturnKeyType
CYIKeyboardInputBridge::Receiver::SetReturnKeyType
Enumerator
Default 

Display the system's default return key. The keyboard will be dismissed when pressed.

Go 

The keyboard will be dismissed when pressed.

Search 

The keyboard will be dismissed when pressed.

Next 

The system will attempt to activate the next input field. If there is no next field, the keyboard will be dismissed.

Done 

The keyboard will be dismissed when pressed.

Constructor & Destructor Documentation

◆ CYIKeyboardInputBridge()

CYIKeyboardInputBridge::CYIKeyboardInputBridge ( )

◆ ~CYIKeyboardInputBridge()

virtual CYIKeyboardInputBridge::~CYIKeyboardInputBridge ( )
virtual

Member Function Documentation

◆ AddAccessoryImageUrl()

virtual void CYIKeyboardInputBridge::AddAccessoryImageUrl ( const CYIUrl url)
protectedvirtual

Override to add a Url for creating an AccessoryImage.

◆ GetCurrentKeyboardTextInputDirection()

virtual KeyboardTextInputDirection CYIKeyboardInputBridge::GetCurrentKeyboardTextInputDirection ( ) const
protectedvirtual

Returns the current text input direction based on the keyboard input language.

Note
Will return Unknown if text input direction couldn't be determined.

◆ GetCurrentReceiver()

Receiver* CYIKeyboardInputBridge::GetCurrentReceiver ( )

Returns the current receiver of keyboard input, if there is one.

◆ GetDirectionFromLanguageCode()

static CYIKeyboardInputBridge::KeyboardTextInputDirection CYIKeyboardInputBridge::GetDirectionFromLanguageCode ( const CYIString languageCode)
staticprotected

Returns text direction based on the provided language code. languageCode is the ISO 639 code for the language.

◆ HasAccessoryImageSupport()

virtual bool CYIKeyboardInputBridge::HasAccessoryImageSupport ( ) const
protectedvirtual

Returns true if the platform supports displaying an image above the keyboard.

◆ HideKeyboard()

virtual bool CYIKeyboardInputBridge::HideKeyboard ( )
virtual

Request the system software keyboard be hidden. Returns true if the keyboard was sucessfully hidden.

◆ HideKeyboardInternal()

virtual bool CYIKeyboardInputBridge::HideKeyboardInternal ( )
protectedpure virtual

◆ HideSelectionMenu()

void CYIKeyboardInputBridge::HideSelectionMenu ( )

Call this to let the system hide a menu pertaining to the current selection.

◆ HideSelectionMenuInternal()

virtual void CYIKeyboardInputBridge::HideSelectionMenuInternal ( )
protectedpure virtual

◆ IsHardwareKeyboardAvailable()

bool CYIKeyboardInputBridge::IsHardwareKeyboardAvailable ( ) const

Returns true if a hardware keyboard is available.

◆ IsHardwareKeyboardAvailableInternal()

virtual bool CYIKeyboardInputBridge::IsHardwareKeyboardAvailableInternal ( ) const
protectedpure virtual

◆ IsKeyboardShowing()

bool CYIKeyboardInputBridge::IsKeyboardShowing ( ) const

Returns true if the software keyboard is currently showing.

◆ IsKeyboardShowingInternal()

virtual bool CYIKeyboardInputBridge::IsKeyboardShowingInternal ( ) const
protectedpure virtual

◆ OnCursorPositionChanged()

void CYIKeyboardInputBridge::OnCursorPositionChanged ( size_t  cursor,
Receiver pSource 
)

Call this to let the system keyboard know the current cursor positon has changed from the UI side. For example, as a result of a "touch" in a text field being edited.

Note
Calling this when the pSource is not the current receiver may not be desirable in all cases because the platform keyboard is not expecting cursor position changes from a receiver other than the current.
See also
GetCurrentReceiver

◆ OnCursorPositionChangedInternal()

virtual void CYIKeyboardInputBridge::OnCursorPositionChangedInternal ( size_t  start,
size_t  end 
)
protectedpure virtual

◆ OnCursorPositionWillChange()

void CYIKeyboardInputBridge::OnCursorPositionWillChange ( Receiver pSource)

Call this to let the system keyboard know the current cursor positon will change from the UI side. For example, as a result of a "touch" in a text field being edited.

Note
Calling this when the pSource is not the current receiver may not be desirable in all cases because the platform keyboard is not expecting cursor position changes from a receiver other than the current.
See also
GetCurrentReceiver

◆ OnCursorPositionWillChangeInternal()

virtual void CYIKeyboardInputBridge::OnCursorPositionWillChangeInternal ( )
protectedpure virtual

◆ OnKeyboardHidden()

virtual void CYIKeyboardInputBridge::OnKeyboardHidden ( )
protectedvirtual

◆ OnKeyboardShown()

virtual void CYIKeyboardInputBridge::OnKeyboardShown ( )
protectedvirtual

◆ OnTextChanged()

void CYIKeyboardInputBridge::OnTextChanged ( const CYIString text,
Receiver pSource 
)

Call this to let the system keyboard know the text being entered was changed from the UI side. For example, a "clear" button on the UI was pressed.

Note
Calling this when the pSource is not the current receiver may not be desirable in all cases because the platform keyboard is not expecting text changes from a receiver other than the current.
See also
GetCurrentReceiver

◆ OnTextChangedInternal()

virtual void CYIKeyboardInputBridge::OnTextChangedInternal ( const CYIString rText)
protectedpure virtual

◆ RemoveAccessoryImageUrl()

virtual void CYIKeyboardInputBridge::RemoveAccessoryImageUrl ( const CYIUrl url)
protectedvirtual

Override to remove a Url for creating an AccessoryImage.

◆ ResetKeyboard()

void CYIKeyboardInputBridge::ResetKeyboard ( Receiver pSource)

Request that the contents of the keyboard be reset.

◆ ResetKeyboardInternal()

virtual void CYIKeyboardInputBridge::ResetKeyboardInternal ( )
protectedpure virtual

◆ SetCurrentReceiver()

virtual void CYIKeyboardInputBridge::SetCurrentReceiver ( Receiver pReceiver)
protectedvirtual

◆ ShowKeyboard()

virtual bool CYIKeyboardInputBridge::ShowKeyboard ( Receiver pSource)
virtual

Request that the system software keyboard be displayed. Returns true if the keyboard was successfully displayed.

◆ ShowKeyboardInternal()

virtual bool CYIKeyboardInputBridge::ShowKeyboardInternal ( Receiver pSource)
protectedpure virtual

◆ ShowSelectionMenu()

void CYIKeyboardInputBridge::ShowSelectionMenu ( bool  textSelected,
YI_RECT  rect 
)

Call this to let the system show a menu pertaining to the current selection. If there is text on the clipboard then a Paste command will displayed. Selection is not currently supported so Copy and Cut commands will not be displayed, but placeholders are added for future implementation. The selection rect (cursor rect) is required for iOS, even when nothing is selected, so that the Paste menu can be displayed next to the text.

◆ ShowSelectionMenuInternal()

virtual void CYIKeyboardInputBridge::ShowSelectionMenuInternal ( bool  textSelected,
YI_RECT  rect 
)
protectedpure virtual

Member Data Documentation

◆ KeyboardHidden

CYISignal CYIKeyboardInputBridge::KeyboardHidden

Fired when the soft keyboard is hidden. On platforms that animate the soft keyboard out, best attempt is made to fire the signal before the animation starts.

◆ KeyboardShown

CYISignal CYIKeyboardInputBridge::KeyboardShown

Fired when the soft keyboard is shown. On platforms that animate the soft keyboard in, best attempt is made to fire the signal before the animation starts.

◆ KeyboardTextInputDirectionChanged

CYISignal<KeyboardTextInputDirection> CYIKeyboardInputBridge::KeyboardTextInputDirectionChanged
protected

Emitted when the keyboard text input language direction is changed by the user at runtime.


The documentation for this class was generated from the following file: