3.4. A Brief Tour of the MJAndroid Code

MJAndroid is a relatively simple application, despite the capabilities it gives its users. This section will give you an overview of the code and resource modules, tell you where they are located in the directory structure, and provide a glimpse of what each component does. You may want to refer to this section in the future when you're trying to find example code for a particular function and want to locate it in the MJAndroid code tree. MJAndroid uses a directory structure that is derived directly from the standard Android application directory structure, so this will also serve as a guide to finding code in other application source trees.

3.4.1. The Project Root Folder (MJAndroid)

If you use Eclipse's Package Explorer to look at the MJAndroid project, you will see a set of folders and files. It turns out all of these were originally created by Eclipse and the Android Development Tool, and similar folders and files are created for any Android application. Let's see what they do:

src folder

src is short for Source, and this is where Eclipse and ADT expect to find all of the Java source files in your application. Almost all of the work you do to create an Android application is done in this folder and the res folder. In the next section, we will take a more detailed look at how the src folder is structured for MJAndroid.

Android Library

This is just what it says: a pointer to the library of Android class files that Eclipse links to in order to provide the Android APIs. You don't need to do anything with this entry, but if you ever need to confirm that a particular Android class is (still) there, this is where you would look.

assets folder

This folder is useful for holding assets that are used by the application: fonts, external JAR files, and so on. For this book and MJAndroid, we don't have any assets, so we will not be using the assets folder.

doc folder

Short for documentation, this is where you can put documentation for a project. For MJAndroid, web pages that describe the Loco project are stored in this folder.

res folder

res is short for resources, and this is where Eclipse and ADT expect to find the resources for your application. Resources include most of the XML files that define the layout of your application, any image files (icons, pictures that are used in your layout, sprites, etc.)—just about everything that isn't part of a Java source file.

AndroidManifest.xml file

This file is created by ADT when you create a new Android project. As the extension suggests, it is an XML file, and it contains a wealth of information about your application: what the activities, services, and intents are, which one starts first, which permissions your application needs from the operating system (for restricted functions such as getting location or making a phone call), and a lot of other information. This file is so important that ADT provides a special editor to maintain it. It's just an XML file, so you could always edit it with a text editor, but you will see later that the specialized editor makes everything a lot easier.

Eclipse also creates two other files and another directory at the same directory level (the root directory of the MJAndroid project) that are not shown by Package Explorer. The .classpath file is used by Eclipse to keep track of the location of standard Java classes and libraries. Eclipse uses the .project file to store information about the project. You will never need to touch either of these files directly, so Eclipse doesn't bother you with them in Package Explorer. The bin directory is where Eclipse puts the compiled class files for each of your Java source files (the ones in src). You can see all of these files if you list the directory of the root folder, but you don't really need to pay any attention to them, because Eclipse will do it all for you.

3.4.2. The Source Folder (src)

The package name for MJAndroid is com.microjobsinc.mjandroid. Eclipse lays out the equivalent directory structure, just as it would for any Java project, and shows you the whole thing when you open src. In addition to these package folders, there is a folder named for the package that contains all the Java files for the project. These include:

MicroJobs.java

The main source file for the application. It designates the Activity that starts first, displays the map that is the centerpiece of the application, and calls other Activities or Services as necessary to implement different features in the user interface.

MicroJobsDatabase.java

A database helper that provides easy access to the local MJAndroid database. This is where all the employer, user, and job information is stored, using SQLite.

AddJob.java and EditJob.java

Part of the database portion of MJAndroid. These provide screens through which the user can add or edit job entries in the database.

MicroJobsDetail.java

The Activity that displays all of the detail information about a particular job opportunity.

MicroJobsEmpDetail.java

The Activity that displays information about an employer, including name, address, reputation, email address, phone number, etc.

MicroJobsList.java

The Activity that displays a list of jobs (as opposed to the map view in MicroJobs.java). It shows a simple list containing Employer and Job entries, and allows the user to sort the list by either field and call up specifics of the job or employer by touching the name on the list.

R.java

This file is created automatically by Eclipse and the ADT to contain Java references for all the resources that are defined in the res folder (see the next section). You should never have to edit this file by hand, as it is maintained for you as you add or edit resources. Take a look, though, just to see how resources are defined for later use in the other Java source files.

3.4.3. The Resource Folder (res)

The res folder contains three folders, and another pointer to the same AndroidMani⁠fest.xml file that shows up in the root directory:

drawable

As you might suspect, this contains all the drawable images that MJAndroid will use: any JPEG or PNG or GIF files or bitmaps.

layout

As with many modern application environments, Android allows you to separate what is displayed by an Activity from how it is displayed. This directory contains XML files that describe the "how"; in other words, they are the layout files for each Activity in the application. When a program runs, Android applies the rules in these files to create the visible layout, a process known as "inflating."

values

Good programming practice calls for the separation of data that does not directly affect the operation of an application, making it a lot easier to do things like translation to foreign languages, theming, etc. We aren't going to be super strict about this in MJAndroid, but we will at least put all of the obvious user-visible text into a file called strings.xml. You'll see how easy it is to retrieve these for use in the actual Android Activity source code.