×
Namespaces

Variants
Actions

Using the PIM API to create Medication Reminders

From Nokia Developer Wiki
Jump to: navigation, search
{{{width}}}
05 Jan
2014

This article explains how to create medication reminders using Calendar Events - PIM API (JSR-75).

Article Metadata
Code ExampleCompatibilityArticle
Created: igordsm (12 Nov 2013)
Last edited: croozeus (05 Jan 2014)

Note.pngNote: This is an entry in the Nokia Asha Wiki Competition 2013H2.

Contents

Introduction

A common problem in today's highly medicated society is that people often forget to take their medications at the correct time. This reduces the medicine's effect, and can put the patient at risk. In this article we describe how to create a medication reminder app for the Nokia Asha software platform, in order to notify patients when it is time to take their medication.

The solution described in this article uses Calendar events to remind patients to take their medication. Calendar events are suited for this task because:

  1. they do not depend on an Internet connection (unlike the Notifications API);
  2. push registry notifications disappear completely after they are dismissed, while events remain
  3. they remain on the device and appear on the calendar
  4. they appear in the Nokia Asha "fastlane"


Screenshots of the app and resulting medication reminders are shown below:


Implementation

First create a new Midlet project in Nokia IDE and open Main.java.

User interface

In this example we use a simple LCDUI. Our interface will contain fields for the medication name, the frequency it should be taken and the dates to start and stop taking the medicine.

Adding a new reminder.

Add the following variables to our MIDlet:

Form f;
TextField name;
DateField start;
DateField end;
TextField every;

We build the Form in the startApp() method and show it to the user.

protected void startApp() throws MIDletStateChangeException {
f = new Form("Medication Reminder");
name = new TextField("Medication name", "", 20, TextField.ANY);
start = new DateField("Start time", DateField.DATE_TIME);
days = new TextField("How many days", "1", 2, TextField.NUMERIC);
frequency = new TextField("Times per day", "2", 2, TextField.NUMERIC);
 
f.append(name);
f.append(start);
f.append(days);
f.append(frequency);
f.addCommand(new Command("Add", Command.OK, 1));
f.setCommandListener(this);
Display.getDisplay(this).setCurrent(f);
}

Also, add the function below. It will be useful later.

protected void resetFields() {
name.setString("");
start.setDate(new Date(System.currentTimeMillis()));
days.setString("1");
frequency.setString("2");
}

Adding events using the PIM API

The Nokia Asha platform implements the PIM API (JSR-75), which gives us access to the user's Calendar.

We are interested in the EventList and Event classes:

  • The EventList holds all the events in the phone's calendar and is accessed using the openPIMList method.
  • The Event class represents an appointment in the calendar. Every Event must be created by an open EventList using the EventList.createEvent() methods, and the fields must be filled using the Event.add* methods. Since the Nokia Asha Platform supports all the fields in the JSR, there is no need to check if they exist. To save the modifications to an Event, call the Commit() method.


Below is an example of how to add an Event to the Calendar

try {
EventList evts = (EventList) PIM.getInstance().openPIMList(PIM.EVENT_LIST, PIM.WRITE_ONLY);
Event e = evts.createEvent();
 
e.addString(Event.SUMMARY, PIMItem.ATTR_NONE, "Event Name");
e.addDate(Event.START, PIMItem.ATTR_NONE, date.getTime());
e.addDate(Event.END, PIMItem.ATTR_NONE, date.getTime());
e.addInt(Event.ALARM, PIMItem.ATTR_NONE, 1); //
 
e.commit();
evts.close();
} catch (PIMException e) {
e.printStackTrace();
}

The following method will be used to add our calendar events. Since we will add many entries for each medication reminder, we take an open EventList as an argument.

public void addEvent(EventList evts, String summary, long start, long end) {
Event e = evts.createEvent();
/* set fields */
e.addString(Event.SUMMARY, PIMItem.ATTR_NONE, name.getString());
e.addDate(Event.START, PIMItem.ATTR_NONE, start);
e.addDate(Event.END, PIMItem.ATTR_NONE,end);
e.addInt(Event.ALARM, PIMItem.ATTR_NONE, 1);
 
try {
e.commit();
} catch (PIMException e1) {
e1.printStackTrace();
}
}

For each medication reminder, we need to create (number of days)*(times per day) calendar events, each starting at the correct time. We put the code to create these events in the commandAction() method.

public void commandAction(Command c, Displayable d) {
try {
EventList evts = (EventList) PIM.getInstance().openPIMList(PIM.EVENT_LIST, PIM.WRITE_ONLY);
int freq = Integer.parseInt(frequency.getString());
long num_days = Integer.parseInt(days.getString());
long n = freq * num_days;
int time_interval = 3600 * 24 / freq * 1000;
for (int i = 0; i < n; i++) {
addEvent(evts, name.getString(),
start.getDate().getTime() + time_interval * i,
start.getDate().getTime() + time_interval * i);
}
evts.close();
} catch (PIMException e) {
e.printStackTrace();
}
 
Alert ok = new Alert("Reminders created.");
ok.setTimeout(2000);
Display.getDisplay(this).setCurrent(ok, f);
resetFields();
}

The interval between the events is the number of times the medicine needs to be taken each day (24 / freq) times the number of milliseconds in each hour (3600*1000).

The reminders appear in the user's calendar.

Conclusions

Taking medications at the correct time is very important to the quality of a health treatment. This article explained how to create medication reminders using the the PIM API to create Calendar Events.

Download the complete code example here: File:MedicationReminders.zip

This page was last modified on 5 January 2014, at 16:20.
244 page views in the last 30 days.