Merge pull request #1220 from ispyisail/feature/script-buttons

Add script buttons: stored scripts with an icon in menu and toolbar

sources/scripting/assistantinfo.cpp

@@ -0,0 +1,143 @@
+/*
+	Copyright 2006-2026 The QElectroTech Team
+	This file is part of QElectroTech.
+
+	QElectroTech is free software: you can redistribute it and/or modify
+	it under the terms of the GNU General Public License as published by
+	the Free Software Foundation, either version 2 of the License, or
+	(at your option) any later version.
+
+	QElectroTech is distributed in the hope that it will be useful,
+	but WITHOUT ANY WARRANTY; without even the implied warranty of
+	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+	GNU General Public License for more details.
+
+	You should have received a copy of the GNU General Public License
+	along with QElectroTech.  If not, see <http://www.gnu.org/licenses/>.
+*/
+#include "assistantinfo.h"
+
+#include "qetscriptapi.h"
+#include "scriptlibrary.h"
+#include "../qetapp.h"
+#include "../qetversion.h"
+#include "../utils/qetsettings.h"
+
+#include <QCoreApplication>
+#include <QDateTime>
+#include <QDir>
+#include <QFile>
+#include <QJsonArray>
+#include <QJsonDocument>
+#include <QSaveFile>
+#include <QStandardPaths>
+
+namespace {
+	QJsonObject s_live;	///< empty while live mode is closed
+	bool s_running = true;
+}
+
+namespace AssistantInfo {
+
+QString path()
+{
+	return QStandardPaths::writableLocation(QStandardPaths::AppDataLocation)
+			+ QStringLiteral("/qet-assistant.json");
+}
+
+/**
+	@brief watch
+	Write the file now, again whenever the stored scripts change, and mark
+	it stopped when QElectroTech quits. Called by every editor window as it
+	opens; acts once.
+*/
+void watch()
+{
+	static bool watching = false;
+	if (watching) return;
+	watching = true;
+	QObject::connect(&ScriptLibrary::instance(), &ScriptLibrary::changed, &write);
+	QObject::connect(qApp, &QCoreApplication::aboutToQuit, &markStopped);
+	write();
+}
+
+void write()
+{
+	QJsonArray scripts, refused;
+	for (const ScriptLibrary::Script &s : ScriptLibrary::instance().scripts()) {
+		const ScriptHeader &h = s.header;
+		scripts.append(QJsonObject{
+			{QStringLiteral("id"), h.id},
+			{QStringLiteral("name"), h.name},
+			{QStringLiteral("file"), s.path},
+			{QStringLiteral("icon"), h.icon},
+			{QStringLiteral("tooltip"), h.tooltip},
+			{QStringLiteral("shortcut"), h.shortcut},
+			{QStringLiteral("context"), h.context},
+			{QStringLiteral("action_id"), ScriptLibrary::actionId(h.id)}});
+	}
+	for (const QString &e : ScriptLibrary::instance().errors()) refused.append(e);
+
+	const QJsonObject info{
+		{QStringLiteral("format"), 1},
+		{QStringLiteral("qelectrotech_version"), QetVersion::displayedVersion()},
+		{QStringLiteral("program"), QCoreApplication::applicationFilePath()},
+		{QStringLiteral("pid"), QCoreApplication::applicationPid()},
+		{QStringLiteral("running"), s_running},
+		{QStringLiteral("written"), QDateTime::currentDateTimeUtc().toString(Qt::ISODate)},
+		{QStringLiteral("folders"), QJsonObject{
+			{QStringLiteral("data"), QETApp::dataDir()},
+			{QStringLiteral("config"), QETApp::configDir()},
+			{QStringLiteral("scripts"), ScriptLibrary::folder()},
+			{QStringLiteral("elements_common"), QETApp::commonElementsDir()},
+			{QStringLiteral("elements_company"), QETApp::companyElementsDir()},
+			{QStringLiteral("elements_custom"), QETApp::customElementsDir()},
+			{QStringLiteral("titleblocks_common"), QETApp::commonTitleBlockTemplatesDir()},
+			{QStringLiteral("titleblocks_company"), QETApp::companyTitleBlockTemplatesDir()},
+			{QStringLiteral("titleblocks_custom"), QETApp::customTitleBlockTemplatesDir()}}},
+		{QStringLiteral("features"), QJsonObject{
+#ifdef QET_HAS_SCRIPTING
+			{QStringLiteral("scripting_available"), true},
+#else
+			{QStringLiteral("scripting_available"), false},
+#endif
+			{QStringLiteral("scripting_enabled"), QetSettings::scriptingEnabled()},
+			{QStringLiteral("live_mode_open"), !s_live.isEmpty()}}},
+		{QStringLiteral("script_api"), QJsonArray::fromStringList(QetScriptApi::signatures())},
+		{QStringLiteral("stored_scripts"), scripts},
+		{QStringLiteral("refused_scripts"), refused},
+		{QStringLiteral("live"), s_live.isEmpty() ? QJsonValue() : QJsonValue(s_live)}};
+
+	const QString file_path = path();
+	QDir().mkpath(QFileInfo(file_path).path());
+	QSaveFile file(file_path);
+	if (!file.open(QIODevice::WriteOnly)) return;
+	file.write(QJsonDocument(info).toJson(QJsonDocument::Indented));
+	if (file.commit())
+		QFile::setPermissions(file_path, QFile::ReadOwner | QFile::WriteOwner);
+}
+
+/**
+	@brief setLive
+	The live channel's details while it is open (socket, token), or an
+	empty object once it closes.
+*/
+void setLive(const QJsonObject &live)
+{
+	s_live = live;
+	write();
+}
+
+/**
+	@brief markStopped
+	QElectroTech is quitting: the file stays, as a record of where things
+	are, but says nothing is listening any more.
+*/
+void markStopped()
+{
+	s_running = false;
+	s_live = QJsonObject();
+	write();
+}
+
+}

