What is Broadcasting?
The broadcasting APIs provide a protocol whereby objects can sign up to be notified of events they are interested in. Here is how it works.
The system is designed so that the handler that triggers an event does not need to know which objects are interested in being notified of the event. Likewise, objects that are interested in being notified of an event do not need to know which object triggered the event. This approach decouples the broadcaster from the listener.
Interested Parties Register to be Notified When an Event Occurs
Using the Broadcasting APIs you register a handler that will be called whenever a specific event occurs. For example, a card with a UI element that changes when a particular preference is set would be interested in being notified when the preference value changes. The card could register to receive those messages using glxapp_listenForBroadcast:
on preOpenCard put glxapp_getProp("preference broadcaster") into theBroadcasterObject glxapp_listenForBroadcast theBroadcasterObject, "check spelling while typing", the long id of me, "SyncSpellCheckWhileTyping" end preOpenCard
The preceding code registers to be notified whenever the check spelling while typing preference is set using glxapp_setPref. Broadcasting preference changes is built into the framework and you register to be notified using the object returned by glxapp_getProp("preference broadcaster") call. Whenever you call glxapp_setPref with the check spelling while typing property, the SyncSpellCheckWhileTyping handler will be called in the card.
You can also trigger custom events. The following code registers to be notified whenever an "article" is updated in the application. When an article is updated the ArticlePropertyUpdated message will be sent to the card.
on preOpenCard glxapp_listenForBroadcast "global", "article", the long id of me, "ArticlePropertyUpdated" end preOpenCard
In the preceding code the word "global" was used rather than an actual object like the "preference broadcaster" object. This keyword provides an easy means of triggering general event notifications and registering to be notified of these events.
A Handler Triggers an Event Which Sends Out Notifications
In order for registered objects to be notified of an event, another handler must broadcast the event. As was mentioned above, an event notification is set whenever a preference is changed with glxapp_setPref. If an object has registered to be notified when a preference changes then registered callback handler will be sent to the object.
For general events, a handler can send notifications of an event occurring by calling glxapp_broadcast:
on UpdateArticleTitle ... # Fill in an array of properties detailing the event that occurred. put the uArticleId of me into thePkgA["ids"] put "title" into thePkgA["property"] put theNewTitle into thePkgA["value"] put the long id of me into thePkgA["source"] glxapp_broadcast "global", "article", thePkgA end UpdateArticleTitle
Broadcasting an event is pretty straightforward. First you create an array that describes the event that occurred. In the preceding code an article had the "title" property changed.
The event is then triggered with the glxapp_broadcast command. Any objects that registered for the "global" "article" event using glxapp_listenForBroadcast will then be notified. Note that the UpdateArticleTitle command that triggers the event has no knowledge of which objects are interested in the event. Its only job is trigger the event.