Class: TStandardEditableVirtualKeyboard

Declaration: Keyboards.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

None.

Inherited By:

None.

Purpose:

Represents an editable software keyboard that corresponds to a standard physical keyboard layout (for example, IBM and Macintosh). Thus, it assumes that the keyboard has more or less the standard number of keys, including modifiers such as Shift and Caps Lock. Use this class when you want to modify an existing instance of a virtual keyboard or to create a new instance, for example, a Dvorak layout to replace the standard QWERTY layout.

Instantiation:

Always allocate on the heap.

Deriving Classes:

Clients do not typically derive. Deriving would be required for a keyboard that uses a set of keys and layout that differs radically from the standard defined in the EKeyName enum.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TStandardEditableVirtualKeyboard::TStandardEditableVirtualKeyboard

TStandardEditableVirtualKeyboard ()
TStandardEditableVirtualKeyboard (const TStandardEditableVirtualKeyboard & copyIn)

Interface Category:

API.

Purpose:

Default constructor.
Copy constructor.

Calling Context:

Called by the stream-in operators and when instantiating an editable keyboard.
Called to copy an object.

Parameters:

Takes no parameters.
const TStandardEditableVirtualKeyboard & copyIn -The object to copy.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStandardEditableVirtualKeyboard::Compact

virtual void Compact ()

Interface Category:

API.

Purpose:

Allows the size of a keyboard to be reduced by removing redundant rules.

Calling Context:

Called by editor programs after completion of a sequence of edits.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

The keyboard should be functional without calling Compact.

Member Function: TStandardEditableVirtualKeyboard::CreateIterator

virtual TKeyMapRuleIterator * CreateIterator () const

Interface Category:

API.

Purpose:

Creates an iterator that lists all the mapping rules in a keyboard.

Calling Context:

Typically called by editor programs to display the rules to a user for editing.

Parameters:

Takes no parameters.

Return Value:

TKeyMapRuleIterator* -The iterator for listing mapping rules.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStandardEditableVirtualKeyboard::SetCommandKeyModifiers

virtual void SetCommandKeyModifiers (const TModifierKeys & modifiers)

Interface Category:

API.

Purpose:

Allows keyboard editors to specify a single modifier to represent the appearance of keys on keycaps and as command key equivalents in menus. For example, appearances of the keycaps on a typical QWERTY keyboard are typically those that can be generated by applying the Caps Lock modifier to each virtual key. The keyboard uses this modifier to generate a TText for TVirtualKeyboard::CommandText. The appearance of specific keys can be set by the SetKeyAppearance function.

Calling Context:

Called by a keyboard editor.

Parameters:

const TModifierKeys & modifiers -The modifiers used to represent a command key equivalent.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStandardEditableVirtualKeyboard::GetCommandKeyModifiers

virtual void GetCommandKeyModifiers (TModifierKeys & modifiers) const

Interface Category:

API.

Purpose:

Gets the command key modifiers for this keyboard.

Calling Context:

Called by editor programs and internally.

Parameters:

TModifierKeys & modifiers -The modifiers used for displaying command key equivalents.

Return Value:

The value in the modifiers parameter.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStandardEditableVirtualKeyboard::SetVirtualKeyboardForCommand

virtual void SetVirtualKeyboardForCommand (const TLocalizableName & name)

Interface Category:

API.

Purpose:

Each virtual keyboard can have an associated keyboard for generating the appearance of command keys equivalents for display in menus, and so on. The command keyboard is used within the function CommandText. SetVirtualKeyboardForCommand permits clients to set the command keyboard. If none is set, this keyboard is used.

Calling Context:

Called by keyboard editor programs.

Parameters:

const TLocalizableName & name -The name of a virtual keyboard to be used for command mappings.

Return Value:

None.

Exceptions:

Throws TVirtualKeyboardException::kSpecifiedKeyboardNotInstalled if the keyboard is not installed.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStandardEditableVirtualKeyboard::GetVirtualKeyboardForCommand

virtual void GetVirtualKeyboardForCommand (TLocalizableName & name) const

Interface Category:

API.

Purpose:

Gets the command keyboard for this keyboard.

Calling Context:

Called by keyboard editor programs and internally by the CommandText function.

Parameters:

TLocalizableName & name -Returns the value of the current command keyboard for this keyboard.

Return Value:

The value in the name parameter.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStandardEditableVirtualKeyboard::SetModifierAppearance

virtual void SetModifierAppearance (const TModifierKeys & modifier, const TText & modifierAppearance)

Interface Category:

API.

Purpose:

Sets up characters that will be a visual representation of a modifier key.

Calling Context:

Called by keyboard editor programs.

Parameters:

const TModifierKeys & modifier -The modifier key.
const TText & modifierAppearance -The key's appearance in menus, and so on.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStandardEditableVirtualKeyboard::GetModifierAppearance

virtual void GetModifierAppearance (const TModifierKeys & modifier, TText & modifierAppearance) const

Interface Category:

API.

Purpose:

Supplies the visual appearance of a modifier key.

Calling Context:

Called by keyboard editor programs and internally.

Parameters:

const TModifierKeys & modifier -The modifier.
TText & modifierAppearance -The modifier's appearance.

Return Value:

The TText returned in modifierAppearance.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStandardEditableVirtualKeyboard::SetUseControlMask

virtual void SetUseControlMask (const bool use)

Interface Category:

API.

Purpose:

Optimization that allows control characters to be generated by masking a character code with 0x1F.

Calling Context:

Called by keyboard editor programs.

Parameters:

const bool use -true if the mask should be used, false if not.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStandardEditableVirtualKeyboard::GetUseControlMask

virtual bool GetUseControlMask () const

Interface Category:

API.

Purpose:

Returns the status of use control mask.

