Initial work on tutorial wizard, not ready for general use yet. See #950.

Author: azonenberg

lib

@@ -2,7 +2,7 @@
 *                                                                                                                      *
 * ngscopeclient                                                                                                        *
 *                                                                                                                      *
-* Copyright (c) 2012-2024 Andrew D. Zonenberg                                                                          *
+* Copyright (c) 2012-2026 Andrew D. Zonenberg and contributors                                                         *
 * All rights reserved.                                                                                                 *
 *                                                                                                                      *
 * Redistribution and use in source and binary forms, with or without modification, are permitted provided that the     *
@@ -35,6 +35,7 @@
 
 #include "ngscopeclient.h"
 #include "AddInstrumentDialog.h"
+#include "MainWindow.h"
 
 using namespace std;
 
@@ -44,17 +45,22 @@ using namespace std;
 AddInstrumentDialog::AddInstrumentDialog(
 	const string& title,
 	const string& nickname,
-	Session& session,
+	Session* session,
+	MainWindow* parent,
 	const string& driverType)
-	: Dialog(title, string("AddInstrument") + to_string_hex(reinterpret_cast<uintptr_t>(this)), ImVec2(600, 150))
-	, m_session(session)
+	: Dialog(
+		title,
+		string("AddInstrument") + to_string_hex(reinterpret_cast<uintptr_t>(this)),
+		ImVec2(600, 150),
+		session,
+		parent)
 	, m_nickname(nickname)
 	, m_selectedDriver(0)
 	, m_selectedTransport(0)
 {
 	SCPITransport::EnumTransports(m_transports);
 
-	m_drivers = session.GetDriverNamesForType(driverType);
+	m_drivers = session->GetDriverNamesForType(driverType);
 }
 
 AddInstrumentDialog::~AddInstrumentDialog()
@@ -72,13 +78,16 @@ AddInstrumentDialog::~AddInstrumentDialog()
  */
 bool AddInstrumentDialog::DoRender()
 {
+	auto tutorial = m_parent->GetTutorialWizard();
+
 	ImGui::InputText("Nickname", &m_nickname);
 	HelpMarker(
 		"Text nickname for this instrument so you can distinguish between multiple similar devices.\n"
 		"\n"
 		"This is shown on the list of recent instruments, to disambiguate channel names in multi-instrument setups, etc.");
 
-	Combo("Driver", m_drivers, m_selectedDriver);
+	bool dropdownOpen = false;
+	Combo("Driver", m_drivers, m_selectedDriver, &dropdownOpen);
 	HelpMarker(
 		"Select the instrument driver to use.\n"
 		"\n"
@@ -88,7 +97,22 @@ bool AddInstrumentDialog::DoRender()
 		"\n"
 		"Check the user manual for details of what driver to use with a given instrument.");
 
-	Combo("Transport", m_transports, m_selectedTransport);
+	//Show speech bubble for tutorial
+	bool showedBubble = false;
+	if(tutorial &&
+		(tutorial->GetCurrentStep() == TutorialWizard::TUTORIAL_02_CONNECT) &&
+		(m_drivers[m_selectedDriver] != "demo") &&
+		!dropdownOpen )
+	{
+		auto pos = ImGui::GetCursorScreenPos();
+		ImVec2 anchorPos(pos.x + 10*ImGui::GetFontSize(), pos.y);
+		tutorial->DrawSpeechBubble(anchorPos, ImGuiDir_Up, "Select the \"demo\" driver");
+		showedBubble = true;
+	}
+	else if(dropdownOpen)	//suppress further bubbles if dropdown is active
+		showedBubble = true;
+
+	Combo("Transport", m_transports, m_selectedTransport, &dropdownOpen);
 	HelpMarker(
 		"Select the SCPI transport for the connection between your computer and the instrument.\n"
 		"\n"
@@ -104,6 +128,21 @@ bool AddInstrumentDialog::DoRender()
 			}
 		);
 
