HeaderPane
Main
Hide
Share Link
Print

Using C

This section describes how to use SftBox/DLL in an application written using the C programming language. The code shown is taken from the Colors sample (see Samples).

Adding SftBox/DLL to an Application

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.
#include "SftBox.h"                     /* SftBox/DLL Header File */

This include statement should appear after the #include <windows.h> statement. The file is located in the directory \Program Files (x86)\Softelvdm\SftBox DLL 6.0\Include (unless changed during the installation). The project settings may need to be updated so the #include file can be located (see "Building Applications" for more information).

B)In order to use SftBox/DLL controls, an application must call the SftBox_RegisterApp function. The call to this function is required so that SftBox/DLL window classes can be registered. This call has to be made before any SftBox/DLL controls are created. Add the following statement to your source code, where your application registers its window classes (normally during application initialization):
SftBox_RegisterApp(hinst);          /* Register with SftBox/DLL */
C)Once SftBox/DLL controls are no longer needed, an application must call the SftBox_UnregisterApp function. The call to this function is required so that SftBox/DLL window classes can be unregistered and cleanup processing can take place. This call has to be made after all SftBox/DLL controls have been destroyed (normally during application termination).
SftBox_UnregisterApp(hinst);        /* Unregister from SftBox/DLL */
D)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.

Adding a Combo Box

There are two methods to add a combo box control to an application:

  • using dialog resources
  • using CreateWindow(Ex)

Adding a combo box using dialog resources is accomplished by using a resource editor to design a dialog. Once a combo box is created, its window handle can be obtained by using the Windows GetDlgItem function. For more information, see Creating a Dialog Resource.

HWND hwndBox = GetDlgItem(hwndDlg, IDC_BACKGROUND);

Another method to create a combo box is by using the CreateWindow(Ex) Windows call:

hwndBox = CreateWindow(TEXT(SFTBOX_CLASS), NULL,
    WS_CHILD | WS_VISIBLE | WS_BORDER | WS_VSCROLL | WS_HSCROLL | WS_TABSTOP |
    SFTBOXSTYLE_DROPDOWNLIST, 10, 10, 200, 24, hwndMain,
    (HMENU) IDC_BACKGROUND, hinst, NULL);

For more information on the various parameters used, see the Windows API documentation. The basic combo box style (SFTBOXSTYLE_SIMPLE, SFTBOXSTYLE_DROPDOWN or SFTBOXSTYLE_DROPDOWNLIST) and the other available styles are described in Window Styles.

Defining Columns

The columns of a combo box are defined using SftBox_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, TEXT("Color"));
InitColumn(&aCols[1], 1, 100, TEXT("Description"));
SftBox_SetColumns(hwndBox, 2, aCols);
SftBox_SetShowHeaderDropDown(hwndBox, TRUE);// Column titles in the dropdown only
SftBox_SetDroppedHeight(hwndBox, 12);       // Show up to 12 items
SftBox_SetDropDownOptimalWidth(hwndBox, TRUE);// The dropdown is as wide as its columns
SftBox_SetDarkMode(hwndBox, SFTBOX_DARKMODE_AUTO);

Adding Items

Items are added using SftBox_AddString (or SftBox_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 SftBox_SetText. An application-defined value can be saved with each item using SftBox_SetItemData.

LONG index;

index = SftBox_AddString(hwndBox, TEXT("Custom..."));
SftBox_SetText(hwndBox, index, 1, TEXT("Any color"));
SftBox_SetItemData(hwndBox, index, custom);

Once all items have been added, the column widths can be adjusted to their contents and an item can be selected:

SftBox_MakeColumnOptimal(hwndBox, -1, 0);   // Make all columns optimal
SftBox_RecalcHorizontalExtent(hwndBox, 0);

// Select the item with the requested color, searching after the custom color
index = SftBox_FindItem(hwndBox, CUSTOM_INDEX + 1, selected);
SftBox_SetCurSel(hwndBox, index >= 0 ? index : CUSTOM_INDEX);

Adding Pictures

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 SftBox_GetCellInfo and SftBox_SetCellInfo:

static void SetColorSample(HWND hwndBox, 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;
    SftBox_GetCellInfo(hwndBox, &CellInfo);
    Sft_SetPictureColorSample(&CellInfo.Cell.CellPicture1, SAMPLE_SIZE, SAMPLE_SIZE, color, SYSCOLOR(COLOR_WINDOWTEXT));
    SftBox_SetCellInfo(hwndBox, &CellInfo);
}

All pictures in the cells of a combo box are the same size. The size is registered before items are added, by calling SftBox_SetCellInfo with the index -1 (see the complete source code of the Colors sample).

Handling Notifications

As with standard Windows controls, applications must respond to events and messages to cause controls to respond to user requests. A combo box sends its notifications to its parent window using WM_COMMAND messages. For additional information, see Notifications.

Responding to a Selection

Respond to the WM_COMMAND notifications SFTBOXN_SELENDOK and SFTBOXN_SELCHANGE just as you would for a standard Windows combo box's CBN_SELENDOK and CBN_SELCHANGE:

case WM_COMMAND:
    switch (LOWORD(wParam)) {
    case IDC_BACKGROUND:
    case IDC_TEXT:
        switch (HIWORD(wParam)) {
        case SFTBOXN_SELENDOK:      // an item was picked in the dropdown
            if (SftBox_GetCurSel((HWND) lParam) == CUSTOM_INDEX)
                ChooseCustomColor(hwndDlg, (HWND) lParam);
            UpdatePreview(hwndDlg);
            break;
        case SFTBOXN_SELCHANGE:     // the selection changed (keyboard, mouse)
            UpdatePreview(hwndDlg);
            break;
        }
        break;
    }
    break;

The selected item is retrieved using SftBox_GetCurSel, its item data using SftBox_GetItemData:

static COLORREF GetSelectedColor(HWND hwndBox)
{
    LONG index = SftBox_GetCurSel(hwndBox);
    if (index < 0)
        return RGB(0, 0, 0);
    return ResolveColor((COLORREF) SftBox_GetItemData(hwndBox, index));
}

Mouse notifications caused by the static portion of a dropdown list combo box, or by the column headers shown above the static portion or the edit control portion (SetShowHeaderMain), use the notification codes of the dropdown portion, wrapped in SFTBOXN_MAIN_NOTIFICATION (taken from the Fonts sample):

case SFTBOXN_MAIN_NOTIFICATION(SFTBOXN_LBUTTONDOWN_COLUMN): // a column title was clicked
    if (SftBox_GetHeaderButton(hwndCtl) == 0) {
        m_fFontsDescending = !m_fFontsDescending;
        SortFonts();
        SetSortIndicator(hwndCtl, m_fFontsDescending);
    }
    break;

Keyboard input notifications are sent as WM_NOTIFY messages with NM_SFTBOX_KEYDOWN, NM_SFTBOX_KEYUP and NM_SFTBOX_CHAR structures. See Notifications for the complete list.


Last Updated 11/21/2026 - (email)
© 2026 Softel vdm, Inc.