TN028: 상황에 맞는 도움말 지원
이 참고에서는 MFC에서 도움말 컨텍스트 ID 및 기타 도움말 문제를 할당하기 위한 규칙을 설명합니다. 상황에 맞는 도움말 지원에는 Visual C++에서 사용할 수 있는 도움말 컴파일러가 필요합니다.
참고 항목
MFC는 WinHelp를 사용하여 상황에 맞는 도움말을 구현하는 것 외에도 HTML 도움말 사용을 지원합니다. HTML 도움말을 사용한 이 지원 및 프로그래밍에 대한 자세한 내용은 HTML 도움말: 프로그램에 대한 상황에 맞는 도움말을 참조 하세요.
지원되는 도움말 유형
Windows 애플리케이션에는 두 가지 유형의 컨텍스트 구분 도움말이 구현되어 있습니다. "F1 도움말"이라고 하는 첫 번째 항목에는 현재 활성 개체에 따라 적절한 컨텍스트로 WinHelp를 시작하는 작업이 포함됩니다. 두 번째는 "Shift+ F1" 모드입니다. 이 모드에서는 마우스 커서가 도움말 커서로 변경되고 사용자가 개체를 클릭합니다. 이 시점에서 WinHelp는 사용자가 클릭한 개체에 대한 도움말을 제공하기 위해 시작됩니다.
Microsoft Foundation 클래스는 이러한 두 가지 형태의 도움말을 모두 구현합니다. 또한 프레임워크는 도움말 인덱스 및 도움말 사용의 두 가지 간단한 도움말 명령을 지원합니다.
도움말 파일
Microsoft Foundation 클래스는 단일 도움말 파일을 가정합니다. 해당 도움말 파일의 이름과 경로는 애플리케이션과 같아야 합니다. 예를 들어 실행 파일이 C:\MyApplication\MyHelp.exe인 경우 도움말 파일은 C:\MyApplication\MyHelp.hlp여야 합니다. CWinApp 클래스의 m_pszHelpFilePath 멤버 변수를 통해 경로를 설정합니다.
도움말 컨텍스트 범위
MFC의 기본 구현에서는 프로그램이 도움말 컨텍스트 ID 할당에 대한 몇 가지 규칙을 따라야 합니다. 이러한 규칙은 특정 컨트롤에 할당된 ID의 범위입니다. 다양한 도움말 관련 멤버 함수의 다양한 구현을 제공하여 이러한 규칙을 재정의할 수 있습니다.
0x00000000 - 0x0000FFFF : user defined
0x00010000 - 0x0001FFFF : commands (menus/command buttons)
0x00010000 + ID_
(note: 0x18000-> 0x1FFFF is the practical range since command IDs are>=0x8000)
0x00020000 - 0x0002FFFF : windows and dialogs
0x00020000 + IDR_
(note: 0x20000-> 0x27FFF is the practical range since IDRs are <= 0x7FFF)
0x00030000 - 0x0003FFFF : error messages (based on error string ID)
0x00030000 + IDP_
0x00040000 - 0x0004FFFF : special purpose (non-client areas)
0x00040000 + HitTest area
0x00050000 - 0x0005FFFF : controls (those that are not commands)
0x00040000 + IDW_
간단한 "도움말" 명령
Microsoft Foundation 클래스에서 구현하는 두 가지 간단한 도움말 명령이 있습니다.
CWinApp::OnHelpIndex에서 구현되는 ID_HELP_INDEX
CWinApp::OnHelpUsing에서 구현되는 ID_HELP_USING
첫 번째 명령은 애플리케이션에 대한 도움말 인덱스입니다. 두 번째는 WinHelp 프로그램 사용에 대한 사용자 도움말을 보여줍니다.
상황에 맞는 도움말(F1 도움말)
F1 키는 일반적으로 기본 창의 가속기 테이블에 배치된 가속기에 의해 ID_HELP ID가 있는 명령으로 변환됩니다. ID_HELP 명령은 기본 창 또는 대화 상자에서 ID가 ID_HELP 있는 단추로 생성될 수도 있습니다.
ID_HELP 명령이 생성되는 방식에 관계없이 명령 처리기에 도달할 때까지 일반 명령으로 라우팅됩니다. MFC 명령 라우팅 아키텍처에 대한 자세한 내용은 Technical Note 21을 참조하세요. 애플리케이션에서 도움말을 사용하도록 설정한 경우 ID_HELP 명령은 CWinApp::OnHelp에서 처리됩니다. 애플리케이션 개체는 도움말 메시지를 받은 다음 명령을 적절하게 라우팅합니다. 이는 기본 명령 라우팅이 가장 구체적인 컨텍스트를 결정하는 데 적합하지 않기 때문에 필요합니다.
CWinApp::OnHelp 는 다음 순서대로 WinHelp를 시작하려고 시도합니다.
도움말 ID를 사용하여 활성
AfxMessageBox통화를 확인합니다. 메시지 상자가 현재 활성 상태이면 해당 메시지 상자에 적합한 컨텍스트를 사용하여 WinHelp가 시작됩니다.현재 창에 WM_COMMANDHELP 메시지를 보냅니다. WinHelp를 시작하여 해당 창이 응답하지 않으면 메시지가 처리되거나 현재 창이 최상위 창이 될 때까지 동일한 메시지가 해당 창의 상위 항목으로 전송됩니다.
기본 창에 ID_DEFAULT_HELP 명령을 보냅니다. 그러면 기본 도움말이 호출됩니다. 이 명령은 일반적으로 .에 매핑됩니다
CWinApp::OnHelpIndex.
기본 ID 기본 값(예: 명령에 대한 0x10000 및 대화 상자와 같은 리소스에 대한 0x20000)을 전역적으로 재정의하려면 애플리케이션이 CWinApp::WinHelp를 재정의해야 합니다.
이 기능과 도움말 컨텍스트가 결정되는 방식을 재정의하려면 WM_COMMANDHELP 메시지를 처리해야 합니다. 현재 MDI 자식 창만큼 깊기 때문에 프레임워크에서 제공하는 것보다 더 구체적인 도움말 라우팅을 제공할 수 있습니다. 해당 개체의 현재 내부 상태 또는 대화 상자 내의 활성 컨트롤에 따라 특정 창 또는 대화 상자에 대한 보다 구체적인 도움말을 제공할 수도 있습니다.
WM_COMMANDHELP
afx_msg LRESULT CWnd::OnCommandHelp(WPARAM wParam, LPARAM lParam)
WM_COMMANDHELP 도움말이 요청될 때 활성 창에서 수신하는 프라이빗 Windows MFC 메시지입니다. 창에서 이 메시지를 받으면 창의 내부 상태와 일치하는 컨텍스트를 사용하여 호출 CWinApp::WinHelp 할 수 있습니다.
lParam
현재 사용 가능한 도움말 컨텍스트를 포함합니다. 도움말 컨텍스트가 결정되지 않은 경우 lParam 은 0입니다. 구현은 OnCommandHelp lParam의 컨텍스트 ID를 사용하여 다른 컨텍스트를 확인하거나 전달할 CWinApp::WinHelp수 있습니다.
wParam
사용되지 않으며 0이 됩니다.
함수가 OnCommandHelp 호출CWinApp::WinHelp하는 경우 TRUE를 반환해야 합니다. TRUE를 반환하면 다른 클래스 및 다른 창으로의 이 명령 라우팅이 중지됩니다.
도움말 모드(Shift+F1 도움말)
이는 컨텍스트에 민감한 도움말의 두 번째 형태입니다. 일반적으로 이 모드는 Shift+F1을 누르거나 메뉴/도구 모음을 통해 입력됩니다. 명령(ID_CONTEXT_HELP)으로 구현됩니다. 메시지 필터 후크는 모달 대화 상자 또는 메뉴가 활성화되어 있는 동안 이 명령을 번역하는 데 사용되지 않으므로 애플리케이션이 기본 메시지 펌프(CWinApp::Run)를 실행하는 경우에만 이 명령을 사용할 수 있습니다.
이 모드를 입력하면 애플리케이션이 일반적으로 해당 영역에 대한 자체 커서(예: 창 주위의 크기 조정 테두리)를 표시하더라도 도움말 마우스 커서가 애플리케이션의 모든 영역에 표시됩니다. 사용자는 마우스 또는 키보드를 사용하여 명령을 선택할 수 있습니다. 명령을 실행하는 대신 해당 명령에 대한 도움말이 표시됩니다. 또한 사용자는 도구 모음의 단추와 같이 화면에 표시되는 개체를 클릭할 수 있으며 해당 개체에 대한 도움말이 표시됩니다. 이 도움말 모드는 .에서 CWinApp::OnContextHelp제공합니다.
이 루프를 실행하는 동안 메뉴에 액세스하는 키를 제외하고 모든 키보드 입력이 비활성 상태입니다. 또한 사용자가 가속기 키를 누르고 해당 명령에 대한 도움말을 받을 수 있도록 명령 번역은 계속 수행 PreTranslateMessage 됩니다.
함수에서 SHIFT+F1 도움말 모드 중에 PreTranslateMessage 수행되지 않아야 하는 특정 번역 또는 작업이 있는 경우 해당 작업을 수행하기 전에 m_bHelpMode 멤버를 CWinApp 검사 합니다. CDialog 예를 들어 호출IsDialogMessage하기 전에 검사 구현 PreTranslateMessage 합니다. 이렇게 하면 SHIFT+F1 모드 중에 모덜리스 대화 상자에서 "대화 상자 탐색" 키가 비활성화됩니다. 또한 CWinApp::OnIdle 이 루프 중에는 여전히 호출됩니다.
사용자가 메뉴에서 명령을 선택하면 해당 명령에 대한 도움말로 처리됩니다(WM_COMMANDHELP 통해 아래 참조). 사용자가 애플리케이션 창의 표시 영역을 클릭하면 비클라이언트 클릭인지 아니면 클라이언트 클릭인지를 결정합니다. OnContextHelp 는 클라이언트 클릭에 대한 비클라이언트 클릭의 매핑을 자동으로 처리합니다. 클라이언트 클릭인 경우 클릭한 창에 WM_HELPHITTEST 보냅니다. 해당 창이 0이 아닌 값을 반환하는 경우 해당 값은 도움말의 컨텍스트로 사용됩니다. 0 OnContextHelp 을 반환하는 경우 부모 창을 시도합니다(및 실패, 부모 등). 도움말 컨텍스트를 확인할 수 없는 경우 기본값은 ID_DEFAULT_HELP 명령을 기본 창으로 보내는 것입니다. 그러면 (일반적으로) 매핑됩니다CWinApp::OnHelpIndex.
WM_HELPHITTEST
afx_msg LRESULT CWnd::OnHelpHitTest(
WPARAM, LPARAM lParam)
WM_HELPHITTEST SHIFT+F1 도움말 모드에서 클릭한 활성 창에서 수신되는 MFC 개인 창 메시지입니다. 창이 이 메시지를 받으면 WinHelp에서 사용할 DWORD 도움말 ID를 반환합니다.
LOWORD(lParam)에는 창의 클라이언트 영역을 기준으로 마우스를 클릭한 X축 디바이스 좌표가 포함되어 있습니다.
HIWORD(lParam)에는 Y축 좌표가 포함되어 있습니다.
wParam
가 사용되지 않으며 0이 됩니다. 반환 값이 0이 아니면 해당 컨텍스트를 사용하여 WinHelp가 호출됩니다. 반환 값이 0이면 부모 창에서 도움말을 쿼리합니다.
대부분의 경우 이미 있을 수 있는 적중 테스트 코드를 활용할 수 있습니다. WM_HELPHITTEST 메시지 처리 예제의 구현 CToolBar::OnHelpHitTest 을 참조하세요(코드는 단추 및 도구 설명에 CControlBar사용되는 적중 테스트 코드를 활용).
MFC 애플리케이션 마법사 지원 및 MAKEHM
MFC 애플리케이션 마법사는 도움말 파일(.cnt 및 .hpj 파일)을 빌드하는 데 필요한 파일을 만듭니다. 또한 Microsoft 도움말 컴파일러에서 허용하는 미리 빌드된 여러 .rtf 파일도 포함됩니다. 대부분의 항목이 완료되었지만 일부 항목은 특정 애플리케이션에 맞게 수정해야 할 수 있습니다.
"도움말 매핑" 파일의 자동 생성은 MAKEHM이라는 유틸리티에서 지원됩니다. MAKEHM 유틸리티는 애플리케이션의 리소스를 변환할 수 있습니다. 도움말 매핑 파일에 대한 H 파일입니다. 예시:
#define IDD_MY_DIALOG 2000
#define ID_MY_COMMAND 150
는 다음으로 변환됩니다.
HIDD_MY_DIALOG 0x207d0
HID_MY_COMMAND 0x10096
이 형식은 컨텍스트 ID(오른쪽의 숫자)를 토픽 이름(왼쪽의 기호)과 매핑하는 도움말 컴파일러의 기능과 호환됩니다.
MAKEHM의 소스 코드는 MFC 프로그래밍 유틸리티 샘플 MAKEHM에서 사용할 수 있습니다.
MFC 애플리케이션 마법사를 실행한 후 도움말 지원 추가
애플리케이션에 도움말을 추가하는 가장 좋은 방법은 애플리케이션을 만들기 전에 MFC 애플리케이션 마법사의 고급 기능 페이지에서 "상황에 맞는 도움말" 옵션을 검사 것입니다. 이렇게 하면 MFC 애플리케이션 마법사가 도움말을 지원하기 위해 CWinApp필요한 메시지 맵 항목을 파생 클래스에 자동으로 추가합니다.
메시지 상자에 대한 도움말
메시지 상자에 대한 도움말(경고라고도 함)은 Windows API에 대한 래퍼인 함수를 MessageBox 통해 AfxMessageBox 지원됩니다.
두 가지 버전이 있습니다. 하나는 문자열 ID와 함께 사용되고 다른 버전은 AfxMessageBox문자열에 대한 포인터와 함께 사용할 수 있습니다(LPCSTR).
int AFXAPI AfxMessageBox(LPCSTR lpszText,
UINT nType,
UINT nIDHelp);
int AFXAPI AfxMessageBox(UINT nIDPrompt,
UINT nType,
UINT nIDHelp);
두 경우 모두 선택적 도움말 ID가 있습니다.
첫 번째 경우 nIDHelp의 기본값은 0으로, 이 메시지 상자에 대한 도움말이 없음을 나타냅니다. 메시지 상자가 활성화되어 있는 동안 사용자가 F1 키를 누르면 애플리케이션에서 도움말을 지원하는 경우에도 도움말이 표시되지 않습니다. 바람직하지 않은 경우 nIDHelp에 대한 도움말 ID를 제공해야 합니다.
두 번째 경우 nIDHelp의 기본값은 -1이며, 이는 도움말 ID가 nIDPrompt와 동일하다는 것을 나타냅니다. 도움말은 애플리케이션이 도움말을 사용하도록 설정된 경우에만 작동합니다. 메시지 상자에 도움말이 지원되지 않도록 하려면 nIDHelp에 대해 0을 제공해야 합니다. 메시지를 도움말을 사용하도록 설정하지만 nIDPrompt와 다른 도움말 ID를 원하는 경우 nIDPrompt와 다른 nIDHelp에 대해 양수 값을 제공하기만 하면 됩니다.