Getting Started

To write an Elementary app, you can get started with the following:

To write an Elementary app, you can get started with the following:

#include <Elementary.h>
EAPI_MAIN int
elm_main(int argc, char **argv)
{
// create window(s) here and do any application init
elm_run(); // run main loop
return 0; // exit 0 for exit code
}
#define ELM_MAIN()
macro to be used after the elm_main() function
Definition: elm_general.h:556
void elm_run(void)
Run Elementary's main loop.
Definition: elm_main.c:1357

To use autotools (which helps in many ways in the long run, like being able to immediately create releases of your software directly from your tree and ensure everything needed to build it is there) you will need a configure.ac, Makefile.am and autogen.sh file.

configure.ac:

AC_INIT(myapp, 0.0.0, myname@mydomain.com)
AC_PREREQ(2.52)
AC_CONFIG_SRCDIR(configure.ac)
AM_CONFIG_HEADER(config.h)
AC_PROG_CC
AM_INIT_AUTOMAKE(1.6 dist-bzip2)
PKG_CHECK_MODULES([ELEMENTARY], elementary)
AC_OUTPUT(Makefile)

Makefile.am:

AUTOMAKE_OPTIONS = 1.4 foreign
MAINTAINERCLEANFILES = Makefile.in aclocal.m4 config.h.in configure depcomp install-sh missing
INCLUDES = -I$(top_srcdir)
bin_PROGRAMS = myapp
myapp_SOURCES = main.c
myapp_LDADD = @ELEMENTARY_LIBS@
myapp_CFLAGS = @ELEMENTARY_CFLAGS@

autogen.sh:

#!/bin/sh
echo "Running aclocal..." ; aclocal $ACLOCAL_FLAGS || exit 1
echo "Running autoheader..." ; autoheader || exit 1
echo "Running autoconf..." ; autoconf || exit 1
echo "Running automake..." ; automake --add-missing --copy --gnu || exit 1
./configure "$@"

To generate all the things needed to bootstrap just run:

./autogen.sh

This will generate Makefile.in's, the configure script and everything else. After this it works like all normal autotools projects:

./configure
make
sudo make install

Note sudo was assumed to get root permissions, as this would install in /usr/local which is system-owned. Use any way you like to gain root, or specify a different prefix with configure:

./configure --prefix=$HOME/mysoftware

Also remember that autotools buys you some useful commands like:

make uninstall

This uninstalls the software after it was installed with "make install". It is very useful to clear up what you built if you wish to clean the system.

make distcheck

This firstly checks if your build tree is "clean" and ready for distribution. It also builds a tarball (myapp-0.0.0.tar.gz) that is ready to upload and distribute to the world, that contains the generated Makefile.in's and configure script. The users do not need to run autogen.sh - just configure and on. They don't need autotools installed. This tarball also builds cleanly, has all the sources it needs to build included (that is sources for your application, not libraries it depends on like Elementary). It builds cleanly in a buildroot and does not contain any files that are temporarily generated like binaries and other build-generated files, so the tarball is clean, and no need to worry about cleaning up your tree before packaging.

make clean

This cleans up all build files (binaries, objects etc.) from the tree.

make distclean

This cleans out all files from the build and from configure's output too.

make maintainer-clean

This deletes all the files autogen.sh will produce so the tree is clean to be put into a revision-control system (like CVS, SVN or GIT for example).

There is a more advanced way of making use of the quicklaunch infrastructure in Elementary (which will not be covered here due to its more advanced nature).

Now let's actually create an interactive "Hello World" gui that you can click the ok button to exit. It's more code because this now does something much more significant, but it's still very simple:

#include <Elementary.h>
static void
on_done(void *data, Evas_Object *obj, void *event_info)
{
// quit the mainloop (elm_run function will return)
}
EAPI_MAIN int
elm_main(int argc, char **argv)
{
Evas_Object *win, *box, *lab, *btn;
// new window - do the usual and give it a name (hello) and title (Hello)
win = elm_win_util_standard_add("hello", "Hello");
// when the user clicks "close" on a window there is a request to delete
evas_object_smart_callback_add(win, "delete,request", on_done, NULL);
// add a box object - default is vertical. a box holds children in a row,
// either horizontally or vertically. nothing more.
box = elm_box_add(win);
// make the box horizontal
// add object as a resize object for the window (controls window minimum
// size as well as gets resized if window is resized)
// add a label widget, set the text and put it in the pad frame
lab = elm_label_add(win);
// set default text of the label
elm_object_text_set(lab, "Hello out there world!");
// pack the label at the end of the box
elm_box_pack_end(box, lab);
// add an ok button
btn = elm_button_add(win);
// set default text of button to "OK"
elm_object_text_set(btn, "OK");
// pack the button at the end of the box
elm_box_pack_end(box, btn);
// call on_done when button is clicked
evas_object_smart_callback_add(btn, "clicked", on_done, NULL);
// now we are done, show the window
// run the mainloop and process events and callbacks
return 0;
}
#define EINA_TRUE
boolean value TRUE (numerical value 1)
Definition: eina_types.h:539
void elm_box_horizontal_set(Elm_Box *obj, Eina_Bool horizontal)
Set the horizontal orientation.
Definition: elm_box_eo.legacy.c:27
Evas_Object * elm_box_add(Evas_Object *parent)
Add a new box to the parent.
Definition: elm_box.c:363
void elm_box_pack_end(Elm_Box *obj, Efl_Canvas_Object *subobj)
Add an object at the end of the pack list.
Definition: elm_box_eo.legacy.c:57
Evas_Object * elm_button_add(Evas_Object *parent)
Add a new button to the parent's canvas.
Definition: efl_ui_button.c:459
void elm_exit(void)
Ask to exit Elementary's main loop.
Definition: elm_main.c:1373
Evas_Object * elm_label_add(Evas_Object *parent)
Add a new label to the parent.
Definition: elm_label.c:421
Evas_Object * elm_win_util_standard_add(const char *name, const char *title)
Adds a window object with standard setup.
Definition: efl_ui_win.c:9582
void elm_win_resize_object_add(Eo *obj, Evas_Object *subobj)
Add subobj as a resize object of window obj.
Definition: efl_ui_win.c:8997
EVAS_API void evas_object_show(Evas_Object *eo_obj)
Makes the given Evas object visible.
Definition: evas_object_main.c:1814
Efl_Canvas_Object Evas_Object
An Evas Object handle.
Definition: Evas_Common.h:185
EVAS_API void evas_object_smart_callback_add(Evas_Object *eo_obj, const char *event, Evas_Smart_Cb func, const void *data)
Add (register) a callback function to the smart event specified by event on the smart object obj.
Definition: evas_object_smart.c:1040