components/permissions/chooser_controller.h

   1 // Copyright 2016 The Chromium Authors
   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 COMPONENTS_PERMISSIONS_CHOOSER_CONTROLLER_H_
   6 #define COMPONENTS_PERMISSIONS_CHOOSER_CONTROLLER_H_
   7
   8 #include <string>
   9 #include <vector>
  10
  11 #include "base/memory/raw_ptr.h"
  12
  13 namespace permissions {
  14
  15 // Subclass ChooserController to implement a chooser, which has some
  16 // introductory text and a list of options that users can pick one of.
  17 // Your subclass must define the set of options users can pick from;
  18 // the actions taken after users select an item or press the 'Cancel'
  19 // button or the chooser is closed.
  20 // After Select/Cancel/Close is called, this object is destroyed and
  21 // calls back into it are not allowed.
  22 class ChooserController {
  23  public:
  24   explicit ChooserController(std::u16string title);
  25
  26   ChooserController(const ChooserController&) = delete;
  27   ChooserController& operator=(const ChooserController&) = delete;
  28
  29   virtual ~ChooserController();
  30
  31   // Since the set of options can change while the UI is visible an
  32   // implementation should register a view to observe changes.
  33   class View {
  34    public:
  35     // Called after the options list is initialized for the first time.
  36     // OnOptionsInitialized should only be called once.
  37     virtual void OnOptionsInitialized() = 0;
  38
  39     // Called after GetOption(index) has been added to the options and the
  40     // newly added option is the last element in the options list. Calling
  41     // GetOption(index) from inside a call to OnOptionAdded will see the
  42     // added string since the options have already been updated.
  43     virtual void OnOptionAdded(size_t index) = 0;
  44
  45     // Called when GetOption(index) is no longer present, and all later
  46     // options have been moved earlier by 1 slot. Calling GetOption(index)
  47     // from inside a call to OnOptionRemoved will NOT see the removed string
  48     // since the options have already been updated.
  49     virtual void OnOptionRemoved(size_t index) = 0;
  50
  51     // Called when the option at |index| has been updated.
  52     virtual void OnOptionUpdated(size_t index) = 0;
  53
  54     // Called when the device adapter is turned on or off.
  55     virtual void OnAdapterEnabledChanged(bool enabled) = 0;
  56
  57     // Called when the platform level device permission is changed.
  58     // Currently only needed on macOS.
  59     virtual void OnAdapterAuthorizationChanged(bool authorized);
  60
  61     // Called when refreshing options is in progress or complete.
  62     virtual void OnRefreshStateChanged(bool refreshing) = 0;
  63
  64    protected:
  65     virtual ~View() {}
  66   };
  67
  68   // Returns the text to be displayed in the chooser title.
  69   // Note that this is only called once, and there is no way to update the title
  70   // for a given instance of ChooserController.
  71   std::u16string GetTitle() const;
  72
  73   // Returns whether the chooser needs to show an icon before the text.
  74   // For WebBluetooth, it is a signal strength icon.
  75   virtual bool ShouldShowIconBeforeText() const;
  76
  77   // Returns whether the chooser needs to show a help button.
  78   virtual bool ShouldShowHelpButton() const;
  79
  80   // Returns whether the chooser needs to show a button to re-scan for devices.
  81   virtual bool ShouldShowReScanButton() const;
  82
  83   // Returns whether the chooser allows multiple items to be selected.
  84   virtual bool AllowMultipleSelection() const;
  85
  86   // Returns whether the chooser needs to show a select-all checkbox.
  87   virtual bool ShouldShowSelectAllCheckbox() const;
  88
  89   // Returns the text to be displayed in the chooser when there are no options.
  90   virtual std::u16string GetNoOptionsText() const = 0;
  91
  92   // Returns the label for OK button.
  93   virtual std::u16string GetOkButtonLabel() const = 0;
  94
  95   // Returns the label for Cancel button.
  96   virtual std::u16string GetCancelButtonLabel() const;
  97
  98   // Returns the label for SelectAll checkbox.
  99   virtual std::u16string GetSelectAllCheckboxLabel() const;
 100
 101   // Returns the label for the throbber shown while options are initializing or
 102   // a re-scan is in progress.
 103   virtual std::pair<std::u16string, std::u16string> GetThrobberLabelAndTooltip()
 104       const = 0;
 105
 106   // Returns whether both OK and Cancel buttons are enabled.
 107   //
 108   // For chooser used in Web APIs such as WebBluetooth, WebUSB,
 109   // WebSerial, etc., the OK button is only enabled when there is at least
 110   // one device listed in the chooser, because user needs to be able to select
 111   // a device to grant access permission in these APIs.
 112   //
 113   // For permission prompt used in Bluetooth scanning Web API, the two buttons
 114   // represent Allow and Block, and should always be enabled so that user can
 115   // make their permission decision.
 116   virtual bool BothButtonsAlwaysEnabled() const;
 117
 118   // Returns whether table view should always be disabled.
 119   //
 120   // For permission prompt used in Bluetooth scanning Web API, the table is
 121   // used for displaying device names, and user doesn't need to select a device
 122   // from the table, so it should always be disabled.
 123   virtual bool TableViewAlwaysDisabled() const;
 124
 125   // The number of options users can pick from. For example, it can be
 126   // the number of USB/Bluetooth device names which are listed in the
 127   // chooser so that users can grant permission.
 128   virtual size_t NumOptions() const = 0;
 129
 130   // The signal strength level (0-4 inclusive) of the device at |index|, which
 131   // is used to retrieve the corresponding icon to be displayed before the
 132   // text. Returns -1 if no icon should be shown.
 133   virtual int GetSignalStrengthLevel(size_t index) const;
 134
 135   // The |index|th option string which is listed in the chooser.
 136   virtual std::u16string GetOption(size_t index) const = 0;
 137
 138   // Returns if the |index|th option is connected.
 139   // This function returns false by default.
 140   virtual bool IsConnected(size_t index) const;
 141
 142   // Returns if the |index|th option is paired.
 143   // This function returns false by default.
 144   virtual bool IsPaired(size_t index) const;
 145
 146   // Refresh the list of options.
 147   virtual void RefreshOptions();
 148
 149   // These three functions are called just before this object is destroyed:
 150
 151   // Called when the user selects elements from the dialog. |indices| contains
 152   // the indices of the selected elements.
 153   virtual void Select(const std::vector<size_t>& indices) = 0;
 154
 155   // Called when the user presses the 'Cancel' button in the dialog.
 156   virtual void Cancel() = 0;
 157
 158   // Called when the user clicks outside the dialog or the dialog otherwise
 159   // closes without the user taking an explicit action.
 160   virtual void Close() = 0;
 161
 162   // Open help center URL.
 163   virtual void OpenHelpCenterUrl() const = 0;
 164
 165   // Provide help information when the adapter is off.
 166   virtual void OpenAdapterOffHelpUrl() const;
 167
 168   // Navigate user to preferences in order to acquire Bluetooth permission.
 169   virtual void OpenPermissionPreferences() const;
 170
 171   // Only one view may be registered at a time.
 172   void set_view(View* view) { view_ = view; }
 173   View* view() const { return view_; }
 174
 175  protected:
 176   void set_title_for_testing(const std::u16string& title) { title_ = title; }
 177
 178  private:
 179   std::u16string title_;
 180   raw_ptr<View, DanglingUntriaged> view_ = nullptr;
 181 };
 182
 183 }  // namespace permissions
 184
 185 #endif  // COMPONENTS_PERMISSIONS_CHOOSER_CONTROLLER_H_