Basic GDI+ Objects


This article has been excerpted from book "Graphics Programming with GDI+".

The Color Structure

You may have notices that we used the Color structure in our previous example. The Color structure represents a GDI+ ARGB (alpha-red-green-blue) color. This class contains a static property for almost every possible color. For example, Color.Black and Color.Red represent black and red respectively. Beside these static properties, this structure has the additional properties defined in Table 2.1.

IsKnownColor, IsNamedColor and IsSystemColor represent members of the KnownColor enumeration, which again defines almost every color as a member.

Table 2.2 describes the methods of the Color structure.

TABLE 2.1 Color properties

Property

Description

Red, Blue, Green, Aqua, Azure, and so on

A specified color static property for almost every color.

A

Return the alpha component value in a Color structure.

R

Returns the red component value in a Color Structure.

G

Returns the green component value in a Color Structure.

B

Returns the blue component value in a Color Structure.

IsEmpty

Indicates whether a Color structure is uninitialized.

IsKnownColor

Indicate whether a color is predefined.

IsNamedColor

Indicate whether a color is predefined.

IsSytemColor

Indicates whether a color is a system color.

Name

Return the name of the color.


TABLE 2.2: Color methods

Method Description

FromArgb

Creates a Color structure from the four 8-bit ARGB component (alpha-red-green-blue) values.

FromKnownColor

Create a Color structure from the specified predefined color.

FromName

Creates a Color structure from the specified name of a predefined color.

GetBrightness

Returns the hue-saturation-brightness (HSB) brightness value of this Color structure.

GetHue

Returns the HSB he value, in degrees, of this Color structure.

GetSaturation

Returns the HSB hue value in degrees, of this Color structure.

ToArgb

Returns the 32-bit ARGB value of this Color structure.

ToKnownColor

Return the KnownColor value of this Color structure.


The Point and PointF Structure

In GDI+, the Point structure represents an ordered pair of integer x- and y-coordinates that define a point in a two-dimensional plane. The Point structure's constructor initializes a new instance of the Point structure. The Point constructor has three overloaded forms that allow you to create a Point object from an integer, a size object, or two integers as follows:


public
Point (int);
public
Point (Size);
public
Point (int, int);

The following code snippet creates Point objects using all three forms of the constructor:

Point pt1 = new Point (10);
Point pt2 = new Point (new Size (20, 20));
Point pt3 = new Point (30, 30);


The PointF structure is similar to the Point structure, but it uses floating point values of integers. Unlike the Point structure, PointF has only one constructor, which takes two floating point values as x- and y-coordinates.

PointF pt3 = new PointF(30.0f, 30.0f);

Both the Point and the PointF structures define three properties: IsEmpty, X, and Y. The IsEmpty property returns true if a point is empty, which means that both X and Y values are zero; otherwise it returns false. The X and Y properties return the x- and y-coordinates of a point, respectively. The Empty static field of the Point structure creates a new point with x and y values set to zero.

Listing 2.3 creates a point with zero x and y values using Point. Empty and assigns new coordinates values using the X and Y properties. This example creates a Graphics object using the Graphics.FromHwnd method and returns the graphics surface for a form. The Graphics.FromHwnd method creates a Graphics object from a window handle, which we pass as this.Handle. The DrawLine method draws a line starting from the first point to the second point using the defined pen. You can test this code on a button or a menu click event handler.

LISTING 2.3: Creating Point objects


//Create a new Point object

Point pt = new Point (50, 50);

//Create a new point using Point.Empty

Point newPoint = Point.Empty;

//Set X and Y properties of Point

newPoint.X=100;
newPoint.Y = 200;

//Create a Graphics object from the
//Current form's handle

Graphics g = Graphics.FromHwnd (this.Handle);

//Create a new pen with color blue and width = 4

Pen pn = new Pen (Color.Blue, 4);

//Draw a line from point pt to new point

g.DrawLine (pn, pt, newPoint);
//Dispose of Pen and Graphics objects
pn.Dispose();
g.Dispose();

Figure 2.10.gif

FIGURE 2.10: Using Point to draw a line

Figure 2.10 shows the output of Listing 2.3. This program draws a line from point 1 to point 2. The "Point" text in this figure is a menu item.

Like the Point structure, PointF can also use Empty, x, and y properties, as shown in Listing 2.4. You can test this code on a button or a menu click event handler.

LISTING 2.4: Creating PointF objects


//Create a new PointF object

PointF pt = new PointF (50.0f, 50.0f);

//Create a new point using PointF.Empty

PointF newPoint = PointF.Empty;

//Set x and y properties of PointF

newPoint.X = 100.0f;
newPoint.Y = 200.0f;

//Create a Graphics object from the current form's handle

