From EventGhost
Jump to: navigation, search

The event is the cornerstone of EventGhost, as its name implies. Events are generated when something "interesting" happens on your computer, to which you might want to react.

Viewing Events

The left pane of EventGhost is a log of the events it observes, along with the macros it executes and the actions it performs. In order to see all of the events that EventGhost can see, make sure that the checkbox at the bottom of the window, labelled "Log only assigned and activated events", is unchecked.

Built-In Events

EventGhost has built-in support for generating events for certain system-level activities. Here is a partial list:

Event Payload? Enduring? Description
Event.pngSystem.Idle N N Your computer is inactive (no keyboard/mouse activity) for 1 minute.
Event.pngSystem.UnIdle N N Your system has been idle, and then detects keyboard/mouse activity.
Event.pngSystem.DriveMounted.N N N A new disk drive has just been mounted as N:.
Event.pngSystem.DriveRemoved.N N N The disk drive called N: has been removed.
Event.pngSystem.DeviceAttached Y N A new USB device, such as a mouse, has been attached. The payload is a list holding a string with the device identifier of the new device.
Event.pngSystem.DeviceRemoved Y N A USB device has been removed. The payload is a list holding a string with the device identifier of the removed device.

See also the complete list of Built-In Events.

To generate events for other activities, you will need to install an appropriate plugin.

Acting on Events

You can make EventGhost take action for you when it sees an event of interest to you. Follow these simple steps:

  1. Create a macro in your configuration tree.
  2. Assign one or more actions to your new macro.
  3. Make sure that the checkbox at the bottom of the EventGhost window, labelled "Log only assigned and activated events", is unchecked.
  4. Generate the event of interest, so it appears in the log.
  5. Click on the event, and drag it into the macro you created.
  6. That's it!

Alternatively, you can click on your new macro, and then click the Event button (Event.png) on the toolbar, or click the Configuration menu and select "Add Event..." You will only be able to choose from a subset of system events, but you can edit it after you've added it to your macro (see below).

Disabling Events

You can right-click on an event in a macro, and select "Disable Item", to disable the event. That event will not trigger the macro while it is disabled.

You can enable and disable events using any of these actions: Action.pngDisable Item, Action.pngEnable Item, Action.pngEnable Item Exclusively. This can be useful for changing EventGhost's behaviour based on specific events; for example, disabling macros for events related to a device that has been disconnected.

Acting on Multiple Events

You can add multiple events to the same macro using the method given above. A macro with multiple events is triggered when any of its events fires.

Editing Events in Macros

If you want to change what event causes your macro to execute, simply double-click the event as it appears in your macro. You will be presented with a new dialog that allows you to edit the event name.

Acting on Classes of Events (Wildcards in Events)

Sometimes you want a macro to trigger when any of several events of the same type occur. For a simple example, imagine you wanted to play a short beep sound whenever any key is pressed on your keyboard. The Plugin.pngKeyboard plugin can generate unique events for each key pressed, but would be tiresome to manually add every keyboard event to your macro.

The solution is to use a wildcard in your event name. After you have added a single keyboard event (for example, Event.pngKeyboard.H) to your macro, double-click on it to edit it. Change it so it reads Event.pngKeyboard.* (that's an asterisk) and click OK. Now your macro will fire when any event starting with "Keyboard." is detected.

The "*" character in an event matches any number of characters in an event name. You can also use the "?" character to match exactly one character in an event name.

Running Multiple Macros from One Event

You can cause the same event to run any number of macros that you want. Simply add the event to each of your macros as described above. Or, you can right-click on the event in one macro, select Copy, and then right-click in another macro and select Paste.

When the same event triggers multiple macros, the macros are run one at a time. Macros higher in the tree are run before macros lower in the tree, and macros closer to the root of the tree are run before macros nested deeper in sub-folders.

Generating Events

You can cause a custom event to be generated by calling the Action.pngTrigger Event action.

Plugin authors can cause their plugin to generate events. This will be documented in a separate section of pages devoted to plugin authoring.

Accessing Events from Actions

Any action that is called as a result of an event can access the event object to learn more about the event. You access this object by referencing eg.event (from the the eg module) in the action.

If you are using the Action.pngPython Command or Action.pngPython Script actions, you can access the following properties directly. Other actions may support python variable expansion to access these properties (see that action's plugin documentation for details).

Property Description Example
eg.event.string The full event name, without payload. "System.Idle"
eg.event.prefix The first part of the event name, up to the first period. "System"
eg.event.suffix The remainder of the event name, after the first period. "Idle"
eg.event.payload The event payload; see below. None
eg.event.time The time at which the event was generated, as returned by the clock() function of Python’s timePython small.png module. 693.1674825
eg.event.isEnded A Boolean flag indicating whether the event is ended (see Enduring Event). True

Event Payloads

Some events carry additional information, besides their name. For example the Plugin.pngNetwork Event Receiver plugin returns also the IP of the client that generated the event. This is called the event's payload.

You can see the event's payload in the log, but when you drag the event into a macro, you will no longer see the payload. That is because your macro will be triggered any time it sees the event by name, regardless of the payload. If you wish to change what happens based on the payload, you will need to use a python expression to access the payload, as described above.

Prolonged Events aka Enduring Events

While some events are instantaneous, like Event.pngSystem.Idle, others can last over a period of time. For example, an event indicating the press of a button on a remote control can be considered active for as long as the button is held down. Such an event is known as an enduring event. For more information on these types of events, see Enduring Event.

See Also