## C.47. `$world->hook`

Abstract

$world->hook function: connects a HOOK

`void $world->hook(` | `event` ,
| `action` ,
| [`attributes`] `)`;

`void $world->hook(` | `event` ,
| `number` ,
| [`action`] ,
| [`attributes`] `)`;

A hook is an action that is connected to an event, such as connecting to the World or the window receiving focus. This function allow you to define a hook for a given event, that will execute `action`, or to edit the hook identifyed by `number`.

Here are the events currently supported:

- `OnConnect`: This hook is execued when a connection to the world is made, after the auto-logon has taken place (if applicable).

- `OnDisconnect`: This hook is executed when you are disconnected from a World, after the connection has been closed.

- `OnReceivedText`: Executed when text is received from the world.

- `OnSentCommand`: Executed after a command is sent to the world. The command is available for the hook in the `$hookdata` variable, and can be inspectd in Perl scripts.

- `OnGetFocus`: Executed when the KildClient window receives the focus.

- `OnLoseFocus`: Executed when the KildClient window loses the focus.

- `OnCloseConnected`: Executed when the world is forcedly closed. This can happen using the World → Close menu, the `$world->close()` function, or by quitting the program with the world connected. You can put in this hook, for example "`quit`" to always exit the MUD nicely, even if you close the world by mistake.

`atributes` is a reference to a hash defining attributes for the hook. Generally the call works like this:

    $world->hook("event", "action", { attribute1 => value1,
                                      attribute2 => value2, ... })

Possible attributes:

- `action`: The action to be executed.

- `enabled`: If value evaluates to true, the hook is enabled. If it evaluates to false, the hook is disbled and is not executed.

- `name`: Assigns a name to the hook, so that it can be referenced by name.