Graphics g = Graphics.FromHwnd (this.Handle);

//Create a new pen with color blue and width 4

Pen pn = new Pen (Color.Blue, 4);

//Draw a line from point pt to new point

g.DrawLine (pn, pt, newPoint);

//Dispose of Pen and Graphics objects

pn.Dispose();
g.Dispose();


FIgure 2.11.gif

FIGURE 2.11: Using PointF to draw a line

Figure 2.11 shows the output of Listing 2.4. It is identical to Figure 2.10.

The Point structure also defines methods to convert from PointF to Point. The Ceiling method of the Point structure converts a PointF object to a Point object by rounding off the values of the PointF object to the next higher integer values. The Round method converts a PointF object to Point by rounding floating values to the nearest integer values. The Truncate method converts a PointF object to Point by truncating the floating values to integers. Listing 2.5 shows how to use the Ceiling, Round, and Truncate methods. You can test this code on a button or a menu click event handler.

LISTING 2.5 Using the Ceiling, Round, and Truncate methods of Point


//Create three points

PointF pt1 = new PointF(30.6f, 30.8f);
PointF pt2 = new PointF(50.3f, 60.7f);
PointF pt3 = new PointF(110.3f, 80.5f);

//Call Ceiling, round, and Truncate methods and return new points

Point pt4 = Point.Ceiling(pt1);
Point pt5 = Point.Round(pt2);
Point pt6 = Point.Truncate(pt3);

//display results

MessageBox.Show("Value of pt4: " +pt4.ToString());
MessageBox.Show("Value of p5: " +pt5.ToString());
MessageBox.Show("Value of pt6: " +pt6.ToString());


The Point structure also defines additional, equality, inequality, subtraction, Point-to-Size, and Point-to-PointF conversion operators. Listing 2.6 shows how do add and subtract a Size object from a Point object, convert from Point to PointF, and convert from a Point object to a Size object. You can test this code on a button or menu click event handler.

LISTING 2.6: Some Point and PointF conversions


//Create a Size object

Size sz = new Size(12,12);

//Create a Point object

Point pt = new Point (20, 20);

//Add point and size and copy to point

pt = pt+ sz;
MessageBox.Show("Addition : " + pt.ToString());

//Subtract point and size

pt = pt-sz;
MessageBox.Show("subtraction : " + pt.ToString());

//Create a PointF object from Point

PointF ptf = pt;
MessageBox.Show("PointF : " +pt.ToString());

//Convert Point to size

sz = (Size) pt;

MessageBox.Show("Size :" + sz.Width.ToString() + "," + sz.Height.ToString());


The Rectangle and RectangleF Structure

The Rectangle and RectangleF structure represent a rectangle in GDI+. A Rectangle structure stores the top left corner and height and width of a rectangle region. You can create a Rectangle object from Point and Size objects or by using four integer values as starting and ending coordinates of the rectangle.

The Rectangle and RectangleF structure provides properties that can be used to get the height, width, and position of the rectangle. Table 2.3 describes the properties of the Rectangle and RectangleF structures.

LISTING 2.7: Using Rectangle Properties


//Create Point, Size, and Rectangle objects

Point pt= new Point(10,10);
Size sz = new Size (60,40);
Rectangle rect1 = Rectangle.Empty;
Rectangle rect2 = new Rectangle (20, 30, 30, 10);


TABLE 2.3: Rectangle and RectangleF Properties

Property Description

Bottom

Return the y-coordinate of the bottom edge.

Height

Represents the rectangle's height.

IsEmpty

Returns true if all of the rectangle's values (starting point, height, and width) are zero, otherwise returns false.

Left

Returns the x-coordinates of the left edge.

Location

Represents the coordinates of the upper left corner.

Right

Returns the x-coordinate of the right edge.

Size

Represents the size of a rectangle.

Top

Return the y-coordinate of the top edge.

Width

Represents the width of a rectangle.

X

Represents the width of a rectangle.

Y

Represents the y-coordinate of the upper left corner.

 //Set Rectangle properties
if
(rect1.IsEmpty)
{
            rect1.Location = pt;
           rect1.Width = sz.Width;
            rect1.Height = sz.Height;
}
      //Get Rectangle properties
      string str = "Location: " + rect1.Location.ToString();
      str += ", X: "+ rect1.X.ToString();
      str += ", y:"+ rect1.Y.ToString();
      str += " Left : " +rect1.Left.ToString();
      str += ", Right:" + rect1.Right.ToString();
      str += ", Top: " + rect1.Top.ToString();
      str += ", Bottom:"+rect1.Bottom.ToString();
      MessageBox.Show(str);  


