English

How To: Mimic the functionality of the Auto-Label dialog box via Avenue's TextPositioner class

Summary

Note:
The information in this article applies to ArcView GIS versions 3.x only. The instructions described apply to the Avenue programming language, which is specific to the ArcView GIS application.

This document describes one of two ways to mimic the functionality of the Auto-Label dialog box via Avenue's TextPositioner Class. The other alternative is to use the Labeler Class, which is covered by the document in the Related Information section.

Procedure

The TextPositioner class, through its subclasses, allows you to position a text string relative to specific kinds of shapes:

PolyTextPositioner
LineTextPositioner
PointTextPositioner

Each of these can be used in two different ways. For example:

thePointTextPositioner = PointTextPositioner.Make
is the same as:
thePointTextPositioner = TextPositioner.Make(Point)

You may set the desired vertical and horizontal relationships between text and shape by using elements of the enumerations TextPositionerHAlignEnum and TextPositionerVAlignEnum. You can obtain these relationships from the settings under the Theme Properties menu option. These vertical and horizontal enumerations allow you to choose the position of the text in relation to the shape you are labeling within a script.

Vertical enumerations:

#TEXTPOSITIONER_VALIGN_ABOVE
#TEXTPOSITIONER_VALIGN_BELOW
#TEXTPOSITIONER_VALIGN_BOTTOM
#TEXTPOSITIONER_VALIGN_ON
#TEXTPOSITIONER_VALIGN_TOP

Horizontal enumerations:

#TEXTPOSITIONER_HALIGN_AFTER
#TEXTPOSITIONER_HALIGN_BEFORE
#TEXTPOSITIONER_HALIGN_CENTER
#TEXTPOSITIONER_HALIGN_LEFT
#TEXTPOSITIONER_HALIGN_RIGHT

TextPositioner objects are used by themes when being labeled. See the online help for more information on the TexPositioner class.

  • The following sample script uses the TextPositioner class to label a theme on a Single field.
'-- Can be used with States.shp sample data set and
'-- works on selected features.
theView = av.GetActiveDoc
theDisplay = theView.GetDisplay
theGraphicList = theView.GetGraphics

'-- Get and labels the first active theme in the view
theActiveThemeList=theView.GetActiveThemes
theTheme = theActiveThemeList.Get(0)
theFtab = theTheme.GetFtab
theShapeField = theFtab.FindField("Shape")

'-- Define the label field
'-- Change the field name accordingly
theStringField = theFtab.findfield("State_name")

'-- This script works on a selected set of features
theSelectedSet = theFtab.GetSelection
for each p in theSelectedSet

'-- Get the SHAPE to label 
    theShape = theFtab.ReturnValue(theShapeField,p)

'-- Create a String to use as the label text
    thestring = theftab.returnvalue(thestringfield, p)

'-- Create a textPositioner using the correct shape
'-- class of your features
    theTextPositioner = TextPositioner.Make(theShape.GetClass)
     
