Home > Articles > Programming > Windows Programming

This chapter is from the book

Collections of Shapes

It is often useful to collect various "building block" shapes into a single unit. Rather than managing each rectangle in a bar graph, for instance, it is often easier to group these objects into a single, manageable unit. If the objects need to be moved or redrawn, you can simply make one method call. Similarly, if you are transforming the objects, maybe rotating them all 45°, it is much easier to transform a group than transform each item independently. The System.Drawing.Drawing2D namespace provides us the Path class for grouping shapes.

Additionally, once you've defined your various object groups, it is often necessary to indicate how those groups interact with one another. If you've ever used a drawing application, you are undoubtedly familiar with the concepts of bring-to-front and send-to-back. These are features that allow an artist to indicate how shapes (or groups of shapes) relate to one another in layers. The System.Drawing namespace gives us the Region class for indicating object interaction and layers.

Paths

Paths enable more advanced drawing techniques in .NET. A path is made of one or more geometric shapes (rectangle, line, curve, and so on). By grouping shapes together in a path, we are able to manage and manipulate the group as one object. We add shapes to a path for storage in what is called the world coordinate space. This coordinate system is essentially virtual. It is the place where the shapes logically exist in memory relative to one another. The graphic can then be manipulated as a whole. It can be drawn to the screen over and over. In addition, it can be transformed (rotated, sheared, reflected, scaled) when moving from this logical world space to the physical device space (form). For example, you might have a 10 x 20 rectangle stored inside a path. When you place it on the form, you can rotate it 20° and sheer the rectangle. The key is that the rectangle still exists as a 10 x 20 rectangle (not rotated, not sheared) in the world space.

To create a path, we use the GraphicsPath class. This class provides methods like AddLine, AddRectangle, AddArc, and so on; each adds their shape to the path. Paths can contain multiple figures or groups of shapes that represent one object. When adding a shape to a path, it is best to indicate to which figure the shape belongs. We do this by calling the StartFigure method. Each subsequent call to an add function adds the shape to the figure. If we call StartFigure again, a new figure is started and all following shapes are added to the new figure. We call the CloseFigure method prior to starting a new figure if we wish the figure to be closed off, or connected from start point to end point.

Listing 9.6 creates a GraphicsPath instance. We add a few shapes to the GraphicsPath class and then display the path to the form.

Listing 9.6 GraphicsPath

Private Sub Button1_Click(ByVal sender As System.Object, _
  ByVal e As System.EventArgs) Handles Button1.Click

  'dimension variables of local scope
  Dim myGraphics As Graphics
  Dim myPen As New Pen(color:=Color.Blue, Width:=2)
  Dim myPath As System.Drawing.Drawing2D.GraphicsPath
  Dim myPoints(2) As Point

  'create a new GraphicsPath instance with default values
  myPath = New System.Drawing.Drawing2D.GraphicsPath()

  'start the figure
  myPath.StartFigure()

  'add an ellipse for the head
  myPath.AddEllipse(x:=0, y:=0, Width:=50, Height:=70)

  'add 2 ellipses to the eyes
  myPath.AddEllipse(x:=10, y:=10, Width:=10, Height:=8)
  myPath.AddEllipse(x:=30, y:=10, Width:=10, Height:=8)

  'add bezier for the nose
  myPath.AddBezier( _
    pt1:=New Point(x:=25, y:=30), _
    pt2:=New Point(x:=15, y:=30), _
    pt3:=New Point(x:=20, y:=40), _
    pt4:=New Point(x:=25, y:=40))

  'add a points to make a curve for the mouth
  myPath.StartFigure()
  myPoints(0) = New Point(x:=10, y:=50)
  myPoints(1) = New Point(x:=25, y:=60)
  myPoints(2) = New Point(x:=40, y:=50)
  myPath.AddCurve(points:=myPoints)

  'return the current form as a drawing surface
  myGraphics = Graphics.FromHwnd(hwnd:=ActiveForm().Handle)

  'output the Path to the drawing surface of the form
  myGraphics.DrawPath(pen:=myPen, path:=myPath)

End Sub

If you use paths a lot, you will want to check out the Flatten method of the GraphicsPath class. This method allows you to change how items are stored within the object instance. By default, state is maintained for each item added to the path. This means that if a curve and an ellipse, for instance, are stored in a GraphicsPath, then data for the curve's points and control points as well as data that defines the ellipse is stored in the object. By flattening the path, you allow the object to manage the shape as a series of line segments, thus reducing overhead. In a completely flattened path, all points are stored as points to be connected by line segments.