Calling Context:

Called by keyboard editor programs and internally.

Parameters:

Takes no parameters.

Return Value:

Returns true if the control key mask is to be used.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStandardEditableVirtualKeyboard::operator=

TStandardEditableVirtualKeyboard & operator =(const TStandardEditableVirtualKeyboard & from)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Called when an object is assigned to another compatible object.

Parameters:

const TStandardEditableVirtualKeyboard & from -The source object for the assignment.

Return Value:

A non-const reference to the left-hand side object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStandardEditableVirtualKeyboard::operator<<=

virtual TStream & operator <<= (TStream & fromWhere)

Interface Category:

API.

Purpose:

Stream-in operator.

Calling Context:

Called to stream in data.

Parameters:

TStream & fromWhere -The stream the object is streamed in from.

Return Value:

Returns a reference to the stream the object streams itself in from.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStandardEditableVirtualKeyboard::operator>>=

virtual TStream & operator >>=(TStream & toWhere) const

Interface Category:

API.

Purpose:

Stream-out operator.

Calling Context:

Called to stream out data.

Parameters:

TStream & toWhere -The stream the object is streamed out to.

Return Value:

Returns a reference to the stream the object streams itself out to.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStandardEditableVirtualKeyboard::~TStandardEditableVirtualKeyboard

virtual ~ TStandardEditableVirtualKeyboard ()

Interface Category:

API.

Purpose:

Destructor.

Calling Context:

Called to destroy an object.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStandardEditableVirtualKeyboard::MapKeyToText

virtual void MapKeyToText (TVirtualKeyCode :: EVirtualKey key, const TModifierKeys & modifiers, TText & text) const

Interface Category:

API.

Purpose:

Produces a TText from a virtual key and modifier combination.

Calling Context:

Most clients do not call this directly, but through an instance of TVirtualKeyboardHandle. For example, the text interaction state calls this via the typing configuration when keyboard input is processed.

Parameters:

TVirtualKeyCode :: EVirtualKey key -The key which was typed.
const TModifierKeys & modifiers -Any additional modifier keys.
TText & text -The resulting text result.

Return Value:

None. The result is returned in the text parameter.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Overrides inherited TVirtualKeyboard function.

Member Function: TStandardEditableVirtualKeyboard::GetKeyAppearance

virtual void GetKeyAppearance (TVirtualKeyCode :: EVirtualKey keyCode, TText & appearance) const

Interface Category:

API.

Purpose:

Generates the appearance of a key for display on keycaps, menus, and so on.

Calling Context:

Called by keyboard editor programs and internally.

Parameters:

TVirtualKeyCode :: EVirtualKey keyCode -The key to display.
TText & appearance -How that key should look on key caps and in menus.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStandardEditableVirtualKeyboard::SetKeyAppearance

virtual void SetKeyAppearance (TVirtualKeyCode :: EVirtualKey keyCode, const TText & appearance)

Interface Category:

API.

Purpose:

Sets up a TText which will be a visual representation of a virtual key. For example, VirtualSpace could be displayed as TControlCodePicture::kOpenBox, which is a standard visual representation of a space. For keys whose appearance has not been set by SetKeyAppearance, the modifiers set by SetCommandKeyModifiers and the command virtual keyboard set by SetVirtualKeyboardForCommand will be used to get their appearance.

Calling Context:

Called by the keyboard editor program.

Parameters:

TVirtualKeyCode :: EVirtualKey keyCode -The keycode whose appearance will be set.
const TText & appearance -The text for the actual appearance.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStandardEditableVirtualKeyboard::AddResult

virtual void AddResult (const UniChar singleChar, TVirtualKeyCode :: EVirtualKey key, const TModifierKeys & modsOn, ECapsLockRule capsLockRule =kDontAddSameRuleForCapsLock, ERightLeftKeyRule rightLeftRule =kAddSameRuleForRightKey)
virtual void AddResult (const TText & result, TVirtualKeyCode :: EVirtualKey key, const TModifierKeys & modsOn, ECapsLockRule capsLockRule =kDontAddSameRuleForCapsLock, ERightLeftKeyRule rightLeftRule =kAddSameRuleForRightKey)

Interface Category:

API.

Purpose:

Adds a key mapping rule to produce a single UniChar.
Adds a key mapping rule to produce a TText containing one or more UniChars.

Calling Context:

Called during an editing session.
Called during an editing session.

Parameters:

const UniChar singleChar -A single UniChar result. If singleChar is TUnicodeSpecial::kNotAUniCode, the rule is removed.
TVirtualKeyCode :: EVirtualKey key -The virtual key that maps to this result.
const TModifierKeys & modsOn -The modifiers that must be on to produce the result.
ECapsLockRule capsLockRule =kDontAddSameRuleForCapsLock -An accelerator for extending this rule to the Caps Lock key. The default is to not extend the rule.
ERightLeftKeyRule rightLeftRule =kAddSameRuleForRightKey -An accelerator for extending this rule to the right-hand corresponding modifier key. The default is to extend the rule.
const TText & result -The TText result that is to be produced by this rule. An empty TText removes the rule.
TVirtualKeyCode :: EVirtualKey key -The virtual key that maps to this result.
const TModifierKeys & modsOn -The modifiers that must be on to produce the result.
ECapsLockRule capsLockRule =kDontAddSameRuleForCapsLock -An accelerator for extending this rule to the Caps Lock key. The default is to not extend the rule.
ERightLeftKeyRule rightLeftRule =kAddSameRuleForRightKey -An accelerator for extending this rule to the right-hand corresponding modifier key. The default is to extend the rule.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Existing rules with the same virtual key and modifier combination will be replaced by any rules added later.

Click the icon to mail questions or corrections about this material to Taligent personnel.