diff options
author | Xavi Artigas <xavierartigas@yahoo.es> | 2018-08-31 02:45:35 -0700 |
---|---|---|
committer | apache <apache@e5-web1.enlightenment.org> | 2018-08-31 02:45:35 -0700 |
commit | 5d748959323041633e4448ea2949595eff951317 (patch) | |
tree | 8d7c80d421f511a67beb705029ac072df6295dbe | |
parent | Wiki page start.md changed with summary [] by Xavi Artigas (diff) | |
download | www-content-5d748959323041633e4448ea2949595eff951317.tar.gz |
Wiki page events.md changed with summary [created] by Xavi Artigas
-rw-r--r-- | pages/develop/guides/csharp/core/events.md.txt | 165 |
1 files changed, 165 insertions, 0 deletions
diff --git a/pages/develop/guides/csharp/core/events.md.txt b/pages/develop/guides/csharp/core/events.md.txt new file mode 100644 index 000000000..4efec3189 --- /dev/null +++ b/pages/develop/guides/csharp/core/events.md.txt @@ -0,0 +1,165 @@ +--- +~~Title: Events Programming Guide in C#~~ +~~NOCACHE~~ +--- + +# Events Programming Guide in C# # + +EFL is event-driven. This means that execution usually takes place within an internal EFL *Main Loop*. The application receives notifications through function callbacks. These can apply to virtually any event which occurs on a computer. + +Events play a central role in EFL. In this guide, you'll learn more about the required methods to handle them. + +You can also find usage examples in the [EFL examples repository](https://git.enlightenment.org/tools/examples.git/tree/). + +## Listening to Events from Objects ## + +All EFL objects can emit events. You can discover more about them in the **Events** section of their respective [API Reference documentation](/develop/api/) (only in C, C# *coming soon*). + +In C# you register a callback method to be called when an object emits a given event using the `+=` operator: + +```csharp +object.event += callback; +``` + +Substitute *object* for any EFL object and *event* for the identifier of the event (such as ``PollHighEvt`` or ``TickEvt``). Set *callback* to the method to be called when the event occurs. + +The method signature for the callback is: + +```csharp +void callback(object sender, EventArgs e); +``` + +*sender* is the object that emitted the event and *e* contains any additional information that the event sent, after casting it to the required type (for example, `efl.input.Interface.KeyDownEvt_Args` when connecting to the `efl.input.Interface.KeyDownEvt` event). + +> **NOTE:** +> The [API Reference documentation](/develop/api/) for each event tells you what type to cast *e* to (*Not available for C# yet*). +> See [EFL_EVENT_POINTER_DOWN](/develop/api/efl/input/interface/event/pointer_down) for example. + +To stop receiving notifications for a particular event, unregister the callback using the `-=` operator: + +```csharp +object.event -= callback; +``` + +Note that in order to unregister the callback you have to provide the callback method again. This is because you can register different callback methods to the same event. + +## Pausing and Resuming Event Notifications ## + +All event emissions from a given object can be paused (*frozen*) using `FreezeEvent()` and resumed with `ThawEvent()`: + +```csharp + object.FreezeEvent(); + object.ThawEvent(); +``` + +While an object is frozen only high-priority events (marked as *hot* in the documentation) will be emitted. Hot events cannot be stopped. + +Remember that ALL events emitting from a object are stopped if it's frozen, except for hot events. If you need to stop individual events you can unregister their callback temporarily and then re-register later. + +## Example ## + +Below is the `core_event.cs` example taken from [the examples repository](https://git.enlightenment.org/tools/examples.git/tree/reference/csharp/core/src/core_event.cs): + +```csharp +public class Example +{ + // Polling callback + private static void PollCb(object sender, EventArgs e) + { + Console.WriteLine(" Poll from {0}", ((efl.IObject)sender).GetName()); + } + + public static void Main() + { + // Initialize EFL and all UI components + efl.All.Init(); + + // Retrieve the application's main loop + var mainloop = efl.App.GetLoopMain(); + mainloop.SetName("Mainloop"); + + // This event gets triggered continuously + mainloop.PollHighEvt += PollCb; + + // This timer will control events fired by the main loop + new efl.Loop_Timer(mainloop, (efl.ILoop_Timer etimer) => { + etimer.SetName("Timer"); + // Trigger every 100ms + etimer.SetInterval(0.1); + // To count number of timer triggers + int tick_count = 0; + etimer.TickEvt += (object sender, EventArgs e) => { + string message = "Tick {0} from {1}: "; + // Depending on the number of timer ticks, it does a different thing + switch (tick_count) { + case 0: + message += "Freezing Mainloop events"; + mainloop.FreezeEvent(); + break; + case 1: + message += "Thawing Mainloop events"; + mainloop.ThawEvent(); + break; + default: + message += "Quitting"; + mainloop.Quit(new eina.Value(0)); + break; + } + Console.WriteLine(message, tick_count, ((efl.IObject)sender).GetName()); + tick_count++; + }; + }); + + Console.WriteLine("Waiting for Timer to call back..."); + + // Start the EFL main loop (and the experiment) + mainloop.Begin(); + + // Shutdown EFL + efl.All.Shutdown(); + + Console.WriteLine("Application is over"); + } +} +``` + +A handler is connected to the `PollHighEvt` event of the application's main loop, which triggers continuously, at an undefined frequency of several shots per second (See the Main Loop Programming Guide, *coming soon*). At every shot, a line is printed on the console. + +At the same time, a timer is instantiated, firing every 100ms, which does a different thing at every shot: + +* First it freezes (pauses) all main loop events (except hot ones). +* Then it thaws (resumes) all main loop events. +* Finally, it quits the application. + +When you run the application, it should produce something like this on the console: + +``` +Waiting for Timer to call back... + Poll from Mainloop + Poll from Mainloop + Poll from Mainloop + Poll from Mainloop + Poll from Mainloop + Poll from Mainloop +Tick 0 from Timer: Freezing Mainloop events +Tick 1 from Timer: Thawing Mainloop events + Poll from Mainloop + Poll from Mainloop + Poll from Mainloop + Poll from Mainloop + Poll from Mainloop + Poll from Mainloop +Tick 2 from Timer: Quitting +``` + +As you can see, the line `Poll from Mainloop` is printed continuously except in the period between Tick 0 and Tick 1 of the Timer, where main loop events are frozen. + +The exact amount of `Poll from Mainloop` messages you get depends on the frequency of the `PollHighEvt` event, which is chosen by EFL. The important thing is that there should be no such messages in between timer ticks 0 and 1, since main loop events are frozen, + +## Further Reading ## + +[`core_event.cs` example](https://git.enlightenment.org/tools/examples.git/tree/reference/csharp/core/src/core_event.cs) +: C# Source code for this example. + +[`Efl.Object` API Reference](https://www.enlightenment.org/develop/api/efl/object) +: Detailed documentation for the EFL object, which implements the events mechanism.
\ No newline at end of file |