Regions and Clipping

A region is a section of the screen defined by a given path or rectangle. Regions allow you to define clip areas and do hit-testing based on a graphics area. Clipping involves one shape defining the border, or area, of another shape. Additional items drawn within a defined region are constrained by the region; that is, a line with a width of 50 drawn within a rectangular region whose width is 20 will be cropped to 20 for display. Hit-testing simply allows your application to know when the user has placed the mouse over a given region or if another shape is contained within the area defined by the region. For example, if you define a region based on a rectangle, you can trap when a user clicks on the rectangle or when his or her mouse travels over the rectangle.

You use the Region class to create regions with the namespace. An instance of the Region class can be created with either a valid Rectangle instance or a Path object. To hit-test, you use the IsVisible method of the Region class. Once a region has been defined, you can pass a point or a rectangle and a valid graphics surface as parameters to the IsVisible method. This method simply returns True if the given point or rectangle is contained within the Region; otherwise, it returns False. The following is an example of this method call; it displays the return of the IsVisible method to a message box.

MsgBox(prompt:=myRegion.IsVisible(x:=75, y:=75, g:=myGraphics))

You still draw with the Graphics class, but the Region class allows you to set parameters for drawing. For example, you set the region parameter of the SetClip method of the Graphics object to your instance of Region. This tells the graphics object that your Region further defines the graphics area on the given drawing surface.

Listing 9.7 presents a clipping example. We first draw a rectangle and add it to a Path object. We then define a Region instance based on the Path object. After that, we call the SetClip method of our Graphics container and pass in the Region object. Finally, we draw a number of strings to the graphic surface; notice how our defined region clips them.

Listing 9.7 Clipping with the Region Class

Private Sub Button1_Click(ByVal sender As System.Object, _
  ByVal e As System.EventArgs) Handles Button1.Click

  'local scope
  Dim myGraphics As Graphics
  Dim myPen As New Pen(color:=Color.Blue, Width:=2)
  Dim myPath As New System.Drawing.Drawing2D.GraphicsPath()
  Dim myPoints(2) As Point
  Dim myRegion As Region
  Dim i As Short

  'define a triangle
  myPath.StartFigure()
  myPoints(0) = New Point(x:=100, y:=20)
  myPoints(1) = New Point(x:=50, y:=100)
  myPoints(2) = New Point(x:=150, y:=100)

  'add triangle to the path
  myPath.AddPolygon(points:=myPoints)

  'create a region based on the path
  myRegion = New Region(path:=myPath)

  'return the current form as a drawing surface
  myGraphics = Graphics.FromHwnd(hwnd:=ActiveForm().Handle)

  'draw the region's outline to the screen
  myGraphics.DrawPath(pen:=myPen, path:=myPath)

  'set the clipping region
  myGraphics.SetClip(Region:=myRegion, _
    combineMode:=Drawing.Drawing2D.CombineMode.Replace)

  'draw the string multiple times
  For i = 20 To 100 Step 20

    'draw clipped text
    myGraphics.DrawString(s:="Clipping Region", _
    Font:=New Font(familyName:="Arial", emSize:=18, _
    style:=FontStyle.Regular, _
    unit:=GraphicsUnit.Pixel), _
    brush:=New SolidBrush(color:=Color.Red), _
    x:=50, y:=i)

  Next

End Sub

Did you notice that when we called SetClip we also set something called the combineMode? This indicates how the two regions or shapes should be combined. In our case, we had a triangular Region object and a few strings that we drew. We set the combineMode enumeration to Replace to indicate that the string information should replace the region inside the triangle. Of course, there are a number of additional members to this enumeration. Table 9.9 lists them. Also, note that each enumeration member has a corresponding method on the Region class (Region.Replace for example).

Table 9.9 Region Combine Modes

Enumeration Member

Example Output

Description

 

This is an example of the two objects that we are combining. The rectangle represents the clipping region.

Complement

The Complement member indicates that only the portion of the second region that does not intersect with the first should be updated.

Exclude

The Exclude member indicates that the intersecting portion of the second region should be excluded from the first region. The result is only points that belong to the first region specifically.

Intersect

The Intersect member indicates that only points common to both regions should be valid.

Replace

The Replace member indicates that the second region replaces the internal region defined by the first. That is, the first region now contains, or defines the area for, the second region.

