CDialog-klass

Basklassen som används för att visa dialogrutor på skärmen.

Syntax

class CDialog : public CWnd

Medlemmar

Offentliga konstruktorer

Offentliga metoder

Skyddade metoder

Anmärkningar

Dialogrutor är av två typer: modala och lägeslösa. En modal dialogruta måste stängas av användaren innan programmet fortsätter. Med en lägeslös dialogruta kan användaren visa dialogrutan och återgå till en annan uppgift utan att avbryta eller ta bort dialogrutan.

Ett CDialog objekt är en kombination av en dialogmall och en CDialog-derived-klass. Använd dialogredigeraren för att skapa dialogmallen och lagra den i en resurs och använd sedan guiden Lägg till klass för att skapa en klass som härletts från CDialog.

En dialogruta, precis som andra fönster, tar emot meddelanden från Windows. I en dialogruta är du särskilt intresserad av att hantera meddelanden från dialogrutans kontroller eftersom det är så användaren interagerar med din dialogruta. Använd klassguiden för att välja vilka meddelanden du vill hantera och lägga till lämpliga posterna för meddelandekarta och medlemsfunktioner för meddelandehanteraren i klassen åt dig. Du behöver bara skriva programspecifik kod i hanteringsmedlemsfunktionerna.

Om du vill kan du alltid skriva posterna i meddelandekartan och medlemsfunktionerna manuellt.

I alla utom den mest triviala dialogrutan lägger du till medlemsvariabler i din härledda dialogklass för att lagra data som anges i dialogrutans kontroller av användaren eller för att visa data för användaren. Du kan använda guiden Lägg till variabel för att skapa medlemsvariabler och associera dem med kontroller. Samtidigt väljer du en variabeltyp och tillåtet värdeintervall för varje variabel. Kodguiden lägger till medlemsvariablerna i din härledda dialogklass.

En datakarta genereras för att automatiskt hantera datautbytet mellan medlemsvariablerna och dialogrutans kontroller. Datakartan innehåller funktioner som initierar kontrollerna i dialogrutan med rätt värden, hämtar data och validerar data.

Om du vill skapa en modal dialogruta skapar du ett objekt i stacken med konstruktorn för din härledda dialogklass och anropar DoModal sedan för att skapa dialogfönstret och dess kontroller. Om du vill skapa en lägeslös dialogruta anropar Create du konstruktorn för din dialogklass.

Du kan också skapa en mall i minnet med hjälp av en DLGTEMPLATE-datastruktur enligt beskrivningen i Windows SDK. När du har skapat ett CDialog objekt anropar du CreateIndirect för att skapa en lägeslös dialogruta eller anropar InitModalIndirect och DoModal för att skapa en modal dialogruta.

Datakartan för utbyte och validering skrivs i en åsidosättning av CWnd::DoDataExchange som läggs till i den nya dialogklassen. Mer information om exchange- och valideringsfunktionerna finns i funktionen DoDataExchange member in CWnd .

Både programmeraren och ramverket anropar DoDataExchange indirekt via ett anrop till CWnd::UpdateData.

Ramverket anropar UpdateData när användaren klickar på OK-knappen för att stänga en modal dialogruta. (Data hämtas inte om knappen Avbryt klickas.) Standardimplementeringen av OnInitDialog anropar UpdateData också för att ange de inledande värdena för kontrollerna. Du åsidosätter OnInitDialog vanligtvis för att ytterligare initiera kontroller. OnInitDialog anropas när alla dialogkontroller har skapats och precis innan dialogrutan visas.

Du kan när som helst anropa CWnd::UpdateData under körningen av en modal eller lägeslös dialogruta.

Om du utvecklar en dialogruta för hand lägger du själv till nödvändiga medlemsvariabler i den härledda dialogruteklassen och lägger till medlemsfunktioner för att ange eller hämta dessa värden.

En modal dialogruta stängs automatiskt när användaren trycker på OK- eller Avbryt-knapparna eller när koden anropar EndDialog medlemsfunktionen.

