Many of the functions in the ObjectWindows GDI classes might look familiar to you; this is because many of them have the same names and very nearly, if not exactly, the same function signature as regular Windows API functions.

Because the ObjectWindows GDI classes replicate the functionality of so many Windows objects, there was no need to alter the existing terminology. Therefore, function names and signatures have been deliberately kept as close as possible to what you are used to in the standard Windows GDI functions.

Some improvements, however, have been made to the functions. These improvements include such things as cracking packed return values and using ObjectWindows objects in place of Windows-defined structures.

None of these changes are hard and fast rules; just because a function can somehow be converted does not mean it necessarily has been. But if you see an ObjectWindows function with the same name as a Windows API function that looks a little different, one of the following reasons should explain the change to you:

API functions that take an object handle as a parameter often omit the handle in the ObjectWindows version.

The TGdiObject base object maintains a handle to each object. The ObjectWindows version then uses that handle when passing the call on to Windows. For example, when selecting an object in a device context, you would normally use the SelectObject API function, as shown here:

void SelectPen(HDC& hdc, HPEN& hpen)
{
 HPEN hpenOld;
 hpenOld = SelectObject(hdc, hpen);
 // Do something with the new pen.
 .
 .
 .
 // Now select the old pen again.
 SelectObject(hdc, hpenOld);
}

The ObjectWindows version of this function is encapsulated in the TDC class, which is derived from TGdiObject. The following example shows how the previous function would appear in a member function of a TDC-derived class. Notice the difference between the two calls to SelectObject:

void SelectPen(TDC& dc, TPEN& pen)
{
 dc.SelectObject(pen);
 
 // Do something with the new pen.
 
 .
 .
 .
 
 // Now select the old pen again.
 dc.RestorePen();
 }

ObjectWindows GDI functions usually substitute an ObjectWindows type in place of a Windows type.

Windows API functions use individual parameters to specify x and y coordinate values; ObjectWindows GDI functions use TPoint objects.
Windows API functions use RECT structures to specify a rectangular area; ObjectWindows GDI functions use TRect objects.
Windows API functions use RGN structures to specify a region; ObjectWindows GDI functions use TRegion objects.
Windows API functions take HLOCAL or HGLOBAL parameters to pass an object that does not have a predefined Windows structure; ObjectWindows GDI functions use references to ObjectWindows objects.

Some Windows functions return a uint32 with data encoded in it.

The uint32 must then must be cracked to get the data from it. The ObjectWindows versions of these functions take a reference to some appropriate object as a parameter. The function then places the data into the object, relieving the programmer from the responsibility of cracking the value. These functions usually return a bool, indicating whether the function call was successful.

For example, the Windows version of SetViewportOrg returns a uint32, with the old value for the viewport origin contained in it. The ObjectWindows version of SetViewportOrg takes a TPoint reference in place of the two ints the Windows version takes as parameters. It also takes a second parameter, a TPoint *, in which the old viewport origins are placed.

API functions that take an object handle as a parameter often omit the handle in the ObjectWindows version.

ObjectWindows GDI functions usually substitute an ObjectWindows type in place of a Windows type.

Some Windows functions return a uint32 with data encoded in it.

See Also