An introduction to avenue

In this lesson, you will learn: • how Avenue organizes objects into classes • what requests and statements are • the basic structure of an Avenue request • how to assign a variable • what an object model diagram is • what an FTab is and how to work with one

Putting objects to work: Using requests Using statements to control requests Assigning variables

Example

Objects and classes in the real world

Topic: Using Avenue

Concepts

What's the first line in an Avenue script?

Understanding the object model diagrams Object relationships

Request keywords Making objects Getting object properties Setting object properties Working with FTabs Understanding lists

Example

Opening a table Lesson summary

Lesson self tes

Goals

In this lesson, you will learn:

• how Avenue organizes objects into classes

• what requests and statements are

• the basic structure of an Avenue request

• how to assign a variable

• what an object model diagram is

• what an FTab is and how to work with one

TOPIC 1: Getting to know Avenue

Before you can write an Avenue script to solve a spatial problem even before you enter

expressions into the Map Calculator you must know the basic components of the Avenue programming language These components include objects, classes, class hierarchy, object model diagrams, requests, statements, and variables

Concept

Working with Avenue

Avenue is a programming language that was created by ESRI to help you customize and extend the functionality of ArcView Using Avenue, you can create scripts to automate tasks and solve problems that are not handled by the normal ArcView interface By changing the buttons, tools, and menus (collectively called controls) in the user interface, you can create an application that iscustomized to your specific needs or tasks

Avenue is also a development environment that provides tools you can use to create Avenue scripts The script editor window is where you write, compile, and debug your scripts

Avenue scripts are created, debugged, compiled, and tested in Script Editor documents [Click to enlarge]

The Customize dialog box is an interface which you can use to modify or create controls In order for a control to carry out an action, you must define the action in a script and link the script to the control When the user interacts with the control, your associated script carries out the action

You can use the Customize dialog box to add, delete, and modify controls

Here, the Zoom In button in the view button bar was selected Various properties associated with the button (shown at the bottom of the dialog) can be changed, including its function, icon, and the help messages it displays.

To successfully customize ArcView, you don't have to be an experienced Avenue programmer Simple customizations like creating, rearranging, or deleting buttons and tools requires no programming at all Knowing a little Avenue can extend your capabilities, however, and help you create custom applications to solve spatial problems

Concept

Understanding objects

In Avenue, an object is something that has a set of characteristics or properties, a set of things it does, and a current state For instance, a car has a unique set of properties that define it: make, model, color, number of doors, and so on A car also has some actions or set of things you can dowith it: start, stop, turn left, turn right; and a car has a state or current mode: speed, fuel

consumption, travel direction You can describe almost any object by identifying its properties, actions, and current state

The properties, actions, and states that a car object can have.

An object may be related to other objects in many ways

• An object may be composed of other objects: A car contains, among other things, a radio,

a steering wheel and seats

• An object may use other objects: A car uses fuel to move

• An object may be associated with other objects: Someone drives the car along a

highway Each related object has its own properties and things it does

In ArcView, everything you work with is an object When you open a view, you're working with a View object; when you add a theme to that view, you're working with a Theme object; when you add a button to the interface, you're working with a Button object

Interacting with the user interface is one way to manipulate ArcView's objects; the other way is by directly accessing the objects through Avenue To do that, you need to identify which objects you want to work with by understanding how ArcView organizes objects into classes

Concept

Understanding how classes organize objects

Objects with similar characteristics are grouped together into a class A class defines the

properties and actions for a specific type of object All objects in a specific class are defined with the same properties

Objects created from the same class are called instances of the class For example, in the figure below, the two cars are instances of the class "Car" and assume the properties defined by the class (cars have wheels and doors) Similarly, in ArcView, Save, Add Theme, and Open Theme Table are all instances of the class "Button."

An individual object is an instance of the class that defines it.

Classes may be further organized through a class hierarchy that defines the relationship betweenclasses One way to illustrate these relationships is through an object model diagram Object model diagrams consist of boxes which represent classes and lines that connect them to show the kinds of relationship between classes By examining an object model diagram, you can quickly see how classes and objects created from them interrelate

The object model diagram can show several types of relationships: generalization (inheritance), aggregation (composition), association, and multiplicity

Inheritance

Inheritance relationships allow for a progressive refinement of classes from the more general to the more specific A superclass groups classes with common properties, and its subclasses inherit the properties it defines Through inheritance, properties need only be defined once in the hierarchy For instance, the superclass Car defines certain properties that all cars share

The symbol for inheritance is an open triangle Any property that is unique to a particular subclass(i.e., that is not inherited from the class above it) is defined in the class itself For example, the subclass Sedan adds properties that distinguish sedans from convertibles and wagons

The superclass "Car" defines certain properties that all cars share In this diagram, the Sedan subclass, the Convertible subclass, and the Wagon subclass all belong to the Car superclass The three subclasses inherit properties that define them as cars, but each has added properties that distinguish them from the other subclasses.

In ArcView, a view is one type of document that you work with in a project A view inherits

properties from the Document class (e.g., a view is contained in a window, has a graphical user interface), but also defines its own properties (e.g., a view has themes and a table of contents)

