Getting started

First, you need to install EWS and its dependencies. Read the Install Guide for details.

Our first example will be the simplest possible EWS application. It will just initialize a display in a window and keep running until you quit it by clicking in the close button.

Source: getting_started.e

class GETTING_STARTED

create
	make

feature {NONE} -- Creation

	make is
		local
			d: DISPLAY
		do
			create {SDL_DISPLAY}d.make (640, 480, 16, False)
			d.do_event_loop
			d.close
		rescue
			if d /= Void then d.close end
		end

end -- class GETTING_STARTED

To compile this example you will need to set up your loadpath.se with the following lines, assuming you installed in the directory suggested in the installation guide:

${SmartEiffelDirectory}/lib_ews
${SmartEiffelDirectory}/lib_ews/events
${SmartEiffelDirectory}/lib_ews/widgets
${SmartEiffelDirectory}/lib_ews/windows
${SmartEiffelDirectory}/lib_ews/animations
${SmartEiffelDirectory}/lib_ews/driver-sdl
${SmartEiffelDirectory}/lib_utils/

If you installed in a different directory, change the prefix ${SmartEiffelDirectory}/lib_ews to the path where you installed EWS. Also note that you will need the path for eiffel utils, shown above as ${SmartEiffelDirectory}/lib_utils/; modify your loadpath properly if you are using a different path. Note that your loadpath.se should also contain the path for the example (not shown above).

With that done, you will be able to compile this example with the following command:

compile getting_started -o getting-started -case_insensitive $(sdl-config --libs --cflags) -lews-SDL

It is a bit long, so I will explain each part:

`compile getting_started`	The usual way to compile a system in SmartEiffel
`-o getting-started`	This sets the name of the reulting executable
`-case_insensitive`	Make SmartEiffel case insensitive. This disables lots of style warnings that would be emitted from EWS code. Some EWS classes have internal features with names not following the Eiffel recommended coding style, for easier interfacing with C.
`$(sdl-config --libs --cflags)`	This links SDL against the generated executable and adds the correct parameters to add the include path of SDL. This assumes a UNIX shell, check SDL documentation for linking instructions in other platforms. The `sdl-config` command should be included with your SDL distribution
`-lews-SDL`	Link to the ews-SDL library. This file is the compiled C component of EWS. It should have been generated during EWS installation.

That's all for compiling. Some features related to image loading will also require adding the parameter -lSDL_image to link another required library.

When you run the program above you will see a black window, 640 pixels wide and 480 pixels tall. That is the EWS display. You will also note that the mouse pointer is not visible inside that window. To finish the application just click on the close button on the window frame, as any other application.

Let's see each one of the three instructions in the code:

create {SDL_DISPLAY}d.make (640, 480, 16, False)

This initializes a display object. The display is a singleton object that will control most of EWS. When you create it the application window appears, or the video mode is set for a fullscreen application. Displays are objects of some class conforming to DISPLAY.

The class DISPLAY itself is a deferred class, but it provides the interface for all specific displays. Different implementation (called "drivers") of EWS could be represented by different descendants of DISPLAY. Currently the only existing driver is SDL_DISPLAY, but other drivers could be implemented in the future. SDL_DISPLAY can use as a screen any device/system supported by the SDL library (the list is quite long).

The creation routine make of SDL_DISPLAY receives as argument the size of the display (640x480 in this case), the color depth in bits (16), and a BOOLEAN indicating if you want to use fullscreen or not. Note that some color depths may not be supported by your display or configuration, and in those cases SDL works converting images to the most similar supported depth. This makes programming simpler in the usual case, but has a performance cost.

You might want to play around with this line to see the effects on the window. Be careful when setting the fullscreen argument to True: You will not have a window frame with a close button, so you will have to kill your application in some other way.

The second line:

d.do_event_loop

Is the place where your application will spend most of its life. It runs a loop where it:

Gets input events (mouse, keyboard, timer, others)
Dispatches these events to the UI components
Updates the display

This loop continues until an event of type EVENT_QUIT is processed. That event is the one sent by the close button in your window frame. When the DISPLAY processes this event, it terminates the event loop.

After that, you should call:

d.close

This takes care of shutting down SDL and EWS, particularly closing the window, or restoring the previous video mode. Not calling this may leave your screen in a weird state, specially when using full-screen. You probably also noted the exception handler for our routine:

rescue
	if d /= Void then d.close end
end

This takes care of shutting down the display when there is a problem. Note that you should not write just d.close because the problem could have appeared when creating d, and in that case d will be Void. The problem with adding that line, is that SmartEiffel will produce less than useful exception tracebacks when you have a handler set at the top level. You probably want to work in windowed mode, and without that rescue clause while debugging.

Let's now move on to more interesting examples.

Table of contents