# Module events

Author: | Alex Mitchell

This module implements an event system that is not dependant on external graphical toolkits. It was originally called `NimEE` because it was inspired by Python's PyEE module. There are two ways you can use events: one is a python-inspired way; the other is more of a C-style way.

    var ee = initEventEmitter()
    var genericargs: TEventArgs
    proc handleevent(e: TEventArgs) =
        echo("Handled!")

    # Python way
    ee.on("EventName", handleevent)
    ee.emit("EventName", genericargs)

    # C/Java way
    # Declare a type
    type
        TSomeObject = object of TObject
            SomeEvent: TEventHandler
    var myobj: TSomeObject
    myobj.SomeEvent = initEventHandler("SomeEvent")
    myobj.SomeEvent.addHandler(handleevent)
    ee.emit(myobj.SomeEvent, genericargs)

# Types

    TEventArgs = object of TObject

  Base object for event arguments that are passed to callback functions.

    TEventHandler = tuple[name: string,
                          handlers: seq[proc (e: TEventArgs) {.closure.}]]

  An eventhandler for an event.

    TEventEmitter = object  {.pure, final.}
      s: seq[TEventHandler]

  An object that fires events and holds event handlers for an object.

    EInvalidEvent = object of EInvalidValue

# Procs

    proc initEventHandler(name: string): TEventHandler {.raises: [], tags: [].}

  Initializes an EventHandler with the specified name and returns it.

    proc addHandler(handler: var TEventHandler;
                    func: proc (e: TEventArgs) {.closure.}) {.raises: [E_Base],
        tags: [TEffect].}

  Adds the callback to the specified event handler.

    proc removeHandler(handler: var TEventHandler;
                       func: proc (e: TEventArgs) {.closure.}) {.raises: [E_Base],
        tags: [TEffect].}

  Removes the callback from the specified event handler.

    proc containsHandler(handler: var TEventHandler;
                         func: proc (e: TEventArgs) {.closure.}): bool {.
        raises: [E_Base], tags: [TEffect].}

  Checks if a callback is registered to this event handler.

    proc clearHandlers(handler: var TEventHandler) {.raises: [], tags: [].}

  Clears all of the callbacks from the event handler.

    proc on(emitter: var TEventEmitter; event: string;
            func: proc (e: TEventArgs) {.closure.}) {.raises: [E_Base],
        tags: [TEffect].}

  Assigns a event handler with the specified callback. If the event doesn't exist, it will be created.

    proc emit(emitter: var TEventEmitter; eventhandler: var TEventHandler;
              args: TEventArgs) {.raises: [E_Base], tags: [TEffect].}

  Fires an event handler with specified event arguments.

    proc emit(emitter: var TEventEmitter; event: string; args: TEventArgs) {.
        raises: [E_Base, EInvalidEvent], tags: [TEffect].}

  Fires an event handler with specified event arguments.

    proc initEventEmitter(): TEventEmitter {.raises: [], tags: [].}

  Creates and returns a new EventEmitter.

Generated: 2013-05-21 09:55:21 UTC