Home | History | Annotate | Download | only in views 
      1 /*
      2  * Copyright 2006 The Android Open Source Project
      3  *
      4  * Use of this source code is governed by a BSD-style license that can be
      5  * found in the LICENSE file.
      6  */
      7 
      8 #ifndef SkEvent_DEFINED
      9 #define SkEvent_DEFINED
     10 
     11 #include "SkDOM.h"
     12 #include "SkMetaData.h"
     13 #include "SkString.h"
     14 
     15 /** Unique 32bit id used to identify an instance of SkEventSink. When events are
     16     posted, they are posted to a specific sinkID. When it is time to dispatch the
     17     event, the sinkID is used to find the specific SkEventSink object. If it is found,
     18     its doEvent() method is called with the event.
     19 */
     20 typedef uint32_t SkEventSinkID;
     21 
     22 /**
     23  *  \class SkEvent
     24  *
     25  *  When an event is dispatched from the event queue, it is either sent to
     26  *  the eventsink matching the target ID (if not 0), or the target proc is
     27  *  called (if not NULL).
     28  */
     29 class SkEvent {
     30 public:
     31     /**
     32      *  Function pointer that takes an event, returns true if it "handled" it.
     33      */
     34     typedef bool (*Proc)(const SkEvent& evt);
     35 
     36     SkEvent();
     37     explicit SkEvent(const SkString& type, SkEventSinkID = 0);
     38     explicit SkEvent(const char type[], SkEventSinkID = 0);
     39     SkEvent(const SkEvent& src);
     40     ~SkEvent();
     41 
     42     /** Copy the event's type into the specified SkString parameter */
     43     void getType(SkString* str) const;
     44 
     45     /** Returns true if the event's type matches exactly the specified type (case sensitive) */
     46     bool isType(const SkString& str) const;
     47 
     48     /** Returns true if the event's type matches exactly the specified type (case sensitive) */
     49     bool isType(const char type[], size_t len = 0) const;
     50 
     51     /**
     52      *  Set the event's type to the specified string.
     53      */
     54     void setType(const SkString&);
     55 
     56     /**
     57      *  Set the event's type to the specified string.
     58      */
     59     void setType(const char type[], size_t len = 0);
     60 
     61     /**
     62      *  Return the target ID, or 0 if there is none.
     63      *
     64      *  When an event is dispatched from the event queue, it is either sent to
     65      *  the eventsink matching the targetID (if not 0), or the target proc is
     66      *  called (if not NULL).
     67      */
     68     SkEventSinkID getTargetID() const { return fTargetID; }
     69 
     70     /**
     71      *  Set the target ID for this event. 0 means none. Calling this will
     72      *  automatically clear the targetProc to null.
     73      *
     74      *  When an event is dispatched from the event queue, it is either sent to
     75      *  the eventsink matching the targetID (if not 0), or the target proc is
     76      *  called (if not NULL).
     77      */
     78     SkEvent* setTargetID(SkEventSinkID targetID) {
     79         fTargetProc = NULL;
     80         fTargetID = targetID;
     81         return this;
     82     }
     83 
     84     /**
     85      *  Return the target proc, or NULL if it has none.
     86      *
     87      *  When an event is dispatched from the event queue, it is either sent to
     88      *  the eventsink matching the targetID (if not 0), or the target proc is
     89      *  called (if not NULL).
     90      */
     91     Proc getTargetProc() const { return fTargetProc; }
     92 
     93     /**
     94      *  Set the target ID for this event. NULL means none. Calling this will
     95      *  automatically clear the targetID to 0.
     96      *
     97      *  When an event is dispatched from the event queue, it is either sent to
     98      *  the eventsink matching the targetID (if not 0), or the target proc is
     99      *  called (if not NULL).
    100      */
    101     SkEvent* setTargetProc(Proc proc) {
    102         fTargetID = 0;
    103         fTargetProc = proc;
    104         return this;
    105     }
    106 
    107     /**
    108      *  Return the event's unnamed 32bit field. Default value is 0
    109      */
    110     uint32_t getFast32() const { return f32; }
    111 
    112     /**
    113      *  Set the event's unnamed 32bit field.
    114      */
    115     void setFast32(uint32_t x) { f32 = x; }
    116 
    117     /** Return true if the event contains the named 32bit field, and return the field
    118         in value (if value is non-null). If there is no matching named field, return false
    119         and ignore the value parameter.
    120     */
    121     bool findS32(const char name[], int32_t* value = NULL) const { return fMeta.findS32(name, value); }
    122     /** Return true if the event contains the named SkScalar field, and return the field
    123         in value (if value is non-null). If there is no matching named field, return false
    124         and ignore the value parameter.
    125     */
    126     bool findScalar(const char name[], SkScalar* value = NULL) const { return fMeta.findScalar(name, value); }
    127     /** Return true if the event contains the named SkScalar field, and return the fields
    128         in value[] (if value is non-null), and return the number of SkScalars in count (if count is non-null).
    129         If there is no matching named field, return false and ignore the value and count parameters.
    130     */
    131     const SkScalar* findScalars(const char name[], int* count, SkScalar values[] = NULL) const { return fMeta.findScalars(name, count, values); }
    132     /** Return the value of the named string field, or if no matching named field exists, return null.
    133     */
    134     const char* findString(const char name[]) const { return fMeta.findString(name); }
    135     /** Return true if the event contains the named pointer field, and return the field
    136         in value (if value is non-null). If there is no matching named field, return false
    137         and ignore the value parameter.
    138     */
    139     bool findPtr(const char name[], void** value) const { return fMeta.findPtr(name, value); }
    140     bool findBool(const char name[], bool* value) const { return fMeta.findBool(name, value); }
    141     const void* findData(const char name[], size_t* byteCount = NULL) const {
    142         return fMeta.findData(name, byteCount);
    143     }
    144 
    145     /** Returns true if ethe event contains the named 32bit field, and if it equals the specified value */
    146     bool hasS32(const char name[], int32_t value) const { return fMeta.hasS32(name, value); }
    147     /** Returns true if ethe event contains the named SkScalar field, and if it equals the specified value */
    148     bool hasScalar(const char name[], SkScalar value) const { return fMeta.hasScalar(name, value); }
    149     /** Returns true if ethe event contains the named string field, and if it equals (using strcmp) the specified value */
    150     bool hasString(const char name[], const char value[]) const { return fMeta.hasString(name, value); }
    151     /** Returns true if ethe event contains the named pointer field, and if it equals the specified value */
    152     bool hasPtr(const char name[], void* value) const { return fMeta.hasPtr(name, value); }
    153     bool hasBool(const char name[], bool value) const { return fMeta.hasBool(name, value); }
    154     bool hasData(const char name[], const void* data, size_t byteCount) const {
    155         return fMeta.hasData(name, data, byteCount);
    156     }
    157 
    158     /** Add/replace the named 32bit field to the event. In XML use the subelement <data name=... s32=... /> */
    159     void setS32(const char name[], int32_t value) { fMeta.setS32(name, value); }
    160     /** Add/replace the named SkScalar field to the event. In XML use the subelement <data name=... scalar=... /> */
    161     void setScalar(const char name[], SkScalar value) { fMeta.setScalar(name, value); }
    162     /** Add/replace the named SkScalar[] field to the event. */
    163     SkScalar* setScalars(const char name[], int count, const SkScalar values[] = NULL) { return fMeta.setScalars(name, count, values); }
    164     /** Add/replace the named string field to the event. In XML use the subelement <data name=... string=... */
    165     void setString(const char name[], const SkString& value) { fMeta.setString(name, value.c_str()); }
    166     /** Add/replace the named string field to the event. In XML use the subelement <data name=... string=... */
    167     void setString(const char name[], const char value[]) { fMeta.setString(name, value); }
    168     /** Add/replace the named pointer field to the event. There is no XML equivalent for this call */
    169     void setPtr(const char name[], void* value) { fMeta.setPtr(name, value); }
    170     void setBool(const char name[], bool value) { fMeta.setBool(name, value); }
    171     void setData(const char name[], const void* data, size_t byteCount) {
    172         fMeta.setData(name, data, byteCount);
    173     }
    174 
    175     /** Return the underlying metadata object */
    176     SkMetaData& getMetaData() { return fMeta; }
    177     /** Return the underlying metadata object */
    178     const SkMetaData& getMetaData() const { return fMeta; }
    179 
    180     /** Call this to initialize the event from the specified XML node */
    181     void inflate(const SkDOM&, const SkDOM::Node*);
    182 
    183     SkDEBUGCODE(void dump(const char title[] = NULL);)
    184 
    185     ///////////////////////////////////////////////////////////////////////////
    186 
    187     /**
    188      *  Post to the event queue using the event's targetID or target-proc.
    189      *
    190      *  The event must be dynamically allocated, as ownership is transferred to
    191      *  the event queue. It cannot be allocated on the stack or in a global.
    192      */
    193     void post() {
    194         return this->postDelay(0);
    195     }
    196 
    197     /**
    198      *  Post to the event queue using the event's targetID or target-proc and
    199      *  the specifed millisecond delay.
    200      *
    201      *  The event must be dynamically allocated, as ownership is transferred to
    202      *  the event queue. It cannot be allocated on the stack or in a global.
    203      */
    204     void postDelay(SkMSec delay);
    205 
    206     /**
    207      *  Post to the event queue using the event's targetID or target-proc.
    208      *  The event will be delivered no sooner than the specified millisecond
    209      *  time, as measured by SkTime::GetMSecs().
    210      *
    211      *  The event must be dynamically allocated, as ownership is transferred to
    212      *  the event queue. It cannot be allocated on the stack or in a global.
    213      */
    214     void postTime(SkMSec time);
    215 
    216     ///////////////////////////////////////////////
    217     /** Porting layer must call these functions **/
    218     ///////////////////////////////////////////////
    219 
    220     /** Global initialization function for the SkEvent system. Should be called exactly
    221         once before any other event method is called, and should be called after the
    222         call to SkGraphics::Init().
    223     */
    224     static void Init();
    225     /** Global cleanup function for the SkEvent system. Should be called exactly once after
    226         all event methods have been called, and should be called before calling SkGraphics::Term().
    227     */
    228     static void Term();
    229 
    230     /** Call this to process one event from the queue. If it returns true, there are more events
    231         to process.
    232     */
    233     static bool ProcessEvent();
    234     /** Call this whenever the requested timer has expired (requested by a call to SetQueueTimer).
    235         It will post any delayed events whose time as "expired" onto the event queue.
    236         It may also call SignalQueueTimer() and SignalNonEmptyQueue().
    237     */
    238     static void ServiceQueueTimer();
    239 
    240     /** Return the number of queued events. note that this value may be obsolete
    241         upon return, since another thread may have called ProcessEvent() or
    242         Post() after the count was made.
    243      */
    244     static int CountEventsOnQueue();
    245 
    246     ////////////////////////////////////////////////////
    247     /** Porting layer must implement these functions **/
    248     ////////////////////////////////////////////////////
    249 
    250     /** Called whenever an SkEvent is posted to an empty queue, so that the OS
    251         can be told to later call Dequeue().
    252     */
    253     static void SignalNonEmptyQueue();
    254     /** Called whenever the delay until the next delayed event changes. If zero is
    255         passed, then there are no more queued delay events.
    256     */
    257     static void SignalQueueTimer(SkMSec delay);
    258 
    259 #if defined(SK_BUILD_FOR_WIN)
    260     static bool WndProc(HWND hWnd, UINT message, WPARAM wParam, LPARAM lParam);
    261 #endif
    262 
    263 private:
    264     SkMetaData      fMeta;
    265     mutable char*   fType;  // may be characters with low bit set to know that it is not a pointer
    266     uint32_t        f32;
    267 
    268     // 'there can be only one' (non-zero) between target-id and target-proc
    269     SkEventSinkID   fTargetID;
    270     Proc            fTargetProc;
    271 
    272     // these are for our implementation of the event queue
    273     SkMSec          fTime;
    274     SkEvent*        fNextEvent; // either in the delay or normal event queue
    275 
    276     void initialize(const char* type, size_t typeLen, SkEventSinkID);
    277 
    278     static bool Enqueue(SkEvent* evt);
    279     static SkMSec EnqueueTime(SkEvent* evt, SkMSec time);
    280     static SkEvent* Dequeue();
    281     static bool     QHasEvents();
    282 };
    283 
    284 #endif
    285