Common Controls and Dialogs

   

A collection of predefined, common window controls is provided within Windows through the common control library ( COMCTL32.DLL ). In addition to controls, a collection of common window dialogs are provided through the common dialog library ( COMDLG32.DLL ). The idea behind providing common controls and dialogs is to allow developers to quickly utilize common interface elements within a program rather than spending lengthy time and effort writing custom window interfaces. For the most part, Borland C++Builder provides a palette full of common controls and dialogs through the Visual Component Library (VCL). However, it's useful for developers to be aware of the Win32 API common controls and dialogs that are available.

Common Controls

There are at least 22 common controls for Windows in COMCTL32.DLL . Examination of the commctrl.h file provided with C++Builder reveals the Win32 elements available with the common control library. These controls are described in Table 14.11.

Table 14.11. Common Controls

Common Control

Description

Borland VCL Equivalent

Animation Control

Plays simple AVI (video) clips without sound. Use ANIMATE_CLASS flag.

TAnimate

ComboBoxEx [*]

Provides support for item images within a combo box. Use WC_COMBOBOXEX flag.

None

Date and Time Picker

Provides an interface for exchanging date and time information with the user . Use DATETIMEPICK_CLASS flag.

TDateTimePicker

Drag List Box

Provides a list box that allows items to be dragged from one position to another. Use MakeDragList() routine.

None

Flat Scroll Bar [*]

Provides a unique three-dimensional scrollbar, created using the InitializeFlatSB() routine.

None

Header Controls

Used to place resizable headers above columns of text or numbers . Use WC_HEADER flag.

THeaderControl

Hot-Key Controls

Allows entry of hotkey keystroke combinations. Use HOTKEY_CLASS flag.

THotKey

Image List

Provides a collection of equal size images referenced by an index.

Created using the ImageListCreate() routine.

TImageList

IP Address [*]

Allows an IP address to be entered in an easily understood format. Use WC_IPADDRESS flag.

None

List View

Displays a collection of items as large icons, small icons, detailed list, or report view within a window control. Use WC_LISTVIEW flag.

TListView

Monthly Calendar

Provides a graphical calendar interface for viewing and selecting dates. Use MONTHCAL_CLASS flag.

TMonthCalendar

Page Scroller [*]

Provides a scrollable window containing a child window (such as a control) that is too large to be seen entirely. Use WC_PAGESCROLLER flag.

TPageScroller

Progress Bars

Used to provide graphical status feedback for lengthy operations. Use PROGRESS_CLASS flag.

TProgressBar

Property Sheets

Presents viewable and editable properties of an item in a tabbed page form.

TPageControl

Rebar (Coolbar)

Used to contain one or more bands composed of any combination of a gripper bar, bitmap, text label, and a child window. Use REBARCLASSNAME flag.

TCoolBar

Status Bar

Provides a panel control used to display text and graphical information. Use STATUSCLASSNAME flag.

TStatusBar

Tab Controls

Defines multiple pages within the area of a window (similar to dividers in a notebook). Use WC_TABCONTROL flag.

TTabControl

Toolbars

Contains one or more selectable buttons within a panel bar. Use TOOLBARCLASSNAME flag.

TToolBar

Tooltip Controls

Used to display a small pop-up window displaying a text description. Use TOOLTIPS_CLASS flag.

THintWindow

Trackbars

Provides a slide indicator with optional tick marks used for adjusting an integer value within a specified range. Use TRACKBAR_CLASS flag.

TTrackBar

Tree View Controls

Displays a hierarchical list of items and subitems within a window frame consisting of a label and an optional bitmapped image. Use WC_TREEVIEW flag.

TTreeView

Up-Down Controls

Provides an edit control consisting of a pair of arrow buttons used to increase or decrease a value. Use UPDOWN_CLASS flag.

TUpDown

[*] Introduced in Internet Explorer 4.0.

Unless otherwise noted, these controls are created by using the CreateWindowEx() routine and by selecting the proper flags associated with each feature. Let's take a quick look at the example shown in Listing 14.9.

