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.
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. 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.
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.
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.)
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.
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. Their numeric IDs should be considered reserved. There is a fifth symbolic ID that represents the default dialog icon. This ID can always be used where a dialog icon ID is needed.
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.
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.
Used within dialog box templates to define the size and position of the dialog box and its controls. 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
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).
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.
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.
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.