1/*
2 * Copyright 2012 Google Inc.
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 SkAnnotation_DEFINED
9#define SkAnnotation_DEFINED
10
11#include "SkRefCnt.h"
12#include "SkString.h"
13
14class SkData;
15class SkReadBuffer;
16class SkWriteBuffer;
17class SkStream;
18class SkWStream;
19struct SkPoint;
20
21/**
22 *  Experimental class for annotating draws. Do not use directly yet.
23 *  Use helper functions at the bottom of this file for now.
24 */
25class SkAnnotation : public SkRefCnt {
26public:
27    virtual ~SkAnnotation();
28
29    static SkAnnotation* Create(const char key[], SkData* value) {
30        return SkNEW_ARGS(SkAnnotation, (key, value));
31    }
32
33    static SkAnnotation* Create(SkReadBuffer& buffer) {
34        return SkNEW_ARGS(SkAnnotation, (buffer));
35    }
36
37    /**
38     *  Return the data for the specified key, or NULL.
39     */
40    SkData* find(const char key[]) const;
41
42    void writeToBuffer(SkWriteBuffer&) const;
43
44private:
45    SkAnnotation(const char key[], SkData* value);
46    SkAnnotation(SkReadBuffer&);
47
48    SkString    fKey;
49    SkData*     fData;
50
51    typedef SkRefCnt INHERITED;
52};
53
54/**
55 *  Experimental collection of predefined Keys into the Annotation dictionary
56 */
57class SkAnnotationKeys {
58public:
59    /**
60     *  Returns the canonical key whose payload is a URL
61     */
62    static const char* URL_Key();
63
64    /**
65     *  Returns the canonical key whose payload is the name of a destination to
66     *  be defined.
67     */
68    static const char* Define_Named_Dest_Key();
69
70    /**
71     *  Returns the canonical key whose payload is the name of a destination to
72     *  be linked to.
73     */
74    static const char* Link_Named_Dest_Key();
75};
76
77///////////////////////////////////////////////////////////////////////////////
78//
79// Experimental helper functions to use Annotations
80//
81
82struct SkRect;
83class SkCanvas;
84
85/**
86 *  Experimental!
87 *
88 *  Annotate the canvas by associating the specified URL with the
89 *  specified rectangle (in local coordinates, just like drawRect). If the
90 *  backend of this canvas does not support annotations, this call is
91 *  safely ignored.
92 *
93 *  The caller is responsible for managing its ownership of the SkData.
94 */
95SK_API void SkAnnotateRectWithURL(SkCanvas*, const SkRect&, SkData*);
96
97/**
98 *  Experimental!
99 *
100 *  Annotate the canvas by associating a name with the specified point.
101 *
102 *  If the backend of this canvas does not support annotations, this call is
103 *  safely ignored.
104 *
105 *  The caller is responsible for managing its ownership of the SkData.
106 */
107SK_API void SkAnnotateNamedDestination(SkCanvas*, const SkPoint&, SkData*);
108
109/**
110 *  Experimental!
111 *
112 *  Annotate the canvas by making the specified rectangle link to a named
113 *  destination.
114 *
115 *  If the backend of this canvas does not support annotations, this call is
116 *  safely ignored.
117 *
118 *  The caller is responsible for managing its ownership of the SkData.
119 */
120SK_API void SkAnnotateLinkToDestination(SkCanvas*, const SkRect&, SkData*);
121
122
123#endif
124