SendEvent Statement

Language Items List

Definition:

Raises the named event on the object specified or on the current object if none is specified. The current object is defined as the object defining the method from which that SendEvent is called.

Syntax:

SendEvent [<EventObject>.]<EventName>[(<args>)]

Details:

Use SendEvent to generate events, such as Click, on objects. There is no restriction as to the type of object on which an event can be defined. Some commonly used events for graphical objects are: Click, Change, LostFocus, and so on. Non-graphical objects such as a Timer can also have events like TimeOut defined on them.

The <EventName> must have been previously declared as an event on the object. It can be declared by either predefining it or by using the Event syntax from the Method Editor. If the event is defined to take arguments then the arguments must be provided or an Argument Mismatch Exception will occur. The handler for the event is looked for and called in the usual way:

1. Try to find <EventName> on the object specified as <EventObject>, execute if found.

2. Try to find <EventObject>_<EventName> on the Container/Host of <EventObject>, execute if found. (EventObject in this case, would be the name given to the object when it was embedded in a container such as Button1).

   ---

Note: It is possible for one, both, or neither of the handlers to be called. That is the advantage of using Events; if there are no handlers, the event is essentially ignored. Whereas, using a method to try and invoke a member that doesn't exist, would cause a NotFound exception.

Take care when defining handlers so that if two ways of handling the event are found, they do not perform conflicting operations.

For example, if a user defined a "Mailbox" object, a "MessageReceived" event could also be defined. If a MailBox object is embedded in a Form, this event would allow the Form to detect when messages come in. The Form can detect when messages come in by having a handler like this:

Form1: Sub MailBox1_MessageReceived()
' Do new mail processing
End Sub

Notice how this is similar to the usual way "Click" is handled for a Button:

Form1: Sub Button1_Click()
End Sub

Both Button1 and MailBox1 are "embedded" in Form1. Any events that occur on them can be picked up on the Container (Form1) by prefixing the event name with the name of the object (the field name that it is called when referred to as Form1.<obj>). The event would be generated by using the SendEvent statement as in:

MailBox: Sub Timer1_Timeout()
If mail_is_ready Then SendEvent MessageReceived()
End Sub

Because of where the Timer1_Timeout Sub is defined, the SendEvent statement generates a "MessageReceived" event on the MailBox object. This event can be picked up in two ways (just like a Click event on a Button):

MailBox: Sub MessageReceived()
End Sub

Form1: Sub MailBox1_MessageReceived()
End Sub

Example:

Form1: Sub Button1_Click()
SendEvent ButtonClicked(Button1)
End Sub

Form1: Sub ButtonClicked(btn As Button)
End Sub

Since the SendEvent is called for a method defined on a Form, the event must be declared on that Form:

Form1: Event ButtonClicked(btn As Button)

Notice how the event declaration looks alot like the Sub declaration that handles it.