Skip to content

Commit

Permalink
docs(readme): add section Deeper concepts
Browse files Browse the repository at this point in the history
  • Loading branch information
robertrosman committed May 30, 2024
1 parent 153f51e commit 080c0a1
Showing 1 changed file with 35 additions and 1 deletion.
36 changes: 35 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,41 @@ Create your own tools if you want to extend the library.
Written in Typescript and fully typed.


## Project Setup
## Deeper concepts

### Tools

vue-paint provides a bunch of tools that you can import. Only the tools imported will be available in the editor. Every tool may or may not produce a shape that is pushed to the [history](#history).
A shape is a plain javascript object that keeps all information needed about that specific action. The shapes can then be rendered by the tool if it is providing a shapeSvg component. Some tools
may not render a component for every shape, but rather one per history. Take the crop tool for example, where it makes sense to only render one crop overlay per image. It is therefor providing a
toolSvg component instead to handle that scenario once.

Note that you need to import the same tools every time you edit an image, otherwise there would be no way to render the shapes that might have already been pushed to the history.

### History

The history of an image is basically every shape and action the user has made to the image in a sequence. So to undo a shape, you just pop the last item of the history array. This also means you can
push any new shapes or actions to the history programmatically like `history.push({ type: 'eraser', id: 'eraseline', targets: ['ka9v1sl'] })` (which will erase a shape earlier in the history with id ka9v1sl).
Since the user might want to undo the erase, it is actually just a new object pushed to the history that can be undone. The eraser tool is then responsible to do the actual cleanup in it's simplifyHistory
method. So if you ever want the simplified version of a history (where deleted shapes are actually removed, and moved objects are actually moved, and so on), you can use the composable useSimplifiedHistory like so:
```
const simplifiedHistory = useSimplifiedHistory({ history, tools, activeShape, includeActiveShape: false })
```

Each editor writes to and reads from your ImageHistory, which is passed to the editor with `v-model:history="history"`. If you don't want the image to be editable, you can pass the history to the component VpImage
like this instead `<vp-image :history="history" :tools="tools" :width="1280" :height="720" />`.

### Settings

The editor needs a settings object to work properly. This object contains information about the selected tool, current color and thickness. These values can be changed by the user through the toolbar,
or programmatically by changing the values respectively. Note that changing the settings does not affect the [history](#history) of the image, only new shapes.

### Theming

To use the default theme you can import it like `import "vue-paint/themes/default.css"`. There's not that much styling going on, most of it relates to the toolbar. More themes are welcome, just open a PR!
If you want to skip the theme completely and write your own css, that's of course an option as well.

## Development

```sh
npm install
Expand Down

0 comments on commit 080c0a1

Please sign in to comment.