tutorial.h 6.0 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154
  1. // Copyright 2021 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_USER_EDUCATION_COMMON_TUTORIAL_H_
  5. #define COMPONENTS_USER_EDUCATION_COMMON_TUTORIAL_H_
  6. #include "components/user_education/common/help_bubble_factory.h"
  7. #include "components/user_education/common/help_bubble_params.h"
  8. #include "components/user_education/common/tutorial_description.h"
  9. #include "third_party/abseil-cpp/absl/types/optional.h"
  10. #include "ui/base/interaction/element_identifier.h"
  11. #include "ui/base/interaction/element_tracker.h"
  12. #include "ui/base/interaction/interaction_sequence.h"
  13. namespace user_education {
  14. class TutorialService;
  15. // Tutorials are a user initiated IPH which spans 1 or more Interactions.
  16. // It utilizes the InteractionSequence Framework to provide a tracked list of
  17. // interactions with tracked elements.
  18. //
  19. // Each tutorial consists of a list of InteractionSequence steps which, in the
  20. // default case, create a HelpBubble which is implementation specific to
  21. // the platform the tutorial is written for. It is possible to create custom
  22. // InteractionSequenceSteps when using the traditional constructor and not
  23. // using the TutorialStepBuilder.
  24. //
  25. // Because of implementation details in InteractionSequence, a tutorial can only
  26. // be run once, see documentation for InteractionSequence.
  27. //
  28. // Basic tutorials use a TutorialDescription struct and the
  29. // Builder::BuildFromDescription method to construct the tutorial.
  30. //
  31. // the end user of a Tutorial would define a tutorial description in a
  32. // TutorialRegistry, for the platform the tutorial is implemented on. (see
  33. // BrowserTutorialServiceFactory)
  34. //
  35. // TODO: Provide an in-depth readme.md for tutorials
  36. //
  37. class Tutorial {
  38. public:
  39. ~Tutorial();
  40. // Step Builder provides an interface for constructing an
  41. // InteractionSequence::Step from a TutorialDescription::Step.
  42. // TutorialDescription is used as the basis for the StepBuilder since all
  43. // parameters of the Description will be needed to create the bubble or build
  44. // the interaction sequence step. In order to use the The StepBuilder should
  45. // only be used by Tutorial::Builder to construct the steps in the tutorial.
  46. class StepBuilder {
  47. public:
  48. StepBuilder();
  49. explicit StepBuilder(const TutorialDescription::Step& step);
  50. StepBuilder(const StepBuilder&) = delete;
  51. StepBuilder& operator=(const StepBuilder&) = delete;
  52. ~StepBuilder();
  53. // Constructs the InteractionSequenceStepDirectly from the
  54. // TutorialDescriptionStep. This method is used by
  55. // Tutorial::Builder::BuildFromDescription to create tutorials.
  56. static std::unique_ptr<ui::InteractionSequence::Step>
  57. BuildFromDescriptionStep(const TutorialDescription::Step& step,
  58. absl::optional<std::pair<int, int>> progress,
  59. bool is_last_step,
  60. bool can_be_restarted,
  61. TutorialService* tutorial_service);
  62. StepBuilder& SetAnchorElementID(ui::ElementIdentifier anchor_element_id);
  63. StepBuilder& SetAnchorElementName(std::string anchor_element_name);
  64. StepBuilder& SetTitleTextID(int title_text_id);
  65. StepBuilder& SetBodyTextID(int body_text_id);
  66. // Sets the step type; `event_type_` should be set only for custom events.
  67. StepBuilder& SetStepType(
  68. ui::InteractionSequence::StepType step_type_,
  69. ui::CustomElementEventType event_type_ = ui::CustomElementEventType());
  70. StepBuilder& SetArrow(HelpBubbleArrow arrow_);
  71. StepBuilder& SetProgress(absl::optional<std::pair<int, int>> progress_);
  72. StepBuilder& SetIsLastStep(bool is_last_step_);
  73. StepBuilder& SetMustRemainVisible(bool must_remain_visible_);
  74. StepBuilder& SetTransitionOnlyOnEvent(bool transition_only_on_event_);
  75. StepBuilder& SetNameElementsCallback(
  76. TutorialDescription::NameElementsCallback name_elements_callback_);
  77. StepBuilder& SetCanBeRestarted(bool can_be_restarted_);
  78. std::unique_ptr<ui::InteractionSequence::Step> Build(
  79. TutorialService* tutorial_service);
  80. private:
  81. absl::optional<std::pair<int, int>> progress;
  82. bool is_last_step = false;
  83. bool can_be_restarted = false;
  84. ui::InteractionSequence::StepStartCallback BuildStartCallback(
  85. TutorialService* tutorial_service);
  86. ui::InteractionSequence::StepStartCallback BuildMaybeShowBubbleCallback(
  87. TutorialService* tutorial_service);
  88. ui::InteractionSequence::StepEndCallback BuildHideBubbleCallback(
  89. TutorialService* tutorial_service);
  90. TutorialDescription::Step step_;
  91. };
  92. class Builder {
  93. public:
  94. Builder();
  95. ~Builder();
  96. static std::unique_ptr<Tutorial> BuildFromDescription(
  97. const TutorialDescription& description,
  98. TutorialService* tutorial_service,
  99. ui::ElementContext context);
  100. Builder(const Builder& other) = delete;
  101. void operator=(Builder& other) = delete;
  102. Builder& AddStep(std::unique_ptr<ui::InteractionSequence::Step> step);
  103. Builder& SetContext(ui::ElementContext element_context);
  104. Builder& SetAbortedCallback(
  105. ui::InteractionSequence::AbortedCallback callback);
  106. Builder& SetCompletedCallback(
  107. ui::InteractionSequence::CompletedCallback callback);
  108. std::unique_ptr<Tutorial> Build();
  109. private:
  110. std::unique_ptr<ui::InteractionSequence::Builder> builder_;
  111. };
  112. // Starts the Tutorial. has the same constraints as
  113. // InteractionSequence::Start.
  114. void Start();
  115. // Cancels the Tutorial. Calls the destructor of the InteractionSequence,
  116. // calling the abort callback if necessary.
  117. void Abort();
  118. private:
  119. // Tutorial Constructor that takes an InteractionSequence. Should only be
  120. // used in cases where custom step logic must be called
  121. explicit Tutorial(
  122. std::unique_ptr<ui::InteractionSequence> interaction_sequence);
  123. // The Interaction Sequence which controls the tutorial bubbles opening and
  124. // closing
  125. std::unique_ptr<ui::InteractionSequence> interaction_sequence_;
  126. };
  127. } // namespace user_education
  128. #endif // COMPONENTS_USER_EDUCATION_COMMON_TUTORIAL_H_