SkEvent.h revision 8a1c16ff38322f0210116fa7293eb8817c7e477e 
1/*
2 * Copyright (C) 2006 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17#ifndef SkEvent_DEFINED
18#define SkEvent_DEFINED
19
20#include "SkDOM.h"
21#include "SkMetaData.h"
22#include "SkString.h"
23
24//class SkOSWindow;
25
26/** Unique 32bit id used to identify an instance of SkEventSink. When events are
27    posted, they are posted to a specific sinkID. When it is time to dispatch the
28    event, the sinkID is used to find the specific SkEventSink object. If it is found,
29    its doEvent() method is called with the event.
30*/
31typedef uint32_t SkEventSinkID;
32
33/** \class SkEvent
34
35    SkEvents are used to communicate type-safe information to SkEventSinks.
36    SkEventSinks (including SkViews) each have a unique ID, which is stored
37    in an event. This ID is used to target the event once it has been "posted".
38*/
39class SkEvent {
40public:
41    /** Default construct, creating an empty event.
42    */
43    SkEvent();
44    /** Construct a new event with the specified type.
45    */
46    explicit SkEvent(const SkString& type);
47    /** Construct a new event with the specified type.
48    */
49    explicit SkEvent(const char type[]);
50    /** Construct a new event by copying the fields from the src event.
51    */
52    SkEvent(const SkEvent& src);
53    ~SkEvent();
54
55//  /** Return the event's type (will never be null) */
56//  const char* getType() const;
57    /** Copy the event's type into the specified SkString parameter */
58    void    getType(SkString* str) const;
59    /** Returns true if the event's type matches exactly the specified type (case sensitive) */
60    bool    isType(const SkString& str) const;
61    /** Returns true if the event's type matches exactly the specified type (case sensitive) */
62    bool    isType(const char type[], size_t len = 0) const;
63    /** Set the event's type to the specified string.
64        In XML, use the "type" attribute.
65    */
66    void    setType(const SkString&);
67    /** Set the event's type to the specified string.
68        In XML, use the "type" attribute.
69    */
70    void    setType(const char type[], size_t len = 0);
71
72    /** Return the event's unnamed 32bit field. Default value is 0 */
73    uint32_t getFast32() const { return f32; }
74    /** Set the event's unnamed 32bit field. In XML, use
75        the subelement <data fast32=... />
76    */
77    void    setFast32(uint32_t x) { f32 = x; }
78
79    /** Return true if the event contains the named 32bit field, and return the field
80        in value (if value is non-null). If there is no matching named field, return false
81        and ignore the value parameter.
82    */
83    bool    findS32(const char name[], int32_t* value = NULL) const { return fMeta.findS32(name, value); }
84    /** Return true if the event contains the named SkScalar field, and return the field
85        in value (if value is non-null). If there is no matching named field, return false
86        and ignore the value parameter.
87    */
88    bool    findScalar(const char name[], SkScalar* value = NULL) const { return fMeta.findScalar(name, value); }
89    /** Return true if the event contains the named SkScalar field, and return the fields
90        in value[] (if value is non-null), and return the number of SkScalars in count (if count is non-null).
91        If there is no matching named field, return false and ignore the value and count parameters.
92    */
93    const SkScalar* findScalars(const char name[], int* count, SkScalar values[] = NULL) const { return fMeta.findScalars(name, count, values); }
94    /** Return the value of the named string field, or if no matching named field exists, return null.
95    */
96    const char* findString(const char name[]) const { return fMeta.findString(name); }
97    /** Return true if the event contains the named pointer field, and return the field
98        in value (if value is non-null). If there is no matching named field, return false
99        and ignore the value parameter.
100    */
101    bool    findPtr(const char name[], void** value) const { return fMeta.findPtr(name, value); }
102    bool    findBool(const char name[], bool* value) const { return fMeta.findBool(name, value); }
103
104    /** Returns true if ethe event contains the named 32bit field, and if it equals the specified value */
105    bool    hasS32(const char name[], int32_t value) const { return fMeta.hasS32(name, value); }
106    /** Returns true if ethe event contains the named SkScalar field, and if it equals the specified value */
107    bool    hasScalar(const char name[], SkScalar value) const { return fMeta.hasScalar(name, value); }
108    /** Returns true if ethe event contains the named string field, and if it equals (using strcmp) the specified value */
109    bool    hasString(const char name[], const char value[]) const { return fMeta.hasString(name, value); }
110    /** Returns true if ethe event contains the named pointer field, and if it equals the specified value */
111    bool    hasPtr(const char name[], void* value) const { return fMeta.hasPtr(name, value); }
112    bool    hasBool(const char name[], bool value) const { return fMeta.hasBool(name, value); }
113
114    /** Add/replace the named 32bit field to the event. In XML use the subelement <data name=... s32=... /> */
115    void    setS32(const char name[], int32_t value) { fMeta.setS32(name, value); }
116    /** Add/replace the named SkScalar field to the event. In XML use the subelement <data name=... scalar=... /> */
117    void    setScalar(const char name[], SkScalar value) { fMeta.setScalar(name, value); }
118    /** Add/replace the named SkScalar[] field to the event. */
119    SkScalar* setScalars(const char name[], int count, const SkScalar values[] = NULL) { return fMeta.setScalars(name, count, values); }
120    /** Add/replace the named string field to the event. In XML use the subelement <data name=... string=... */
121    void    setString(const char name[], const SkString& value) { fMeta.setString(name, value.c_str()); }
122    /** Add/replace the named string field to the event. In XML use the subelement <data name=... string=... */
123    void    setString(const char name[], const char value[]) { fMeta.setString(name, value); }
124    /** Add/replace the named pointer field to the event. There is no XML equivalent for this call */
125    void    setPtr(const char name[], void* value) { fMeta.setPtr(name, value); }
126    void    setBool(const char name[], bool value) { fMeta.setBool(name, value); }
127
128    /** Return the underlying metadata object */
129    SkMetaData&         getMetaData() { return fMeta; }
130    /** Return the underlying metadata object */
131    const SkMetaData&   getMetaData() const { return fMeta; }
132
133    void tron() { SkDEBUGCODE(fDebugTrace = true;) }
134    void troff() { SkDEBUGCODE(fDebugTrace = false;) }
135    bool isDebugTrace() const
136    {
137#ifdef SK_DEBUG
138        return fDebugTrace;
139#else
140        return false;
141#endif
142    }
143
144    /** Call this to initialize the event from the specified XML node */
145    void    inflate(const SkDOM&, const SkDOM::Node*);
146
147    SkDEBUGCODE(void dump(const char title[] = NULL);)
148
149    /** Post the specified event to the event queue, targeting the specified eventsink, with an optional
150        delay. The event must be dynamically allocated for this. It cannot be a global or on the stack.
151        After this call, ownership is transfered to the system, so the caller must not retain
152        the event's ptr. Returns false if the event could not be posted (which means it will have been deleted).
153    */
154    static bool Post(SkEvent* evt, SkEventSinkID targetID, SkMSec delay = 0);
155    /** Post the specified event to the event queue, targeting the specified eventsink, to be delivered on/after the
156        specified millisecond time. The event must be dynamically allocated for this. It cannot be a global or on the stack.
157        After this call, ownership is transfered to the system, so the caller must not retain
158        the event's ptr. Returns false if the event could not be posted (which means it will have been deleted).
159    */
160    static bool PostTime(SkEvent* evt, SkEventSinkID targetID, SkMSec time);
161
162    /** Helper method for calling SkEvent::PostTime(this, ...), where the caller specifies a delay.
163        The real "time" will be computed automatically by sampling the clock and adding its value
164        to delay.
165    */
166    bool post(SkEventSinkID sinkID, SkMSec delay = 0)
167    {
168        return SkEvent::Post(this, sinkID, delay);
169    }
170
171    void postTime(SkEventSinkID sinkID, SkMSec time)
172    {
173        SkEvent::PostTime(this, sinkID, time);
174    }
175
176    ///////////////////////////////////////////////
177    /** Porting layer must call these functions **/
178    ///////////////////////////////////////////////
179
180    /** Global initialization function for the SkEvent system. Should be called exactly
181        once before any other event method is called, and should be called after the
182        call to SkGraphics::Init().
183    */
184    static void     Init();
185    /** Global cleanup function for the SkEvent system. Should be called exactly once after
186        all event methods have been called, and should be called before calling SkGraphics::Term().
187    */
188    static void     Term();
189
190    /** Call this to process one event from the queue. If it returns true, there are more events
191        to process.
192    */
193    static bool     ProcessEvent();
194    /** Call this whenever the requested timer has expired (requested by a call to SetQueueTimer).
195        It will post any delayed events whose time as "expired" onto the event queue.
196        It may also call SignalQueueTimer() and SignalNonEmptyQueue().
197    */
198    static void     ServiceQueueTimer();
199
200    ////////////////////////////////////////////////////
201    /** Porting layer must implement these functions **/
202    ////////////////////////////////////////////////////
203
204    /** Called whenever an SkEvent is posted to an empty queue, so that the OS
205        can be told to later call Dequeue().
206    */
207    static void SignalNonEmptyQueue();
208    /** Called whenever the delay until the next delayed event changes. If zero is
209        passed, then there are no more queued delay events.
210    */
211    static void SignalQueueTimer(SkMSec delay);
212
213#ifndef SK_USE_WXWIDGETS
214#ifdef SK_BUILD_FOR_WIN
215    static bool WndProc(HWND hWnd, UINT message, WPARAM wParam, LPARAM lParam);
216#elif defined(SK_BUILD_FOR_UNIXx)
217  static uint32_t HandleTimer(uint32_t, void*);
218  static bool WndProc(Display*, Window, XEvent&);
219#endif
220#else
221    // Don't know yet what this will be
222    //static bool CustomEvent();
223#endif
224
225private:
226    SkMetaData      fMeta;
227    mutable char*   fType;  // may be characters with low bit set to know that it is not a pointer
228    uint32_t        f32;
229    SkDEBUGCODE(bool fDebugTrace;)
230
231    // these are for our implementation of the event queue
232    SkEventSinkID   fTargetID;
233    SkMSec          fTime;
234    SkEvent*        fNextEvent; // either in the delay or normal event queue
235    void initialize(const char* type, size_t typeLen);
236
237    static bool Enqueue(SkEvent* evt);
238    static SkMSec EnqueueTime(SkEvent* evt, SkMSec time);
239    static SkEvent* Dequeue(SkEventSinkID* targetID);
240    static bool     QHasEvents();
241};
242
243#endif
244
245