När du implementerar en lägeslös dialogruta åsidosätter OnCancel du alltid medlemsfunktionen och anropar DestroyWindow inifrån den. Anropa inte basklassen CDialog::OnCanceleftersom den anropar EndDialog, vilket gör dialogrutan osynlig men kommer inte att förstöra den. Du bör också åsidosätta PostNcDestroy för lägeslösa dialogrutor för att ta bort thiseftersom lägeslösa dialogrutor vanligtvis allokeras med new. Modala dialogrutor skapas vanligtvis i ramen och behöver PostNcDestroy inte rensas.

Mer information om CDialogfinns i Dialogrutor.

Arvshierarki

CObject

CCmdTarget

CWnd

CDialog

Kravspecifikation

rubrik: afxwin.h

CDialog::CDialog

Om du vill skapa en resursbaserad modal-dialogruta anropar du antingen den offentliga formen av konstruktorn.

explicit CDialog(
    LPCTSTR lpszTemplateName,
    CWnd* pParentWnd = NULL);

explicit CDialog(
    UINT nIDTemplate,
    CWnd* pParentWnd = NULL);

CDialog();

Parameterar

lpszTemplateName
Innehåller en null-avslutad sträng som är namnet på en mallresurs i dialogrutan.

nIDTemplate
Innehåller ID-numret för en mallresurs i dialogrutan.

pParentWnd
Pekar på det överordnade eller ägarfönsterobjektet (av typen CWnd) som dialogobjektet tillhör. Om det är NULL är dialogobjektets överordnade fönster inställt på huvudprogrammets fönster.

Anmärkningar

En form av konstruktorn ger åtkomst till dialogresursen efter mallnamn. Den andra konstruktorn ger åtkomst via mall-ID-nummer, vanligtvis med ett IDD_ prefix (till exempel IDD_DIALOG1).

Om du vill skapa en modal dialogruta från en mall i minnet anropar du först den parameterlösa, skyddade konstruktorn och anropar InitModalIndirectsedan .

När du har skapat en modal dialogruta med någon av metoderna ovan anropar du DoModal.

Om du vill skapa en lägeslös dialogruta använder du konstruktorns CDialog skyddade form. Konstruktorn är skyddad eftersom du måste härleda din egen dialogruteklass för att implementera en lägeslös dialogruta. Att skapa en lägeslös dialogruta är en tvåstegsprocess. Anropa först konstruktorn. anropa Create sedan medlemsfunktionen för att skapa en resursbaserad dialogruta eller anropa CreateIndirect för att skapa dialogrutan från en mall i minnet.

CDialog::Skapa

Anropa Create för att skapa en lägeslös dialogruta med hjälp av en dialogrutemall från en resurs.

virtual BOOL Create(
    LPCTSTR lpszTemplateName,
    CWnd* pParentWnd = NULL);

virtual BOOL Create(
    UINT nIDTemplate,
    CWnd* pParentWnd = NULL);

Parameterar

lpszTemplateName
Innehåller en null-avslutad sträng som är namnet på en mallresurs i dialogrutan.

pParentWnd
Pekar på det överordnade fönsterobjektet (av typen CWnd) som dialogobjektet tillhör. Om det är NULL är dialogobjektets överordnade fönster inställt på huvudprogrammets fönster.

nIDTemplate
Innehåller ID-numret för en mallresurs i dialogrutan.

Returvärde

Båda formulären returnerar nonzero om skapande och initiering av dialogrutor lyckades. annars 0.

Anmärkningar

Du kan placera anropet Create i konstruktorn eller anropa det när konstruktorn har anropats.

Två former av Create medlemsfunktionen tillhandahålls för åtkomst till mallresursen i dialogrutan med antingen mallnamn eller mall-ID-nummer (till exempel IDD_DIALOG1).

För båda formulären skickar du en pekare till det överordnade fönsterobjektet. Om pParentWnd är NULL skapas dialogrutan med dess överordnade fönster eller ägarfönster inställt på huvudprogrammets fönster.

Medlemsfunktionen Create returneras omedelbart efter att dialogrutan har skapats.

Använd formatmallen WS_VISIBLE i dialogrutan om dialogrutan ska visas när det överordnade fönstret skapas. Annars måste du anropa ShowWindow. Mer information om dialogruteformat och deras program finns i DLGTEMPLATE-strukturen i Windows SDK och Fönsterformat i MFC-referensen.