sources/scripting/assistantinfo.h

@@ -0,0 +1,50 @@
+/*
+	Copyright 2006-2026 The QElectroTech Team
+	This file is part of QElectroTech.
+
+	QElectroTech is free software: you can redistribute it and/or modify
+	it under the terms of the GNU General Public License as published by
+	the Free Software Foundation, either version 2 of the License, or
+	(at your option) any later version.
+
+	QElectroTech is distributed in the hope that it will be useful,
+	but WITHOUT ANY WARRANTY; without even the implied warranty of
+	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+	GNU General Public License for more details.
+
+	You should have received a copy of the GNU General Public License
+	along with QElectroTech.  If not, see <http://www.gnu.org/licenses/>.
+*/
+#ifndef ASSISTANTINFO_H
+#define ASSISTANTINFO_H
+
+#include <QJsonObject>
+#include <QString>
+
+/**
+	@brief qet-assistant.json: what an AI assistant (through the qet MCP
+	server) needs to know about this QElectroTech, in one file.
+
+	Where its folders are -- data, settings, scripts, the element and title
+	block collections --, which features are switched on, every call a
+	script can make, the stored scripts, and, while live mode is open, how
+	to reach it. QElectroTech rewrites it when it starts and whenever one of
+	those changes, so the MCP server reads facts instead of guessing them
+	per platform -- wrong as soon as QElectroTech is started with
+	--data-dir or --config-dir.
+
+	It always lives in the standard data folder for the platform, even
+	when --data-dir moves the data elsewhere: that is the one place the
+	server can look without being told. Readable by the user only: while
+	live mode is open it holds the channel's token.
+*/
+namespace AssistantInfo
+{
+	QString path();
+	void watch();
+	void write();
+	void setLive(const QJsonObject &live);
+	void markStopped();
+}
+
+#endif // ASSISTANTINFO_H

sources/scripting/qetscriptapi.cpp

@@ -133,9 +133,19 @@ int QetScriptApi::folioCount() const
 	all of them.
 */
 QStringList QetScriptApi::apiSignatures() const
