Wizard.cs 24 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713
  1. using System;
  2. using System.Collections.Generic;
  3. using System.Linq;
  4. using NStack;
  5. using Terminal.Gui.Resources;
  6. namespace Terminal.Gui {
  7. /// <summary>
  8. /// Provides a step-based "wizard" UI. The Wizard supports multiple steps. Each step (<see cref="WizardStep"/>) can host
  9. /// arbitrary <see cref="View"/>s, much like a <see cref="Dialog"/>. Each step also has a pane for help text. Along the
  10. /// bottom of the Wizard view are customizable buttons enabling the user to navigate forward and backward through the Wizard.
  11. /// </summary>
  12. /// <remarks>
  13. /// </remarks>
  14. public class Wizard : Dialog {
  15. /// <summary>
  16. /// One step for the Wizard. The <see cref="WizardStep"/> view hosts two sub-views: 1) add <see cref="View"/>s to <see cref="WizardStep.Controls"/>,
  17. /// 2) use <see cref="WizardStep.HelpText"/> to set the contents of the <see cref="TextView"/> that shows on the
  18. /// right side. Use <see cref="WizardStep.showControls"/> and <see cref="WizardStep.showHelp"/> to
  19. /// control wether the control or help pane are shown.
  20. /// </summary>
  21. /// <remarks>
  22. /// If <see cref="Button"/>s are added, do not set <see cref="Button.IsDefault"/> to true as this will conflict
  23. /// with the Next button of the Wizard.
  24. ///
  25. /// Subscribe to the <see cref="View.VisibleChanged"/> event to be notified when the step is active; see also: <see cref="Wizard.StepChanged"/>.
  26. ///
  27. /// To enable or disable a step from being shown to the user, set <see cref="View.Enabled"/>.
  28. ///
  29. /// </remarks>
  30. public class WizardStep : View {
  31. /// <summary>
  32. /// The title of the <see cref="WizardStep"/>.
  33. /// </summary>
  34. public ustring Title {
  35. get => title;
  36. set {
  37. if (!OnTitleChanging (value)) {
  38. title = value;
  39. OnTitleChanged (title);
  40. }
  41. SetNeedsDisplay ();
  42. }
  43. }
  44. private ustring title;
  45. /// <summary>
  46. /// An <see cref="EventArgs"/> which allows passing a cancelable new <see cref="Title"/> value event.
  47. /// </summary>
  48. public class TitleEventArgs : EventArgs {
  49. /// <summary>
  50. /// The new Window Title.
  51. /// </summary>
  52. public ustring NewTitle { get; set; }
  53. /// <summary>
  54. /// Flag which allows cancelling changing to the new TItle value.
  55. /// </summary>
  56. public bool Cancel { get; set; }
  57. /// <summary>
  58. /// Initializes a new instance of <see cref="TitleEventArgs"/>
  59. /// </summary>
  60. /// <param name="newTitle">The new <see cref="Window.Title"/> to be replaced.</param>
  61. public TitleEventArgs (ustring newTitle)
  62. {
  63. NewTitle = newTitle;
  64. }
  65. }
  66. /// <summary>
  67. /// Called before the <see cref="Window.Title"/> changes. Invokes the <see cref="TitleChanging"/> event, which can be cancelled.
  68. /// </summary>
  69. /// <returns>`true` if an event handler cancelled the Title change.</returns>
  70. public virtual bool OnTitleChanging (ustring newTitle)
  71. {
  72. var args = new TitleEventArgs (newTitle);
  73. TitleChanging?.Invoke (args);
  74. return args.Cancel;
  75. }
  76. /// <summary>
  77. /// Event fired when the <see cref="Window.Title"/> is changing. Set <see cref="TitleEventArgs.Cancel"/> to
  78. /// `true` to cancel the Title change.
  79. /// </summary>
  80. public event Action<TitleEventArgs> TitleChanging;
  81. /// <summary>
  82. /// Called when the <see cref="Window.Title"/> has been changed. Invokes the <see cref="TitleChanged"/> event.
  83. /// </summary>
  84. public virtual void OnTitleChanged (ustring newTitle)
  85. {
  86. var args = new TitleEventArgs (title);
  87. TitleChanged?.Invoke (args);
  88. }
  89. /// <summary>
  90. /// Event fired after the <see cref="Window.Title"/> has been changed.
  91. /// </summary>
  92. public event Action<TitleEventArgs> TitleChanged;
  93. // The controlPane is a separate view, so when devs add controls to the Step and help is visible, Y = Pos.AnchorEnd()
  94. // will work as expected.
  95. private View controlPane = new FrameView ();
  96. /// <summary>
  97. /// THe pane that holds the controls for the <see cref="WizardStep"/>. Use <see cref="WizardStep.Controls"/> `Add(View`) to add
  98. /// controls. Note that the Controls view is sized to take 70% of the Wizard's width and the <see cref="WizardStep.HelpText"/>
  99. /// takes the other 30%. This can be adjusted by setting `Width` from `Dim.Percent(70)` to
  100. /// another value. If <see cref="WizardStep.ShowHelp"/> is set to `false` the control pane will fill the entire
  101. /// Wizard.
  102. /// </summary>
  103. public View Controls { get => controlPane; }
  104. /// <summary>
  105. /// Sets or gets help text for the <see cref="WizardStep"/>.If <see cref="WizardStep.ShowHelp"/> is set to
  106. /// `false` the control pane will fill the entire wizard.
  107. /// </summary>
  108. /// <remarks>The help text is displayed using a read-only <see cref="TextView"/>.</remarks>
  109. public ustring HelpText { get => helpTextView.Text; set => helpTextView.Text = value; }
  110. private TextView helpTextView = new TextView ();
  111. /// <summary>
  112. /// Sets or gets the text for the back button. The back button will only be visible on
  113. /// steps after the first step.
  114. /// </summary>
  115. /// <remarks>The default text is "Back"</remarks>
  116. public ustring BackButtonText { get; set; } = ustring.Empty;
  117. // TODO: Update button text of Wizard button when step's button text is changed if step is current - this will require step to slueth it's parent
  118. /// <summary>
  119. /// Sets or gets the text for the next/finish button.
  120. /// </summary>
  121. /// <remarks>The default text is "Next..." if the Pane is not the last pane. Otherwise it is "Finish"</remarks>
  122. public ustring NextButtonText { get; set; } = ustring.Empty;
  123. // TODO: Update button text of Wizard button when step's button text is changed if step is current - this will require step to slueth it's parent
  124. /// <summary>
  125. /// Initializes a new instance of the <see cref="Wizard"/> class using <see cref="LayoutStyle.Computed"/> positioning.
  126. /// </summary>
  127. /// <param name="title">Title for the Step. Will be appended to the containing Wizard's title as
  128. /// "Wizard Title - Wizard Step Title" when this step is active.</param>
  129. /// <remarks>
  130. /// </remarks>
  131. public WizardStep (ustring title)
  132. {
  133. this.Title = title; // this.Title holds just the "Wizard Title"; base.Title holds "Wizard Title - Step Title"
  134. this.ColorScheme = Colors.Dialog;
  135. Y = 0;
  136. Height = Dim.Fill (1); // for button frame
  137. Width = Dim.Fill ();
  138. Controls.ColorScheme = Colors.Dialog;
  139. Controls.Border.BorderStyle = BorderStyle.None;
  140. Controls.Border.Padding = new Thickness (0);
  141. Controls.Border.BorderThickness = new Thickness (0);
  142. this.Add (Controls);
  143. helpTextView.ColorScheme = Colors.Menu;
  144. helpTextView.Y = 0;
  145. helpTextView.ReadOnly = true;
  146. helpTextView.WordWrap = true;
  147. this.Add (helpTextView);
  148. ShowHide ();
  149. var scrollBar = new ScrollBarView (helpTextView, true);
  150. scrollBar.ChangedPosition += () => {
  151. helpTextView.TopRow = scrollBar.Position;
  152. if (helpTextView.TopRow != scrollBar.Position) {
  153. scrollBar.Position = helpTextView.TopRow;
  154. }
  155. helpTextView.SetNeedsDisplay ();
  156. };
  157. scrollBar.OtherScrollBarView.ChangedPosition += () => {
  158. helpTextView.LeftColumn = scrollBar.OtherScrollBarView.Position;
  159. if (helpTextView.LeftColumn != scrollBar.OtherScrollBarView.Position) {
  160. scrollBar.OtherScrollBarView.Position = helpTextView.LeftColumn;
  161. }
  162. helpTextView.SetNeedsDisplay ();
  163. };
  164. scrollBar.VisibleChanged += () => {
  165. if (scrollBar.Visible && helpTextView.RightOffset == 0) {
  166. helpTextView.RightOffset = 1;
  167. } else if (!scrollBar.Visible && helpTextView.RightOffset == 1) {
  168. helpTextView.RightOffset = 0;
  169. }
  170. };
  171. scrollBar.OtherScrollBarView.VisibleChanged += () => {
  172. if (scrollBar.OtherScrollBarView.Visible && helpTextView.BottomOffset == 0) {
  173. helpTextView.BottomOffset = 1;
  174. } else if (!scrollBar.OtherScrollBarView.Visible && helpTextView.BottomOffset == 1) {
  175. helpTextView.BottomOffset = 0;
  176. }
  177. };
  178. helpTextView.DrawContent += (e) => {
  179. scrollBar.Size = helpTextView.Lines;
  180. scrollBar.Position = helpTextView.TopRow;
  181. if (scrollBar.OtherScrollBarView != null) {
  182. scrollBar.OtherScrollBarView.Size = helpTextView.Maxlength;
  183. scrollBar.OtherScrollBarView.Position = helpTextView.LeftColumn;
  184. }
  185. scrollBar.LayoutSubviews ();
  186. scrollBar.Refresh ();
  187. };
  188. this.Add (scrollBar);
  189. }
  190. //public override void OnEnabledChanged()
  191. //{
  192. // if (Enabled) { }
  193. // base.OnEnabledChanged ();
  194. //}
  195. /// <summary>
  196. /// If true (the default) the help will be visible. If false, the help will not be shown and the control pane will
  197. /// fill the wizard step.
  198. /// </summary>
  199. public bool ShowHelp {
  200. get => showHelp;
  201. set {
  202. showHelp = value;
  203. ShowHide ();
  204. }
  205. }
  206. private bool showHelp = true;
  207. /// <summary>
  208. /// If true (the default) the <see cref="Controls"/> View will be visible. If false, the controls will not be shown and the help will
  209. /// fill the wizard step.
  210. /// </summary>
  211. public bool ShowControls {
  212. get => showControls;
  213. set {
  214. showControls = value;
  215. ShowHide ();
  216. }
  217. }
  218. private bool showControls = true;
  219. /// <summary>
  220. /// Does the work to show and hide the controls, help, and buttons as appropriate
  221. /// </summary>
  222. private void ShowHide ()
  223. {
  224. Controls.Height = Dim.Fill (1);
  225. helpTextView.Height = Dim.Fill (1);
  226. helpTextView.Width = Dim.Fill ();
  227. if (showControls) {
  228. if (showHelp) {
  229. Controls.Width = Dim.Percent (70);
  230. helpTextView.X = Pos.Right (Controls);
  231. helpTextView.Width = Dim.Fill ();
  232. } else {
  233. Controls.Width = Dim.Percent (100);
  234. }
  235. } else {
  236. if (showHelp) {
  237. helpTextView.X = 0;
  238. } else {
  239. // Error - no pane shown
  240. }
  241. }
  242. Controls.Visible = showControls;
  243. helpTextView.Visible = showHelp;
  244. }
  245. } // WizardStep
  246. /// <summary>
  247. /// Initializes a new instance of the <see cref="Wizard"/> class using <see cref="LayoutStyle.Computed"/> positioning.
  248. /// </summary>
  249. /// <remarks>
  250. /// The Wizard will be vertically and horizontally centered in the container.
  251. /// After initialization use <c>X</c>, <c>Y</c>, <c>Width</c>, and <c>Height</c> change size and position.
  252. /// </remarks>
  253. public Wizard () : this (ustring.Empty)
  254. {
  255. }
  256. /// <summary>
  257. /// Initializes a new instance of the <see cref="Wizard"/> class using <see cref="LayoutStyle.Computed"/> positioning.
  258. /// </summary>
  259. /// <param name="title">Title for the Wizard.</param>
  260. /// <remarks>
  261. /// The Wizard will be vertically and horizontally centered in the container.
  262. /// After initialization use <c>X</c>, <c>Y</c>, <c>Width</c>, and <c>Height</c> change size and position.
  263. /// </remarks>
  264. public Wizard (ustring title) : base (title)
  265. {
  266. wizardTitle = title;
  267. // Using Justify causes the Back and Next buttons to be hard justified against
  268. // the left and right edge
  269. ButtonAlignment = ButtonAlignments.Justify;
  270. this.Border.BorderStyle = BorderStyle.Double;
  271. // Add a horiz separator
  272. var separator = new LineView (Graphs.Orientation.Horizontal) {
  273. Y = Pos.AnchorEnd (2)
  274. };
  275. Add (separator);
  276. // BUGBUG: Space is to work around https://github.com/migueldeicaza/gui.cs/issues/1812
  277. backBtn = new Button (Strings.wzBack) { AutoSize = true };
  278. AddButton (backBtn);
  279. nextfinishBtn = new Button (Strings.wzFinish) { AutoSize = true };
  280. nextfinishBtn.IsDefault = true;
  281. AddButton (nextfinishBtn);
  282. backBtn.Clicked += BackBtn_Clicked;
  283. nextfinishBtn.Clicked += NextfinishBtn_Clicked;
  284. Loaded += Wizard_Loaded;
  285. Closing += Wizard_Closing;
  286. }
  287. private bool finishedPressed = false;
  288. private void Wizard_Closing (ToplevelClosingEventArgs obj)
  289. {
  290. if (!finishedPressed) {
  291. var args = new WizardButtonEventArgs ();
  292. Cancelled?.Invoke (args);
  293. }
  294. }
  295. private void Wizard_Loaded ()
  296. {
  297. foreach (var step in steps) {
  298. step.Y = 0;
  299. }
  300. CurrentStep = GetNextStep (); // gets the first step if CurrentStep == null
  301. }
  302. private void NextfinishBtn_Clicked ()
  303. {
  304. if (CurrentStep == steps.Last.Value) {
  305. var args = new WizardButtonEventArgs ();
  306. Finished?.Invoke (args);
  307. if (!args.Cancel) {
  308. finishedPressed = true;
  309. Application.RequestStop (this);
  310. }
  311. } else {
  312. var args = new WizardButtonEventArgs ();
  313. MovingNext?.Invoke (args);
  314. if (!args.Cancel) {
  315. GoNext ();
  316. }
  317. }
  318. }
  319. /// <summary>
  320. /// Causes the wizad to move to the next enabled step (or last step if <see cref="CurrentStep"/> is not set).
  321. /// If there is no previous step, does nothing.
  322. /// </summary>
  323. public void GoNext ()
  324. {
  325. var nextStep = GetNextStep ();
  326. if (nextStep != null) {
  327. GoToStep (nextStep);
  328. }
  329. }
  330. /// <summary>
  331. /// Returns the next enabled <see cref="WizardStep"/> after the current step. Takes into account steps which
  332. /// are disabled. If <see cref="CurrentStep"/> is `null` returns the first enabled step.
  333. /// </summary>
  334. /// <returns>The next step after the current step, if there is one; otherwise returns `null`, which
  335. /// indicates either there are no enabled steps or the current step is the last enabled step.</returns>
  336. public WizardStep GetNextStep ()
  337. {
  338. LinkedListNode<WizardStep> step = null;
  339. if (CurrentStep == null) {
  340. // Get last step, assume it is next
  341. step = steps.First;
  342. } else {
  343. // Get the step after current
  344. step = steps.Find (CurrentStep);
  345. if (step != null) {
  346. step = step.Next;
  347. }
  348. }
  349. // step now points to the potential next step
  350. while (step != null) {
  351. if (step.Value.Enabled) {
  352. return step.Value;
  353. }
  354. step = step.Next;
  355. }
  356. return null;
  357. }
  358. private void BackBtn_Clicked ()
  359. {
  360. var args = new WizardButtonEventArgs ();
  361. MovingBack?.Invoke (args);
  362. if (!args.Cancel) {
  363. GoBack ();
  364. }
  365. }
  366. /// <summary>
  367. /// Causes the wizad to move to the previous enabled step (or first step if <see cref="CurrentStep"/> is not set).
  368. /// If there is no previous step, does nothing.
  369. /// </summary>
  370. public void GoBack ()
  371. {
  372. var previous = GetPreviousStep ();
  373. if (previous != null) {
  374. GoToStep (previous);
  375. }
  376. }
  377. /// <summary>
  378. /// Returns the first enabled <see cref="WizardStep"/> before the current step. Takes into account steps which
  379. /// are disabled. If <see cref="CurrentStep"/> is `null` returns the last enabled step.
  380. /// </summary>
  381. /// <returns>The first step ahead of the current step, if there is one; otherwise returns `null`, which
  382. /// indicates either there are no enabled steps or the current step is the first enabled step.</returns>
  383. public WizardStep GetPreviousStep ()
  384. {
  385. LinkedListNode<WizardStep> step = null;
  386. if (CurrentStep == null) {
  387. // Get last step, assume it is previous
  388. step = steps.Last;
  389. } else {
  390. // Get the step before current
  391. step = steps.Find (CurrentStep);
  392. if (step != null) {
  393. step = step.Previous;
  394. }
  395. }
  396. // step now points to the potential previous step
  397. while (step != null) {
  398. if (step.Value.Enabled) {
  399. return step.Value;
  400. }
  401. step = step.Previous;
  402. }
  403. return null;
  404. }
  405. /// <summary>
  406. /// Returns the first enabled step in the Wizard
  407. /// </summary>
  408. /// <returns>The last enabled step</returns>
  409. public WizardStep GetFirstStep ()
  410. {
  411. return steps.FirstOrDefault (s => s.Enabled);
  412. }
  413. /// <summary>
  414. /// Returns the last enabled step in the Wizard
  415. /// </summary>
  416. /// <returns>The last enabled step</returns>
  417. public WizardStep GetLastStep ()
  418. {
  419. return steps.LastOrDefault (s => s.Enabled);
  420. }
  421. private LinkedList<WizardStep> steps = new LinkedList<WizardStep> ();
  422. private WizardStep currentStep = null;
  423. /// <summary>
  424. /// If the <see cref="CurrentStep"/> is not the first step in the wizard, this button causes
  425. /// the <see cref="MovingBack"/> event to be fired and the wizard moves to the previous step.
  426. /// </summary>
  427. /// <remarks>
  428. /// Use the <see cref="MovingBack"></see> event to be notified when the user attempts to go back.
  429. /// </remarks>
  430. public Button BackButton { get => backBtn; }
  431. private Button backBtn;
  432. /// <summary>
  433. /// If the <see cref="CurrentStep"/> is the last step in the wizard, this button causes
  434. /// the <see cref="Finished"/> event to be fired and the wizard to close. If the step is not the last step,
  435. /// the <see cref="MovingNext"/> event will be fired and the wizard will move next step.
  436. /// </summary>
  437. /// <remarks>
  438. /// Use the <see cref="MovingNext"></see> and <see cref="Finished"></see> events to be notified
  439. /// when the user attempts go to the next step or finish the wizard.
  440. /// </remarks>
  441. public Button NextFinishButton { get => nextfinishBtn; }
  442. private Button nextfinishBtn;
  443. /// <summary>
  444. /// Adds a step to the wizard. The Next and Back buttons navigate through the added steps in the
  445. /// order they were added.
  446. /// </summary>
  447. /// <param name="newStep"></param>
  448. /// <remarks>The "Next..." button of the last step added will read "Finish" (unless changed from default).</remarks>
  449. public void AddStep (WizardStep newStep)
  450. {
  451. steps.AddLast (newStep);
  452. this.Add (newStep);
  453. newStep.EnabledChanged += UpdateButtonsAndTitle;
  454. newStep.TitleChanged += (args) => UpdateButtonsAndTitle();
  455. UpdateButtonsAndTitle ();
  456. }
  457. /// <summary>
  458. /// The title of the Wizard, shown at the top of the Wizard with " - currentStep.Title" appended.
  459. /// </summary>
  460. public new ustring Title {
  461. get {
  462. // The base (Dialog) Title holds the full title ("Wizard Title - Step Title")
  463. return base.Title;
  464. }
  465. set {
  466. wizardTitle = value;
  467. base.Title = $"{wizardTitle}{(steps.Count > 0 && currentStep != null ? " - " + currentStep.Title : string.Empty)}";
  468. }
  469. }
  470. private ustring wizardTitle = ustring.Empty;
  471. /// <summary>
  472. /// <see cref="EventArgs"/> for <see cref="WizardStep"/> transition events.
  473. /// </summary>
  474. public class WizardButtonEventArgs : EventArgs {
  475. /// <summary>
  476. /// Set to true to cancel the transition to the next step.
  477. /// </summary>
  478. public bool Cancel { get; set; }
  479. /// <summary>
  480. /// Initializes a new instance of <see cref="WizardButtonEventArgs"/>
  481. /// </summary>
  482. public WizardButtonEventArgs ()
  483. {
  484. Cancel = false;
  485. }
  486. }
  487. /// <summary>
  488. /// This event is raised when the Back button in the <see cref="Wizard"/> is clicked. The Back button is always
  489. /// the first button in the array of Buttons passed to the <see cref="Wizard"/> constructor, if any.
  490. /// </summary>
  491. public event Action<WizardButtonEventArgs> MovingBack;
  492. /// <summary>
  493. /// This event is raised when the Next/Finish button in the <see cref="Wizard"/> is clicked. The Next/Finish button is always
  494. /// the last button in the array of Buttons passed to the <see cref="Wizard"/> constructor, if any. This event is only
  495. /// raised if the <see cref="CurrentStep"/> is the last Step in the Wizard flow
  496. /// (otherwise the <see cref="Finished"/> event is raised).
  497. /// </summary>
  498. public event Action<WizardButtonEventArgs> MovingNext;
  499. /// <summary>
  500. /// This event is raised when the Next/Finish button in the <see cref="Wizard"/> is clicked. The Next/Finish button is always
  501. /// the last button in the array of Buttons passed to the <see cref="Wizard"/> constructor, if any. This event is only
  502. /// raised if the <see cref="CurrentStep"/> is the last Step in the Wizard flow
  503. /// (otherwise the <see cref="Finished"/> event is raised).
  504. /// </summary>
  505. public event Action<WizardButtonEventArgs> Finished;
  506. /// <summary>
  507. /// This event is raised when the user has cancelled the <see cref="Wizard"/> (with Ctrl-Q or ESC).
  508. /// </summary>
  509. public event Action<WizardButtonEventArgs> Cancelled;
  510. /// <summary>
  511. /// <see cref="EventArgs"/> for <see cref="WizardStep"/> events.
  512. /// </summary>
  513. public class StepChangeEventArgs : EventArgs {
  514. /// <summary>
  515. /// The current (or previous) <see cref="WizardStep"/>.
  516. /// </summary>
  517. public WizardStep OldStep { get; }
  518. /// <summary>
  519. /// The <see cref="WizardStep"/> the <see cref="Wizard"/> is changing to or has changed to.
  520. /// </summary>
  521. public WizardStep NewStep { get; }
  522. /// <summary>
  523. /// Event handlers can set to true before returning to cancel the step transition.
  524. /// </summary>
  525. public bool Cancel { get; set; }
  526. /// <summary>
  527. /// Initializes a new instance of <see cref="StepChangeEventArgs"/>
  528. /// </summary>
  529. /// <param name="oldStep">The current <see cref="WizardStep"/>.</param>
  530. /// <param name="newStep">The new <see cref="WizardStep"/>.</param>
  531. public StepChangeEventArgs (WizardStep oldStep, WizardStep newStep)
  532. {
  533. OldStep = oldStep;
  534. NewStep = newStep;
  535. Cancel = false;
  536. }
  537. }
  538. /// <summary>
  539. /// This event is raised when the current <see cref="CurrentStep"/>) is about to change. Use <see cref="StepChangeEventArgs.Cancel"/>
  540. /// to abort the transition.
  541. /// </summary>
  542. public event Action<StepChangeEventArgs> StepChanging;
  543. /// <summary>
  544. /// This event is raised after the <see cref="Wizard"/> has changed the <see cref="CurrentStep"/>.
  545. /// </summary>
  546. public event Action<StepChangeEventArgs> StepChanged;
  547. /// <summary>
  548. /// Gets or sets the currently active <see cref="WizardStep"/>.
  549. /// </summary>
  550. public WizardStep CurrentStep {
  551. get => currentStep;
  552. set {
  553. GoToStep (value);
  554. }
  555. }
  556. /// <summary>
  557. /// Called when the <see cref="Wizard"/> is about to transition to another <see cref="WizardStep"/>. Fires the <see cref="StepChanging"/> event.
  558. /// </summary>
  559. /// <param name="oldStep">The step the Wizard is about to change from</param>
  560. /// <param name="newStep">The step the Wizard is about to change to</param>
  561. /// <returns>True if the change is to be cancelled.</returns>
  562. public virtual bool OnStepChanging (WizardStep oldStep, WizardStep newStep)
  563. {
  564. var args = new StepChangeEventArgs (oldStep, newStep);
  565. StepChanging?.Invoke (args);
  566. return args.Cancel;
  567. }
  568. /// <summary>
  569. /// Called when the <see cref="Wizard"/> has completed transition to a new <see cref="WizardStep"/>. Fires the <see cref="StepChanged"/> event.
  570. /// </summary>
  571. /// <param name="oldStep">The step the Wizard changed from</param>
  572. /// <param name="newStep">The step the Wizard has changed to</param>
  573. /// <returns>True if the change is to be cancelled.</returns>
  574. public virtual bool OnStepChanged (WizardStep oldStep, WizardStep newStep)
  575. {
  576. var args = new StepChangeEventArgs (oldStep, newStep);
  577. StepChanged?.Invoke (args);
  578. return args.Cancel;
  579. }
  580. /// <summary>
  581. /// Changes to the specified <see cref="WizardStep"/>.
  582. /// </summary>
  583. /// <param name="newStep">The step to go to.</param>
  584. /// <returns>True if the transition to the step succeeded. False if the step was not found or the operation was cancelled.</returns>
  585. public bool GoToStep (WizardStep newStep)
  586. {
  587. if (OnStepChanging (currentStep, newStep) || (newStep != null && !newStep.Enabled)) {
  588. return false;
  589. }
  590. // Hide all but the new step
  591. foreach (WizardStep step in steps) {
  592. step.Visible = (step == newStep);
  593. }
  594. var oldStep = currentStep;
  595. currentStep = newStep;
  596. UpdateButtonsAndTitle ();
  597. // Set focus to the nav buttons
  598. if (backBtn.HasFocus) {
  599. backBtn.SetFocus ();
  600. } else {
  601. nextfinishBtn.SetFocus ();
  602. }
  603. if (OnStepChanged (oldStep, currentStep)) {
  604. // For correctness we do this, but it's meaningless because there's nothing to cancel
  605. return false;
  606. }
  607. return true;
  608. }
  609. private void UpdateButtonsAndTitle ()
  610. {
  611. if (CurrentStep == null) return;
  612. base.Title = $"{wizardTitle}{(steps.Count > 0 ? " - " + CurrentStep.Title : string.Empty)}";
  613. // Configure the Back button
  614. backBtn.Text = CurrentStep.BackButtonText != ustring.Empty ? CurrentStep.BackButtonText : Strings.wzBack; // "_Back";
  615. backBtn.Visible = (CurrentStep != GetFirstStep ());
  616. // Configure the Next/Finished button
  617. if (CurrentStep == GetLastStep ()) {
  618. nextfinishBtn.Text = CurrentStep.NextButtonText != ustring.Empty ? CurrentStep.NextButtonText : Strings.wzFinish; // "Fi_nish";
  619. } else {
  620. nextfinishBtn.Text = CurrentStep.NextButtonText != ustring.Empty ? CurrentStep.NextButtonText : Strings.wzNext; // "_Next...";
  621. }
  622. SetNeedsLayout ();
  623. LayoutSubviews ();
  624. Redraw (Bounds);
  625. }
  626. }
  627. }