About shapes in the MapPoint object model

Article
11/16/2006

Shapes in Microsoft MapPoint are similar to shapes in other applications, such as Microsoft PowerPoint or WordArt. The differences mostly have to do with the shapes being drawn on a round globe as opposed to a flat presentation or document.

Note Most of the samples in this topic set the Name property of the shape as soon as it's created. Setting the name of a shape gives you a way to access the shape by name using the Item property of the Shapes collection. The name never appears in the user interface; it is only used when programming with the MapPoint object model.

Drawing lines

A line is defined by two Location objects. Use the AddLine method to draw a line. To learn more about Location objects, see Working with locations and finding places and address in the MapPoint object model.

  Sub TransPacific()
    Dim oMap As MapPoint.Map
    Set oMap = GetObject(, "MapPoint.Application").ActiveMap
    oMap.FindResults("Pacific Ocean")(1).GoTo

    Dim locLA, locTokyo As MapPoint.Location
    Set locLA = oMap.FindResults("Los Angeles, California")(1)
    Set locTokyo = oMap.FindResults("Tokyo, Japan")(1)

    ' Create and name the shape
    oMap.Shapes.AddLine(locLA, locTokyo).Name = "Tokyo Route"
End Sub

Drawing polylines

A polyline is a line that consists of more than two vertices. To create a polyline, pass an array of Location objects to the AddPolyline method. A polyline that has only two vertices is a line, even if it was created with the AddPolyline method.

To display a distance measurement with MapPoint, set the polyline's SizeVisible property to True. Distances are measured in GeoUnits. For information about calculating a distance, see "Measuring distances" in Working with locations and finding places and address in the MapPoint object model.

  Sub ViaHawaii()
    Dim oMap As MapPoint.Map
    Set oMap = GetObject(, "MapPoint.Application").ActiveMap

    oMap.FindResults("Pacific Ocean")(1).GoTo

    Dim locLA, locHawaii, locTokyo As MapPoint.Location
    Set locLA = oMap.FindResults("Los Angeles, California")(1)
    Set locHawaii = oMap.FindResults("Honolulu, Hawaii")(1)
    Set locTokyo = oMap.FindResults("Tokyo, Japan")(1)

    ' Create and name the shape
    Dim oShp As MapPoint.Shape
    Set oShp = oMap.Shapes.AddPolyline(Array(locLA, locHawaii, locTokyo))
    oShp.Name = "Tokyo Via Hawaii"
    oShp.SizeVisible = True
End Sub

To draw a closed polyline, make the first and last location the same.

  Sub BermudaTriangle()
    Dim oMap As MapPoint.Map
    Set oMap = GetObject(, "MapPoint.Application").ActiveMap

    Dim locFL, locPR, locB As MapPoint.Location
    Set locFL = oMap.FindResults("Fort Lauderdale, Florida")(1)
    Set locPR = oMap.FindResults("San Juan, Puerto Rico")(1)
    Set locB = oMap.FindResults("Bermuda")(1)

    Dim arrTri
    arrTri = Array(locFL, locPR, locB, locFL)

    ' Go there first
    oMap.Union(arrTri).GoTo

    ' Create and name the shape
    oMap.Shapes.AddPolyline(arrTri).Name = "Bermuda Triangle"

End Sub

Working with complex polylines

Every time you access an object in MapPoint from a Microsoft Visual Basic project, Visual Basic and MapPoint must communicate information about that object. This time is usually negligible, but it adds up quickly when operations involve more than a few hundred objects. If you are drawing complex shapes, you could be working with hundreds of Location objects and thus spending a lot of time setting up the communication between Visual Basic and MapPoint. You may want to consider writing an add-in executable to create and modify the shape. An add-in runs as part of MapPoint, not as a separate program, which makes communication faster and can result in a significant performance gain. For more information, see About creating a COM add-in.

Modifying polylines

To modify a polyline, use the Vertices property. This is the array of locations that were used to create the polyline. By setting the Vertices property to a new array of locations, you can modify an existing polyline. In this example, a line is turned into a polyline by adding an extra vertex.

  Sub TransPacificMod()
    Dim oMap As MapPoint.Map
    Set oMap = GetObject(, "MapPoint.Application").ActiveMap
    oMap.FindResults("Pacific Ocean")(1).GoTo

    Dim locLA, locHawaii, locTokyo As MapPoint.Location
    Set locLA = oMap.FindResults("Los Angeles, California")(1)
    Set locHawaii = oMap.FindResults("Honolulu, Hawaii")(1)
    Set locTokyo = oMap.FindResults("Tokyo, Japan")(1)

    ' Create and name the shape
    Dim oShp As MapPoint.Shape
    Set oShp = oMap.Shapes.AddLine(locLA, locTokyo)
    oShp.Name = "Tokyo Route"

    MsgBox "The line will be a polyline after this message."

    oShp.Vertices = Array(locLA, locHawaii, locTokyo)
