Editing and history

​

What a session does with a command

​

Send a command

import type { BuildingSession } from '@opengeometry/floorkit';

export function moveDoor(session: BuildingSession): void {
  session.apply(
    {
      kind: 'move-hosted-opening',
      buildingId: 'building',
      storeyId: 'ground',
      wallId: 'room-walls',
      openingId: 'entry-door',
      offset: 2.5,
    },
    session.revision,
  );
}

​

The commands

​

Add, replace and remove

import type { BmColumn } from '@opengeometry/floorkit';

export function replaceColumn(session: BuildingSession, column: BmColumn): void {
  session.apply(
    {
      kind: 'replace-element',
      buildingId: 'building',
      storeyId: 'ground',
      list: 'columns',
      elementId: column.id,
      element: column,
    },
    session.revision,
  );
}

• An add with an id that exists: an element in its list, an asset in the model, a storey in its building.
• A replace or a remove with an id that does not exist.
• A replace-element whose new element has a different id.
• A remove-asset of an asset that an instance uses.
• A remove-storey of the last storey of a building.
• A replace-mass that removes a storey that holds an element.
• An add-building with an id that any object of the model has, and a remove-building of the last building.
• A replace-site with no site when the model has none.

​

Doors and windows in walls

import {
  resolveViewEditCandidate,
  type DrawingSourceRef,
  type ViewDrag,
  type ViewFrame,
} from '@opengeometry/floorkit';

export function dragDoor(
  session: BuildingSession,
  frame: ViewFrame,
  hit: DrawingSourceRef,
  drag: ViewDrag,
): void {
  const revision = session.revision;
  const command = resolveViewEditCandidate(
    session.snapshot(),
    frame,
    hit,
    drag,
    { kind: 'along-host-wall' },
    session.currentBuild,
  );
  session.apply(command, revision);
}

​

A batch of commands

export function addColumns(session: BuildingSession, columns: BmColumn[]): void {
  session.apply(
    {
      kind: 'batch',
      commands: columns.map((column) => ({
        kind: 'add-element',
        buildingId: 'building',
        storeyId: 'ground',
        list: 'columns',
        element: column,
      })),
    },
    session.revision,
  );
}

• A batch is all or nothing. If one command fails, apply throws the error of that command and the session changes nothing. The message starts with the place of the command, such as command 3 of 6:.
• If one command has a wrong field or an unknown kind, the code is invalid-command, and the message starts with the place of the command too.
• Each command works on the result of the commands before it. Thus a batch can add a storey and then add an element to that storey.
• The model must be valid after each command, not only after the last one. For example, in a building with a mass, two commands change the heights of two storeys, and the storeys fit the mass only after the second command. The session rejects this batch at the first command.
• The rules of each command stay the same in a batch. For example, a remove-asset of an asset that an instance uses fails.
• A batch must have one command or more, and it cannot hold a batch. In TypeScript, a batch in a batch does not compile. A list with the type BuildingEditCommand[] does not go into a batch, because that type permits a batch. Give the list the type of its commands, such as ElementListCommand[], or the type BatchCommand['commands'].
• session.lastEditCommand gives the batch.

​

The revision number

​

Undo and redo

export function undoLast(session: BuildingSession): void {
  if (session.canUndo) session.undo(session.revision);
}

export function redoLast(session: BuildingSession): void {
  if (session.canRedo) session.redo(session.revision);
}

​

Keep an edit fast

• Send one command through apply for one change of the user. If the change needs several commands, send one batch. After a command for one slab, roof, room, stair, column, beam, railing, block instance, loose door, loose window or basic shape, Floorkit builds again only that element. The other elements of the storey keep their geometry. After a command for a wall, or for a door or window in a wall, Floorkit joins the walls of the storey again and builds again only the walls, doors and windows that changed. A command that adds a storey or changes its settings builds that storey. A command that changes an asset, or the settings of a storey in a building with a mass, builds the whole building again. A batch builds again what its commands build, one time.
• Do not call session.snapshot(), manager.snapshot(), manager.save(), saveProject, new BuildingSession(model), drawProjectView or an export at each edit or at each frame of a drag. Each of them copies, writes or builds the whole model. Save on an action of the user or on a timer.
• Do not open a new session for a change that a command covers, as replaceBuilding in Start a building does. A new session builds the whole building and has an empty undo history. Open one to load or replace a whole building.
• Read the new revision from what apply returns, and read the built element from session.currentBuild.elementsById. Do not keep an element object across a change: read the element again by its id after each change. A changed slab, roof, stair, column, beam, railing, space, basic shape, block or loose door or window is a new object, and Floorkit disposes the old object. A changed wall, and a door, a window or a hole on a wall, can stay the same object with new geometry, or can be a new object. Do not call snapshot() to see the result. snapshot() copies the whole model.
• After a change, refresh only what the event names. The event of session.subscribe and of manager.subscribe has changed: the ids of the built elements that the step built again, added or removed. An element that the list does not name keeps its object. Read each id from session.currentBuild.elementsById, or from session.currentBuild.modelObjectsById for a basic shape. An id that is in neither map was removed. If changed is absent, the whole building was built again: refresh all.
• When a step fails, the model and the revision stay as they were. If the failed step already changed built elements, Floorkit builds them again from the saved model and sends one event with the kind restore (the cause restore from the manager) and with changed. Refresh these elements as after a step.

​

Doors and windows follow their wall

​

Interactive editors