Threading model, GUI
This section provides more details about accessing the Carmenta Engine MapControl and implementing event handlers safely.
Interacting with the MapControl
The MapControl class is a GUI control and has thread affinity with with the main thread of the application, also called the GUI thread. Thread affinity with a thread means that state is associated with the thread and the object can only be accessed correctly from that particular thread. This is a common situation with GUI control libraries regardless of API and platform.
Another set of classes in Carmenta Engine that are closely with the MapControl are all tools, predefined as well as application provided implementations, and they should also only be accessed from the GUI thread.
Events and event handlers
An area that is related to working with the MapControl and other GUI controls are events and event handlers. Events that are fired by Carmenta Engine cannot, unless specified otherwise by the documentation (in the Remarks section of the documentation for the event), be relied upon to by fired on a specific thread. This means that an event handler that updates an application's GUI, a very common situation, might need to marshal the operation to the GUI thread.
For example, many applications provide a list control or tree control that displays the layers in a map and whether they are enabled or not.
 |
If the application enables or disables layers through code, as opposed to doing it through the GUI, it might make sense to hook the Layer.EnabledChanged event to ensure that the layer control always displays the correct state of a layer. However, the Layer.EnabledChanged event can be fired on any thread due to the fact that the Layer.Enabled property is thread safe (and so can be modified from any thread without first acquiring the configuration lock). The application must therefore marshal the operation to the GUI thread to update the layer control safely.
How you marshal calls to the GUI thread is API and platform specific. Here follows a couple of examples:
In a native Windows application you typically marshal calls by posting an application specific message to the application window.
A Windows Forms application can make use of the Control.InvokeRequired property to determine whether marshaling is required and the Control.Invoke method to perform the marshaling.
A WPF application use an instance of the System.Windows.Threading.Dispatcher class to marshal calls to specific threads. An instance associated with the GUI thread can be accessed through the MapControl.Dispatcher property.