Objects, Events, Properties and Methods
LotusScript is an event-driven programming environment similar to Microsoft's Visual Basic. Event-driven programs are based on the concept that objects have associated events, methods, and properties. In this Chapter we will examine what objects, events, and properties are and how they are used to create robust applications.
It is important to understand that event-driven programming is actuated usually, though not always, through actions taken by a user. As a developer, you might write code behind the Click event of a button, which could display a message on the screen in what is called a "message box". The code to display the message box does not execute until the button is clicked. Thus, the action of clicking the button causes the code behind the click event to execute. If the button is not clicked, the code is not executed. This is what is meant by event-driven programming.
Although the events that drive the code are often user initiated, that is not always the case. Code can be written that is does not rely on the execution of an event. This method will be discussed in a later chapter. For now, thinking in terms of event-driven code will be just fine.
Objects
Objects are the heart of event-driven programming. For our purposes here, an object is any structure that is available for customization or manipulation by LotusScript. The main objects available for scripting in Notes are forms, fields, buttons, hotspots, actions, OLE controls, and Lotus Components. Each object has its own events and properties, which can be programmed through LotusScript to meet the needs of your application.
Events
Each object has events associated with it. These events are sometimes the same as the events that other objects have, sometimes events are exclusive to a particular object. For instance, a button is an object. Since a user can click a button, "Click" is an event associated with the button. A Form is another type of object. However, a form does not have a Click event. On the other hand, both a button and a form have the event "Initialize", because both objects can be initialized when a document is created or opened. As you can imagine, it can take a little time to know which events are associated with which objects. Most of the events that are associated with an Object are obvious, such as "Click" for a button. You will be learning which events are available naturally as you learn LotusScript. The table below lists some objects and their associated events:
Object
|
Events
|
Form
|
QueryOpen, PostOpen, Querymodechange, Postmodechange, Postrecalc, Querysave, Queryclose, Initialize, Terminate
|
Button
|
Click, Objectexecute, Initialize, Terminate
|
Field
|
Entering, Initialize, Terminate
|
Each object has events that are for use in LotusScript, and others that are exclusively for the Notes formula language. If you were trying to write code for the Default Value event of a field object, you would not be able to write script code; you would only be able to use the Notes formula language. As you switch between events in the Development pane, you will notice the Formula and Script radio buttons becoming available or unavailable depending on the event selected.
Events allow you to control when code will be executed. Do you need to lookup some values automatically when a document is created or opened? Write code for the Form Initialize event. Do you want to have code execute when a hotspot is clicked? Write code for the Hotspot Click event. Do you want to compute certain values when a document is closed? Write code for the Form Terminate event. Do you want a field to ask the user a question each time the cursor is moved into the field? Code the field Entering event.
The script below displays the message "Hello World!" in a messagebox:
Sub Click(Source As Button)
Messagebox("Hello World!")
End Sub
Messagebox("Hello World!")
End Sub
The first line of the script defines the event that must be triggered for the messagebox to appear. A Sub is a kind of mini program that is usually run by an event such as a click event, as in this case. Hence, the first line contains Sub Click. The end of a sub is defined by the End Sub line. Everything in between is executed when the click event is initiated (Event calls the sub). The first and last lines were automatically generated by Notes when you chose the Click event for the button in the Design pane. You will find that Notes always generates similar lines of code whenever you choose to script an event.
Properties
Properties are also associated with objects. Properties allow you to manipulate the attributes of an object. As an example, we will look at the properties associated with a document. Some document properties are:
1. Authors -- the names of users who have saved the document
2. Created -- the date and time the document was created
3. IsSigned -- a boolean value that is true if the document was signed
4. NoteID -- the Note ID of the document
Each of these properties can be accessed via script to allow you to determine their value. Most (but not all) of the properties will allow you to write new values to them.
In this document we have discussed what objects, events, and properties are. We have not discussed how to use them syntactically, because for now, it is only important that you understand the principles of each. As we learn more about LotusScript, we will learn more about these subjects.
Methods
Methods, like properties, are associated with objects. A property has to do with what an object is, while a method has to do with what an object does. For instance, a NotesDatabase object has a property called Title, which might contain the value: LotusScript Technology Learning Center, and a method called Compact, which compacts the database. Methods usually return a value, some require arguments, and are always separated from the object name by a period:
nsize = db.Compact
nsize is the difference in size of the database after it has been compacted
db represents the LotusScript Technology Learning Center database
Compact is a method that causes a database to be compacted
