src/lib/elm_getting_started.h

   1 /**
   2  * @defgroup Start Getting Started
   3  *
   4  * To write an Elementary app, you can get started with the following:
   5  *
   6  * @code
   7  * #include <Elementary.h>
   8  * EAPI_MAIN int
   9  * elm_main(int argc, char **argv)
  10  * {
  11  *    // create window(s) here and do any application init
  12  *    elm_run(); // run main loop
  13  *    elm_shutdown(); // after mainloop finishes running, shutdown
  14  *    return 0; // exit 0 for exit code
  15  * }
  16  * ELM_MAIN()
  17  * @endcode
  18  *
  19  * To use autotools (which helps in many ways in the long run, like being able
  20  * to immediately create releases of your software directly from your tree
  21  * and ensure everything needed to build it is there) you will need a
  22  * configure.ac, Makefile.am and autogen.sh file.
  23  *
  24  * configure.ac:
  25  *
  26  * @verbatim
  27  * AC_INIT(myapp, 0.0.0, myname@mydomain.com)
  28  * AC_PREREQ(2.52)
  29  * AC_CONFIG_SRCDIR(configure.ac)
  30  * AM_CONFIG_HEADER(config.h)
  31  * AC_PROG_CC
  32  * AM_INIT_AUTOMAKE(1.6 dist-bzip2)
  33  * PKG_CHECK_MODULES([ELEMENTARY], elementary)
  34  * AC_OUTPUT(Makefile)
  35  * @endverbatim
  36  *
  37  * Makefile.am:
  38  *
  39  * @verbatim
  40  * AUTOMAKE_OPTIONS = 1.4 foreign
  41  * MAINTAINERCLEANFILES = Makefile.in aclocal.m4 config.h.in configure depcomp install-sh missing
  42  *
  43  * INCLUDES = -I$(top_srcdir)
  44  *
  45  * bin_PROGRAMS = myapp
  46  *
  47  * myapp_SOURCES = main.c
  48  * myapp_LDADD = @ELEMENTARY_LIBS@
  49  * myapp_CFLAGS = @ELEMENTARY_CFLAGS@
  50  * @endverbatim
  51  *
  52  * autogen.sh:
  53  *
  54  * @verbatim
  55  *#!/bin/sh
  56  * echo "Running aclocal..." ; aclocal $ACLOCAL_FLAGS || exit 1
  57  * echo "Running autoheader..." ; autoheader || exit 1
  58  * echo "Running autoconf..." ; autoconf || exit 1
  59  * echo "Running automake..." ; automake --add-missing --copy --gnu || exit 1
  60  * ./configure "$@"
  61  * @endverbatim
  62  *
  63  * To generate all the things needed to bootstrap just run:
  64  *
  65  * @verbatim
  66  * ./autogen.sh
  67  * @endverbatim
  68  *
  69 <<<<<<< HEAD
  70  * This will generate Makefile.in's, the confgure script and everything else.
  71 =======
  72  * This will generate Makefile.in's, the configure script and everything else.
  73 >>>>>>> remotes/origin/upstream
  74  * After this it works like all normal autotools projects:
  75  * @verbatim
  76  * ./configure
  77  * make
  78  * sudo make install
  79  * @endverbatim
  80  *
  81  * Note sudo was assumed to get root permissions, as this would install in
  82  * /usr/local which is system-owned. Use any way you like to gain root, or
  83  * specify a different prefix with configure:
  84  *
  85  * @verbatim
  86 <<<<<<< HEAD
  87  * ./confiugre --prefix=$HOME/mysoftware
  88 =======
  89  * ./configure --prefix=$HOME/mysoftware
  90 >>>>>>> remotes/origin/upstream
  91  * @endverbatim
  92  *
  93  * Also remember that autotools buys you some useful commands like:
  94  * @verbatim
  95  * make uninstall
  96  * @endverbatim
  97  *
  98  * This uninstalls the software after it was installed with "make install".
  99  * It is very useful to clear up what you built if you wish to clean the
 100  * system.
 101  *
 102  * @verbatim
 103  * make distcheck
 104  * @endverbatim
 105  *
 106  * This firstly checks if your build tree is "clean" and ready for
 107  * distribution. It also builds a tarball (myapp-0.0.0.tar.gz) that is
 108  * ready to upload and distribute to the world, that contains the generated
 109  * Makefile.in's and configure script. The users do not need to run
 110  * autogen.sh - just configure and on. They don't need autotools installed.
 111  * This tarball also builds cleanly, has all the sources it needs to build
 112  * included (that is sources for your application, not libraries it depends
 113  * on like Elementary). It builds cleanly in a buildroot and does not
 114  * contain any files that are temporarily generated like binaries and other
 115  * build-generated files, so the tarball is clean, and no need to worry
 116  * about cleaning up your tree before packaging.
 117  *
 118  * @verbatim
 119  * make clean
 120  * @endverbatim
 121  *
 122  * This cleans up all build files (binaries, objects etc.) from the tree.
 123  *
 124  * @verbatim
 125  * make distclean
 126  * @endverbatim
 127  *
 128  * This cleans out all files from the build and from configure's output too.
 129  *
 130  * @verbatim
 131  * make maintainer-clean
 132  * @endverbatim
 133  *
 134  * This deletes all the files autogen.sh will produce so the tree is clean
 135  * to be put into a revision-control system (like CVS, SVN or GIT for example).
 136  *
 137  * There is a more advanced way of making use of the quicklaunch infrastructure
 138  * in Elementary (which will not be covered here due to its more advanced
 139  * nature).
 140  *
 141  * Now let's actually create an interactive "Hello World" gui that you can
 142  * click the ok button to exit. It's more code because this now does something
 143  * much more significant, but it's still very simple:
 144  *
 145  * @code
 146  * #include <Elementary.h>
 147  *
 148  * static void
 149  * on_done(void *data, Evas_Object *obj, void *event_info)
 150  * {
 151  *    // quit the mainloop (elm_run function will return)
 152  *    elm_exit();
 153  * }
 154  *
 155  * EAPI_MAIN int
 156  * elm_main(int argc, char **argv)
 157  * {
 158  *    Evas_Object *win, *box, *lab, *btn;
 159  *
 160  *    // new window - do the usual and give it a name (hello) and title (Hello)
 161  *    win = elm_win_util_standard_add("hello", "Hello");
 162  *    // when the user clicks "close" on a window there is a request to delete
 163  *    evas_object_smart_callback_add(win, "delete,request", on_done, NULL);
 164  *
 165  *    // add a box object - default is vertical. a box holds children in a row,
 166  *    // either horizontally or vertically. nothing more.
 167  *    box = elm_box_add(win);
 168 <<<<<<< HEAD
 169  *    // make the box hotizontal
 170 =======
 171  *    // make the box horizontal
 172 >>>>>>> remotes/origin/upstream
 173  *    elm_box_horizontal_set(box, EINA_TRUE);
 174  *    // add object as a resize object for the window (controls window minimum
 175  *    // size as well as gets resized if window is resized)
 176  *    elm_win_resize_object_add(win, box);
 177  *    evas_object_show(box);
 178  *
 179  *    // add a label widget, set the text and put it in the pad frame
 180  *    lab = elm_label_add(win);
 181  *    // set default text of the label
 182  *    elm_object_text_set(lab, "Hello out there world!");
 183  *    // pack the label at the end of the box
 184  *    elm_box_pack_end(box, lab);
 185  *    evas_object_show(lab);
 186  *
 187  *    // add an ok button
 188  *    btn = elm_button_add(win);
 189  *    // set default text of button to "OK"
 190  *    elm_object_text_set(btn, "OK");
 191  *    // pack the button at the end of the box
 192  *    elm_box_pack_end(box, btn);
 193  *    evas_object_show(btn);
 194  *    // call on_done when button is clicked
 195  *    evas_object_smart_callback_add(btn, "clicked", on_done, NULL);
 196  *
 197  *    // now we are done, show the window
 198  *    evas_object_show(win);
 199  *
 200  *    // run the mainloop and process events and callbacks
 201  *    elm_run();
 202  *    elm_shutdown();
 203  *    return 0;
 204  * }
 205  * ELM_MAIN()
 206  * @endcode
 207  *
 208  */