To get started with programming for the Android platform we are going to make a very simple application. Though, it will be a bit more advanced than the barebone "Hello World"-app or the simple starter app that is being generated automatically by the development framework when creating a new Android project.
Our Basic application
The app we are gong to build is a reaction tester. A program that will count how many millisconds it takes you to press a button after you have been given the "go" signal. In this first tutorial we will keep it very simple and then we will add more feaures in the upcoming tutorials in our Android App Development-series.
The program will be doing the following: When it loads it will alert the user to be ready to react. Seconds later a "Go!" message will be given signalling the user to react. The user reacts by pressing a button on the screen. The instant the button is pressed the program will calculate the time from the signal was given until the button was pressed. The resulting time will be displayed on the screen (and the user will be able to start the process again to see if he can beat his previous time).
Setting up namespaces
Our program starts out like this:
using System;
using Android.App;
using Android.Content;
using Android.Runtime;
using Android.Views;
using Android.Widget;
using Android.OS;
namespace ReactionTimer
{
First we are applying the using directive to be able to reference different elements of the Mono (for Android) Framework that we will be needing for our program. For instance we are going to use a Button which is a specific graphical element with a specific set of features and which is drawn on the screen in a specific way by the Android device. A Button is located in the Android.Widget namespace. A namespace is simply a way of dividing code into logical units giving it a proper a structure that allows programmers to find what they need (easily, hopefully). Without our using directive we would need to write Android.Widget.Button in order to reference the needed class in the Mono Framework. Now, we can instead just write Button in our code. When the program is prepared for execution (compiled) the compiler will know what type of button we are referring to and where to find it.
In the same way we are also referring the System namespace (in the very first line) which is not a reference to Android specific code elements but to general code from the .NET Framework (now in its Mono implementation as we are using the Mono Framework).
After that on line 10 we are creating our very own name space (yay, our first piece of original code) ReactionTimer. As we only have one main file and one namespace we do not have any special benefits from this. However, as our application grows, making use of cleverly named spaces can be quite useful.
The Android Activity class
Next we come to our first class Activity1 which inherits from the Activity class in the Android.App namespace
See the piece of code below:
[Activity(Label = "Reaction Tester", MainLauncher = true, Icon = "@drawable/icon")]
public class Activity1 : Activity
{
An activity on Android is logical construct (besides being a class) that refers to something the user can do. For at user to do something a user interface (UI)is required. Thus, a primary function of an Activity is to control a window on which graphical items (UI-elements) are placed for the the user to interact with.
In our application our activity is to carry our a reaction as fast as possible. This requires only a single screen and so we only have one Activity class. If we needed multiple screens we would create multiple classes. Instaead of Activity1 we could have named our activity differently - for exaple "ReactionScreen".
Just above our Activity class we see what is called an attribute. An attribute is not part of the code itself and is not influencing the program when it is running. Rather it is a form of annotation that can be used by the programming environment when the code is being processed and made into an executable form.
In our case we have an ActivityAttribute and it has some parameters called Label, MainLauncher and Icon. These attributes are being used by the Mono framework and what happens specifically is that during the build process the Mono framework looks for all the class attributes and uses the data found in order to generate an XML file. This resulting file is called "AndroidManifest.xml" and is a file that needs to be included within every Android application. It is a kind of settings file that tells Android something about the program and how to deal with it. In our case our device will know that the label to use for our activity is "Reaction Tester" (will be shown on the screen when the app is running), that our activity class is to be launched when the program starts, and it knows where to find the icon to associate with our program.
Content of the Activity class
Our Activity class contains the following code:
private ChangeStateTimer timer;
private State state;
private long startTime;
private Button button;
private TextView label;
protected override void OnCreate(Bundle bundle)
{
base.OnCreate(bundle);
// Set our view from the "main" layout resource
SetContentView(Resource.Layout.Main);
// Get our button from the layout resource and attach an event to it
this.button = FindViewById<Button>(Resource.Id.buttonMain);
this.button.Click += new EventHandler(HandleUserReaction);
//Ensure the button cannot be pressed until we need it to
this.button.Enabled = false;
//Get a reference to the label from the layout resource
this.label = FindViewById<TextView>(Resource.Id.labelResult);
this.state = State.Stopped;
this.timer = new ChangeStateTimer(10000, 2000, this);
this.timer.Start();
}
First we have five variables (called Fields in C#). The two first are used to hold references to a timer that we will need and to the state we discussed before. The third of them will hold the time (measure in milliseconds) for when the "go"-signal was given so that we can use it later to see how much time passed until the user pressed the button. Finally, the two last fields will be referring to our two UI-items which is a Button and a TextView (which we will be referring to as a "label").
Next we have a method that is being called automatically by the system once the program has started and our Activity has been created. This is the way that Android informs us that "Ok, now your program has started and I am going to turn it over to you now. So, get ready.". In this method we have to prepare a few things so that our program can later function as we intend.
Well, first we have to do something for Android which is to call the OnCreate method on the base class. This is so that the Activity class can do it's magic (setting up something that needs to be set-up for an Android program to run - which we do not need to concern ourselves with).
The first major thing we do is to load our user interface by calling the SetContentView method of our activity passing it our layout as a parameter. Our layout is stored in an XML template file called "Main" and located amongst our program Resources in the "Layout" folder (see file content later). It needs to be connected to our activity so that it will display the UI-elements we have marked up there.
Then we locate our button and label in our template and save a reference to them so that we can do something with them later. Also, we attach an event handler to the Click event of the button. This is done by passing the name of our method - which is HandleUserReaction to a so-called delegate.
A delegate is specific concept in C# that acts as a form of a contract. The purpose is to constrict exactly what form a method should have in order to be called by a particular event. The event in this case is the Click event of a button. From documentation we know that it is the EventHandler delegate that holds the contract related this event. So, as long as our method conforms to the contract laid out by this particular delegate we can be sure that it can be executed when the Click event of the button has been triggered.
Now we set the state of our application (see more below). At this point we want to remember that we are not currently Running (but rather Stopped) meaning that we have not yet started the experiment of seeing how fast the user can press the button after we tell him to.
Lastly, we create a new instance of our timer. We give it a few parameters with the most interesting being the first one which is used to set how many milliseconds the countdown should last. A deeper description will follow a few paragraphs down.
Creating state for our application
Next we make use of the enumeration data type (created with the enum keyword) containing two items. These are states which we will logically have to handle in our application and with our enum we are able to asily assign and retrieve them.
What the states are and their purpose should be evident from the code and the comments:
private enum State {
Running,//The test is running and we await the reaction from the user
Stopped//The test is not running (which will be the case at start-up or after the user has reacted)
}The timer class
Explanation of the timer class to follow
private class ChangeStateTimer : CountDownTimer
{
Activity1 activity;
public ChangeStateTimer(long finalTime, long intervals, Activity1 activity)
: base(finalTime, intervals)
{
this.activity = activity;
}
public override void OnFinish()
{
this.activity.GiveStartSignal();
}
public override void OnTick(long millisUntilFinished)
{
//Not using this method as we are not using the intervals
}
}
}
}
Ready, set, Go!
Next we have the GiveStartSignal method that will be called by the timer once it has finished counting down. At this point we are ready to time the reaction of the user.
private void GiveStartSignal()
{
this.label.Text = "Waiting for your reaction.";
this.button.Text = "Now!";
this.button.Enabled = true;
this.state = State.Running;
this.startTime = SystemClock.CurrentThreadTimeMillis();
}
To alert the user that we are awaiting his reaction we change the text of our label to "Waiting for your reaction.". Also, we change the text of our button to "Now!". More importantly we change the Enabled state of the button to true so that it will actually function.
We then set the state to Running and register the current time. Note, that it is not the actual time of day that we are recording but the time that has passed since our application has been started (measured in milliseconds). This is totally fine because we are not concerned about the actual time but only interested in being able calculate the difference between "now" and the point at which the user will have pressed the button.
You might have noticed that it says CurrentThreadTimeMillis. So, technically we are not necessarily getting the time elapsed since the start of the application itself but rather that of the thread that is handling our application. A thread is a mechanism through which the processer is able to prioritize the execution of different programs (and different parts of a single program in case of multi-threaded programs).
So, now the "click is ticking" and the program is waiting for the user to press the "reaction"-button - which brings us to the last part of our code.
Handling states
Finally, we come to the method we assigned to the Click event of our button. Looking throug the code you will see that is uses our State enum to check what part of the code in the method to execute:
private void HandleUserReaction(Object sender, EventArgs e)
{
if (this.state == State.Running)
{
//We have been waiting for a reaction and now we need to see how long it took
long reactionTime = SystemClock.CurrentThreadTimeMillis() - this.startTime;
this.label.Text = "You reacted in: " + reactionTime.ToString() + " milliseconds.";
this.button.Text = "Restart";
this.state = State.Stopped;
}
else if (this.state == State.Stopped)
{
//State is stopped and so a new click means we have to start over
this.label.Text = "Stand by for the button to signal a start";
this.button.Text = "Stand by ...";
this.button.Enabled = false;//Button must not be clickable now because we await for system to give the signal to the user
this.timer.Start();
}
}
First we check if we are in the Running state. If this is the case the user has just reacted and pressed the button as fast as humanly possible.
Therefore, we look at the current point in time again - and subtract the value we stored previously when the "go"-signal was given. Then we graciously present the user with the fact that it takes him just about half a second to press a button.
Lastly, we change the text of the button to "Restart" so the user can see that the way to beat himself trying to squeeze the reaction down to a quarter of a second is to once again press the same darn button. For that to work we also change the state to Stopped so that our program will execute the other part of the method next time it is called.
when the other part, and the last part of our program, is run, we know that the user has pressed the button again and we know that the state is Stopped. Consequently, what we must do is to start the timer once again so it can make a new countdown towards a new "go"-signal.
Also, we disable the button so that our user can see that the button is not currently to be pressed (if it was the timer would simply be restarted). As you test the program you might see that the user can cheat by hammering the button repeatedly hoping to trigger it the very instant it is re-enabled when the new signal is given. This problem we will tackle in the next tutorial where we will generally look at how we can enhance the current version.
The XML User Interface
Our graphical elements are contained in an XML file that acts as a template for our program. The UI-items can also be added to a screen directly through code but since the programming framework automactially generates a layout file as part of the model application we will stick to this way of going about it. Also, it is generaly good programming practice to separate programming logic from UI-layout.
<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
android:orientation="vertical"
android:layout_width="fill_parent"
android:layout_height="fill_parent"
>
<Button
android:id="@+id/buttonMain"
android:layout_width="fill_parent"
android:layout_height="wrap_content"
android:text=""
/>
<TextView
android:id="@+id/labelResult"
android:text=""
android:layout_width="fill_parent"
android:layout_height="wrap_content"
/>
</LinearLayout>
In the file we see that we have our Button and Textview and that they are contained in a LinearLayout. The tags all refer to classes in the Android Framework and LinearLyout is a class responsible for grouping controls and laying them out on the screen in a particular (liniear) way ("linear" means that the controls will be positioned one after another).
Besides the orientation of the layout which is set to "vertical" we see that special attributes are used for assigning height and width. The value "fill_parent" means that the control will take up as much space as it can limited only by its containing parent - while "wrap_content" means that the control will extend as much as possible to contain the content it holds (in our case the button and label will be as high as needed in order to contain the text we need them to show).
Now we have a working Android application. Good luck, keep studying and practising.
As always, comments and questions are welcome, we'll try our best to answer them when we can.
Helpful and productive suggestions and corrections, if any are needed are very much appreciated through our contact page.
As always, comments and questions are welcome, we'll try our best to answer them when we can.
Helpful and productive suggestions and corrections, if any are needed are very much appreciated through our contact page.
