Getting some text that I'd written on the target API in the repo.

1 files changed, 39 insertions, 0 deletions

diff --git a/docs/indicator-dbus.txt b/docs/indicator-dbus.txt
new file mode 100644
index 0000000..7e655b5
--- /dev/null
+++ b/docs/indicator-dbus.txt
@@ -0,0 +1,39 @@
+Thoughts on Indicators
+
+There are two ways to think about how applications interact with users.  One is to tell the user that something is happening right now, the other is to flag the user that more information is available if they'd like to work.  These can be combined, leaving a temporal instantaneous notification and a perennial marker of the event happening.  Together, these allow for applications that are not currently in the user's focus to provide information and also notify the user that they require attention.
+
+Due to the nature of notifications being constant until the user interacts with the application, I think that the interface between the indicators on the panel and the application should mirror this.  The application would then provide an interface over DBus that would provide access to it's notifications and signals for when they change.
+
+
+Methods
+
+• GetDesktop -> string -- returns the path to the desktop file that represents this application.  This is used for getting information like the name and icon of the application to display in notifications.
+• GetIndicatorCount -> uint -- returns the number of indicators that are currently shown by the application.
+• GetIndicatorCountByType (type) -> uint -- allows a caller to only notice indicators of a particular type.  For instance to separate out mail and calendar notifications in a PIM.
+• GetIndicatorList -> int[] -- an array of all the indicator IDs that are currently displayed by the application.
+• GetIndicatorListByType (type) -> int[] -- an array of all the indicator IDs that are currently displayed filtered by type.
+• GetIndicatorProperty (id, property) -> string -- indicators can have properties that describe them.  There is a set of required and optional properties for specific types.
+• GetIndicatorPropertyGroup (id, property[]) -> string[] -- same as GetIndicatorProperty, but with lots of properties in one call.
+• GetIndicatorProperties (id) -> string[] -- A list of the properties that are on this indicator.
+• ShowIndicatorToUser(id) -- calling this function is an indication to the application that the user has indicated that they would like more information on this indicator.  If this is something like an e-mail message the message should be shown.  If it is a conversation, the window with the conversation in it should be shown.
+
+
+Signals
+
+• IndicatorAdded (id, type) -- signaled when a new indicator is added
+• IndicatorRemoved (id, type) -- signaled when an indicator is deleted
+• IndicatorModified (id, property) -- thrown when an indicator's properties change
+
+
+Types
+
+• "message" -- a user level message.  This includes e-mail, IM and SMS messages.
+• "system" -- a software update or other notification about the system state.
+• "media" -- a notification related media the user is listening to in the background
+
+
+Properties
+
+• "subject" -- "message" (optional) -- This is the subject line of an e-mail or message.
+• "sender" -- "message" (required) -- The person who sent the message
+• "body" -- "message" (required) -- The body of the message sent to the user