Union

The Union member indicates that both regions should be joined. The result is an area that is defined by all points in both regions.

Xor

The Xor member is the opposite of the Intersect member. It contains all points that are not common to either region.


The following code was used to create the example graphics in the previous table. Note that we created two regions and combined them using the Region.[Method] syntax.

'local scope
Dim myGraphics As Graphics
Dim myPath As New System.Drawing.Drawing2D.GraphicsPath()
Dim myPath2 As New System.Drawing.Drawing2D.GraphicsPath()
Dim myRegion As Region
Dim myRegion2 As Region

'return the current form as a drawing surface
myGraphics = Graphics.FromHwnd(hwnd:=ActiveForm().Handle)

'create the first path and region
myPath.StartFigure()
myPath.AddRectangle(rect:=New Rectangle(x:=50, y:=50, Width:=50, _
  Height:=20))
myRegion = New Region(path:=myPath)

'create the first path and region
myPath2.StartFigure()
Dim myRec As New Rectangle(x:=35, y:=45, Width:=50, Height:=30)
myPath2.AddEllipse(rect:=myRec)
myRegion2 = New Region(path:=myPath2)

'add the paths together 
myRegion.Complement(Region:=myRegion2)

'fill the region
myGraphics.FillRegion(brush:=New SolidBrush(Color.Black), _ 
  Region:=myRegion) 

Suggestions for Further Exploration

  • Write code using the following methods of the GraphicsPath class: Warp and Widen.

  • Use the interior of text to outline a clipping region. Create a Path based on a string and use the path to create the Region.

InformIT Promotional Mailings & Special Offers

I would like to receive exclusive offers and hear about products from InformIT and its family of brands. I can unsubscribe at any time.

Overview


Pearson Education, Inc., 221 River Street, Hoboken, New Jersey 07030, (Pearson) presents this site to provide information about products and services that can be purchased through this site.

This privacy notice provides an overview of our commitment to privacy and describes how we collect, protect, use and share personal information collected through this site. Please note that other Pearson websites and online products and services have their own separate privacy policies.

Collection and Use of Information


To conduct business and deliver products and services, Pearson collects and uses personal information in several ways in connection with this site, including:

Questions and Inquiries

For inquiries and questions, we collect the inquiry or question, together with name, contact details (email address, phone number and mailing address) and any other additional information voluntarily submitted to us through a Contact Us form or an email. We use this information to address the inquiry and respond to the question.

Online Store

For orders and purchases placed through our online store on this site, we collect order details, name, institution name and address (if applicable), email address, phone number, shipping and billing addresses, credit/debit card information, shipping options and any instructions. We use this information to complete transactions, fulfill orders, communicate with individuals placing orders or visiting the online store, and for related purposes.

Surveys

Pearson may offer opportunities to provide feedback or participate in surveys, including surveys evaluating Pearson products, services or sites. Participation is voluntary. Pearson collects information requested in the survey questions and uses the information to evaluate, support, maintain and improve products, services or sites, develop new products and services, conduct educational research and for other purposes specified in the survey.

Contests and Drawings

Occasionally, we may sponsor a contest or drawing. Participation is optional. Pearson collects name, contact information and other information specified on the entry form for the contest or drawing to conduct the contest or drawing. Pearson may collect additional personal information from the winners of a contest or drawing in order to award the prize and for tax reporting purposes, as required by law.

Newsletters

If you have elected to receive email newsletters or promotional mailings and special offers but want to unsubscribe, simply email information@informit.com.

Service Announcements

On rare occasions it is necessary to send out a strictly service related announcement. For instance, if our service is temporarily suspended for maintenance we might send users an email. Generally, users may not opt-out of these communications, though they can deactivate their account information. However, these communications are not promotional in nature.

Customer Service

We communicate with users on a regular basis to provide requested services and in regard to issues relating to their account we reply via email or phone in accordance with the users' wishes when a user submits their information through our Contact Us form.

Other Collection and Use of Information


Application and System Logs

Pearson automatically collects log data to help ensure the delivery, availability and security of this site. Log data may include technical information about how a user or visitor connected to this site, such as browser type, type of computer/device, operating system, internet service provider and IP address. We use this information for support purposes and to monitor the health of the site, identify problems, improve service, detect unauthorized access and fraudulent activity, prevent and respond to security incidents and appropriately scale computing resources.

Web Analytics

