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>
+
+*/