StringFormat::SetHotkeyPrefix method (gdiplusstringformat.h)

Article
10/13/2021

The StringFormat::SetHotkeyPrefix method sets the type of processing that is performed on a string when the hot key prefix, an ampersand (&), is encountered. The ampersand is called the hot key prefix and can be used to designate certain keys as hot keys.

Syntax

Status SetHotkeyPrefix(
  [in] HotkeyPrefix hotkeyPrefix
);

Parameters

[in] hotkeyPrefix

Type: HotkeyPrefix

Element of the HotkeyPrefix enumeration that specifies how to process the hot key prefix.

Return value

Type: Status

If the method succeeds, it returns Ok, which is an element of the Status enumeration.

If the method fails, it returns one of the other elements of the Status enumeration.

Remarks

Hot keys, also called access keys, are keys that are programmed to provide an end user with keyboard shortcuts to functionality and are activated by pressing the ALT key. The keys are application dependent and are identified by an underscored letter, typically in a menu name or menu item; for example, when you press ALT, the letter F of the File menu is underscored. The F key is a shortcut to display the File menu.

A client programmer designates a hot key in an application by using the hot key prefix, an ampersand (&), in a string that typically is displayed as the name of a menu or an item in a menu and by using the StringFormat::SetHotkeyPrefix method to set the appropriate type of processing. When a character in a string is preceded with an ampersand, the key that corresponds to the character becomes a hot key during the processing that occurs when the string is drawn on the display device. The ampersand is called a hot key prefix because it precedes the character to be activated. If HotkeyPrefixNone is passed to StringFormat::SetHotkeyPrefix, no processing of the hot key prefix occurs.

Note The term hot key is used synonymously here with the term access key. The term hot key may have a different meaning in other Windows APIs.

Examples

The following example creates a StringFormat object and sets the type of hot key prefix processing to be performed on the string. The code then uses the StringFormat object to draw a string that contains the hot key prefix character. The code also draws the string's layout rectangle.

VOID Example_SetHotkeyPrefix(HDC hdc)
{
   Graphics graphics(hdc);

   SolidBrush  solidBrush(Color(255, 255, 0, 0)); 
   FontFamily  fontFamily(L"Times New Roman");
   Font        font(&fontFamily, 24, FontStyleRegular, UnitPixel);
   
   StringFormat stringFormat;
   stringFormat.SetHotkeyPrefix(HotkeyPrefixShow);

   graphics.DrawString(
      L"This &text has some &underlined characters.", 
      43,  // string length
      &font, 
      RectF(30, 30, 160, 200), 
      &stringFormat, 
      &solidBrush);

   // Draw the rectangle that encloses the text.
   Pen pen(Color(255, 255, 0, 0));
   graphics.DrawRectangle(&pen, 30, 30, 160, 200);
}

Requirements

Requirement	Value
Minimum supported client	Windows XP, Windows 2000 Professional [desktop apps only]
Minimum supported server	Windows 2000 Server [desktop apps only]
Target Platform	Windows
Header	gdiplusstringformat.h (include Gdiplus.h)
Library	Gdiplus.lib
DLL	Gdiplus.dll

Share via