End Sub

Drawing AutoShapes

AutoShapes in MapPoint are defined by a center point (the location of the shape) and width and height defined in GeoUnits. There are three types of AutoShapes: rectangle, oval, and radius. Rectangle and oval shapes have separate Width and Height properties. With the radius shape, Width and Height are always equal, and setting one results in the other being set.

AutoShape Shape objects have a Type property of geoAutoShape and an AutoShapeType property that distinguishes between the three kinds of AutoShapes.

The following example draws AutoShapes of each type.

  Sub EuroShapes()
    Dim oMap As MapPoint.Map
    Set oMap = GetObject(, "MapPoint.Application").ActiveMap
    oMap.Application.Units = geoKm
    Dim locDublin, locRome, locWarsaw As Location

    oMap.FindResults("Europe")(1).GoTo

    Set locDublin = oMap.FindResults("Dublin, Ireland")(1)
    Set locRome = oMap.FindResults("Rome, Italy")(1)
    Set locWarsaw = oMap.FindResults("Warsaw, Poland")(1)

    With oMap.Shapes
        .AddShape(geoShapeOval, locDublin, 1200, 800).Name = "Dublin"
        .AddShape(geoShapeRadius, locRome, 1200, 800).Name = "Rome"
        .AddShape(geoShapeRectangle, locWarsaw, 1200, 800).Name = "Warsaw"
    End With
End Sub

A radius is always drawn with the smaller of the two dimensions given.

The radius shape has a directional line that shows the size of the radius in miles or kilometers. You can change the angle of the directional line by using the Adjustments collection. (There is only one adjustment in MapPoint: the radius angle.)

  Sub MtPinatubo()
    Dim oMap As MapPoint.Map
    Set oMap = GetObject(, "MapPoint.Application").ActiveMap
    oMap.Application.Units = geoKm

    Dim locVolcano As MapPoint.Location

    oMap.FindResults("Luzon")(1).GoTo

    Set locVolcano = oMap.FindResults("Mount Pinatubo")(1)

    ' Give it that "radar" look
    Dim iRad, i As Integer
    iRad = 50
    For i = 1 To 3
        oMap.Shapes.AddShape(geoShapeRadius, locVolcano, iRad * 2 * i, iRad * 2 * i).Name = "Zone" & CStr(i)
        oMap.Shapes("Zone" & CStr(i)).Adjustments(1) = 45
    Next i
End Sub

Drawing text boxes

Text boxes are rectangles that are measured in pixels rather than GeoUnits. The FontColor property changes the color of the text. The following example draws a text box.

  Sub OhCanada()
    Dim oMap As MapPoint.Map
    Set oMap = GetObject(, "MapPoint.Application").ActiveMap

    oMap.FindResults("Canada")(1).GoTo

    Dim oShp As MapPoint.Shape
    Set oShp = oMap.Shapes.AddTextbox(oMap.Location, 100, 100)
    oShp.Text = "Largest country by land mass in Western Hemisphere"
    oShp.FontColor = vbRed
End Sub

Creating drivetime zones

A drivetime zone is a closed polyline that encloses all places that can be driven to from a center point in a specific amount of time. To create a drivetime zone, use the AddDrivetimeZone method. This example creates a 10-minute drivetime zone that is drawn behind (beneath) roads.

  Sub Atlanta10()
    Dim oMap As MapPoint.Map
    Set oMap = GetObject(, "MapPoint.Application").ActiveMap

    Dim oLoc As MapPoint.Location
    Set oLoc = oMap.FindAddressResults(, "Atlanta", , "GA")(1)
    oLoc.GoTo

    Dim oShp As MapPoint.Shape
    Set oShp = oMap.Shapes.AddDrivetimeZone(oLoc, geoOneMinute * 10)
    oShp.ZOrder geoSendBehindRoads
End Sub

Changing the z-order of shapes

Change the z-order of shapes by using the ZOrderPosition property and the ZOrder method.

