summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorLuciana Magno de Almeida <luciana@expertisesolutions.com.br>2014-12-16 19:04:43 -0200
committerFelipe Magno de Almeida <felipe@expertisesolutions.com.br>2015-08-25 03:42:34 -0300
commitcf4d84c85b48d32fd85deeafdc7aee4543875725 (patch)
tree0c5c7a61507819bff113eb8ee8883c7026f33465 /doc
parentdfb979950cfcebc21d1b0e933d4f02ab2084e304 (diff)
cxx: Added examples and tutorial for C++ binding
Summary: Added the following examples: * bg_cxx_example_01 * bg_cxx_example_02 * bubble_cxx_example_01 * button_cxx_example_00 * button_cxx_example_01 * calendar_cxx_example_01 * calendar_cxx_example_02 * calendar_cxx_example_03 * calendar_cxx_example_04 * calendar_cxx_example_05 * clock_cxx_example * datetime_cxx_example * glview_cxx_example_01 * hoversel_cxx_example_01 * icon_cxx_example_01 * location_cxx_example_01 * menu_cxx_example_01 * popup_cxx_example_01 * radio_cxx_example_01 * separator_cxx_example_01 * slider_cxx_example * spinner_cxx_example * table_cxx_example_01 * table_cxx_example_02 * thumb_cxx_example_01 Added documentation for the above examples, as well as how using lambdas with C++ elm binding. How to use autohide feature and how to use the C++ wrappers to create windows, widgets and call Eo functions from them with automatic C++ type conversion and how to use signals from C++.
Diffstat (limited to 'doc')
-rw-r--r--doc/Doxyfile.in2
-rw-r--r--doc/examples-cxx.dox5332
-rw-r--r--doc/examples.dox1
3 files changed, 5334 insertions, 1 deletions
diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in
index 72133cd68..7c0e86a61 100644
--- a/doc/Doxyfile.in
+++ b/doc/Doxyfile.in
@@ -1,7 +1,7 @@
1PROJECT_NAME = Elementary 1PROJECT_NAME = Elementary
2PROJECT_NUMBER = @PACKAGE_VERSION@ 2PROJECT_NUMBER = @PACKAGE_VERSION@
3OUTPUT_DIRECTORY = . 3OUTPUT_DIRECTORY = .
4INPUT = @srcdir@/examples.dox @top_srcdir@/src/lib @srcdir@/index.doxy @top_srcdir@/src/bin/elm_prefs_cc_handlers.c 4INPUT = @srcdir@/examples.dox @srcdir@/examples-cxx.dox @top_srcdir@/src/lib @srcdir@/index.doxy @top_srcdir@/src/bin/elm_prefs_cc_handlers.c
5IMAGE_PATH = @srcdir@/img 5IMAGE_PATH = @srcdir@/img
6OUTPUT_LANGUAGE = English 6OUTPUT_LANGUAGE = English
7GENERATE_HTML = YES 7GENERATE_HTML = YES
diff --git a/doc/examples-cxx.dox b/doc/examples-cxx.dox
new file mode 100644
index 000000000..7b45ed9ff
--- /dev/null
+++ b/doc/examples-cxx.dox
@@ -0,0 +1,5332 @@
1/**
2 * @page Examples-cxx Examples with C++ Bindings.
3 *
4 * Here is a list of Elementary C++ Examples.
5 *
6 * @ref bg_cxx_example_01
7 *
8 * @ref bg_cxx_example_02
9 *
10 * @ref bubble_cxx_example_01
11 *
12 * @ref button_cxx_example_00
13 *
14 * @ref button_cxx_example_01
15 *
16 * @ref calendar_cxx_example_01
17 *
18 * @ref calendar_cxx_example_02
19 *
20 * @ref calendar_cxx_example_03
21 *
22 * @ref calendar_cxx_example_04
23 *
24 * @ref calendar_cxx_example_05
25 *
26 * @ref clock_cxx_example
27 *
28 * @ref datetime_cxx_example
29 *
30 * @ref glview_cxx_example_01
31 *
32 * @ref hoversel_cxx_example_01
33 *
34 * @ref icon_cxx_example_01
35 *
36 * @ref location_cxx_example_01
37 *
38 * @ref menu_cxx_example_01
39 *
40 * @ref popup_cxx_example_01
41 *
42 * @ref radio_cxx_example_01
43 *
44 * @ref separator_cxx_example_01
45 *
46 * @ref slider_cxx_example
47 *
48 * @ref spinner_cxx_example
49 *
50 * @ref table_cxx_example_01
51 *
52 * @ref table_cxx_example_02
53 *
54 * @ref thumb_cxx_example_01
55 *
56 */
57
58/**
59 * @page lambda Lambda Functions with Elementary - C++11
60
61 * With this tutorial we'll give you a better view of how the lambda
62 * function can and will be constantly use in the C++ bindings. For a
63 * more broad aproach you should do a little web research.
64
65 * The syntax adopted for these examples:
66
67 * @c [capture] @c (parameters) @c {body}
68
69 * @a capture: Determinate how and if the capture occurs. Possible
70 * indicators, two or more should be intercalated by commas:
71
72 * @li [ ] - Capture nothing
73
74 * @li [&] - Capture variables by reference
75
76 * @li [=] - Capture variables by copy
77
78 * @li [&a, b] - Capture <b> only @a a </b> by reference and <b> only
79 * @a b </b> by copy
80
81 * @li [&, a] - Capture variables by reference and <b> only @a a </b>
82 * by copy
83
84 * @li [this] - Capture @c this pointer by copy
85
86 * @a parameters: List of parameters necessary for each specific
87 * lambda function.
88
89 * @a body: Function body
90
91 * Let's start with a more simple lambda and later a more complex one,
92 * all extracted from elementary examples:
93
94 * <b>First Example</b> - @ref button_cxx_example_00 :
95
96 * @image html screenshots/button_cxx_example_00.png
97 * @image latex screenshots/button_cxx_example_00.eps width=\textwidth
98
99 * @dontinclude button_cxx_example_00.cc
100 * @skipline btn
101 * @skip auto
102 * @until clicked_add
103
104 * In this example we use a @a lambda function for elm::button
105 * btn that will be called when that button is clicked in
106 * callback_clicked_add( on_click ). This lambda will then ask to exit
107 * Elementary's main loop with @a elm_exit(). If this call is issued,
108 * it will flag the main loop to cease processing and return back to
109 * its parent function, usually your elm_main() function.
110
111 * Now let's analize the sintax used for this lambda:
112
113 * With @a [] we are signaling that we don't want to capture any
114 * variables and with @a () we are indicating that this lambda doesn't
115 * need parameters to work as it should. Now the important part of this
116 * function it's the @a body represented by @a {} where we are applying
117 * elm_exit() everytime this lambda is called.
118
119 * In this case we are using @a std::bind to bind the parameters of
120 * our lambda function to return as @a std::function object to
121 * on_click which was declare as auto.
122
123 * For this example with std::bind we simplified our work simply
124 * because we didn't have to search in the code or documentation of
125 * Elementary to look for the parameters and/or values that the
126 * callback_clicked_add requires of the function we are adding.
127
128 * <b>Second Example</b> - @ref hoversel_cxx_example_01 :
129
130 * @image html screenshots/hoversel_cxx_example_01.png
131 * @image latex screenshots/hoverse_cxx_example_01.eps width=\textwidth
132
133 * @dontinclude hoversel_cxx_example_01.cc
134 * @skip add_item
135 * @until clicked_add
136
137 * In this example we use a @a lambda function for @a hoversel that
138 * will be called when that hoversel is clicked in
139 * callback_clicked_add( add_item ). This lambda will then add an item
140 * to heversel, note that since we allocate memory for the item we
141 * need to know when the item dies so we can free that memory.
142
143 * Now let's analize the sintax used for this lambda:
144
145 * @li @a [] : signaling that we don't want to capture any
146 * variables
147
148 * @li @a (::elm::hoversel obj ) : indicating that this lambda needs
149 * the parameter @p obj to work as it should. Bbecause we are only
150 * adding the parameter we need instead of all the parameters this
151 * callback requires we need to use placeholders in std::bind,
152 * indicating the place that @obj should occupy in our
153 * callback_clicked_add.
154
155 * When the function object returned by bind is called, an argument
156 * with placeholder _1 is replaced by the first argument in the call,
157 * _2 is replaced by the second argument in the call, and so on.
158
159 * @li @a body represented by @a {} where we are adding ervery
160 * function and local variables that will be needed.
161
162 * In this case we are using @a std::bind to bind the parameters of
163 * our lambda function to return as @a std::function object to
164 * add_item which was declare as auto.
165
166 * @see Consult all examples from elementary with C++ Bindings @ref
167 * Examples-cxx "here"
168 */
169
170/**
171 * @page bg_cxx_example_01 elm::bg - Plain color background with C++ binding
172 * @dontinclude bg_cxx_example_01.cc
173
174 * This example just sets a default background with a plain color.
175
176 * The first part consists of including the headers. In this case we
177 * are only working with the Elementary C++ binding and thus we need
178 * only to include him.
179
180 * @skipline Elementary.hh
181
182 * @attention If necessary the C and/or the C++ headers should be
183 * include here as well.
184
185 * Now we need to actually start the code and set the elm_policy,
186 * which defines for a given policy group/identifier a new policy's
187 * value, respectively. In this example the only policy we need to
188 * set a value for is @c ELM_POLICY_QUIT, possibles values for it are:
189
190 * @li @p ELM_POLICY_QUIT_NONE: Never quit the application
191 * automatically;
192
193 * @li @p ELM_POLICY_QUIT_LAST_WINDOW_CLOSED: quit when the
194 * application's last window is closed;
195
196 * @li @p ELM_POLICY_QUIT_LAST_WINDOW_HIDDEN : quit when the
197 * application's last window is hidden;
198
199 * @skip EAPI_MAIN
200 * @until elm_policy_set
201
202 * As you can see, the policy we chose was to quit when the last win
203 * is hidden as opose to examples with the C bindings where we
204 * perpetually set it to quit when last win was closed. This changed
205 * was necessary because in C++ binding as the elm mainloop stop
206 * running all object are destroyed, references are unreferenced and
207 * events are stopped at ELM_MAIN().
208
209 * @see For more details consult elm_policy_set
210
211 * Next step is creating an Elementary window, where win calls a
212 * constructor and sets the type of the win to ELM_WIN_BASIC
213 * (Elm_Win_Type), which is the indicated type for most of our
214 * examples. Here we also set the title that will appear at the top of
215 * our window and then the autohide state for it.
216
217 * The autohide works similarly to @p autodel, automatically handling
218 * "delete,request" signals when set to @p true, with the difference
219 * that it will hide the window, instead of destroying it.
220
221 * It is specially designed to work together with @p
222 * ELM_POLICY_QUIT_LAST_WINDOW_HIDDEN which allows exiting
223 * Elementary's main loop when all the windows are hidden.
224
225 * @skip ::elm::win
226 * @until autohide_set
227
228 * @note @p autodel and @a autohide are not mutually exclusive. The
229 * window will be destructed if both autodel and autohide is set to @p
230 * EINA_TRUE or @p true.
231
232 * Now we construct the elm background and for this we use the C++
233 * method below, setting it's parent.
234
235 * @skipline ::elm::bg
236
237 * To better understand, the function @c size_hint_weight_set for C++
238 * bindings originated from C bindings function
239 * evas_object_size_hint_weight_set, that is EFL Evas type function.
240 * With this function we set the hints for an object's weight. The
241 * parameters are:
242
243 * @li x - Nonnegative double value to use as horizontal weight hint.
244
245 * @li y - Nonnegative double value to use as vertical weight hint.
246
247 * This is not a size enforcement in any way, it's just a hint that
248 * should be used whenever appropriate. This is a hint on how a
249 * container object should resize a given child within its area.
250
251 * Containers may adhere to the simpler logic of just expanding the
252 * child object's dimensions to fit its own (see the EVAS_HINT_EXPAND
253 * helper weight macro in the EFL Evas Documentation) or the complete
254 * one of taking each child's weight hint as real weights to how much
255 * of its size to allocate for them in each axis. A container is
256 * supposed to, after normalizing the weights of its children (with
257 * weight hints), distribute the space it has to layout them by those
258 * factors – most weighted children get larger in this process than
259 * the least ones.
260
261 * @skipline weight_set
262
263 * @note Default weight hint values are 0.0, for both axis.
264
265 * Now we add the background as a resize_object to win informing that
266 * when the size of the win changes so should the background's
267 * size. And finally we make it visible.
268
269 * @skip win
270 * @until visibility_set
271
272 * @remarks If a color it's not setted the default color will be used.
273
274 * Now we set the size for the window, making it visible in the end.
275
276 * @skip size_set
277 * @until visibility_set
278
279 * Finally we just have to start the elm mainloop, starting to handle
280 * events and drawing operations.
281
282 * @skip elm_run
283 * @until ELM_MAIN
284
285 * The full code for this example can be found at @ref
286 * bg_cxx_example_01.cc .
287
288 * @example bg_cxx_example_01.cc
289*/
290
291/**
292 * @page bg_cxx_example_02 elm::bg - Image background using C++ binding
293 * @dontinclude bg_cxx_example_02.cc
294
295 * This is the second background example and shows how to use the
296 * Elementary background object to set an image as background of your
297 * application.
298
299 * The first part consists of including the headers. In this case we
300 * are only working with the Elementary C++ binding and thus we need
301 * only to include him.
302
303 * @skipline Elementary.hh
304
305 * @attention If necessary the C and/or the C++ headers should be
306 * include here as well.
307
308 * Now we need to actually start the code and set the elm_policy,
309 * which defines for a given policy group/identifier a new policy's
310 * value, respectively. In this example the only policy we need to
311 * set a value for is @c ELM_POLICY_QUIT, possibles values for it are:
312
313 * @li @p ELM_POLICY_QUIT_NONE: Never quit the application
314 * automatically;
315
316 * @li @p ELM_POLICY_QUIT_LAST_WINDOW_CLOSED: quit when the
317 * application's last window is closed;
318
319 * @li @p ELM_POLICY_QUIT_LAST_WINDOW_HIDDEN : quit when the
320 * application's last window is hidden;
321
322 * @skip EAPI_MAIN
323 * @until elm_policy_set
324
325 * As you can see, the policy we chose was to quit when the last win
326 * is hidden as opose to examples with the C bindings where we
327 * perpetually set it to quit when last win was closed. This changed
328 * was necessary because in C++ binding as the elm mainloop stop
329 * running all object are destroyed, references are unreferenced and
330 * events are stopped at ELM_MAIN().
331
332 * @see For more details consult elm_policy_set
333
334 * Next step is creating an Elementary window, where win calls a
335 * constructor and sets the type of the win to ELM_WIN_BASIC
336 * (Elm_Win_Type), which is the indicated type for most of our
337 * examples. Here we also set the title that will appear at the top of
338 * our window and then the autohide state for it.
339
340 * The autohide works similarly to @p autodel, automatically handling
341 * "delete,request" signals when set to @p true, with the difference
342 * that it will hide the window, instead of destroying it.
343
344 * It is specially designed to work together with @p
345 * ELM_POLICY_QUIT_LAST_WINDOW_HIDDEN which allows exiting
346 * Elementary's main loop when all the windows are hidden.
347
348 * @skip ::elm::win
349 * @until autohide_set
350
351 * @note @p autodel and @a autohide are not mutually exclusive. The
352 * window will be destructed if both autodel and autohide is set to @p
353 * EINA_TRUE or @p true.
354
355 * Our background will have an image, that will be displayed over the
356 * background color.
357
358 * To do so, first we set the directory and archive for the image. And
359 * create the background that will display it.
360
361 * @skip elm_app_info_set
362 * @until ::elm::bg
363
364 * Before loading this image, we set the load size of the image. The
365 * load size is a hint about the size that we want the image displayed
366 * in the screen. It's not the exact size that the image will have,
367 * but usually a bit bigger. The background object can still be scaled
368 * to a size bigger than the one set here. Setting the image load size
369 * to something smaller than its real size will reduce the memory used
370 * to keep the pixmap representation of the image, and the time to
371 * load it. Here we set the load size to 20x20 pixels, but the image
372 * is loaded with a size bigger than that (since it's just a hint):
373
374 * @skipline load_size_set
375
376 * And set our background image to be centered, instead of stretched
377 * or scaled, so the effect of the load_size_set() can be easily
378 * understood:
379
380 * @skipline option_set
381
382 * We need a filename to set, so we get one from the previous
383 * installed images in the @c PACKAGE_DATA_DIR, and write its full
384 * path to a std::stringstream. Then we use this stringstream to set
385 * the file name in the background object:
386
387 * @skip std::stringstream
388 * @until file_set
389
390 * Notice that the second argument of the file_set() function is @c
391 * nullptr, since we are setting an image to this background. This
392 * function also supports setting an Eet file as background, in which
393 * case the @c key parameter wouldn't be @c nullptr, but be the name
394 * of the Eet key instead.
395
396 * To better understand, the function @c size_hint_weight_set for C++
397 * bindings originated from C bindings function
398 * evas_object_size_hint_weight_set, that is EFL Evas type function.
399 * With this function we set the hints for an object's weight. The
400 * parameters are:
401
402 * @li x - Nonnegative double value to use as horizontal weight hint.
403
404 * @li y - Nonnegative double value to use as vertical weight hint.
405
406 * This is not a size enforcement in any way, it's just a hint that
407 * should be used whenever appropriate.
408
409 * This is a hint on how a container object should resize a given
410 * child within its area.
411
412 * Containers may adhere to the simpler logic of just expanding the
413 * child object's dimensions to fit its own (see the EVAS_HINT_EXPAND
414 * helper weight macro in the EFL Evas Documentation) or the complete
415 * one of taking each child's weight hint as real weights to how much
416 * of its size to allocate for them in each axis. A container is
417 * supposed to, after normalizing the weights of its children (with
418 * weight hints), distribute the space it has to layout them by those
419 * factors – most weighted children get larger in this process than
420 * the least ones.
421
422 * @skipline weight_set
423
424 * @note Default weight hint values are 0.0, for both axis.
425
426 * Now we add the background as a resize_object to win informing that
427 * when the size of the win changes so should the background's
428 * size. And finally we make background.
429
430 * @skip win
431 * @until visibility
432
433 * Now we only have to set the size for our window and make it
434 * visible.
435
436 * @skip size_set
437 * @until visibility_set
438
439 * Finally we just have to start the elm mainloop, starting to handle
440 * events and drawing operations.
441
442 * @skip elm_run
443 * @until ELM_MAIN
444
445 * The full code for this example can be found at @ref
446 * bg_cxx_example_02.cc .
447
448 * This example will look like this:
449
450 * @image html screenshots/bg_cxx_example_02.png
451 * @image latex screenshots/bg_cxx_example_02.eps width=\textwidth
452 * @example bg_cxx_example_02.cc
453 */
454
455/**
456 * @page bubble_cxx_example_01 elm::bubble - Simple use with C++ binding
457 * @dontinclude bubble_cxx_example_01.cc
458
459 * This example shows a bubble with all fields set - label, info,
460 * content and icon - and the selected corner changing when the bubble
461 * is clicked.
462
463 * The first part consists of including the headers. In this case we
464 * are working with the Elementary and Evas C++ bindings and thus we
465 * need only to include them.
466
467 * @skip Elementary
468 * @untilt Evas
469
470 * @attention If necessary the C and/or the C++ headers should be
471 * include here as well.
472
473 * Now we need to actually start the code and set the elm_policy,
474 * which defines for a given policy group/identifier a new policy's
475 * value, respectively. In this example the only policy we need to
476 * set a value for is @c ELM_POLICY_QUIT, possibles values for it are:
477
478 * @li @p ELM_POLICY_QUIT_NONE: Never quit the application
479 * automatically;
480
481 * @li @p ELM_POLICY_QUIT_LAST_WINDOW_CLOSED: quit when the
482 * application's last window is closed;
483
484 * @li @p ELM_POLICY_QUIT_LAST_WINDOW_HIDDEN : quit when the
485 * application's last window is hidden;
486
487 * @skip EAPI_MAIN
488 * @until elm_policy_set
489
490 * As you can see, the policy we chose was to quit when the last win
491 * is hidden as opose to examples with the C bindings where we
492 * perpetually set it to quit when last win was closed. This changed
493 * was necessary because in C++ binding as the elm mainloop stop
494 * running all object are destroyed, references are unreferenced and
495 * events are stopped at ELM_MAIN().
496
497 * @see For more details consult elm_policy_set
498
499 * Next step is creating an Elementary window, where win calls a
500 * constructor and sets the type of the win to ELM_WIN_BASIC
501 * (Elm_Win_Type), which is the indicated type for most of our
502 * examples. Here we also set the title that will appear at the top of
503 * our window and then the autohide state for it.
504
505 * The autohide works similarly to @p autodel, automatically handling
506 * "delete,request" signals when set to @p true, with the difference
507 * that it will hide the window, instead of destroying it.
508
509 * It is specially designed to work together with @p
510 * ELM_POLICY_QUIT_LAST_WINDOW_HIDDEN which allows exiting
511 * Elementary's main loop when all the windows are hidden.
512
513 * @skip ::elm::win
514 * @until autohide_set
515
516 * @note @p autodel and @a autohide are not mutually exclusive. The
517 * window will be destructed if both autodel and autohide is set to @p
518 * EINA_TRUE or @p true.
519
520 * Now we construct the elm background using the C++ method below,
521 * setting it's parent.
522
523 * @skipline elm::bg
524
525 * To better understand, the function @c size_hint_weight_set for C++
526 * bindings originated from C bindings function
527 * evas_object_size_hint_weight_set, that is EFL Evas type function.
528 * With this function we set the hints for an object's weight.
529
530 * The parameters are:
531
532 * @li x - Nonnegative double value to use as horizontal weight hint.
533
534 * @li y - Nonnegative double value to use as vertical weight hint.
535
536 * This is not a size enforcement in any way, it's just a hint that
537 * should be used whenever appropriate.
538
539 * This is a hint on how a container object should resize a given
540 * child within its area.
541
542 * Containers may adhere to the simpler logic of just expanding the
543 * child object's dimensions to fit its own (see the EVAS_HINT_EXPAND
544 * helper weight macro in the EFL Evas Documentation) or the complete
545 * one of taking each child's weight hint as real weights to how much
546 * of its size to allocate for them in each axis. A container is
547 * supposed to, after normalizing the weights of its children (with
548 * weight hints), distribute the space it has to layout them by those
549 * factors – most weighted children get larger in this process than
550 * the least ones.
551
552 * @skipline weight_set
553
554 * @note Default weight hint values are 0.0, for both axis.
555
556 * Now we add the background as a resize_object to win informing that
557 * when the size of the win changes so should the background's
558 * size. And finally we make it visible.
559
560 * @skip resize
561 * @until visibility_set
562
563 * @note If a color it's not setted the standard color will be used.
564
565 * Here we are creating an elm::label that is going to be used as the
566 * content for our bubble:
567
568 * @skip elm::label
569 * @until visibility_set
570
571 * Despite it's name the bubble's icon in this case it's actually
572 * evas::rectangle, that we set it's color to blue and at the end make
573 * it visible.
574
575 * @skip evas::rectangle
576 * @until visibility_set
577
578 * And finally we have the actual bubble creation and the setting of
579 * it's label, info and content:
580
581 * @skip elm::bubble
582 * @until visibility_set
583
584 * @remark Because we didn't set a corner, the default "top_left" will be used.
585
586 * To have the selected corner change in a clockwise motion we are going to
587 * use the following callback using lambda:
588
589 * @skip auto
590 * @until });
591
592 * @see To learn more about consult @ref lambda.
593
594 * Now that we have our bubble and callback all that is left is adding our
595 * lambda as a clicked callback:
596
597 * @line callback_clicked_add
598
599 * This last bubble we created was very complete, so it's pertinent to show
600 * that most of that stuff is optional a bubble can be created with nothing
601 * but content:
602
603 * @skip label2
604 * @until bubble2.visibility_set
605
606 * Now we only have to set the size for our window and make it
607 * visible.
608
609 * @skip size_set
610 * @until visibility_set
611
612 * And finally, start the elm mainloop, starting to handle events and
613 * drawing operations.
614
615 * @skip elm_run
616 * @until ELM_MAIN
617
618 * Our example will look like this:
619
620 * @image html screenshots/bubble_cxx_example_01.png
621 * @image latex screenshots/bubble_cxx_example_01.eps width=\textwidth
622
623 * @see Full source code @ref bubble_cxx_example_01.cc .
624
625 * @example bubble_cxx_example_01.cc
626 */
627
628/**
629 * @page button_cxx_example_00 Button - Hello, Button!
630 * @dontinclude button_cxx_example_00.cc
631
632 * Keeping the tradition, this is a simple "Hello, World" button
633 * example. We will show how to create a button and associate an
634 * action to be performed when you click on it.
635
636 * The first part consists of including the headers. In this case we
637 * are only working with the Elementary C++ binding and thus we need
638 * only to include him.
639
640 * @skipline Elementary.hh
641
642 * @attention If necessary the C and/or the C++ headers should be
643 * include here as well.
644
645 * Now we need to actually start the code and set the elm_policy,
646 * which defines for a given policy group/identifier a new policy's
647 * value, respectively. In this example the only policy we need to
648 * set a value for is @c ELM_POLICY_QUIT, possibles values for it are:
649
650 * @li @p ELM_POLICY_QUIT_NONE: Never quit the application
651 * automatically;
652
653 * @li @p ELM_POLICY_QUIT_LAST_WINDOW_CLOSED: quit when the
654 * application's last window is closed;
655
656 * @li @p ELM_POLICY_QUIT_LAST_WINDOW_HIDDEN : quit when the
657 * application's last window is hidden;
658
659 * @skip EAPI_MAIN
660 * @until elm_policy_set
661
662 * As you can see, the policy we chose was to quit when the last win
663 * is hidden as opose to examples with the C bindings where we
664 * perpetually set it to quit when last win was closed. This changed
665 * was necessary because in C++ binding as the elm mainloop stop
666 * running all object are destroyed, references are unreferenced and
667 * events are stopped at ELM_MAIN().
668
669 * @see For more details consult elm_policy_set
670
671 * Next step is creating an Elementary window, where win calls a
672 * constructor and sets the type of the win to ELM_WIN_BASIC
673 * (Elm_Win_Type), which is the indicated type for most of our
674 * examples. Here we also set the title that will appear at the top of
675 * our window and then the autohide state for it.
676
677 * The autohide works similarly to @p autodel, automatically handling
678 * "delete,request" signals when set to @p true, with the difference
679 * that it will hide the window, instead of destroying it.
680
681 * It is specially designed to work together with @p
682 * ELM_POLICY_QUIT_LAST_WINDOW_HIDDEN which allows exiting
683 * Elementary's main loop when all the windows are hidden.
684
685 * @skip ::elm::win
686 * @until autohide_set
687
688 * @note @p autodel and @a autohide are not mutually exclusive. The
689 * window will be destructed if both autodel and autohide is set to @p
690 * EINA_TRUE or @p true.
691
692 * Now we construct the elm background and for this we use the C++
693 * method below, setting it's parent.
694
695 * @skipline ::elm::bg
696
697 * The function @c size_hint_weight_set for C++ bindings originated
698 * from C bindings function evas_object_size_hint_weight_set, that is
699 * EFL Evas type function. With this function we set the hints for an
700 * object's weight. The parameters are:
701
702 * @li x - Nonnegative double value to use as horizontal weight hint.
703
704 * @li y - Nonnegative double value to use as vertical weight hint.
705
706 * This is not a size enforcement in any way, it's just a hint that
707 * should be used whenever appropriate. This is a hint on how a
708 * container object should resize a given child within its area.
709
710 * Containers may adhere to the simpler logic of just expanding the
711 * child object's dimensions to fit its own (see the EVAS_HINT_EXPAND
712 * helper weight macro in the EFL Evas Documentation) or the complete
713 * one of taking each child's weight hint as real weights to how much
714 * of its size to allocate for them in each axis. A container is
715 * supposed to, after normalizing the weights of its children (with
716 * weight hints), distribute the space it has to layout them by those
717 * factors – most weighted children get larger in this process than
718 * the least ones.
719
720 * @skipline weight_set
721
722 * @note Default weight hint values are 0.0, for both axis.
723
724 * Now we add the background as a resize_object to win informing that
725 * when the size of the win changes so should the background's
726 * size. And finally we make it visible.
727
728 * @skip win
729 * @until visibility_set
730
731 * @remarks If a color it's not setted the default color will be used.
732
733 * There is only one button on this interface. We need to create this
734 * button with the C++ method, set the text to be displayed, the size,
735 * position and the size hint for weight.
736
737 * @skip btn
738 * @until weight
739
740 * For alignment we'll use the function @c size_hint_align_set for C++
741 * bindings originated from C bindings function
742 * evas_object_size_hint_align_set, that is EFL Evas type
743 * function. With this function we set the hints for an object's
744 * alignment. The parameters are:
745
746 * @li x - Double, ranging from 0.0 to 1.0 or with the special value
747 * EVAS_HINT_FILL, to use as horizontal alignment hint.
748
749 * @li y - Double, ranging from 0.0 to 1.0 or with the special value
750 * EVAS_HINT_FILL, to use as vertical alignment hint.
751
752 * These are hints on how to align an object inside the boundaries of
753 * a container/manager. Accepted values are in the 0.0 to 1.0 range,
754 * with the special value EVAS_HINT_FILL used to specify "justify" or
755 * "fill" by some users. In this case, maximum size hints should be
756 * enforced with higher priority, if they are set. Also, any padding
757 * hint set on objects should add up to the alignment space on the
758 * final scene composition.
759
760 * For the horizontal component, 0.0 means to the left, 1.0 means to
761 * the right. Analogously, for the vertical component, 0.0 to the top,
762 * 1.0 means to the bottom.
763
764 * This is not a size enforcement in any way, it's just a hint that
765 * should be used whenever appropriate.
766
767 * @skipline align
768
769 * @note Default alignment hint values are 0.5, for both axis.
770
771 * Continuing with our button we make it visible.
772
773 * @skipline visibility
774
775 * This button performs a basic action: close the application. This
776 * behavior is described by on_click() which is a lambda function,
777 * that interrupt the program invoking elm_exit(). The lambda function
778 * on_click is the added as a clicked callback to btn.
779
780 * @skip on_click
781 * @until callback
782
783 * @see For more details consult @ref lambda
784
785 * Now we set the size for the window, making it visible in the end:
786
787 * @skip size_set
788 * @until visibility_set
789
790 * Finally we just have to start the elm mainloop, starting to handle
791 * events and drawing operations.
792
793 * @skip elm_run
794 * @until ELM_MAIN
795
796 * The full code for this example can be found at @ref
797 * button_cxx_example_00.cc .
798
799 * This example will look like this:
800 * @image html screenshots/button_cxx_example_00.png
801 * @image latex screenshots/button_cxx_example_00.eps width=\textwidth
802 * @example button_cxx_example_00.cc
803 */
804
805/**
806 * @page button_cxx_example_01 Button - Complete example
807 * @dontinclude button_cxx_example_01.cc
808
809 * A button is simple, you click on it and something happens. That said,
810 * we'll go through an example to show in detail the button API less
811 * commonly used.
812
813 * The first part consists of including the headers. In this case we
814 * are only working with the Elementary C++ binding and thus we need
815 * only to include him.
816
817 * @skipline Elementary.hh
818
819 * @attention If necessary the C and/or the C++ headers should be
820 * include here as well.
821
822 * Now we need to actually start the code and set the elm_policy,
823 * which defines for a given policy group/identifier a new policy's
824 * value, respectively. In this example the only policy we need to
825 * set a value for is @c ELM_POLICY_QUIT, possibles values for it are:
826
827 * @li @p ELM_POLICY_QUIT_NONE: Never quit the application
828 * automatically;
829
830 * @li @p ELM_POLICY_QUIT_LAST_WINDOW_CLOSED: quit when the
831 * application's last window is closed;
832
833 * @li @p ELM_POLICY_QUIT_LAST_WINDOW_HIDDEN : quit when the
834 * application's last window is hidden;
835
836 * @skip EAPI_MAIN
837 * @until elm_policy_set
838
839 * As you can see, the policy we chose was to quit when the last win
840 * is hidden as opose to examples with the C bindings where we
841 * perpetually set it to quit when last win was closed. This changed
842 * was necessary because in C++ binding as the elm mainloop stop
843 * running all object are destroyed, references are unreferenced and
844 * events are stopped at ELM_MAIN().
845
846 * @see For more details consult elm_policy_set
847
848 * Next step is creating an Elementary window, in this example we use
849 * the C++ binding method with the elm_win_util_standard_add that is a
850 * elm_win_legacy function, better explained below. And then we set
851 * the autohide state for it.
852
853 * @p elm_win_util_standard_add (const char *name, const char *tittle)
854 * Adds a window object with standard setup.
855 * Parameters:
856
857 * @li @p name - The name of the window;
858
859 * @li @p title - The title for the window.
860
861 * This creates a window but also puts in a standard background with
862 * @p elm_bg_add(), as well as setting the window title to @p
863 * title. The window type created is of type @c ELM_WIN_BASIC, with
864 * the @c NULL as the parent widget. Returns the created object or @c
865 * NULL on failure.
866
867 * The autohide works similarly to @p autodel, automatically handling
868 * "delete,request" signals when set to @p true, with the difference
869 * that it will hide the window, instead of destroying it.
870
871 * It is specially designed to work together with @p
872 * ELM_POLICY_QUIT_LAST_WINDOW_HIDDEN which allows exiting
873 * Elementary's main loop when all the windows are hidden.
874
875 * @skip ::elm::win
876 * @until autohide_set
877
878 * @note @p autodel and @a autohide are not mutually exclusive. The
879 * window will be destructed if both autodel and autohide is set to @p
880 * EINA_TRUE or @p true.
881
882 * In this example we'll have several buttons that will be arranged in
883 * two boxes that will be inserted in a bigger box. One of the smaller
884 * boxes will contain a set of buttons that will set different times
885 * for the autorepeat timeouts of the buttons that will be contained in
886 * the other smaller box.
887
888 * For all this to work, we will construct the three smaller boxes and
889 * all the button that will be needed. The smaller boxes will be then
890 * packed in the bigger one.
891
892 * In this part we'll create our directional buttons, that we'll be
893 * added in the third smaller box, this is necessary for our callback
894 * to work properly.
895
896 * @skip icon
897 * @until right
898
899 * Now let's create our bigger box using the C++ method and setting
900 * it's parent as win.
901
902 * @skipline box
903
904 * The function @c size_hint_weight_set for C++ bindings originated
905 * from C bindings function evas_object_size_hint_weight_set, that is
906 * EFL Evas type function. With this function we set the hints for an
907 * object's weight. The parameters are:
908
909 * @li x - Nonnegative double value to use as horizontal weight hint.
910
911 * @li y - Nonnegative double value to use as vertical weight hint.
912
913 * This is not a size enforcement in any way, it's just a hint that
914 * should be used whenever appropriate. This is a hint on how a
915 * container object should resize a given child within its area.
916
917 * Containers may adhere to the simpler logic of just expanding the
918 * child object's dimensions to fit its own (see the EVAS_HINT_EXPAND
919 * helper weight macro in the EFL Evas Documentation) or the complete
920 * one of taking each child's weight hint as real weights to how much
921 * of its size to allocate for them in each axis. A container is
922 * supposed to, after normalizing the weights of its children (with
923 * weight hints), distribute the space it has to layout them by those
924 * factors – most weighted children get larger in this process than
925 * the least ones.
926
927 * @skipline weight_set
928
929 * @note Default weight hint values are 0.0, for both axis.
930
931 * Now we add the box as a resize_object to win informing that when
932 * the size of the win changes so should the box's size. And finally
933 * we make it visible.
934
935 * @skip win
936 * @until visibility_set
937
938 * Creating our initial box, again using the C++ method, in this case
939 * we want the arrangement of the objects, that this box will contain,
940 * to be displayed horizontally and fot this we will set horizontal to
941 * @p true, vertical by default.
942
943 * @skip box
944 * @until horizontal
945
946 * Again we'll set the size hint for weight, but in this box we will
947 * set the packing method to include this box inside the bigger one.
948
949 * When using the elm box the packing method of the subobj - box in
950 * this case - should be defined. There are four possible methods:
951
952 * @li @c pack_start(subobj_) - Add an object to the beginning of the
953 * pack list. Pack @c subobj_ into the box obj, placing it first in
954 * the list of children objects. The actual position the object will
955 * get on screen depends on the layout used. If no custom layout is
956 * set, it will be at the top or left, depending if the box is
957 * vertical or horizontal, respectively.
958
959 * @li @c pack_end(subobj_) - Add an object at the end of the pack
960 * list. Pack @c subobj_ into the box obj, placing it last in the list
961 * of children objects. The actual position the object will get on
962 * screen depends on the layout used. If no custom layout is set, it
963 * will be at the bottom or right, depending if the box is vertical or
964 * horizontal, respectively.
965
966 * @li @c pack_before(subobj_, before_) - Adds an object to the box
967 * before the indicated object. This will add the @c subobj_ to the
968 * box indicated before the object indicated with @c before_. If
969 * before is not already in the box, results are undefined. Before
970 * means either to the left of the indicated object or above it
971 * depending on orientation.
972
973 * @li @c pack_after(subobj_, after_) - Adds an object to the box
974 * after the indicated object. This will add the @c subobj_ to the box
975 * indicated after the object indicated with @c after_. If after is
976 * not already in the box, results are undefined. After means either
977 * to the right of the indicated object or below it depending on
978 * orientation.
979
980 * In this and most examples we use pack_end by choice and
981 * practicality. In this part of the code we also make calendar
982 * visible.
983
984 * @skip pack_end
985 * @until visibility
986
987 * Now let's start creating the buttons that will be included in this
988 * first small box, this will contain the initial timeout button.
989
990 * We'll use again the C++ method to create this button, set a text,
991 * packing method for btn and finally make it visible.
992
993 * @skip btn
994 * @until visibility
995
996 * In this part we'll use Lambda type function that will be added in
997 * the clicked callback for all buttons in the first smaller box,
998 * that'll identify the current initial and gap to be use in the
999 * autorepeat timeout that will move the central button.
1000
1001 * @skip auto
1002 * @until callback
1003
1004 * @note To learn more about Lambda Function and its use in Elementary
1005 * consult @ref lambda.
1006
1007 * The second and third button will also set the initial timeout but
1008 * with different values.
1009
1010 * @skip btn2
1011 * @until btn3.callback
1012
1013 * Now for our gap timeout buttons will create our second smaller box,
1014 * the same way with the initial box, we'll use the C++ method, set to
1015 * be horizontal, set the size hint weight, choose the packing method
1016 * and set the visibility to true.
1017
1018 * @skip box_gap
1019 * @until visibility
1020
1021 * For our gap buttons we'll again, use the C++ method, set the texts
1022 * with the different values for gap, choose the packing method, set
1023 * the visibility and the clicked callback.
1024
1025 * @skip btn4
1026 * @until btn6.callback
1027
1028 * Now we'll give our directional buttons more options so that it will
1029 * visible and also have all the caracteristics that is require.
1030
1031 * For the up button, we'll set to @p true the autorepeat,
1032 * autorepeat_initial_timeout, autoreapet_gap_timeout, the size hints
1033 * for weight and alignement, choose our packing method and making out
1034 * up button visible.
1035
1036 * @skip up
1037 * @until visibility
1038
1039 * For this directional buttons we'll have a diferent repeated
1040 * callback that will insure the timeouts of our middle button in the
1041 * gap and initial timeout that is current setted.
1042
1043 * @skip auto
1044 * @until
1045
1046 * For our second callback, we'll detail the release of our
1047 * directional buttons.
1048
1049 * @skip auto
1050 * @until callback
1051
1052 * Finishing our up button, we'll create an icon, that'll will be the
1053 * standard "arrow_up".
1054
1055 * @skip icon
1056 * @until content
1057
1058 * This last box, will content all the directional buttons and the
1059 * middle button. As before, we use the C++ method, horizontal set,
1060 * weight and align hints, chose the packing method and make it
1061 * visible.
1062
1063 * @skip box
1064 * @until visibility
1065
1066 * Now we'll create all the directional and middle buttons, the same as we did with the up button,
1067 * changing only the icon.
1068
1069 * @skip left
1070 * @until down.content
1071
1072 * Now we set the size for the window, making it visible in the end:
1073
1074 * @skip size_set
1075 * @until visibility_set
1076
1077 * Finally we just have to start the elm mainloop, starting to handle
1078 * events and drawing operations.
1079
1080 * @skip elm_run
1081 * @until ELM_MAIN
1082
1083 * The full code for this example can be found at @ref
1084 * button_cxx_example_01.cc .
1085
1086 * This example will look like this:
1087 * @image html screenshots/button_cxx_example_01.png
1088 * @image latex screenshots/button_cxx_example_01.eps width=\textwidth
1089 * @example button_cxx_example_01.cc
1090 */
1091
1092/**
1093 * @page calendar_cxx_example_01 Calendar - Simple creation with C++ binding
1094 * @dontinclude calendar_cxx_example_01.cc
1095
1096 * As a first example, let's just display a calendar in our window,
1097 * explaining all steps required to do so.
1098
1099 * The first part consists of including the headers. In this case we
1100 * are only working with the Elementary C++ binding and thus we need
1101 * only to include him.
1102
1103 * @skipline Elementary.hh
1104
1105 * @attention If necessary the C and/or the C++ headers should be
1106 * include here as well.
1107
1108 * Now we need to actually start the code and set the elm_policy,
1109 * which defines for a given policy group/identifier a new policy's
1110 * value, respectively. In this example the only policy we need to
1111 * set a value for is @c ELM_POLICY_QUIT, possibles values for it are:
1112
1113 * @li @p ELM_POLICY_QUIT_NONE: Never quit the application
1114 * automatically;
1115
1116 * @li @p ELM_POLICY_QUIT_LAST_WINDOW_CLOSED: quit when the
1117 * application's last window is closed;
1118
1119 * @li @p ELM_POLICY_QUIT_LAST_WINDOW_HIDDEN : quit when the
1120 * application's last window is hidden;
1121
1122 * @skip EAPI_MAIN
1123 * @until elm_policy_set
1124
1125 * As you can see, the policy we chose was to quit when the last win
1126 * is hidden as opose to examples with the C bindings where we
1127 * perpetually set it to quit when last win was closed. This changed
1128 * was necessary because in C++ binding as the elm mainloop stop
1129 * running all object are destroyed, references are unreferenced and
1130 * events are stopped at ELM_MAIN().
1131
1132 * @see For more details consult elm_policy_set
1133
1134 * Next step is creating an Elementary window, in this example we use
1135 * the C++ binding method with the elm_win_util_standard_add that is a
1136 * elm_win_legacy function, better explained below. And then we set
1137 * the autohide state for it.
1138
1139 * @p elm_win_util_standard_add (const char *name, const char *tittle)
1140 * Adds a window object with standard setup.
1141 * Parameters:
1142
1143 * @li @p name - The name of the window;
1144
1145 * @li @p title - The title for the window.
1146
1147 * This creates a window but also puts in a standard background with
1148 * @p elm_bg_add(), as well as setting the window title to @p
1149 * title. The window type created is of type @c ELM_WIN_BASIC, with
1150 * the @c NULL as the parent widget. Returns the created object or @c
1151 * NULL on failure.
1152
1153 * The autohide works similarly to @p autodel, automatically handling
1154 * "delete,request" signals when set to @p true, with the difference
1155 * that it will hide the window, instead of destroying it.
1156
1157 * It is specially designed to work together with @p
1158 * ELM_POLICY_QUIT_LAST_WINDOW_HIDDEN which allows exiting
1159 * Elementary's main loop when all the windows are hidden.
1160
1161 * @skip ::elm::win
1162 * @until autohide_set
1163
1164 * @note @p autodel and @a autohide are not mutually exclusive. The
1165 * window will be destructed if both autodel and autohide is set to @p
1166 * EINA_TRUE or @p true.
1167
1168 * Now, the exciting part, let's create the calendar with the C++
1169 * binding method, passing our window object as parent.
1170
1171 * @skipline elm::calendar
1172
1173 * The function @c size_hint_weight_set for C++ bindings originated
1174 * from C bindings function evas_object_size_hint_weight_set, that is
1175 * EFL Evas type function. With this function we set the hints for an
1176 * object's weight. The parameters are:
1177
1178 * @li x - Nonnegative double value to use as horizontal weight hint.
1179
1180 * @li y - Nonnegative double value to use as vertical weight hint.
1181
1182 * This is not a size enforcement in any way, it's just a hint that
1183 * should be used whenever appropriate. This is a hint on how a
1184 * container object should resize a given child within its area.
1185
1186 * Containers may adhere to the simpler logic of just expanding the
1187 * child object's dimensions to fit its own (see the EVAS_HINT_EXPAND
1188 * helper weight macro in the EFL Evas Documentation) or the complete
1189 * one of taking each child's weight hint as real weights to how much
1190 * of its size to allocate for them in each axis. A container is
1191 * supposed to, after normalizing the weights of its children (with
1192 * weight hints), distribute the space it has to layout them by those
1193 * factors – most weighted children get larger in this process than
1194 * the least ones.
1195
1196 * @skipline weight_set
1197
1198 * @note Default weight hint values are 0.0, for both axis.
1199
1200 * Now we add the calendar as a resize-object to win informing that
1201 * when the size of the win changes so should the calendar's
1202 * size. And finally we make it visible.
1203
1204 * @skip win
1205 * @until visibility
1206
1207 * Finally we just have to start the elm mainloop, starting to handle
1208 * events and drawing operations.
1209
1210 * @skip elm_run
1211 * @until ELM_MAIN
1212
1213 * Our example will look like this:
1214
1215 * @image html screenshots/calendar_cxx_example_01.png
1216
1217 * @image latex screenshots/calendar_cxx_example_01.eps width=\textwidth
1218
1219 * See the full source code @ref calendar_cxx_example_01.cc here.
1220
1221 * @example calendar_cxx_example_01.cc
1222 */
1223
1224/**
1225 * @page calendar_cxx_example_02 Calendar - Layout strings formatting with C++ binding
1226 * @dontinclude calendar_cxx_example_02.cc
1227
1228 * In this simple example, we'll explain how to format the labels
1229 * displaying month and year, and also set weekday names.
1230
1231 * The first part consists of including the headers. In this case we
1232 * are only working with the Elementary C++ binding and thus we need
1233 * only to include him.
1234
1235 * @skipline Elementary.hh
1236
1237 * @attention If necessary the C and/or the C++ headers should be
1238 * include here as well.
1239
1240 * Now we will jump to the actual code and later explain the function
1241 * to make this tutorial more didactical.
1242
1243 * We must set the elm_policy, which defines for a given policy
1244 * group/identifier a new policy's value, respectively. In this
1245 * example the only policy we need to set a value for is @c
1246 * ELM_POLICY_QUIT, possibles values for it are:
1247
1248 * @li @p ELM_POLICY_QUIT_NONE: Never quit the application
1249 * automatically;
1250
1251 * @li @p ELM_POLICY_QUIT_LAST_WINDOW_CLOSED: quit when the
1252 * application's last window is closed;
1253
1254 * @li @p ELM_POLICY_QUIT_LAST_WINDOW_HIDDEN : quit when the
1255 * application's last window is hidden;
1256
1257 * @skip EAPI_MAIN
1258 * @until elm_policy_set
1259
1260 * As you can see, the policy we chose was to quit when the last win
1261 * is hidden as opose to examples with the C bindings where we
1262 * perpetually set it to quit when last win was closed. This changed
1263 * was necessary because in C++ binding as the elm mainloop stop
1264 * running all object are destroyed, references are unreferenced and
1265 * events are stopped at ELM_MAIN().
1266
1267 * @see For more details consult elm_policy_set
1268
1269 * Next step is creating an Elementary window, in this example we use
1270 * the C++ binding method with the elm_win_util_standard_add that is a
1271 * elm_win_legacy function, better explained below. And then we set
1272 * the autohide state for it.
1273
1274 * @p elm_win_util_standard_add (const char *name, const char *tittle)
1275 * Adds a window object with standard setup.
1276 * Parameters:
1277
1278 * @li @p name - The name of the window;
1279
1280 * @li @p title - The title for the window.
1281
1282 * This creates a window but also puts in a standard background with
1283 * @p elm_bg_add(), as well as setting the window title to @p
1284 * title. The window type created is of type @c ELM_WIN_BASIC, with
1285 * the @c NULL as the parent widget. Returns the created object or @c
1286 * NULL on failure.
1287
1288 * The autohide works similarly to @p autodel, automatically handling
1289 * "delete,request" signals when set to @p true, with the difference
1290 * that it will hide the window, instead of destroying it.
1291
1292 * It is specially designed to work together with @p
1293 * ELM_POLICY_QUIT_LAST_WINDOW_HIDDEN which allows exiting
1294 * Elementary's main loop when all the windows are hidden.
1295
1296 * @skip ::elm::win
1297 * @until autohide_set
1298
1299 * @note @p autodel and @a autohide are not mutually exclusive. The
1300 * window will be destructed if both autodel and autohide is set to @p
1301 * EINA_TRUE or @p true.
1302
1303 * Now let's create the calendar with the C++ binding method, passing
1304 * our window object as parent.
1305
1306 * @skipline elm::calendar
1307
1308 * The function @c size_hint_weight_set for C++ bindings originated
1309 * from C bindings function evas_object_size_hint_weight_set, that is
1310 * EFL Evas type function. With this function we set the hints for an
1311 * object's weight. The parameters are:
1312
1313 * @li x - Nonnegative double value to use as horizontal weight hint.
1314
1315 * @li y - Nonnegative double value to use as vertical weight hint.
1316
1317 * This is not a size enforcement in any way, it's just a hint that
1318 * should be used whenever appropriate. This is a hint on how a
1319 * container object should resize a given child within its area.
1320
1321 * Containers may adhere to the simpler logic of just expanding the
1322 * child object's dimensions to fit its own (see the EVAS_HINT_EXPAND
1323 * helper weight macro in the EFL Evas Documentation) or the complete
1324 * one of taking each child's weight hint as real weights to how much
1325 * of its size to allocate for them in each axis. A container is
1326 * supposed to, after normalizing the weights of its children (with
1327 * weight hints), distribute the space it has to layout them by those
1328 * factors – most weighted children get larger in this process than
1329 * the least ones.
1330
1331 * @skipline weight_set
1332
1333 * @note Default weight hint values are 0.0, for both axis.
1334
1335 * Now we add the calendar as a resize-object to win informing that
1336 * when the size of the win changes so should the calendar's
1337 * size.
1338
1339 * @skipline win
1340
1341 * To format month and year labels, we need to create a callback
1342 * function to create a string given the selected time, declared under
1343 * a <tt> struct tm </tt>.
1344
1345 * <tt> struct tm </tt>, declared on @c time.h, is a structure
1346 * composed by nine integers:
1347
1348 * @li <tt> tm_sec seconds [0,59] </tt>
1349 * @li <tt> tm_min minutes [0,59] </tt>
1350 * @li <tt> tm_hour hour [0,23] </tt>
1351 * @li <tt> tm_mday day of month [1,31] </tt>
1352 * @li <tt> tm_mon month of year [0,11] </tt>
1353 * @li <tt> tm_year years since 1900 </tt>
1354 * @li <tt> tm_wday day of week [0,6] (Sunday = 0) </tt>
1355 * @li <tt> tm_yday day of year [0,365] </tt>
1356 * @li <tt> tm_isdst daylight savings flag </tt>
1357
1358 * @note Glib version has 2 additional fields.
1359
1360 * For our function @p _format_month_year , only stuff that matters
1361 * are <tt>tm_mon</tt> and <tt>tm_year</tt>. But we don't need to
1362 * access it directly, since there are nice functions to format date
1363 * and time, as @c strftime.
1364
1365 * We will get abbreviated month (%b) and year (%y) (check strftime
1366 * manpage for more) in our example:
1367
1368 * @dontinclude calendar_cxx_example_02.cc
1369 * @skip static char
1370 * @until }
1371
1372 * We need to alloc the string to be returned, and calendar widget
1373 * will free it when it's not needed, what is done by @c strdup.
1374
1375 * So let's register our callback to calendar object:
1376
1377 * @skipline format_function_set
1378
1379 * To set weekday names, we should declare them as an array of
1380 * strings:
1381
1382 * @dontinclude calendar_cxx_example_02.cc
1383 * @skip weekdays[]
1384 * @until }
1385
1386 * And then set them to calendar:
1387 * @skipline weekdays_names_set
1388
1389 * Finally we just have to make the calendar and window visible and
1390 * then start the elm mainloop, starting to handle events and drawing
1391 * operations.
1392
1393 * @skip visibility
1394 * @until ELM_MAIN
1395
1396 * Our example will look like this:
1397
1398 * @image html screenshots/calendar_cxx_example_02.png
1399 * @image latex screenshots/calendar_cxx_example_02.eps width=\textwidth
1400
1401 * See the full source code @ref calendar_cxx_example_02.cc here.
1402 * @example calendar_cxx_example_02.cc
1403 */
1404
1405/**
1406 * @page calendar_cxx_example_03 Calendar - Years restrictions with C++ binding
1407 * @dontinclude calendar_cxx_example_03.cc
1408
1409 * This example explains how to set max and min year to be displayed
1410 * by a calendar object. This means that user won't be able to see or
1411 * select a date before and after selected years. By default, limits
1412 * are 1902 and maximum value will depends on platform architecture
1413 * (year 2037 for 32 bits); You can read more about time functions on
1414 * @c ctime manpage.
1415
1416 * The first part consists of including the headers. In this case we
1417 * are only working with the Elementary C++ binding and thus we need
1418 * only to include him.
1419
1420 * @skipline Elementary.hh
1421
1422 * @attention If necessary the C and/or the C++ headers should be
1423 * include here as well.
1424
1425 * Now we need to actually start the code and set the elm_policy,
1426 * which defines for a given policy group/identifier a new policy's
1427 * value, respectively. In this example the only policy we need to set
1428 * a value for is @c ELM_POLICY_QUIT, possibles values for it are:
1429 * function to make this tutorial more didactical.
1430
1431 * @li @p ELM_POLICY_QUIT_NONE: Never quit the application
1432 * automatically;
1433
1434 * @li @p ELM_POLICY_QUIT_LAST_WINDOW_CLOSED: quit when the
1435 * application's last window is closed;
1436
1437 * @li @p ELM_POLICY_QUIT_LAST_WINDOW_HIDDEN : quit when the
1438 * application's last window is hidden;
1439
1440 * @skip EAPI_MAIN
1441 * @until elm_policy_set
1442
1443 * As you can see, the policy we chose was to quit when the last win
1444 * is hidden as opose to examples with the C bindings where we
1445 * perpetually set it to quit when last win was closed. This changed
1446 * was necessary because in C++ binding as the elm mainloop stop
1447 * running all object are destroyed, references are unreferenced and
1448 * events are stopped at ELM_MAIN().
1449
1450 * @see For more details consult elm_policy_set
1451
1452 * Next step is creating an elementary window, in this example we use
1453 * the C++ binding method with the elm_win_util_standard_add that is a
1454 * elm_win_legacy function, better explained below. And then we set
1455 * the autohide state for it.
1456
1457 * @p elm_win_util_standard_add (const char *name, const char *tittle)
1458 * Adds a window object with standard setup.
1459 * Parameters:
1460
1461 * @li @p name - The name of the window;
1462
1463 * @li @p title - The title for the window.
1464
1465 * This creates a window but also puts in a standard background with
1466 * @p elm_bg_add(), as well as setting the window title to @p
1467 * title. The window type created is of type @c ELM_WIN_BASIC, with
1468 * the @c NULL as the parent widget. Returns the created object or @c
1469 * NULL on failure.
1470
1471 * The autohide works similarly to @p autodel, automatically handling
1472 * "delete,request" signals when set to @p true, with the difference
1473 * that it will hide the window, instead of destroying it.
1474
1475 * It is specially designed to work together with @p
1476 * ELM_POLICY_QUIT_LAST_WINDOW_HIDDEN which allows exiting
1477 * Elementary's main loop when all the windows are hidden.
1478
1479 * @skip ::elm::win
1480 * @until autohide_set
1481
1482 * @note @p autodel and @a autohide are not mutually exclusive. The
1483 * window will be destructed if both autodel and autohide is set to @p
1484 * EINA_TRUE or @p true.
1485
1486 * Now let's create the calendar with the C++ binding method, passing
1487 * our window object as parent.
1488
1489 * @skipline elm::calendar
1490
1491 * The function @c size_hint_weight_set for C++ bindings originated
1492 * from C bindings function evas_object_size_hint_weight_set, that is
1493 * EFL Evas type function. With this function we set the hints for an
1494 * object's weight. The parameters are:
1495
1496 * @li x - Nonnegative double value to use as horizontal weight hint.
1497
1498 * @li y - Nonnegative double value to use as vertical weight hint.
1499
1500 * This is not a size enforcement in any way, it's just a hint that
1501 * should be used whenever appropriate. This is a hint on how a
1502 * container object should resize a given child within its area.
1503
1504 * Containers may adhere to the simpler logic of just expanding the
1505 * child object's dimensions to fit its own (see the EVAS_HINT_EXPAND
1506 * helper weight macro in the EFL Evas Documentation) or the complete
1507 * one of taking each child's weight hint as real weights to how much
1508 * of its size to allocate for them in each axis. A container is
1509 * supposed to, after normalizing the weights of its children (with
1510 * weight hints), distribute the space it has to layout them by those
1511 * factors – most weighted children get larger in this process than
1512 * the least ones.
1513
1514 * @skipline weight_set
1515
1516 * @note Default weight hint values are 0.0, for both axis.
1517
1518 * Now we add the calendar as a resize-object to win informing that
1519 * when the size of the win changes so should the calendar's
1520 * size.
1521
1522 * @skipline win
1523
1524 * Straigh to the point, to set it is enough to call
1525 * min_max_year_set(). First value is minimum year, second is
1526 * maximum. If first value is negative, it won't apply limit for min
1527 * year, if the second one is negative, won't apply for max year.
1528 * Setting both to negative value will clear limits (default state):
1529
1530 * @skipline min_max_year_set
1531
1532 * Finally we just have to make the calendar and window visible and
1533 * then start the elm mainloop, starting to handle events and drawing
1534 * operations.
1535
1536 * @skip visibility
1537 * @until ELM_MAIN
1538
1539 * Our example will look like this:
1540
1541 * @image html screenshots/calendar_cxx_example_03.png
1542 * @image latex screenshots/calendar_cxx_example_03.eps width=\textwidth
1543
1544 * See the full source code @ref calendar_cxx_example_03.cc here.
1545
1546 * @example calendar_cxx_example_03.cc
1547 */
1548
1549/**
1550 * @page calendar_cxx_example_04 Calendar - Days selection with C++ binding.
1551 * @dontinclude calendar_cxx_example_04.cc
1552
1553 * It's possible to disable date selection and to select a date
1554 * from your program, and that's what we'll see on this example.
1555
1556 * The first part consists of including the headers. In this case we
1557 * are only working with the Elementary C++ binding and thus we need
1558 * only to include him.
1559
1560 * @skipline Elementary.hh
1561
1562 * @attention If necessary the C and/or the C++ headers should be
1563 * include here as well.
1564
1565 * Now we need to actually start the code and set the elm_policy,
1566 * which defines for a given policy group/identifier a new policy's
1567 * value, respectively. In this example the only policy we need to set
1568 * a value for is @c ELM_POLICY_QUIT, possibles values for it are:
1569
1570 * @li @p ELM_POLICY_QUIT_NONE: Never quit the application
1571 * automatically;
1572
1573 * @li @p ELM_POLICY_QUIT_LAST_WINDOW_CLOSED: quit when the
1574 * application's last window is closed;
1575
1576 * @li @p ELM_POLICY_QUIT_LAST_WINDOW_HIDDEN : quit when the
1577 * application's last window is hidden;
1578
1579 * @skip EAPI_MAIN
1580 * @until elm_policy_set
1581
1582 * As you can see, the policy we chose was to quit when the last win
1583 * is hidden as opose to examples with the C bindings where we
1584 * perpetually set it to quit when last win was closed. This changed
1585 * was necessary because in C++ binding as the elm mainloop stop
1586 * running all object are destroyed, references are unreferenced and
1587 * events are stopped at ELM_MAIN().
1588
1589 * @see For more details consult elm_policy_set
1590
1591 * Next step is creating an elementary window, in this example we use
1592 * the C++ binding method with the elm_win_util_standard_add that is a
1593 * elm_win_legacy function, better explained below. And then we set
1594 * the autohide state for it.
1595
1596 * @p elm_win_util_standard_add (const char *name, const char *tittle)
1597 * Adds a window object with standard setup.
1598 * Parameters:
1599
1600 * @li @p name - The name of the window;
1601
1602 * @li @p title - The title for the window.
1603
1604 * This creates a window but also puts in a standard background with
1605 * @p elm_bg_add(), as well as setting the window title to @p
1606 * title. The window type created is of type @c ELM_WIN_BASIC, with
1607 * the @c NULL as the parent widget. Returns the created object or @c
1608 * NULL on failure.
1609
1610 * The autohide works similarly to @p autodel, automatically handling
1611 * "delete,request" signals when set to @p true, with the difference
1612 * that it will hide the window, instead of destroying it.
1613
1614 * It is specially designed to work together with @p
1615 * ELM_POLICY_QUIT_LAST_WINDOW_HIDDEN which allows exiting
1616 * Elementary's main loop when all the windows are hidden.
1617
1618 * @skip ::elm::win
1619 * @until autohide_set
1620
1621 * @note @p autodel and @a autohide are not mutually exclusive. The
1622 * window will be destructed if both autodel and autohide is set to @p
1623 * EINA_TRUE or @p true.
1624
1625 * In this example we'll need to use a elm::box to layout the two
1626 * calendars that'll be created. A box arranges objects in a linear
1627 * fashion, governed by a layout function that defines the details of
1628 * this arrangement. The box will use an internal function
1629 * to set the layout to a single row, vertical by default.
1630
1631 * Now let's create the box with the C++ binding method, passing
1632 * our window object as parent.
1633
1634 * @skipline elm::box
1635
1636 * The function @c size_hint_weight_set for C++ bindings originated
1637 * from C bindings function evas_object_size_hint_weight_set, that is
1638 * EFL Evas type function. With this function we set the hints for an
1639 * object's weight. The parameters are:
1640
1641 * @li x - Nonnegative double value to use as horizontal weight hint.
1642
1643 * @li y - Nonnegative double value to use as vertical weight hint.
1644
1645 * This is not a size enforcement in any way, it's just a hint that
1646 * should be used whenever appropriate. This is a hint on how a
1647 * container object should resize a given child within its area.
1648
1649 * Containers may adhere to the simpler logic of just expanding the
1650 * child object's dimensions to fit its own (see the EVAS_HINT_EXPAND
1651 * helper weight macro in the EFL Evas Documentation) or the complete
1652 * one of taking each child's weight hint as real weights to how much
1653 * of its size to allocate for them in each axis. A container is
1654 * supposed to, after normalizing the weights of its children (with
1655 * weight hints), distribute the space it has to layout them by those
1656 * factors – most weighted children get larger in this process than
1657 * the least ones.
1658
1659 * @skipline weight_set
1660
1661 * @note Default weight hint values are 0.0, for both axis.
1662
1663 * Now we add the box as a resize-object to win informing that when
1664 * the size of the win changes so should the box's size. Remember
1665 * always to set the box visibility to true.
1666
1667 * @skip win
1668 * @until visibility
1669
1670 * Now let's create the calendar with the C++ binding method, passing
1671 * our window object as parent. The function size_hint_weight_set
1672 * works with calendar the same way as with box, for more, search
1673 * above.
1674
1675 * @skip elm::calendar
1676 * @until weight_set
1677
1678 * The function @c size_hint_align_set for C++ bindings originated
1679 * from C bindings function evas_object_size_hint_align_set, that is
1680 * EFL Evas type function. With this function we set the hints for an
1681 * object's alignment. The parameters are:
1682
1683 * @li x - Double, ranging from 0.0 to 1.0 or with the special value
1684 * EVAS_HINT_FILL, to use as horizontal alignment hint.
1685
1686 * @li y - Double, ranging from 0.0 to 1.0 or with the special value
1687 * EVAS_HINT_FILL, to use as vertical alignment hint.
1688
1689 * These are hints on how to align an object inside the boundaries of
1690 * a container/manager. Accepted values are in the 0.0 to 1.0 range,
1691 * with the special value EVAS_HINT_FILL used to specify "justify" or
1692 * "fill" by some users. In this case, maximum size hints should be
1693 * enforced with higher priority, if they are set. Also, any padding
1694 * hint set on objects should add up to the alignment space on the
1695 * final scene composition.
1696
1697 * For the horizontal component, 0.0 means to the left, 1.0 means to
1698 * the right. Analogously, for the vertical component, 0.0 to the top,
1699 * 1.0 means to the bottom.
1700
1701 * This is not a size enforcement in any way, it's just a hint that
1702 * should be used whenever appropriate.
1703
1704 * @note Default alignment hint values are 0.5, for both axis.
1705
1706 * @skipline align_set
1707
1708 * If isn't required that users could select a day on calendar, only
1709 * interacting going through months, disabling days selection could be
1710 * a good idea to avoid confusion. For that:
1711
1712 * @skipline select_mode_set
1713
1714 * When using the elm box the packing method of the subobj - calendar
1715 * in this case - should be defined. There are four possible methods:
1716
1717 * @li @c pack_start(subobj_) - Add an object to the beginning of the
1718 * pack list. Pack @c subobj_ into the box obj, placing it first in
1719 * the list of children objects. The actual position the object will
1720 * get on screen depends on the layout used. If no custom layout is
1721 * set, it will be at the top or left, depending if the box is
1722 * vertical or horizontal, respectively.
1723
1724 * @li @c pack_end(subobj_) - Add an object at the end of the pack
1725 * list. Pack @c subobj_ into the box obj, placing it last in the list
1726 * of children objects. The actual position the object will get on
1727 * screen depends on the layout used. If no custom layout is set, it
1728 * will be at the bottom or right, depending if the box is vertical or
1729 * horizontal, respectively.
1730
1731 * @li @c pack_before(subobj_, before_) - Adds an object to the box
1732 * before the indicated object. This will add the @c subobj_ to the
1733 * box indicated before the object indicated with @c before_. If
1734 * before is not already in the box, results are undefined. Before
1735 * means either to the left of the indicated object or above it
1736 * depending on orientation.
1737
1738 * @li @c pack_after(subobj_, after_) - Adds an object to the box
1739 * after the indicated object. This will add the @c subobj_ to the box
1740 * indicated after the object indicated with @c after_. If after is
1741 * not already in the box, results are undefined. After means either
1742 * to the right of the indicated object or below it depending on
1743 * orientation.
1744
1745 * In this and most examples we use pack_end by choice and
1746 * practicality. In this part of the code we also make calendar
1747 * visible.
1748
1749 * @skip visibility
1750 * @until pack_end
1751
1752 * Also, regarding days selection, you could be interested to set a
1753 * date to be highlighted on calendar from your code, maybe when a
1754 * specific event happens or after calendar creation. As @c time
1755 * output is in seconds, we define the number of seconds contained
1756 * within a day as a constant:
1757
1758 * @dontinclude calendar_cxx_example_04.cc
1759 * @skipline SECS_DAY
1760
1761 * As with the first calendar, we'll also construct cal2, set it's
1762 * hint_weight and hint_align, make cal2 visible and choose the
1763 * packing method.
1764
1765 * @skip cal2
1766 * @until weight
1767 * @skip visibility
1768 * @until pack
1769
1770 * Now let's select two days from current day:
1771
1772 * @dontinclude calendar_cxx_example_04.cc
1773 * @skip time(NULL)
1774 * @until selected_time_set
1775
1776 * Finally we just have to make window visible and then start the elm
1777 * mainloop, starting to handle events and drawing operations.
1778
1779 * @skip visibility
1780 * @until ELM_MAIN
1781
1782 * Our example will look like this:
1783
1784 * @image html screenshots/calendar_cxx_example_04.png
1785 * @image latex screenshots/calendar_cxx_example_04.eps width=\textwidth
1786
1787 * See the full source code @ref calendar_cxx_example_04.cc here.
1788 * @example calendar_cxx_example_04.cc
1789 */
1790
1791/**
1792 * @page calendar_cxx_example_05 Calendar - Signal callback and getters with C++ binding.
1793 * @dontinclude calendar_cxx_example_05.cc
1794
1795 * Most of setters explained on previous examples have associated
1796 * getters. That's the subject of this example. We'll add a callback
1797 * to display all calendar information every time user interacts with
1798 * the calendar. To be more didatical we'll start with the basics.
1799
1800 * The first part consists of including the headers. In this case we
1801 * are only working with the Elementary C++ binding and thus we need
1802 * only to include him.
1803
1804 * @skipline Elementary.hh
1805
1806 * @attention If necessary the C and/or the C++ headers should be
1807 * included here as well.
1808
1809 * Now we need to actually start the code and set the elm_policy,
1810 * which defines for a given policy group/identifier a new policy's
1811 * value, respectively. In this example the only policy we need to set
1812 * a value for is @c ELM_POLICY_QUIT, possibles values for it are:
1813 * function to make this tutorial more didactical.
1814
1815 * @li @p ELM_POLICY_QUIT_NONE: Never quit the application
1816 * automatically;
1817
1818 * @li @p ELM_POLICY_QUIT_LAST_WINDOW_CLOSED: quit when the
1819 * application's last window is closed;
1820
1821 * @li @p ELM_POLICY_QUIT_LAST_WINDOW_HIDDEN : quit when the
1822 * application's last window is hidden;
1823
1824 * @skip EAPI_MAIN
1825 * @until elm_policy_set
1826
1827 * As you can see, the policy we chose was to quit when the last win
1828 * is hidden as opose to examples with the C bindings where we
1829 * perpetually set it to quit when last win was closed. This changed
1830 * was necessary because in C++ binding as the elm mainloop stop
1831 * running all object are destroyed, references are unreferenced and
1832 * events are stopped at ELM_MAIN().
1833
1834 * @see For more details consult elm_policy_set
1835
1836 * Next step is creating an elementary window, in this example we use
1837 * the C++ binding method with the elm_win_util_standard_add that is a
1838 * elm_win_legacy function, better explained below. And then we set
1839 * the autohide state for it.
1840
1841 * @p elm_win_util_standard_add (const char *name, const char *tittle)
1842 * Adds a window object with standard setup.
1843 * Parameters:
1844
1845 * @li @p name - The name of the window;
1846
1847 * @li @p title - The title for the window.
1848
1849 * This creates a window but also puts in a standard background with
1850 * @p elm_bg_add(), as well as setting the window title to @p
1851 * title. The window type created is of type @c ELM_WIN_BASIC, with
1852 * the @c NULL as the parent widget. Returns the created object or @c
1853 * NULL on failure.
1854
1855 * The autohide works similarly to @p autodel, automatically handling
1856 * "delete,request" signals when set to @p true, with the difference
1857 * that it will hide the window, instead of destroying it.
1858
1859 * It is specially designed to work together with @p
1860 * ELM_POLICY_QUIT_LAST_WINDOW_HIDDEN which allows exiting
1861 * Elementary's main loop when all the windows are hidden.
1862
1863 * @skip ::elm::win
1864 * @until autohide_set
1865
1866 * @note @p autodel and @a autohide are not mutually exclusive. The
1867 * window will be destructed if both autodel and autohide is set to @p
1868 * EINA_TRUE or @p true.
1869
1870 * Now let's create the calendar with the C++ binding method, passing
1871 * our window object as parent.
1872
1873 * @skipline elm::calendar
1874
1875 * The function @c size_hint_weight_set for C++ bindings originated
1876 * from C bindings function evas_object_size_hint_weight_set, that is
1877 * EFL Evas type function. With this function we set the hints for an
1878 * object's weight. The parameters are:
1879
1880 * @li x - Nonnegative double value to use as horizontal weight hint.
1881
1882 * @li y - Nonnegative double value to use as vertical weight hint.
1883
1884 * This is not a size enforcement in any way, it's just a hint that
1885 * should be used whenever appropriate. This is a hint on how a
1886 * container object should resize a given child within its area.
1887
1888 * Containers may adhere to the simpler logic of just expanding the
1889 * child object's dimensions to fit its own (see the EVAS_HINT_EXPAND
1890 * helper weight macro in the EFL Evas Documentation) or the complete
1891 * one of taking each child's weight hint as real weights to how much
1892 * of its size to allocate for them in each axis. A container is
1893 * supposed to, after normalizing the weights of its children (with
1894 * weight hints), distribute the space it has to layout them by those
1895 * factors – most weighted children get larger in this process than
1896 * the least ones.
1897
1898 * @skipline weight_set
1899
1900 * @note Default weight hint values are 0.0, for both axis.
1901
1902 * Now we add the calendar as a resize-object to win informing that
1903 * when the size of the win changes so should the calendar's
1904 * size.
1905
1906 * Let's check our callback function, type lambda:
1907 * @skip print_cal_info
1908 * @until double interval;
1909
1910 * To learn more about consult @ref lambda.
1911
1912 * To get selected day, we need to call selected_time_get(), but to
1913 * assure nothing wrong happened, we must check for function return.
1914 * It'll return @c EINA_FALSE if fail. Otherwise we can use time set
1915 * to our structure @p stime.
1916
1917 * @skip selected_time_get
1918 * @until return
1919
1920 * Next we'll get information from calendar and place on declared
1921 * vars:
1922
1923 * @skip interval
1924 * @until weekdays_names_get
1925
1926 * The only tricky part is that last line gets an array of strings
1927 * (char arrays), one for each weekday.
1928
1929 * Then we can simple print that with std::cout and finish the lambda
1930 * function:
1931
1932 * @skip std::cout
1933 * @until std::placeholders::_1
1934
1935 * <tt> struct tm </tt> is declared on @c time.h. You can check @c
1936 * ctime manpage to read about it.
1937
1938 * To register this callback, that will be called every time user
1939 * selects a day or goes to next or previous month, just add a
1940 * callback for signal @b changed.
1941
1942 * @skipline callback_changed_add
1943
1944 * Finally we just have to make calendar and window visibles and then
1945 * start the elm mainloop, starting to handle events and drawing
1946 * operations.
1947
1948 * @skip visibility
1949 * @until ELM_MAIN
1950
1951 * Our example will look like this:
1952
1953 * @image html screenshots/calendar_cxx_example_05.png
1954 * @image latex screenshots/calendar_cxx_example_05.eps width=\textwidth
1955
1956 * See the full source code @ref calendar_cxx_example_05.cc here.
1957 * @example calendar_cxx_example_05.cc
1958 */
1959
1960/**
1961 * @page clock_cxx_example Clock widget example wit C++ binding.
1962 * @dontinclude clock_cxx_example.cc
1963
1964 * This code places five Elementary clock widgets on a window, each of
1965 * them exemplifying a part of the widget's API. Before explaining
1966 * each clock to be more didatical let's start with the basics.
1967
1968 * The first part consists of including the headers. In this
1969 * case we are only working with the Elementary C++ binding and thus
1970 * we need only to include him.
1971
1972 * @skipline Elementary.hh
1973
1974 * @attention If necessary the C and/or the C++ headers should be
1975 * include here as well.
1976
1977 * Now we need to actually start the code and set the elm_policy,
1978 * which defines for a given policy group/identifier a new policy's
1979 * value, respectively. In this example the only policy we need to
1980 * set a value for is @c ELM_POLICY_QUIT, possibles values for it are:
1981
1982 * @li @p ELM_POLICY_QUIT_NONE: Never quit the application
1983 * automatically;
1984
1985 * @li @p ELM_POLICY_QUIT_LAST_WINDOW_CLOSED: quit when the
1986 * application's last window is closed;
1987
1988 * @li @p ELM_POLICY_QUIT_LAST_WINDOW_HIDDEN : quit when the
1989 * application's last window is hidden;
1990
1991 * @skip EAPI_MAIN
1992 * @until elm_policy_set
1993
1994 * As you can see, the policy we chose was to quit when the last win
1995 * is hidden as opose to examples with the C bindings where we
1996 * perpetually set it to quit when last win was closed. This changed
1997 * was necessary because in C++ binding as the elm mainloop stop
1998 * running all object are destroyed, references are unreferenced and
1999 * events are stopped at ELM_MAIN().
2000
2001 * @see For more details consult elm_policy_set
2002
2003 * Next step is creating an Elementary window, in this example we use
2004 * the C++ binding method with the elm_win_util_standard_add that is a
2005 * elm_win_legacy function, better explained below. And then we set
2006 * the autohide state for it.
2007
2008 * @p elm_win_util_standard_add (const char *name, const char *tittle)
2009 * Adds a window object with standard setup.
2010 * Parameters:
2011
2012 * @li @p name - The name of the window;
2013
2014 * @li @p title - The title for the window.
2015
2016 * This creates a window but also puts in a standard background with
2017 * @p elm_bg_add(), as well as setting the window title to @p
2018 * title. The window type created is of type @c ELM_WIN_BASIC, with
2019 * the @c NULL as the parent widget. Returns the created object or @c
2020 * NULL on failure.
2021
2022 * And we also set the autohide state for win, autohide works
2023 * similarly to @p autodel, automatically handling "delete,request"
2024 * signals when set to @p true, with the difference that it will hide
2025 * the window, instead of destroying it.
2026
2027 * It is specially designed to work together with @p
2028 * ELM_POLICY_QUIT_LAST_WINDOW_HIDDEN which allows exiting
2029 * Elementary's main loop when all the windows are hidden.
2030
2031 * @skip ::elm::win
2032 * @until autohide_set
2033
2034 * @note @p autodel and @a autohide are not mutually exclusive. The
2035 * window will be destructed if both autodel and autohide is set to @p
2036 * EINA_TRUE or @p true.
2037
2038 * @see For more details consult elm::win::autohide_set().
2039
2040 * A box arranges objects in a linear fashion, governed by a layout
2041 * function that defines the details of this arrangement. The box will
2042 * use an internal function to set the layout to a single row,
2043 * vertical by default.
2044
2045 * Now let's create the box with the C++ binding method, passing our
2046 * window object as parent.
2047
2048 * @skipline elm::box
2049
2050 * To better understand, the function @c size_hint_weight_set for C++
2051 * bindings originated from C bindings function
2052 * evas_object_size_hint_weight_set, that is EFL Evas type function.
2053 * With this function we set the hints for an object's weight. The
2054 * parameters are:
2055
2056 * @li x - Nonnegative double value to use as horizontal weight hint.
2057
2058 * @li y - Nonnegative double value to use as vertical weight hint.
2059
2060 * This is not a size enforcement in any way, it's just a hint that
2061 * should be used whenever appropriate. This is a hint on how a
2062 * container object should resize a given child within its area.
2063
2064 * Containers may adhere to the simpler logic of just expanding the
2065 * child object's dimensions to fit its own (see the EVAS_HINT_EXPAND
2066 * helper weight macro in the EFL Evas Documentation) or the complete
2067 * one of taking each child's weight hint as real weights to how much
2068 * of its size to allocate for them in each axis. A container is
2069 * supposed to, after normalizing the weights of its children (with
2070 * weight hints), distribute the space it has to layout them by those
2071 * factors – most weighted children get larger in this process than
2072 * the least ones.
2073
2074 * @skipline weight_set
2075
2076 * @note Default weight hint values are 0.0, for both axis.
2077
2078 * Then we add the box as a resize-object to win informing that when
2079 * the size of the win changes so should the box's size. Remember
2080 * always to set the box visibility to true.
2081
2082 * @skip win
2083 * @until visibility
2084
2085 * We create each clock with the C++ binding method, passing our
2086 * window object as parent. The first of them is the pristine clock,
2087 * using the defaults for a clock, which are military time with no
2088 * seconds shown.
2089
2090 * @skipline clock
2091
2092 * When using the elm::box the packing method of the subobj - clock
2093 * in this case - should be defined. There are four possible methods:
2094
2095 * @li @c pack_start(subobj_) - Add an object to the beginning of the
2096 * pack list. Pack @c subobj_ into the box obj, placing it first in
2097 * the list of children objects. The actual position the object will
2098 * get on screen depends on the layout used. If no custom layout is
2099 * set, it will be at the top or left, depending if the box is
2100 * vertical or horizontal, respectively.
2101
2102 * @li @c pack_end(subobj_) - Add an object at the end of the pack
2103 * list. Pack @c subobj_ into the box obj, placing it last in the list
2104 * of children objects. The actual position the object will get on
2105 * screen depends on the layout used. If no custom layout is set, it
2106 * will be at the bottom or right, depending if the box is vertical or
2107 * horizontal, respectively.
2108
2109 * @li @c pack_before(subobj_, before_) - Adds an object to the box
2110 * before the indicated object. This will add the @c subobj_ to the
2111 * box indicated before the object indicated with @c before_. If
2112 * before is not already in the box, results are undefined. Before
2113 * means either to the left of the indicated object or above it
2114 * depending on orientation.
2115
2116 * @li @c pack_after(subobj_, after_) - Adds an object to the box
2117 * after the indicated object. This will add the @c subobj_ to the box
2118 * indicated after the object indicated with @c after_. If after is
2119 * not already in the box, results are undefined. After means either
2120 * to the right of the indicated object or below it depending on
2121 * orientation.
2122
2123 * In this and most examples we use pack_end by choice and
2124 * practicality. In this part of the code we also make clock
2125 * visible.
2126
2127 * @skip pack_end
2128 * @until visibility
2129
2130 * The second clock shows ther am/pm time, that we also create with
2131 * the C++ binding method, passing our window object as
2132 * parent. Setting show_am_pm to true and again choosing the packing
2133 * method and making clock visible.
2134
2135 * @skip clock
2136 * @until visibility
2137
2138 * The third one will show the seconds digits, which will flip in
2139 * synchrony with system time. Note, besides, that the time itself is
2140 * @b different from the system's -- it was customly set with
2141 * time_set():
2142
2143 * @skip ck3
2144 * @until visibility
2145
2146 * In both fourth and fifth ones, we turn on the <b>edition
2147 * mode</b>. See how you can change each of the sheets on it, and be
2148 * sure to try holding the mouse pressed over one of the sheet
2149 * arrows. The forth one also starts with a custom time set:
2150
2151 * @skip ck4
2152 * @until visibility
2153
2154 * The fifth, besides editable, has only the time @b units editable,
2155 * for hours, minutes and seconds. This exemplifies edit_mode_set():
2156
2157 * @skip ck5
2158 * @until visibility
2159
2160 * Finally we just have to make our window visible and then run the
2161 * elm mainloop, starting to handle events and drawing operations.
2162
2163 * @skip visibility
2164 * @until ELM_MAIN
2165
2166 * See the full @ref clock_cxx_example.cc, whose window should look
2167 * like this picture:
2168
2169 * @image html screenshots/clock_cxx_example.png
2170 * @image latex screenshots/clock_cxx_example.eps width=\textwidth
2171 * @example clock_cxx_example.cc
2172 */
2173
2174 /**
2175 * @page datetime_cxx_example Datetime Example with C++ binding
2176 * @dontinclude datetime_cxx_example.cc
2177
2178 * This example places three Elementary Datetime widgets on a window,
2179 * each of them exemplifying the widget's different usage.
2180
2181 * The first part consists of including the headers. In this
2182 * case we are only working with the Elementary C++ binding and thus
2183 * we need only to include him.
2184
2185 * @skipline Elementary.hh
2186
2187 * @attention If necessary the C and/or the C++ headers should be
2188 * include here as well.
2189
2190 * Now we need to actually start the code and set the elm_policy,
2191 * which defines for a given policy group/identifier a new policy's
2192 * value, respectively. In this example the only policy we need to
2193 * set a value for is @c ELM_POLICY_QUIT, possibles values for it are:
2194
2195 * @li @p ELM_POLICY_QUIT_NONE: Never quit the application
2196 * automatically;
2197
2198 * @li @p ELM_POLICY_QUIT_LAST_WINDOW_CLOSED: quit when the
2199 * application's last window is closed;
2200
2201 * @li @p ELM_POLICY_QUIT_LAST_WINDOW_HIDDEN : quit when the
2202 * application's last window is hidden;
2203
2204 * @skip EAPI_MAIN
2205 * @until elm_policy_set
2206
2207 * As you can see, the policy we chose was to quit when the last win
2208 * is hidden as opose to examples with the C bindings where we
2209 * perpetually set it to quit when last win was closed. This changed
2210 * was necessary because in C++ binding as the elm mainloop stop
2211 * running all object are destroyed, references are unreferenced and
2212 * events are stopped at ELM_MAIN().
2213
2214 * @see For more details consult elm_policy_set
2215
2216 * Next step is creating an Elementary window, where win calls a
2217 * constructor and sets the type of the win to ELM_WIN_BASIC
2218 * (Elm_Win_Type), which is the indicated type for most of our
2219 * examples. Here we also set the title that will appear at the top of
2220 * our window and then the autohide state for win.
2221
2222 * The autohide works similarly to @p autodel, automatically handling
2223 * "delete,request" signals when set to @p true, with the difference
2224 * that it will hide the window, instead of destroying it.
2225
2226 * It is specially designed to work together with @p
2227 * ELM_POLICY_QUIT_LAST_WINDOW_HIDDEN which allows exiting
2228 * Elementary's main loop when all the windows are hidden.
2229
2230 * @skip ::elm::win
2231 * @until autohide_set
2232
2233 * @note @p autodel and @a autohide are not mutually exclusive. The
2234 * window will be destructed if both autodel and autohide is set to @p
2235 * EINA_TRUE or @p true.
2236
2237 * Now we construct the elm background and for this we use the C++
2238 * method below, setting it's parent.
2239
2240 * @skipline ::elm::bg
2241
2242 * To better understand, the function @c size_hint_weight_set for C++
2243 * bindings originated from C bindings function
2244 * evas_object_size_hint_weight_set, that is EFL Evas type function.
2245 * With this function we set the hints for an object's weight. The
2246 * parameters are:
2247
2248 * @li x - Nonnegative double value to use as horizontal weight hint.
2249
2250 * @li y - Nonnegative double value to use as vertical weight hint.
2251
2252 * This is not a size enforcement in any way, it's just a hint that
2253 * should be used whenever appropriate. This is a hint on how a
2254 * container object should resize a given child within its area.
2255
2256 * Containers may adhere to the simpler logic of just expanding the
2257 * child object's dimensions to fit its own (see the EVAS_HINT_EXPAND
2258 * helper weight macro in the EFL Evas Documentation) or the complete
2259 * one of taking each child's weight hint as real weights to how much
2260 * of its size to allocate for them in each axis. A container is
2261 * supposed to, after normalizing the weights of its children (with
2262 * weight hints), distribute the space it has to layout them by those
2263 * factors – most weighted children get larger in this process than
2264 * the least ones.
2265
2266 * @skipline weight_set
2267
2268 * @note Default weight hint values are 0.0, for both axis.
2269
2270 * Now we add the background as a resize_object to win informing that
2271 * when the size of the win changes so should the background's
2272 * size. And finally we make it visible.
2273
2274 * @skip win
2275 * @until visibility_set
2276
2277 * @remarks If a color it's not setted the default color will be used.
2278
2279 * A box arranges objects in a linear fashion, governed by a layout
2280 * function that defines the details of this arrangement. The box will
2281 * use an internal function to set the layout to a single row,
2282 * vertical by default.
2283
2284 * Now let's create the box with the C++ binding method, passing our
2285 * window object as parent. Using Evas weight_set function again to
2286 * hint on how a container object should resize a given child within
2287 * its area.
2288
2289 * @skipline elm::box
2290 * @until weight_set
2291
2292 * Then we add the box as a resize-object to win informing that when
2293 * the size of the win changes so should the box's size. Remember
2294 * always to set the box visibility to true.
2295
2296 * @skip win
2297 * @until visibility
2298
2299 * The first of them is <b>"only Date display"</b>. We will create it
2300 * using the C++ method below. The weight hint works with datetime the
2301 * same as it did with background and box.
2302
2303 * @skip datetime
2304 * @until weight
2305
2306 * Now we have to The function @c size_hint_align_set for C++ bindings
2307 * originated from C bindings function
2308 * evas_object_size_hint_align_set, that is EFL Evas type
2309 * function. With this function we set the hints for an object's
2310 * alignment. The parameters are:
2311
2312 * @li x - Double, ranging from 0.0 to 1.0 or with the special value
2313 * EVAS_HINT_FILL, to use as horizontal alignment hint.
2314
2315 * @li y - Double, ranging from 0.0 to 1.0 or with the special value
2316 * EVAS_HINT_FILL, to use as vertical alignment hint.
2317
2318 * These are hints on how to align an object inside the boundaries of
2319 * a container/manager. Accepted values are in the 0.0 to 1.0 range,
2320 * with the special value EVAS_HINT_FILL used to specify "justify" or
2321 * "fill" by some users. In this case, maximum size hints should be
2322 * enforced with higher priority, if they are set. Also, any padding
2323 * hint set on objects should add up to the alignment space on the
2324 * final scene composition.
2325
2326 * For the horizontal component, 0.0 means to the left, 1.0 means to
2327 * the right. Analogously, for the vertical component, 0.0 to the top,
2328 * 1.0 means to the bottom.
2329
2330 * This is not a size enforcement in any way, it's just a hint that
2331 * should be used whenever appropriate.
2332
2333 * @skipline align
2334
2335 * @note Default alignment hint values are 0.5, for both axis.
2336
2337 * An important feature for the datetime is the setting of what we
2338 * want it to display. We can achieve that by using:
2339
2340 * @p field_visible_set ( Elm_Datetime_Field_Type fieldtype_, bool
2341 * visible_)
2342
2343 * Parameters are:
2344
2345 * @li @p fieldtype_: type of the field, supports 6 fields:
2346
2347 * @p ELM_DATETIME_YEAR: Indicates Year field.
2348
2349 * @p ELM_DATETIME_MONTH: Indicates Month field.
2350
2351 * @p ELM_DATETIME_DATE: Indicates Date field.
2352
2353 * @p ELM_DATETIME_HOUR: Indicates Hour field,
2354
2355 * @p ELM_DATETIME_MINUTE: Indicates Minute field.
2356
2357 * @p ELM_DATETIME_AMPM: Indicates AM/PM field.
2358
2359 * @li @p visible_: @p true field can be visible, @p false otherwise.
2360
2361 * @attention Setting this API True does not ensure that the field is
2362 * visible, apart from this, the field's format must be present in
2363 * Datetime overall format. If a field's visibility is set to False
2364 * then it won't appear even though its format is present in overall
2365 * format. So if and only if this API is set true and the
2366 * corresponding field's format is present in Datetime format, the
2367 * field is visible.
2368
2369 * @note By default the field visibility is set to @p true.
2370
2371 * For this first datetime we are setting the HOUR, MINUTE and AM/PM
2372 * to not be visible, doing this we'll display in our datetime the
2373 * year, month and date.
2374
2375 * @note Hour format 12hr(1-12) or 24hr(0-23) display can be selected
2376 * by setting the corresponding user format. The corresponding Month
2377 * and AM/PM strings are displayed according to the system’s language
2378 * settings.
2379
2380 * @skip HOUR
2381 * @until AMPM
2382
2383 * When using the elm box the packing method of the subobj - datetime
2384 * in this case - should be defined. There are four possible methods:
2385
2386 * @li @c pack_start(subobj_) - Add an object to the beginning of the
2387 * pack list. Pack @c subobj_ into the box obj, placing it first in
2388 * the list of children objects. The actual position the object will
2389 * get on screen depends on the layout used. If no custom layout is
2390 * set, it will be at the top or left, depending if the box is
2391 * vertical or horizontal, respectively.
2392
2393 * @li @c pack_end(subobj_) - Add an object at the end of the pack
2394 * list. Pack @c subobj_ into the box obj, placing it last in the list
2395 * of children objects. The actual position the object will get on
2396 * screen depends on the layout used. If no custom layout is set, it
2397 * will be at the bottom or right, depending if the box is vertical or
2398 * horizontal, respectively.
2399
2400 * @li @c pack_before(subobj_, before_) - Adds an object to the box
2401 * before the indicated object. This will add the @c subobj_ to the
2402 * box indicated before the object indicated with @c before_. If
2403 * before is not already in the box, results are undefined. Before
2404 * means either to the left of the indicated object or above it
2405 * depending on orientation.
2406
2407 * @li @c pack_after(subobj_, after_) - Adds an object to the box
2408 * after the indicated object. This will add the @c subobj_ to the box
2409 * indicated after the object indicated with @c after_. If after is
2410 * not already in the box, results are undefined. After means either
2411 * to the right of the indicated object or below it depending on
2412 * orientation.
2413
2414 * In this and most examples we use pack_end by choice and
2415 * practicality. In this part of the code we also make datetime
2416 * visible.
2417
2418 * @skip pack_end
2419 * @until visibility
2420
2421 * For our second datetime, we'll also set the size hints weight and
2422 * align, but in this case, the filds YEAR, MONTH and DATE will be not
2423 * visible, and thus displaying in our datetime the hour, minute and
2424 * AM/PM. Finally we choose it's packing method and set the visibility
2425 * of datetime to @p true.
2426
2427 * @skip datetime2
2428 * @until visibility
2429
2430 * For our third and last datetime, we setted the weight and align as
2431 * before, chose our packing method and made it visible. Note that in
2432 * this case we didn't exclude any type of field leaving all visible.
2433
2434 * @skip datetime3
2435 * @until visibility
2436
2437 * And finally, we set our win's visibility and start the elm
2438 * mainloop, starting to handle events and drawing operations.
2439
2440 * @skip win
2441 * @until ELM_MAIN
2442
2443 * See the full @ref datetime_cxx_example.cc .
2444
2445 * This example should look like:
2446
2447 * @image html screenshots/datetime_cxx_example.png
2448 * @image latex screenshots/datetime_cxx_example.eps width=\textwidth
2449
2450 * @example datetime_cxx_example.cc
2451 */
2452
2453/**
2454 * @page glview_cxx_example_01 Glview example with C++ Binding
2455 * @dontinclude glview_cxx_example_01.cc
2456
2457 * In this example we'll illustrate how to use Glview and it's
2458 * features.
2459
2460 * The first part consists of including the headers. In this case we
2461 * need to include @p Elementary.hh, @p Evas_GL.h and @p stdio.h.
2462
2463 *@li @p Elementary.hh: library for Elementary with support for C++
2464 * language;
2465
2466 *@li @p Evas_GL.h: has functions that are used to do OpenGL rendering
2467 * on Evas, Evas allows us to use OpenGL to render to specially set up
2468 * image objects, which act as render target surfaces.
2469
2470 *@li @p stdio.h is a C library with functions tha perform
2471 * Input/Output operations.
2472
2473 * @skip Elementary.hh
2474 * @until stdio
2475
2476 * Continuing with the code, at this point we create a GL related
2477 * struct:
2478
2479 *@li @p Evas_GL_API that is the structure type of the Evas GL API object
2480 * that contains the GL APIs to be used in Evas GL.
2481
2482 *@li @p GLuint one of the pre-defined types of OpenGL which is a unsigned binary integer.
2483
2484 *@li @p int AKA @p int.
2485
2486 * @skip typedef
2487 * @until };
2488
2489 * Here we're simply initializing a type float, that we named red.
2490
2491 * @skipline red
2492
2493 * In this example we'll need a type C helper function to load shaders
2494 * from a shader source.
2495
2496 * @skip static
2497 * @until GLint
2498
2499 * Inside this function we create the shader objectand load/compile
2500 * shader source.
2501
2502 * @skip shader
2503 * @until return shader;
2504
2505 * Completing our load shader function.
2506
2507 * @skipline }
2508
2509 * This example will also need a function to initialize the shader and
2510 * program object.
2511
2512 * @skip static
2513 * @until linked
2514
2515 * In this function we load the vertex/fragment shaders, create the
2516 * program object and finish our funtion.
2517
2518 * @skip gld
2519 * @until return 1;
2520 * @skiline }
2521
2522 * We need the following callbacks:
2523
2524 * @li initialize callback: that get called once for
2525 * initialization;
2526
2527 * @skip void
2528 * @until BufferData
2529 * @skipline }
2530
2531 * @li delete callback: gets called when glview is deleted;
2532
2533 * @skip void
2534 * @until free
2535 * @skipline }
2536
2537 * @li resize callback: gets called every time object is resized;
2538
2539 * @skip void
2540 * @skipline }
2541
2542 * @li draw callback: is where all the main GL rendering happens.
2543
2544 * @skip void
2545 * @until COLOR_BUFFER
2546
2547 * Inside this callback, we'll draw a triangle.
2548
2549 * @skip gl
2550 * @until DrawArrays
2551
2552 * Still inside as an option we are going to flush the GL pipeline and
2553 * end our callback.
2554
2555 * @skip Finish
2556 * @until }
2557
2558 * We create @p _anim to notify that glview has changed so it can
2559 * render.
2560
2561 * @skip static
2562 * @until }
2563
2564 * Now that we finished with the GL preparations, we'll start the main
2565 * code and initialize our GLData pointer object to NULL and run a
2566 * check just in case.
2567
2568 * @skip EAPI_MAIN
2569 * @until if
2570
2571 * Let's set the elm_policy, which defines for a given policy
2572 * group/identifier a new policy's value, respectively. In this
2573 * example the only policy we need to set a value for is @c
2574 * ELM_POLICY_QUIT, possibles values for it are:
2575
2576 * @li @p ELM_POLICY_QUIT_NONE: Never quit the application
2577 * automatically;
2578
2579 * @li @p ELM_POLICY_QUIT_LAST_WINDOW_CLOSED: quit when the
2580 * application's last window is closed;
2581
2582 * @li @p ELM_POLICY_QUIT_LAST_WINDOW_HIDDEN : quit when the
2583 * application's last window is hidden;
2584
2585 * @skipline elm_policy_set
2586
2587 * As you can see, the policy we chose was to quit when the last win
2588 * is hidden as opose to examples with the C bindings where we
2589 * perpetually set it to quit when last win was closed. This changed
2590 * was necessary because in C++ binding as the elm mainloop stop
2591 * running all object are destroyed, references are unreferenced and
2592 * events are stopped at ELM_MAIN().
2593
2594 * @see For more details consult elm_policy_set
2595
2596 * Next step is creating an elementary window, in this example we use
2597 * the C++ binding method with the elm_win_util_standard_add that is a
2598 * elm_win_legacy function, better explained below. And then we set
2599 * the autohide state for it.
2600
2601 * @p elm_win_util_standard_add (const char *name, const char *tittle)
2602 * Adds a window object with standard setup.
2603 * Parameters:
2604
2605 * @li @p name - The name of the window;
2606
2607 * @li @p title - The title for the window.
2608
2609 * This creates a window but also puts in a standard background with
2610 * @p elm_bg_add(), as well as setting the window title to @p
2611 * title. The window type created is of type @c ELM_WIN_BASIC, with
2612 * the @c NULL as the parent widget. Returns the created object or @c
2613 * NULL on failure.
2614
2615 * The autohide works similarly to @p autodel, automatically handling
2616 * "delete,request" signals when set to @p true, with the difference
2617 * that it will hide the window, instead of destroying it.
2618
2619 * It is specially designed to work together with @p
2620 * ELM_POLICY_QUIT_LAST_WINDOW_HIDDEN which allows exiting
2621 * Elementary's main loop when all the windows are hidden.
2622
2623 * @skip ::elm::win
2624 * @until autohide_set
2625
2626 * @note @p autodel and @a autohide are not mutually exclusive. The
2627 * window will be destructed if both autodel and autohide is set to @p
2628 * EINA_TRUE or @p true.
2629
2630 * Now let's create a box with the C++ binding method, passing our
2631 * window object as parent, we'll use this box to contain our glview
2632 * object.
2633
2634 * @skipline bx
2635
2636 * To better understand, the function @c size_hint_weight_set for C++
2637 * bindings originated from C bindings function
2638 * evas_object_size_hint_weight_set, that is EFL Evas type function.
2639 * With this function we set the hints for an object's weight. The
2640 * parameters are:
2641
2642 * @li x - Nonnegative double value to use as horizontal weight hint.
2643
2644 * @li y - Nonnegative double value to use as vertical weight hint.
2645
2646 * This is not a size enforcement in any way, it's just a hint that
2647 * should be used whenever appropriate. This is a hint on how a
2648 * container object should resize a given child within its area.
2649
2650 * Containers may adhere to the simpler logic of just expanding the
2651 * child object's dimensions to fit its own (see the EVAS_HINT_EXPAND
2652 * helper weight macro in the EFL Evas Documentation) or the complete
2653 * one of taking each child's weight hint as real weights to how much
2654 * of its size to allocate for them in each axis. A container is
2655 * supposed to, after normalizing the weights of its children (with
2656 * weight hints), distribute the space it has to layout them by those
2657 * factors – most weighted children get larger in this process than
2658 * the least ones.
2659
2660 * @skipline weight_set
2661
2662 * @note Default weight hint values are 0.0, for both axis.
2663
2664 * Then we add the box as a resize-object to win informing that when
2665 * the size of the win changes so should the box's size. Remember
2666 * always to set the box visibility to true.
2667
2668 * @skip win
2669 * @until visibility
2670
2671 * In this part we'll create a new elm glview, using the C++ method,
2672 * in this case it requires that we set @p Evas_GL_Context_Version
2673 * with the version_constructor. @p Evas_GL_Context_Version is a
2674 * enumeration that defines the available OpenGL ES version numbers,
2675 * it can be used to create OpenGL-ES 1.1 contexts.
2676
2677 * @skip glview
2678 * @until glapi
2679
2680 * The function size_hint_weight_set works with glview the same way as
2681 * with box, for more, search above.
2682
2683 * The function @c size_hint_align_set for C++ bindings originated
2684 * from C bindings function evas_object_size_hint_align_set, that is
2685 * EFL Evas type function. With this function we set the hints for an
2686 * object's alignment. The parameters are:
2687
2688 * @li x - Double, ranging from 0.0 to 1.0 or with the special value
2689 * EVAS_HINT_FILL, to use as horizontal alignment hint.
2690
2691 * @li y - Double, ranging from 0.0 to 1.0 or with the special value
2692 * EVAS_HINT_FILL, to use as vertical alignment hint.
2693
2694 * These are hints on how to align an object inside the boundaries of
2695 * a container/manager. Accepted values are in the 0.0 to 1.0 range,
2696 * with the special value EVAS_HINT_FILL used to specify "justify" or
2697 * "fill" by some users. In this case, maximum size hints should be
2698 * enforced with higher priority, if they are set. Also, any padding
2699 * hint set on objects should add up to the alignment space on the
2700 * final scene composition.
2701
2702 * For the horizontal component, 0.0 means to the left, 1.0 means to
2703 * the right. Analogously, for the vertical component, 0.0 to the top,
2704 * 1.0 means to the bottom.
2705
2706 * This is not a size enforcement in any way, it's just a hint that
2707 * should be used whenever appropriate.
2708
2709 * @note Default alignment hint values are 0.5, for both axis.
2710
2711 * @skipline align_set
2712
2713 * Mode is simply for supporting alpha, depth buffering and stencil
2714 * buffering.
2715
2716 * @skip mode
2717 * @until mode_set
2718
2719 * Resize policy tells glview what to do with the surface when it
2720 * resizes. ELM_VIEW_RESIZE_POLICY_RECREATE will tell it to destroy
2721 * the current surface and recreate it to the new size.
2722
2723 * @skipline resize
2724
2725 * Render policy tells glview how it would like glview to render gl
2726 * code. ELM_GLVIEW_RENDER_POLICY_ON_DEMAND will have the gl calls
2727 * called in the pixel_get callback, which only gets called if the
2728 * object is visible, hence ON_DEMAND. ALWAYS mode renders it despite
2729 * the visibility of the object.
2730
2731 * @skipline render
2732
2733 * Now we'll register our callbacks.
2734
2735 * @skip init
2736 * @until draw
2737
2738 * When using the elm box the packing method of the subobj - glview in
2739 * this case - should be defined. There are four possible methods:
2740
2741 * @li @c pack_start(subobj_) - Add an object to the beginning of the
2742 * pack list. Pack @c subobj_ into the box obj, placing it first in
2743 * the list of children objects. The actual position the object will
2744 * get on screen depends on the layout used. If no custom layout is
2745 * set, it will be at the top or left, depending if the box is
2746 * vertical or horizontal, respectively.
2747
2748 * @li @c pack_end(subobj_) - Add an object at the end of the pack
2749 * list. Pack @c subobj_ into the box obj, placing it last in the list
2750 * of children objects. The actual position the object will get on
2751 * screen depends on the layout used. If no custom layout is set, it
2752 * will be at the bottom or right, depending if the box is vertical or
2753 * horizontal, respectively.
2754
2755 * @li @c pack_before(subobj_, before_) - Adds an object to the box
2756 * before the indicated object. This will add the @c subobj_ to the
2757 * box indicated before the object indicated with @c before_. If
2758 * before is not already in the box, results are undefined. Before
2759 * means either to the left of the indicated object or above it
2760 * depending on orientation.
2761
2762 * @li @c pack_after(subobj_, after_) - Adds an object to the box
2763 * after the indicated object. This will add the @c subobj_ to the box
2764 * indicated after the object indicated with @c after_. If after is
2765 * not already in the box, results are undefined. After means either
2766 * to the right of the indicated object or below it depending on
2767 * orientation.
2768
2769 * In this and most examples we use pack_end by choice and
2770 * practicality, in this part of the code we also make glview visible
2771 * and set to focus.
2772
2773 * @skip pack_end
2774 * @until focus
2775
2776 * For a simple demonstration of the animation we'll have to use
2777 * ecore::animator. As long as tou trigger an update on the image via
2778 * @p changed_set() it will be updated.
2779
2780 * @skip ani
2781 * @until "gld"
2782
2783 * If you delete gl, this animator will keep running trying to access
2784 * gl so it's better to delete this animator with
2785 * ecore_animator_del(), as seen inside the lambda function.
2786
2787 * @skipline callback_del
2788
2789 * @note To learn more about Lambda Function and its use in Elementary
2790 * consult @ref lambda.
2791
2792 * We're going to add a "OK" button to end the program. First step is
2793 * to create it using the C++ method, setting it's parent.
2794
2795 * @skipline button
2796
2797 * Second, set the text, alignment and weight hints, the hints work
2798 * the same as with box and glview.
2799
2800 * @skip text
2801 * @until weight
2802
2803 * Pack our button in the same box as glview and set the visibility for
2804 * it.
2805
2806 * @skip pack
2807 * @until visibility
2808
2809 * As a final step for our button, we are going to add a clicked
2810 * callback, using again Lambda Type Function.
2811
2812 * @skipline clicked
2813
2814 * @note To learn more about Lambda Function and its use in Elementary
2815 * consult @ref lambda.
2816
2817 * Now we only have to set the size for our window and make it
2818 * visible.
2819
2820 * @skip size_set
2821 * @until visibility_set
2822
2823 * And finally, start the elm mainloop, starting to handle events and
2824 * drawing operations.
2825
2826 * @skip elm_run
2827 * @until ELM_MAIN
2828
2829 * See full code for this example @ref glview_cxx_example_01.cc "here" .
2830
2831 * @example glview_cxx_example_01.cc
2832 */
2833
2834/**
2835 * @page hoversel_cxx_example_01 Hoversel example with C++ Binding
2836 * @dontinclude hoversel_cxx_example_01.cc
2837
2838 * In this example we'll create a hoversel with 3 items, one with a
2839 * label but no icon and two with both a label and an icon. Every item
2840 * that is clicked will be deleted, but everytime the hoversel is
2841 * activated we will also add an item. In addition our first item will
2842 * print all items when clicked and our third item will clear all
2843 * items in the hoversel.
2844
2845 * The first part consists of including the headers. We'll include @p
2846 * Elementary.hh, @p Eina.hh and @p Evas.hh, that are C++ bindings
2847 * that are needed in this example.
2848
2849 * @skip Elementary
2850 * @until Evas
2851
2852 * Before our main code we'll need the following callbacks:
2853
2854 *@li @p _print_items: callback for our first item which prints all
2855 * items in the hoversel.
2856
2857 * @until print
2858
2859 *@li @p _free: callback that frees the allocated memory.
2860
2861 * @until free
2862
2863 * Starting the main code and initializing Eina C++ Lybrary, always
2864 * initiate Eina when included.
2865
2866 * @skip EAPI
2867 * @until eina
2868
2869 * Now let's set the elm_policy, which defines for a given policy
2870 * group/identifier a new policy's value, respectively. In this
2871 * example the only policy we need to set a value for is @c
2872 * ELM_POLICY_QUIT, possibles values for it are:
2873
2874 * @li @p ELM_POLICY_QUIT_NONE: Never quit the application
2875 * automatically;
2876
2877 * @li @p ELM_POLICY_QUIT_LAST_WINDOW_CLOSED: quit when the
2878 * application's last window is closed;
2879
2880 * @li @p ELM_POLICY_QUIT_LAST_WINDOW_HIDDEN : quit when the
2881 * application's last window is hidden;
2882
2883 * @skipline elm_policy_set
2884
2885 * As you can see, the policy we chose was to quit when the last win
2886 * is hidden as opose to examples with the C bindings where we
2887 * perpetually set it to quit when last win was closed. This changed
2888 * was necessary because in C++ binding as the elm mainloop stop
2889 * running all object are destroyed, references are unreferenced and
2890 * events are stopped at ELM_MAIN().
2891
2892 * @see For more details consult elm_policy_set
2893
2894 * Next step is creating an elementary window, in this example we use
2895 * the C++ binding method with the elm_win_util_standard_add that is a
2896 * elm_win_legacy function, better explained below. And then we set
2897 * the autohide state for it.
2898
2899 * @p elm_win_util_standard_add (const char *name, const char *tittle)
2900 * Adds a window object with standard setup.
2901 * Parameters:
2902
2903 * @li @p name - The name of the window;
2904
2905 * @li @p title - The title for the window.
2906
2907 * This creates a window but also puts in a standard background with
2908 * @p elm_bg_add(), as well as setting the window title to @p
2909 * title. The window type created is of type @c ELM_WIN_BASIC, with
2910 * the @c NULL as the parent widget. Returns the created object or @c
2911 * NULL on failure.
2912
2913 * The autohide works similarly to @p autodel, automatically handling
2914 * "delete,request" signals when set to @p true, with the difference
2915 * that it will hide the window, instead of destroying it.
2916
2917 * It is specially designed to work together with @p
2918 * ELM_POLICY_QUIT_LAST_WINDOW_HIDDEN which allows exiting
2919 * Elementary's main loop when all the windows are hidden.
2920
2921 * @skip ::elm::win
2922 * @until autohide_set
2923
2924 * @note @p autodel and @a autohide are not mutually exclusive. The
2925 * window will be destructed if both autodel and autohide is set to @p
2926 * EINA_TRUE or @p true.
2927
2928 * Next we'll create a red evas::rectangle to use as the icon of our
2929 * hoversel, for thus using the C++ method, setting the color and
2930 * making it visible.
2931
2932 * @skip evas
2933 * @until visibility
2934
2935 * And now we create our hoversel and set some of it's properties. We
2936 * set @p win as its parent, set it to be vertical and give it a label
2937 * and content, that will work as icon:
2938
2939 * @skip hoversel
2940 * @until content
2941
2942 * Next we will add callbacks to be called for the first and third:
2943
2944 * @skip item
2945 * @until "Option 2"
2946
2947 * We also set a pair of callbacks to be called whenever any item is
2948 * selected or when the hoversel is activated, for this we'll use
2949 * Lambda type function, @p add_item is called when the hoversel is
2950 * activated and adds an item to the hoversel. Note that since we
2951 * allocate memory for the item we need to know when the item dies so
2952 * we can free that memory.
2953
2954 * @skip add
2955 * @until clicked
2956
2957 * @see For more on Lambda check @ref lambda "here"
2958
2959 * Finishing with hoversel we set its size, position and make it
2960 * visible.
2961
2962 * @skip size
2963 * @until visibility
2964
2965 * In our second hoversel we'll add a button and for this we need
2966 * create it using C++ method, set a text, add a callback for when
2967 * button is clicked. This callback is type Lambda, it will clear
2968 * hoversel when clicked.
2969
2970 * @skip button
2971 * @until callback
2972
2973 * Concluding our button options, we will set the size, position and
2974 * visibility.
2975
2976 * @skip size
2977 * @until visibility
2978
2979 * Now we set the size for the window, making it visible in the end:
2980
2981 * @skip size_set
2982 * @until visibility_set
2983
2984 * Finally we just have to start the elm mainloop, starting to handle
2985 * events and drawing operations.
2986
2987 * @skip elm_run
2988 * @until ELM_MAIN
2989
2990 * Our example will look like this:
2991
2992 * @image html screenshots/hoversel_cxx_example_01.png
2993 * @image latex screenshots/hoversel_cxx_example_01.eps width=\textwidth
2994
2995 * @example hoversel_cxx_example_01.cc
2996 */
2997
2998/**
2999 * @page icon_cxx_example_01 Icon Example with C++ binding
3000 * @dontinclude icon_cxx_example_01.cc
3001
3002 * This example is as simple as possible. An icon object will be added
3003 * to the window over a blank background, and set to be resizable
3004 * together with the window. All the options set through the example
3005 * will affect the behavior of this icon.
3006
3007 * The first part consists of including the headers. In this case we
3008 * are only working with the Elementary C++ binding and thus we need
3009 * only to include him.
3010
3011 * @skipline Elementary.hh
3012
3013 * @attention If necessary the C and/or the C++ headers should be
3014 * include here as well.
3015
3016 * Now we need to actually start the code and set the elm_policy,
3017 * which defines for a given policy group/identifier a new policy's
3018 * value, respectively. In this example the only policy we need to set
3019 * a value for is @c ELM_POLICY_QUIT, possibles values for it are:
3020
3021 * @li @p ELM_POLICY_QUIT_NONE: Never quit the application
3022 * automatically;
3023
3024 * @li @p ELM_POLICY_QUIT_LAST_WINDOW_CLOSED: quit when the
3025 * application's last window is closed;
3026
3027 * @li @p ELM_POLICY_QUIT_LAST_WINDOW_HIDDEN : quit when the
3028 * application's last window is hidden;
3029
3030 * @skip EAPI_MAIN
3031 * @until elm_policy_set
3032
3033 * As you can see, the policy we chose was to quit when the last win
3034 * is hidden as opose to examples with the C bindings where we
3035 * perpetually set it to quit when last win was closed. This changed
3036 * was necessary because in C++ binding as the elm mainloop stop
3037 * running all object are destroyed, references are unreferenced and
3038 * events are stopped at ELM_MAIN().
3039
3040 * @see For more details consult elm_policy_set
3041
3042 * Next step is creating an elementary window, in this example we use
3043 * the C++ binding method with the elm_win_util_standard_add that is a
3044 * elm_win_legacy function, better explained below. And then we set
3045 * the autohide state for it.
3046
3047 * @p elm_win_util_standard_add (const char *name, const char *tittle)
3048 * Adds a window object with standard setup.
3049 * Parameters:
3050
3051 * @li @p name - The name of the window;
3052
3053 * @li @p title - The title for the window.
3054
3055 * This creates a window but also puts in a standard background with
3056 * @p elm_bg_add(), as well as setting the window title to @p
3057 * title. The window type created is of type @c ELM_WIN_BASIC, with
3058 * the @c NULL as the parent widget. Returns the created object or @c
3059 * NULL on failure.
3060
3061 * The autohide works similarly to @p autodel, automatically handling
3062 * "delete,request" signals when set to @p true, with the difference
3063 * that it will hide the window, instead of destroying it.
3064
3065 * It is specially designed to work together with @p
3066 * ELM_POLICY_QUIT_LAST_WINDOW_HIDDEN which allows exiting
3067 * Elementary's main loop when all the windows are hidden.
3068
3069 * @skip ::elm::win
3070 * @until autohide_set
3071
3072 * @note @p autodel and @a autohide are not mutually exclusive. The
3073 * window will be destructed if both autodel and autohide is set to @p
3074 * EINA_TRUE or @p true.
3075
3076 * Now we construct the elm icon and for this we use the C++ method
3077 * below, setting it's parent. An icon object is used to display
3078 * standard icon images ("delete", "edit", "arrows", etc.) or images
3079 * coming from a custom file (PNG, JPG, EDJE, etc.), on icon contexts.
3080
3081 * @skipline ::elm::icon
3082
3083 * The icon image requested can be in the Elementary theme in use, or
3084 * in the freedesktop.org theme paths. It's possible to set the order
3085 * of preference from where an image will be fetched and for that
3086 * we'll use the function @ order_lookup_set(order_) that will be use
3087 * by standard_set. Possibles values for @p order_ are:
3088
3089 * @li @p ELM_ICON_LOOKUP_FDO_THEME: icon look up order is freedesktop
3090 * then theme;
3091
3092 * @li @p ELM_ICON_LOOKUP_THEME_FDO: icon look up order is theme then
3093 * freedesktop;
3094
3095 * @li @p ELM_ICON_LOOKUP_FDO: icon look up order is only freedesktop;
3096
3097 * @li @p ELM_ICON_LOOKUP_THEME: icon look up order is only theme;
3098
3099 * @skipline order
3100
3101 * Now that we setted the order value we can set the standard "home"
3102 * icon, chosen for this example.
3103
3104 * @skipline standard
3105
3106 * An interesting thing is that after setting this, it's possible to
3107 * check where in the filesystem is the theme used by this icon, and
3108 * the name of the group used, using file_get.
3109
3110 * @skip file
3111 * @until std::cout
3112
3113 * We can also get the name of the standard icon that we setted
3114 * before.
3115
3116 * @skip name
3117 * @until std::cout
3118
3119 * We can now go setting our options.
3120
3121 * no_scale_set() is used just to set this value to true as we don't
3122 * actually want to scale our icon, just resize it.
3123
3124 * resizable_set() is used to allow the icon to be resized to a size
3125 * smaller than the original one, but not to a size bigger than it.
3126
3127 * smooth_set() will disable the smooth scaling, so the scale
3128 * algorithm used to scale the icon to the new object size is going to
3129 * be faster, but with a lower quality.
3130
3131 * fill_outside_set() is used to ensure that the icon will fill the
3132 * entire area available to it, even if keeping the aspect ratio. The
3133 * icon will overflow its width or height (any of them that is
3134 * necessary) to the object area, instead of resizing the icon down
3135 * until it can fit entirely in this area.
3136
3137 * This is the code for setting these options:
3138
3139 * @until fill_outside
3140
3141 * However, if you try this example you may notice that this image is
3142 * not being affected by all of these options. This happens because
3143 * the used icon will be from elementary theme, and thus it has its
3144 * own set of options like smooth scaling and fill_outside
3145 * options. You can change the "home" icon to use some image (from
3146 * your system) and see that then those options will be respected.
3147
3148 * To better understand, the function @c size_hint_weight_set for C++
3149 * bindings originated from C bindings function
3150 * evas_object_size_hint_weight_set, that is EFL Evas type function.
3151 * With this function we set the hints for an object's weight. The
3152 * parameters are:
3153
3154 * @li x - Nonnegative double value to use as horizontal weight hint.
3155
3156 * @li y - Nonnegative double value to use as vertical weight hint.
3157
3158 * This is not a size enforcement in any way, it's just a hint that
3159 * should be used whenever appropriate.
3160
3161 * This is a hint on how a container object should resize a given
3162 * child within its area.
3163
3164 * Containers may adhere to the simpler logic of just expanding the
3165 * child object's dimensions to fit its own (see the EVAS_HINT_EXPAND
3166 * helper weight macro in the EFL Evas Documentation) or the complete
3167 * one of taking each child's weight hint as real weights to how much
3168 * of its size to allocate for them in each axis. A container is
3169 * supposed to, after normalizing the weights of its children (with
3170 * weight hints), distribute the space it has to layout them by those
3171 * factors – most weighted children get larger in this process than
3172 * the least ones.
3173
3174 * @skipline weight_set
3175
3176 * @note Default weight hint values are 0.0, for both axis.
3177
3178 * Now we add the icon as a resize_object to win informing that
3179 * when the size of the win changes so should the icon's
3180 * size. And finally we make icon visible.
3181
3182 * Now we set the size for the window, making it visible in the end:
3183
3184 * @skip size_set
3185 * @until visibility_set
3186
3187 * Finally we just have to start the elm mainloop, starting to handle
3188 * events and drawing operations.
3189
3190 * @skip elm_run
3191 * @until ELM_MAIN
3192
3193 * The full code for this example can be found at @ref icon_cxx_example_01.cc
3194
3195 * This example will look like this:
3196
3197 * @image html screenshots/icon_cxx_example_01.png
3198 * @image latex screenshots/icon_cxx_example_01.eps width=\textwidth
3199
3200 * @example icon_cxx_example_01.cc
3201 */
3202
3203/**
3204 * @page location_cxx_example_01 Location example with C++ Binding
3205 * @dontinclude location_cxx_example_01.cc
3206
3207 * This example shows how to integrate the Elocation.h library with
3208 * elementary.
3209
3210 * The first part consists of including the headers. In this case we
3211 * need to include both Elementary C++ binding and Elocation,
3212
3213 * @skip Elementary.hh
3214 * @until endif
3215
3216 * @attention All necessary libraries from Elementary, Elightenment, C
3217 * and/or C++ headers should be include here.
3218
3219 * Before our main code, we need a set of callbacks to react on
3220 * incoming elocation events. They are standard ecore events and we
3221 * register callbacks on these events in the main function.
3222
3223 * @skip void
3224 * @until ECORE_CALLBACK_DONE
3225 * @until }
3226
3227 * Now we need to actually start the code and initializing pointers
3228 * for address, addr_geocode, position and pos_geocode and an integer
3229 * status. We also run a check for elm_need_elocation.
3230
3231 * @skip EAPI_MAIN
3232 * @until -1
3233
3234 * Now let's set the elm_policy, which defines for a given policy
3235 * group/identifier a new policy's value, respectively. In this
3236 * example the only policy we need to set a value for is @c
3237 * ELM_POLICY_QUIT, possibles values for it are:
3238
3239 * @li @p ELM_POLICY_QUIT_NONE: Never quit the application
3240 * automatically;
3241
3242 * @li @p ELM_POLICY_QUIT_LAST_WINDOW_CLOSED: quit when the
3243 * application's last window is closed;
3244
3245 * @li @p ELM_POLICY_QUIT_LAST_WINDOW_HIDDEN : quit when the
3246 * application's last window is hidden;
3247
3248 * @skipline elm_policy_set
3249
3250 * As you can see, the policy we chose was to quit when the last win
3251 * is hidden as opose to examples with the C bindings where we
3252 * perpetually set it to quit when last win was closed. This changed
3253 * was necessary because in C++ binding as the elm mainloop stop
3254 * running all object are destroyed, references are unreferenced and
3255 * events are stopped at ELM_MAIN().
3256
3257 * @see For more details consult elm_policy_set
3258
3259 * Next step is creating an elementary window, in this example we use
3260 * the C++ binding method with the elm_win_util_standard_add that is a
3261 * elm_win_legacy function, better explained below. And then we set
3262 * the autohide state for it.
3263
3264 * @p elm_win_util_standard_add (const char *name, const char *tittle)
3265 * Adds a window object with standard setup.
3266 * Parameters:
3267
3268 * @li @p name - The name of the window;
3269
3270 * @li @p title - The title for the window.
3271
3272 * This creates a window but also puts in a standard background with
3273 * @p elm_bg_add(), as well as setting the window title to @p
3274 * title. The window type created is of type @c ELM_WIN_BASIC, with
3275 * the @c NULL as the parent widget. Returns the created object or @c
3276 * NULL on failure.
3277
3278 * The autohide works similarly to @p autodel, automatically handling
3279 * "delete,request" signals when set to @p true, with the difference
3280 * that it will hide the window, instead of destroying it.
3281
3282 * It is specially designed to work together with @p
3283 * ELM_POLICY_QUIT_LAST_WINDOW_HIDDEN which allows exiting
3284 * Elementary's main loop when all the windows are hidden.
3285
3286 * @skip ::elm::win
3287 * @until autohide_set
3288
3289 * @note @p autodel and @a autohide are not mutually exclusive. The
3290 * window will be destructed if both autodel and autohide is set to @p
3291 * EINA_TRUE or @p true.
3292
3293 * For this example we're using a label that will display the text
3294 * "Getting location ...". First we'll create our label, setting it's
3295 * parent, then setting the following label's options:
3296
3297 * @li @p line_wrap_set: Set the wrapping behavior of the label, by
3298 * default no wrapping is done. Possible values for wrap are:
3299 * @p ELM_WRAP_NONE - No wrapping;
3300 * @p ELM_WRAP_CHAR - wrap between characters;
3301 * @p ELM_WRAP_WORD - wrap between words;
3302 * @p ELM_WRAP_MIXED - Word wrap, and if that fails, char wrap.
3303
3304 * @ skipline wrap
3305
3306 * @li @p text_set: Set the text that label will display.
3307
3308 * @skipline text
3309
3310 * @li @p slide_mode_set: Set the slide mode of the label widget. By
3311 * default, slide mode is none. Possible values for mode are:
3312
3313 * ELM_LABEL_SLIDE_MODE_NONE - no slide effect
3314
3315 * ELM_LABEL_SLIDE_MODE_AUTO - slide only if the label area is bigger
3316 * than the text width length
3317
3318 * ELM_LABEL_SLIDE_MODE_ALWAYS -slide always
3319
3320 * @attention ELM_LABEL_SLIDE_MODE_AUTO, ELM_LABEL_SLIDE_MODE_ALWAYS
3321 * only work with the themes "slide_short", "slide_long" and
3322 * "slide_bounce". ELM_LABEL_SLIDE_MODE_AUTO,
3323 * ELM_LABEL_SLIDE_MODE_ALWAYS don't work if the line
3324 * wrap(elm_label_line_wrap_set()) or
3325 * ellipsis(elm_label_ellipsis_set()) is set.
3326
3327 * @skipline slide
3328
3329 * To better understand, the function @c size_hint_weight_set for C++
3330 * bindings originated from C bindings function
3331 * evas_object_size_hint_weight_set, that is EFL Evas type function.
3332 * With this function we set the hints for an object's weight. The
3333 * parameters are:
3334
3335 * @li x - Nonnegative double value to use as horizontal weight hint.
3336
3337 * @li y - Nonnegative double value to use as vertical weight hint.
3338
3339 * This is not a size enforcement in any way, it's just a hint that
3340 * should be used whenever appropriate. This is a hint on how a
3341 * container object should resize a given child within its area.
3342
3343 * Containers may adhere to the simpler logic of just expanding the
3344 * child object's dimensions to fit its own (see the EVAS_HINT_EXPAND
3345 * helper weight macro in the EFL Evas Documentation) or the complete
3346 * one of taking each child's weight hint as real weights to how much
3347 * of its size to allocate for them in each axis. A container is
3348 * supposed to, after normalizing the weights of its children (with
3349 * weight hints), distribute the space it has to layout them by those
3350 * factors – most weighted children get larger in this process than
3351 * the least ones.
3352
3353 * @dontinclude location_cxx_example_01.cc
3354 * @skipline weight_set
3355
3356 * @note Default weight hint values are 0.0, for both axis.
3357
3358 * The function @c size_hint_align_set for C++ bindings originated
3359 * from C bindings function evas_object_size_hint_align_set, that is
3360 * EFL Evas type function. With this function we set the hints for an
3361 * object's alignment. The parameters are:
3362
3363 * @li x - Double, ranging from 0.0 to 1.0 or with the special value
3364 * EVAS_HINT_FILL, to use as horizontal alignment hint.
3365
3366 * @li y - Double, ranging from 0.0 to 1.0 or with the special value
3367 * EVAS_HINT_FILL, to use as vertical alignment hint.
3368
3369 * These are hints on how to align an object inside the boundaries of
3370 * a container/manager. Accepted values are in the 0.0 to 1.0 range,
3371 * with the special value EVAS_HINT_FILL used to specify "justify" or
3372 * "fill" by some users. In this case, maximum size hints should be
3373 * enforced with higher priority, if they are set. Also, any padding
3374 * hint set on objects should add up to the alignment space on the
3375 * final scene composition.
3376
3377 * For the horizontal component, 0.0 means to the left, 1.0 means to
3378 * the right. Analogously, for the vertical component, 0.0 to the top,
3379 * 1.0 means to the bottom.
3380
3381 * This is not a size enforcement in any way, it's just a hint that
3382 * should be used whenever appropriate.
3383
3384 * @note Default alignment hint values are 0.5, for both axis.
3385
3386 * @skipline align_set
3387
3388 * Setting the size for label and make it visible.
3389
3390 * @skip size
3391 * @until visibility
3392
3393 * Going back to our elocation, first we'll create an address
3394 * and position object that we'll use for all our operations.
3395
3396 * @skip address
3397 * @until position
3398
3399 * We also have to register our callback so we get updates later on.
3400
3401 * @skipline ecore
3402
3403 * Now we need to get the elocation position and print it, using our
3404 * label. This fills in the object with the data from GeoClue.
3405
3406 * @skip elocation
3407 * @until print
3408
3409 * Now we only have to set the size for our window and make it
3410 * visible.
3411
3412 * @skip size_set
3413 * @until visibility_set
3414
3415 * And finally, start the elm mainloop, starting to handle events and
3416 * drawing operations.
3417
3418 * @skip elm_run
3419 * @until ELM_MAIN
3420
3421 * The full code for this example can be found at @ref location_cxx_example_01.cc
3422
3423 * @example location_cxx_example_01.cc
3424 */
3425
3426
3427/**
3428 * @page menu_cxx_example_01 Menu Example with C++ Binding
3429 * @dontinclude menu_cxx_example_01.cc
3430
3431 * This example shows how to create a menu with regular items, object
3432 * items, submenus and how to delete items from a menu.
3433
3434 * The first part consists of including the headers. We'll include @p
3435 * Elementary.hh, @p Eina.hh and @p Evas.hh, that are C++ bindings
3436 * that are needed in this example.
3437
3438 * @skip Elementary
3439 * @until Evas
3440
3441 * Starting the main code and initializing Eina C++ Lybrary, always
3442 * initiate Eina when included. We'll also initialize a couple of
3443 * pointers.
3444
3445 * @skip EAPI
3446 * @until menu_it
3447
3448 * Now let's set the elm_policy, which defines for a given policy
3449 * group/identifier a new policy's value, respectively. In this
3450 * example the only policy we need to set a value for is @c
3451 * ELM_POLICY_QUIT, possibles values for it are:
3452
3453 * @li @p ELM_POLICY_QUIT_NONE: Never quit the application
3454 * automatically;
3455
3456 * @li @p ELM_POLICY_QUIT_LAST_WINDOW_CLOSED: quit when the
3457 * application's last window is closed;
3458
3459 * @li @p ELM_POLICY_QUIT_LAST_WINDOW_HIDDEN : quit when the
3460 * application's last window is hidden;
3461
3462 * @skipline elm_policy_set
3463
3464 * As you can see, the policy we chose was to quit when the last win
3465 * is hidden as opose to examples with the C bindings where we
3466 * perpetually set it to quit when last win was closed. This changed
3467 * was necessary because in C++ binding as the elm mainloop stop
3468 * running all object are destroyed, references are unreferenced and
3469 * events are stopped at ELM_MAIN().
3470
3471 * @see For more details consult elm_policy_set
3472
3473 * Next step is creating an elementary window, in this example we use
3474 * the C++ binding method with the elm_win_util_standard_add that is a
3475 * elm_win_legacy function, better explained below. And then we set
3476 * the autohide state for it.
3477
3478 * @p elm_win_util_standard_add (const char *name, const char *tittle)
3479 * Adds a window object with standard setup.
3480 * Parameters:
3481
3482 * @li @p name - The name of the window;
3483
3484 * @li @p title - The title for the window.
3485
3486 * This creates a window but also puts in a standard background with
3487 * @p elm_bg_add(), as well as setting the window title to @p
3488 * title. The window type created is of type @c ELM_WIN_BASIC, with
3489 * the @c NULL as the parent widget. Returns the created object or @c
3490 * NULL on failure.
3491
3492 * The autohide works similarly to @p autodel, automatically handling
3493 * "delete,request" signals when set to @p true, with the difference
3494 * that it will hide the window, instead of destroying it.
3495
3496 * It is specially designed to work together with @p
3497 * ELM_POLICY_QUIT_LAST_WINDOW_HIDDEN which allows exiting
3498 * Elementary's main loop when all the windows are hidden.
3499
3500 * @skip ::elm::win
3501 * @until autohide_set
3502
3503 * @note @p autodel and @a autohide are not mutually exclusive. The
3504 * window will be destructed if both autodel and autohide is set to @p
3505 * EINA_TRUE or @p true.
3506
3507 * Next we'll create a evas::rectangle to use as the icon of our menu
3508 * for thus using the C++ method, adding our rect as a resize-object
3509 * to win informing that when the size of the win changes so should
3510 * the box's size.
3511
3512 * @skip evas
3513 * @until resize
3514
3515 * We'll also set, for rect, the hint for it's minimum size, it's
3516 * color and making it visible.
3517
3518 * @skip size
3519 * @until visibility
3520
3521 * Creating the menu using the C++ method, setting it's parent and
3522 * adding an item to this menu. We are going to add more items, but
3523 * these icons are going to have a parent, which will put them in a
3524 * sub-menu.
3525
3526 * @skip menu
3527 * @until "menu 1"
3528
3529 * We'll add a button to a menu_item, where this button will delete
3530 * the first item of our sub-menu when clicked, we'll do this
3531 * using @p elm_object_item_content_set().
3532
3533 * @skip button
3534 * @until content_set
3535
3536 * Now, for the callback that will be used in this button we're use
3537 * lambda type function and then add as clicked callback to button.
3538
3539 * @skip del_it
3540 * @until clicked
3541
3542 * @see To learn more about consult @ref lambda.
3543
3544 * We now add a separator and three more regular items:
3545
3546 * @until item_add
3547 * @until item_add
3548 * @until item_add
3549
3550 * We now add another item, however this time it won't go the sub-menu
3551 * and it'll be disabled:
3552
3553 * @until disabled_set
3554
3555 * To make sure that our menu is shown whenever the window is
3556 * clicked, we use the following callback, also lambda:
3557
3558 * @skip show
3559 * @until ( show );
3560
3561 * Finally. we just make menu visible, set a size for our window
3562 * making it visible and then start the elm mainloop, starting to
3563 * handle events and drawing operations.
3564
3565 * @skip visibility
3566 * @until ELM_MAIN
3567
3568 * Our example will look like this:
3569
3570 * @image html screenshots/menu_cxx_example_01.png
3571 * @image latex screenshots/menu_cxx_example_01.eps width=\textwidth
3572
3573 * @example menu_cxx_example_01.cc
3574 */
3575
3576/**
3577 * @page popup_cxx_example_01 Popup example with C++ Binding
3578 * @dontinclude popup_cxx_example_01.cc
3579
3580 * The first part consists of including the headers. In this
3581 * case we are only working with the Elementary C++ binding and thus
3582 * we need only to include him.
3583
3584 * @skipline Elementary.hh
3585
3586 * @attention If necessary the C and/or the C++ headers should be
3587 * include here as well.
3588
3589 * Now we need to actually start the code and set the elm_policy,
3590 * which defines for a given policy group/identifier a new policy's
3591 * value, respectively. In this example the only policy we need to
3592 * set a value for is @c ELM_POLICY_QUIT, possibles values for it are:
3593
3594 * @li @p ELM_POLICY_QUIT_NONE: Never quit the application
3595 * automatically;
3596
3597 * @li @p ELM_POLICY_QUIT_LAST_WINDOW_CLOSED: quit when the
3598 * application's last window is closed;
3599
3600 * @li @p ELM_POLICY_QUIT_LAST_WINDOW_HIDDEN : quit when the
3601 * application's last window is hidden;
3602
3603 * @skip EAPI_MAIN
3604 * @until elm_policy_set
3605
3606 * As you can see, the policy we chose was to quit when the last win
3607 * is hidden as opose to examples with the C bindings where we
3608 * perpetually set it to quit when last win was closed. This changed
3609 * was necessary because in C++ binding as the elm mainloop stop
3610 * running all object are destroyed, references are unreferenced and
3611 * events are stopped at ELM_MAIN().
3612
3613 * @see For more details consult elm_policy_set
3614
3615 * Next step is creating an Elementary window, in this example we use
3616 * the C++ binding method with the elm_win_util_standard_add that is a
3617 * elm_win_legacy function, better explained below. And then we set
3618 * the autohide state for it.
3619
3620 * @p elm_win_util_standard_add (const char *name, const char *tittle)
3621 * Adds a window object with standard setup.
3622
3623 * Parameters:
3624
3625 * @li @p name - The name of the window;
3626
3627 * @li @p title - The title for the window.
3628
3629 * This creates a window but also puts in a standard background with
3630 * @p elm_bg_add(), as well as setting the window title to @p
3631 * title. The window type created is of type @c ELM_WIN_BASIC, with
3632 * the @c NULL as the parent widget. Returns the created object or @c
3633 * NULL on failure.
3634
3635 * The autohide works similarly to @p autodel, automatically handling
3636 * "delete,request" signals when set to @p true, with the difference
3637 * that it will hide the window, instead of destroying it.
3638
3639 * It is specially designed to work together with @p
3640 * ELM_POLICY_QUIT_LAST_WINDOW_HIDDEN which allows exiting
3641 * Elementary's main loop when all the windows are hidden.
3642
3643 * @skip ::elm::win
3644 * @until autohide_set
3645
3646 * @note @p autodel and @a autohide are not mutually exclusive. The
3647 * window will be destructed if both autodel and autohide is set to @p
3648 * EINA_TRUE or @p true.
3649
3650 * Now let's create the label with the C++ binding method, passing our
3651 * window object as parent. We'll also set to this label the text that
3652 * we'll use later on the popup.
3653
3654 * @skip elm::label
3655 * @until text
3656
3657 * Using the same method we'll create our popup passing our window
3658 * object as parent. We'll also set the timeout to 3.0 seconds, label
3659 * as content, the title and visibility true for our popup.
3660
3661 * @skip elm::popup
3662 * @until visibility
3663
3664 * Our popup will hide every time the lambda type function is called.
3665 * The lambda function get the popup object by reference and set it's
3666 * visibility to false, making it invisible. In this example we are
3667 * using @a std::bind to bind the parameters of our lambda function to
3668 * return as @a std::function object to popup_hide which was declare
3669 * as auto.
3670
3671 * @skip popup_hide
3672 * @until });
3673
3674 * To learn more consult @ref lambda.
3675
3676 * In this example we'll add the popup_hide in the timeout callback
3677 * and the block_clicked callback. This results in hiding the popup in
3678 * maximum of 3.0 seconds or when the popup block is clicked.
3679
3680 * @skip timeout
3681 * @until block
3682
3683 * Finally we just have to make our window visible and set it's size,
3684 * then run the elm mainloop, starting to handle events and drawing
3685 * operations.
3686
3687 * @skip visibility
3688 * @until ELM_MAIN
3689
3690 * This example will initially look like this:
3691
3692 * @image html screenshots/popup_cxx_example_01.png
3693 * @image latex screenshots/popup_cxx_example_01.eps width=\textwidth
3694
3695 * Once the popup is hidden after timeout:
3696
3697 * @image html screenshots/popup_cxx_example_01_a.png
3698 * @image latex screenshots/popup_cxx_example_01_a.eps width=\textwidth
3699
3700 * @example popup_cxx_example_01.cc
3701 */
3702
3703/**
3704 * @page radio_cxx_example_01 Radio example with C++ Binding
3705 * @dontinclude radio_cxx_example_01.cc
3706
3707 * In this example we will create 4 radios, and add them to the same
3708 * group. We will also have the radios in the group change the value
3709 * of a variable directly and have then print it when the value
3710 * changes.
3711
3712 * The first part consists of including the headers. In this
3713 * case we are only working with the Elementary C++ binding and thus
3714 * we need only to include him.
3715
3716 * @skipline Elementary.hh
3717
3718 * @attention If necessary the C and/or the C++ headers should be
3719 * include here as well.
3720
3721 * Now we need to actually start the code and set the elm_policy,
3722 * which defines for a given policy group/identifier a new policy's
3723 * value, respectively. In this example the only policy we need to
3724 * set a value for is @c ELM_POLICY_QUIT, possibles values for it are:
3725
3726 * @li @p ELM_POLICY_QUIT_NONE: Never quit the application
3727 * automatically;
3728
3729 * @li @p ELM_POLICY_QUIT_LAST_WINDOW_CLOSED: quit when the
3730 * application's last window is closed;
3731
3732 * @li @p ELM_POLICY_QUIT_LAST_WINDOW_HIDDEN : quit when the
3733 * application's last window is hidden;
3734
3735 * @skip EAPI_MAIN
3736 * @until elm_policy_set
3737
3738 * As you can see, the policy we chose was to quit when the last win
3739 * is hidden as opose to examples with the C bindings where we
3740 * perpetually set it to quit when last win was closed. This changed
3741 * was necessary because in C++ binding as the elm mainloop stop
3742 * running all object are destroyed, references are unreferenced and
3743 * events are stopped at ELM_MAIN().
3744
3745 * @see For more details consult elm_policy_set
3746
3747 * And move right to declaring a static variable, the one whose value
3748 * the radios will change:
3749
3750 * @skipline static
3751
3752 * Next step is creating an Elementary window, in this example we use
3753 * the C++ binding method with the elm_win_util_standard_add that is a
3754 * elm_win_legacy function, better explained below. And then we set
3755 * the autohide state for it.
3756
3757 * @p elm_win_util_standard_add (const char *name, const char *tittle)
3758 * Adds a window object with standard setup.
3759
3760 * Parameters:
3761
3762 * @li @p name - The name of the window;
3763
3764 * @li @p title - The title for the window.
3765
3766 * This creates a window but also puts in a standard background with
3767 * @p elm_bg_add(), as well as setting the window title to @p
3768 * title. The window type created is of type @c ELM_WIN_BASIC, with
3769 * the @c NULL as the parent widget. Returns the created object or @c
3770 * NULL on failure.
3771
3772 * The autohide works similarly to @p autodel, automatically handling
3773 * "delete,request" signals when set to @p true, with the difference
3774 * that it will hide the window, instead of destroying it.
3775
3776 * It is specially designed to work together with @p
3777 * ELM_POLICY_QUIT_LAST_WINDOW_HIDDEN which allows exiting
3778 * Elementary's main loop when all the windows are hidden.
3779
3780 * @skip ::elm::win
3781 * @until autohide_set
3782
3783 * @note @p autodel and @a autohide are not mutually exclusive. The
3784 * window will be destructed if both autodel and autohide is set to @p
3785 * EINA_TRUE or @p true.
3786
3787 * A box arranges objects in a linear fashion, governed by a layout
3788 * function that defines the details of this arrangement. The box will
3789 * use an internal function to set the layout to a single row,
3790 * vertical by default.
3791
3792 * Now let's create the box with the C++ binding method, passing our
3793 * window object as parent and then setting box's layout as
3794 * horizontal.
3795
3796 * @skipline elm::box
3797 * @until horizontal
3798
3799 * To better understand, the function @c size_hint_weight_set for C++
3800 * bindings originated from C bindings function
3801 * evas_object_size_hint_weight_set, that is EFL Evas type function.
3802 * With this function we set the hints for an object's weight. The
3803 * parameters are:
3804
3805 * @li x - Nonnegative double value to use as horizontal weight hint.
3806
3807 * @li y - Nonnegative double value to use as vertical weight hint.
3808
3809 * This is not a size enforcement in any way, it's just a hint that
3810 * should be used whenever appropriate. This is a hint on how a
3811 * container object should resize a given child within its area.
3812
3813 * Containers may adhere to the simpler logic of just expanding the
3814 * child object's dimensions to fit its own (see the EVAS_HINT_EXPAND
3815 * helper weight macro in the EFL Evas Documentation) or the complete
3816 * one of taking each child's weight hint as real weights to how much
3817 * of its size to allocate for them in each axis. A container is
3818 * supposed to, after normalizing the weights of its children (with
3819 * weight hints), distribute the space it has to layout them by those
3820 * factors – most weighted children get larger in this process than
3821 * the least ones.
3822
3823 * @skipline weight_set
3824
3825 * @note Default weight hint values are 0.0, for both axis.
3826
3827 * Now we add the box as a resize_object to win informing that when
3828 * the size of the win changes so should the box's size. And finally
3829 * we make it visible.
3830
3831 * @skip win
3832 * @until visibility_set
3833
3834 * Radio is a widget that allows for one or more options to be
3835 * displayed and have the user choose only one of them. It contains an
3836 * indicator, an optional label and an optional icon object. While
3837 * it's possible to have a group of only one radio they, are normally
3838 * used in groups of 2 or more.
3839
3840 * We will create the box with the C++ binding method, passing our
3841 * window object as parent and then setting box's layout as
3842 * horizontal.
3843
3844 * And now we create a radio with the C++ binding method, passing our
3845 * window object as parent. Since this is the first radio in our group
3846 * we set the group to be the radio, so we can set the other radios in
3847 * the same group.
3848
3849 * @skip radio
3850 * @until radio;
3851
3852 * We also set the text, then state value of this radio to 1 and
3853 * the value pointer to @p val, since val is @p 1 this has the
3854 * additional effect of setting the radio value to @p 1.
3855
3856 * @skip text
3857 * @until pointer
3858
3859 * For this radio we choose the standard home icon, the icon will be
3860 * created with the same method and setting the icon as content of
3861 * radio.
3862
3863 * @skip icon
3864 * @until content
3865
3866 * When using the elm::box the packing method of the subobj - radio
3867 * in this case - should be defined. There are four possible methods: