author | zecke <zecke> | 2004-02-08 15:19:48 (UTC) |
---|---|---|
committer | zecke <zecke> | 2004-02-08 15:19:48 (UTC) |
commit | d03af1b4f0e9f00f7d135d4366cac818c6797600 (patch) (unidiff) | |
tree | 64e239f1f7134f3e9baadbd18f326112cd59ea60 | |
parent | a763515241faab10c9d86c5cb785c714578e9bb0 (diff) | |
download | opie-d03af1b4f0e9f00f7d135d4366cac818c6797600.zip opie-d03af1b4f0e9f00f7d135d4366cac818c6797600.tar.gz opie-d03af1b4f0e9f00f7d135d4366cac818c6797600.tar.bz2 |
Add API docu
-rw-r--r-- | library/alarmserver.cpp | 60 | ||||
-rw-r--r-- | library/dummy_api_docu.cpp | 58 |
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 | */ |
334 | void AlarmServer::addAlarm ( QDateTime when, const QCString& channel, | 394 | void 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 | */ | ||