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

An introduction to Avenue Table of Contents Lesson goals Topic: Getting to know Avenue Concepts Working with Avenue Understanding objects Understanding how classes organize objects 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 is customized 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 do with 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 between classes. 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, if you 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 to get 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 create new 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 theme object, 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 send the 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 Avenue statement 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: someCondition.not When you send a request to an object, the request may result in the return of another object. In some cases, these objects contain information about other objects, as in this example: theName = theView.GetName Here a view object (represented as "theView") is sent the "GetName" request, which returns the name of the view. The view name is subsequently stored in the variable, theName. Likewise, the expression: 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: theProject = av.GetProject theView = theProject.FindDoc("City of Crestline") theTheme = theView.FindTheme("Streets") you could chain the requests together and do this: theTheme = av.GetProject.FindDoc("City of Crestline").FindTheme("Streets") 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't return 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 the request 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 GetProject request 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 variable and 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 same name. 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 [...]... 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 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- one relationships 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... 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 has properties that all coins have This is what makes it a part of the class "money." Instantiating an object When you instantiate an object, you create a new object, or instance, from a class Unfortunately, the government has laws that forbid you from instantiating... may relate to a single instance of another class How many objects of a given class may relate to the class they inherit from How many instances of a given class may relate to a single instance of the same class None of the above 8 To send an Avenue request to an object, the statement is formed with this syntax: Request.Object True False 9 Which of the following is true about an object? It's something... window that can be opened with the Open request Later, Jodi will assign the OpenTable script to a button and add more code to analyze records in the Table's associated VTab object Summary In this lesson, you've learned some of the basics of Avenue programming While this was only a brief introduction to Avenue, you've learned some of the important concepts to help you use the Map Calculator For more... 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... you to add, order, retrieve, and remove list elements Use lists whenever you need efficient sequential access to an unbounded number of objects, or when you need efficient random access based upon the list index number It is important to understand the concept of lists because some ArcView Spatial Analyst requests use lists as parameters Example Opening a table In this example project, Jodi wants to. .. 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. .. trying to find In the example, FindDoc is used because a project can contain a list of many documents FindDoc has a parameter where you can enter the name of the document that you are searching for Set Once you have an object, use Set requests to change that object's properties Make Whenever you need to create or instantiate a new object, use the Make request As Whenever you need to convert an object... the keywords and symbols used in the object model diagrams, you can write Avenue code by looking at the diagram relationships and deciding on a request Request keywords: • • • • • • • • Get Find Set Make Return Add As Has, Is, Can When programming with Avenue, it's useful to look at the object model diagrams because, for each connector line in the diagram, you will have to use a request to get the next . 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. 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. online help for an explanation about one -to- one relationships and look at the Request Keywords to get an understanding of why the Get request is used to get the project. Concept Understanding the