TN028: Bağlama Duyarlı Yardım Desteği
Bu not, MFC'de Yardım bağlamı kimlikleri ve diğer yardım sorunlarını atama kurallarını açıklar. Bağlama duyarlı yardım desteği, Visual C++'da kullanılabilen yardım derleyicisini gerektirir.
Dekont
MFC, WinHelp kullanarak bağlama duyarlı yardım uygulamaya ek olarak HTML Yardımı'nın kullanılmasını da destekler. HTML Yardımı ile bu destek ve programlama hakkında daha fazla bilgi için bkz . HTML Yardımı: Programlarınız için Bağlama Duyarlı Yardım.
Desteklenen Yardım Türleri
Windows uygulamalarında iki tür bağlama duyarlı yardım uygulanır. "F1 Yardımı" olarak adlandırılan ilk işlem, geçerli etkin nesneye göre uygun bağlamla WinHelp'in başlatılmasını içerir. İkincisi "Shift+ F1" modudur. Bu modda, fare imleci yardım imlecine dönüşür ve kullanıcı bir nesneye tıklamaya devam eder. Bu noktada, kullanıcının tıklandığı nesne için yardım vermek üzere WinHelp başlatılır.
Microsoft Foundation Sınıfları bu yardım biçimlerinden her ikisini de uygular. Ayrıca çerçeve, Yardım Dizini ve Yardım Kullanma olmak üzere iki basit yardım komutunu destekler.
Yardım Dosyaları
Microsoft Foundation sınıfları tek bir Yardım dosyası varsayılır. Bu Yardım dosyasının adı ve yolu uygulamayla aynı olmalıdır. Örneğin, yürütülebilir dosya C:\MyApplication\MyHelp.exe ise, yardım dosyası C:\MyApplication\MyHelp.hlp olmalıdır. CWinApp Sınıfının m_pszHelpFilePath üye değişkeni aracılığıyla yolu ayarlarsınız.
Yardım Bağlam Aralıkları
MFC'nin varsayılan uygulaması, bir programın Yardım bağlam kimliklerinin ataması ile ilgili bazı kuralları izlemesini gerektirir. Bu kurallar, belirli denetimlere ayrılmış bir kimlik aralığıdır. Yardımla ilgili çeşitli üye işlevlerinin farklı uygulamalarını sağlayarak bu kuralları geçersiz kılabilirsiniz.
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_
Basit "Yardım" Komutları
Microsoft Foundation Sınıfları tarafından uygulanan iki basit Yardım komutu vardır:
CWinApp::OnHelpIndex tarafından uygulanan ID_HELP_INDEX
CWinApp::OnHelpUsing tarafından uygulanan ID_HELP_USING
İlk komut, uygulamanın Yardım dizinini gösterir. İkincisi, WinHelp programını kullanma konusunda kullanıcı yardımını gösterir.
Bağlama Duyarlı Yardım (F1 Yardımı)
F1 anahtarı genellikle ana pencerenin hızlandırıcı tablosuna yerleştirilen bir hızlandırıcı tarafından ID_HELP kimliğine sahip bir komuta çevrilir. ID_HELP komutu, ana pencerede veya iletişim kutusunda ID_HELP kimliğine sahip bir düğme tarafından da oluşturulabilir.
ID_HELP komutunun nasıl oluşturulduğundan bağımsız olarak, bir komut işleyicisine ulaşana kadar normal bir komut olarak yönlendirilir. MFC komut yönlendirme mimarisi hakkında daha fazla bilgi için Teknik Not 21'e bakın. Uygulamada Yardım etkinleştirildiyse, ID_HELP komutu CWinApp::OnHelp tarafından işlenir. Uygulama nesnesi yardım iletisini alır ve komutu uygun şekilde yönlendirir. Varsayılan komut yönlendirme en belirli bağlamı belirlemek için yeterli olmadığından bu gereklidir.
CWinApp::OnHelp WinHelp'i aşağıdaki sırayla başlatmayı dener:
Yardım Kimliği ile etkin
AfxMessageBoxbir çağrıyı denetler. Bir ileti kutusu şu anda etkinse, WinHelp bu ileti kutusuna uygun bağlamla başlatılır.Etkin pencereye bir WM_COMMANDHELP iletisi gönderir. Bu pencere WinHelp başlatılarak yanıt vermezse, ileti işlenene veya geçerli pencere en üst düzey pencere olana kadar aynı ileti bu pencerenin üst düzeylerine gönderilir.
Ana pencereye bir ID_DEFAULT_HELP komutu gönderir. Bu, varsayılan Yardım'ı çağırır. Bu komut genellikle ile
CWinApp::OnHelpIndexeşlenir.
Varsayılan kimlik temel değerlerini (örneğin, komutlar için 0x10000 ve iletişim kutuları gibi kaynaklar için 0x20000) genel olarak geçersiz kılmak için uygulamanın CWinApp::WinHelp'i geçersiz kılması gerekir.
Bu işlevselliği ve Yardım bağlamını belirleme biçimini geçersiz kılmak için WM_COMMANDHELP iletisini işlemeniz gerekir. Yalnızca geçerli MDI alt penceresi kadar derin olduğundan çerçevenin sağladığından daha ayrıntılı Yardım yönlendirmesi sağlamak isteyebilirsiniz. Ayrıca, söz konusu nesnenin geçerli iç durumuna veya iletişim kutusundaki etkin denetime bağlı olarak belirli bir pencere veya iletişim kutusu için daha belirgin yardım sağlamak isteyebilirsiniz.
WM_COMMANDHELP
afx_msg LRESULT CWnd::OnCommandHelp(WPARAM wParam, LPARAM lParam)
WM_COMMANDHELP, Yardım istendiğinde etkin pencere tarafından alınan özel bir Windows MFC iletisidir. Pencere bu iletiyi aldığında, pencerenin iç durumuyla eşleşen bağlamla çağrı CWinApp::WinHelp yapabilir.
Lparam
Şu anda kullanılabilir Olan Yardım bağlamını içerir. Yardım bağlamı belirlenmezse lParam sıfırdır. uygulamasıOnCommandHelp, farklı bir bağlam belirlemek için lParam'daki bağlam kimliğini kullanabilir veya yalnızca öğesine CWinApp::WinHelpgeçirebilir.
Wparam
Kullanılmaz ve sıfır olur.
OnCommandHelp İşlev çağırırsa CWinApp::WinHelpTRUE döndürmelidir. TRUE döndürülerek bu komutun diğer sınıflara ve diğer pencerelere yönlendirilmesi durdurulur.
Yardım Modu (Shift+F1 Yardımı)
Bu, bağlama duyarlı Yardım'ın ikinci biçimidir. Bu mod genellikle SHIFT+F1 tuşlarına basılarak veya menü/araç çubuğu aracılığıyla girilir. Komut olarak uygulanır (ID_CONTEXT_HELP). İleti filtresi kancası, kalıcı bir iletişim kutusu veya menü etkinken bu komutu çevirmek için kullanılmaz, bu nedenle bu komut yalnızca uygulama ana ileti pompasını (CWinApp::Run ) yürütürken kullanıcı tarafından kullanılabilir.
Bu moda girdikten sonra, uygulama normalde söz konusu alan için kendi imlecini görüntülese bile (pencerenin etrafındaki boyutlandırma kenarlığı gibi) Yardım fare imleci uygulamanın tüm alanları üzerinde görüntülenir. Kullanıcı bir komut seçmek için fareyi veya klavyeyi kullanabilir. Komutu yürütmek yerine, bu komutla ilgili Yardım görüntülenir. Ayrıca kullanıcı, araç çubuğundaki bir düğme gibi ekranda görünen bir nesneye tıklayabilir ve bu nesne için Yardım görüntülenir. Bu Yardım modu tarafından CWinApp::OnContextHelpsağlanır.
Bu döngünün yürütülmesi sırasında, menüye erişen tuşlar dışında tüm klavye girişi etkin değildir. Ayrıca, kullanıcının bir hızlandırıcı tuşuna basıp bu komutla ilgili yardım almasına izin vermek için komut çevirisi yine aracılığıyla PreTranslateMessage gerçekleştirilir.
İşlevde PreTranslateMessage SHIFT+F1 Yardım modu sırasında gerçekleşmemesi gereken belirli çeviriler veya eylemler varsa, bu işlemleri gerçekleştirmeden önce öğesinin m_bHelpMode üyesini CWinApp denetlemeniz gerekir. CDialog uygulamasıPreTranslateMessage, örneğin çağrısından IsDialogMessageönce bunu denetler. Bu, SHIFT+F1 modu sırasında modsuz iletişim kutularındaki "iletişim kutusu gezintisi" tuşlarını devre dışı bırakır. Ayrıca, CWinApp::OnIdle bu döngü sırasında hala çağrılır.
Kullanıcı menüden bir komut seçerse, bu komut üzerinde yardım olarak işlenir (WM_COMMANDHELP aracılığıyla aşağıya bakın). Kullanıcı uygulamalar penceresinin görünür bir alanına tıklarsa, bunun istemci olmayan bir tıklama mı yoksa istemci tıklaması mı olduğu konusunda bir belirleme yapılır. OnContextHelp , istemci olmayan tıklamaların istemci tıklamalarına otomatik olarak eşlemesini işler. Bu bir istemci tıklamasıysa, tıklanan pencereye bir WM_HELPHITTEST gönderir. Bu pencere sıfır olmayan bir değer döndürürse, bu değer yardım bağlamı olarak kullanılır. Sıfır döndürürse, OnContextHelp üst pencereyi dener (ve bunu, üst penceresini vb. başarısız olur). Bir Yardım bağlamı belirlenemezse, varsayılan değer ana pencereye bir ID_DEFAULT_HELP komutu göndermektir ve bu komut (genellikle) ile CWinApp::OnHelpIndexeşlenir.
WM_HELPHITTEST
afx_msg LRESULT CWnd::OnHelpHitTest(
WPARAM, LPARAM lParam)
WM_HELPHITTEST, SHIFT+F1 Yardım modu sırasında tıklanan etkin pencere tarafından alınan bir MFC özel windows iletisidir. Pencere bu iletiyi aldığında, WinHelp tarafından kullanılmak üzere bir DWORD Yardım Kimliği döndürür.
LOWORD(lParam), pencerenin istemci alanına göre farenin tıklandığı X ekseni cihaz koordinatını içerir.
HIWORD(lParam), Y ekseni koordinatını içerir.
Wparam
kullanılmaz ve sıfır olur. Dönüş değeri sıfır değilse, WinHelp bu bağlamla çağrılır. Dönüş değeri sıfırsa, yardım için üst pencere sorgulanır.
Çoğu durumda, zaten sahip olabileceğiniz isabet testi kodunu kullanabilirsiniz. WM_HELPHITTEST iletisini işleme örneği için uygulamasını CToolBar::OnHelpHitTest inceleyin (kod, içindeki düğmeler ve araç ipuçlarında kullanılan isabet testi kodundan CControlBaryararlanıyor).
MFC Uygulama Sihirbazı Desteği ve MAKEHM
MFC Uygulama Sihirbazı, bir Yardım dosyası (.cnt ve .hpj dosyaları) oluşturmak için gerekli dosyaları oluşturur. Ayrıca, Microsoft Yardım Derleyicisi tarafından kabul edilen bir dizi önceden oluşturulmuş .rtf dosyası içerir. Konuların çoğu tamamlanır, ancak belirli bir uygulama için bazı konuların değiştirilmesi gerekebilir.
"Yardım eşleme" dosyasının otomatik olarak oluşturulması MAKEHM adlı bir yardımcı program tarafından desteklenir. MAKEHM yardımcı programı bir uygulamanın RESOURCE değerini çevirebilir. Yardım eşleme dosyasına H dosyası. Örnek:
#define IDD_MY_DIALOG 2000
#define ID_MY_COMMAND 150
şu şekilde çevrilecek:
HIDD_MY_DIALOG 0x207d0
HID_MY_COMMAND 0x10096
Bu biçim, bağlam kimliklerini (sağ taraftaki sayılar) konu adlarıyla (sol taraftaki simgeler) eşleyen Yardım derleyicisinin tesisiyle uyumludur.
MAKEHM'nin kaynak kodu MFC Programlama Yardımcı Programları örneği MAKEHM'de kullanılabilir.
MFC Uygulama Sihirbazı'nı Çalıştırdıktan Sonra Yardım Desteği Ekleme
Uygulamanıza Yardım eklemenin en iyi yolu, uygulamanızı oluşturmadan önce MFC Uygulama Sihirbazı'nın Gelişmiş Özellikler sayfasındaki "Bağlama duyarlı Yardım" seçeneğini denetlemektir. Bu şekilde MFC Uygulama Sihirbazı, Yardım'ı desteklemek için türetilmiş sınıfınıza CWinAppgerekli ileti eşleme girdilerini otomatik olarak ekler.
İleti Kutularıyla ilgili Yardım
windows API'sine yönelik bir sarmalayıcı olan işlev aracılığıyla AfxMessageBox İleti Kutuları (bazen uyarı olarak da adlandırılır) ile ilgili MessageBox yardım desteklenir.
biri dize kimliğiyle, diğeri de dize işaretçisiLPCSTR () ile kullanılmak üzere iki sürümü AfxMessageBoxvardır:
int AFXAPI AfxMessageBox(LPCSTR lpszText,
UINT nType,
UINT nIDHelp);
int AFXAPI AfxMessageBox(UINT nIDPrompt,
UINT nType,
UINT nIDHelp);
Her iki durumda da isteğe bağlı bir Yardım Kimliği vardır.
İlk durumda, nIDHelp için varsayılan değer 0'dır ve bu da bu ileti kutusu için Yardım olmadığını gösterir. İleti kutusu etkinken kullanıcı F1 tuşuna basarsa, kullanıcı Yardım almaz (uygulama Yardım'ı desteklese bile). Bu istenmiyorsa, nIDHelp için bir Yardım Kimliği sağlanmalıdır.
İkinci durumda, nIDHelp için varsayılan değer -1'dir ve bu, Yardım Kimliğinin nIDPrompt ile aynı olduğunu gösterir. Yardım yalnızca uygulama Yardım etkinse çalışır, elbette). İleti kutusunun yardım desteği olmamasını istiyorsanız nIDHelp için 0 sağlamanız gerekir. İletinin Yardım'ın etkinleştirilmesini, ancak nIDPrompt'tan farklı bir yardım kimliği istemeniz durumunda nIDHelp için nIDPrompt değerinden farklı bir pozitif değer sağlamanız yeterlidir.