ITfKeystrokeMgr::PreserveKey method (msctf.h)

Registers a preserved key.

Syntax

HRESULT PreserveKey(
  [in] TfClientId            tid,
  [in] REFGUID               rguid,
  [in] const TF_PRESERVEDKEY *prekey,
  [in] const WCHAR           *pchDesc,
  [in] ULONG                 cchDesc
);

Parameters

[in] tid

Contains the client identifier of the TSF text service. This value is passed to the TSF text service in its ITfTextInputProcessor::Activate method.

[in] rguid

Contains the command GUID of the preserved key. This value is passed to the TSF text service ITfKeyEventSink::OnPreservedKey method to identify the preserved key when the preserved key is activated.

[in] prekey

Pointer to a TF_PRESERVEDKEY structure that specifies the preserved key. The uVKey member contains the virtual key code and the uModifiers member identifies the modifiers of the preserved key.

[in] pchDesc

Pointer to a Unicode string that contains the description of the preserved key. This cannot be NULL unless cchDesc is zero.

[in] cchDesc

Specifies the number of characters in pchDesc. Pass zero for this parameter if no description is required.

Return value

This method can return one of these values.

Value Description
S_OK
The method was successful.
TF_E_ALREADY_EXISTS
The preserved key is registered.
E_INVALIDARG
One or more parameters are invalid.
E_OUTOFMEMORY
A memory allocation error occurred.
E_FAIL
An unspecified error occurred.

Remarks

Preserved keys are registered by TSF text services and provide keyboard shortcuts to common commands implemented by the TSF text service.

Requirements

Requirement Value
Minimum supported client Windows 2000 Professional [desktop apps | UWP apps]
Minimum supported server Windows 2000 Server [desktop apps | UWP apps]
Target Platform Windows
Header msctf.h
DLL Msctf.dll
Redistributable TSF 1.0 on Windows 2000 Professional

See also

ITfKeyEventSink::OnPreservedKey

ITfKeystrokeMgr

ITfKeystrokeMgr::UnpreserveKey

ITfTextInputProcessor::Activate

TF_PRESERVEDKEY