Definition of Terms

resource id

The identification number of a dialog resource. There are several different types of dialog resources, menus, dialog controls, and bitmaps, to name a few. You assign IDs when you create the resource definition for your dialog. An ID can be either numerical (for example, 1) or symbolic (for example, "IDOK").

IDs must be unique for each resource of the same type. Although two resources of different types may have the same ID, when using symbolic IDs with ooDialog, it is advisable to give all resources unique numerical IDs.

symbolic id

Defining a symbolic name for each numeric resource ID is often useful in programs that work with resource IDs. The symbolic name is then used where ever a numeric resource ID is needed. Symbolic names are easier to remember than numeric IDs and can make the code easier to understand.

The mechanism ooDialog provides for using symbolic IDs is the ConstDir attribute of the dialog classes. This is a directory object where the indexes are symbolic IDs and the item at each index is the numerical value of the ID.

Some generic resources are bound to the oodialog.dll. They can be used in any ooDialog program and are accessed using the .ResourceImage class. Programmers should always use their symbolic ID rather than their numeric ID in case the numeric value changes in future versions. To allow for future expansion, the ooDialog programmer should consider the resource IDs of 1 through 50 as reserved for ooDialog. Programmers can avoid conflicts by using IDs greater than 50 for resource IDs they assign in their programs.

The symbolic IDs in the following table are pre-defined by ooDialog and placed in the ConstDir when an instance of a dialog class is created. All symbolic names after IDC_STATIC in the table refer to resources bound to oodialog.dll for general use by the ooDialog programmer.

Table 2-1. Symbolic IDs Used by ooDialog

Numeric ID or SymbolSymbolic IDResourceType
1IDOKButton Control
2IDCANCELButton Control
9IDHELPButton Control
-1IDC_STATICStatic Control
IDI_DLG_OODIALOGIDI_DLG_OODIALOGIcon
IDI_DLG_APPICONIDI_DLG_APPICONIcon
IDI_DLG_APPICON2IDI_DLG_APPICON2Icon
IDI_DLG_OOREXXIDI_DLG_OOREXXIcon
IDI_DLG_DEFAULTIDI_DLG_DEFAULTIcon
#define statement

Define statements are often used in the C and C++ languages to define symbolic names for numerical values. Because of this, it is common in Windows programs with dialogs to define symbolic names for resource IDs. Most Windows resource editors use symbolic IDs, (some to a limited degree, others exclusively.) Often the define statements are put in a header file so they are available both to the resource compiler and to the program code. The defines take the form of: #define symbolicName numericValue as in this example:


#define   ID_PUSHBUTTON1  413
#define   ID_EDIT1        511
#define   ID_LISTBOX1     602

When ooDialog parses a resource script or a header file and finds a define statement, it will add the symbolic ID to the ConstDir directory object of the dialog. Resource scripts are used by subclasses of the UserDialog (see the Load method.) All the ooDialog dialog classes accept a header file as an optional parameter when a new instance of a dialog object is created. (See for example the Init method in the BaseDialog or UserDialog sections.) Symbolic IDs added to the ConstDir can be used in any method of the ooDialog classes where a resource ID is needed.

header file

