1// Copyright (c) 2011 The Chromium Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5#ifndef CHROME_BROWSER_AUTOCOMPLETE_AUTOCOMPLETE_MATCH_H_
6#define CHROME_BROWSER_AUTOCOMPLETE_AUTOCOMPLETE_MATCH_H_
7#pragma once
8
9#include <vector>
10#include <string>
11
12#include "content/common/page_transition_types.h"
13#include "googleurl/src/gurl.h"
14
15class AutocompleteProvider;
16class PageTransition;
17class TemplateURL;
18
19// AutocompleteMatch ----------------------------------------------------------
20
21// A single result line with classified spans.  The autocomplete popup displays
22// the 'contents' and the 'description' (the description is optional) in the
23// autocomplete dropdown, and fills in 'fill_into_edit' into the textbox when
24// that line is selected.  fill_into_edit may be the same as 'description' for
25// things like URLs, but may be different for searches or other providers.  For
26// example, a search result may say "Search for asdf" as the description, but
27// "asdf" should appear in the box.
28struct AutocompleteMatch {
29  // Autocomplete matches contain strings that are classified according to a
30  // separate vector of styles.  This vector associates flags with particular
31  // string segments, and must be in sorted order.  All text must be associated
32  // with some kind of classification.  Even if a match has no distinct
33  // segments, its vector should contain an entry at offset 0 with no flags.
34  //
35  // Example: The user typed "goog"
36  //   http://www.google.com/        Google
37  //   ^          ^   ^              ^   ^
38  //   0,         |   15,            |   4,
39  //              11,match           0,match
40  //
41  // This structure holds the classification information for each span.
42  struct ACMatchClassification {
43    // The values in here are not mutually exclusive -- use them like a
44    // bitfield.  This also means we use "int" instead of this enum type when
45    // passing the values around, so the compiler doesn't complain.
46    enum Style {
47      NONE  = 0,
48      URL   = 1 << 0,  // A URL
49      MATCH = 1 << 1,  // A match for the user's search term
50      DIM   = 1 << 2,  // "Helper text"
51    };
52
53    ACMatchClassification(size_t offset, int style)
54        : offset(offset),
55          style(style) {
56    }
57
58    // Offset within the string that this classification starts
59    size_t offset;
60
61    int style;
62  };
63
64  typedef std::vector<ACMatchClassification> ACMatchClassifications;
65
66  // The type of this match.
67  enum Type {
68    URL_WHAT_YOU_TYPED = 0,  // The input as a URL.
69    HISTORY_URL,             // A past page whose URL contains the input.
70    HISTORY_TITLE,           // A past page whose title contains the input.
71    HISTORY_BODY,            // A past page whose body contains the input.
72    HISTORY_KEYWORD,         // A past page whose keyword contains the input.
73    NAVSUGGEST,              // A suggested URL.
74    SEARCH_WHAT_YOU_TYPED,   // The input as a search query (with the default
75                             // engine).
76    SEARCH_HISTORY,          // A past search (with the default engine)
77                             // containing the input.
78    SEARCH_SUGGEST,          // A suggested search (with the default engine).
79    SEARCH_OTHER_ENGINE,     // A search with a non-default engine.
80    EXTENSION_APP,           // An Extension App with a title/url that contains
81                             // the input.
82    NUM_TYPES,
83  };
84
85  AutocompleteMatch();
86  AutocompleteMatch(AutocompleteProvider* provider,
87                    int relevance,
88                    bool deletable,
89                    Type type);
90  ~AutocompleteMatch();
91
92  // Converts |type| to a string representation.  Used in logging.
93  static std::string TypeToString(Type type);
94
95  // Converts |type| to a resource identifier for the appropriate icon for this
96  // type.
97  static int TypeToIcon(Type type);
98
99  // Comparison function for determining when one match is better than another.
100  static bool MoreRelevant(const AutocompleteMatch& elem1,
101                           const AutocompleteMatch& elem2);
102
103  // Comparison functions for removing matches with duplicate destinations.
104  static bool DestinationSortFunc(const AutocompleteMatch& elem1,
105                                  const AutocompleteMatch& elem2);
106  static bool DestinationsEqual(const AutocompleteMatch& elem1,
107                                const AutocompleteMatch& elem2);
108
109  // Helper functions for classes creating matches:
110  // Fills in the classifications for |text|, using |style| as the base style
111  // and marking the first instance of |find_text| as a match.  (This match
112  // will also not be dimmed, if |style| has DIM set.)
113  static void ClassifyMatchInString(const string16& find_text,
114                                    const string16& text,
115                                    int style,
116                                    ACMatchClassifications* classifications);
117
118  // Similar to ClassifyMatchInString(), but for cases where the range to mark
119  // as matching is already known (avoids calling find()).  This can be helpful
120  // when find() would be misleading (e.g. you want to mark the second match in
121  // a string instead of the first).
122  static void ClassifyLocationInString(size_t match_location,
123                                       size_t match_length,
124                                       size_t overall_length,
125                                       int style,
126                                       ACMatchClassifications* classifications);
127
128  // The provider of this match, used to remember which provider the user had
129  // selected when the input changes. This may be NULL, in which case there is
130  // no provider (or memory of the user's selection).
131  AutocompleteProvider* provider;
132
133  // The relevance of this match. See table in autocomplete.h for scores
134  // returned by various providers. This is used to rank matches among all
135  // responding providers, so different providers must be carefully tuned to
136  // supply matches with appropriate relevance.
137  //
138  // TODO(pkasting): http://b/1111299 This should be calculated algorithmically,
139  // rather than being a fairly fixed value defined by the table above.
140  int relevance;
141
142  // True if the user should be able to delete this match.
143  bool deletable;
144
145  // This string is loaded into the location bar when the item is selected
146  // by pressing the arrow keys. This may be different than a URL, for example,
147  // for search suggestions, this would just be the search terms.
148  string16 fill_into_edit;
149
150  // The position within fill_into_edit from which we'll display the inline
151  // autocomplete string.  This will be string16::npos if this match should
152  // not be inline autocompleted.
153  size_t inline_autocomplete_offset;
154
155  // The URL to actually load when the autocomplete item is selected. This URL
156  // should be canonical so we can compare URLs with strcmp to avoid dupes.
157  // It may be empty if there is no possible navigation.
158  GURL destination_url;
159
160  // The main text displayed in the address bar dropdown.
161  string16 contents;
162  ACMatchClassifications contents_class;
163
164  // Additional helper text for each entry, such as a title or description.
165  string16 description;
166  ACMatchClassifications description_class;
167
168  // The transition type to use when the user opens this match.  By default
169  // this is TYPED.  Providers whose matches do not look like URLs should set
170  // it to GENERATED.
171  PageTransition::Type transition;
172
173  // True when this match is the "what you typed" match from the history
174  // system.
175  bool is_history_what_you_typed_match;
176
177  // Type of this match.
178  Type type;
179
180  // If this match corresponds to a keyword, this is the TemplateURL the
181  // keyword was obtained from.
182  const TemplateURL* template_url;
183
184  // True if the user has starred the destination URL.
185  bool starred;
186
187  // True if this match is from a previous result.
188  bool from_previous;
189
190#ifndef NDEBUG
191  // Does a data integrity check on this match.
192  void Validate() const;
193
194  // Checks one text/classifications pair for valid values.
195  void ValidateClassifications(
196      const string16& text,
197      const ACMatchClassifications& classifications) const;
198#endif
199};
200
201typedef AutocompleteMatch::ACMatchClassification ACMatchClassification;
202typedef std::vector<ACMatchClassification> ACMatchClassifications;
203
204#endif  // CHROME_BROWSER_AUTOCOMPLETE_AUTOCOMPLETE_MATCH_H_
205