The View class and the Table class are subclasses of the Document class They inherit properties from a document, but also define their own properties For instance, a view is contained in a window and has a GUI, just like all documents, but it also has a Table of Contents, which no other type of document has

[Click to enlarge]

Aggregation and Association

Aggregation indicates an "is composed of" relationship; for example, a car is composed of an engine, four tires, a radio, and seats Of course, a car is composed of much more, but a diagram showing all possible relationships would be unreadable The diagrams of ArcView's object model will show only the most important relationships between classes The symbol for aggregation is a diamond

In this model, a car has a radio and a radio has a tuner Note that the aggregation only works in one direction A radio is part of a car, but a car is not part of a radio.

Association describes the physical or conceptual connection between classes A diagram depicting an association will often include the verb describing the relationship

This diagram depicts the relationship between a car and gasoline and between a car and a person A car runs on gasoline; a car is driven by

a person.

Multiplicity

Other symbols show how many instances of a given class may relate to a single instance of another class A single line indicates one related object, a filled circle indicates many (zero or more), and an open circle indicates optional (zero or one) To be entirely accurate, the diagram above would look like this:

A car contains exactly one engine, four tires, two or more seats, and optionally,

a radio that may or may not have a cassette player.

Relationships with multiplicity of zero or more are often supported through collections such as lists or dictionaries For example, a project contains zero or more documents

Object model diagrams show relationships between classes Once you understand these

relationships, you can begin to control the objects that belong to a particular class For example, ifyou wanted to turn up the volume of the radio in your car, you'd first have to get the object that is your car, and then get its radio Similarly, if you want to control a theme in a view, you first have toget the view that contains the theme

As you can see, to program with Avenue you need to identify which class an object belongs to and then send that object a request to do some action—like turn up the volume of the radio The key, of course, is to identify the right object and ask it to do something that it knows how to do You couldn't ask a car seat to increase its volume, but you could ask it to recline—as long as it can recline (or as long as the class has a request to carry out that action)

Concept

Putting objects to work: Using requests

Requests make things happen in ArcView When you click a button or select a menu option, ArcView sends requests to objects A request may create a new object, such as a new theme when you add a theme to a view; it may retrieve information about an object, like the name of the current view; or it may change a property of an object, such as changing the name of a theme or making it active

Most Avenue requests retrieve or modify existing objects These requests are called instance requests because you send them to an instance of a class For example, you'd send the

appropriate instance request to a theme object to show or hide its legend

Other requests, called class requests, are sent directly to a class Class requests generally createnew objects of the target class or return information about things that affect the class For

example, you could send the appropriate class request to the Theme class to create a new themeobject, which you would then add to a view

A class is like a factory that builds cars You send the factory a request to build

the car (class request) but once built, you drive the car (send it instance

requests).

Different classes support different requests For example, you can send a request to a view to zoom, but a table would not understand the request Sometimes you'll find that different classes have requests with the same name These requests will likely produce similar results This is known as polymorphism

For example, the request to create a new view object is called Make; you also use the Make request to create a new table object Both Make requests generate a new instance of the target class; however, the resulting object (a new view or a new table) depends on which class you sendthe request to

Avenue request names generally begin with a verb that indicates the action it performs; for example, GetProject, FindScript, AddDoc, and SetValue where Get, Find, Add, and Set are actions and Project, Script, Doc, and Value are objects that receive that action You can

understand the function and general behavior of an Avenue request by recognizing the action keyword inherent in its name The table below shows some keywords and what they do

Some of the keywords used in Avenue requests Each keyword tells the object to carry out a certain action

[Click to enlarge]

To send an object a request to perform an action, you embed the object and request in an Avenuestatement

Concept

Using statements to control requests

Avenue statements organize how and when Avenue executes requests To send an object a request, you form a statement with this syntax: Object.Request

theView.Print

Here a view object, represented by "theView" is sent the Print request This form is the most common way to specify an object request statement and is referred to as Postfix notation

because the request comes after the object

When you send requests to number objects, you form a statement with the syntax Object

Request Object:

101 + 662

This notation is called Infix notation

When you work with Boolean expressions (expressions that evaluate to true or false) you may place the request before the object using Prefix notation:

not someCondition

However, you may still use Postfix notation and form the expression as:

myNumber = 2 + 5

returns a number object that results from adding two number objects Avenue assigns that number object to the variable, myNumber, which is why these statements are called Assignment statements

Some requests require additional information, or arguments Arguments are enclosed in a set of parentheses that follow the request

theView = theProject.FindDoc("City of Crestline")

In the above line of code, a string object, representing the name of the view, is the argument to the FindDoc request When a request requires more than one argument, you separate the arguments with commas

The online help for each request indicates whether it requires any arguments and if it returns another object To get help for a particular class or request, search for it in the online help index

You can expand the basic Object.Request syntax to include many requests (i.e.,

Object.Request.Request.Request, etc.) So instead of writing code like this:

ArcView processes each Object.Request pair one at a time from left to right The returned object

is then sent the next request in the chain

Concept

