aboutsummaryrefslogtreecommitdiff
path: root/README.md
diff options
context:
space:
mode:
authorMike Gabriel <mike.gabriel@das-netzwerkteam.de>2017-12-08 13:38:50 +0100
committerMike Gabriel <mike.gabriel@das-netzwerkteam.de>2017-12-08 13:38:50 +0100
commitdabd7c8c65ef0132dbf75360ae83e9505cbe614d (patch)
tree3deaba23121a0c8ebf058cc8d39bca1dabf3ea73 /README.md
parent436caeff89a4c3b8d6abb2a2381ad3d5c39e83ad (diff)
downloadayatana-indicator-datetime-dabd7c8c65ef0132dbf75360ae83e9505cbe614d.tar.gz
ayatana-indicator-datetime-dabd7c8c65ef0132dbf75360ae83e9505cbe614d.tar.bz2
ayatana-indicator-datetime-dabd7c8c65ef0132dbf75360ae83e9505cbe614d.zip
README(.md): Ship README.md, symlinked from README -> README.md.
Diffstat (limited to 'README.md')
-rw-r--r--README.md130
1 files changed, 130 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..a28eb39
--- /dev/null
+++ b/README.md
@@ -0,0 +1,130 @@
+# Ayatana Indicator DateTime
+
+## ACTIONS
+
+ * "desktop.open-settings-app"
+ * "phone.open-settings-app"
+ Description: open the settings application.
+ State: None
+ Parameter: None
+
+ * "desktop.open-alarm-app"
+ * "phone.open-alarm-app"
+ Description: open the application for creating new alarms.
+ State: None
+ Parameter: None
+
+ * "desktop.open-calendar-app"
+ * "phone.open-calendar-app"
+ State: None
+ Parameter: int64, a time_t hinting which day/time to show in the planner,
+ or 0 for the current day
+
+ * "desktop.open-appointment"
+ * "phone.open-appointment"
+ Description: opens an appointment editor to the specified appointment.
+ State: None
+ Parameter: string, an opaque uid to specify which appointment to use.
+ This uid comes from the menuitems' target values.
+
+ * "set-location"
+ Description: Set the current location. This will try to set the current
+ timezone to the new location's timezone.
+ State: None
+ Parameter: a timezone id string followed by a space and location name.
+ Example: "America/Chicago Oklahoma City"
+
+ * "calendar"
+ Description: set which month/day should be given focus in the indicator's
+ calendar. The planner will look for appointments from this
+ day to the end of the same month.
+ Client code implementing the calendar view should call this
+ when the user clicks on a new day, month, or year.
+ State: a dictionary containing these key value/pairs:
+ "appointment-days": an array of day-of-month ints. Used by the
+ calendar menuitem to mark appointment days.
+ "calendar-day": int64, a time_t. Used by the calendar menuitem
+ to know which year/month should be visible
+ and which day should have the cursor.
+ "show-week-numbers": if true, show week numbers in the calendar.
+ Parameter: int64, a time_t specifying which year/month should be visible
+ and which day should have the cursor.
+
+
+## CUSTOM MENUITEMS
+
+ * Calendar
+ - x-canonical-type s "org.ayatana.indicator.calendar"
+
+ * Alarm
+ - label s short summary of the appointment
+ - x-canonical-type s "org.ayatana.indicator.alarm"
+ - x-canonical-time x the date of the appointment
+ - x-canonical-time-format s strftime format string
+
+ * Appointment
+ - label s short summary of the appointment
+ - x-canonical-type s "org.ayatana.indicator.appointment"
+ - x-canonical-color s color of the appt's type, to give a visual cue
+ - x-canonical-time x the date of the appointment
+ - x-canonical-time-format s strftime format string
+
+ * Location
+ - label s the location's name, eg "Oklahoma City"
+ - x-canonical-type s "org.ayatana.indicator.location"
+ - x-canonical-timezone s timezone that the location is in
+ - x-canonical-time-format s strftime format string
+
+
+
+## CODE
+
+Model
+
+ The app's model is represented by the "State" class, and "Menu" objects
+ are the corresponding views. "State" is a simple container for various
+ properties, and menus connect to those properties' changed() signals to
+ know when the view needs to be refreshed.
+
+ As one can see in main.c, the app's very simple flow is to instantiate
+ a state and its properties, build menus that correspond to the state,
+ and export the menus on DBus.
+
+ Because State is a simple aggregate of its components (such as a "Clock"
+ or "Planner" object to get the current time and upcoming appointments,
+ respectively), one can plug in live components for production and mock
+ components for unit tests. The entire backend can be mix-and-matched by
+ adding the desired test-or-production components.
+
+ Start with:
+ include/datetime/state.h
+ include/datetime/clock.h
+ include/datetime/locations.h
+ include/datetime/planner.h
+ include/datetime/settings.h
+ include/datetime/timezones.h
+
+ Implementations:
+ include/datetime/settings-live.h
+ include/datetime/locations-settings.h
+ include/datetime/planner-eds.h
+ include/datetime/timezones-live.h
+
+## View
+
+ Menu is a mostly-opaque class to wrap GMenu code. Its subclasses contain
+ the per-profile logic of which sections/menuitems to show and which to hide.
+ Menus are instantiated via the MenuFactory, which takes a state and profile.
+
+ Actions is a mostly-opaque class to wrap our GActionGroup. Its subclasses
+ contain the code that actually executed when an action is triggered (ie,
+ LiveActions for production and MockActions for testing).
+
+ Exporter exports the Actions and Menus onto the DBus, and also emits a
+ signal if/when the busname is lost so indicator-datetime-service knows
+ when to exit.
+
+ include/datetime/menu.h
+ include/datetime/actions.h
+ include/datetime/exporter.h
+