Initial revision

1 files changed, 179 insertions, 0 deletions

diff --git a/docs/qcop.doc b/docs/qcop.doc
new file mode 100644
index 0000000..6fe4c71
--- a/dev/null
+++ b/docs/qcop.doc
@@ -0,0 +1,179 @@
+/*!
+
+\page qcop.html
+
+\title QCop Messages
+
+QCop messages allow applications to communicate with each other.
+These messages are send using QCopEnvelope, and received by connecting
+to a QCopChannel.
+
+The <tt>channelname</tt> of channels within Qtopia all start with "QPE/".
+The <tt>messagename</tt> is a function identifier followed by a list of types
+in parentheses. There are no spaces in the message name.
+
+The variable names shown in this documentation are purely for information
+purposes.  A message shown as
+"messageName(Type1 varname1, Type2 varname2, Type2 varname3)" would be
+used in program code as:
+
+\code
+   QCopEnvelope e(channelname, "messageName(Type1,Type2,Type2)");
+   e << parameter1 << parameter2 << parameter3;
+\endcode
+
+
+The system-wide channels and messages.
+
+<dl>
+<dt><b>QPE/System</b>
+ <dd>
+  <ul>
+    <li>busy()
+        <br> Causes a wait indicator to be shown to the user.
+    <li>notBusy()
+        <br> Cancels the wait indicator.
+    <li>linkChanged(QString)
+        <br> Sent whenever a link is changed.
+            It is sent by FileManager::saveFile() and others, and
+            received by the Launcher.
+    <li>applyStyle()
+        <br> Sent when user changes style.
+            It is received by QPEApplication and the application
+            will redraw accordingly.
+    <li>quit()
+        <br> Terminates the Qtopia environment.
+    <li>shutdown()
+        <br> Terminates the system.
+    <li>restart()
+        <br> Restarts the Qtopia environment.
+    <li>execute(QString)
+        <br> Executes or raises the given application.
+    <li>execute(QString,QString)
+        <br> Executes or raises the given application, passing an argument.
+            Note that you should consider using the 
+            <b>QPE/Application/<i>appname</i></b> channels described below.
+    <li>addAlarm(QDateTime,QCString,QCString,int)
+        <br> Internal. See AlarmServer::addAlarm()
+    <li>deleteAlarm(QDateTime,QCString,QCString,int)
+        <br> Internal. See AlarmServer::deleteAlarm()
+    <li>setDefaultRotation(int)
+        <br> Internal.
+    <li>grabKeyboard(QString)
+        <br> Internal.
+    <li>timeChange(QString)
+        <br> Internal.
+    <li>clockChange(bool)
+        <br> Internal.
+    <li>setScreenSaverInterval(int)
+        <br> Internal.
+    <li>language(QString)
+        <br> Internal.
+  </ul>
+
+<dt><b>QPE/Sync</b>
+ <ul>
+    <li>flush()
+        <br> Sent at the start of synchronization. Synchable applications
+            should save any synchable data to disk.
+            <i>Note: this message is currently asynchronous. Stay tuned
+                to discussions regarding synchronization, as this message
+                may become synchronous, requiring slight midification to
+                your code. For now, just respond in a timely fashion,
+                since the sync server merely waits a small time.</i>
+    <li>reload()
+        <br> Sent at the end of synchronization. Synchable applications
+            should reload any synchable data from disk.
+ </ul>
+
+<dt><b>QPE/TaskBar</b>
+ <ul>
+    <li>message(QString)
+        <br> Internal. See Global::statusMessage()
+    <li>showInputMethod()
+        <br> Internal.
+    <li>hideInputMethod()
+        <br> Internal.
+    <li>reloadInputMethods()
+        <br> Internal.
+    <li>reloadApplets()
+        <br> Internal.
+ </ul>
+
+<dt><b>QPE/Card</b>
+ <ul>
+    <li>stabChanged()
+        <br> Sent when <tt>/var/run/stab</tt>, <tt>/var/state/pcmcia/stab</tt>,
+                or <tt>/var/lib/pcmcia/stab</tt> may have changed.
+    <li>netUp()
+        <br> Sent when a network connection is running.
+    <li>netDown()
+        <br> Sent when a network connection is available, but not running.
+    <li>netUnavailable()
+        <br> Sent when a network connection is not available.
+ </ul>
+
+<dt><b>Qt/Tray</b>
+ This channel allows Qt applications (not just Qtopia applications)
+ to show system-tray status in a cross-platform manner,
+ but it is not currently supported. See TaskbarAppletInterface for
+ a more powerful alternative for system tray applications.
+ <ul>
+    <li>popup(int,QPoint)
+    <li>remove(int)
+    <li>setIcon(int,QPixmap)
+    <li>setToolTip(int,QString)
+    <li>doubleClicked(int,QPoint)
+    <li>clicked(int,QPoint)
+ </ul>
+</dl>
+
+Each application listens on a channel called
+<b>QPE/Application/<i>appname</i></b>, where <b><i>appname</i></b> is
+the executable name (the application identifier). Standard messages on
+this channel are:
+
+<dl>
+ <dt><b>QPE/Application/<i>appname</i></b>
+  <ul>
+    <li>setDocument(QString)
+        <br>Internal. Causes the setDocument(const QString&) slot
+            of <a href=docwidget.html>the main document widget</a>
+            to be called.
+    <li>nextView()
+        <br>Applications connected to hardware buttons will receive
+            this message if they are already visible.
+    <li>raise()
+        <br>Internal. Causes the the main document widget and the
+            current modal widget to be raised.
+    <li>quit()
+        <br>Internal. Terminates the application.
+    <li>quitIfInvisible()
+        <br>Internal. Terminates the application if it is not shown.
+  </ul>
+</dl>
+
+The QPE/Application/<i>appname</i> channel has a special property: when
+messages are sent to these channels vie QCopEnvelope, the message is
+delivered even if the application is not yet running (the application
+is run and the message is then sent).
+
+Applications also respond to messages specific to the application.
+Such messages in the base Qtopia applications are:
+
+<dl>
+ <dt><b>QPE/Application/helpbrowser</b>
+  <ul>
+   <li>showFile(QString <i>file</i>)
+    <br>Send this message to have the Help Browser show a file.
+        The <i>file</i> may be an absolute filename or relative
+        to the system HTML documentation directory ($QPEDIR/help/html).
+  </ul>
+ <dt><b>QPE/Application/datebook</b>
+  <ul>
+   <li>alarm(QDateTime,int)
+    <br>Internal. Causes the Calendar application to sound alarms.
+  </ul>
+</dl>
+
+*/