Easy Writer

ScriptWorld.h header

#include <ew/app/ScriptWorld.h>

Namespace ew::app

ScriptWorld class

class ew::app::ScriptWorld

The project's codex "world" exposed to a ScriptHost as a global JavaScript object – install it with host.registerGlobal("world", &scriptWorld) and a macro reaches it as world (DESIGN §4.16 "embedded scripting: macros, automation, batch ops"). A script reads the codex and, through the project's undoable command stack, mutates it: every change is pushed as a Command, so a macro's edit is a single undo step exactly like one made in the UI, and a botched macro can be undone.

It wraps a live Project and its CommandStack – both must outlive the bridge and live on the same thread as the ScriptHost (the GUI thread for the desktop console), so a script's mutations run on the thread that owns the project. It does not own either. Every scriptable method is Q_INVOKABLE and returns moc-friendly types (QString / QStringList / QVariantList / bool) so no QtQml value types leak into the public API.

Members

ew::app::ScriptWorld::ScriptWorld(ew::core::Project &project, ew::core::CommandStack &commands, QObject *parent=nullptr)

Wraps project and its commands (neither owned; both must outlive this bridge). parent is the usual QObject parent for lifetime management.

Q_INVOKABLE QStringList ew::app::ScriptWorld::entityIds() const

The ids (as strings) of every codex entity in the project, in project order.

Q_INVOKABLE QVariantList ew::app::ScriptWorld::entities() const

Every codex entity as a plain object {id, name, category} (category is the category's display name, or "" when uncategorized), for a macro to iterate with world.entities().

Q_INVOKABLE QString ew::app::ScriptWorld::entityName(const QString &id) const

The display name of the entity with id id, or "" if there is no such entity.

Q_INVOKABLE QString ew::app::ScriptWorld::findEntity(const QString &name) const

The id of the first codex entity whose name equals name exactly, or "" if none matches.

Q_INVOKABLE QString ew::app::ScriptWorld::field(const QString &id, const QString &key) const

The value of field key on entity id, or "" when the entity or the field is absent.

Q_INVOKABLE QStringList ew::app::ScriptWorld::documentIds() const

The ids (as strings) of every document (prose/screenplay/note) in the project, in project order, for a macro to iterate the manuscript with world.documentIds().

Q_INVOKABLE QVariantList ew::app::ScriptWorld::documents() const

Every document as a plain object {id, title, kind} (kind is the stable token "prose"/"screenplay"/"note"), for world.documents().

Q_INVOKABLE QString ew::app::ScriptWorld::documentTitle(const QString &id) const

The title of the document with id id, or "" if there is no such document.

Q_INVOKABLE QString ew::app::ScriptWorld::documentBody(const QString &id) const

The Markdown body of the document with id id, or "" when the document is absent.

Q_INVOKABLE QStringList ew::app::ScriptWorld::categoryIds() const

The ids (as strings) of every codex category, in stable (id-sorted) order.

Q_INVOKABLE QVariantList ew::app::ScriptWorld::categories() const

Every codex category as a plain object {id, name}, for world.categories().

Q_INVOKABLE QString ew::app::ScriptWorld::categoryName(const QString &id) const

The display name of the category with id id, or "" if it is null/unknown.

Q_INVOKABLE QString ew::app::ScriptWorld::findCategory(const QString &name) const

The id of the first category whose name equals name exactly, or "" if none matches.

Q_INVOKABLE QVariantList ew::app::ScriptWorld::objects() const

Every content object in the project as a plain object {id, title, type} – where type is the stable token ("entity", "document", "timeline_event", "task", "map", "spreadsheet", "source", ...) – so a macro can enumerate the WHOLE model, not only entities and documents.

Q_INVOKABLE QStringList ew::app::ScriptWorld::objectIds(const QString &typeToken) const

The ids of every content object of type typeToken (e.g. "task", "timeline_event", "map"); an empty token returns every object's id, and an unrecognized token returns none.

Q_INVOKABLE QString ew::app::ScriptWorld::objectTitle(const QString &id) const

The display title (or name) of the object with id id, whatever its content type, or "" if there is no such object. Works for every type, not just entities/documents.

Q_INVOKABLE QString ew::app::ScriptWorld::objectType(const QString &id) const

The stable content-type token of the object with id id (e.g. "entity", "document", "map"), or "" if there is no such object.

Q_INVOKABLE QString ew::app::ScriptWorld::createEntity(const QString &name)

Creates an (uncategorized) codex entity named name and returns its new id (a string), as one undoable step. Returns "" for an empty name.

Q_INVOKABLE bool ew::app::ScriptWorld::setField(const QString &id, const QString &key, const QString &value)

Sets field key to value on entity id as one undoable step. Returns true when the entity exists and the change was applied, false otherwise (no such entity).

Q_INVOKABLE bool ew::app::ScriptWorld::renameEntity(const QString &id, const QString &name)

Renames entity id to name as one undoable step. Returns true when the entity exists and name is non-empty, false otherwise.

Q_INVOKABLE QString ew::app::ScriptWorld::createEntityInCategory(const QString &name, const QString &categoryId)

Creates a codex entity named name in category categoryId and returns its new id, as one undoable step. An empty or unknown categoryId leaves the entity uncategorized. Returns "" for an empty name.

Q_INVOKABLE QString ew::app::ScriptWorld::createDocument(const QString &title)

Creates a prose document titled title at the top level of the manuscript and returns its new id, as one undoable step. Returns "" for an empty title.

Q_INVOKABLE bool ew::app::ScriptWorld::setDocumentBody(const QString &id, const QString &body)

Sets the Markdown body of document id as one undoable step. Returns true when the document exists and the change was applied, false otherwise.

Q_INVOKABLE bool ew::app::ScriptWorld::setDocumentTitle(const QString &id, const QString &title)

Sets the title of document id as one undoable step. Returns true when the document exists and title is non-empty, false otherwise.

Q_INVOKABLE QString ew::app::ScriptWorld::createCategory(const QString &name)

Creates a root codex category named name and returns its new id, as one undoable step. Returns "" for an empty name.