Accelerators

There are ways to add keyboard shortcuts to menus and these are called Accelerators. Accelerators are application resource. It contains one or more mappings of key combination to menu items. Very popular key shortcuts in notepad or any editor applications are -

  • Ctrl+N
  • Ctrl+O
  • Ctrl+S

Accelerators resource editor

Like all other resoures in VC++ project, accelerators are another type of resource and VC++ editor provides an editor for this. A new accelerator can be created using "New Resource" or an existing Accelerator can be edited in Resource tab in the project exploler.

Accelerators resource editor in VC++

Accelerators APIs

LoadAccelerators, TranslateAccelerator, TranslateMessage are most common Win32 APIs used for Accelerators. Lets see the details of these APIs and how to use these. Later we have a sample code where we have utilized these functions.

LoadAccelerators function

Loads the specified accelerator table and returns the handle to accelerator table.

HACCEL WINAPI LoadAccelerators(
 HINSTANCE hInstance,
 LPCTSTR   lpTableName
);

Parameters

  • hInstance - A handle to the module whichfile contains the accelerator table to be loaded.
  • lpTableName - The name of the accelerator table as string to be loaded. MAKEINTRESOURCE macro can be used if resource ID is given instead of name.

Return value

handle to the loaded accelerator table on success or NULL in failure.

Remarks

Accelerator tables loaded from resources are freed automatically when the application terminates.

TranslateAccelerator function

Processes accelerator keys for menu commands. The function translates a WM_KEYDOWN or WM_SYSKEYDOWN message to a WM_COMMAND or WM_SYSCOMMAND message (if there is an entry for the key in the specified accelerator table) and then sends the WM_COMMAND or WM_SYSCOMMAND message directly to the specified window procedure. TranslateAccelerator does not return until the window procedure has processed the message.

int WINAPI TranslateAccelerator(
  HWND   hWnd,
  HACCEL hAccTable,
  LPMSG  lpMsg
);

Parameters

  • hWnd - A handle to the window whose messages are to be translated.
  • hAccTable - A handle to the accelerator table loaded with LoadAccelerators().
  • lpMsg -A pointer to an MSG structure that contains message information retrieved from the calling thread's message queue using the GetMessage or PeekMessage function.

Return value

  • If the function succeeds, the return value is nonzero.
  • If the function fails, the return value is zero. To get extended error information, call GetLastError.
  • TranslateMessage function

    Translates virtual-key messages into character messages. The character messages are posted to the calling thread's message queue, to be read the next time the thread calls the GetMessage or PeekMessage function.

    BOOL WINAPI TranslateMessage(
       const MSG *lpMsg
    );
    

    Parameters

    • lpMsg - A pointer to an MSG structure that contains message information retrieved from the calling thread's message queue by using the GetMessage or PeekMessage function.

    Return value

    • If the message is translated (that is, a character message is posted to the thread's message queue), the return value is nonzero.
    • If the message is WM_KEYDOWN, WM_KEYUP, WM_SYSKEYDOWN, or WM_SYSKEYUP, the return value is nonzero, regardless of the translation.
    • If the message is not translated (that is, a character message is not posted to the thread's message queue), the return value is zero.

    Sample code

    int APIENTRY WinMain(HINSTANCE hInstance,
                         HINSTANCE hPrevInstance,
                         LPSTR     lpCmdLine,
                         int       nCmdShow)
    {
      MSG msg;
      HACCEL hAccelTable;

      /* Load the Accelerator table */
      hAccelTable = LoadAccelerators(hInstance, (LPCTSTR)IDC_ACC);

      while (GetMessage(&msg, NULL, 0, 0)) 
      {
          /* Check and translate the msg key if present in table */
        if (!TranslateAccelerator(msg.hwnd, hAccelTable, &msg)) 
        {
            /* Translate the message and dispatch */
          TranslateMessage(&msg);
          DispatchMessage(&msg);
        }
      }

      return msg.wParam;
    }

    LRESULT CALLBACK WndProc(HWND hWnd, UINT message, WPARAM wParam, LPARAM lParam)
    {
      int wmId, wmEvent;

      switch (message) 
      {
        case WM_COMMAND:
          wmId    = LOWORD(wParam); 
          wmEvent = HIWORD(wParam); 
          /* Parse the menu selections: */
          switch (wmId)
          {
            case IDM_ABOUT:
               DialogBox(hInst, (LPCTSTR)IDD_ABOUTBOX, hWnd, (DLGPROC)About);
               break;
            case IDM_EXIT:
               DestroyWindow(hWnd);
               break;
            default:
               return DefWindowProc(hWnd, message, wParam, lParam);
          }
          break;

        case WM_DESTROY:
          PostQuitMessage(0);
          break;
        default:
          return DefWindowProc(hWnd, message, wParam, lParam);
       }
       return 0;
    }

    About our authors: Team EQA

    Further readings

    Where is WinMain() function in MFC application ?

    MFC hides WinMain in its framework and includes source file on WinMain(). This explains how framework calls global CWinApp::Initinstance() from entry WinMain.

    What is the utility of CWinApp class?

    This is constructed during global C++ objects are constructed and is already available when Windows calls the WinMain function, which is supplied by the ...

    Basic steps in Win32 GUI Application with source code.

    Define a custom Window class structure, Register the class name, CreateWindow, Show windows and write message get and dispatch loop statements. Define the Window CallBack procedure and write the handlers.

    What is a Window CallBack procedure and what is its utility?

    DispatchMessage() is a API which indirectly triggers the Window CallBack procedure. Message structure members from this function are passed to the CallBack procedure. CallBack procedure should implement event handlers depending on the need of the application.

    What are LPARAM and WPARAM in window proc function?

    LPARAM and WPARAM are the two parameters in Window CallBack procedure. They signifies parameters of various events. They are used in handing individual events.

    What are the basic steps of a typical MFC based application?

    We need to write WinMain and need to follow all these in a Win32 application. However we need not to write much if we are writing an application with MFC ...

    Learn on Youtube

    #