TN028: Context-Sensitive Destek Yardımı

Uyarı

Microsoft Foundation Sınıfları (MFC) kitaplığına destek verilmeye devam ediliyor. Ancak artık özellik eklemeyeceğiz veya belgeleri güncelleştirmeyeceğiz.

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 Studio'da kullanılabilen yardım derleyicisini gerektirir.

Uyarı

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ı: Context-Sensitive Programlarınız için 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ı kullanılacağını varsayar. 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ınm_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

• ID_HELP_USING, CWinApp::OnHelpUsing tarafından gerçekleştirilen

İlk komut, uygulamanın Yardım dizinini gösterir. İkincisi, WinHelp programını kullanma konusunda kullanıcı yardımını gösterir.

Context-Sensitive Yardımı (F1 Yardımı)

F1 tuşu genellikle ana pencerenin hızlandırıcı tablosuna yerleştirilen bir hızlandırıcı aracılığıyla ID_HELP kimliğine sahip bir komuta dönüştürülür. 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:

1. Yardım Kimliği ile ilişkili aktif bir AfxMessageBox çağrıyı denetler. Şayet bir ileti kutusu şu anda etkinse, WinHelp, bu ileti kutusuna uygun bağlam ile başlatılır.

2. 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.

3. Ana pencereye bir ID_DEFAULT_HELP komutu gönderir. Bu, varsayılan Yardım'ı çağırır. Bu komut genellikle CWinApp::OnHelpIndex ile eş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, uygulama CWinApp::WinHelp'i geçersiz kılmalıdır.

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. Çerçevenin sağladığı yönlendirme yalnızca geçerli MDI alt penceresi kadar derin olduğu için, daha ayrıntılı bir Yardım yönlendirmesi sağlamayı düşünebilirsiniz. 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 mesajı aldığında, pencerenin iç durumuyla eşleşen bağlamda CWinApp::WinHelp çağrılabilir.

lParam
Şu anda kullanılabilir Olan Yardım bağlamını içerir. Yardım bağlamı belirlenmezse lParam sıfırdır. Bir OnCommandHelp uygulaması, farklı bir bağlam belirlemek için lParam'daki bağlam kimliğini kullanabilir veya bu kimliği yalnızca CWinApp::WinHelp öğesine geçirebilir.

wParam
Kullanılmaz ve sıfır olur.

OnCommandHelp işlevi CWinApp::WinHelp çağırıyorsa, TRUE 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 modunda 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 önce üst pencereyi dener (eğer bu başarısız olursa, onun üst penceresini dener, ve bu şekilde devam eder). Bir Yardım bağlamı belirlenemezse, varsayılan işlem ana pencereye "ID_DEFAULT_HELP" komutu göndermektir ve bu komut (genellikle) CWinApp::OnHelpIndex ile eşlenir.

WM_HELPHITTEST

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

WM_HELPHITTEST, SHIFT+F1 Yardım modundayken tıklanan etkin pencere tarafından alınan bir MFC özel Windows mesajıdır. 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 ana pencere sorgulanır.

Çoğu durumda, zaten sahip olabileceğiniz isabet testi kodunu kullanabilirsiniz. WM_HELPHITTEST mesajını nasıl işleyebileceğinize dair bir örnek için bu uygulamayı CToolBar::OnHelpHitTest inceleyin (kod, CControlBar içindeki düğmelerde ve araç ipuçlarında kullanılan isabet testi kodundan yararlanı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.H dosyasını Yardım eşleme dosyasına dönüştürebilir. Örneğin:

#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

AfxMessageBox Windows API'si için bir sarmalayıcı olan MessageBox işlevi aracılığıyla İleti Kutuları (bazen uyarı olarak da adlandırılır) hakkında yardım sağlanır.

biri dize kimliğiyle, diğeri de dize işaretçisiAfxMessageBox () ile kullanılmak üzere iki sürümü LPCSTRvardı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. Uygulama yardım ile etkinleştirilmişse, yardım elbette çalışır. İleti kutusunun yardım desteği olmamasını istiyorsanız nIDHelp için 0 sağlamanız gerekir. Mesajın Yardım ile etkinleştirilmesini isteyip, nIDPrompt'tan farklı bir yardım kimliği talep etmeniz durumunda, nIDHelp için nIDPrompt değerinden farklı bir pozitif değer sağlamanız yeterlidir.

Ayrıca bakınız

Numaraya Göre Teknik Notlar
Kategorilere Göre Teknik Notlar