WinTranslateAccel

This function translates a WM_CHAR message.

Syntax

WinTranslateAccel(hab, hwnd, haccelAccel, pQmsg);

Parameters

hab (HAB) - input

Anchor-block handle.

hwnd (HWND) - input

Destination window.

haccelAccel (HACCEL) - input

Accelerator-table handle.

pQmsg (PQMSG) - in/out

Message to be translated.

Returns

rc (BOOL) - returns

Success indicator.

TRUE

Successful completion

FALSE

Error occurred.

Errors

Possible returns from WinGetLastError

PMERR_INVALID_HWND (0x1001)

An invalid window handle was specified.

PMERR_INVALID_HACCEL (0x101A)

An invalid accelerator-table handle was specified.

Remarks

This function translates pQmsg if it is a WM_CHAR message in the accelerator table haccelAccel. The message is translated into a WM_COMMAND, WM_SYSCOMMAND, or WM_HELP message, with hwnd identifying the destination window. Normally, this parameter is a frame-window handle. This function does not highlight menu items.

If haccelAccel equals NULL, the current accelerator table is assumed.

WinTranslateAccel returns TRUE if the message matches an accelerator in the table. pQmsg is modified by WinTranslateAccel if a match is found.

If a menu item exists that matches the accelerator-command value, and that item is disabled, pQmsg is translated to a WM_NULL message, rather than a WM_COMMAND, WM_SYSCOMMAND, or WM_HELP message. If the command is WM_SYSCOMMAND or WM_HELP (and if a WM_SYSCOMMAND or FID_SYSMENU child window is searched) the menu child window of hwnd that has the FID_MENU identifier is searched.

It is possible to have accelerators that do not correspond to items in a menu. If the command value does not match any items in the menu, the message is still translated.

Generally, applications do not have to call this function; it is usually called automatically by WinGetMsg and WinPeekMsg, when a WM_CHAR message is received with the window handle of the active window as the first parameter. The standard frame window procedure always passes WM_COMMAND messages to the FID_CLIENT window. Because the message is physically changed by WinTranslateAccel, applications do not see the WM_CHAR messages that result in WM_COMMAND, WM_SYSCOMMAND, or WM_HELP messages.

Example Code

This example uses the WinTranslateAccel API to translate WM_CHAR messages destined for the frame window.

#define INCL_WINWINDOWMGR
#define INCL_WINACCELERATORS
#include <OS2.H>

HACCEL haccel;
HWND hwndFrame, hwndClient; /* window handles. */
HAB hab;                    /* anchor block.   */
QMSG qmsg;

hwndFrame = WinQueryWindow(hwndClient,
                           QW_PARENT); /* get handle of parent, */
                                       /* which is frame window. */


    /* Now  get the accel table for the frame window  */
haccel = WinQueryAccelTable(hab,
                            hwndFrame);

WinTranslateAccel(hab,
                  hwndFrame,
                  haccel,
                  &qmsg);

switch(qmsg.msg)
{
   case WM_COMMAND:

   case WM_SYSCOMMAND:

   case WM_HELP:
   break;
}

Definition

#define INCL_WINACCELERATORS /* Or use INCL_WIN, INCL_PM, */
#include <os2.h>

HAB       hab;          /*  Anchor-block handle. */
HWND      hwnd;         /*  Destination window. */
HACCEL    haccelAccel;  /*  Accelerator-table handle. */
PQMSG     pQmsg;        /*  Message to be translated. */
BOOL      rc;           /*  Success indicator. */

rc = WinTranslateAccel(hab, hwnd, haccelAccel,
       pQmsg);

Related Functions

• WinCopyAccelTable
• WinCreateAccelTable
• WinDestroyAccelTable
• WinLoadAccelTable
• WinQueryAccelTable
• WinSetAccelTable

Related Messages

• WM_CHAR
• WM_COMMAND
• WM_HELP
• WM_NULL
• WM_SYSCOMMAND