src/lib/Elementary.h.in

   1 /*
   2  *
   3  * vim:ts=8:sw=3:sts=3:expandtab:cino=>5n-3f0^-2{2(0W1st0
   4  */
   5
   6 /**
   7 @file Elementary.h.in
   8 @brief Elementary Widget Library
   9 */
  10
  11 /**
  12 @mainpage Elementary
  13 @image html  elementary.png
  14 @version 0.8.0
  15 @date 2008-2011
  16
  17 @section intro What is Elementary?
  18
  19 This is a VERY SIMPLE toolkit. It is not meant for writing extensive desktop
  20 applications (yet). Small simple ones with simple needs.
  21
  22 It is meant to make the programmers work almost brainless but give them lots
  23 of flexibility.
  24
  25 @li @ref Start - Go here to quickly get started with writing Apps
  26
  27 @section organization Organization
  28
  29 One can divide Elemementary into three main groups:
  30 @li @ref infralist - These are modules that deal with Elementary as a whole.
  31 @li @ref widgetslist - These are the widgets you'll compose your UI out of.
  32 @li @ref containerslist - These are the containers which hold the widgets.
  33
  34 @section license License
  35
  36 LGPL v2 (see COPYING in the base of Elementary's source). This applies to
  37 all files in the source tree.
  38
  39 @section ack Acknowledgements
  40 There is a lot that goes into making a widget set, and they don't happen out of
  41 nothing. It's like trying to make everyone everywhere happy, regardless of age,
  42 gender, race or nationality - and that is really tough. So thanks to people and
  43 organisations behind this, as listed in the @ref authors page.
  44 */
  45
  46
  47 /**
  48  * @defgroup Start Getting Started
  49  *
  50  * To write an Elementary app, you can get started with the following:
  51  *
  52 @code
  53 #include <Elementary.h>
  54 EAPI_MAIN int
  55 elm_main(int argc, char **argv)
  56 {
  57    // create window(s) here and do any application init
  58    elm_run(); // run main loop
  59    elm_shutdown(); // after mainloop finishes running, shutdown
  60    return 0; // exit 0 for exit code
  61 }
  62 ELM_MAIN()
  63 @endcode
  64  *
  65  * To use autotools (which helps in many ways in the long run, like being able
  66  * to immediately create releases of your software directly from your tree
  67  * and ensure everything needed to build it is there) you will need a
  68  * configure.ac, Makefile.am and autogen.sh file.
  69  *
  70  * configure.ac:
  71  *
  72 @verbatim
  73 AC_INIT(myapp, 0.0.0, myname@mydomain.com)
  74 AC_PREREQ(2.52)
  75 AC_CONFIG_SRCDIR(configure.ac)
  76 AM_CONFIG_HEADER(config.h)
  77 AC_PROG_CC
  78 AM_INIT_AUTOMAKE(1.6 dist-bzip2)
  79 PKG_CHECK_MODULES([ELEMENTARY], elementary)
  80 AC_OUTPUT(Makefile)
  81 @endverbatim
  82  *
  83  * Makefile.am:
  84  *
  85 @verbatim
  86 AUTOMAKE_OPTIONS = 1.4 foreign
  87 MAINTAINERCLEANFILES = Makefile.in aclocal.m4 config.h.in configure depcomp install-sh missing
  88
  89 INCLUDES = -I$(top_srcdir)
  90
  91 bin_PROGRAMS = myapp
  92
  93 myapp_SOURCES = main.c
  94 myapp_LDADD = @ELEMENTARY_LIBS@
  95 myapp_CFLAGS = @ELEMENTARY_CFLAGS@
  96 @endverbatim
  97  *
  98  * autogen.sh:
  99  *
 100 @verbatim
 101 #!/bin/sh
 102 echo "Running aclocal..." ; aclocal $ACLOCAL_FLAGS || exit 1
 103 echo "Running autoheader..." ; autoheader || exit 1
 104 echo "Running autoconf..." ; autoconf || exit 1
 105 echo "Running automake..." ; automake --add-missing --copy --gnu || exit 1
 106 ./configure "$@"
 107 @endverbatim
 108  *
 109  * To generate all the things needed to bootstrap just run:
 110  *
 111 @verbatim
 112 ./autogen.sh
 113 @endverbatim
 114  *
 115  * This will generate Makefile.in's, the confgure script and everything else.
 116  * After this it works like all normal autotools projects:
 117 @verbatim
 118 ./configure
 119 make
 120 sudo make install
 121 @endverbatim
 122  *
 123  * Note sudo was assumed to get root permissions, as this would install in
 124  * /usr/local which is system-owned. Use any way you like to gain root, or
 125  * specify a different prefix with configure:
 126  *
 127 @verbatim
 128 ./confiugre --prefix=$HOME/mysoftware
 129 @endverbatim
 130  *
 131  * Also remember that autotools buys you some useful commands like:
 132 @verbatim
 133 make uninstall
 134 @endverbatim
 135  *
 136  * This uninstalls the software after it was installed with "make install".
 137  * It is very useful to clear up what you built if you wish to clean the
 138  * system.
 139  *
 140 @verbatim
 141 make distcheck
 142 @endverbatim
 143  *
 144  * This firstly checks if your build tree is "clean" and ready for
 145  * distribution. It also builds a tarball (myapp-0.0.0.tar.gz) that is
 146  * ready to upload and distribute to the world, that contains the generated
 147  * Makefile.in's and configure script. The users do not need to run
 148  * autogen.sh - just configure and on. They don't need autotools installed.
 149  * This tarball also builds cleanly, has all the sources it needs to build
 150  * included (that is sources for your application, not libraries it depends
 151  * on like Elementary). It builds cleanly in a buildroot and does not
 152  * contain any files that are temporarily generated like binaries and other
 153  * build-generated files, so the tarball is clean, and no need to worry
 154  * about cleaning up your tree before packaging.
 155  *
 156 @verbatim
 157 make clean
 158 @endverbatim
 159  *
 160  * This cleans up all build files (binaries, objects etc.) from the tree.
 161  *
 162 @verbatim
 163 make distclean
 164 @endverbatim
 165  *
 166  * This cleans out all files from the build and from configure's output too.
 167  *
 168 @verbatim
 169 make maintainer-clean
 170 @endverbatim
 171  *
 172  * This deletes all the files autogen.sh will produce so the tree is clean
 173  * to be put into a revision-control system (like CVS, SVN or GIT for example).
 174  *
 175  * There is a more advanced way of making use of the quicklaunch infrastructure
 176  * in Elementary (which will not be covered here due to its more advanced
 177  * nature).
 178  *
 179  * Now let's actually create an interactive "Hello World" gui that you can
 180  * click the ok button to exit. It's more code because this now does something
 181  * much more significant, but it's still very simple:
 182  *
 183 @code
 184 #include <Elementary.h>
 185
 186 static void
 187 on_done(void *data, Evas_Object *obj, void *event_info)
 188 {
 189    // quit the mainloop (elm_run function will return)
 190    elm_exit();
 191 }
 192
 193 EAPI_MAIN int
 194 elm_main(int argc, char **argv)
 195 {
 196    Evas_Object *win, *bg, *box, *lab, *btn;
 197
 198    // new window - do the usual and give it a name (hello) and title (Hello)
 199    win = elm_win_util_standard_add("hello", "Hello");
 200    // when the user clicks "close" on a window there is a request to delete
 201    evas_object_smart_callback_add(win, "delete,request", on_done, NULL);
 202
 203    // add a box object - default is vertical. a box holds children in a row,
 204    // either horizontally or vertically. nothing more.
 205    box = elm_box_add(win);
 206    // make the box hotizontal
 207    elm_box_horizontal_set(box, EINA_TRUE);
 208    // add object as a resize object for the window (controls window minimum
 209    // size as well as gets resized if window is resized)
 210    elm_win_resize_object_add(win, box);
 211    evas_object_show(box);
 212
 213    // add a label widget, set the text and put it in the pad frame
 214    lab = elm_label_add(win);
 215    // set default text of the label
 216    elm_object_text_set(lab, "Hello out there world!");
 217    // pack the label at the end of the box
 218    elm_box_pack_end(box, lab);
 219    evas_object_show(lab);
 220
 221    // add an ok button
 222    btn = elm_button_add(win);
 223    // set default text of button to "OK"
 224    elm_object_text_set(btn, "OK");
 225    // pack the button at the end of the box
 226    elm_box_pack_end(box, btn);
 227    evas_object_show(btn);
 228    // call on_done when button is clicked
 229    evas_object_smart_callback_add(btn, "clicked", on_done, NULL);
 230
 231    // now we are done, show the window
 232    evas_object_show(win);
 233
 234    // run the mainloop and process events and callbacks
 235    elm_run();
 236    elm_shutdown();
 237    return 0;
 238 }
 239 ELM_MAIN()
 240 @endcode
 241    *
 242    */
 243
 244 /**
 245 @page authors Authors
 246 @author Carsten Haitzler <raster@@rasterman.com>
 247 @author Gustavo Sverzut Barbieri <barbieri@@profusion.mobi>
 248 @author Cedric Bail <cedric.bail@@free.fr>
 249 @author Vincent Torri <vtorri@@univ-evry.fr>
 250 @author Daniel Kolesa <quaker66@@gmail.com>
 251 @author Jaime Thomas <avi.thomas@@gmail.com>
 252 @author Swisscom - http://www.swisscom.ch/
 253 @author Christopher Michael <devilhorns@@comcast.net>
 254 @author Marco Trevisan (Treviño) <mail@@3v1n0.net>
 255 @author Michael Bouchaud <michael.bouchaud@@gmail.com>
 256 @author Jonathan Atton (Watchwolf) <jonathan.atton@@gmail.com>
 257 @author Brian Wang <brian.wang.0721@@gmail.com>
 258 @author Mike Blumenkrantz (discomfitor/zmike) <michael.blumenkrantz@@gmail.com>
 259 @author Samsung Electronics <tbd>
 260 @author Samsung SAIT <tbd>
 261 @author Brett Nash <nash@@nash.id.au>
 262 @author Bruno Dilly <bdilly@@profusion.mobi>
 263 @author Rafael Fonseca <rfonseca@@profusion.mobi>
 264 @author Chuneon Park <hermet@@hermet.pe.kr>
 265 @author Woohyun Jung <wh0705.jung@@samsung.com>
 266 @author Jaehwan Kim <jae.hwan.kim@@samsung.com>
 267 @author Wonguk Jeong <wonguk.jeong@@samsung.com>
 268 @author Leandro A. F. Pereira <leandro@@profusion.mobi>
 269 @author Helen Fornazier <helen.fornazier@@profusion.mobi>
 270 @author Gustavo Lima Chaves <glima@@profusion.mobi>
 271 @author Fabiano Fidêncio <fidencio@@profusion.mobi>
 272 @author Tiago Falcão <tiago@@profusion.mobi>
 273 @author Otavio Pontes <otavio@@profusion.mobi>
 274 @author Viktor Kojouharov <vkojouharov@@gmail.com>
 275 @author Daniel Juyung Seo (SeoZ) <juyung.seo@@samsung.com> <seojuyung2@@gmail.com>
 276 @author Sangho Park <sangho.g.park@@samsung.com> <gouache95@@gmail.com>
 277 @author Rajeev Ranjan (Rajeev) <rajeev.r@@samsung.com> <rajeev.jnnce@@gmail.com>
 278 @author Seunggyun Kim <sgyun.kim@@samsung.com> <tmdrbs@@gmail.com>
 279 @author Sohyun Kim <anna1014.kim@@samsung.com> <sohyun.anna@@gmail.com>
 280 @author Jihoon Kim <jihoon48.kim@@samsung.com>
 281 @author Jeonghyun Yun (arosis) <jh0506.yun@@samsung.com>
 282 @author Tom Hacohen <tom@@stosb.com>
 283 @author Aharon Hillel <a.hillel@@partner.samsung.com>
 284 @author Jonathan Atton (Watchwolf) <jonathan.atton@@gmail.com>
 285 @author Shinwoo Kim <kimcinoo@@gmail.com>
 286 @author Govindaraju SM <govi.sm@@samsung.com> <govism@@gmail.com>
 287 @author Prince Kumar Dubey <prince.dubey@@samsung.com> <prince.dubey@@gmail.com>
 288 @author Sung W. Park <sungwoo@@gmail.com>
 289 @author Thierry el Borgi <thierry@@substantiel.fr>
 290 @author Shilpa Singh <shilpa.singh@@samsung.com> <shilpasingh.o@@gmail.com>
 291 @author Chanwook Jung <joey.jung@@samsung.com>
 292 @author Hyoyoung Chang <hyoyoung.chang@@samsung.com>
 293 @author Guillaume "Kuri" Friloux <guillaume.friloux@@asp64.com>
 294 @author Kim Yunhan <spbear@@gmail.com>
 295 @author Bluezery <ohpowel@@gmail.com>
 296 @author Nicolas Aguirre <aguirre.nicolas@@gmail.com>
 297 @author Sanjeev BA <iamsanjeev@@gmail.com>
 298
 299 Please contact <enlightenment-devel@lists.sourceforge.net> to get in
 300 contact with the developers and maintainers.
 301  */
 302
 303 #ifndef ELEMENTARY_H
 304 #define ELEMENTARY_H
 305
 306 /**
 307  * @file Elementary.h
 308  * @brief Elementary's API
 309  *
 310  * Elementary API.
 311  */
 312
 313 @ELM_UNIX_DEF@ ELM_UNIX
 314 @ELM_WIN32_DEF@ ELM_WIN32
 315 @ELM_WINCE_DEF@ ELM_WINCE
 316 @ELM_EDBUS_DEF@ ELM_EDBUS
 317 @ELM_EFREET_DEF@ ELM_EFREET
 318 @ELM_ETHUMB_DEF@ ELM_ETHUMB
 319 @ELM_WEB_DEF@ ELM_WEB
 320 @ELM_EMAP_DEF@ ELM_EMAP
 321 @ELM_DEBUG_DEF@ ELM_DEBUG
 322 @ELM_ALLOCA_H_DEF@ ELM_ALLOCA_H
 323 @ELM_LIBINTL_H_DEF@ ELM_LIBINTL_H
 324 @ELM_DIRENT_H_DEF@ ELM_DIRENT_H
 325
 326 /* Standard headers for standard system calls etc. */
 327 #include <stdio.h>
 328 #include <stdlib.h>
 329 #include <unistd.h>
 330 #include <string.h>
 331 #include <sys/types.h>
 332 #include <sys/stat.h>
 333 #include <sys/time.h>
 334 #include <sys/param.h>
 335 #include <math.h>
 336 #include <fnmatch.h>
 337 #include <limits.h>
 338 #include <ctype.h>
 339 #include <time.h>
 340 #ifdef ELM_DIRENT_H
 341 # include <dirent.h>
 342 #endif
 343 #include <pwd.h>
 344 #include <errno.h>
 345
 346 #ifdef ELM_UNIX
 347 # include <locale.h>
 348 # ifdef ELM_LIBINTL_H
 349 #  include <libintl.h>
 350 # endif
 351 # include <signal.h>
 352 # include <grp.h>
 353 # include <glob.h>
 354 #endif
 355
 356 #ifdef ELM_ALLOCA_H
 357 # include <alloca.h>
 358 #endif
 359
 360 #if defined (ELM_WIN32) || defined (ELM_WINCE)
 361 # include <malloc.h>
 362 # ifndef alloca
 363 #  define alloca _alloca
 364 # endif
 365 #endif
 366
 367
 368 /* EFL headers */
 369 #include <Eina.h>
 370 #include <Eet.h>
 371 #include <Evas.h>
 372 #include <Evas_GL.h>
 373 #include <Ecore.h>
 374 #include <Ecore_Evas.h>
 375 #include <Ecore_File.h>
 376 @ELEMENTARY_ECORE_IMF_INC@
 377 @ELEMENTARY_ECORE_CON_INC@
 378 #include <Edje.h>
 379
 380 #ifdef ELM_EDBUS
 381 # include <E_DBus.h>
 382 #endif
 383
 384 #ifdef ELM_EFREET
 385 # include <Efreet.h>
 386 # include <Efreet_Mime.h>
 387 # include <Efreet_Trash.h>
 388 #endif
 389
 390 #ifdef ELM_ETHUMB
 391 # include <Ethumb_Client.h>
 392 #endif
 393
 394 #ifdef ELM_EMAP
 395 # include <EMap.h>
 396 #endif
 397
 398 #ifdef EAPI
 399 # undef EAPI
 400 #endif
 401
 402 #ifdef _WIN32
 403 # ifdef ELEMENTARY_BUILD
 404 #  ifdef DLL_EXPORT
 405 #   define EAPI __declspec(dllexport)
 406 #  else
 407 #   define EAPI
 408 #  endif /* ! DLL_EXPORT */
 409 # else
 410 #  define EAPI __declspec(dllimport)
 411 # endif /* ! EFL_EVAS_BUILD */
 412 #else
 413 # ifdef __GNUC__
 414 #  if __GNUC__ >= 4
 415 #   define EAPI __attribute__ ((visibility("default")))
 416 #  else
 417 #   define EAPI
 418 #  endif
 419 # else
 420 #  define EAPI
 421 # endif
 422 #endif /* ! _WIN32 */
 423
 424 #ifdef _WIN32
 425 # define EAPI_MAIN
 426 #else
 427 # define EAPI_MAIN EAPI
 428 #endif
 429
 430 /* allow usage from c++ */
 431 #ifdef __cplusplus
 432 extern "C" {
 433 #endif
 434
 435 #define ELM_VERSION_MAJOR @VMAJ@
 436 #define ELM_VERSION_MINOR @VMIN@
 437
 438    typedef struct _Elm_Version
 439      {
 440         int major;
 441         int minor;
 442         int micro;
 443         int revision;
 444      } Elm_Version;
 445
 446    EAPI extern Elm_Version *elm_version;
 447
 448 /* include these first for general used definitions */
 449 #include <elm_general.h>
 450 #include <elm_object_item.h>
 451 #include <elm_tooltip.h>
 452
 453 /* special widgets - types used elsewhere */
 454 #include <elm_icon.h>
 455 #include <elm_scroller.h>
 456 #include <elm_entry.h>
 457 #include <elm_list.h>
 458
 459 /* other includes */
 460 #include <elc_anchorblock.h>
 461 #include <elc_anchorview.h>
 462 #include <elc_ctxpopup.h>
 463 #include <elc_fileselector_button.h>
 464 #include <elc_fileselector_entry.h>
 465 #include <elc_fileselector.h>
 466 #include <elc_hoversel.h>
 467 #include <elc_multibuttonentry.h>
 468 #include <elc_naviframe.h>
 469 #include <elm_actionslider.h>
 470 #include <elm_app.h>
 471 #include <elm_bg.h>
 472 #include <elm_box.h>
 473 #include <elm_bubble.h>
 474 #include <elm_button.h>
 475 #include <elm_cache.h>
 476 #include <elm_calendar.h>
 477 #include <elm_check.h>
 478 #include <elm_clock.h>
 479 #include <elm_cnp.h>
 480 #include <elm_colorselector.h>
 481 #include <elm_config.h>
 482 #include <elm_conform.h>
 483 #include <elm_cursor.h>
 484 #include <elm_debug.h>
 485 #include <elm_deprecated.h>
 486 #include <elm_diskselector.h>
 487 #include <elm_engine.h>
 488 #include <elm_factory.h>
 489 #include <elm_finger.h>
 490 #include <elm_flip.h>
 491 #include <elm_flipselector.h>
 492 #include <elm_focus.h>
 493 #include <elm_fonts.h>
 494 #include <elm_frame.h>
 495 #include <elm_gengrid.h>
 496 #include <elm_genlist.h>
 497 #include <elm_gesture_layer.h>
 498 #include <elm_glview.h>
 499 #include <elm_grid.h>
 500 #include <elm_hover.h>
 501 #include <elm_image.h>
 502 #include <elm_index.h>
 503 #include <elm_label.h>
 504 #include <elm_layout.h>
 505 #include <elm_macros.h>
 506 #include <elm_mapbuf.h>
 507 #include <elm_map.h>
 508 #include <elm_menu.h>
 509 #include <elm_mirroring.h>
 510 #include <elm_need.h>
 511 #include <elm_notify.h>
 512 #include <elm_object.h>
 513 #include <elm_pager.h>
 514 #include <elm_panel.h>
 515 #include <elm_panes.h>
 516 #include <elm_password.h>
 517 #include <elm_photocam.h>
 518 #include <elm_photo.h>
 519 #include <elm_progressbar.h>
 520 #include <elm_radio.h>
 521 #include <elm_route.h>
 522 #include <elm_scale.h>
 523 #include <elm_scroll.h>
 524 #include <elm_segment_control.h>
 525 #include <elm_separator.h>
 526 #include <elm_slider.h>
 527 #include <elm_slideshow.h>
 528 #include <elm_spinner.h>
 529 #include <elm_store.h>
 530 #include <elm_table.h>
 531 #include <elm_theme.h>
 532 #include <elm_thumb.h>
 533 #include <elm_toolbar.h>
 534 #include <elm_transit.h>
 535 #include <elm_video.h>
 536 #include <elm_web.h>
 537 #include <elm_win.h>
 538
 539 #ifdef __cplusplus
 540 }
 541 #endif
 542
 543 #endif