| -rw-r--r-- | docs/qcop.doc | 179 |
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> + +*/ |