Assigning variables

Requests you send to an object will either return another object or they won't Requests that don'treturn an object simply execute the action of the request The statement below makes a theme visible just as checking its box in the view's Table of Contents would:

theTheme.SetVisible(true)

If a request returns an object, you can use a variable to reference it so you don't have to send therequest each time you want to manipulate the object You might use a variable to reference the current project, a view, a theme, or a number that indicates how many themes are in a view To create a variable, specify its name to the left of the assignment operator (the equals sign) in an assignment statement

In the assignment statement below, the GetProject request is sent to the application object, av The returned object (the project) is captured in the variable called "theProject." Any requests that need to be sent to the project can now be used with "theProject," rather than using the GetProjectrequest on the application object every time you need to reference the project object

theProject = av.GetProject

Once you create a variable, use it as you would the object itself in other parts of the script If, however, you need to refer to the object only once in a script, you might forego creating a variableand just use the object directly, as in this chained request that sends the FindDoc request to the project object returned from av.GetProject:

theView = av.GetProject.FindDoc("City of San Francisco")

When you create a variable, you define it as either a local or global variable The difference between local and global variables is in the scope, or range, of the variable The object

referenced by a local variable can be accessed only by the script it's set in, so use local variables

to reference objects that don't need to be accessed outside the current script The scope of a global variable extends beyond the current script Once assigned, global variables are available

to all scripts in any project To create a global variable, you prefix the name with an underscore (_):

_theProject = av.GetProject

In general, variable names should be long enough to indicate the purpose or contents of the variable Using the object type as part of the variable name (theView, aNumber, theActiveTheme) and using both upper- and lowercase letters for clarity (variables are not case-sensitive) is a common practice Variable names must be unique; more than one variable cannot have the samename

A common mistake is to give a variable the same name as an ArcView class "View" and "theme" would not be acceptable variable names because they're class names A simple way to resolve the conflict is to change the name to "aView," "myView," or "theView," or something else

appropriate

Example

Objects and classes in the real world

Can you think of an example of an object and a class from the real world? Take a moment and think about coins

Some of the properties that all U.S coins have are:

U.S coins all share these properties Can you think of any others?

Objects have properties

Although all U.S coins have these properties, the values of these properties may vary per coin For example, a nickel has a different metal property than a penny

An instance of a coin.

The coin object in your hand represents an instance of a coin and belongs to the coin class It hasproperties that all coins have This is what makes it a part of the class "money."

Three examples of coin "objects." All three have properties that define them as money, but each also has properties that distinguish it from the others A U.S penny is different from a Canadian penny and from a U.S quarter.

Superclasses and subclasses

You can think of money as a superclass for the coin class Money would have other subclasses besides coins For example, paper money, checks, and credit cards could all be subclasses of Money Each subclass inherits the properties of the Money superclass If you wanted to make a check object, you'd have to get a money object and use it to make a check object

Examples of objects exist all around us When you use Avenue, you can create objects any time you need to The objects will be created following the rules for the class that the object belongs

to, and the object will have properties that you can modify to suit your task

TOPIC2: Using Avenue

As you start writing your first Avenue scripts, there are a few pointers that will make your

programming life easier First, always look at existing sample scripts and system scripts for Avenue programming examples Use discussion lists like ArcView-L to ask for examples You canask for help and advice in a lot of places, but eventually you need to become self-sufficient and develop your own skills to write original scripts

The object model diagrams are the gem of the online help system These diagrams show

relationships between objects and help you figure out which requests to use Once you learn how

to interpret the symbols used on the diagrams and the request keywords, you're on your way to becoming a successful Avenue programer

ArcView Application object model diagram

Concept

What's the first line in an Avenue script?

Because projects contain all of your documents, about 80% of the time, the first line of code in a script will get the current project The next line will most likely get a document from that project theProject = av.GetProject

After creating a variable to reference the project (theProject) it can be used later in the script For example, you might change the name of the project:

theProject.SetName("streets.apr")

While the theProject variable is available, next you will likely get a document from that project

myView = theProject.FindDoc("City Streets View")

The GetProject request is used with av, a special variable that references the ArcView application window The application window (av) contains one project document at a time The application and project have a one-to-one relationship There is never more than one project and you can't drag projects out of the application window

Look at the ArcView object model diagrams in the online help for an explanation about one-to-onerelationships and look at the Request Keywords to get an understanding of why the Get request

is used to get the project

Concept

Understanding the object model diagrams

Object model diagrams use graphic symbols (lines, dots, triangles, and diamonds) to show how objects are related to each other To an Avenue programmer, the object model diagrams are like road maps Object relationships are displayed with connector lines and symbols Each connector line between two objects requires you to write an Avenue request to go from one object to the next The symbol in the relationship helps you figure out which request keyword to use

The Application Framework is the main object model diagram The Application object (also known

as the ArcView window and av to programmers) is your starting point to other ArcView objects

The ArcView Application Framework object model diagram [Click to enlarge]

The Application Framework is actually only a minor part of the full ArcView object model diagram, shown below The Application object is still the entry point that leads you to most of the other ArcView objects