Documentation

If you haven’t yet, check out the Examples page for a really brief example of what the structure is like and what it can do. It might give you an idea of what to expect for this section. If you’ve already seen that, or you just want to get started, continue reading.

PLEASE NOTE: I realize this documentation falls far short of what will eventually be necessary. It should be enough to get Android devs started with the download that has just become available, however.



Android Project Integration

This process assumes you are using Eclipse with the ADT properly setup already. If you don’t have this prepared yet, check out the setup guide. If you’re using something besides Eclipse, then hopefully you can figure out the integration process on your own.

  1. Create or open your Android project.
    The AML library for Android requires as a minimum the Cupcake release (v1.5) of the SDK as a minimum. You can use anything newer if you like, but choose at least 1.5.
  2. Add the AMLCode library to your project.
    1. Download the latest version (or get it from the Subversion repository).
    2. Import it into your Eclipse workspace if you downloaded it, or if you used Subversive/Subclipse, it should be there already.
    3. Right-click on your project and select Properties.
    4. Select the Android category in the list on the left.
    5. In the Library group, click the Add button.
    6. Select the AMLCode library which should be in the list, and click OK, then click OK again.
  3. Create a /res/raw subfolder for local AML files.
    If you won’t be pulling down all AML resources from an external location, you create a /raw folder inside your project’s /res folder for local AML markup files. This will allow you to reference them using the built-in R.raw.filename method.
  4. OPTIONAL: Create a sample application.aml.
    Creating a local file inside the /res/raw folder for testing will make it easier to experiment with AML. See the instructions below for details.

Creating a Sample AML Markup File

You really only need to complete the first two steps to be able to use the AML library, but if you do the last two as well, you can quickly test some AML before really diving into it. This is probably easiest if you are starting from scratch, or at least a fresh Activity class.

  1. Right-click on your new /res/raw folder and select New, then File (do not select Android XML File, which is quite different).
  2. Call it “application.aml“, and then open it in the editor.
  3. Paste in the following content:
    <aml id="amlTestInput" scroll="yes">
      <input type="button">Test Button</input>
      <input type="checkbox">Test CheckBox</input>
      <input type="togglebutton" checked="yes" />
      <input type="imagebutton" image="drawable/icon" />
      <input type="text">Test Text</input>
      <input type="password">Test Password</input>
      <radiogroup>
        <input type="radiobutton" checked="yes">Radio Button 1</input>
        <input type="radiobutton">Radio Button 2</input>
        <input type="radiobutton">Radio Button 3</input>
      </radiogroup>
      <input type="button" tap=".back()">Exit</input>
    </aml>
  4. Modify your Activity class onCreate() method to look like this:
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        AmlBuilder.setActivity(this);
        AmlBuilder.parse(R.raw.application);
        View root = AmlBuilder.getView("amlTestInput");
        if (root != null) setContentView(root);
    }

Now run it (F11 to debug, Ctrl+F11 to run) and see what happens! You should get a nice little sample of input objects generated by your AML markup.

A few important things to note about the example onCreate() method shown above:

  • You must call AmlBuilder.setActivity(this) before parsing the AML resource or getting the view. Because the Android AML library reuses a single Activity class (AmlActivity) while switching between views, it must maintain its own Activity stack. Knowing which is the root activity is critical.
  • You must call AmlBuilder.parse() before requesting any views that are contained within the parsed resource. The reasoning for this is kind of obvious.
  • The Activity’s setContentView() call is using the view created by AML, not the R.raw.application resource. If you try to simply set the view to that resource, it won’t work.

iPhone/Windows Phone 7 Integration

These platforms are not currently supported in any way, but I plan to port the library over to them as completely and as soon as possible. The Android platform is my priority at the moment.

Go to Top