<?xml version="1.0" encoding="utf-8"?>
<page xmlns="http://projectmallard.org/1.0/" xmlns:its="http://www.w3.org/2005/11/its" type="guide" style="task" id="weatherApp.js" lang="ca">
  <info>
  <title type="text">Weather application (JavaScript)</title>
    <link type="guide" xref="js#examples"/>
    <revision version="0.1" date="2012-03-09" status="stub"/>

    <credit type="author copyright">
      <name>Susanna Huhtanen</name>
      <email its:translate="no">ihmis.suski@gmail.com</email>
      <years>2012</years>
    </credit>
    <credit type="editor">
      <name>Marta Maria Casetti</name>
      <email its:translate="no">mmcasetti@gmail.com</email>
      <years>2013</years>
    </credit>

    <desc> How to plan an application that uses asynchronous calls. Asynchronous calls will be presented through a weather application.
    </desc>

  </info>

  <title>Weather application</title>
  <synopsis>
    <p>In this guide well construct a weather application using asynchronous calls. Weather information in this example is fetched from geonames.org and the application is using the <link href="http://en.wikipedia.org/wiki/List_of_airports_by_ICAO_code:_E">ICAO codes </link> to place your weather request. To write and run all the code examples yourself, you need an editor to write code in, Terminal and GNOME 3 or higher installed into your computer. In this guide we we'll go through the following parts:</p>

    <list>
      <item><p> <link xref="#planningUi">Planning the graphical user interface</link></p></item>
      <item><p> <link xref="#asynchronous">Asynchronous calls</link></p></item>
      <item><p> <link xref="#main">The main program file</link></p></item>
      <item><p> <link xref="#main">Local library GeoNames</link></p></item>
      <item><p> <link xref="#main">Autotools and Icons</link></p></item>
    </list>
  </synopsis>

  <p>After reading this tutorial, you should see this in your screen:</p>
  <media type="image" mime="image/png" src="media/weatherAppJs.png"/>

  <section id="planningUi">
    <title>Planning the graphical user interface</title>
    <p> Structuring an application for GNOME 3 means you will be using <link href="http://developer.gnome.org/platform-overview/stable/gtk">GTK+</link>. The most important thing is to remember that the main window will only accept one widget. You must plan your structure accordingly (this example is using Gtk.Grid). A useful method is to draw out the main window and place every widget needed inside that box. By looking at an image of your future application it is easier to tell what are the relations between widgets. For example Gtk.Grid places your widgets in relation to other widgets, so after the first widget is in place, placing widgets can be done in relation to any widget on the grid. </p>
  </section>
  <section id="asynchronous">
    <title>Asynchronous calls</title>
    <p> With many programming languages, all operations are run synchronously - you tell the program to do something, and it will wait until that action completes before proceeding. This is however bad for
    graphical user interfaces, as then the whole application will be frozen while the program waits for
    the operation. Going asynchronous (async) helps here. With async calls, your UI won't be blocked with any requests. Async calls make your application more flexible and better equipped to handle situations when calls take more time than expected or for some reason get jammed. Async calls can be used for example file system I/O and for slower calculations in the background.   </p>
    <p>    In this example we have to get data from geonames.org. While we do that we want the rest of our program to continue. If we wouldn't get any information from geonames.org for the lack of internet connection and this would be a synchronous application we would never  get to the point where our main_quit() is processed correctly and the application would have to killed from Terminal.  </p>
  </section>
  <section id="main">
    <title>The different parts of the program</title>
  </section>
</page>
