SAPrefs - Netscape-like Preferences Dialog

• Download source - 48 Kb

CSAPrefsDialog is a base for a preferences dialog, similar to the one used in Netscape. Page selection is handled with a CTreeCtrl - pages can be "sub-pages" of other pages!

Use is very similar to CPropertySheet / CPropertyPage : create a CSAPrefsDialog object. This implements the container for your property pages. The pages are objects of type CPrefsSubDlg (a subclass of CDialog). Using these classes is as easy as this :

// our preferences dialog
CSAPrefsDialog dlg;

// the "pages" (all derived from CSAPrefsSubDlg)
CPage1 page1;
CPage2 page2;
CPage3 page3;
CPage4 page4;

// add 3 pages
dlg.AddPage(page1, "Page 1");
dlg.AddPage(page2, "Page 2");
dlg.AddPage(page3, "Page 3");

// this one will be a child node on the tree
// (&page3 specifies the parent)
dlg.AddPage(dlg4, "Page 4", &page3);

// the prefs dialog title
dlg.SetTitle("This is pretty");

// text drawn on the right side of the shaded
// page label. this does not change when the
// pages change, hence "constant".
dlg.SetConstantText("SAPrefs");

// launch it like any other dialog...
dlg1.m_csText = m_csStupidCString;
if (dlg.DoModal()==IDOK)
{
  m_csStupidCString = dlg1.m_csText;
}

To use this in your own application, you need to follow these steps :

1. Add the following files to your project :
   • CSAPrefsDialog.cpp,.h
   • CSAPrefsSubDlg.cpp,.h
   • CSAPrefsStatic.cpp,.h
2. Copy the IDD_SAPREFS dialog resource from the sample project to your project.
3. Create your preference "pages" in the resource editor with the following settings :
   • Style - Child
   • Border - None
   • No OK or Cancel buttons! (pretend these are CPropertyPages!)
4. Use Class Wizard to create the dialog classes for the pages.
5. In the .cpp and .h files for your new dialog classes, replace all occurances of CDialog with CSAPrefsSubDlg. (you will need to #include "SAPrefsSubDlg.h")
6. Follow the steps shown in the sample code (above) to create the main dialog and add your pages.

Notes

• The parent/child relationships that you specify with AddPage(page, text, &parent) are strictly cosmetic. Only the tree control knows about them! As far as the CSAPrefsDialog is concerned, all pages are equal and independent of each other.
• OnOK and OnCancel are virtual functions of CSAPrefsSubDlg. You can override them in your own derived dialogs. But, you will have to do this by-hand (implement them like any other function). Class Wizard will not be able to do this for you. These functions are called, for every page that has been viewed, when CSAPrefsSubDlg is closed by OK or Cancel.
• You should handle "Help" as with CPropertyPage : with a WM_NOTIFY message handler :

  BOOL CMyPage::OnNotify(WPARAM wParam, LPARAM lParam, LRESULT* pResult) 
  {
  	NMHDR* pnmh = (LPNMHDR) lParam;
  	if (pnmh->code == PSN_HELP) {
  		AfxGetApp()->WinHelp(some help ID);
  	}
  
  	return CSAPrefsSubDlg::OnNotify(wParam, lParam, pResult);
  }

• Your pages should fit inside the IDC_DLG_FRAME rectangle on the IDD_SAPREFS dialog. CSAPrefsSubDlg does not resize to fit your pages, like CPropertySheet does. This keeps things nice and simple. Auto-resizing would be a nice addition, but I don't need it for my purposes, so I didn't add it.

History

• Jan 27 2002 - updated source files.
• 21 April 2002 - updated source files.