+	//Show speech bubble for tutorial
+	if(tutorial &&
+		(tutorial->GetCurrentStep() == TutorialWizard::TUTORIAL_02_CONNECT) &&
+		(m_transports[m_selectedTransport] != "null") &&
+		!dropdownOpen &&
+		!showedBubble)
+	{
+		auto pos = ImGui::GetCursorScreenPos();
+		ImVec2 anchorPos(pos.x + 10*ImGui::GetFontSize(), pos.y);
+		tutorial->DrawSpeechBubble(anchorPos, ImGuiDir_Up, "Select the \"null\" transport");
+		showedBubble = true;
+	}
+	else if(dropdownOpen)	//suppress further bubbles if dropdown is active
+		showedBubble = true;
+
 	ImGui::InputText("Path", &m_path);
 	HelpMarker(
 		"Transport-specific description of how to connect to the instrument.\n",
@@ -170,6 +209,6 @@ SCPITransport* AddInstrumentDialog::MakeTransport()
 
 bool AddInstrumentDialog::DoConnect(SCPITransport* transport)
 {
-	m_session.CreateAndAddInstrument(m_drivers[m_selectedDriver], transport, m_nickname);
+	m_session->CreateAndAddInstrument(m_drivers[m_selectedDriver], transport, m_nickname);
 	return true;
 }

src/ngscopeclient/AddInstrumentDialog.cpp

@@ -2,7 +2,7 @@
 *                                                                                                                      *
 * ngscopeclient                                                                                                        *
 *                                                                                                                      *
-* Copyright (c) 2012-2024 Andrew D. Zonenberg                                                                          *
+* Copyright (c) 2012-2026 Andrew D. Zonenberg and contributors                                                         *
 * All rights reserved.                                                                                                 *
 *                                                                                                                      *
 * Redistribution and use in source and binary forms, with or without modification, are permitted provided that the     *
@@ -44,7 +44,8 @@ class AddInstrumentDialog : public Dialog
 	AddInstrumentDialog(
 		const std::string& title,
 		const std::string& nickname,
-		Session& session,
+		Session* session,
+		MainWindow* parent,
 		const std::string& driverType);
 	virtual ~AddInstrumentDialog();
 
@@ -55,8 +56,6 @@ class AddInstrumentDialog : public Dialog
 
 	virtual bool DoConnect(SCPITransport* transport);
 
-	Session& m_session;
-
 	//GUI widget values
 	std::string m_nickname;
 	int m_selectedDriver;

src/ngscopeclient/AddInstrumentDialog.h

@@ -108,6 +108,7 @@ add_executable(ngscopeclient
 	TextureManager.cpp
 	TriggerGroup.cpp
 	TriggerPropertiesDialog.cpp
+	TutorialWizard.cpp
 	VulkanWindow.cpp
 	WaveformArea.cpp
 	WaveformGroup.cpp

src/ngscopeclient/CMakeLists.txt

@@ -136,8 +136,10 @@ void Dialog::RenderErrorPopup()
 
 /**
 	@brief Displays a combo box from a vector<string>
+
+	@param open optional boolean indicating the dropdown is open
  */
-bool Dialog::Combo(const string& label, const vector<string>& items, int& selection)
+bool Dialog::Combo(const string& label, const vector<string>& items, int& selection, bool* open)
 {
 	string preview;
 	ImGuiComboFlags flags = 0;
@@ -155,6 +157,9 @@ bool Dialog::Combo(const string& label, const vector<string>& items, int& select
 	//Render the box
 	if(ImGui::BeginCombo(label.c_str(), preview.c_str(), flags))
 	{
+		if(open)
+			*open = true;
+
 		for(int i=0; i<(int)items.size(); i++)
 		{
 			bool selected = (i == selection);
@@ -168,6 +173,8 @@ bool Dialog::Combo(const string& label, const vector<string>& items, int& select
 		}
 		ImGui::EndCombo();
 	}
+	else if(open)
+		*open = false;
 	return changed;
 }
 

src/ngscopeclient/Dialog.cpp

@@ -59,7 +59,7 @@ class Dialog
 	{ return m_title + "###" + m_id; }
 
 	//TODO: this might be better off as a global method?
-	static bool Combo(const std::string& label, const std::vector<std::string>& items, int& selection);
+	static bool Combo(const std::string& label, const std::vector<std::string>& items, int& selection, bool* open = nullptr);
 	static bool UnitInputWithImplicitApply(
 		const std::string& label,
 		std::string& currentValue,

src/ngscopeclient/Dialog.h

@@ -231,6 +231,13 @@ void MainWindow::InitializeDefaultSession()
 
 	//Dock it
 	m_initialWorkspaceDockRequest = w;
+
+	//Spawn the tutorial if requested
+	if(m_session.GetPreferences().GetBool("Help.Wizards.first_run_wizard"))
+	{
+		m_tutorialDialog = make_shared<TutorialWizard>(&m_session, this);
+		AddDialog(m_tutorialDialog);
+	}
 }
 
 void MainWindow::CloseSession()
@@ -266,6 +273,7 @@ void MainWindow::CloseSession()
 	m_historyDialog = nullptr;
 	m_preferenceDialog = nullptr;
 	m_persistenceDialog = nullptr;
+	m_tutorialDialog = nullptr;
 	m_manageInstrumentsDialog = nullptr;
 	m_initialWorkspaceDockRequest = nullptr;
 	m_graphEditor = nullptr;
@@ -1166,6 +1174,8 @@ void MainWindow::OnDialogClosed(const std::shared_ptr<Dialog>& dlg)
 		m_persistenceDialog = nullptr;
 	if(m_notesDialog == dlg)
 		m_notesDialog = nullptr;
+	if(m_tutorialDialog == dlg)
+		m_tutorialDialog = nullptr;
 	if(m_graphEditor == dlg)
 	{
 		m_graphEditorGroups = m_graphEditor->GetGroupIDs();

src/ngscopeclient/MainWindow.cpp

@@ -47,6 +47,7 @@
 #include "ProtocolAnalyzerDialog.h"
 #include "StreamBrowserDialog.h"
 #include "TriggerPropertiesDialog.h"
+#include "TutorialWizard.h"
 #include "Workspace.h"
 #include "imgui_markdown.h"
 
@@ -230,6 +231,10 @@ class MainWindow : public VulkanWindow
 	void SetStartupSession(const std::string& path)
 	{ m_startupSession = path; }
 
+	///@brief Gets a pointer to the tutorial wizard (if we have one open)
+	std::shared_ptr<TutorialWizard> GetTutorialWizard()
+	{ return m_tutorialDialog; }
+
 protected:
 	virtual void DoRender(vk::raii::CommandBuffer& cmdBuf);
 
@@ -364,6 +369,9 @@ class MainWindow : public VulkanWindow
 	///@brief Lab notes
 	std::shared_ptr<Dialog> m_notesDialog;
 
+	///@brief Tutorial flow
+	std::shared_ptr<TutorialWizard> m_tutorialDialog;
+
 	///@brief Filter graph editor
 	std::shared_ptr<FilterGraphEditor> m_graphEditor;
 

src/ngscopeclient/MainWindow.h

@@ -236,6 +236,8 @@ void MainWindow::ViewMenu()
  */
 void MainWindow::AddMenu()
 {
+	auto menuStartPos = ImGui::GetCursorScreenPos();
+
 	if(ImGui::BeginMenu("Add"))
 	{
 		//Make a reverse mapping: timestamp -> instruments last used at that time
@@ -272,6 +274,19 @@ void MainWindow::AddMenu()
 
 		ImGui::EndMenu();
 	}
+
+	//Add hint bubble here during the tutorial, but only if menu is not open
+	//(we don't want to block the user's view of said menu)
+	else if(m_tutorialDialog && (m_tutorialDialog->GetCurrentStep() == TutorialWizard::TUTORIAL_01_ADDINSTRUMENT) )
+	{
+		auto menuEndPos = ImGui::GetCursorScreenPos();
+
+		ImVec2 anchorPos(
+			(menuStartPos.x + menuEndPos.x)/2,
+			menuStartPos.y + 2*ImGui::GetFontSize());
+
+		m_tutorialDialog->DrawSpeechBubble(anchorPos, ImGuiDir_Up, "Add an oscilloscope to your session");
+	}
 }
 
 /**
@@ -293,8 +308,17 @@ void MainWindow::DoAddSubMenu(
 			m_dialogs.emplace(make_shared<AddInstrumentDialog>(
 				string("Add ") + typePretty,
 				defaultName,
-				m_session,
+				&m_session,
+				this,
 				typeInternal));
+
+			//Move to the next step of the tutorial if needed
+			if((typeInternal == "oscilloscope") &&
+				m_tutorialDialog &&
+				(m_tutorialDialog->GetCurrentStep() == TutorialWizard::TUTORIAL_01_ADDINSTRUMENT) )
+			{
+				m_tutorialDialog->AdvanceToNextStep();
+			}
 		}
 		ImGui::Separator();
 
@@ -782,6 +806,16 @@ void MainWindow::HelpMenu()
 {
 	if(ImGui::BeginMenu("Help"))
 	{
+		ImGui::BeginDisabled(m_tutorialDialog != nullptr);
+			if(ImGui::MenuItem("Tutorial..."))
+			{
+				m_tutorialDialog = make_shared<TutorialWizard>(&m_session, this);
+				AddDialog(m_tutorialDialog);
+			}
+		ImGui::EndDisabled();
+
+		ImGui::Separator();
+
 		if(ImGui::MenuItem("About..."))
 			AddDialog(make_shared<AboutDialog>(this));
 

src/ngscopeclient/MainWindow_Menus.cpp

@@ -172,6 +172,17 @@ void PreferenceManager::InitializeDefaults()
 				.Label("Icon color")
 				.Description("Color for icon captions"));
 
+		auto& ahelp = appearance.AddCategory("Help");
+			ahelp.AddPreference(
+				Preference::Color("bubble_outline_color", ColorFromString("#00ff00"))
+				.Label("Bubble outline color")
+				.Description("Color for tutorial bubble outlines"));
+
+			ahelp.AddPreference(
+				Preference::Color("bubble_fill_color", ColorFromString("#202020e0"))
+				.Label("Bubble fill color")
+				.Description("Color for tutorial bubble fill"));
+
 		auto& stream = appearance.AddCategory("Stream Browser");
 			stream.AddPreference(
 				Preference::Enum("numeric_value_display", NUMERIC_DISPLAY_MONO_FONT)
@@ -543,6 +554,13 @@ void PreferenceManager::InitializeDefaults()
 			.Description("Maximum number of recent .scopesession file paths to save in history")
 			.Unit(Unit::UNIT_COUNTS));
 
+	auto& help = this->m_treeRoot.AddCategory("Help");
+		auto& wizards = help.AddCategory("Wizards");
+			wizards.AddPreference(
+				Preference::Bool("first_run_wizard", true)
+				.Label("First-run wizard")
+				.Description("Enable the first-run tutorial wizard"));
+
 	auto& misc = this->m_treeRoot.AddCategory("Miscellaneous");
 		auto& menus = misc.AddCategory("Menus");
 			menus.AddPreference(