TN028: Dukungan Bantuan Sensitif Konteks

Artikel
06/16/2023

Catatan ini menjelaskan aturan untuk menetapkan ID konteks Bantuan dan masalah bantuan lainnya di MFC. Dukungan bantuan peka konteks memerlukan pengkompilasi bantuan yang tersedia di Visual C++.

Catatan

Selain menerapkan bantuan sensitif konteks menggunakan WinHelp, MFC juga mendukung penggunaan Bantuan HTML. Untuk informasi selengkapnya tentang dukungan dan pemrograman ini dengan Bantuan HTML, lihat Bantuan HTML: Bantuan Sensitif Konteks untuk Program Anda.

Jenis Bantuan yang Didukung

Ada dua jenis bantuan sensitif konteks yang diterapkan dalam aplikasi Windows. Yang pertama, yang disebut sebagai "Bantuan F1" melibatkan peluncuran WinHelp dengan konteks yang sesuai berdasarkan objek yang saat ini aktif. Yang kedua adalah mode "Shift+ F1". Dalam mode ini, kursor mouse berubah menjadi kursor bantuan, dan pengguna melanjutkan untuk mengklik objek. Pada titik itu, WinHelp diluncurkan untuk memberikan bantuan untuk objek yang diklik pengguna.

Kelas Microsoft Foundation mengimplementasikan kedua bentuk bantuan ini. Selain itu, kerangka kerja mendukung dua perintah bantuan sederhana, Indeks Bantuan dan Menggunakan Bantuan.

File Bantuan

Kelas Microsoft Foundation mengasumsikan satu file Bantuan. File Bantuan tersebut harus memiliki nama dan jalur yang sama dengan aplikasi. Misalnya, jika yang dapat dieksekusi adalah C:\MyApplication\MyHelp.exe, file bantuan harus C:\MyApplication\MyHelp.hlp. Anda mengatur jalur melalui variabel anggota m_pszHelpFilePath dari Kelas CWinApp.

Rentang Konteks Bantuan

Implementasi default MFC mengharuskan program untuk mengikuti beberapa aturan tentang penetapan ID konteks Bantuan. Aturan ini adalah berbagai ID yang dialokasikan untuk kontrol tertentu. Anda dapat mengambil alih aturan ini dengan menyediakan implementasi yang berbeda dari berbagai fungsi anggota terkait Bantuan.

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_

Perintah "Bantuan" sederhana

Ada dua perintah Bantuan sederhana yang diimplementasikan oleh Kelas Microsoft Foundation:

ID_HELP_INDEX yang diimplementasikan oleh CWinApp::OnHelpIndex
ID_HELP_USING yang diimplementasikan oleh CWinApp::OnHelpUsing

Perintah pertama menunjukkan indeks Bantuan untuk aplikasi. Yang kedua menunjukkan bantuan pengguna dalam menggunakan program WinHelp.

Bantuan Sensitif Konteks (Bantuan F1)

Kunci F1 biasanya diterjemahkan ke perintah dengan ID ID_HELP oleh akselerator yang ditempatkan ke dalam tabel akselerator jendela utama. Perintah ID_HELP juga dapat dihasilkan oleh tombol dengan ID ID_HELP pada jendela utama atau kotak dialog.

Terlepas dari bagaimana perintah ID_HELP dihasilkan, perintah tersebut dirutekan sebagai perintah normal hingga mencapai handler perintah. Untuk informasi selengkapnya tentang arsitektur perutean perintah MFC, lihat Catatan Teknis 21. Jika aplikasi mengaktifkan Bantuan, perintah ID_HELP akan ditangani oleh CWinApp::OnHelp. Objek aplikasi menerima pesan bantuan lalu merutekan perintah dengan tepat. Ini diperlukan karena perutean perintah default tidak memadai untuk menentukan konteks yang paling spesifik.

CWinApp::OnHelp mencoba meluncurkan WinHelp dalam urutan berikut:

Memeriksa panggilan aktif AfxMessageBox dengan ID Bantuan. Jika kotak pesan saat ini aktif, WinHelp diluncurkan dengan konteks yang sesuai dengan kotak pesan tersebut.
Mengirim pesan WM_COMMANDHELP ke jendela aktif. Jika jendela tersebut tidak merespons dengan meluncurkan WinHelp, pesan yang sama kemudian dikirim ke leluhur jendela tersebut hingga pesan diproses atau jendela saat ini adalah jendela tingkat atas.
Mengirim perintah ID_DEFAULT_HELP ke jendela utama. Ini memanggil Bantuan default. Perintah ini umumnya dipetakan ke CWinApp::OnHelpIndex.

Untuk mengganti nilai dasar ID default secara global (misalnya 0x10000 untuk perintah dan 0x20000 untuk sumber daya seperti dialog), aplikasi harus mengambil alih CWinApp::WinHelp.

