How to: Implement HTML Help Text Pop-Ups in un'applicazione MFC

Implementazione di finestre popup di testo utilizzando una matrice di ID Guida

1. Utilizzando un editor di testo, creare un file txt nel seguente formato:

   .topic help-id
   text to be displayed
   						

   il seguente, denominato "Popups.txt", è un esempio:

   .topic IDH_HT_VSCROLL
   Vertical Scroll
   
   .topic IDH_FILE_OPEN
   Open a File
   
   .topic IDH_FILE_NEW
   Create A New File
   
   .topic IDH_FILE_SAVE
   Save a File
   					

2. Includere il file di testo popup nella sezione [testo popup] del file di progetto della Guida HTML. A tale scopo, fare clic sul pulsante HTML Help API informazioni quindi popup di testo e File di testo per aggiungere il file di testo. Salvare il progetto.
3. Gli ID di fatto riferimento nel file testo, ad esempio HID_FILE_SAVE e HID_FILE_NEW nel passaggio precedente, devono essere definiti in un file di inclusione, quali questo denominato "Context.h:"

   #define IDH_FILE_NEW 1
   #define IDH_FILE_OPEN 2
   #define IDH_FILE_SAVE 3
   #define IDH_EDIT_CUT 4
   #define IDH_EDIT_COPY 5 
   #define IDH_EDIT_PASTE 6
   #define IDH_FILE_PRINT 7
   #define IDH_APP_ABOUT 8 
   #define IDH_FILE_PRINT_PREVIEW 9
   #define IDH_BUTTON1 10
   					

4. Il file "Context.h" deve essere compilato nel progetto della Guida HTML. Per effettuare questa operazione, fare clic sul pulsante HTML Help API informazioni quindi popup di testo e File di intestazione per aggiungere il file di intestazione. Dopo questo passaggio, la sezione [testo popup] necessario due file. Dovrebbe avere il file di testo testo popup dell'e il file di inclusione, ad esempio:

   [TEXT POPUPS]
   popups.txt
   context.h
   						

   Salva il progetto e compilarlo.
   
   I passaggi successivi implicano la modifica dell'applicazione MFC, quindi chiudere HTML Help Workshop e aprire l'applicazione in Visual Studio.
5. Dichiarare una matrice in qualsiasi modulo utilizza l'API per visualizzare finestre popup di testo (vedere il passaggio 7 per ulteriori informazioni su dove dovrebbe essere). La matrice contiene coppie di ID dei controlli e i relativi ID Guida corrispondente. La matrice deve terminare con uno 0. Seguito è riportato un esempio:

   //Declare an array of control id - help id pairs. The array must have 0 as the last element.
   
   DWORD ids[7] ; 
   ids[0] = ID_FILE_OPEN; ids[1] = IDH_FILE_OPEN;
   ids[2] = ID_FILE_NEW;  ids[3] = IDH_FILE_NEW; 
   ids[4] = ID_FILE_SAVE; ids[5] = IDH_FILE_SAVE; 
   ids[6]= 0;
   #define numHelpIDs 3
   					

6. Includere il file di intestazione per l'ID di Guida. In questo esempio sarebbe la seguente:

   #include "context.h"
   					