+{
+	return signatures();
+}
+
+/**
+	@brief QetScriptApi::signatures
+	apiSignatures() without a script running: what qet-assistant.json lists
+	for an assistant before it has run anything.
+*/
+QStringList QetScriptApi::signatures()
 {
 	QStringList list;
-	const QMetaObject *meta = metaObject();
+	const QMetaObject *meta = &staticMetaObject;
 	for (int i = meta->methodOffset(); i < meta->methodCount(); ++i) {
 		const QMetaMethod method = meta->method(i);
 		if (method.methodType() != QMetaMethod::Method

sources/scripting/qetscriptapi.h

@@ -586,6 +586,7 @@ class QetScriptApi : public QObject
 
 		// -- what a script can call, read from this class itself --
 		Q_INVOKABLE QStringList apiSignatures() const;
+		static QStringList signatures();
 
 		void setUndoGrouped(bool grouped);
 

sources/scripting/qetscripting.cpp

@@ -113,7 +113,8 @@ namespace {
 	constexpr int kScriptTimeoutMs = 30000;
 }
 
-bool runOnProject(const QString &scriptPath, QETProject *project, DiagramView *view)
+bool runOnProject(const QString &scriptPath, QETProject *project, DiagramView *view,
+		  const QString &title)
 {
 	// Checked here as well as at each caller, deliberately: this is the
 	// one function that actually evaluates JavaScript, so it is the one
@@ -173,7 +174,8 @@ bool runOnProject(const QString &scriptPath, QETProject *project, DiagramView *v
 	QUndoStack *stack = (view && project) ? project->undoStack() : nullptr;
 	if (stack) {
 		stack->beginMacro(QObject::tr("Script : %1")
-				  .arg(QFileInfo(scriptPath).completeBaseName()));
+				  .arg(title.isEmpty() ? QFileInfo(scriptPath).completeBaseName()
+						       : title));
 		api->setUndoGrouped(true);
 	}
 
@@ -229,7 +231,7 @@ int run(const QStringList &)
 	return 1;
 }
 
-bool runOnProject(const QString &, QETProject *, DiagramView *)
+bool runOnProject(const QString &, QETProject *, DiagramView *, const QString &)
 {
 	err << "This build of QElectroTech was compiled without the Qt Qml "
 		   "module, so JavaScript scripting is not available.\n";

sources/scripting/qetscripting.h

@@ -57,9 +57,12 @@ namespace QetScripting {
 		@param view the active DiagramView, so the script's zoom methods
 		have something to act on; nullptr from the headless entry point,
 		where they become no-ops (see QetScriptApi).
+		@param title what the undo step is called; the script's file name
+		if empty.
 		@return true if the script ran without throwing.
 	*/
-	bool runOnProject(const QString &scriptPath, QETProject *project, DiagramView *view = nullptr);
+	bool runOnProject(const QString &scriptPath, QETProject *project, DiagramView *view = nullptr,
+			  const QString &title = QString());
 
 }
 

sources/scripting/scriptheader.h

@@ -0,0 +1,118 @@
+/*
+	Copyright 2006-2026 The QElectroTech Team
+	This file is part of QElectroTech.
+
+	QElectroTech is free software: you can redistribute it and/or modify
+	it under the terms of the GNU General Public License as published by
+	the Free Software Foundation, either version 2 of the License, or
+	(at your option) any later version.
+
+	QElectroTech is distributed in the hope that it will be useful,
+	but WITHOUT ANY WARRANTY; without even the implied warranty of
+	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+	GNU General Public License for more details.
+
+	You should have received a copy of the GNU General Public License
+	along with QElectroTech.  If not, see <http://www.gnu.org/licenses/>.
+*/
+#ifndef SCRIPTHEADER_H
+#define SCRIPTHEADER_H
+
+#include <QRegularExpression>
+#include <QString>
+#include <QStringList>
+
+/**
+	@brief The ScriptHeader struct
+	How a stored script's button looks, read from a comment block at the top
+	of the .js file itself, so one file is all there is to write by hand,
+	to share, or for an assistant to create:
+
+	@code
+	// ==QETScript==
+	// @name     Add revision note
+	// @icon     note.svg           (a file next to the script, or builtin:<theme icon>)
+	// @tooltip  Puts a "Rev A" note on the folio on screen
+	// @shortcut Ctrl+Alt+R
+	// @context  canvas             (canvas, selection or conductor)
+	// @api      1
+	// ==/QETScript==
+	@endcode
+
+	Only @name is required. An unknown key is an error rather than ignored:
+	a misspelt "@shortcut" that silently did nothing would be harder to find
+	than a script refused with the line that is wrong.
+
+	Header-only, with no QElectroTech dependency, so it is tested on its own.
+*/
+struct ScriptHeader
+{
+	QString id;        ///< file name without .js; the action id is diagrameditor.script.<id>
+	QString name;
+	QString icon;
+	QString tooltip;
+	QString shortcut;  ///< as QKeySequence::fromString() reads it
+	QString context = QStringLiteral("canvas");
+	int api = 1;
+	QString error;     ///< empty if the header is usable
+
+	bool isValid() const { return error.isEmpty(); }
+
+	static QStringList contexts()
+	{
+		return {QStringLiteral("canvas"), QStringLiteral("selection"),
+			QStringLiteral("conductor")};
+	}
+
+	/**
+		@brief parse
+		@param text : the whole script
+		@param id : the script's file name without its extension
+	*/
+	static ScriptHeader parse(const QString &text, const QString &id)
+	{
+		ScriptHeader h;
+		h.id = id;
+		static const QRegularExpression block(
+			QStringLiteral("//\\s*==QETScript==\\s*\\n(.*?)//\\s*==/QETScript=="),
+			QRegularExpression::DotMatchesEverythingOption);
+		const QRegularExpressionMatch m = block.match(text);
+		if (!m.hasMatch()) {
+			h.error = QStringLiteral("no // ==QETScript== header");
+			return h;
+		}
+		static const QRegularExpression line_re(
+			QStringLiteral("^\\s*//\\s*@(\\w+)\\s+(.*?)\\s*$"));
+		const QStringList lines = m.captured(1).split(QLatin1Char('\n'));
+		for (const QString &line : lines) {
+			const QRegularExpressionMatch lm = line_re.match(line);
+			if (!lm.hasMatch()) {
+				continue;
+			}
+			const QString key = lm.captured(1);
+			const QString value = lm.captured(2);
+			if (key == QLatin1String("name")) h.name = value;
+			else if (key == QLatin1String("icon")) h.icon = value;
+			else if (key == QLatin1String("tooltip")) h.tooltip = value;
+			else if (key == QLatin1String("shortcut")) h.shortcut = value;
+			else if (key == QLatin1String("context")) h.context = value;
+			else if (key == QLatin1String("api")) h.api = value.toInt();
+			else {
+				h.error = QStringLiteral("unknown header key @%1").arg(key);
+				return h;
+			}
+		}
+		if (h.name.isEmpty()) {
+			h.error = QStringLiteral("@name is required");
+		} else if (!contexts().contains(h.context)) {
+			h.error = QStringLiteral("@context must be one of: %1")
+					.arg(contexts().join(QStringLiteral(", ")));
+		} else if (h.api != 1) {
+			h.error = QStringLiteral("@api %1 is not supported by this "
+						 "version (1 is)").arg(h.api);
+		}
+		return h;
+	}
+};
+
+#endif // SCRIPTHEADER_H

sources/scripting/scriptlibrary.cpp

@@ -0,0 +1,194 @@
+/*
+	Copyright 2006-2026 The QElectroTech Team
+	This file is part of QElectroTech.
+
+	QElectroTech is free software: you can redistribute it and/or modify
+	it under the terms of the GNU General Public License as published by
+	the Free Software Foundation, either version 2 of the License, or
+	(at your option) any later version.
+
+	QElectroTech is distributed in the hope that it will be useful,
+	but WITHOUT ANY WARRANTY; without even the implied warranty of
+	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+	GNU General Public License for more details.
+
+	You should have received a copy of the GNU General Public License
+	along with QElectroTech.  If not, see <http://www.gnu.org/licenses/>.
+*/
+#include "scriptlibrary.h"
+
+#include "../qetapp.h"
+
+#include <QDir>
+#include <QFile>
+#include <QFileInfo>
+#include <QGuiApplication>
+#include <QPainter>
+#include <QPalette>
+#include <QPixmap>
+
+ScriptLibrary &ScriptLibrary::instance()
+{
+	static ScriptLibrary library;
+	return library;
+}
+
+/**
+	@brief ScriptLibrary::folder
+	Where stored scripts live: "scripts" in the user's data folder, next to
+	the user's own element and title block collections.
+*/
+QString ScriptLibrary::folder()
+{
+	return QETApp::dataDir() + QStringLiteral("/scripts");
+}
+
+/**
+	@brief ScriptLibrary::actionId
+	The ShortcutManager id of a script's action. The "diagrameditor."
+	prefix is what puts it among the commands the shortcut bar can show.
+*/
+QString ScriptLibrary::actionId(const QString &script_id)
+{
+	return QStringLiteral("diagrameditor.script.") + script_id;
+}
+
+ScriptLibrary::ScriptLibrary()
+{
+		//An editor saving a file often writes it more than once, or
+		//replaces it through a rename: wait for it to settle.
+	m_rescan_timer.setSingleShot(true);
+	m_rescan_timer.setInterval(250);
+	connect(&m_rescan_timer, &QTimer::timeout, this, &ScriptLibrary::rescan);
+	connect(&m_watcher, &QFileSystemWatcher::directoryChanged,
+		&m_rescan_timer, qOverload<>(&QTimer::start));
+	connect(&m_watcher, &QFileSystemWatcher::fileChanged,
+		&m_rescan_timer, qOverload<>(&QTimer::start));
+	rescan();
+}
+
+/**
+	@brief ScriptLibrary::watch
+	Watch the folder and each script in it, or, while the folder does not
+	exist yet, the data folder it will be created in.
+*/
+void ScriptLibrary::watch()
+{
+	if (!m_watcher.files().isEmpty()) m_watcher.removePaths(m_watcher.files());
+	if (!m_watcher.directories().isEmpty()) m_watcher.removePaths(m_watcher.directories());
+
+	const QDir dir(folder());
+	if (!dir.exists()) {
+		if (QFileInfo::exists(QETApp::dataDir())) {
+			m_watcher.addPath(QETApp::dataDir());
+		}
+		return;
+	}
+	m_watcher.addPath(dir.path());
+	QStringList files;
+	for (const Script &s : std::as_const(m_scripts)) files << s.path;
+	for (const QString &e : std::as_const(m_errors)) files << dir.filePath(e.section(QLatin1Char(':'), 0, 0));
+	if (!files.isEmpty()) m_watcher.addPaths(files);
+}
+
+void ScriptLibrary::rescan()
+{
+	QList<Script> scripts;
+	QStringList errors;
+	const QDir dir(folder());
+	const QFileInfoList infos = dir.entryInfoList({QStringLiteral("*.js")},
+						      QDir::Files, QDir::Name);
+	for (const QFileInfo &info : infos) {
+		QFile file(info.filePath());
+		if (!file.open(QIODevice::ReadOnly | QIODevice::Text)) continue;
+		const ScriptHeader header = ScriptHeader::parse(
+			QString::fromUtf8(file.readAll()), info.completeBaseName());
+		if (header.isValid()) {
+			scripts << Script{header, info.filePath()};
+		} else {
+			errors << info.fileName() + QStringLiteral(": ") + header.error;
+		}
+	}
+
+	auto signature = [](const QList<Script> &list) {
+		QStringList parts;
+		for (const Script &s : list) {
+			const ScriptHeader &h = s.header;
+			parts << QStringList{s.path, h.name, h.icon, h.tooltip, h.shortcut,
+					     h.context}.join(QLatin1Char('\x1f'));
+		}
+		return parts;
+	};
+	const bool same = signature(scripts) == signature(m_scripts) && errors == m_errors;
+	m_scripts = scripts;
+	m_errors = errors;
+	watch();
+		//The script's own text is read again on every run, so only a
+		//change to what its button shows needs the actions rebuilt --
+		//except an icon file edited in place, which this cannot see; the
+		//next change to the folder picks it up.
+	if (!same) emit changed();
+}
+
+QList<ScriptLibrary::Script> ScriptLibrary::scripts() const
+{
+	return m_scripts;
+}
+
+/**
+	@brief ScriptLibrary::errors
+	One "file.js: reason" per script whose header could not be used, so
+	whoever wrote it can be told why its button is missing.
+*/
+QStringList ScriptLibrary::errors() const
+{
+	return m_errors;
+}
+
+/**
+	@brief ScriptLibrary::icon
+	The icon a script's header names -- "builtin:<name>" from the icon
+	theme, or an image file, relative to the script -- or, failing that, a
+	tile with the script's initials, so every button can be told apart.
+*/
+QIcon ScriptLibrary::icon(const Script &script)
+{
+	const QString spec = script.header.icon;
+	if (spec.startsWith(QLatin1String("builtin:"))) {
+		const QIcon themed = QIcon::fromTheme(spec.mid(8));
+		if (!themed.isNull()) return themed;
+	} else if (!spec.isEmpty()) {
+		const QString path = QFileInfo(script.path).dir().absoluteFilePath(spec);
+		if (QFileInfo::exists(path)) {
+			const QIcon file_icon(path);
+			if (!file_icon.availableSizes().isEmpty()
+			    || !file_icon.pixmap(32).isNull()) {
+				return file_icon;
+			}
+		}
+	}
+
+	QString initials;
+	for (const QString &word : script.header.name.split(QLatin1Char(' '), Qt::SkipEmptyParts)) {
+		if (word.at(0).isLetterOrNumber()) initials += word.at(0).toUpper();
+		if (initials.size() == 2) break;
+	}
+	if (initials.isEmpty()) initials = QStringLiteral("JS");
+
+	const QPalette palette = QGuiApplication::palette();
+	QPixmap pixmap(64, 64);
+	pixmap.fill(Qt::transparent);
+	QPainter painter(&pixmap);
+	painter.setRenderHint(QPainter::Antialiasing);
+	painter.setPen(Qt::NoPen);
+	painter.setBrush(palette.color(QPalette::Highlight));
+	painter.drawRoundedRect(QRectF(4, 4, 56, 56), 10, 10);
+	QFont font = painter.font();
+	font.setBold(true);
+	font.setPixelSize(initials.size() == 1 ? 34 : 26);
+	painter.setFont(font);
+	painter.setPen(palette.color(QPalette::HighlightedText));
+	painter.drawText(QRectF(4, 4, 56, 56), Qt::AlignCenter, initials);
+	painter.end();
+	return QIcon(pixmap);
+}

sources/scripting/scriptlibrary.h

@@ -0,0 +1,72 @@
+/*
+	Copyright 2006-2026 The QElectroTech Team
+	This file is part of QElectroTech.
+
+	QElectroTech is free software: you can redistribute it and/or modify
+	it under the terms of the GNU General Public License as published by
+	the Free Software Foundation, either version 2 of the License, or
+	(at your option) any later version.
+
+	QElectroTech is distributed in the hope that it will be useful,
+	but WITHOUT ANY WARRANTY; without even the implied warranty of
+	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+	GNU General Public License for more details.
+
+	You should have received a copy of the GNU General Public License
+	along with QElectroTech.  If not, see <http://www.gnu.org/licenses/>.
+*/
+#ifndef SCRIPTLIBRARY_H
+#define SCRIPTLIBRARY_H
+
+#include "scriptheader.h"
+
+#include <QFileSystemWatcher>
+#include <QIcon>
+#include <QList>
+#include <QObject>
+#include <QTimer>
+
+/**
+	@brief The ScriptLibrary class
+	The user's stored scripts: every .js file with a ScriptHeader in
+	folder(). The folder is the whole interface. A script written by hand
+	in any editor, one saved by the script manager and one installed by an
+	assistant through the qet MCP server all arrive the same way, as a file,
+	and the library notices it with a QFileSystemWatcher and emits changed().
+
+	One instance for the application, shared by every editor window.
+*/
+class ScriptLibrary : public QObject
+{
+	Q_OBJECT
+
+	public:
+		struct Script
+		{
+			ScriptHeader header;
+			QString path;
+		};
+
+		static ScriptLibrary &instance();
+		static QString folder();
+		static QString actionId(const QString &script_id);
+		static QIcon icon(const Script &script);
+
+		QList<Script> scripts() const;
+		QStringList errors() const;
+
+	signals:
+		void changed();
+
+	private:
+		ScriptLibrary();
+		void rescan();
+		void watch();
+
+		QFileSystemWatcher m_watcher;
+		QTimer m_rescan_timer;
+		QList<Script> m_scripts;
+		QStringList m_errors;
+};
+
+#endif // SCRIPTLIBRARY_H