summaryrefslogtreecommitdiff
path: root/docs/qcop.doc
Side-by-side diff
Diffstat (limited to 'docs/qcop.doc') (more/less context) (show whitespace changes)
-rw-r--r--docs/qcop.doc179
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>
+
+*/