Listing 14.9 Common Control Example
 __fastcall TFormCommCtrl_Dlg::TFormCommCtrl_Dlg(TComponent* Owner)          : TForm(Owner)  {     InitCommonControls();    // make sure the the common control DLL is loaded.     ControlHandle = NULL;  }  //--------------------------------------------------------------------------- void __fastcall TFormCommCtrl_Dlg::ButtonMakeListViewClick(TObject *Sender)  {   HWND ListBox;   RECT Rect;   DWORD dwExStyle = 0;   Rect = GetClientRect();   HINSTANCE  hInstance = (HINSTANCE )GetWindowThreadProcessId(      Handle,    // handle of window      NULL    // address of variable for process identifier     );    ControlHandle = CreateWindowEx(0L,        WC_LISTVIEW,        NULL,        WS_VISIBLE  WS_CHILD  WS_BORDER  TVS_HASLINES  TVS_HASBUTTONS  TVS_LINESATROOT,        0, 180,        Rect.right - Rect.left, Rect.bottom-180,        Handle,        0,        hInstance,        NULL);  }  

Before using a common control, be sure to call the InitCommonControlsEx() routine to ensure that the common control dynamic-link library (DLL) is properly loaded. In this example, this was done in the constructor for this form. The ButtonMakeListViewClick() event handler provides the code for creating a common control widget that is placed on our form. This is accomplished using the CreateWindowEx() call with a WC_LISTVIEW flag.

In scanning through the table, you'll notice a majority of the common control features are supported by Borland's VCL. There are more than 80 routines available within the common control library ( comctl32.dll ) supporting these and possibly other common controls. Use Borland's impdef command-line tool or DLL LIB Util , which was described earlier in a Tip, to determine the full list of the available common control functions supported by the Win32 API. Also examine the latest commctrl.h file for identifying the common control macro definitions.

Common Dialogs

In addition to common controls, Microsoft provides common dialogs for applications. There are currently eight common dialogs contained in recent versions of COMDLG32.DLL . C++Builder, however, provides VCL wrappers for each of these dialogs, as shown in Table 14.12.

Table 14.12. VCL Equivalents for Microsoft API Common Dialog Functions

Common Dialog

Microsoft API Call

VCL Equivalent

Choose Color

ChooseColor()

TColorDialog

Choose Font

ChooseFont()

TFontDialog

Find Text

FindText()

TFindDialog

Open File

GetOpenNameFile()

TOpenDialog

Save File

GetSaveFileName()

TSaveDialog

Print Setup

PageSetupDlg()

TPrinterSetupDialog

Print

PrintDlg()

TPrintDialog

Replace Text

ReplaceText()

TReplaceDialog

Examination of the commdlg.h file provided with C++Builder reveals the Win32 elements available with the common dialog library. Creating the .def file for the commdlg.dll will further reveal the available API routines.

To understand how to use one of these common dialogs, let's look at an example that demonstrates the use of the Choose Color dialog as shown in Figure 14.8.

Figure 14.8. Example application that uses the Color Common Dialog.

graphics/14fig08.jpg

The code used to generate the Color Common Dialog is provided in Listing 14.10.

Listing 14.10 Common Dialog Example
 void __fastcall TFormCommCtrl_Dlg::ButtonChooseColorClick(TObject *Sender)  {      LPCHOOSECOLOR cc;      COLORREF    initrgb, rgb;      BOOL        res;      DWORD        err;      initrgb= 0x0000FFFF; //yellow      char result[MAX_PATH];      HINSTANCE  hInstance = (HINSTANCE )GetWindowThreadProcessId(              Handle,    // handle of window              NULL);    // address of variable for process identifier      DWORD mcolors[15];      mcolors[0] =  0x00FF0000; // blue      mcolors[1] =  0x00FF4040; // med blue      mcolors[2] =  0x00FF8080; // light med blue      mcolors[3] =  0x00FFFF00; // aqua      mcolors[4] =  0x0000FF00; // green      mcolors[5] =  0x0040FF40; // med green      mcolors[6] = 0x0080FF80; // light med green      mcolors[7] =  0x0000FFFF; // yellow      mcolors[8] =  0x000000FF; // red      mcolors[9] = 0x004040FF; // more pink      mcolors[10] = 0x008080FF; // pink      mcolors[11] = 0x00400040; // purple      mcolors[12] = 0x00808080; // gray      mcolors[13] = 0x00404040; // dk gray      mcolors[14] =  0x00000000; // white      mcolors[15] =  0x00FFFFFF; // black      cc = (LPCHOOSECOLOR)malloc(sizeof(CHOOSECOLOR));      cc->lStructSize = (DWORD) sizeof(CHOOSECOLOR);      cc->hwndOwner = Handle;      cc->hInstance = hInstance;      cc->rgbResult = initrgb;      cc->lpCustColors = mcolors;      cc->Flags = CC_ANYCOLOR  CC_FULLOPEN  CC_RGBINIT;      cc->lCustData = NULL;      cc->lpfnHook = NULL;      cc->lpTemplateName = NULL;      if (!(res = ChooseColor(cc)))      {              err = CommDlgExtendedError();              sprintf(result,"Error: %d\n",err);      }      else{              rgb=cc->rgbResult;              sprintf(result,"r g b: %d %d %d\n", ((BYTE) (rgb)) ,((BYTE)                      (((WORD) (rgb)) >> 8)),((BYTE) ((rgb) >> 16))  );      }      MessageBox(Handle,result,"Result",MB_OK);  }  

In this example, we're using the ChooseColor() API call to display the Color selection dialog. Within the ButtonChooseClorClick() event handler, we set up an array identifying the custom colors we want to load, and a pointer to the CHOOSECOLOR structure, which is defined as follows :

 typedef struct {   // cc      DWORD        lStructSize;      HWND         hwndOwner;      HWND         hInstance;      COLORREF     rgbResult;      COLORREF*    lpCustColors;      DWORD        Flags;      LPARAM       lCustData;      LPCCHOOKPROC lpfnHook;      LPCTSTR      lpTemplateName;  } CHOOSECOLOR; 

The mcolors array that we've defined and initialized is assigned to the lpCustColors flag of the structure. We also identify the windows handle and instance of our application, plus any flags we want associated to the dialog. The ChooseColor() call returns the color value selected by the user. If the return is 0, we know that the user opted out of selecting a color.

In addition to dialogs, the ComDlg32.dll also provides a couple of trivial functions including GetFileTitle() and LoadAlterBitmap() . Plus, a useful function to help isolate errors called CommDlgExtendedError() .

GetFileTitle() is used to retrieve the display name for a specified file. For instance, what is displayed to the user in Windows Explorer is considered the display name. According to the Win32 API, "the display name includes an extension only if that is the user's preference for displaying filenames."

LoadAlterBitmap() function is a bit of a mystery. There is no known documentation on this call, but it's presumably made to load an alternate bitmap, such as an icon, associated to the file within its resource file.

CommDlgExtendedError() is used to retrieve an error code for a failed dialog call. The Win32 API help file provides more details on each of the error codes, which begin with a prefix of CDERR_ .


     
Top


C++ Builder Developers Guide
C++Builder 5 Developers Guide
ISBN: 0672319721
EAN: 2147483647
Year: 2002
Pages: 253

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net