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