Untuk mengambil alih fungsionalitas ini dan cara konteks Bantuan ditentukan, Anda harus menangani pesan WM_COMMANDHELP. Anda mungkin ingin memberikan perutean Bantuan yang lebih spesifik daripada yang disediakan kerangka kerja, karena hanya sedalam jendela anak MDI saat ini. Anda mungkin juga ingin memberikan bantuan yang lebih spesifik untuk jendela atau dialog tertentu, mungkin berdasarkan status internal objek tersebut saat ini atau kontrol aktif dalam dialog.

WM_COMMANDHELP

afx_msg LRESULT CWnd::OnCommandHelp(WPARAM wParam, LPARAM lParam)

WM_COMMANDHELP adalah pesan MFC Windows privat yang diterima oleh jendela aktif saat Bantuan diminta. Ketika jendela menerima pesan ini, jendela dapat memanggil CWinApp::WinHelp dengan konteks yang cocok dengan status internal jendela.

lParam
Berisi konteks Bantuan yang saat ini tersedia. lParam adalah nol jika tidak ada konteks Bantuan yang ditentukan. Implementasi OnCommandHelp dapat menggunakan ID konteks di lParam untuk menentukan konteks yang berbeda atau hanya dapat meneruskannya ke CWinApp::WinHelp.

wParam
Tidak digunakan dan akan menjadi nol.

OnCommandHelp Jika fungsi memanggil CWinApp::WinHelp, fungsi harus mengembalikan TRUE. Mengembalikan TRUE menghentikan perutean perintah ini ke kelas lain dan ke jendela lain.

Mode Bantuan (Bantuan Shift+F1)

Ini adalah bentuk bantuan peka konteks kedua. Umumnya, mode ini dimasukkan dengan menekan SHIFT+F1 atau melalui menu/toolbar. Ini diimplementasikan sebagai perintah (ID_CONTEXT_HELP). Hook filter pesan tidak digunakan untuk menerjemahkan perintah ini saat kotak dialog atau menu modal aktif, oleh karena itu perintah ini hanya tersedia untuk pengguna ketika aplikasi menjalankan pompa pesan utama (CWinApp::Run).

Setelah memasuki mode ini, kursor Tetikus Bantuan ditampilkan di semua area aplikasi, bahkan jika aplikasi biasanya akan menampilkan kursornya sendiri untuk area tersebut (seperti batas ukuran di sekitar jendela). Pengguna dapat menggunakan mouse atau keyboard untuk memilih perintah. Alih-alih menjalankan perintah, Bantuan pada perintah tersebut ditampilkan. Selain itu, pengguna dapat mengklik objek yang terlihat di layar, seperti tombol pada toolbar, dan Bantuan akan ditampilkan untuk objek tersebut. Mode Bantuan ini disediakan oleh CWinApp::OnContextHelp.

Selama eksekusi perulangan ini, semua input keyboard tidak aktif, kecuali untuk tombol yang mengakses menu. Selain itu, terjemahan perintah masih dilakukan melalui PreTranslateMessage untuk memungkinkan pengguna menekan tombol akselerator dan menerima bantuan pada perintah tersebut.

Jika ada terjemahan atau tindakan tertentu yang terjadi dalam PreTranslateMessage fungsi yang seharusnya tidak terjadi selama mode Bantuan SHIFT+F1, Anda harus memeriksa anggota CWinApp m_bHelpMode sebelum melakukan operasi tersebut. Implementasi CDialog PreTranslateMessage pemeriksaan ini sebelum memanggil IsDialogMessage, misalnya. Ini menonaktifkan tombol "navigasi dialog" pada dialog tanpa mode selama mode SHIFT+F1. Selain itu, CWinApp::OnIdle masih dipanggil selama perulangan ini.

Jika pengguna memilih perintah dari menu, perintah tersebut ditangani sebagai bantuan pada perintah tersebut (melalui WM_COMMANDHELP, lihat di bawah). Jika pengguna mengklik area yang terlihat dari jendela aplikasi, penentuan dibuat untuk apakah itu adalah klik nonkelola atau klik klien. OnContextHelp menangani pemetaan klik nonkelas ke klik klien secara otomatis. Jika itu adalah klik klien, itu kemudian mengirim WM_HELPHITTEST ke jendela yang diklik. Jika jendela tersebut mengembalikan nilai bukan nol, nilai tersebut digunakan sebagai konteks untuk bantuan. Jika mengembalikan nol, OnContextHelp coba jendela induk (dan gagal itu, induknya, dan sebagainya). Jika konteks Bantuan tidak dapat ditentukan, defaultnya adalah mengirim perintah ID_DEFAULT_HELP ke jendela utama, yang kemudian (biasanya) dipetakan ke CWinApp::OnHelpIndex.

