1
    2
    3
    4
    5
    6
    7
    8
    9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   23
   24
   25
   26
   27
   28
   29
   30
   31
   32
   33
   34
   35
   36
   37
   38
   39
   40
   41
   42
   43
   44
   45
   46
   47
   48
   49
   50
   51
   52
   53
   54
   55
   56
   57
   58
   59
   60
   61
   62
   63
   64
   65
   66
   67
   68
   69
   70
   71
   72
   73
   74
   75
   76
   77
   78
   79
   80
   81
   82
   83
   84
   85
   86
   87
   88
   89
   90
   91
   92
   93
   94
   95
   96
   97
   98
   99
  100
  101
  102
  103
  104
  105
  106
  107
  108
  109
  110
  111
  112
  113
  114
  115
  116
  117
  118
  119
  120
  121
  122


ash / public / cpp / app_list / app_list_notifier.h [blame]

// Copyright 2020 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

#ifndef ASH_PUBLIC_CPP_APP_LIST_APP_LIST_NOTIFIER_H_
#define ASH_PUBLIC_CPP_APP_LIST_APP_LIST_NOTIFIER_H_

#include <stdint.h>

#include <optional>
#include <string>
#include <vector>

#include "ash/public/cpp/app_list/app_list_types.h"
#include "ash/public/cpp/ash_public_export.h"
#include "base/observer_list_types.h"

namespace ash {

// A notifier interface implemented in Chrome and called from Ash, which allows
// objects in Chrome to observe state changes in Ash. Its main use is to signal
// events related to metrics and logging: search result impressions, abandons,
// ignores, and launches. See method comments for definitions of these.
//
// Implementing notifiers guarantee that calls to each observer come in pairs.
// Every OnImpression call will be followed by a call to one of OnAbandon,
// OnIgnore, or OnLaunch, and vice versa. Each pair of calls will be passed
// the same results vector.
class ASH_PUBLIC_EXPORT AppListNotifier {
 public:
  using Location = ash::SearchResultDisplayType;

  struct Result {
    Result(const std::string& id,
           ash::SearchResultType type,
           const std::optional<ash::ContinueFileSuggestionType>&
               continue_file_type)
        : id(id), type(type), continue_file_type(continue_file_type) {}

    std::string id;
    ash::SearchResultType type = ash::SEARCH_RESULT_TYPE_BOUNDARY;
    std::optional<ash::ContinueFileSuggestionType> continue_file_type;
  };

  class Observer : public base::CheckedObserver {
   public:
    // Called when the search query is first updated after activating the search
    // box or the app list view state transitions to kFullscreenSearch.
    virtual void OnSearchSessionStarted() {}

    // Called when an active search session ends when exiting bubble launcher
    // search or the app list view state transitions out of kFullscreenSearch.
    virtual void OnSearchSessionEnded(const std::u16string& query) {}

    // Called when |results| have been displayed for the length of the
    // impression timer.
    virtual void OnSeen(Location location,
                        const std::vector<Result>& results,
                        const std::u16string& query) {}

    // Called when |results| have been displayed for the length of the
    // impression timer, launched, or ignored.
    virtual void OnImpression(Location location,
                              const std::vector<Result>& results,
                              const std::u16string& query) {}

    // Called when an impression occurred for |results|, and the user then moved
    // to a different UI view. For example, by closing the launcher or
    // changing the search query.
    virtual void OnAbandon(Location location,
                           const std::vector<Result>& results,
                           const std::u16string& query) {}

    // Called when the |location| UI view displayed |results|, but the user
    // launched a result in a different UI view. This can only happen when
    // |location| is kContinue or kRecentApps.
    virtual void OnIgnore(Location location,
                          const std::vector<Result>& results,
                          const std::u16string& query) {}

    // Called when the |launched| result is launched, and provides all |shown|
    // results at |location| (including |launched|).
    virtual void OnLaunch(Location location,
                          const Result& launched,
                          const std::vector<Result>& shown,
                          const std::u16string& query) {}

    // Called immediately when the search |query| changes.
    virtual void OnQueryChanged(const std::u16string& query) {}
  };

  virtual ~AppListNotifier() = default;

  virtual void AddObserver(Observer* observer) = 0;
  virtual void RemoveObserver(Observer* observer) = 0;

  // Called when visibility of a container within the launcher continue section
  // (continue task suggestions, or recent apps) changes.
  virtual void NotifyContinueSectionVisibilityChanged(Location location,
                                                      bool visible) = 0;

  // Called to indicate a search |result| has been launched at the UI surface
  // |location|.
  virtual void NotifyLaunched(Location location, const Result& result) = 0;

  // Called to indicate the results displayed in the |location| UI surface have
  // changed. |results| should contain a complete list of what is now shown.
  virtual void NotifyResultsUpdated(Location location,
                                    const std::vector<Result>& results) = 0;

  // Called to indicate the user has updated the search query to |query|.
  virtual void NotifySearchQueryChanged(const std::u16string& query) = 0;

  // Fires a timer to report search result impression for the provided
  // location, if an impression update was scheduled. Returns whether a timer
  // was fired.
  virtual bool FireImpressionTimerForTesting(Location location) = 0;
};

}  // namespace ash

#endif  // ASH_PUBLIC_CPP_APP_LIST_APP_LIST_NOTIFIER_H_