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