document the service's actions and custom menuitems. This will also act as a workitem list for the upcoming GMenuification

1 files changed, 61 insertions, 0 deletions

diff --git a/README b/README
index e69de29..ebeed8b 100644
--- a/README
+++ b/README
@@ -0,0 +1,61 @@
+ACTIONS
+=======
+
+ * "aboutToShow"
+   Description: notifies the indicator that its menu is about to be shown.
+   Workitems that are expensive on startup (such as loading EDS to query
+   it for appointments, or loading GeoClue to guess our current location)
+   may be deferred until this is called.
+   So, calendarDay's state may not be fully populated until this is called.
+   FIXME: aboutToShow should be spec'ed once for all indicators, not ad-hoc
+
+ * "activateSettings"
+   Description: opens a page for changing indicator-datetime's settings
+   State: NULL
+   Parameter: NULL
+
+ * "activatePlanner"
+   Description: opens up the appointment editor.
+   State: NULL
+   Parameter: uint64 (a time_t hinting which day/time to show in the planner,
+              or 0 for the current day)
+
+ * "calendarDay"
+   Description: set which month/day should be given focus in the indicator's
+                calendar and to use as a starting point when listing upcoming
+                appointments in the indicator.
+                Client code implementing the calendar widget should call this
+                when the user clicks to a different day, month, or year.
+   State: a dictionary containing these key value pairs:
+          "calendarDay": string ("YYYY-MM-DD"). Used by the calendar menuitem
+                         to know which year/month should be visible and which
+                         day should have the cursor.
+          "daysWithAppointments": an array of day-of-month ints. Used by the
+                                  calendar menuitem to mark appointment days.
+   Parameter: uint64 (a time_t specifying which day to give focus to)
+
+ * "location"
+   Description: Sets the user's current location. Called by location menuitems.
+   State: string containing a location and a timezone
+   Parameter: string containing a location and a timezone
+
+
+CUSTOM MENUITEMS
+================
+
+ * Calendar
+   - x-canonical-type         s "com.canonical.indicator.calendar"
+
+ * Appointment
+   - x-canonical-type         s "com.canonical.indicator.appointment"
+   - x-canonical-color        s color of the appt's type, to give a visual cue
+   - label                    s short summary of the appointment
+   - x-canonical-right-label  s the date of the appointment
+
+ * Location
+   - x-canonical-type         s "com.canonical.indicator.location"
+   - label                    s the location's name, eg "Oklahoma City"
+   - x-canonical-timezone     s timezone that the location is in
+   - x-canonical-time-format  s strftime format string
+
+