Previous  Up  Next

Module Bogue.Mailbox

module Mailbox: sig .. end

Sending arbitrary messages to widgets

Working with messages can go a long way simplifying an intricate GUI.

Technically, Mailboxes are build upon Bogues's connections, and can be seen as a (semantic) extension to the simple Update mechanism. Mailboxes can be useful

  1. for letting two widgets talk together in suitations where they are far away from each other in the code (distinct scopes), making the use of standard connections difficult.
  2. for avoiding recursivity issues: widgets can "send orders" at places in the code where the way to achieve theses orders are not even defined yet.
  3. more generally, for rethinking all or part of your UI logic to delegate decision making to a few "decision centers" (the mail handlers).

WARNING: new API, not stabilized yet.

Dependency graph
type 'a mbx 
val create : ?owner:Widget.t -> unit -> 'a mbx

Create an empty mailbox which will receive messages of type 'a.

Specifying an owner widget is optional (and may disappear in future API); it could help structuring the code: we think of it as "the widget that handles the incoming mail".

Once a mailbox is created, anyone can send messages to it using Mailbox.send. However the mail will be effectively handled only once Mailbox.activate is called.

val activate : ?sync:bool -> 'a mbx -> ('a -> unit) -> unit

activate mbx handler sets the owner widget ready to receive messages, and each received message will be handled by the handler function.

By default, "the mailman delivers at each frame": messages are handled one by one in the Sync queue, in the order of reception (FIFO). Setting sync=false will on the contrary execute the handler in a separate thread. (Only one thread per mailbox.)

Note that all messages are transfered to the handler as soon as the first delivery occurs, so in principle the handler is authorized itself to send new messages to its own mailbox. Of course if all messages trigger sending a new one, this will loop forever.

val send : 'a mbx -> 'a -> unit

send mbx msg sends the message msg to the mailbox mbx.

Recall that all messages sent to a given mailbox must be of the same type. It can be handy to use polymorphic variants like

send mbx (`Start_new_level 7)

Even if the mailbox is not activated, or disabled, messages can still be sent: they accumulate in the mailbox queue, and will all be handled once the mailbox is activated or re-enabled.

val enable : 'a mbx -> unit
val disable : 'a mbx -> unit
val clear : 'a mbx -> unit