Performing Handle-Based Operations

A handle is a unique number with which some element of the operating system is identified to the computer. For example, every window on your desktop has a unique handle that enables the computer to distinguish it from other windows. Every device context, brush, pen, and font also has a unique handle.

To maintain optimal compatibility with the Win32 API, the Graphics, Pen, Brush, and Font objects support handle-based operations. For example, if you use the Win32 CreatePen function to create a pen, this function returns a handle. You can then pass this handle to the Pen object constructor, and the object is created based on the characteristics of that Win32 pen.

Even if you do not create a Pen, Brush, or Font object based on a handle that you allocate, you can retrieve the handle on which a Pen, Brush, or Font object is based. Each of these objects supports both a copyHandle and a getHandle method, and once you’ve used these methods to duplicate or retrieve the object’s handle, you can pass that handle to any Win32 function that is intended to take such a handle as a parameter.

The following are a few important rules to keep in mind when performing handle-based operations with the Graphics object:

• If you create an object based on a handle that you’ve previously allocated using a Win32 method, the object does not assume ownership of that handle. For example, if you use the Win32 GetDC method to retrieve a form’s device context handle (HDC), then create a Graphics object based on that HDC, then you own the handle. This means that when the Graphics object’s dispose method is called, the handle is not freed in memory. Instead, you must use the appropriate Win32 routine to destroy the handle.

  Below is an example that illustrates appropriate handle management. This example uses the Win32 GetDC to retrieve the handle to the form’s device context, then creates a Graphics object based on that handle. After using the Graphics object to draw a line on the form, the Graphics object’s dispose method is used to destroy the Graphics object, and the Win32 ReleaseDC routine is used to free the device context handle allocated by GetDC:

  // import the com.ms.wfc.Win32.Windows package.
  import com.ms.wfc.win32.Windows;
  
  int hDC = Windows.GetDC(this.getHandle());
  Graphics g = new Graphics(hDC);
  
  g.drawLine(new Point(0,0), new Point(100, 0));
  g.dispose();
  
  Windows.ReleaseDC(hDC);

Note that while this example uses the handle to a device context, the principle illustrated here applies to pens, brushes, fonts, and bitmaps.

• Most graphical objects support a copyHandle method through which you can duplicate the handle on which the object is based. If you use the copyHandle method to duplicate an object’s handle, you are responsible for freeing the handle.
  
  
• Most graphical objects also support a getHandle method, which returns the handle on which the object is based (as opposed to a copy of that handle). This method is intended to enable support compatibility between Graphics object methods and Win32 graphics routines.

  Handles retrieved through the getHandle method are not copies of an object’s underlying handle. Therefore, you should never attempt to free handles retrieved through getHandle. Such handles are freed when the object is disposed.