7. Esistono diverse posizioni in cui "della Guida rapida" nella Guida può essere implementato. Questo passaggio vengono descritti metodi per aggiungere una tale Guida in tre punti:
   
   
   1. Per aggiungere della ? quali ? Guida a una finestra di dialogo, assicurarsi che l'opzione Guida sensibile al contesto sia selezionata nella casella proprietà Stili estesi nell'editor delle risorse. Quindi eseguire l'override del metodo di OnHelpInfo() mediante la creazione guidata classe. Seguito è riportato un esempio:

      BOOL CMyDialog::OnHelpInfo(HELPINFO* pHelpInfo) 
      {
       HtmlHelp((HWND)pHelpInfo->hItemHandle, "sample.chm::/popups.txt",HH_TP_HELP_WM_HELP,(DWORD) ids);
      	  return CDialog::OnHelpInfo(pHelpInfo);
      
      }

   2. Per aggiungere "della Guida rapida" Guida per la finestra principale di, eseguire l'override CWinApp::Winhelp, verificare il parametro nCmd per verificare se è HELP_CONTEXT. Se è, potrebbe essere F1 o "Qual questa Guida". Se si desidera gestire questi tipi di Guida in linea nello stesso modo, quindi non è necessario conoscere quali uno è. Se si desidera modificare il tipo di Guida che verrà visualizzata per ciascuno dei comandi, è necessario determinare il tipo di Guida in linea viene richiamato. Un modo per ignorare il comando CMainFrame::OnContextHelp. Quando il cursore della ? quali ? si fa clic sulla finestra cornice, il framework chiama questa routine. Eseguire l'override questa funzione per impostare un flag per indicare che ? della Guida rapida ? Guida è stata richiamata. Quando l'utente fa quindi clic su un controllo, viene richiamata la funzione CWinApp::Winhelp. Nella funzione CWinApp::Winhelp, se HELP_CONTEXT è il comando ricevuto, controllare il flag. Seguito è riportato un esempio del metodo CMainFrame::OnContextHelp e il metodo CWinApp::WinHelp:

      void CMainFrame::OnContextHelp()
       {
      	((CNEWTEXTPOPApp *) AfxGetApp())->m_bWhatsThisHelp = TRUE;
      	CMDIFrameWnd::OnContextHelp();
      }
      
      
      void CNEWTEXTPOPApp::WinHelp(DWORD dwData, UINT nCmd)
      {
         DWORD i;
         DWORD ids[3];
      
         i=nCmd;
      
         switch (nCmd)
         {
         case HELP_CONTEXT:
            for (i= 0; i < numHelpIDs*2; i+=2)
              {
      	if(  (aMenuHelpIDs[i] == LOWORD (dwData) ) )
      	{
      		if (m_bWhatsThisHelp)
      		{
      			m_bWhatsThisHelp = FALSE;
      		 	i++;
      			
      			ids[1] = aMenuHelpIDs[i];
      			ids[2] = 0;
         
      		        	ids[0]= ((CMainFrame *)m_pMainWnd)->GetDlgCtrlID();
      			HWND atest = ((CMainFrame *)m_pMainWnd)->m_hWnd;
      
                      		HtmlHelp(atest, "sample.chm::/popups.txt",HH_TP_HELP_WM_HELP,(DWORD) ids);
      
      			return;
      		  }
      		  else
      		  {
      			// If F1 help was selected, use HH_HELP_CONTEXT..			
      			HtmlHelp(m_pMainWnd->m_hWnd, "F:\\HTML H Context Help\\test\\sample.chm",HH_HELP_CONTEXT, aMenuHelpIDs[i+1]);
      			return;
                         }
                }
                }
          break;
         }
      }
      							

   3. "Guida rapida" Guida per una visualizzazione, ad esempio una visualizzazione form segue lo stesso percorso comando come per la finestra cornice. Il controllo passi la CFrameWindow::OnContextHelp quindi a CWinApp::Winhelp. È necessario intercettare il framework tra queste due funzioni per impostare l'ID del controllo appropriato. È possibile eseguire questa operazione manualmente (è Impossibile utilizzare la creazione guidata classe) eseguendo l'override del metodo OnHelpHitTest.
      
      Questo comprende tre passaggi:
      
      
      1. In primo luogo, aggiungere il metodo OnHelpHitTest la mappa messaggi della classe di visualizzazione:

         BEGIN_MESSAGE_MAP(MyFormView, CFormView)
         	//{{AFX_MSG_MAP(MyFormView)
         	//}}AFX_MSG_MAP
         	ON_MESSAGE(WM_HELPHITTEST, OnHelpHitTest)
         END_MESSAGE_MAP()

      2. Successivamente, aggiungere il prototipo per OnHelpHitTest alla visualizzazione del file di inclusione:

         LRESULT OnHelpHitTest(WPARAM wParam, LPARAM lParam);

      3. Infine, aggiungere il metodo OnHelpHitTest la classe di visualizzazione. il lParam passato contiene la posizione di mouse del cursore. Per determinare l'ID del controllo, verificare se il mouse si trova su un controllo. Se si tratta di, è possibile restituire l'ID del controllo. Il framework chiamerà quindi CWinApp::CWinHelp con tale ID di controllo. In alternativa, è possibile visualizzare il messaggio di testo popup da OnHelpHitTest e impostare un flag per impedire che guida la gestione del messaggio nuovamente. Seguito è riportato un esempio di quest'ultimo:

         LRESULT MyFormView::OnHelpHitTest(WPARAM wParam, LPARAM lParam)
         {
         	CWnd *pCtrl;
         	RECT ctrlRect;
         	CRect ctrlCRect;
         	CPoint HitPt;
         	int i;
         	CRect rectView;
         
         // Get View's Rectangle
         	GetWindowRect(&rectView);
         
         // HitPt is where the mouse clicked in screen coordinates but
         // relative to the view window.
         	HitPt.x = LOWORD (lParam);  
         	HitPt.y = HIWORD (lParam);
         
         // Make the screen coordinates relative to the main window
         // since controls coords will be.
         	HitPt.x+= rectView.left;
         	HitPt.y+= rectView.top;
         
         // Look at the screen coords for each control
         	for (i=0; i < NUM_CONTROLS; i++){
         		pCtrl =  GetDlgItem(ViewControlIds[i]);  // get a ptr to a control id
         		if (pCtrl == NULL) return (0);
               		pCtrl->GetWindowRect(&ctrlRect);     // get control's rectangle
         `		ctrlCRect = ctrlRect;                // convert to CRect for next
         
         	  	if (ctrlCRect.PtInRect(HitPt)){       // if point was in Control's rect
         	  		((CNEWTEXTPOPApp *) AfxGetApp())->m_bWhatsThisHelp = TRUE;
         			return (ViewControlIds[i]);         // pass help id to Winhelp
               		} 
         
         	}
           	i++;  // point past help control id
         	return 0;          // if not on control pass 0 to let winhelp handle
         } 
         									

Implementazione di finestre popup di testo mediante una struttura HH_POPUP

typedef struct tagHH_POPUP
{
    int       cbStruct;      // sizeof this structure
    HINSTANCE hinst;         // instance handle for string resource
    UINT      idString;      // string resource ID, or text ID if szFile is specified in HtmlHelp call
    LPCTSTR   pszText;       // used if idString is zero
    POINT     pt;            // top center of popup window
    COLORREF  clrForeground; // use -1 for default
    COLORREF  clrBackground; // use -1 for default
    RECT      rcMargins;     // amount of space between edges of window and text, -1 for each member to ignore
    LPCTSTR   pszFont;       // facename, point size, char set, BOLD ITALIC UNDERLINE
} HH_POPUP;
				

// Define a structure to save the control IDs and the text strings for<BR/>
// them.


struct MyStrings_Struct
{
	DWORD control_id;    
	CHAR   myString[80];
} MyStrings[2];

// Initialize the structure.
MyStrings[0].control_id = ID_FILE_OPEN;
strcpy(MyStrings[0].myString , "This opens the file.\n");
MyStrings[1].control_id = ID_FILE_NEW;
strcpy(MyStrings[1].myString , "This opens a new file.\n");

// Declare the popup structure and initialize it.
HH_POPUP        myPopup;

memset(&amp;myPopup, 0, sizeof(HH_POPUP) );          // Fill in the popup 
structure
myPopup.cbStruct = sizeof(HH_POPUP);
myPopup.pt.x = r.left;
myPopup.pt.y = r.bottom;
myPopup.rcMargins.top    = 5;
myPopup.rcMargins.bottom = 5;
myPopup.rcMargins.left   = 5;
myPopup.rcMargins.right  = 5;
myPopup.idString =  0;   // set the ID string to 0

// search for the control id in the control array, put the help control ID in the HH_POPUP array.

for( i=0; i < MY_ARRAY_SIZE; i+=2 )
 {
     if  (MyControlId ==  MyStrings[i].control_id ) 
     { 
              strcpy(MyPopup.pszText, MyStrings[i].myString);
        HtmlHelp( this->m_hWnd, NULL, HH_DISPLAY_TEXT_POPUP, (DWORD) &myPopup);
	return;
   }
}
				

Torna all'inizio | Invia suggerimenti