Pearson may use third party web trend analytical services, including Google Analytics, to collect visitor information, such as IP addresses, browser types, referring pages, pages visited and time spent on a particular site. While these analytical services collect and report information on an anonymous basis, they may use cookies to gather web trend information. The information gathered may enable Pearson (but not the third party web trend services) to link information with application and system log data. Pearson uses this information for system administration and to identify problems, improve service, detect unauthorized access and fraudulent activity, prevent and respond to security incidents, appropriately scale computing resources and otherwise support and deliver this site and its services.

Cookies and Related Technologies

This site uses cookies and similar technologies to personalize content, measure traffic patterns, control security, track use and access of information on this site, and provide interest-based messages and advertising. Users can manage and block the use of cookies through their browser. Disabling or blocking certain cookies may limit the functionality of this site.

Do Not Track

This site currently does not respond to Do Not Track signals.

Security


Pearson uses appropriate physical, administrative and technical security measures to protect personal information from unauthorized access, use and disclosure.

Children


This site is not directed to children under the age of 13.

Marketing


Pearson may send or direct marketing communications to users, provided that

  • Pearson will not use personal information collected or processed as a K-12 school service provider for the purpose of directed or targeted advertising.
  • Such marketing is consistent with applicable law and Pearson's legal obligations.
  • Pearson will not knowingly direct or send marketing communications to an individual who has expressed a preference not to receive marketing.
  • Where required by applicable law, express or implied consent to marketing exists and has not been withdrawn.

Pearson may provide personal information to a third party service provider on a restricted basis to provide marketing solely on behalf of Pearson or an affiliate or customer for whom Pearson is a service provider. Marketing preferences may be changed at any time.

Correcting/Updating Personal Information


If a user's personally identifiable information changes (such as your postal address or email address), we provide a way to correct or update that user's personal data provided to us. This can be done on the Account page. If a user no longer desires our service and desires to delete his or her account, please contact us at customer-service@informit.com and we will process the deletion of a user's account.

Choice/Opt-out


Users can always make an informed choice as to whether they should proceed with certain services offered by InformIT. If you choose to remove yourself from our mailing list(s) simply visit the following page and uncheck any communication you no longer want to receive: www.informit.com/u.aspx.

Sale of Personal Information


Pearson does not rent or sell personal information in exchange for any payment of money.

While Pearson does not sell personal information, as defined in Nevada law, Nevada residents may email a request for no sale of their personal information to NevadaDesignatedRequest@pearson.com.

Supplemental Privacy Statement for California Residents


California residents should read our Supplemental privacy statement for California residents in conjunction with this Privacy Notice. The Supplemental privacy statement for California residents explains Pearson's commitment to comply with California law and applies to personal information of California residents collected in connection with this site and the Services.

Sharing and Disclosure


Pearson may disclose personal information, as follows:

  • As required by law.
  • With the consent of the individual (or their parent, if the individual is a minor)
  • In response to a subpoena, court order or legal process, to the extent permitted or required by law
  • To protect the security and safety of individuals, data, assets and systems, consistent with applicable law
  • In connection the sale, joint venture or other transfer of some or all of its company or assets, subject to the provisions of this Privacy Notice
  • To investigate or address actual or suspected fraud or other illegal activities
  • To exercise its legal rights, including enforcement of the Terms of Use for this site or another contract
  • To affiliated Pearson companies and other companies and organizations who perform work for Pearson and are obligated to protect the privacy of personal information consistent with this Privacy Notice
  • To a school, organization, company or government agency, where Pearson collects or processes the personal information in a school setting or on behalf of such organization, company or government agency.

Links


This web site contains links to other sites. Please be aware that we are not responsible for the privacy practices of such other sites. We encourage our users to be aware when they leave our site and to read the privacy statements of each and every web site that collects Personal Information. This privacy statement applies solely to information collected by this web site.

Requests and Contact


Please contact us about this Privacy Notice or if you have any requests or questions relating to the privacy of your personal information.

Changes to this Privacy Notice


We may revise this Privacy Notice through an updated posting. We will identify the effective date of the revision in the posting. Often, updates are made to provide greater clarity or to comply with changes in regulatory requirements. If the updates involve material changes to the collection, protection, use or disclosure of Personal Information, Pearson will provide notice of the change through a conspicuous notice on this site or other appropriate way. Continued use of the site after the effective date of a posted revision evidences acceptance. Please contact us if you have questions or concerns about the Privacy Notice or any objection to any revisions.

Last Update: November 17, 2020