CWnd::DestroyWindow Använd funktionen för att förstöra en dialogruta som skapats av Create funktionen.

Exempel

void CMyDialog::OnMenuShowSimpleDialog()
{
   //m_pSimpleDialog initialized to NULL in the constructor of CMyDialog class
   m_pSimpleDlg = new CSimpleDlg();
   //Check if new succeeded and we got a valid pointer to a dialog object
   if (m_pSimpleDlg != NULL)
   {
      BOOL ret = m_pSimpleDlg->Create(IDD_SIMPLEDIALOG, this);

      if (!ret) //Create failed.
      {
         AfxMessageBox(_T("Error creating Dialog"));
      }

      m_pSimpleDlg->ShowWindow(SW_SHOW);
   }
   else
   {
      AfxMessageBox(_T("Error Creating Dialog Object"));
   }
}

CDialog::CreateIndirect

Anropa den här medlemsfunktionen för att skapa en lägeslös dialogruta från en dialogrutemall i minnet.

virtual BOOL CreateIndirect(
    LPCDLGTEMPLATE lpDialogTemplate,
    CWnd* pParentWnd = NULL,
    void* lpDialogInit = NULL);

virtual BOOL CreateIndirect(
    HGLOBAL hDialogTemplate,
    CWnd* pParentWnd = NULL);

Parameterar

lpDialogTemplate
Pekar på minne som innehåller en dialogrutemall som används för att skapa dialogrutan. Den här mallen är i form av en DLGTEMPLATE-struktur och kontrollinformation, enligt beskrivningen i Windows SDK.

pParentWnd
Pekar på dialogobjektets överordnade fönsterobjekt (av typen CWnd). Om det är NULL är dialogobjektets överordnade fönster inställt på huvudprogrammets fönster.

lpDialogInit
Pekar på en DLGINIT-resurs.

hDialogTemplate
Innehåller en referens till globalt minne som innehåller en dialogrutemall. Den här mallen är i form av en DLGTEMPLATE struktur och data för varje kontroll i dialogrutan.

Returvärde

Nonzero om dialogrutan har skapats och initierats. annars 0.

Anmärkningar

Medlemsfunktionen CreateIndirect returneras omedelbart efter att dialogrutan har skapats.

Använd formatmallen WS_VISIBLE i dialogrutan om dialogrutan ska visas när det överordnade fönstret skapas. Annars måste du anropa ShowWindow för att det ska visas. Mer information om hur du kan ange andra dialogruteformat i mallen finns i strukturen DLGTEMPLATE i Windows SDK.

CWnd::DestroyWindow Använd funktionen för att förstöra en dialogruta som skapats av CreateIndirect funktionen.

Dialogrutor som innehåller ActiveX-kontroller kräver ytterligare information i en DLGINIT-resurs.

CDialog::D oModal

Anropa den här medlemsfunktionen för att anropa den modala dialogrutan och returnera dialogruteresultatet när du är klar.

virtual INT_PTR DoModal();

Returvärde

Ett int värde som anger värdet för parametern nResult som skickades till medlemsfunktionen CDialog::EndDialog , som används för att stänga dialogrutan. Returvärdet är -1 om funktionen inte kunde skapa dialogrutan eller IDABORT om något annat fel uppstod, i vilket fall utdatafönstret innehåller felinformation från GetLastError.

Anmärkningar

Den här medlemsfunktionen hanterar all interaktion med användaren medan dialogrutan är aktiv. Det är detta som gör dialogrutan modal; Användaren kan alltså inte interagera med andra fönster förrän dialogrutan har stängts.

Om användaren klickar på någon av push-knapparna i dialogrutan, till exempel OK eller Avbryt, anropas en medlemsfunktion för meddelandehanteraren, till exempel OnOK eller OnCancel, för att försöka stänga dialogrutan. OnOK Standardmedlemsfunktionen validerar och uppdaterar dialogrutedata och stänger dialogrutan med resultat-IDOK, och standardmedlemsfunktionen OnCancel stänger dialogrutan med resultat-IDCANCEL utan att verifiera eller uppdatera dialogrutedata. Du kan åsidosätta dessa meddelandehanterarfunktioner för att ändra deras beteende.