A common practice when programming applications in Windows that use dialogs and dialog resources is to place symbolic defines in a separate file. These files often have a .h extension and are usually called header files. Windows resource editors often manage a header file for the symbolic IDs automatically. (For instance Microsoft's dialog editor creates, writes, and reads the resource ID header file completely on its own. The user does not need to take any action other than including the file in her program.)

handle

A unique reference to a Windows object assigned by the system. It can be a reference to a dialog, a particular dialog item, or a graphic object (pen, brush, font). Handles are required for certain methods; they can be retrieved from the system when needed.

dialog icon

The term dialog icon is used in this documentation to refer to the icon that is displayed in the left hand corner of the title bar of a dialog. In Windows this is often called the application icon. The dialog icon is also used for the Task Bar display and in the AltTab task switcher application.

The dialog icon for a specific dialog can be set when the dialog is run using one of the execute methods. See the Execute or Popup methods for example. ooDialog provides four pre-defined icons for use in dialogs. Custom icons can be used by including the icon in a binary (compiled) resource, a resource script, or by using the addIcon method of the UserDialog. The following table shows the symbolic IDs of the pre-defined icons. The symbolic ID should always be used in case the numeric value is changed in the future. In addition, the programmer should avoid using numeric IDs reserved by ooDialog. The IDI_DLG_DEFAULT is a fifth symbolic ID that represents the default dialog icon. This ID can always be used where a dialog icon ID is needed.

Table 2-2. ooDialog Supplied Icons

DescriptionSymbolic ID
The default, the letters OODIDI_DLG_OODIALOG
Dialog box imageIDI_DLG_APPICON
Fancier dialog box imageIDI_DLG_APPICON2
The ooRexx imageIDI_DLG_OOREXX
IDI_DLG_DEFAULTIDI_DLG_DEFAULT
device context

Stores information about the graphic objects that are displayed, such as bitmaps, lines, and pixels, and the tools used to display them, such as pens, brushes, and fonts. A device context can be acquired for a dialog or a button; it must be explicitly freed when the text or graphic operations are completed.

Common Controls Library (ComCtl32)

The dialog control windows used in dialogs, List-Views, Edit, Tree-Views, etc., are supplied by Microsoft in the common controls library. This is a DLL with the name comctl32.dll. Every version of Windows is supplied with a common controls library. However, Microsoft has updated the library a number of times to provide enhanced functionality and improved features

Each new version of the library is backwards compatible with previous versions, but will contain features not available in older versions. For instance, some of the List-View extended styles are only available with a 6.0, or later, version of the common controls library. ooDialog can only provide the features available in the version of the common controls libray on the system ooDialog is running on.

Therefore, an ooDialog program running on a Windows 2000 machine will not have available some of the features that are available when ooDialog is running on a XP service pack two system. The DlgUtil class provides a method, comCtl32Version that allows the programmer to determine the exact version of the common controls library that ooDialog is using. In the documentation for the ooDialog dialog control classes, features that are not available in all versions of the common control library are noted. The minimum version of the library that is needed is listed. In general, at this time, all features of ooDialog are avaialable on Windows XP or later. This may change in the future as Vista has common control features not available on XP.

pixel

Individual addressable point within a window. VGA screens support 640 by 480 pixels, SVGA screens support higher resolutions, such as 800 by 600, 1024 by 768, 1280 by 1024, and 1600 by 1200. Pixel values in a dialog start at the top left corner and include the window title and border.

dialog unit

Dialog box templates contain measurements that define the size and position of the dialog box and its controls. These measurements are device independent. This allows a single template to be used to create the same dialog box for all types of display devices. Using device independent measurements allows a dialog box to have the same proportions and appearance on all screens despite differing resolutions and aspect ratios between screens.

These measurements are called dialog template units, often shortened to just dialog units in this documentation.

The following paragraph in italics, which has been the sole documentation of dialog units in the ooDialog documentation prior to version 4.0.0, is unfortunately incorrect. The value of a dialog unit is dependent on the font actually used in the dialog, not on the system font. The statements below were probably true in very early versions of Windows when every dialog used system 8 pt font. Today it is highly unusual for a dialog to use system 8 pt font. The factorX and factorY values are calculated incorrectly. These values are only correct if the dialog is using system 8 pt font and are incorrect for a dialog using any other font.

There is a horizontal and a vertical dialog base unit to convert width and height of dialog boxes and controls from dialog units to pixels and vice versa. The value of these base units depend on the screen resolution and the active system font; they are stored in attributes of the UserDialog class.

  
  xPixels = xDialogUnits * self~FactorX
  
  

color

Each color supported by the Windows operating system is assigned a number. Sample color indexes are 0 (black), 1 (dark red), 2 (dark green), 3 (dark yellow), 4 (dark blue), 5 (purple), 6 (blue grey), 7 (light grey), 8 (pale green), 9 (light blue), 10 (white), 11 (grey), 12 (dark grey), 13 (red), 14 (light green), 15 (yellow), 16 (blue), 17 (pink), 18 (turquoise).

color palette

An array that contains color values identifying the colors that can currently be displayed or drawn on the output device.

Color palettes are used by devices that can generate many colors but can only display or draw a subset of them at a time. For such devices, Windows maintains a system palette to track and manage the current colors of the device.

Applications do not have direct access to this system palette. Instead, Windows associates a default palette with each device context. Applications can use the colors in the default palette.

The default palette is an array of color values identifying the colors that can be used with a device context by default. Windows associates the default palette with a context whenever an application creates a context for a device that supports color palettes. The default palette ensures that colors are available for use by an application without any further action. The default palette typically has 20 entries (colors), but the exact number of entries can vary from device to device. The colors in the default palette depend on the device. Display devices, for example, often use the 16 standard colors of the VGA display and 4 other colors defined by Windows.

Windows documentation

The term Windows documentation is used throughout the ooDialog reference to refer to the Windows Operating System documentation provided by Microsoft. The documentation is called the MSDN Library. The library is provided online for anyone to access. In addition, since May 2006, Microsoft has also provided free of charge the ISO images of the library installation program. Anyone can download the ISOs, burn them to a CD and install the library locally on their system.

It is not necessary for the ooDialog programmer to know or understand the underlying Windows API that ooDialog is built on. However, as programmers write more sophisticated ooDialog applications, it may prove helpful to look up certain details in the MSDN Library. The information below is provided to help the ooDialog programmer locate the MSDN Library, if they would like to. All things on the Internet change. The URLs listed here are accurate at the time of this writing.

The online MSDN Library is currently located at:

http://msdn2.microsoft.com/en-us/library/default.aspx.

Directions to the downloadable ISO images of the MSDN Library have been posted on this blog entry:

http://blogs.msdn.com/robcaron/archive/2006/07/26/678897.aspx

A Google search using: "Rob Caron" General Downloads MSDN Library should also turn up the blog entry.

Windows platform SDK

The Windows Platform SDK is provided free of charge by Microsoft. The SDK is not needed to write ooDialog programs. However, combining the use of the documentation in the MSDN Library with the SDK allows very sophisticated ooDialog programs to be written. In general, the ooDialog framework takes care of the low-level details needed to work with the Windows API. However, there are a few generic ooDialog methods that provide direct access to the Windows API.

As an example, the AddUserMessage method allows the programmer to connect any Windows message sent to a dialog to a method in his ooDialog class. To use this method, the programmer would go to the MSDN library to look up details on the message and message parameters he is interested in. He would then use the Platform SDK to determine the numeric value of the Windows message and possibly the numeric values of its parameters.

This link provides some good information on the Platform SDK in general and also points the reader to where to get a SDK.

http://en.wikipedia.org/wiki/Platform_SDK

Again, note that it is not at all necessary to obtain, or understand details concerning, the Platform SDK. This information is provided for those programmers that have reached the point where they think a method like AddUserMessage might help them and need some direction as to how to go about using it.

System error code

The term system error code refers to an error code set by the Windows operating system when an API fails. ooDialog provides an interface to the Windows APIs and when an error is detected many of the ooDialog methods have some means of conveying the system error code to the programmer. The ooDialog programmer can look up the meaning of a system error code in the MSDN library to understand better the cause of a failure.

Note that not all APIs set the system error code.