chooser_controller.h 7.1 KB

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