Exempel

void CMyDialog::OnMenuShowAboutDialog()
{
   // Construct the dialog box passing the
   // ID of the dialog template resource
   CDialog aboutDlg(IDD_ABOUTBOX);

   // Create and show the dialog box
   INT_PTR nRet = -1;
   nRet = aboutDlg.DoModal();

   // Handle the return value from DoModal
   switch (nRet)
   {
   case -1:
      AfxMessageBox(_T("Dialog box could not be created!"));
      break;
   case IDABORT:
      // Do something
      break;
   case IDOK:
      // Do something
      break;
   case IDCANCEL:
      // Do something
      break;
   default:
      // Do something
      break;
   }
}

CDialog::EndDialog

Anropa den här medlemsfunktionen för att avsluta en modal dialogruta.

void EndDialog(int nResult);

Parameterar

nResult
Innehåller värdet som ska returneras från dialogrutan till anroparen för DoModal.

Anmärkningar

Den här medlemsfunktionen returnerar nResult som returvärdet DoModalför . Du måste använda EndDialog funktionen för att slutföra bearbetningen när en modal dialogruta skapas.

Du kan anropa EndDialog när som helst, även i OnInitDialog, i vilket fall du bör stänga dialogrutan innan den visas eller innan indatafokuset anges.

EndDialog stänger inte dialogrutan omedelbart. I stället anger den en flagga som leder till att dialogrutan stängs så snart den aktuella meddelandehanteraren returnerar.

Exempel

void CMyDialog::OnMenuShowSimpleModal()
{
   CSimpleDlg myDlg;
   INT_PTR nRet = myDlg.DoModal();

   if (nRet == IDOK || nRet == 5)
   {
      AfxMessageBox(_T("Dialog closed successfully"));
   }
}

void CSimpleDlg::OnRButtonUp(UINT nFlags, CPoint point)
{
   UNREFERENCED_PARAMETER(nFlags);
   // Do something

   int nRet = point.x; // Just any value would do!
   EndDialog(nRet);    // This value is returned by DoModal!

   // Do something

   return; // Dialog closed and DoModal returns only here!
}

CDialog::GetDefID

GetDefID Anropa medlemsfunktionen för att hämta ID:t för standardknappkontrollen för en dialogruta.

DWORD GetDefID() const;

Returvärde

Ett 32-bitars värde (DWORD). Om standard-pushbuttonen har ett ID-värde innehåller högordningsordet DC_HASDEFID och ordet med låg ordning innehåller ID-värdet. Om standard-pushbuttonen inte har något ID-värde är returvärdet 0.

Anmärkningar

Det här är vanligtvis en OK-knapp.

CDialog::GotoDlgCtrl

Flyttar fokus till den angivna kontrollen i dialogrutan.

void GotoDlgCtrl(CWnd* pWndCtrl);

Parameterar

pWndCtrl
Identifierar det fönster (kontroll) som ska ta emot fokus.

Anmärkningar

Om du vill få en pekare till kontrollen (underordnat fönster) som ska skickas som pWndCtrl anropar CWnd::GetDlgItem du medlemsfunktionen, som returnerar en pekare till ett CWnd-objekt .

Exempel

Se exemplet för CWnd::GetDlgItem.

CDialog::InitModalIndirect

Anropa den här medlemsfunktionen för att initiera ett modalt dialogobjekt med hjälp av en dialogrutemall som du skapar i minnet.

BOOL InitModalIndirect(
    LPCDLGTEMPLATE lpDialogTemplate,
    CWnd* pParentWnd = NULL,
    void* lpDialogInit = NULL);

    BOOL InitModalIndirect(
    HGLOBAL hDialogTemplate,
    CWnd* pParentWnd = NULL);

Parameterar

lpDialogTemplate
Pekar på minne som innehåller en dialogrutemall som används för att skapa dialogrutan. Den här mallen är i form av en DLGTEMPLATE-struktur och kontrollinformation, enligt beskrivningen i Windows SDK.