'-- Choose vertical and horizontal alignment enumerations
    theTextPositioner.SetVAlign(#TEXTPOSITIONER_VALIGN_ABOVE) 
    theTextPositioner.SetHAlign(#TEXTPOSITIONER_HALIGN_CENTER)

'-- Create the GraphicText object using the label string
'-- and a temporary point
    theGraphicText = GraphicText.Make(theString,Point.Make(0,0))

'-- Set the GraphicText to a Display so it knows where to draw.
'-- The display can be either PageDisplay (Layout) or MapDisplay (View)
    theGraphicText.SetDisplay(theDisplay)

'-- Use the Calculate request to calculate the
'-- position of the TextPositioner
    theTextPositioner.Calculate(theShape,theGraphicText.GetExtent,0,nil)
    theOrigin = TheTextPositioner.GetOrigin
    theAngle = theTextPositioner.GetAngle

'-- Set the Origin and Angle of the GraphicText using
'-- info returned from the textPositioner
'-- in the previous two lines
    theGraphicText.SetOrigin(theOrigin)
    theGraphicText.SetAngle(theAngle)

'-- Add the GraphicText to the graphics list 
    theGraphicList.Add(theGraphicText)
end
theView.Invalidate
System.RefreshWindows
  • Example 1: Using TextPositioner to label a single theme on Multiple fields by varying the vertical and horizontal alignment enumerations for each label.
'-- Can be used with States.shp sample data set and
'-- works on selected features.
theView = av.GetActiveDoc
theDisplay = theView.GetDisplay
theGraphicList = theView.GetGraphics

theActiveThemeList = theView.GetActiveThemes
theTheme = theActiveThemeList.Get(0)
theFtab = theTheme.GetFtab
theShapeField = theFtab.FindField("Shape")

'-- Return two different fields for labeling
theStringField = theFtab.findfield("State_name")
theStringField2 = theFtab.findfield("State_abbr")

theSelectedSet = theFtab.GetSelection
for each p in theSelectedSet

    theShape = theFtab.ReturnValue(theShapeField,p)
    thestring = theftab.returnvalue(thestringfield, p)
    thestring2 = theftab.returnvalue(thestringfield2, p)

    theTextPositioner = TextPositioner.Make(theShape.GetClass)
    theTextPositioner2 = TextPositioner.Make(theShape.GetClass)
    theTextPositionerType = theTextPositioner.GetClass.GetClassName
    theTextPositionerType2 = theTextPositioner2.GetClass.GetClassName
 
'-- When positioning the test with the vertical and
'-- horizontal alignments, choose two different locations
'-- for the text so they do NOT overlap.
    theTextPositioner.SetVAlign(#TEXTPOSITIONER_VALIGN_ABOVE) 
    theTextPositioner.SetHAlign(#TEXTPOSITIONER_HALIGN_CENTER)
    theTextPositioner2.SetVAlign(#TEXTPOSITIONER_VALIGN_BELOW) 
    theTextPositioner2.SetHAlign(#TEXTPOSITIONER_HALIGN_CENTER)    
    
    theGraphicText = GraphicText.Make(theString,Point.Make(0,0))
    theGraphicText2 = GraphicText.Make(theString2,Point.Make(0,0))

    theGraphicText.SetDisplay(theDisplay) 
    theGraphicText2.SetDisplay(theDisplay) 
    
    theTextPositioner.Calculate(theShape,theGraphicText.GetExtent,0,nil) 
    theTextPositioner2.Calculate(theShape,theGraphicText2.GetExtent,0,nil)
    
    theOrigin = TheTextPositioner.GetOrigin
    theAngle = theTextPositioner.GetAngle
    theOrigin2 = TheTextPositioner2.GetOrigin
    theAngle2 = theTextPositioner2.GetAngle
    
    theGraphicText.SetOrigin(theOrigin)
    theGraphicText.SetAngle(theAngle) 
    theGraphicText2.SetOrigin(theOrigin2)
    theGraphicText2.SetAngle(theAngle2) 

    theGraphicList.Add(theGraphicText)
    theGraphicList.Add(theGraphicText2)
    
end 

theView.Invalidate
System.RefreshWindows 
  • Example 2: Using TextPositioner to label a single theme on Multiple fields by concatenating all label strings into a single string and labeling at a single position.
'-- Can be used with States.shp sample data set and
'-- works on selected features.
theView = av.GetActiveDoc
theDisplay = theView.GetDisplay
theGraphicList = theView.GetGraphics

theActiveThemeList = theView.GetActiveThemes
theTheme = theActiveThemeList.Get(0)
theFtab = theTheme.GetFtab
theShapeField = theFtab.FindField("Shape")

'-- Return three different fields for labeling

theStringField = theFtab.findfield("State_name")
theStringField2 = theFtab.FindField("State_fips")
thestringField3 = theFtab.FindField("State_abbr")

theSelectedSet = theFtab.GetSelection
for each p in theSelectedSet

    theShape = theFtab.ReturnValue(theShapeField,p)
    thestring = theftab.returnvalue(thestringfield, p)
    theString2 = theFtab.ReturnValue(theStringField2, p)
    theString3 = theFtab.ReturnValue(thestringField3, p)

'-- Construct a label string by concatenating three
'-- label strings together with NL (newline) characters.
    theString4 = thestring+NL+theString2+NL+theString3
    msgbox.info(thestring4,"")
    theTextPositioner = TextPositioner.Make(theShape.GetClass)
    theTextPositionerType = theTextPositioner.GetClass.GetClassName

'-- Choose a single position to label from
    theTextPositioner.SetVAlign(#TEXTPOSITIONER_VALIGN_ON) 
    theTextPositioner.SetHAlign(#TEXTPOSITIONER_HALIGN_CENTER)
        
    theGraphicText = GraphicText.Make(theString4,Point.Make(0,0))
    theGraphicText.SetDisplay(theDisplay) 
    
    theTextPositioner.Calculate(theShape,theGraphicText.GetExtent,0,nil) 
    
    theOrigin = TheTextPositioner.GetOrigin
    theAngle = theTextPositioner.GetAngle
    theGraphicText.SetOrigin(theOrigin)
    theGraphicText.SetAngle(theAngle) 
    
    theGraphicList.Add(theGraphicText)
end 

theView.Invalidate
System.RefreshWindows 
Note:
If you are trying to label on three different fields, you may notice that even though you choose three different positions to stack on top of each other, the labels overlap slightly.  You can get around this by creating one text object from three fields and then choosing one position to label. 

Related Information