Interfaces

Public Interfaces

• Intent
• Content Provider
• SuntimesCalculator

Intent

Alarm Clock

To schedule an alarm create an Intent with the ACTION_SET_ALARM action.

Intent intent = new Intent(AlarmClock.ACTION_SET_ALARM);
intent.putExtra(AlarmClock.EXTRA_MESSAGE, "My Alarm");
intent.putExtra(AlarmClock.EXTRA_HOUR, hour);
intent.putExtra(AlarmClock.EXTRA_MINUTES, minutes);
intent.putExtra("solarevent", "SUNRISE");
startActivity(intent);

This is the same as scheduling using the Android Alarm Clock, where EXTRA_MESSAGE, EXTRA_HOUR, and EXTRA_MINUTES are expected parameters. Other standard extras include; AlarmClock.EXTRA_VIBRATE, AlarmClock.EXTRA_RINGTONE, and AlarmClock.EXTRA_DAYS.

See https://developer.android.com/reference/android/provider/AlarmClock.

The solarevent extra is a "Suntimes Alarms" feature that will override the hour and minute using the specified solar event.

The following solar event identifiers are recognized: MORNING_ASTRONOMICAL, MORNING_NAUTICAL, MORNING_BLUE8, MORNING_CIVIL, MORNING_BLUE4, SUNRISE, MORNING_GOLDEN, NOON, EVENING_GOLDEN, SUNSET, EVENING_BLUE4, EVENING_CIVIL, EVENING_BLUE8, EVENING_NAUTICAL, EVENING_ASTRONOMICAL, MOONRISE, MOONSET

The latitude, longitude, and altitude extras allow overriding the event location (defaults to the app location). If these extras are supplied, the location_label extra can also be supplied to set the place name.

Others

TODO: (Re)configure activity intent & extras. TODO: widget list, theme list

Content Provider

A ContentProvider permits third-party access to implementations of the SuntimesCalculator interface (and supporting configuration data); since v0.10.0.

See the CalculatorProviderContract for more information.

An Example

// Gets the time of all full moons occurring between `startDate` to `endDate`:

String[] projection = new String[] { COLUMN_MOON_FULL };
Uri uri = Uri.parse("content://" + AUTHORITY + "/" + QUERY_MOONPHASE + "/" 
        + startDate.getTimeInMillis() + "-" + endDate.getTimeInMillis());    
  
ContentResolver resolver = context.getContentResolver();
Cursor cursor = resolver.query(uri, projection, null, null, null);
if (cursor != null
{
    cursor.moveToFirst();
    while (!cursor.isAfterLast())
    {
        Long fullMoonTimeMillis = cursor.getLong(cursor.getColumnIndex(COLUMN_MOON_FULL));
        if (fullMoonTimeMillis != null) {             
            // ...
        }
        cursor.moveToNext();
    }
    cursor.close();
}       

SuntimesCalculator

The app uses an interface to perform all calculations. To add a new calculator you must first implement SuntimesCalculator, and then publish a SuntimesCalculatorDescriptor.

Implementing the Interface

TODO

Publishing a Descriptor

A) Publish as a default

The default calculators are defined in SuntimesCalculatorDescriptor.initCalculators(). Add a call to addValue that initializes your descriptor with the rest of the defaults, then recompile the app.

B) Publish as a plugin

It is also possible to dynamically add calculators without recompiling by publishing the descriptor from the AndroidManifest.xml.

Create a new project with a single Activity and an implementation of the interface. Supposing our calculator implementation is MySuntimesCalculator.java, the project manifest might look like...

    <activity android:name="com.example.MyCalculatorPlugin">    
        <meta-data android:name="CalculatorName" android:value="mycalculatorname" />
        <meta-data android:name="CalculatorDisplayString" android:value="My Calculator" />
        <meta-data android:name="CalculatorReference" android:value="com.example.MySuntimesCalculator" />
        <meta-data android:name="CalculatorFeatures" android:value="0,30" />
        <intent-filter>
            <action android:name="android.intent.action.RUN" />
            <category android:name="com.forrestguice.suntimeswidget.SUNTIMES_CALCULATOR" />
        </intent-filter>
    </activity>

...where CalculatorName, CalculatorDisplayString, CalculatorReference, and CalculatorFeatures match the values defined by our implementation. The MyCalculatorPlugin activity itself can be empty (or optionally shown by the launcher to display "about" info).

Compile the new project and install the resulting apk.

When the data source plugins option is enabled, Suntimes will automatically scan for activities that provide the RUN action and attempt to load a descriptor.