Correctly Clearing XOR-ed Lines Drawn in the Viewport

Sometimes a plug-in needs to draw two-dimensional lines and shapes that are XOR-ed with the viewport image. The following is an example of drawing a XOR-ed rectangle using XORDottedRect() :

HWND hWnd = // the viewport's HWND to draw into
IPoint2 p1, p2; // Opposites corners of the new rectangle 
IPoint2 p1_old, p2_old; // Opposite corners of the old rectangle 
XORDottedRect(hWnd, p1_old, p2_old); // Erase old rectangle
XORDottedRect(hWnd, p1, p2); // Draw new rectangle

When the Nitrous viewport is active, the code above will not clear the old rectangle. To ensure that the old lines are cleared in all viewport modes, the bErase parameter needs to be set to true in the first call to XORDottedRect(). The example then becomes:

HWND hWnd = // the viewport's HWND to draw into
IPoint2 p1, p2; // Opposites corners of the new rectangle 
IPoint2 p1_old, p2_old; // Opposite corners of the old rectangle 
XORDottedRect(hWnd, p1_old, p2_old, 0, true); // Erase old rectangle, explicitly erase foreground
XORDottedRect(hWnd, p1, p2); // Draw new rectangle

The above recommendation applies to the following functions: XORDottedRect(), XORDottedCircle(), XORDottedPolyline().