hDialogTemplate
Innehåller en referens till globalt minne som innehåller en dialogrutemall. Den här mallen är i form av en DLGTEMPLATE struktur och data för varje kontroll i dialogrutan.

pParentWnd
Pekar på det överordnade eller ägarfönsterobjektet (av typen CWnd) som dialogobjektet tillhör. Om det är NULL är dialogobjektets överordnade fönster inställt på huvudprogrammets fönster.

lpDialogInit
Pekar på en DLGINIT-resurs.

Returvärde

Nonzero om dialogobjektet har skapats och initierats. annars 0.

Anmärkningar

Om du vill skapa en modifierad dialogruta indirekt allokerar du först ett globalt minnesblock och fyller det med dialogrutemallen. Anropa sedan den tomma CDialog konstruktorn för att skapa dialogruteobjektet. Anropa sedan InitModalIndirect för att lagra handtaget i dialogrutan i minnet. Dialogrutan Windows skapas och visas senare när funktionen DoModal-medlem anropas.

Dialogrutor som innehåller ActiveX-kontroller kräver ytterligare information i en DLGINIT-resurs.

CDialog::MapDialogRect

Anropa för att konvertera dialogruteenheterna för en rektangel till skärmenheter.

void MapDialogRect(LPRECT lpRect) const;

Parameterar

lpRect
Pekar på en RECT-struktur eller ett CRect-objekt som innehåller de dialogrutekoordinater som ska konverteras.

Anmärkningar

Dialogruteenheter anges i termer av den aktuella dialogrutebasenheten som härleds från den genomsnittliga bredden och höjden på tecken i det teckensnitt som används för dialogrutetext. En vågrät enhet är en fjärdedel av dialogrutans basbreddsenhet och en lodrät enhet är en åttondel av dialogrutans bashöjdsenhet.

GetDialogBaseUnits Windows-funktionen returnerar storleksinformation för systemteckensnittet, men du kan ange ett annat teckensnitt för varje dialogruta om du använder formatet DS_SETFONT i resursdefinitionsfilen. Windows-funktionen MapDialogRect använder lämpligt teckensnitt för den här dialogrutan.

Medlemsfunktionen MapDialogRect ersätter dialogruteenheterna i lpRect med skärmenheter (bildpunkter) så att rektangeln kan användas för att skapa en dialogruta eller placera en kontroll i en ruta.

CDialog::NextDlgCtrl

Flyttar fokus till nästa kontroll i dialogrutan.

void NextDlgCtrl() const;

Anmärkningar

Om fokus ligger på den sista kontrollen i dialogrutan flyttas den till den första kontrollen.

CDialog::OnCancel

Ramverket anropar den här metoden när användaren klickar på Avbryt eller trycker på ESC-tangenten i en modal eller lägeslös dialogruta.

virtual void OnCancel();

Anmärkningar

Åsidosätt den här metoden för att utföra åtgärder (till exempel återställa gamla data) när en användare stänger dialogrutan genom att klicka på Avbryt eller trycka på ESC-nyckeln. Standardinställningen stänger en modal dialogruta genom att anropa EndDialog och göra så att DoModal returnerar IDCANCEL.

Om du implementerar knappen Avbryt i en lägeslös dialogruta måste du åsidosätta OnCancel metoden och anropa DestroyWindow i den. Anropa inte basklassmetoden eftersom den anropar EndDialog, vilket gör dialogrutan osynlig men inte förstör den.

Exempel

void CSimpleDlg::OnCancel()
{
   // TODO: Add extra cleanup here

   // Ensure that you reset all the values back to the
   // ones before modification. This handler is called
   // when the user doesn't want to save the changes.

   if (AfxMessageBox(_T("Are you sure you want to abort the changes?"),
                     MB_YESNO) == IDNO)
   {
      // Give the user a chance if he has unknowingly hit the
      // Cancel button. If he says No, return. Don't reset. If
      // Yes, go ahead and reset the values and close the dialog.
      return;
   }

   m_nMyValue = m_nPrevValue;
   m_pMyString = NULL;

   CDialog::OnCancel();
}

CDialog::OnInitDialog

Den här metoden anropas som svar på meddelandet WM_INITDIALOG .

virtual BOOL OnInitDialog();

Returvärde

