This section describes how to use SftBox/DLL in an application written using C++ and the Microsoft Foundation Class library (MFC). The code shown is taken from the MFC Colors sample (see Samples).
Please see "Building Applications" to prepare a project for development with SftBox/DLL.
| A) | Every source program making use of a SftBox/DLL control must include the required header file SftBox.h by using the #include directive. In an MFC application, SftBox.h automatically includes SftBoxM.h, which defines the CSftBox class. |
|---|
#include "SftBox.h" /* SftBox/DLL Header File */
This include statement should appear after the #include <stdafx.h> statement or can be included at the end of stdafx.h (after the MFC header files).
| B) | The source program SftBoxM.cpp must be added to your project. It is added to the project, without making any modifications to the file. Instead of adding it to the project, you can include the file using the #include directive. However, it must be included in a source file (*.CPP) as it is not a header file, and only one source file can #include the file SftBoxM.cpp. SftBoxM.cpp provides the run-time class information of the CSftBox class in debug builds. |
|---|
#include "SftBoxM.cpp"
| C) | In order to use SftBox/DLL controls, an application must call the CSftBox::RegisterApp function. The preferred location is the InitInstance member function of your CWinApp-based application object: |
|---|
CSftBox::RegisterApp(); /* Register with SftBox/DLL */| D) | Once SftBox/DLL controls are no longer needed, an application must call the CSftBox::UnregisterApp function. The preferred location is the ExitInstance member function of your CWinApp-based application object: |
|---|
CSftBox::UnregisterApp(); /* Unregister from SftBox/DLL */| E) | The application's executable (Exe or Dll) must be linked with the correct Lib file, depending on the target environment. Please see "Building Applications" for more information. |
|---|
ClassWizard does not support new classes such as CSftBox, so any combo box instance variables, notification handlers, message map entries, etc., have to be added manually.
There are two methods to add a combo box control to an application:
Adding a combo box using dialog resources is accomplished by using a resource editor to design a dialog. For more information, see Creating a Dialog Resource. Once a combo box is created, its CSftBox-based object can be obtained by using DDX_Control in DoDataExchange or attached to a CSftBox object using SubclassDlgItem:
CSftBox m_Background; CSftBox m_Text; void CMainDlg::DoDataExchange(CDataExchange* pDX) { CDialog::DoDataExchange(pDX); DDX_Control(pDX, IDC_BACKGROUND, m_Background); DDX_Control(pDX, IDC_TEXT, m_Text); }
or
CSftBox m_Background;
m_Background.SubclassDlgItem(IDC_BACKGROUND, this);Another method to create a combo box is by using the CSftBox::Create member function.
CSftBox m_Background; m_Background.Create(WS_CHILD | WS_VISIBLE | WS_BORDER | WS_VSCROLL | WS_HSCROLL | WS_TABSTOP | SFTBOXSTYLE_DROPDOWNLIST, CRect(10,10,210,34), pParentWnd, IDC_BACKGROUND);
The columns of a combo box are defined using SetColumns and an array of SFTBOX_COLUMN structures. Each structure is cleared first, colors that are not used are set to SFTBOX_NOCOLOR.
static void InitColumn(LPSFTBOX_COLUMN lpCol, int position, int width, LPCTSTR lpszTitle) { memset(lpCol, 0, sizeof(SFTBOX_COLUMN)); lpCol->width = width; lpCol->style = ES_LEFT | SFTBOX_TOOLTIP; lpCol->styleTitle = ES_LEFT | SFTBOX_HEADER_UP; lpCol->lpszTitle = (LPTSTR) lpszTitle; lpCol->colorBg = lpCol->colorFg = lpCol->colorBgSel = lpCol->colorFgSel = SFTBOX_NOCOLOR; lpCol->colorBgEnd = lpCol->colorBgSelEnd = SFTBOX_NOCOLOR; lpCol->colorProgress = lpCol->colorProgressEnd = SFTBOX_NOCOLOR; lpCol->realPos = lpCol->dispPos = position; }
SFTBOX_COLUMN aCols[2]; InitColumn(&aCols[0], 0, 100, _T("Color")); InitColumn(&aCols[1], 1, 100, _T("Description")); box.SetColumns(2, aCols); box.SetShowHeaderDropDown(TRUE); // Column titles in the dropdown only box.SetDroppedHeight(12); // Show up to 12 items box.SetDropDownOptimalWidth(TRUE); // The dropdown is as wide as its columns box.SetDarkMode(SFTBOX_DARKMODE_AUTO);
Items are added using AddString (or InsertString), which defines the text of the first column and returns the index of the new item. The text of the other columns is set using SetText. An application-defined value can be saved with each item using SetItemData.
LONG index; index = box.AddString(_T("Custom...")); box.SetText(index, 1, _T("Any color")); box.SetItemData(index, custom);
Once all items have been added, the column widths can be adjusted to their contents and an item can be selected:
box.MakeColumnOptimal(-1, 0); // Make all columns optimal box.RecalcHorizontalExtent(0); // Select the item with the requested color, searching after the custom color index = box.FindItem(CUSTOM_INDEX + 1, selected); box.SetCurSel(index >= 0 ? index : CUSTOM_INDEX);
Pictures are described by SFT_PICTURE structures, which are initialized using the Sft_SetPictureXxx functions defined in SftPicture2.h (included by SftBox.h). The Colors sample shows a color sample as cell picture in the first column of each item, using GetCellInfo and SetCellInfo:
void CMainDlg::SetColorSample(CSftBox& box, LONG index, COLORREF color) { // The color sample is the picture of the cell in the first column. SFTBOX_CELLINFOPARM CellInfo; memset(&CellInfo, 0, sizeof(CellInfo)); CellInfo.index = index; CellInfo.iCol = 0; box.GetCellInfo(&CellInfo); Sft_SetPictureColorSample(&CellInfo.Cell.CellPicture1, SAMPLE_SIZE, SAMPLE_SIZE, color, SYSCOLOR(COLOR_WINDOWTEXT)); box.SetCellInfo(&CellInfo); }
As with standard Windows controls, applications must respond to events and messages to cause controls to respond to user requests. For additional information, see Notifications and Notifications Using MFC.
// Event handler prototypes added to dialog/window class
afx_msg void OnBackgroundSelEndOK();
afx_msg void OnSelChange();
// Event handler(s) added to message map
BEGIN_MESSAGE_MAP(CMainDlg, CDialog)
ON_CONTROL(SFTBOXN_SELENDOK, IDC_BACKGROUND, OnBackgroundSelEndOK)
ON_CONTROL(SFTBOXN_SELCHANGE, IDC_BACKGROUND, OnSelChange)
END_MESSAGE_MAP()
// Event handler implementation
void CMainDlg::OnBackgroundSelEndOK() // an item was picked in the dropdown
{
if (m_Background.GetCurSel() == CUSTOM_INDEX)
ChooseCustomColor(m_Background);
UpdatePreview();
}
void CMainDlg::OnSelChange() // the selection changed (keyboard, mouse)
{
UpdatePreview();
}The selected item is retrieved using GetCurSel, its item data using GetItemData:
COLORREF CMainDlg::GetSelectedColor(const CSftBox& box) const { LONG index = box.GetCurSel(); if (index < 0) return RGB(0, 0, 0); return ResolveColor((COLORREF) box.GetItemData(index)); }