mirror of
https://github.com/scratchfoundation/scratch-paint.git
synced 2024-12-22 13:32:28 -05:00
Update the readme
This commit is contained in:
DD
parent
efe30ec50d
commit
35ca4ea58e
1 changed files with 63 additions and 34 deletions
97
README.md
97
README.md
|
|
@ -1,44 +1,73 @@
|
|||
# scratch-paint
|
||||
#### Scratch paint provides a React component which is a vector paint editor. It is very much still under construction!
|
||||
#### Scratch-paint provides a vector paint editor React component that takes and outputs SVGs. It is now in beta!
|
||||
- Try it out at [https://llk.github.io/scratch-paint/](https://llk.github.io/scratch-paint/)
|
||||
|
||||
- Or, to try it out as part of Scratch 3.0, visit [https://preview.scratch.mit.edu/](https://preview.scratch.mit.edu/)
|
||||
|
||||
### Installation
|
||||
This requires you to have Git and Node.js installed.
|
||||
It will be easiest if you develop on Mac or Linux. If you are using Windows, I recommend using Ubuntu on Windows, which will allow you to use Linux commands on Windows. You will need administrator permissions.
|
||||
|
||||
In your own node environment/application:
|
||||
- https://docs.microsoft.com/en-us/windows/wsl/install-win10
|
||||
|
||||
Scratch Paint requires you to have Git and Node.js installed. See:
|
||||
- [https://git-scm.com/book/en/v2/Getting-Started-Installing-Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
|
||||
- [https://nodejs.org/en/download/](https://nodejs.org/en/download/)
|
||||
|
||||
If you want to use scratch-paint in your own Node environment/application, add it with:
|
||||
```bash
|
||||
npm install https://github.com/LLK/scratch-paint.git
|
||||
npm install scratch-paint
|
||||
```
|
||||
If you want to edit/play yourself:
|
||||
If you want to edit scratch-paint, or help contribute to our open-source project, fork the [scratch-paint repo](https://github.com/LLK/scratch-paint). Then:
|
||||
```bash
|
||||
git clone https://github.com/LLK/scratch-paint.git
|
||||
git clone https://github.com/<YOUR_GITHUB_USERNAME>/scratch-paint.git
|
||||
cd scratch-paint
|
||||
npm install
|
||||
```
|
||||
|
||||
## Playground
|
||||
This requires Node.js to be installed.
|
||||
### Running locally (stand-alone)
|
||||
You can try out your own copy of the paint editor by running the development server.
|
||||
|
||||
Run the paint editor independent of Scratch by running the development server.
|
||||
Open a Command Prompt or Terminal in the repository and run:
|
||||
In the cloned `scratch-paint` directory, run:
|
||||
```bash
|
||||
npm start
|
||||
```
|
||||
|
||||
Then go to [http://localhost:8078/playground/](http://localhost:8078/playground/). 8078 is BLOB upside-down.
|
||||
Then go to [http://localhost:8078/playground/](http://localhost:8078/playground/). 8078 is BLOB upside-down. The True Name of this repo is scratch-blobs.
|
||||
|
||||
Code for the playground is in `scratch-paint/src/playground/playground.jsx`. You can change the SVG vector that is passed in, and `onUpdateSvg`, which is called with the new SVG each time the vector drawing is edited.
|
||||
### Running locally (as part of Scratch)
|
||||
So you've tried out your edits in the playground and they look good. You should now test with the rest of Scratch, to make sure that everything hooks up right, and so that you can use your custom paint editor to make costumes and sprites!
|
||||
|
||||
## How to include in a Node.js App
|
||||
For an example, check out the `scratch-paint/src/playground` directory.
|
||||
Get the rest of Scratch:
|
||||
```bash
|
||||
git clone https://github.com/LLK/scratch-gui.git
|
||||
```
|
||||
Go to your `scratch-paint` folder and run:
|
||||
```bash
|
||||
npm link
|
||||
npm run watch
|
||||
```
|
||||
This runs a file watcher which should automatically recompile scratch-paint if you edit any files.
|
||||
|
||||
In the component:
|
||||
Now in another tab, go back to the `scratch-gui` folder and run
|
||||
```bash
|
||||
npm link scratch-paint
|
||||
npm install
|
||||
npm start
|
||||
```
|
||||
Then go to [http://localhost:8601](http://localhost:8601). 601 is supposed to look like GUI (it's okay, I don't really see it either.) The Costumes tab should be running your local copy of scratch-paint!
|
||||
|
||||
### How to include in your own Node.js App
|
||||
For an example of how to use scratch-paint as a library, check out the `scratch-paint/src/playground` directory.
|
||||
In `playground.jsx`, you can change the SVG vector that is passed in, and edit the handler `onUpdateSvg`, which is called with the new SVG each time the vector drawing is edited.
|
||||
|
||||
In your parent component:
|
||||
```
|
||||
import PaintEditor from 'scratch-paint';
|
||||
...
|
||||
<PaintEditor
|
||||
svg={optionalSvg}
|
||||
rotationCenterX={optionalCenterPointXRelativeToSvg}
|
||||
rotationCenterY={optionalCenterPointYRelativeToSvg}
|
||||
rotationCenterX={optionalCenterPointXRelativeToSvgTopLeft}
|
||||
rotationCenterY={optionalCenterPointYRelativeToSvgTopLeft}
|
||||
onUpdateSvg={handleUpdateSvgFunction}
|
||||
/>
|
||||
```
|
||||
|
|
@ -52,11 +81,21 @@ combineReducers({
|
|||
scratchPaint: ScratchPaintReducer
|
||||
});
|
||||
```
|
||||
Note that scratch-paint expects its state to be in `state.scratchPaint` so the name must be exact.
|
||||
Note that scratch-paint expects its state to be in `state.scratchPaint`, so the name must be exact.
|
||||
|
||||
Scratch paint shares state with its parent component because it expects to share the parent's IntlProvider, which inserts translations into the state. See the intlProvider setup in `scratch-gui` [here](https://github.com/LLK/scratch-gui/blob/f017ed72201bf63334dced161441ef6f154b1c74/src/lib/app-state-hoc.jsx).
|
||||
Scratch-paint shares state with its parent component because it expects to share the parent's `IntlProvider`, which inserts translations into the state. See the `IntlProvider` setup in `scratch-gui` [here](https://github.com/LLK/scratch-gui/blob/f017ed72201bf63334dced161441ef6f154b1c74/src/lib/app-state-hoc.jsx).
|
||||
|
||||
## Testing
|
||||
### Code organization
|
||||
We use React and Redux. If you're just getting started with them, here are some good tutorials:
|
||||
[https://egghead.io/courses/getting-started-with-redux](https://egghead.io/courses/getting-started-with-redux)
|
||||
|
||||
- Under `/src`, our React/Redux code is divided mainly between `components` (presentational components), `containers` (container components), and `reducers`.
|
||||
|
||||
- `css` contains only shared css. Most of the css is stored alongside its component.
|
||||
|
||||
- `helper` contains pure javascript used by the containers. If you want to change how something works, it's probably here. For instance, the brush tool is in `helper/blob-tools/`, and the code that's run when you click the group button is in `helper/group.js`.
|
||||
|
||||
### Testing
|
||||
```bash
|
||||
npm run test
|
||||
```
|
||||
|
|
@ -66,22 +105,12 @@ Just unit tests:
|
|||
npm run unit
|
||||
```
|
||||
|
||||
Individual unit test: (from `scratch-paint` directory)
|
||||
An individual unit test: (run from `scratch-paint` directory)
|
||||
```bash
|
||||
./node_modules/.bin/jest ./test/unit/undo-reducer.test.js
|
||||
```
|
||||
|
||||
## Publishing to GitHub Pages
|
||||
```bash
|
||||
npm run deploy
|
||||
```
|
||||
### Donate
|
||||
We provide [Scratch](https://scratch.mit.edu) free of charge, and want to keep it that way! Please consider making a [donation](https://secure.donationpay.org/scratchfoundation/) to support our continued engineering, design, community, and resource development efforts. Donations of any size are appreciated. Thank you!
|
||||
|
||||
This will push the currently built playground to the gh-pages branch of the
|
||||
currently tracked remote. If you would like to change where to push to, add
|
||||
a repo url argument:
|
||||
```bash
|
||||
npm run deploy -- -r <your repo url>
|
||||
```
|
||||
|
||||
## Donate
|
||||
We provide [Scratch](https://scratch.mit.edu) free of charge, and want to keep it that way! Please consider making a [donation](https://secure.donationpay.org/scratchfoundation/) to support our continued engineering, design, community, and resource development efforts. Donations of any size are appreciated. Thank you!
|
||||
Scratch-paint couldn't exist without [w00dn/papergrapher](https://github.com/w00dn/papergrapher) and [Paper.js](https://github.com/paperjs/paper.js). If you are amazed and/or baffled by the insane boolean operation math that makes the brush and eraser tools possible, please check out and consider contributing to Paper. Thank you!
|
||||
Loading…
Reference in a new issue