Anger om programmet har angett indatafokus till en av kontrollerna i dialogrutan. Om OnInitDialog returnerar nonzero anger Windows indatafokus till standardplatsen, den första kontrollen i dialogrutan. Programmet kan bara returnera 0 om det uttryckligen har angett indatafokus till en av kontrollerna i dialogrutan.

Anmärkningar

Windows skickar WM_INITDIALOG meddelandet till dialogrutan under anropen Skapa, CreateIndirect eller DoModal , som inträffar omedelbart innan dialogrutan visas.

Åsidosätt den här metoden om du vill utföra särskild bearbetning när dialogrutan initieras. I den åsidosatta versionen anropar du först basklassen OnInitDialog men ignorerar dess returvärde. Du returnerar TRUE vanligtvis från den åsidosatta metoden.

Windows anropar OnInitDialog funktionen med hjälp av den globala standarddialogruteproceduren som är gemensam för alla dialogrutor för Microsoft Foundation-klassbibliotek. Den anropar inte den här funktionen via meddelandekartan och därför behöver du ingen post för meddelandekartan för den här metoden.

Exempel

BOOL CSimpleDlg::OnInitDialog()
{
   CDialog::OnInitDialog();

   // TODO: Add extra initialization here
   m_cMyEdit.SetWindowText(_T("My Name")); // Initialize control values
   m_cMyList.ShowWindow(SW_HIDE);          // Show or hide a control, etc.

   return TRUE; // return TRUE unless you set the focus to a control
   // EXCEPTION: OCX Property Pages should return FALSE
}

CDialog::OnOK

Anropas när användaren klickar på OK-knappen (knappen med ett ID för IDOK).

virtual void OnOK();

Anmärkningar

Åsidosätt den här metoden för att utföra åtgärder när OK-knappen aktiveras. Om dialogrutan innehåller automatisk dataverifiering och utbyte validerar standardimplementeringen av den här metoden dialogrutedata och uppdaterar lämpliga variabler i ditt program.

Om du implementerar OK-knappen i en lägeslös dialogruta måste du åsidosätta OnOK metoden och anropa DestroyWindow i den. Anropa inte basklassmetoden eftersom den anropar EndDialog , vilket gör dialogrutan osynlig men inte förstör den.

Exempel

void CSimpleDlg::OnOK()
{
   // TODO: Add extra validation here

   // Ensure that your UI got the necessary input
   // from the user before closing the dialog. The
   // default OnOK will close this.
   if (m_nMyValue == 0) // Is a particular field still empty?
   {
      // Inform the user that he can't close the dialog without
      // entering the necessary values and don't close the
      // dialog.
      AfxMessageBox(_T("Please enter a value for MyValue"));
      return;
   }

   CDialog::OnOK(); // This will close the dialog and DoModal will return.
}

CDialog::OnSetFont

Anger teckensnittet som en dialogrutekontroll ska använda när du ritar text.

Virtual void OnSetFont(CFont* pFont);

Parameterar

pFont
[i] Anger en pekare till teckensnittet som ska användas som standardteckensnitt för alla kontroller i den här dialogrutan.

Anmärkningar

Dialogrutan använder det angivna teckensnittet som standard för alla dess kontroller.

Dialogredigeraren anger vanligtvis dialogruteteckensnittet som en del av mallresursen i dialogrutan.

CDialog::P revDlgCtrl

Anger fokus till föregående kontroll i dialogrutan.

void PrevDlgCtrl() const;

Anmärkningar

Om fokus ligger vid den första kontrollen i dialogrutan flyttas den till den sista kontrollen i rutan.

CDialog::SetDefID

Ändrar standardknappkontrollen för en dialogruta.

void SetDefID(UINT nID);

Parameterar

Nid
Anger ID för den pushbutton-kontroll som ska bli standard.

CDialog::SetHelpID

Anger ett kontextkänsligt hjälp-ID för dialogrutan.

void SetHelpID(UINT nIDR);

Parameterar

nIDR
Anger det kontextkänsliga hjälp-ID:t.

Se även

MFC-exempel DLGCBR32
MFC-exempel DLGTEMPL
CWnd-klass
hierarkidiagram