aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorTed Gould <ted@canonical.com>2008-11-10 13:16:32 -0600
committerTed Gould <ted@canonical.com>2008-11-10 13:16:32 -0600
commit75e2280fccdc9c1284292235c4889d28d437f3a7 (patch)
tree4a70565cc89aa00ab48c2b5235e58f57874667b2
parent0fdb6ccc5652f2aa856a155a9b042fdb291425d5 (diff)
downloadlibayatana-indicator-75e2280fccdc9c1284292235c4889d28d437f3a7.tar.gz
libayatana-indicator-75e2280fccdc9c1284292235c4889d28d437f3a7.tar.bz2
libayatana-indicator-75e2280fccdc9c1284292235c4889d28d437f3a7.zip
Getting some text that I'd written on the target API in the repo.
-rw-r--r--docs/indicator-dbus.txt39
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