2
* @page ecore_examples Ecore Examples
4
* Here is a page with some Ecore examples explained:
6
* @li @ref ecore_time_functions_example_c
7
* @li @ref ecore_timer_example_c
8
* @li @ref ecore_idler_example_c
9
* @li @ref ecore_job_example_c
10
* @li @ref ecore_event_example_01_c
11
* @li @ref ecore_event_example_02_c
12
* @li @ref ecore_fd_handler_example_c
13
* @li @ref ecore_poller_example_c
14
* @li @ref ecore_con_lookup_example_c
15
* @li @ref ecore_con_url_download_example_c
16
* @li @ref ecore_con_server_simple_example_c
17
* @li @ref ecore_con_client_simple_example_c
18
* @li @ref ecore_evas_callbacks_example_c
19
* @li @ref ecore_evas_object_example_c
20
* @li @ref ecore_evas_basics_example_c
21
* @li @ref Ecore_Evas_Window_Sizes_Example_c
22
* @li @ref Ecore_Evas_Buffer_Example_01_c
23
* @li @ref Ecore_Evas_Buffer_Example_02_c
24
* @li @ref Ecore_exe_simple_example_c
25
* @li @ref ecore_imf_example_c
29
* @page ecore_time_functions_example_c ecore_time - Differences between time functions
31
* This example shows the difference between calling ecore_time_get(),
32
* ecore_loop_time_get() and ecore_time_unix_get().
34
* It initializes ecore, then sets a timer with a callback that, when called,
35
* will retrieve the system time using these 3 different functions. After
36
* displaying the time, it sleeps for 1 second, then call display the time
37
* again using the 3 functions.
39
* Since everything occurs inside the same main loop iteration, the internal
40
* ecore time variable will not be updated, and calling ecore_loop_time_get()
41
* before and after the sleep() call will return the same result.
43
* The two other functions will return a difference of 1 second, as expected.
44
* But ecore_time_unix_get() returns the number of seconds since 00:00:00 1st
45
* January 1970, while ecore_time_get() will return the time since a
46
* unspecified point, but that never goes back in time, even when the timezone
47
* of the machine changes.
49
* @note The usage of ecore_loop_time_get() should be preferred against the
50
* two other functions, for most time calculations, since it won't produce a
51
* system call to get the current time. Use ecore_time_unix_get() when you need
52
* to know the current time and date, and ecore_time_get() when you need a
53
* monotonic and more precise time than ecore_loop_time_get().
55
* @include ecore_time_functions_example.c
59
* @page ecore_timer_example_c ecore timers - Scheduled events
60
* @dontinclude ecore_timer_example.c
62
* This example shows how to setup timer callbacks. It starts a timer that will
63
* tick (expire) every 1 second, and then setup other timers that will expire
64
* only once, but each of them will affect the first timer still executing with
65
* a different API, to demonstrate its usage. To see the full code for this
66
* example, click @ref ecore_timer_example.c "here".
68
* To demonstrate this, let's define some constants that will determine at which
69
* time each timer will expire:
73
* These constants should tell by themselves what will be the behavior of the
74
* program, but I'll explain it anyway. The first timer is set to tick every 1
75
* second, but all the other timers until the 6th one will be started
76
* concurrently at the beginning of the program. Each of them will expire at the
77
* specified time in these constants:
79
* @li The timer2, after 3 seconds of the program being executed, will add a delay
80
* of 3 seconds to timer1;
81
* @li The timer3 will pause timer1 at 8.2 seconds;
82
* @li timer4 will resume timer1 at 11.0 seconds;
83
* @li timer5 will will change the interval of timer1 to 2 seconds;
84
* @li timer6 will stop timer1 and start timer7 and timer8, with 1.1 and 1.2
85
* seconds of interval, respectively; it also sets the precision to 0.2 seconds;
86
* @li timer7 and timer8 will just print their expiration time.
88
* @until ecore_time_get
91
* As almost all the other examples, we create a context structure to pass to
92
* our callbacks, so they can have access to the other timers. We also store the
93
* time of the program start in @c _initial_time, and use the function
94
* @c _get_current_time to retrieve the current time relative to that time. This
95
* will help demonstrate what is going on.
97
* Now, the behavior and relationship between the timers that was described
98
* above is dictated by the following timer callbacks:
103
* It's possible to see the same behavior as other Ecore callbacks here,
104
* returning @ref ECORE_CALLBACK_RENEW when the timer needs to continue ticking,
105
* and @ref ECORE_CALLBACK_CANCEL when it needs to stop its execution. Also
106
* notice that later on our program we are checking for the timers pointers in
107
* the context to see if they are still executing before deleting them, so we
108
* need to set these timer pointers to @c NULL when we are returning @ref
109
* ECORE_CALLBACK_CANCEL. Otherwise the pointer would still be not @c NULL, but
110
* pointing to something that is invalid, since the timer would have already
111
* expired without renewing.
113
* Now the main code, which will start the timers:
115
* @until ecore_shutdown
118
* This code is very simple. Just after starting the library, it will save the
119
* current time to @c _initial_time, start all timers from 1 to 6, and begin the
120
* main loop. Everything should be running right now, displaying the time which
121
* each timer is expiring, and what it is doing to affect the other timers.
123
* After returning from the main loop, every timer is checked to see if it's
124
* still alive and, in that case, deleted, before finalizing the library. This
125
* is not really necessary, since ecore_shutdown() will already delete them for
126
* you, but it's good practice if you have other things going on after this
127
* point that could restart the main loop.
132
* @page ecore_idler_example_c ecore idle state - Idlers, enterers and exiters
134
* This example demonstrates how to manage the idle state of the main loop. Once
135
* a program knows that the main loop is going to enter in idle state, it could
136
* start doing some processing until getting out of this state.
138
* To exemplify this, we also add events and a timer to this program, so we can
139
* see the idle exiter callback being called before processing the event and/or
140
* timer, the event/timer callback being called (processed), then the idle
141
* enterer being called before entering in idle state again. Once in idle, the
142
* main loop keeps calling the idler callback continuously until a new event or
145
* First, we declare a struct that will be used as context to be passed to
146
* every callback. It's not useful everywhere, since this example is very
147
* simple and doesn't do anything other than printing messages, but using this
148
* context will make it a little bit more real. Our context will be used to
149
* delete the timer, idler, idle enterer and exiter, and the event handler, and
150
* also to count how many times the idler was called.
152
* Then we start declaring callbacks for the idle enterer, idle exiter and the
153
* idler itself. Idle enterer and exiter callbacks just print a message saying
154
* that they were called, while the idler, in addition to printing a message
155
* too, also sends an event every 10 times that it is called, incrementing the
156
* context count variable. This event will be used to make the main loop exit
157
* the idle state and call the event callback.
159
* These callbacks return @ref ECORE_CALLBACK_RENEW, since we want them to keep
160
* being called every time the main loop changes to/from idle state. Otherwise,
161
* if we didn't want them to be called again, they should return @ref
162
* ECORE_CALLBACK_CANCEL.
164
* The next function declared is the event callback @c _event_handler_cb. It
165
* will check if the idler was called more than 100 times already @c
166
* (ctxt->count > 100), and will delete the idler, idle enterer and exiter, the
167
* timer (if it still exists), and request that the main loop stop running. Then
168
* it returns @ref ECORE_CALLBACK_DONE to indicate that the event shouldn't be
169
* handled by any other callback.
171
* Finally, we add a callback to the timer, that will just print a message when
172
* it is called, and this will happen only once (@ref ECORE_CALLBACK_CANCEL is
173
* being returned). This timer callback is just here to show that the main loop
174
* gets out of idle state when processing timers too.
176
* The @b main function is simple, just creates a new type of event that we will
177
* use to demonstrate the event handling together with the idle state, adds the
178
* callbacks that we declared so far, fill the context struct, and starts
179
* running the main loop.
181
* @note We use timer and event callbacks to demonstrate the idle state
182
* changing, but it also happens for file descriptor handlers, pipe handlers,
185
* @include ecore_idler_example.c
189
* @page ecore_job_example_c ecore_job - Queuing tasks
191
* This example shows how an @ref Ecore_Job can be added, how it can be
192
* deleted, and that they always execute in the added order.
194
* First, 2 callback functions are declared, one that prints strings passed to
195
* it in the @c data pointer, and another one that quits the main loop. In the
196
* @c main function, 3 jobs are added using the first callback, and another one
197
* is added using the second one.
199
* Then the second added job is deleted just to demonstrate the usage of
200
* ecore_job_del(), and the main loop is finally started. Run this example to
201
* see that @c job1, @c job3 and @c job_quit are ran, in this order.
203
* @include ecore_job_example.c
207
* @page ecore_event_example_01_c Handling events example
208
* This example shows the simplest possible way to register a handler for an
209
* ecore event, this way we can focus on the important aspects. The example will
210
* start the main loop and quit it when it receives the ECORE_EVENT_SIGNAL_EXIT
211
* event. This event is triggered by a SIGTERM(pressing ctrl+c).
213
* So let's start with the function we want called when we receive the event,
214
* instead of just stopping the main loop we'll also print a message, that's
215
* just so it's clear that it got called:
216
* @dontinclude ecore_event_example_01.c
219
* @note We return ECORE_CALLBACK_DONE because we don't want any other handlers
220
* for this event to be called, the program is quitting after all.
222
* We then have our main function and the obligatory initialization of ecore:
225
* We then get to the one line of our example that makes everything work, the
226
* registering of the callback:
228
* @note The @c NULL there is because there is no need to pass data to the
231
* And the all that is left to do is start the main loop:
234
* Full source code for this example: @ref ecore_event_example_01.c.
238
* @page ecore_event_example_02_c ecore events and handlers - Setup and use
239
* This example shows how to create a new type of event, setup some event
240
* handlers to it, fire the event and have the callbacks called. After
241
* finishing, we delete the event handlers so no memory will leak.
243
* See the full source code for this example @ref ecore_event_example_02.c
246
* Let's start the example from the beginning:
248
* @dontinclude ecore_event_example_02.c
251
* First thing is to declare a struct that will be passed as context to the
252
* event handlers. In this structure we will store the event handler pointers,
253
* and two strings that will be used by the first event handler. We also will
254
* use a global integer to store the event type used for our event. It is
255
* initialized with 0 in the beginning because the event wasn't created yet.
256
* Later, in the main function we will use ecore_event_type_new() to associate
257
* another value to it. Now the event handler callbacks:
261
* This is the first event handler callback. It prints the event data received
262
* by the event, and the data passed to this handler when it was added. Notice
263
* that this callback already knows that the event data is an integer pointer,
264
* and that the handler data is a string. It knows about the first one because
265
* this is based on the type of event that is going to be handled, and the
266
* second because it was passed to the ecore_event_handler_add() function when
267
* registering the event handler.
269
* Another interesting point about this callback is that it returns @ref
270
* ECORE_CALLBACK_DONE (0) if the event data is even, swallowing the event and
271
* don't allowing any other callback to be called after this one for this event.
272
* Otherwise it returns @ref ECORE_CALLBACK_PASS_ON, allowing the event to be
273
* handled by other event handlers registered for this event. This makes the
274
* second event handler be called just for "odd" events.
276
* @until ECORE_CALLBACK_DONE
279
* The second event handler will check if the event data is equal to 5, and if
280
* that's the case, it will change the event handler data of the first event
281
* handler to another string. Then it checks if the event data is higher than
282
* 10, and if so, it will request the main loop to quit.
284
* An interesting point of this example is that although the second event
285
* handler requests the main loop to finish after the 11th event being received,
286
* it will process all the events that were already fired, and call their
287
* respective event handlers, before the main loop stops. If we didn't want
288
* these event handlers to be called after the 11th event, we would need to
289
* unregister them with ecore_event_handler_del() at this point.
291
* Now some basic initialization of the context, and the Ecore library itself:
295
* This last line is interesting. It creates a new type of event and returns a
296
* unique ID for this event inside Ecore. This ID can be used anywhere else in
297
* your program to reference this specific type of event, and to add callbacks
300
* It's common if you are implementing a library that declares new types of
301
* events to export their respective types as extern in the header files. This
302
* way, when the library is initialized and the new type is created, it will be
303
* available through the header file to an application using it add some
304
* callbacks to it. Since our example is self-contained, we are just putting it
305
* as a global variable.
307
* Now we add some callbacks:
311
* This is very simple. Just need to call ecore_event_handler_add() with the
312
* respective event type, the callback function to be called, and a data pointer
313
* that will be passed to the callback when it is called by the event.
315
* Then we start firing events:
319
* This @c for will fire 16 events of this type. Notice that the events will be
320
* fired consecutively, but any callback will be called yet. They are just
321
* called by the main loop, and since it wasn't even started, nothing happens
322
* yet. For each event fired, we allocate an integer that will hold the number
323
* of the event (we are arbitrarily creating these numbers just for
324
* demonstration purposes). It's up to the event creator to decide which type of
325
* information it wants to give to the event handler, and the event handler must
326
* know what is the event info structure for that type of event.
328
* Since we are not allocating any complex structure, just a simple integer, we
329
* don't need to pass any special free function to ecore_event_add(), and it
330
* will use a simple @c free on our data. That's the default behavior.
332
* Now finishing our example:
336
* We just start the main loop and watch things happen, waiting to shutdown
337
* Ecore when the main loop exits and return.
341
* @page ecore_fd_handler_example_c ecore fd handlers - Monitoring file descriptors
342
* @dontinclude ecore_fd_handler_example.c
344
* This is a very simple example where we will start monitoring the stdin of the
345
* program and, whenever there's something to be read, we call our callback that
348
* Check the full code for this example @ref ecore_fd_handler_example.c "here".
350
* This seems to be stupid, since a similar result could be achieved by the
354
* while (nbytes = read(STDIN_FILENO, buf, sizeof(buf)))
356
* buf[nbytes - 1] = '\0';
357
* printf("Read %zd bytes from input: \"%s\"\n", nbytes - 1, buf);361
* However, the above code is blocking, and won't allow you to do anything else
362
* other than reading the input. Of course there are other methods to do a
363
* non-blocking reading, like setting the file descriptor to non-blocking and
364
* keep looping always checking if there's something to be read, and do other
365
* things otherwise. Or use a @c select call to watch for more than one file
366
* descriptor at the same time.
368
* The advantage of using an @ref Ecore_Fd_Handler is that you can monitor a
369
* file descriptor, while still iterating on the Ecore main loop. It will allow
370
* you to have timers working and expiring, events still being processed when
371
* received, idlers doing its work when there's nothing happening, and whenever
372
* there's something to be read from the file descriptor, your callback will be
373
* called. And it's everything monitored in the same main loop, no threads are
374
* needed, thus reducing the complexity of the program and any overhead caused
375
* by the use of threads.
377
* Now let's start our program. First we just declare a context structure that
378
* will be passed to our callback, with pointers to our handler and to a timer
379
* that will be used later:
383
* Then we will declare a prepare_callback that is called before any fd_handler
384
* set in the program, and before the main loop select function is called. Just
385
* use one if you really know that you need it. We are just putting it here to
386
* exemplify its usage:
390
* Now, our fd handler. In its arguments, the @c data pointer will have any data
391
* passed to it when it was registered, and the @c handler pointer will contain
392
* the fd handler returned by the ecore_main_fd_handler_add() call. It can be
393
* used, for example, to retrieve which file descriptor triggered this callback,
394
* since it could be added to more than one file descriptor, or to check what
395
* type of activity there's in the file descriptor.
397
* The code is very simple: we first check if the type of activity was an error.
398
* It probably won't happen with the default input, but could be the case of a
399
* network socket detecting a disconnection. Next, we get the file descriptor
400
* from this handler (as said before, the callback could be added to more than
401
* one file descriptor), and read it since we know that it shouldn't block,
402
* because our fd handler told us that there's some activity on it. If the
403
* result of the read was 0 bytes, we know that it's an end of file (EOF), so we
404
* can finish reading the input. Otherwise we just print the content read from
409
* Also notice that this callback returns @ref ECORE_CALLBACK_RENEW to keep
410
* being called, as almost all other Ecore callbacks, otherwise if it returns
411
* @ref ECORE_CALLBACK_CANCEL then the file handler would be deleted.
413
* Just to demonstrate that our program isn't blocking in the input read but
414
* still can process other Ecore events, we are going to setup an @ref
415
* Ecore_Timer. This is its callback:
419
* Now in the main code we are going to initialize the library, and setup
420
* callbacks for the file descriptor, the prepare callback, and the timer:
424
* Notice that the use of ecore_main_fd_handler_add() specifies what kind of
425
* activity we are monitoring. In this case, we want to monitor for read (since
426
* it's the standard input) and for errors. This is done by the flags @ref
427
* ECORE_FD_READ and @ref ECORE_FD_ERROR. For the three callbacks we are also
428
* giving a pointer to our context structure, which has pointers to the handlers
431
* Then we can start the main loop and see everything happening:
435
* In the end we are just deleting the fd handler and the timer to demonstrate
436
* the API usage, since Ecore would already do it for us on its shutdown.
440
* @page ecore_poller_example_c ecore poller - Repetitive polling tasks
441
* @dontinclude ecore_poller_example.c
443
* This example shows how to setup, and explains how an @ref Ecore_Poller is
444
* called. You can @ref ecore_poller_example.c "see the full source code here".
446
* In this example we store the initial time of the program just to use as
447
* comparison to the time when the poller callbacks are called. It will be
448
* stored in @c _initial_time :
450
* @until initial_time
452
* Then next step is to define the poller callback. This callback assumes that a
453
* @c data pointer is passed to it on creation, and is a string just used to
454
* identify the poller. The callback prints this string and the time since the
455
* program started, and returns @ref ECORE_CALLBACK_RENEW to keep being called.
459
* Now in the main function we initialize Ecore, and save the initial time of
460
* the program, so we can compare it later with the time that the pollers are
463
* @until initial_time
465
* Then we change the poll interval to 0.3 seconds (the default is 0.125
466
* seconds) just to show the API usage.
468
* Finally, we create two pollers, one that will be called every 4 ticks, and
469
* another one that will be called every 8 ticks. This means the the first
470
* poller interval will be around 1.2 seconds, and the second one will be
471
* around 2.4 seconds. But the most important point is: since the second poller
472
* interval is a multiple of the first one, they will be always synchronized.
473
* Ecore calls pollers that are in the "same tick" together. It doesn't go back
474
* to the main loop and check if there's another poller to execute at this
475
* time, but instead it calls all the pollers registered to this "tick" at the
476
* same time. See the description of ecore_poller_add() for more details. This
477
* is easy to see in the time printed by both of them.
479
* If instead of two synchronized pollers, we were using two different timers,
480
* one with interval of 1.2 seconds and another one with an interval of 2.4
481
* seconds, there would be no guarantee that they would be totally in sync. Some
482
* delay in the execution of another task, or even in the task called in the
483
* callback, could make them get out of sync, forcing Ecore's main loop to wake
484
* up more than necessary.
486
* Well, this is the code that create these two pollers and set the poll
487
* interval, then starts the main loop:
489
* @until ecore_main_loop_begin
491
* If you hit CTRL-C during the execution of the program, the main loop will
492
* quit, since there are some signal handlers already set by default to do this.
493
* So after the main loop begin call, we change the second poller's interval to
494
* 16 ticks, so it will happen each 4.8 seconds (or each 4 times that the first
497
* This means: the program is started, the first poller is called each 4 ticks
498
* and the second is called each 8 ticks. After CTRL-C is used, the second
499
* poller will be called each 16 ticks.
503
* The rest of the program is just deleting the pollers and shutting down the
508
* @page ecore_con_lookup_example_c Ecore_Con - DNS lookup
510
* This is a very simple example that shows how to make a simple DNS lookup
511
* using ecore_con_lookup().
513
* It's possible to see in the beginning of the main function that we are using
514
* the arguments passed via command line. This is the address that we are going
515
* to make the DNS lookup on.
517
* The next step is to initialize the libraries, and just call
518
* ecore_con_lookup(). This function will get the string that contains the
519
* address to be resolved as first parameter, then a callback that will be
520
* called when the resolve stage is done, and finally a data pointer that will
521
* be passed to the callback.
523
* This function is asynchronous, and the callback will be called only on
524
* success. If there was an error during the resolve stage, there's no way to
525
* know about that. It's only possible to know about errors when setting up the
526
* lookup, by looking at the return code of the ecore_con_lookup() function.
528
* The callback @c _lookup_done_cb passed as argument to ecore_con_lookup() just
529
* prints the resolved canonical name, IP, address of the sockaddr structure,
530
* and the length of the socket address (in bytes).
532
* Finally, we start the main loop, and after that we finalize the libraries and
535
* This is the code for this simple example:
537
* @include ecore_con_lookup_example.c
541
* @page ecore_con_url_download_example_c Ecore_Con_Url - downloading a file
543
* This is a simple example that shows how to download a file using @ref
544
* Ecore_Con_Url. The full source code for this example can be found at @ref
545
* ecore_con_url_download_example.c.
547
* First we are setting some callbacks for events that will be sent when data
548
* arrives in our connection (the data is the content of the file being
549
* downloaded), and when the download is completed. The @c _url_progress_cb and
550
* @c _url_complete_cb are these callbacks:
552
* @dontinclude ecore_con_url_download_example.c
554
* @until main_loop_quit
557
* Notice that we also declared a struct that will hold how many bytes were
558
* downloaded through this object. It will be set in the @c main function using
559
* ecore_con_url_data_set().
561
* In the next step, on the @c main function, we open a file where we are going
562
* to save the content being downloaded:
567
* With the file successfully open, let's create our @ref Ecore_Con_Url object.
568
* For this, we initialize the libraries and create the object:
572
* Then we allocate and set the data struct to the connection object, and set a
573
* file descriptor from our previously open file to it. We also add the event
574
* handlers (callbacks) to the events that will be emitted on data being
575
* received and download complete:
579
* Finally we start our request, and run the main loop:
584
* The rest of this code was just freeing resources, with some labels to be used
585
* for error handling.
589
* @page ecore_con_url_cookies_example_c Ecore_Con_Url - Managing cookies
591
* This example shows how to use an @ref Ecore_Con_Url and enable it to
592
* receive/send cookies. These cookies can be set by the server, saved to a
593
* file, loaded later from this file and sent again to the server. The complete
594
* example can be found at @ref ecore_con_url_cookies_example.c
595
* "ecore_con_url_cookies_example.c"
597
* First we are setting some callbacks for events that will be sent when data
598
* arrives in our connection (the data is the content of the file being
599
* downloaded), and when the download is completed. The @c _url_data_cb and
600
* @c _url_complete_cb are these callbacks:
602
* @dontinclude ecore_con_url_download_example.c
604
* @until main_loop_quit
607
* In the @c main function we parse some parameter from the command line. These
608
* parameters are the url that we are connecting to, and cookie use policy.
610
* After that we initialize the libraries and create a handler to our request
611
* using the given url:
616
* We also set the event handlers for this request and add a header to it, that
617
* will inform our custom user agent:
621
* Now we start playing with cookies. First, let's call
622
* ecore_con_url_cookies_init() to inform that we want cookies enabled. We also
623
* set a file from which we are loading previously set (old) cookies, in case
624
* that we don't want to clear old cookies or old session cookies.
626
* After that we set the file where we are going to save all valid cookies in
627
* the @ref Ecore_Con_Url object. This includes previously loaded cookies (that
628
* weren't cleared) and new cookies set by the response header "Set-Cookie" that
629
* comes with the response to our request:
631
* @until jar_file_set
633
* And finally, before performing the request, we check the command passed as
634
* argument in the command line and use it to choose between clearing old
635
* cookies, clearing just old session cookies, or ignoring old session cookies.
637
* After that we just finish our code as expected:
642
* Notice that in this code, if we want to clear old cookies, we also don't load
643
* them from the file. This is a bit confusing and the API isn't clear, but
644
* ecore_con_url_cookies_file_add() will load cookies from the specified files
645
* just when the operation is really performed (i.e. ecore_con_url_get() is
646
* called). So if ecore_con_url_cookies_clear() is called before
647
* ecore_con_url_get(), the old cookies may not have been loaded yet, so they
648
* are not cleared. To avoid having old cookies loaded, don't add any cookie
649
* file with ecore_con_url_cookies_file_add().
651
* The function ecore_con_url_cookies_clear() is just useful to clear cookies
652
* that are already loaded/valid in the @ref Ecore_Con_Url object (from a
653
* previous request, for example).
657
* @page ecore_con_url_headers_example_c Ecore_Con_Url - customizing a request
659
* This is a simple example that shows how to make a custom request using @ref
660
* Ecore_Con_Url. The full source code for this example can be found at @ref
661
* ecore_con_url_headers_example.c.
663
* The first part of the example is setting the callbacks to be called when an
664
* #ECORE_CON_EVENT_URL_DATA or #ECORE_CON_EVENT_URL_COMPLETE event is received.
665
* These are the callbacks that are going to be used with this:
667
* @dontinclude ecore_con_url_headers_example.c
669
* @until main_loop_quit
672
* The @c main code is as simple as the @ref Ecore_Con_Url example. It contains
673
* some checks for the arguments to see if a GET or POST request is required:
678
* Then we start our required libraries and configure a global option to use
679
* pipelined requests:
681
* @until pipeline_set
683
* Now we create our request object, but using ecore_con_url_custom_new() to use
684
* a POST or GET method depending on the command line arguments. And we also add
685
* the event handlers for our callbacks:
689
* In order to demonstrate our API, some options are set to this request before
690
* actually performing it:
694
* Depending on what kind of request was asked (GET or POST), we use one of the
695
* specific functions to perform it:
699
* After that, we just check for errors, start the main loop, free resources and
707
* @page ecore_con_server_simple_example_c Ecore_Con - Creating a server
709
* In this example we are going to create a server that listens for connections
710
* from clients through a TCP port. You can get the full source code at @ref
711
* ecore_con_server_simple_example.c.
713
* We begin our example in the main function, to demonstrate how to setup
714
* things, and then go to the callbacks that are needed for it to run properly.
716
* In the @c main function, after initializing the libraries, we use
717
* ecore_con_server_add() to startup the server. Look at the reference
718
* documentation of this function: it supports many types of server, and we are
719
* going to use #ECORE_CON_REMOTE_TCP (a TCP based server). Other arguments to
720
* this function are the address where we are listening on, the port, and a data
721
* pointer that will associate that data with the server:
723
* @dontinclude ecore_con_server_simple_example.c
727
* Notice that we are listening only on 127.0.0.1, which is the internal
728
* loopback interface. If the server needs to listening on all of its ips, use
731
* We also need to set event handlers to be called when we receive any data from
732
* the clients, when a new client connects to our server, or when a client
733
* disconnects. These callbacks are:
737
* More details about what these callbacks do will be given later.
739
* Now, before running the main loop, we also want to set some limits to our
740
* server. To avoid it to be overloaded with too many connections to handle, we
741
* are going to set a maximum of 3 clients connected at the same time. This
742
* number is used just to demonstrate the API. A good number to be used here
743
* would need to be determined by tests done on the server, to check the load
746
* Any other client trying to connect to this server, after the limit is
747
* reached, will wait until one of the connected clients disconnect and the
748
* server accepts the new connection.
750
* Another important thing to do is setting a timeout, to avoid that a client
751
* hold a connection for too long without doing anything. This timeout will
752
* disconnect the idle client, allowing that other clients that may be waiting
753
* to connect finally can do it.
755
* Then we just start the main loop:
757
* @until main_loop_begin
759
* After exiting the main loop, we print the list of connected clients, and also
760
* free the data associated with each respective client. This data was
761
* previously associated using ecore_con_client_data_set():
765
* Then before exiting we show the total uptime of the server:
769
* Now let's go back to the used callbacks.
771
* The first callback, @c _add, is registered to the event
772
* #ECORE_CON_EVENT_CLIENT_ADD, which will be called whenever a client connects
775
* This callback will associate a data structure to this client, that will be
776
* used to count how many bytes were received from it. It also prints some info
777
* about the client, and send a welcome string to it. ecore_con_client_flush()
778
* is used to ensure that the string is sent immediately, instead of being
781
* A timeout for idle specific for this client is also set, to demonstrate that
782
* it is independent of the general timeout of the server.
784
* Before exiting, the callback will display a list of all clients still
785
* connected to this server. The code for this callback follows:
787
* @dontinclude ecore_con_server_simple_example.c
789
* @until CALLBACK_RENEW
792
* The second callback is @c _del. It is associated with
793
* #ECORE_CON_EVENT_CLIENT_DEL, and is called whenever a client disconnects from
796
* It will just print some information about the client, free the associated
797
* data structure, and call ecore_con_client_del() on it before exiting the
798
* callback. Here's its code:
800
* @until CALLBACK_RENEW
803
* The last callback will print any data received by this server from its
804
* clients. It also increments the "bytes received" counter, sdata, in the
805
* data structure associated with this client. The callback code follows:
807
* @until CALLBACK_RENEW
810
* The important parts of this example were described above. If you need to see
811
* the full source code for it, there's a link to the code in the beginning of
814
* This example will start a server and start accepting connections from clients, as
815
* demonstrated in the following diagram:
817
* @image rtf ecore_con-client-server-example.png
818
* @image html ecore_con-client-server-example.png
819
* @image latex ecore_con-client-server-example.eps width=\textwidth
821
* @note This example contains a serious security flaw: it doesn't check for the
822
* size of data being received, thus allowing to the string to be exploited in
823
* some way. However, it is left like this to make the code simpler and just
824
* demonstrate the API usage.
828
* @page ecore_con_client_simple_example_c Ecore_Con - Creating a client
830
* Following the same idea as the @ref ecore_con_server_simple_example_c , this
831
* example will demonstrate how to create a client that connects to a specified
832
* server through a TCP port. You can see the full source code at @ref
833
* ecore_con_client_simple_example.c.
835
* Starting from the @c main function, after reading the command line argument
836
* list and initializing the libraries, we try to connect to the server:
838
* @dontinclude ecore_con_client_simple_example.c
843
* After doing this, everything else in @c main is setting up callbacks for the
844
* client events, starting the main loop and shutting down the libraries after
847
* Now let's go to the callbacks. These callbacks are very similar to the server
848
* callbacks (our implementation for this example is very simple). On the
849
* @c _add callback, we just set a data structure to the server, print some
850
* information about the server, and send a welcome message to it:
852
* @dontinclude ecore_con_client_simple_example.c
854
* @until CALLBACK_RENEW
857
* The @c _del callback is as simple as the previous one. We free the data
858
* associated with the server, print the uptime of this client, and quit the
859
* main loop (since there's nothing to do once we disconnect):
861
* @until CALLBACK_RENEW
864
* The @c _data callback is also similar to the server data callback. it will
865
* print any received data, and increase the data counter in the structure
866
* associated with this server:
869
* @until CALLBACK_RENEW
872
* You can see the server counterpart functions of the ones used in this example
873
* in the @ref ecore_con_server_simple_example_c.
875
* This example will connect to the server and start comunicating with it, as
876
* demonstrated in the following diagram:
878
* @image rtf ecore_con-client-server-example2.png
879
* @image html ecore_con-client-server-example2.png
880
* @image latex ecore_con-client-server-example2.eps width=\textwidth
882
* @note This example contains a serious security flaw: it doesn't check for the
883
* size of data being received, thus allowing to the string to be exploited in
884
* some way. However, it is left like this to make the code simpler and just
885
* demonstrate the API usage.
889
* @example ecore_idler_example.c
890
* This example shows when @ref Ecore_Idler, @ref Ecore_Idle_Enterer and @ref
891
* Ecore_Idle_Exiter are called. See
892
* @ref ecore_idler_example_c "the explanation here".
896
* @example ecore_job_example.c
897
* This example shows how to use an @ref Ecore_Job. See
898
* @ref ecore_job_example_c "the explanation here".
902
* @example ecore_time_functions_example.c
903
* Shows the difference between the three time functions. See @ref
904
* ecore_time_functions_example_c "the example explained".
908
* @example ecore_timer_example.c
909
* This example shows how to use timers to have timed events inside ecore.
910
* See @ref ecore_timer_example_c "the example explained".
914
* @example ecore_exe_example_child.c
915
* This is a child process used to receive messages and send it back
917
* Check the @ref Ecore_exe_simple_example_c "Full tutorial"
921
* @example ecore_exe_example.c
922
* This is a process that will send messages to a child and it will stop
923
* when it receives "quit".
924
* Check the @ref Ecore_exe_simple_example_c "Full tutorial"
928
* @example ecore_fd_handler_example.c
929
* This example shows how to setup and use an fd_handler. See
930
* @ref ecore_fd_handler_example_c "the explanation here".
934
* @example ecore_poller_example.c
935
* This example shows how to setup and use a poller. See
936
* @ref ecore_poller_example_c "the explanation here".
940
* @example ecore_event_example_01.c
941
* This example shows how to create an event handler. Explanation: @ref
942
* ecore_event_example_01_c
946
* @example ecore_event_example_02.c
947
* This example shows how to setup, change, and delete event handlers. See
948
* @ref ecore_event_example_02_c "the explanation here".
952
* @example ecore_con_lookup_example.c
953
* Shows how to make a simple DNS lookup. See the complete example description
954
* at @ref ecore_con_lookup_example_c
958
* @example ecore_con_url_download_example.c
959
* Shows how to download a file using an @ref Ecore_Con_Url object. See the
960
* complete example description at @ref ecore_con_url_download_example_c
964
* @example ecore_con_url_cookies_example.c
965
* Shows how to manage cookies on a @ref Ecore_Con_Url object. See the complete
966
* example description at @ref ecore_con_url_cookies_example_c.
970
* @example ecore_con_server_simple_example.c
971
* Shows how to setup a simple server that accepts client connections and sends
972
* a "hello" string to them. See the complete example description at @ref
973
* ecore_con_server_simple_example_c
977
* @example ecore_con_client_simple_example.c
978
* Shows how to setup a simple client that connects to a server and sends a
979
* "hello" string to it. See the complete example description at @ref
980
* ecore_con_client_simple_example_c
984
* @example ecore_con_url_headers_example.c
985
* Shows how to make GET or POST requests using an @ref Ecore_Con_Url object,
986
* and make use of most of its API. See the complete example description at
987
* @ref ecore_con_url_headers_example_c
991
* @page tutorial_ecore_pipe_gstreamer_example
993
* Here is an example that uses the pipe wrapper with a Gstreamer
994
* pipeline. For each decoded frame in the Gstreamer thread, a handle
995
* is called in the ecore thread.
997
* @include ecore_pipe_gstreamer_example.c
998
* @example ecore_pipe_gstreamer_example.c
1002
* @page tutorial_ecore_pipe_simple_example
1003
* @dontinclude ecore_pipe_simple_example.c
1005
* This example shows some simple usage of ecore_pipe. We are going to create a
1006
* pipe, fork our process, and then the child is going to communicate to the
1007
* parent the result of its processing through the pipe.
1009
* As always we start with our includes, nothing special:
1013
* The first thing we are going to define in our example is the function we are
1014
* going to run on the child process, which, as mentioned, will do some
1015
* processing and then will write the result to the pipe:
1018
* @note The sleep was added so the parent process would think the child process
1019
* was doing something interesting...
1021
* Next up is our function for handling data arriving in the pipe. It copies the
1022
* data to another buffer, adds a terminating NULL and prints it. Also if it
1023
* receives a certain string it stops the main loop(effectively ending the
1028
* And now on to our main function, we start by declaring some variables and
1029
* initializing ecore:
1032
* And since we are talking about pipes let's create one:
1035
* Now we are going to fork:
1039
* The child process is going to do the our fancy processing:
1041
* @note It's very important to call ecore_pipe_read_close() here so that the
1042
* child process won't read what it is writing to the pipe itself.
1044
* And the parent is going to run ecore's main loop waiting for some data:
1046
* @note Calling ecore_pipe_write_close() here isn't important but since we
1047
* aren't going to write in the pipe it is good practice.
1049
* And finally when done processing(the child) or done receiving(the parent) we
1050
* delete the pipe and shutdown ecore:
1053
* @example ecore_pipe_simple_example.c
1057
* @page tutorial_ecore_animator Ecore animator example
1058
* @dontinclude ecore_animator_example.c
1060
* For this example we are going to animate a rectangle growing, moving and
1061
* changing color, and then move it back to it's initial state with a
1062
* different animation. We are also going to have a second rectangle moving
1063
* along the bottom of the screen. To do this we are going to use ecore_evas,
1064
* but since that is not the focus here we won't going into detail about it.
1067
* @until evas_object_show
1068
* @until evas_object_show
1069
* All of this is just setup, not what we're interested in right now.
1071
* Now we are going to set the frametime for our animation to one fiftieth of
1072
* a second, this will make our program consume more resources but should make
1073
* our animation extra smooth:
1076
* And now we get right to the business of creating our ecore_animator:
1078
* @note We are telling our animation to last 10 second and to call
1079
* _advance_frame with rect as data.
1081
* So far we setup the first and second animations, the third one however is a
1082
* bit different, this time we won't use a timeline animation, that's because we
1083
* don't want our animation to stop:
1084
* @until animator_add
1086
* Next we set a few timers to execute _start_second_anim, _freeze_third_anim
1087
* and _thaw_thir_anim in 10, 5 and 10 seconds respectively:
1090
* And now we tell ecore to begin the main loop and free some resources once
1091
* it leaves the main loop:
1094
* Here we have the callback function for our first animation, which first
1095
* takes @p pos(where in the timeline we are), maps it to a SPRING curve that
1096
* which will wobble 15 times and will decay by a factor of 1.2:
1099
* Now that we have the frame we can adjust the rectangle to its appropriate
1103
* And now the callback that will run 10 seconds after the program starts(5
1104
* seconds after the first animation finishes) and starts our second
1107
* @note For this animation we made the frametime much larger which means our
1108
* animation might get "jerky".
1110
* The callback for our second animation, our savvy reader no doubt noted that
1111
* it's very similar to the callback for the first animation. What we change for
1112
* this one is the type of animation to BOUNCE and the number of times it will
1116
* And for our last animation callback something simpler, we just move our
1117
* rectangle right by one pixel until it reaches the end of the screen and then
1118
* start at the beginning again:
1121
* Our next two functions respectively freezes and thaw our third animation, so
1122
* that it won't happen for the 5 seconds after the first animation ends and the
1123
* second animation begins:
1127
* @example ecore_animator_example.c
1131
* @page ecore_thread_example_c Ecore_Thread - API overview
1133
* Working with threads is hard. Ecore helps to do so a bit easier, but as
1134
* the example in @ref ecore_thread_example.c "ecore_thread_example.c" shows,
1135
* there's a lot to consider even when doing the most simple things.
1137
* We'll be going through this thorough example now, showing how the differents
1138
* aspects of @ref Ecore_Thread are used, but users are encourage to avoid
1139
* threads unless it's really the only option, as they always add more
1140
* complexity than the program usually requires.
1142
* Ecore Threads come in two flavors, short jobs and feedback jobs. Short jobs
1143
* just run the given function and are more commonly used for small tasks
1144
* where the main loop does not need to know how the work is going in between.
1145
* The short job in our example is so short we had to artificially enlarge it
1146
* with @c sleep(). Other than that, it also uses threads local data to keep
1147
* the data we are working with persistent across different jobs ran by the
1148
* same system thread. This data will be freed when the no more jobs are
1149
* pending and the thread is terminated. If the data doesn't exist in the
1150
* thread's storage, we create it and save it there for future jobs to find
1151
* it. If creation fails, we cancel ourselves, so the main loop knows that
1152
* we didn't just exit normally, meaning the job could not be done. The main
1153
* part of the function checks in each iteration if it was canceled by the
1154
* main loop, and if it was, it stops processing and clears the data from the
1155
* storage (we assume @c cancel means no one else will need this, but this is
1156
* really application dependent).
1157
* @dontinclude ecore_thread_example.c
1163
* Feedback jobs, on the other hand, run tasks that will inform back to the
1164
* main loop its progress, send partial data as is processed, just ping saying
1165
* it's still alive and processing, or anything that needs the thread to talk
1166
* back to the main loop.
1171
* Finally, one more feedback job, but this one will be running outside of
1172
* Ecore's pool, so we can use the pool for real work and keep this very
1173
* light function unchecked. All it does is check if some condition is met
1174
* and send a message to the main loop telling it it's time to close.
1180
* Every now and then the program prints its status, counting threads running
1185
* In our main loop, we'll be receiving messages from our feedback jobs using
1186
* the same callback for both of them.
1190
* The light job running out of the pool will let us know when we can exit our
1194
* Next comes the handling of data sent from the actual worker threads, always
1195
* remembering that the data belongs to us now, and not the thread, so it's
1196
* our responsibility to free it.
1200
* Last, the condition to exit is given by how many messages we want to handle,
1201
* so we need to count them and inform the condition checking thread that the
1205
* When a thread finishes its job or gets canceled, the main loop is notified
1206
* through the callbacks set when creating the task. In this case, we just
1207
* print what happen and keep track of one of them used to exemplify canceling.
1208
* Here we are pretending one of our short jobs has a timeout, so if it doesn't
1209
* finish before a timer is triggered, it will be canceled.
1211
* @until _cancel_timer_cb
1214
* The main function does some setup that includes reading parameters from
1215
* the command line to change its behaviour and test different results.
1217
* @li -t \<some_num\> maximum number of threads to run at the same time.
1218
* @li -p \<some_path\> adds @c some_path to the list used by the feedback jobs.
1219
* This parameter can be used multiple times.
1220
* @li -m \<some_num\> the number of messages to process before the program is
1221
* signalled to exit.
1223
* Skipping some bits, we init Ecore and our application data.
1225
* @until appdata.max_msgs
1227
* If any paths for the feedback jobs were given, we use them, otherwise we
1228
* fallback to some defaults. Always initializing the proper mutexes used by the
1231
* @until EINA_LIST_FREE
1235
* Initialize the mutex needed for the condition checking thread
1236
* @skip appdata.mutex
1237
* @until appdata.condition
1239
* And start our tasks.
1240
* @until appdata.thread_3
1243
* To finalize, set a timer to cancel one of the tasks if it doesn't end
1244
* before the timeout, one more timer for status report and get into the main
1245
* loop. Once we are out, destroy our mutexes and finish the program.
1246
* @until _status_timer_cb
1249
* @example ecore_thread_example.c
1253
* @page ecore_evas_callbacks_example_c Ecore Evas Callbacks
1254
* @dontinclude ecore_evas_callbacks.c
1256
* Our example is remarkably simple, all it does is create an Ecore_Evas and
1257
* register a callback for a bunch of events. What's interesting here is
1258
* knowing when each of these callbacks will be called, however since that
1259
* depends on the underlying windowing system there are no guarantees that all
1260
* of the callbacks will be called for your windowing system. To know which
1261
* callbacks will be called for your windowing system run the example and
1262
* redirect the output to a file, and take a look at it.
1264
* @note Make sure you minimize, resize, give and remove focus to see more
1267
* The example is constituted of two main parts, first is the implementation of
1268
* callbacks that will be called for each event(all our callbacks do is print
1269
* their own name) and the second is the main function where we register the
1270
* event callbacks and run the main loop:
1271
* @include ecore_evas_callbacks.c
1272
* @example ecore_evas_callbacks.c
1276
* @page Ecore_Evas_Window_Sizes_Example_c Ecore_Evas window size hints
1278
* On this example, we show you how to deal with @c Ecore_Evas window
1279
* size hints, which are implemented <b>per Evas engine</b>.
1281
* We start by defining an initial size for our window and, after
1282
* creating it, adding a background white rectangle and a text object
1283
* to it, to be used to display the current window's sizes, at any
1285
* @dontinclude ecore_evas_window_sizes_example.c
1286
* @skip define WIDTH
1289
* @dontinclude ecore_evas_window_sizes_example.c
1292
* @dontinclude ecore_evas_window_sizes_example.c
1294
* @until main_loop_begin
1295
* @dontinclude ecore_evas_window_sizes_example.c
1299
* The program has a command line interface, responding to the
1301
* @dontinclude ecore_evas_window_sizes_example.c
1305
* Use the @c 'm' key to impose a minimum size of half the initial
1306
* ones on our window. Test it by trying to resize it to smaller sizes
1308
* @dontinclude ecore_evas_window_sizes_example.c
1314
* The @c 'x' key will, in turn, set a maximum size on our window --
1315
* to two times our initial size. Test it by trying to resize the
1316
* window to bigger sizes than that:
1317
* @dontinclude ecore_evas_window_sizes_example.c
1323
* Window base sizes will override any minimum sizes set, so try it
1324
* with the @c 'b' key. It will set a base size of two times the
1326
* @dontinclude ecore_evas_window_sizes_example.c
1332
* Finally, there's a key to impose a "step size" on our window, of 40
1333
* pixels. With than on (@c 's' key), you'll see the window will
1334
* always be bound to @b multiples of that size, for dimensions on
1341
* The full example follows.
1343
* @include ecore_evas_window_sizes_example.c
1344
* @example ecore_evas_window_sizes_example.c
1348
* @page ecore_evas_object_example_c Ecore Evas Object example
1349
* @dontinclude ecore_evas_object_example.c
1351
* This example creates an Ecore_Evas(a window) and associates a background and
1352
* a custom cursor for it.
1354
* We'll start looking at the association, which is quite simple. We choose to
1355
* associate using ECORE_EVAS_OBJECT_ASSOCIATE_BASE to have it be resized with
1356
* the window, since for a background that is what's most useful:
1357
* @skipline ecore_evas_object_associate
1358
* @note If we didn't associate the background we'd need to listen to resize of
1359
* Ecore_Evas and manually resize the background or have artifacts on our
1362
* We then check that the association worked:
1365
* Next we are going to set a custom cursor, for our cursor we are going to use
1366
* a small green rectangle. Our cursor is going to be on layer 0(any lower and
1367
* it would be below the background and thus invisible) and clicks will be
1368
* computed as happening on pixel 1, 1 of the image:
1371
* We then check every one of those parameters:
1374
* Here you have the full-source of the code:
1375
* @include ecore_evas_object_example.c
1376
* @example ecore_evas_object_example.c
1380
* @page ecore_evas_basics_example_c Ecore Evas basics example
1381
* @dontinclude ecore_evas_basics_example.c
1383
* This example will illustrates the usage of some basic Ecore_Evas functions.
1384
* This example will list the available evas engines, check which one we used to
1385
* create our window and set some data on our Ecore_Evas. It also allows you to
1386
* hide/show all windows in this process(we only have one, but if there were
1387
* more they would be hidden), to hide the windows type 'h' and hit return, to
1388
* show them, type 's' and hit return.
1390
* The very first thing we'll do is initialize ecore_evas:
1391
* @skipline evas_init
1394
* Once inited we query which engines are available:
1395
* @until ecore_evas_engines_free
1397
* We then create an Ecore_Evas(window) with the first available engine, on
1398
* position 0,0 with size 200,200 and no especial flags, set it's title and show
1402
* We now add some important data to our Ecore_Evas:
1405
* And since our data is dynamically allocated we'll need to free it when the
1407
* @until delete_request
1408
* @dontinclude ecore_evas_basics_example.c
1411
* @skip printf("Using1413
* We now print which Evas engine is being used for our example:
1416
* We are going to add a background to our window but before we can do that
1417
* we'll need to get the canvas(Evas) on which to draw it:
1420
* We then do a sanity check, verifying if the Ecore_Evas of the Evas is the
1421
* Ecore_Evas from which we got the Evas:
1424
* Now we can actually add the background:
1425
* @until ecore_evas_object_associate
1427
* To hide and show the windows of this process when the user presses 'h' and
1428
* 's' respectively we need to know when the user types something, so we
1429
* register a callback for when we can read something from @c stdin:
1432
* The callback that actually does the hiding and showing is pretty simple, it
1433
* does a @c scanf(which we know won't block since there is something to read on
1434
* @c stdin) and if the character is an 'h' we iterate over all windows calling
1435
* @c ecore_evas_hide on them, if the character is an 's' we call @c
1436
* ecore_evas_show instead:
1437
* @dontinclude ecore_evas_basics_example.c
1438
* @skip static Eina_Bool
1440
* @skip ecore_main_loop_begin
1442
* Once all is done we run our main loop, and when that is done(application is
1443
* exiting) we free our Ecore_Evas and shutdown the ecore_evas subsystem:
1446
* Here you have the full-source of the code:
1447
* @include ecore_evas_basics_example.c
1448
* @example ecore_evas_basics_example.c
1452
* @page Ecore_Evas_Buffer_Example_01_c Ecore_Evas buffer example
1454
* Between the Evas examples, there is one in which one creates a
1455
* canvas bound to the Evas @b buffer engine and uses its pixel
1456
* contents to create an PPM image on disk. There, one does that by
1457
* creating the canvas "by hand", with @c evas_new(), @c
1458
* evas_engine_info_set(), etc.
1460
* On this example, we accomplish the very same task, but by using the
1461
* @c Ecore_Evas helper wrapper functions on a buffer engine
1462
* canvas. If you compare both codes, you'll see how much code one is
1463
* saved from by using the @c Ecore_Evas wrapper functions.
1465
* The code is simple as it can be. After instantianting our canvas
1466
* window, with ecore_evas_buffer_new(), we grab its canvas pointer
1467
* and create the desired objects scene on it, which in this case is
1468
* formed by 3 rectangles over the top left corner of a white
1470
* @dontinclude ecore_evas_buffer_example_01.c
1474
* Since it's a buffer canvas and we're using it to only save its
1475
* contents on a file, we even needn't ecore_evas_show() it. We make
1476
* it render itself, forcefully, without the aid of Ecore's main loop,
1477
* with ecore_evas_manual_render():
1478
* @dontinclude ecore_evas_buffer_example_01.c
1479
* @skip manual_render
1480
* @until manual_render
1482
* And we're ready to save the window's shiny rendered contents as a
1483
* simple PPM image. We do so by grabbing the pixels of the @c
1484
* Ecore_Evas' internal canvas, with ecore_evas_buffer_pixels_get():
1485
* @dontinclude ecore_evas_buffer_example_01.c
1488
* @dontinclude ecore_evas_buffer_example_01.c
1489
* @skip support function
1494
* Check that destination file for the result. The full example
1497
* @include ecore_evas_buffer_example_01.c
1498
* @example ecore_evas_buffer_example_01.c
1502
* @page Ecore_Evas_Buffer_Example_02_c Ecore_Evas (image) buffer example
1504
* In this example, we'll demonstrate the use of
1505
* ecore_evas_object_image_new(). The idea is to have the same scene
1506
* created for @ref Ecore_Evas_Buffer_Example_01_c as the contents of
1509
* The canvas receiving this image object will have a white
1510
* background, a red border image to delimit this image's boundaries
1511
* and the image itself. After we create the special image, we set
1512
* its "fill" property, place and resize it as we want. We have also
1513
* to resize its underlying @c Ecore_Evas too, to the same dimensions:
1514
* @dontinclude ecore_evas_buffer_example_02.c
1515
* @skip object_image_new
1516
* @until resize(sub_ee
1518
* Now, we re-create the scene we cited, using the sub-canvas of our
1519
* image to parent the objects in question. Because image objects are
1520
* created with the alpha channel enabled, by default, we'll be seeing
1521
* our white rectangle beneath the scene:
1522
* @dontinclude ecore_evas_buffer_example_02.c
1523
* @skip rectangle_add(sub_canvas
1526
* And that's all. The contents of our image could be updated as one
1527
* wished, and they would always be mirrored in the image's area.
1529
* Check that destination file for the result. The full example
1532
* @include ecore_evas_buffer_example_02.c
1533
* @example ecore_evas_buffer_example_02.c
1537
* @page Ecore_exe_simple_example_c Ecore_exe
1538
* Creating a processes and IPC (Inter process communication)
1540
* In this example we will show how to create a new process and communicate
1541
* with it in a portable way using the Ecore_exe module.
1543
* In this example we will have two process and both will communicate with each
1544
* other using messages. A father process will start a child process and it will
1545
* keep sending messages to the child until it receives a message to quit.
1546
* To see the full source use the links:
1547
* @li @ref ecore_exe_example.c "Father"
1548
* @li @ref ecore_exe_example_child.c "Child"
1550
* Let's start the tutorial. The implementation of the child it's pretty simple.
1551
* We just read strings from stdin and write a message in the stdout. But you
1552
* should be asking yourself right know. "If I'm receiving data from an other
1553
* process why I'm reading and writing in stdin/stdout?". That's because, when
1554
* you spawn a process using the Ecore_Exe module it will create a pipe between
1555
* the father and the child process and the stdin/stdout of the child process
1556
* will be redirected to the pipe. So when the child wants to receive or send
1557
* data to the father, just use the stdin/stdout.
1558
* However the steps to send data from the father to the child is quite
1559
* different, but we will get there.
1561
* The child will register a fd handler to monitor the stdin.
1562
* So we start registering the ecore FD handler:
1563
* @dontinclude ecore_exe_example_child.c
1564
* @skip ecore_main_fd_handler_add
1567
* If you don't remember the parameters of @ref ecore_main_fd_handler_add,
1568
* please check its documentation.
1570
* Now that we have our handler registered we will start the ecore's main loop:
1571
* @skipline ecore_main_loop_begin
1573
* Now let's take a look in the callback function. Its a simple function
1574
* that will read from stdin 3 times and at the third time will say
1575
* to the father: "quit".
1576
* @dontinclude ecore_exe_example_child.c
1577
* @skip static Eina_Bool
1583
* You may notice that we are sending the messages to stdout, and our father
1584
* will receive it. Also our string must have a "\n" because the string will
1585
* be buffered in the pipe until it finds EOF or a "newline" in our case we
1586
* won't have a EOF unless we close the pipe, so we use the "\n" char.
1588
* One more thing, we use fflush(stdout) because probably our message won't
1589
* fill our entire buffer and the father would never receive the message. So we
1590
* use this function to flush the buffer and the father can receive as fast as
1593
* Now that we have our child ready, let's start our work in the father's source
1596
* We start creating the child process like this:
1597
* @dontinclude ecore_exe_example.c
1598
* @skip childHandle = ecore_exe_pipe_run
1601
* With the command above we are creating our child process, the first
1602
* parameter is the command to be executed, the second are the pipe flags and
1603
* in our case we will write and read in the pipe so we must say what we are
1604
* doing in the pipe. You may notice the flag ECORE_EXE_PIPE_READ_LINE_BUFFERED,
1605
* this means that reads are buffered until I find a newline. And the third
1606
* parameter is data that we would like to send to the process in its creating.
1607
* This case we are sending nothing, so just use NULL.
1609
* Then we check if the process was created:
1613
* After this we get the PID of the child process and just print it in the screen.
1614
* The PID stands for Process identification. This is just an internal
1615
* identifier of your process:
1621
* The way that Ecore_exe works is: when we want to read data sent from
1622
* our child we must use an ecore event.
1623
* So let's start register our event listener:
1624
* @skipline ecore_event_handler_add
1626
* Now to send messages to our child we will use a timer, so every 1 second we
1627
* will send a message to the child.
1628
* @skipline ecore_timer_add
1630
* After all this we start the main loop. Now let's pass to the callback
1633
* Now we will see how we actually send the data and receive it.
1634
* Let's start with _sendMessage:
1635
* @dontinclude ecore_exe_example.c
1636
* @skip _sendMessage(void *data)
1639
* We use ecore_exe_send to send data to the child process, it's pretty simple.
1640
* To know what the parameters stands for, check the docs.
1642
* @note The function @b ecore_exe_send will never block your program, also
1643
* there is no partial send of the data. This means either the function will
1644
* send all the data or it will fail.
1646
* Now let's take a look in our event callback and see how we retrieve the
1648
* @dontinclude ecore_exe_example.c
1649
* @skip static Eina_Bool
1653
* It's just like an normal event, we get a reference to Ecore_Exe_Event_Data,
1654
* extract the data and then show it in the screen.
1656
* And that's it, after all it's not complicated to create a process and
1657
* communicate with it.
1662
* @page ecore_imf_example_c ecore_imf - How to handle preedit and commit string from Input Method Framework
1664
* This example demonstrates how to connect input method framework and handle preedit and commit string from input method framework.
1666
* To input Chinese, Japanese, Korean and other complex languages, the editor should be connected with input method framework.
1668
* How to initialize and shutdown ecore imf module
1669
* @li ecore_imf_init() should be called to initialize and load immodule.
1670
* @li ecore_imf_shutdown() is used for shutdowning and unloading immodule.
1672
* How to create input context and register pre-edit and commit event handler
1674
* Each entry should have each input context to connect with input service framework.
1675
* Key event is processed by input method engine.
1676
* The result is notified to application through ECORE_IMF_CALLBACK_PREEDIT_CHANGED and ECORE_IMF_CALLBACK_COMMIT event.
1678
* The full example follows.
1680
* @include ecore_imf_example.c