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