← C++

C++ · 07 / 24

Map editing, undo/redo and safe project files

Trace an editor draft through changes, undo/redo and a verified file round-trip.

  • Large
  • Advanced
  • 120 min

Prerequisites: Headers, CMake and first unit tests, Your first Qt interface with signals and slots

In this tutorial
  1. Prepare the source snapshot
  2. Read the document model
  3. Separate history from saved state
  4. Inspect the repository
  5. Execute the round-trip
  6. Inspect the verification
  7. Check the complete editor
  8. Exercise and solution
  9. Project context and sources

Download learning package

Setup and verification

GCC with C++20 and CMake 3.25 or newer, Qt 6.4 or newer. Python 3 is also required for the common verification entry point. Extract the learning package into a new folder and run python3 run_checks.py there. The script copies the included files into a temporary learning directory. It verifies the example and then the supplied solution there, preserving the original files. Required packages are downloaded on the first run.

Set CMAKE_PREFIX_PATH to your Qt installation if CMake cannot find Qt. Required FactoryForge source files are already included under vendor.

Verified on 2026-10-21 on Linux x86_64. Save and load in a temporary directory. The solution checks dirty, undo and preservation of the draft after a failed load.

This lesson connects the interface to the complete application layer. Its small example does not implement a second editor. It uses the same Document and repository classes as the graphical FactoryForge editor. Download the complete source ZIP from the project page before building it.

An editor draft and a running simulation are different states. Document owns the starting layout. Changes produce project values for its history. A saved comparison value identifies unsaved work. The simulation later starts from an independent copy. Moving vehicles therefore cannot silently change the saved map layout.

Package contents and individual files

01Prepare the source snapshot

Extract the learning package. The required FactoryForge sources are included under vendor from the linked pinned revision. Run cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug and cmake --build build. This standalone check does not require an additional full project download.

CMakeLists.txt · cmakeOpen file
cmake_minimum_required(VERSION 3.25)
project(DocumentLesson LANGUAGES CXX)
set(CMAKE_CXX_STANDARD 20)
get_filename_component(FACTORYFORGE_SOURCE_DIR "${CMAKE_CURRENT_SOURCE_DIR}/vendor/factory-forge" ABSOLUTE CACHE)
find_package(Qt6 6.4 REQUIRED COMPONENTS Core)
add_executable(lesson main.cpp
  "${FACTORYFORGE_SOURCE_DIR}/src/core/project.cpp"
  "${FACTORYFORGE_SOURCE_DIR}/src/core/pathfinder.cpp"
  "${FACTORYFORGE_SOURCE_DIR}/src/core/puzzles.cpp"
  "${FACTORYFORGE_SOURCE_DIR}/src/application/document.cpp"
  "${FACTORYFORGE_SOURCE_DIR}/src/data/json_project_repository.cpp")
target_include_directories(lesson PRIVATE "${FACTORYFORGE_SOURCE_DIR}/include")
target_link_libraries(lesson PRIVATE Qt6::Core)

02Read the document model

The example creates a repository and Document. replace establishes a verified puzzle solution as the starting state. edit takes a change operation and first works on a copy. A failed edit does not modify the existing draft. The graphical editor applies the same principle to grid tools and settings.

main.cpp · cppOpen file
#include "factory/application/document.h"
#include "factory/core/puzzles.h"
#include "factory/data/json_project_repository.h"
#include <QCoreApplication>
#include <QTemporaryDir>
#include <iostream>
int main(int argc, char **argv) {
  QCoreApplication app(argc, argv);
  auto repository = std::make_shared<factory::JsonProjectRepository>();
  factory::Document document(repository);
  document.replace(factory::makePuzzle(0, true));
  document.edit(
      [](factory::Project &project) { project.name = "Warehouse experiment"; });
  document.undo();
  document.redo();
  QTemporaryDir directory;
  if (!directory.isValid())
    return 1;
  const auto path = directory.filePath("example.factoryforge").toStdString();
  document.save(path);
  document.load(path);
  std::cout << "project=" << document.project().name << '\n';
  std::cout << std::boolalpha << "dirty=" << document.dirty() << '\n';
}

Run / check

cmake -S . -B build -G Ninja -DFACTORYFORGE_SOURCE_DIR=/path/to/factory-forge
cmake --build build
./build/lesson

03Separate history from saved state

undo moves the history cursor back and redo moves it forward. A fresh edit after undo discards the incompatible redo branch. dirty compares the current project value with the last successfully saved value. Counting keystrokes since saving would incorrectly report the case where undo returns to that saved state.

04Inspect the repository

ProjectRepository declares load and save without depending on Qt. JsonProjectRepository handles JSON and QSaveFile. It validates the format version, dimensions, data types and unique IDs before accepting a file. Drafts may be incomplete. Before play, preflight additionally checks goals, budgets and reachable connections.

05Execute the round-trip

The example writes inside QTemporaryDir. This isolated temporary directory is unrelated to personal project files and is removed after execution. save updates the saved comparison value only after writing succeeds. load adopts only a completely read project. Configure, build and run using the commands below main.cpp.

Expected result

project=Warehouse experiment dirty=false

06Inspect the verification

Save and load in a temporary directory. The solution checks dirty, undo and preservation of the draft after a failed load.Run python3 run_checks.py from the extracted package. Compare the test expectations with the exercise before opening the solution.

Expected result

The example and automated solution pass. The stated manual checks remain separate.

07Check the complete editor

Start the app, draw a road, undo it and redo the change. Save, reopen and compare the stations. Type a new name in a custom map and cancel closing. Both input and the draft must remain available. Desktop and repository tests verify those promises.

Your exercise

Change the name again after saving. Check dirty, undo the new change and check it again. Then attempt to load a missing file.

Show the solution and explanation

The additional change makes dirty true. Undo returns to the saved project value and dirty becomes false. A failed load raises an error before replace is called. Catch the error and confirm that the previous name remains available. Keep using the isolated temporary directory rather than personal files.

solution/main.cpp · cppOpen file
#include "factory/application/document.h"
#include "factory/core/puzzles.h"
#include "factory/data/json_project_repository.h"
#include <QCoreApplication>
#include <QTemporaryDir>
#include <cassert>
#include <iostream>
int main(int argc, char **argv) {
  QCoreApplication app(argc, argv);
  auto repository = std::make_shared<factory::JsonProjectRepository>();
  factory::Document document(repository);
  document.replace(factory::makePuzzle(0, true));
  document.edit(
      [](factory::Project &project) { project.name = "Warehouse experiment"; });
  document.undo();
  document.redo();
  QTemporaryDir directory;
  if (!directory.isValid())
    return 1;
  const auto path = directory.filePath("example.factoryforge").toStdString();
  document.save(path);
  document.load(path);
  assert(!document.dirty());
  document.edit([](factory::Project &project) { project.name = "Changed"; });
  assert(document.dirty());
  document.undo();
  assert(!document.dirty());
  try {
    document.load(path + ".missing");
    return 2;
  } catch (const std::exception &) {
  }
  assert(document.project().name == "Warehouse experiment");
  std::cout << "project=" << document.project().name << '\n';
  std::cout << std::boolalpha << "dirty=" << document.dirty() << '\n';
}

Project context and sources

The first six examples are standalone teaching programs. Lessons 7 through 9 use the complete FactoryForge source snapshot. Code, exercises and verified simplifications are explained separately. The project page provides a source ZIP while the GitHub repository is not yet published.