WM_HELPHITTEST

afx_msg LRESULT CWnd::OnHelpHitTest(
WPARAM, LPARAM lParam)

WM_HELPHITTEST adalah pesan jendela privat MFC yang diterima oleh jendela aktif yang diklik selama mode Bantuan SHIFT+F1. Ketika Jendela menerima pesan ini, Jendela mengembalikan ID Bantuan DWORD untuk digunakan oleh WinHelp.

LOWORD(lParam) berisi koordinat perangkat sumbu X tempat mouse diklik relatif terhadap area klien jendela.

HIWORD(lParam) berisi koordinat sumbu Y.

wParam
tidak digunakan dan akan menjadi nol. Jika nilai yang dikembalikan bukan nol, WinHelp dipanggil dengan konteks tersebut. Jika nilai yang dikembalikan adalah nol, jendela induk dikueri untuk mendapatkan bantuan.

Dalam banyak kasus, Anda dapat memanfaatkan kode pengujian hit yang mungkin sudah Anda miliki. Lihat implementasi CToolBar::OnHelpHitTest untuk contoh penanganan pesan WM_HELPHITTEST (kode memanfaatkan kode hit-test yang digunakan pada tombol dan tipsalat di CControlBar).

Dukungan MFC Application Wizard dan MAKEHM

MFC Application Wizard membuat file yang diperlukan untuk membuat file Bantuan (file .cnt dan .hpj). Ini juga mencakup sejumlah file .rtf bawaan yang diterima oleh Pengkompilasi Bantuan Microsoft. Banyak topik yang lengkap, tetapi beberapa mungkin perlu dimodifikasi untuk aplikasi spesifik Anda.

Pembuatan otomatis file "pemetaan bantuan" didukung oleh utilitas yang disebut MAKEHM. Utilitas MAKEHM dapat menerjemahkan RESOURCE aplikasi. File H ke file pemetaan Bantuan. Contohnya:

#define IDD_MY_DIALOG   2000
#define ID_MY_COMMAND   150

akan diterjemahkan ke dalam:

HIDD_MY_DIALOG    0x207d0
HID_MY_COMMAND    0x10096

Format ini kompatibel dengan fasilitas pengkompilasi Bantuan, yang memetakan ID konteks (angka di sisi kanan) dengan nama topik (simbol di sisi kiri).

Kode sumber untuk MAKEHM tersedia dalam sampel MFC Programming Utilities MAKEHM.

Menambahkan Dukungan Bantuan Setelah Menjalankan Wizard Aplikasi MFC

Cara terbaik untuk menambahkan Bantuan ke aplikasi Anda adalah dengan memeriksa opsi "Bantuan peka konteks" di halaman Fitur Tingkat Lanjut dari Wizard Aplikasi MFC sebelum membuat aplikasi Anda. Dengan begitu Wizard Aplikasi MFC secara otomatis menambahkan entri peta pesan yang diperlukan ke kelas turunan Anda CWinAppuntuk mendukung Bantuan.

Bantuan pada Kotak Pesan

Bantuan tentang Kotak Pesan (kadang-kadang disebut pemberitahuan) didukung melalui AfxMessageBox fungsi , pembungkus untuk MessageBox WINDOWS API.

Ada dua versi AfxMessageBox, satu untuk digunakan dengan ID string dan yang lain untuk digunakan dengan pointer ke string (LPCSTR):

int AFXAPI AfxMessageBox(LPCSTR lpszText,
    UINT nType,
    UINT nIDHelp);

int AFXAPI AfxMessageBox(UINT nIDPrompt,
    UINT nType,
    UINT nIDHelp);

Dalam kedua kasus, ada ID Bantuan opsional.

Dalam kasus pertama, default untuk nIDHelp adalah 0, yang menunjukkan tidak ada Bantuan untuk kotak pesan ini. Jika pengguna menekan F1 saat kotak pesan aktif, pengguna tidak akan menerima Bantuan (bahkan jika aplikasi mendukung Bantuan). Jika ini tidak diinginkan, ID Bantuan harus disediakan untuk nIDHelp.

Dalam kasus kedua, nilai default untuk nIDHelp adalah -1, yang menunjukkan ID Bantuan sama dengan nIDPrompt. Bantuan akan berfungsi hanya jika aplikasi diaktifkan Bantuan, tentu saja). Anda harus menyediakan 0 untuk nIDHelp jika Anda ingin kotak pesan tidak memiliki dukungan bantuan. Jika Anda ingin pesan diaktifkan, tetapi menginginkan ID bantuan yang berbeda dari nIDPrompt, cukup berikan nilai positif untuk nIDHelp yang berbeda dari nIDPrompt.

Bagikan melalui