Listing 2.8 uses three different methods to create three Rectangle objects. The first method creates a Rectangle object by using a Point and a Size. The second and third methods create a Rectangle by using four integer values as the starting x- and y-coordinates and the width and height of the rectangle. After creating the rectangle, the program creates pen and brush objects using the Pen and SolidBrush classes and calls the fill and draw methods of Graphics to draw and fill the rectangles. Finally, we dispose of the objects. You can test this code on a button or menu click event handler.

LISTING 2.8: Creating Rectangle Objects


//Create a Graphics object

Graphics g = this.CreateGraphics();

int
x = 40;
int
y = 40;
int
height = 120;
int
width = 120;
//Create a Point object

Point pt = new Point (80, 80);

//Create a Size object

Size sz = new Size(100, 100);

//Create a rectangle from Point and size

Rectangle rect1 = new Rectangle (pt, sz);

//Create a rectangle from integers

Rectangle rect2 = new Rectangle (x, y, width, height);

//Create a rectangle from direct integers

Rectangle rect3 = new Rectangle(10, 10, 180, 180);

//Create pens and brushes

Pen redPen = new Pen (Color.Red, 2);
SolidBrush greenBrush = new SolidBrush (Color.Blue);
SolidBrush blueBrush = new SolidBrush (Color.Green);

//Draw and fill rectangles

g.DrawRectangle (redPen, rect3);
g.FillRectangle (blueBrush, rect2);
g.FillRectangle (greenBrush, rect1);

//Dispose of the objects

redPen.Dispose();
blueBrush.Dispose();
greenBrush.Dispose();
g.Dispose();


Figure 2.12 shows the output from Listing 2.8: three different rectangles.

Figure 2.12.jpg

FIGURES 2.12: Using Rectangle to create rectangles

You can create a Rectangle object in a similar way. The only difference is that RectangleF takes floating point arguments instead of integers, SizeF instead of Size, and PointF instead of Point. Listing 2.9 creates RectangleF objects from SizeF, PointF, Size and Point objects. You can test this code on a button or a menu click event handler.

LISTING 2.9: creating RectangleF objects


//Create a Graphics object

Graphics g = this.CreateGraphics();

float
x = 40.0f;
float
y = 40.0f;
float
height = 120.0f;
float
width = 120.0f;
//Create a Point object

PointF pt = new PointF (80.0f, 80.0f);

//Create a Size object

SizeF sz = new SizeF(100.0f, 100.0f);

//Create a rectangle from Point and size

RectangleF rect1 = new RectangleF (pt, sz);

//Create a rectangle from integers

RectangleF rect2 = new RectangleF (x, y, width, height);

//Create a rectangle from direct integers

RectangleF rect3 = new RectangleF(10.0f, 10.0f, 180.0f, 180.0f);

//Create pens and brushes

Pen redPen = new Pen (Color.Red, 2);
SolidBrush greenBrush = new SolidBrush (Color.Blue);
SolidBrush blueBrush = new SolidBrush (Color.Green);

//Draw and fill rectangles

g.DrawRectangle (redPen, rect3.X, rect3.Y, rect3.Width, rect3.Height);
g.FillRectangle (blueBrush, rect2);
g.FillRectangle (greenBrush, rect1);

//Dispose of the objects

redPen.Dispose();
blueBrush.Dispose();
greenBrush.Dispose();
g.Dispose();


Figure 2.13 shows the output from Listing 2.9: three different rectangles as in Figure 2.12.

Figure 2.13.jpg

FIGURE 2.13: Using RectangleF to create rectangles

TABLE 2.4: Rectangle and RectangleF methods


Method Description

Ceiling

Converts a RectangleF object to a Rectangle object by rounding the RectangleF values to the next higher integer values.

Contains

Determines if the specified point is contained within the rectangular region of a rectangle.

FromLTRB

Creates a rectangle with the specified edge locations.

Inflate

Creates and returns an inflated copy of a rectangle.

Intersect

Replaces a rectangle with the intersection of itself and another rectangle.

IntersectsWith

Determines it a specified rectangle intersects with rect.

Offset

Adjust the location of a specified rectangle by the specified amount.

Round

Converts a RectangleF object to a Rectangle object by rounding the RectangleF values of the nearest integer values.

Truncate

Converts a RectangleF object to a Rectangle object by truncating the RectangleF values.

Union

Returns a rectangle that contains the union of two Rectangle structure.


Like the Point and PointF structures, Rectangle and RectangleF define Ceiling, Round, and Truncate methods. These methods are described in Table 2.4. Listing 2.10 shows how to use these methods.

LISTING 2.10: Using the Round, Truncate, Union, inflate, Ceiling, and Intersect methods of Rectangle

//Create a Graphics object
Graphics g = this.CreateGraphics();
//Create PointF, SizeF, and RectangleF objects

