Skip to content

Commit

Permalink
Fixed spelling, grammar
Browse files Browse the repository at this point in the history
  • Loading branch information
adcox committed Jul 6, 2016
1 parent 9d60360 commit 40094cf
Showing 1 changed file with 10 additions and 13 deletions.
23 changes: 10 additions & 13 deletions documentation/events/introduction.markdown
@@ -1,8 +1,8 @@
## Application and custom events using the observer pattern.

The events module in openFrameworks has some classes and functions that allow to work with events. Events allow to receive a notification whenever something happens in another part of the code or in the hardware.
The events module in openFrameworks has some classes and functions that allow the user to work with events. Events allow a listener to receive a notification whenever something happens in another part of the code or in the hardware.

For example when the mouse is moved you can use the mouseMoved function in your ofApp to do something. If you want to know when the mouse is moved in any other object in your code you can simply call from your ofApp to your object or you can register a method of that object as a listener to the mouseMoved event.
For example when the mouse is moved you can use the mouseMoved function in your ofApp to respond. If you want to know when the mouse is moved in any other object in your code you can simply call from your ofApp to your object or you can register a method of that object as a listener to the mouseMoved event.

```cpp
class SomeClass{
Expand All @@ -21,23 +21,20 @@ public:
}
```
The syntax is kind of strange, mostly the ofAddListener and ofRemoveListener calls, lets see what it means:
The syntax is kind of strange, mostly the ofAddListener and ofRemoveListener calls, let's see what it means:
[ofAddListener](ofEventUtils.html#ofAddListener), allows to register a method of an object or a function as a listener to an event, that way whenever that event is notified the method or function will be called.
[ofAddListener](ofEventUtils.html#ofAddListener) registers a method of an object or a function as a listener to an event such that the method or function will be called whenever that event occurs.
The first parameter to ofAddListener is the event to which we want to add a listener, in this case `ofEvents().mouseMoved`
The second parameter, this, means that we want the notifications to be sent, the method which will be called, to happen in this object. We could have set it to another object but using `this` is a pretty common pattern.
The second parameter, `this`, indicates that the listening method or function exists in this object; the event can also be sent to another object, but using `this` is a common pattern.
The third parameter, `&SomeClass::mouseMoved` is the method mouseMoved in the class SomeClass and we use an `&` because we are passing a pointer to that function.
The third parameter, `&SomeClass::mouseMoved` is the method `mouseMoved` in the class `SomeClass`. The `&` operator is used to pass a pointer to that function.
Another thing that is important is to remove the listener at least before the class is completely destroyed, that's why in the destructor of our class we use [ofRemoveListener](ofEventUtils.html#ofRemoveListener) which has the same syntax as [ofAddListener](ofEventUtils.html#ofAddListener) to remove the method as a listener to the mouseMoved event. Otherwise OF could try to call our object after it's been destroyed and the application would crash.
Another important aspect of event handling is to remove the listener before the object is destroyed. In this example, we place a call to [ofRemoveListener](ofEventUtils.html#ofRemoveListener) in the destructor to ensure that happens. The syntax is identical to the [ofAddListener](ofEventUtils.html#ofAddListener) function.
The last thing to notice is the signature, the syntax, of the event or function that will receive the event. By now that method has to receive 1 parameter which is a reference to the type of the event, that's why we use `&`
The last thing to notice is the signature (i.e., the syntax) of the event or function that will receive the event. In this case, the event expects to be passed to a method that recieves one parameter: a reference to the event type. The `&` operator is used to specify that the event type object is passed by reference.
You can also create your own events using the [ofEvent](ofEvent.html) class. And in case you don't need a thread safe event, if you are going to work from only one thread, you can also use [ofFastEvent](ofFastEvent) which has the same syntax but is much faster than the normal [ofEvent](ofEvent.html)
Events in OF are an implementation of the [Observer](https://en.wikipedia.org/wiki/Observer_pattern) pattern which has it's pros and cons, use it with care but try not to use it unless really needed. The main usage for an event instead of a direct call from one object to another is to provide independence from the caller to the callee so if you don't really need that or plan to need it in the future you can probably use a direct call beter.
One of the biggest problems of events are that you need to take care of unregistering every listener before it's destroyed, also if you copy an object and it was registered to an event the copy won't be, so you'll need to implement the copy constructor which is better to avoid since it's more error prone than letting the default copy constructor copy the whole object.
You can also create your own events using the [ofEvent](ofEvent.html) class. If thread saftey is not important for your application, you can also use [ofFastEvent](ofFastEvent), which has the same syntax but is much faster than the normal [ofEvent](ofEvent.html)
Events in OF are an implementation of the [Observer](https://en.wikipedia.org/wiki/Observer_pattern) pattern. Use it with care and try to avoid using it unless required. The main usage for an event (rather than a direct call from one object to another) is to provide independence from the caller to the callee. Note that custom events must also be "unregistered" before an objects are destroyed, and that registration is not transfered or duplicated if a registered object is copied. However, transferall of the registration may be accomplished by implementing your own copy constructor.

0 comments on commit 40094cf

Please sign in to comment.