You can also use the ZOrder method to specify that a shape be drawn behind roads.

  Sub ShapeOrder()
    Dim oMap As MapPoint.Map
    Set oMap = GetObject(, "MapPoint.Application").ActiveMap
    oMap.Application.Units = geoKm

    oMap.FindResults("Europe")(1).GoTo

    Dim shpLondon, shpParis, shpBrussles As MapPoint.Shape

    Set shpLondon = oMap.Shapes.AddShape(geoShapeRectangle, oMap.FindResults("London, England")(1), 800, 500)
    shpLondon.Name = "London"
    shpLondon.Fill.Visible = True
    shpLondon.Fill.ForeColor = vbWhite

    Set shpParis = oMap.Shapes.AddShape(geoShapeOval, oMap.FindResults("Paris, France")(1), 600, 700)
    shpParis.Name = "Paris"
    shpParis.Fill.Visible = True
    shpParis.Fill.ForeColor = vbWhite

    Set shpBrussles = oMap.Shapes.AddShape(geoShapeRadius, oMap.FindResults("Brussles, Belgium")(1), 500, 500)
    shpBrussles.Name = "Brussles"
    shpBrussles.Fill.Visible = True
    shpBrussles.Fill.ForeColor = vbWhite

    MsgBox "The z-order will change after this message."

    shpBrussles.ZOrder geoSendBehindRoads
    shpParis.ZOrderPosition = 1
End Sub

Modifying AutoShapes

AutoShapes are modified by setting the Location, Width, and Height properties. When either the width or height of a radius shape is changed, both are changed.

To learn about changing the line and fill of a shape, see "Setting the line format" and "Setting the fill format" below.

  Sub ShapeProps()
    Dim oMap As MapPoint.Map
    Set oMap = GetObject(, "MapPoint.Application").ActiveMap
    oMap.Application.Units = geoKm

    oMap.FindResults("Europe")(1).GoTo

    Dim shpLondon, shpParis, shpEUCapitol As MapPoint.Shape

    Set shpLondon = oMap.Shapes.AddShape(geoShapeRectangle, oMap.FindResults("London, England")(1), 600, 500)
    shpLondon.Name = "London"
    shpLondon.Fill.Visible = True
    shpLondon.Fill.ForeColor = vbWhite

    Set shpParis = oMap.Shapes.AddShape(geoShapeOval, oMap.FindResults("Paris, France")(1), 600, 500)
    shpParis.Name = "Paris"
    shpParis.Fill.Visible = True
    shpParis.Fill.ForeColor = vbWhite

    Set shpEUCapitol = oMap.Shapes.AddShape(geoShapeRadius, oMap.FindResults("Rome, Italy")(1), 500, 500)
    shpEUCapitol.Name = "EUCapitol"
    shpEUCapitol.Fill.Visible = True
    shpEUCapitol.Fill.ForeColor = vbWhite

    MsgBox "The properties will change after this message."

    shpLondon.Width = 700
    shpParis.Height = 700
    shpEUCapitol.Height = 700
    Set shpEUCapitol.Location = oMap.FindResults("Brussels, Belgium")(1)
End Sub

Setting the line format

The LineFormat object has properties that can be used to change the look of a line. This example draws a line from London to Paris, sets the line weight, makes it blue, and gives it an arrowhead pointing to Paris. It then displays the size of the line.

  Sub CrossChannel()
    Dim oMap As MapPoint.Map
    Set oMap = GetObject(, "MapPoint.Application").ActiveMap

    Dim locLondon, locParis As MapPoint.Location
    Set locLondon = oMap.FindResults("London, England")(1)
    Set locParis = oMap.FindResults("Paris, France")(1)

    oMap.Union(Array(locLondon, locParis)).GoTo
    oMap.ZoomOut

    Dim oShp As MapPoint.Shape
    ' Create and name the shape
    Set oShp = oMap.Shapes.AddPolyline(Array(locLondon, locParis))
    oShp.Name = "London to Paris"
    oShp.Line.EndArrowhead = True
    oShp.Line.ForeColor = vbBlue
    oShp.Line.Weight = 4
    oShp.SizeVisible = True
End Sub

Setting the fill format

Shape objects can have a fill as well as line formatting properties. The FillFormat object has properties that allow you to change the look of the fill. The following code draws a textbox, hides the line, and makes the fill blue and the text yellow.

  Sub FillProps()
    Dim oMap As MapPoint.Map
    Set oMap = GetObject(, "MapPoint.Application").ActiveMap
    oMap.Application.Units = geoMiles
    oMap.FindResults("Canada")(1).GoTo

    Dim oShp As MapPoint.Shape
    Set oShp = oMap.Shapes.AddShape(geoShapeRectangle, oMap.Location, 800, 400)
    oShp.Text = "Largest country by land mass in Western Hemisphere"
    oShp.Line.Visible = False
    oShp.Fill.Visible = True
    oShp.Fill.ForeColor = vbBlue
    oShp.FontColor = vbYellow
End Sub