How Actions and Listener Interfaces Work

When a widget receives a user event, it will likely want to perform some kind of action that changes its appearance or behavior. After the user event has been handled, the widget may want to inform other components of the application that it has performed some kind of action in response to the user's input. A widget generates an "action," which is effectively a message that wraps the pertinent information describing the widget's performed action. The widget then passes this message to all of its listeners.

If a component of an application desires to be notified of the various actions that widgets are performing, it must "listen" to them. In order to listen to a widget's actions, the component must implement the appropriate "listener." For instance, to get updates on a scrollbar's value, a component would implement the GmScalarListener interface. This interface includes the function changeOccurred. Whenever a scrollbar receives a user event from the mouse or keyboard that instructs it to scroll up or down, it will generate a GmScalarAction that encapsulates the new value of the scrollbar and the change from the old value. All of this information is wrapped by the action and passed to the changeOccurred function which is called by the scrollbar for all of its listeners.

After implementing the appropriate interface, a component can begin listening to a widget by calling the correct addListener. To listen to a scrollbar, that function would be addScalarListener. After this function is called and the listener passed as its only parameter, any action performed by the widget will be sent to the listener. If a component wishes to stop listening to the widget, it may call the appropriate removeListener function.

Once the action is received via the functions implemented for the appropriate interface, its data can be queried. All actions include the source of the action's ID so that the origin of the message can be determined. Other than this, each action includes the necessary data for its purpose, for instance, a GmSelectionAction includes a developer defined widget ID for the component that was selected in the selection action.

Communication between widgets and other application components is easily understood and implemented using actions and listeners. Actions and listeners are also very extendible, so that communication is extremely flexible and customizable.