Main Page   Class Hierarchy   Alphabetical List   Compound List   File List   Compound Members

FXGUISignal.h

Go to the documentation of this file.
00001 /********************************************************************************
00002 *                                                                               *
00003 *                        S i g n a l   G U I   T h r e a d                      *
00004 *                                                                               *
00005 *********************************************************************************
00006 * Copyright (C) 2005,2006 by Jeroen van der Zijp.   All Rights Reserved.        *
00007 *********************************************************************************
00008 * This library is free software; you can redistribute it and/or                 *
00009 * modify it under the terms of the GNU Lesser General Public                    *
00010 * License as published by the Free Software Foundation; either                  *
00011 * version 2.1 of the License, or (at your option) any later version.            *
00012 *                                                                               *
00013 * This library is distributed in the hope that it will be useful,               *
00014 * but WITHOUT ANY WARRANTY; without even the implied warranty of                *
00015 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU             *
00016 * Lesser General Public License for more details.                               *
00017 *                                                                               *
00018 * You should have received a copy of the GNU Lesser General Public              *
00019 * License along with this library; if not, write to the Free Software           *
00020 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA.    *
00021 *********************************************************************************
00022 * $Id: FXGUISignal.h,v 1.6.2.1 2006/05/24 12:08:45 fox Exp $                        *
00023 ********************************************************************************/
00024 #ifndef FXGUISIGNAL_H
00025 #define FXGUISIGNAL_H
00026 
00027 #ifndef FXOBJECT_H
00028 #include "FXObject.h"
00029 #endif
00030 
00031 namespace FX {
00032 
00033 class FXApp;
00034 
00035 
00036 /**
00037 * An FXGUISignal manages a waitable object which is used to awaken the
00038 * main user-interface thread from a worker thread.  When a FXGUISignal is
00039 * constructed, it automatically calls addInput() function to register itself
00040 * as the message handler for the SEL_IO_READ message from FXApp.  Likewise,
00041 * when FXGUISignal is destroyed, it calls removeInput() to remove itself as
00042 * the message handler for the SEL_IO_READ message from FXApp.
00043 * When a worker thread calls the signal() API, the waitable object managed by
00044 * FXGUISignal is set to the signaled state, after which the worker thread
00045 * continues execution immediately.
00046 * Meanwhile, the main user-interface thread is awakened because one of its
00047 * inputs has become signaled.  It invokes the onSignal handler of FXGUISignal,
00048 * which clears the waitable object's state and subsequently dispatches to the
00049 * target of FXGUISignal through the SEL_IO_READ message.
00050 * Thus, the SEL_IO_READ handler in FXGUISignal is executed in the context of
00051 * the user-interface thread, allowing any user-interaction without blocking
00052 * a worker thread.
00053 * In a typical scenario, a worker thread updates some common data structure,
00054 * then notifies the main user-interface thread (via the FXGUISignal) to update
00055 * the user interface and perform some appropriate action.
00056 */
00057 class FXAPI FXGUISignal : public FXObject {
00058   FXDECLARE(FXGUISignal)
00059 private:
00060   FXApp     *app;       // Application
00061 protected:
00062   FXObject  *target;    // Target object
00063   void      *data;      // User data
00064   FXSelector message;   // Message id
00065 private:
00066 #ifndef WIN32
00067   FXInputHandle fd[2];
00068 #else
00069   FXInputHandle event;
00070 #endif
00071 protected:
00072   FXGUISignal();
00073 private:
00074   FXGUISignal(const FXGUISignal&);
00075   FXGUISignal& operator=(const FXGUISignal&);
00076 public:
00077   enum{
00078     ID_IO_READ=0,
00079     ID_LAST
00080     };
00081 public:
00082   long onSignal(FXObject*,FXSelector,void*);
00083 public:
00084 
00085   /// Constructor
00086   FXGUISignal(FXApp* a,FXObject* tgt=NULL,FXSelector sel=0,void* ptr=NULL);
00087 
00088   /// Get application
00089   FXApp* getApp() const { return app; }
00090 
00091   /// Set the message target object
00092   void setTarget(FXObject *t){ target=t; }
00093 
00094   /// Get the message target object, if any
00095   FXObject* getTarget() const { return target; }
00096 
00097   /// Set the message identifier
00098   void setSelector(FXSelector sel){ message=sel; }
00099 
00100   /// Get the message identifier
00101   FXSelector getSelector() const { return message; }
00102 
00103   /// Set user data pointer
00104   void setData(void *ptr){ data=ptr; }
00105 
00106   /// Get user data pointer
00107   void* getData() const { return data; }
00108 
00109   /**
00110   * Signal the event; this API may be called by the worker thread
00111   * to send a message to the user-interface thread.
00112   */
00113   void signal();
00114 
00115   /// Destructor
00116   virtual ~FXGUISignal();
00117   };
00118 
00119 }
00120 
00121 #endif
00122 
00123 

Copyright © 1997-2005 Jeroen van der Zijp