summaryrefslogtreecommitdiff
authorzecke <zecke>2004-02-08 15:19:48 (UTC)
committer zecke <zecke>2004-02-08 15:19:48 (UTC)
commitd03af1b4f0e9f00f7d135d4366cac818c6797600 (patch) (unidiff)
tree64e239f1f7134f3e9baadbd18f326112cd59ea60
parenta763515241faab10c9d86c5cb785c714578e9bb0 (diff)
downloadopie-d03af1b4f0e9f00f7d135d4366cac818c6797600.zip
opie-d03af1b4f0e9f00f7d135d4366cac818c6797600.tar.gz
opie-d03af1b4f0e9f00f7d135d4366cac818c6797600.tar.bz2
Add API docu
Diffstat (more/less context) (ignore whitespace changes)
-rw-r--r--library/alarmserver.cpp60
-rw-r--r--library/dummy_api_docu.cpp58
2 files changed, 118 insertions, 0 deletions
diff --git a/library/alarmserver.cpp b/library/alarmserver.cpp
index a75fc7e..6f6f32d 100644
--- a/library/alarmserver.cpp
+++ b/library/alarmserver.cpp
@@ -295,61 +295,121 @@ void TimerReceiverObject::timerEvent( QTimerEvent * )
295 setNearestTimerEvent(); 295 setNearestTimerEvent();
296 } 296 }
297 else { 297 else {
298 resetTimer(); 298 resetTimer();
299 } 299 }
300 if ( needSave ) 300 if ( needSave )
301 saveState(); 301 saveState();
302} 302}
303 303
304/*! 304/*!
305 \class AlarmServer alarmserver.h 305 \class AlarmServer alarmserver.h
306 \brief The AlarmServer class allows alarms to be scheduled and unscheduled. 306 \brief The AlarmServer class allows alarms to be scheduled and unscheduled.
307 307
308 Applications can schedule alarms with addAlarm() and can 308 Applications can schedule alarms with addAlarm() and can
309 unschedule alarms with deleteAlarm(). When the time for an alarm 309 unschedule alarms with deleteAlarm(). When the time for an alarm
310 to go off is reached the specified \link qcop.html QCop\endlink 310 to go off is reached the specified \link qcop.html QCop\endlink
311 message is sent on the specified channel (optionally with 311 message is sent on the specified channel (optionally with
312 additional data). 312 additional data).
313 313
314 Scheduling an alarm using this class is important (rather just using 314 Scheduling an alarm using this class is important (rather just using
315 a QTimer) since the machine may be asleep and needs to get woken up using 315 a QTimer) since the machine may be asleep and needs to get woken up using
316 the Linux kernel which implements this at the kernel level to minimize 316 the Linux kernel which implements this at the kernel level to minimize
317 battery usage while asleep. 317 battery usage while asleep.
318 318
319 A small example on how to use AlarmServer.
320
321 First we need to connect a slot the AppMessage QCOP call. appMessage
322 will be emitted if QPE/Application/appname gets called.
323
324 \code
325 TestApp::TestApp(QWidget *parent, const char* name, WFlags fl )
326 : QMainWindow(parent,name,fl){
327 connect(qApp,SIGNAL(appMessage(const QCString&,const QByteArray&)),
328 this,SLOT(slotAppMessage(const QCString&,const QByteArray&)));
329 }
330 \endcode
331
332 To add / delete an alarm, you can use the static method AlarmServer::addAlarm and
333 AlarmServer::deleteAlarm. Note that an old (expired) alarm will automatically be deleted
334 from the alarmserver list, but a change in timing will have the effect, that both
335 alarms will be emitted. So if you change an Alarm be sure to delete the old one!
336 @see addAlarm
337
338 \code
339 QDateTime oldDt = oldAlarmDateTime();
340 QPEApplication::execDialog(ourDlg);
341 QDateTime newDt = ourDlg->dateTime();
342 if(newDt == oldDt ) return;
343 @slash* code is missing for unsetting an alarm *@slash
344
345 AlarmServer::deleteAlarm(oldDt,"QPE/Application/appname","checkAlarm(QDateTime,int)",0);
346 AlarmServer::addAlarm( newDt,"QPE/AlarmServer/appname","checkAlarm(QDateTime,int)",0);
347
348 \endcode
349
350 Now once the Alarm is emitted you need to check the appMessage and then do what you want.
351 \code
352 void TestApp::slotAppMessage(const QCString& str, const QByteArray& ar ){
353 QDataStream stream(ar,IO_ReadOnly);
354 if(str == "checkAlarm(QDateTime,int)" ){
355 QDateTime dt;
356 int a;
357 stream >> dt >> a;
358 // fire up alarm
359 }
360 }
361 \endcode
362
319 \ingroup qtopiaemb 363 \ingroup qtopiaemb
320 \sa QCopEnvelope 364 \sa QCopEnvelope
365 @see QPEApplication::appMessage(const QCString&,const QByteArray&)
366 @see OPimMainWindow
367 @see ODevice::alarmSound()
368 @see Sound::soundAlarm()
321*/ 369*/
322 370
323/*! 371/*!
324 Schedules an alarm to go off at (or soon after) time \a when. When 372 Schedules an alarm to go off at (or soon after) time \a when. When
325 the alarm goes off, the \link qcop.html QCop\endlink \a message will 373 the alarm goes off, the \link qcop.html QCop\endlink \a message will
326 be sent to \a channel, with \a data as a parameter. 374 be sent to \a channel, with \a data as a parameter.
327 375
328 If this function is called with exactly the same data as a previous 376 If this function is called with exactly the same data as a previous
329 call the subsequent call is ignored, so there is only ever one alarm 377 call the subsequent call is ignored, so there is only ever one alarm
330 with a given set of parameters. 378 with a given set of parameters.
331 379
380 Once an alarm is emitted. The \a channel with a \a message will be emitted
381 and data will be send.
382 The QDateTime and int are the two parameters included in the QCOP message.
383 You can specify channel, message and the integer parameter. QDateTime will be
384 the datetime of the QCop call.
385
386 @param when The QDateTime of the alarm
387 @param channel The channel which gets called once the alarm is emitted
388 @param message The message to be send to the channel
389 @param data Additional data as integer
390
391 @see QCopChannel
332 \sa deleteAlarm() 392 \sa deleteAlarm()
333*/ 393*/
334void AlarmServer::addAlarm ( QDateTime when, const QCString& channel, 394void AlarmServer::addAlarm ( QDateTime when, const QCString& channel,
335 const QCString& message, int data) 395 const QCString& message, int data)
336{ 396{
337 if ( qApp->type() == QApplication::GuiServer ) { 397 if ( qApp->type() == QApplication::GuiServer ) {
338 bool needSave = FALSE; 398 bool needSave = FALSE;
339 // Here we are the server so either it has been directly called from 399 // Here we are the server so either it has been directly called from
340 // within the server or it has been sent to us from a client via QCop 400 // within the server or it has been sent to us from a client via QCop
341 if (!timerEventReceiver) 401 if (!timerEventReceiver)
342 timerEventReceiver = new TimerReceiverObject; 402 timerEventReceiver = new TimerReceiverObject;
343 403
344 timerEventItem *newTimerEventItem = new timerEventItem; 404 timerEventItem *newTimerEventItem = new timerEventItem;
345 newTimerEventItem->UTCtime = TimeConversion::toUTC( when ); 405 newTimerEventItem->UTCtime = TimeConversion::toUTC( when );
346 newTimerEventItem->channel = channel; 406 newTimerEventItem->channel = channel;
347 newTimerEventItem->message = message; 407 newTimerEventItem->message = message;
348 newTimerEventItem->data = data; 408 newTimerEventItem->data = data;
349 // explore the case of already having the event in here... 409 // explore the case of already having the event in here...
350 QListIterator<timerEventItem> it( timerEventList ); 410 QListIterator<timerEventItem> it( timerEventList );
351 for ( ; *it; ++it ) 411 for ( ; *it; ++it )
352 if ( *(*it) == *newTimerEventItem ) 412 if ( *(*it) == *newTimerEventItem )
353 return ; 413 return ;
354 // if we made it here, it is okay to add the item... 414 // if we made it here, it is okay to add the item...
355 timerEventList.append( newTimerEventItem ); 415 timerEventList.append( newTimerEventItem );
diff --git a/library/dummy_api_docu.cpp b/library/dummy_api_docu.cpp
index 6b76401..f2153df 100644
--- a/library/dummy_api_docu.cpp
+++ b/library/dummy_api_docu.cpp
@@ -288,24 +288,82 @@
288 288
289 289
290/** 290/**
291 * \class TaskbarAppletInterface 291 * \class TaskbarAppletInterface
292 * 292 *
293 * This is the base class of all Applets shown in the taskbar 293 * This is the base class of all Applets shown in the taskbar
294 * An applets need to provide a position and a widget. 294 * An applets need to provide a position and a widget.
295 * 295 *
296 * Applets need to be put into OPIEDIR/plugins/applets 296 * Applets need to be put into OPIEDIR/plugins/applets
297 * 297 *
298 */ 298 */
299/** 299/**
300 * \fn QWidget* TaskbarAppletInterface::applet( QWidget* parent ) 300 * \fn QWidget* TaskbarAppletInterface::applet( QWidget* parent )
301 * \brief return the new Applet Widget 301 * \brief return the new Applet Widget
302 * 302 *
303 * @param parent The parent of the Applet normally the taskbar 303 * @param parent The parent of the Applet normally the taskbar
304 */ 304 */
305 305
306/** 306/**
307 * \fn int TaskbarAppletInterface::position()const; 307 * \fn int TaskbarAppletInterface::position()const;
308 * \brief the wished position 308 * \brief the wished position
309 * 309 *
310 * From left to right. 0 is left. The clock uses 10 310 * From left to right. 0 is left. The clock uses 10
311 */ 311 */
312
313
314/**
315 * \class WindowDecorationInterface
316 *
317 * Interface class for Window Decorations. Yu need to implement
318 * metric and drawing functions.
319 */
320
321/**
322 * \class WindowDecorationInterface::WindowData
323 *
324 * Window informations like the QRect, Palette, Caption
325 * and flag
326 */
327
328/**
329 * \fn int WindowDecorationInterface::metric(Metric m,const WindowData* )
330 *
331 * Return the width for the item out of Metric.
332 * Normally you will case Metric and default: should call the interface
333 * method. Also return 0
334 */
335
336/**
337 * \fn void WindowDecorationInterface::drawArea( Area a, QPainter* , const WindowData* )const
338 *
339 * draw the Area specefic in a to the QPainter
340 */
341
342/**
343 * \fn void WindowDecorationInterface::drawButton(Button b,QPainter*p ,const WindowData* d, int x, int y, int w,int h, QWSButton::State s)const
344 *
345 * @param b The Button to be drawn
346 * @param p The painter to draw at
347 * @param d The Window Data
348 * @param x The X position of the button
349 * @param y The Y position of the button
350 * @param w The width of the button
351 * @param h The height of the button
352 * @param s The state of the button
353 */
354
355/**
356 * \fn QRegion WindowDecorationInterface::mask( const WindowData* )const
357 *
358 * The mask of the Decoration.
359 *
360 * \code
361 * int th = metric(TitleHeight,wd);
362 * QRect rect( wd->rect );
363 * QRect r(rect.left() - metric(LeftBorder,wd),
364 * rect.top() - th - metric(TopBorder,wd),
365 * rect.width() + metric(LeftBorder,wd) + metric(RightBorder,wd),
366 * rect.height() + th + metric(TopBorder,wd) + metric(BottomBorder,wd));
367 * return QRegion(r) - rect;
368 * \endcode
369 */