PointF pt = new PointF(30.8f, 20.7f);
SizeF sz = new SizeF(60.0f, 40.0f);
RectangleF rect2 = new RectangleF (40.2f, 40.6f, 100.5f, 100.0f);
RectangleF rect1 = new RectangleF (pt, sz);
Rectangle rect3 = Rectangle.Ceiling(rect1);
Rectangle rect4 = Rectangle.Truncate(rect1);
Rectangle rect5 = Rectangle.Round(rect2);
//Draw rectangles

g.DrawRectangle(Pens.Black, rect3);
g.DrawRectangle(Pens.Red, rect5);
//Insert rectangles
Rectangle isectRect = Rectangle.Intersect (rect3, rect5);
//Fill new rectangle

g.FillRectangle(new SolidBrush(Color.Blue), isectRect);
//Create a Size object
Size inflateSize = new Size (0, 40);
// Inflate rectangle

isectRect.Inflate(inflateSize);
//Draw new rectangle

g.DrawRectangle (Pens.Blue, isectRect);
//Set Rectangle properties
rect4 = Rectangle.Empty;
rect4.Location = new Point (50, 50);
rect4.X = 30;
rect4.Y = 40;
//Union two rectangles
Rectangle unionRect = Rectangle.Union(rect4, rect5);
//Draw new rectangle

g.DrawRectangle (Pens.Green, unionRect);
//Dispose of the Graphics object

g.Dispose();     

Figure 2.14 shows the output from listing 2.10

The Size and SizeF Structures

The Size and SizeF structures represent the size of a rectangle area. Like Point/PointF and Rectangle/RectangleF, Size and SizeF also each have an Empty static field, which creates a Size object with zero height and zero width. The only difference between Size and SizeF is that Size uses integer values and SizeF uses floating point values.

You can create Size and SizeF objects by passing the width and height of the Point and PointF objects as constructor arguments, respectively. Listing 2.11 shows different ways to create Size and SizeF objects.

Figure 2.14.gif
FIGURE 2.14: Using the Round, Truncate, Union, Inflate, Ceiling, and Intersect methods of Rectangle.

LISTING 2.11 Creating Size and SizeF objects

Point pt1 = new Point (20,40);
PointF pt2 = new PointF (50.0f, 80.0f);
Size sz1 = new Size(pt1);
SizeF sz2 = new SizeF(pt2);
Size sz3 = new Size(100,150);
SizeF sz4 = new SizeF(12.5f, 87.6f);

The Height and Width properties represent the height and width respectively, of the area represented by the Size and SizeF structures. The IsEmpty property return true if Size has zero height and zero width; otherwise it returns false.

Like the Point/PointF and Rectangle/RectangleF structures, Size and SizeF have Ceiling, Truncate, and Round static methods. Each method can convert a SizeF object to a Size object: the Ceiling method by rounding the values of the Size structure to the next higher integer values; the Round method, by rounding the values of the Size structures to the nearest integer values; and the Truncate method, by truncating the values to the next lower integer values.

Listing 2.12 shows the use of the Ceiling, Round and Truncate methods. You can test this code on a button or a menu click event handler.

LISTING 2.12: Using the Ceiling, Round, and Truncate methods of Size and SizeF

      PointF pt1 = new PointF (20.6f, 30.8f);
      PointF pt2 = new PointF (50.3f, 60.7f);
      PointF pt3 = new PointF (110.3f, 80.5f);
      SizeF sz1 = new SizeF(pt1);
      SizeF sz2= new SizeF(pt2);
      SizeF sz3 = new SizeF(pt3);
      SizeF sz4 = Size.Ceiling(sz1);
      SizeF sz5 = Size.Round(sz2);
      SizeF sz6 = Size.Truncate(sz3);

Conclusion

Before you write a graphic application, a basic understanding of drawing surfaces and coordinates is a must. This article began with the basic of the drawing surface and the coordinate system, describing how drawing surface and coordinate system are represented in GDI+ and how the GDI+ coordinate system differs from other coordinate systems.

Before using any GDI+ related classes defined in the .NET Framework library, you must reference System.Drawing and its subnamespaces. In this article you learned how to add reference to the GDI+ library and how to import the GDI+ related namespaces into your application. After adding a reference to the GDI+ library and namespaces to the application, the nest step is to get the Graphics object. There are several ways to get a Graphics object in an application. This article discussed three different ways, and then showed how to use the Graphics class methods to draw and fill lines, rectangles, and ellipses. You also learned to dispose of objects when you're finished with them.

Finally, we covered some basic GDI+ structures - including Color, Rectangle, RectangleF, Point, PointF, Size and SizeF-describing their members and how to use them in your application.

You should now be able to write simple graphics applications using GDI+.