summaryrefslogtreecommitdiff
path: root/pages
diff options
context:
space:
mode:
authorXavi Artigas <xavierartigas@yahoo.es>2018-08-31 02:45:35 -0700
committerapache <apache@e5-web1.enlightenment.org>2018-08-31 02:45:35 -0700
commit5d748959323041633e4448ea2949595eff951317 (patch)
tree8d7c80d421f511a67beb705029ac072df6295dbe /pages
parentdc5431d83e15214c56bf808e1725c6f49198a90c (diff)
Wiki page events.md changed with summary [created] by Xavi Artigas
Diffstat (limited to 'pages')
-rw-r--r--pages/develop/guides/csharp/core/events.md.txt165
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 @@
1---
2~~Title: Events Programming Guide in C#~~
3~~NOCACHE~~
4---
5
6# Events Programming Guide in C# #
7
8EFL 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.
9
10Events play a central role in EFL. In this guide, you'll learn more about the required methods to handle them.
11
12You can also find usage examples in the [EFL examples repository](https://git.enlightenment.org/tools/examples.git/tree/).
13
14## Listening to Events from Objects ##
15
16All 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*).
17
18In C# you register a callback method to be called when an object emits a given event using the `+=` operator:
19
20```csharp
21object.event += callback;
22```
23
24Substitute *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.
25
26The method signature for the callback is:
27
28```csharp
29void callback(object sender, EventArgs e);
30```
31
32*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).
33
34> **NOTE:**
35> The [API Reference documentation](/develop/api/) for each event tells you what type to cast *e* to (*Not available for C# yet*).
36> See [EFL_EVENT_POINTER_DOWN](/develop/api/efl/input/interface/event/pointer_down) for example.
37
38To stop receiving notifications for a particular event, unregister the callback using the `-=` operator:
39
40```csharp
41object.event -= callback;
42```
43
44Note 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.
45
46## Pausing and Resuming Event Notifications ##
47
48All event emissions from a given object can be paused (*frozen*) using `FreezeEvent()` and resumed with `ThawEvent()`:
49
50```csharp
51 object.FreezeEvent();
52 object.ThawEvent();
53```
54
55While an object is frozen only high-priority events (marked as *hot* in the documentation) will be emitted. Hot events cannot be stopped.
56
57Remember 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.
58
59## Example ##
60
61Below 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):
62
63```csharp
64public class Example
65{
66 // Polling callback
67 private static void PollCb(object sender, EventArgs e)
68 {
69 Console.WriteLine(" Poll from {0}", ((efl.IObject)sender).GetName());
70 }
71
72 public static void Main()
73 {
74 // Initialize EFL and all UI components
75 efl.All.Init();
76
77 // Retrieve the application's main loop
78 var mainloop = efl.App.GetLoopMain();
79 mainloop.SetName("Mainloop");
80
81 // This event gets triggered continuously
82 mainloop.PollHighEvt += PollCb;
83
84 // This timer will control events fired by the main loop
85 new efl.Loop_Timer(mainloop, (efl.ILoop_Timer etimer) => {
86 etimer.SetName("Timer");
87 // Trigger every 100ms
88 etimer.SetInterval(0.1);
89 // To count number of timer triggers
90 int tick_count = 0;
91 etimer.TickEvt += (object sender, EventArgs e) => {
92 string message = "Tick {0} from {1}: ";
93 // Depending on the number of timer ticks, it does a different thing
94 switch (tick_count) {
95 case 0:
96 message += "Freezing Mainloop events";
97 mainloop.FreezeEvent();
98 break;
99 case 1:
100 message += "Thawing Mainloop events";
101 mainloop.ThawEvent();
102 break;
103 default:
104 message += "Quitting";
105 mainloop.Quit(new eina.Value(0));
106 break;
107 }
108 Console.WriteLine(message, tick_count, ((efl.IObject)sender).GetName());
109 tick_count++;
110 };
111 });
112
113 Console.WriteLine("Waiting for Timer to call back...");
114
115 // Start the EFL main loop (and the experiment)
116 mainloop.Begin();
117
118 // Shutdown EFL
119 efl.All.Shutdown();
120
121 Console.WriteLine("Application is over");
122 }
123}
124```
125
126A 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.
127
128At the same time, a timer is instantiated, firing every 100ms, which does a different thing at every shot:
129
130* First it freezes (pauses) all main loop events (except hot ones).
131* Then it thaws (resumes) all main loop events.
132* Finally, it quits the application.
133
134When you run the application, it should produce something like this on the console:
135
136```
137Waiting for Timer to call back...
138 Poll from Mainloop
139 Poll from Mainloop
140 Poll from Mainloop
141 Poll from Mainloop
142 Poll from Mainloop
143 Poll from Mainloop
144Tick 0 from Timer: Freezing Mainloop events
145Tick 1 from Timer: Thawing Mainloop events
146 Poll from Mainloop
147 Poll from Mainloop
148 Poll from Mainloop
149 Poll from Mainloop
150 Poll from Mainloop
151 Poll from Mainloop
152Tick 2 from Timer: Quitting
153```
154
155As 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.
156
157The 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,
158
159## Further Reading ##
160
161[`core_event.cs` example](https://git.enlightenment.org/tools/examples.git/tree/reference/csharp/core/src/core_event.cs)
162: C# Source code for this example.
163
164[`Efl.Object` API Reference](https://www.enlightenment.org/develop/api/efl/object)
165: Detailed documentation for the EFL object, which implements the events mechanism. \ No newline at end of file