You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
# <imgstyle="vertical-align:middle;margin-right:10px;"width="100"alt="Calm"src="docs/images/calm.png"> C A L M
2
2
3
3
[](https://github.com/VitoVan/calm/actions/workflows/calm.yml)[](#pre-built-binary)[](https://github.com/VitoVan/calm/releases/latest)
4
4
5
-
A Lisp development environment that enables you to build and distribute canvas based applications as Linux AppImage, macOS Application Bundle, Windows Installer and Web Application.
6
-
7
-
CALM down and draw something, in Lisp.
5
+
**C**anvas **A**ided **L**isp **M**agic: Create canvas-based applications with Lisp and distribute them on Linux, macOS, Windows, and the web.
8
6
9
7
## Hello World
10
8
11
-
Find whatever directory, create a file: **canvas.lisp**
9
+
Find whatever directory, and create a file: **canvas.lisp**
Source files and binaries for the above examples are [here](https://github.com/VitoVan/calm/tree/main/docs/examples) and [here](https://github.com/VitoVan/calm/releases/tag/examples-0.1.3).
37
+
Source files and binaries for the above examples are [here](https://github.com/VitoVan/calm/tree/main/docs/examples) and [here](https://github.com/VitoVan/calm/releases/tag/1.0.1).
40
38
41
-
For more applications made with CALM, please check:[Made with CALM](https://github.com/VitoVan/made-with-calm).
39
+
For more applications made with CALM, please check [Made with CALM](https://github.com/VitoVan/made-with-calm).
@@ -86,7 +84,7 @@ This command will generate different packages on different platforms:
86
84
87
85
>**Note**
88
86
>
89
-
>DMG creation is powered by [create-dmg](https://github.com/create-dmg/create-dmg), will be installed by `brew install create-dmg` if it were not present. So if you don't have create-dmg, this will install create-dmg for you.
87
+
>DMG creation is powered by [create-dmg](https://github.com/create-dmg/create-dmg) and will be installed by `brew install create-dmg` if it were not present. So if you don't have create-dmg, this will install create-dmg for you.
90
88
>
91
89
>And, if you don't have [Homebrew](https://brew.sh/), this will also install Homebrew for you.
92
90
>
@@ -98,7 +96,7 @@ This command will generate different packages on different platforms:
98
96
99
97
> **Note**
100
98
>
101
-
> Installer creation is powered by [NSIS](https://nsis.sourceforge.io/), will be installed by `winget install nsis` if it were not present. So if you don't have NSIS (i.e., `makensis`) under your PATH, this will install NSIS for you.
99
+
> Installer creation is powered by [NSIS](https://nsis.sourceforge.io/) and will be installed by `winget install nsis` if it were not present. So if you don't have NSIS (i.e., `makensis`) under your PATH, this will install NSIS for you.
102
100
>
103
101
> And, if you don't have [winget](https://github.com/microsoft/winget-cli) under your PATH, this will also install winget for you.
104
102
>
@@ -116,7 +114,7 @@ For more, please refer to the [Command Reference](#command-reference).
116
114
117
115
# CALM - References
118
116
119
-
From CALM 1.0.0, the version number will follow [Semantic Versioning Specification](https://semver.org/spec/v2.0.0.html). This means you can use CALM calmly without worrying me being crazy. Because whenever I'm going to be crazy, I will let you know [before anything got changed](https://semver.org/spec/v2.0.0.html#spec-item-7) and bump the major version if [anything could surprise](https://semver.org/spec/v2.0.0.html#spec-item-8) you.
117
+
From CALM 1.0.0, the version number will follow [Semantic Versioning Specification](https://semver.org/spec/v2.0.0.html). This means you can use CALM calmly without worrying about me being crazy. Because whenever I'm going to be crazy, I will let you know [before anything got changed](https://semver.org/spec/v2.0.0.html#spec-item-7) and bump the major version if [anything could surprise](https://semver.org/spec/v2.0.0.html#spec-item-8) you.
120
118
121
119
Keep CALM and have fun.
122
120
@@ -126,9 +124,9 @@ Keep CALM and have fun.
126
124
127
125
You should run this command inside your project directory, where the file **canvas.lisp** should exist.
128
126
129
-
This command will load **canvas.lisp** and show a window according to the instructions of the function `draw` or `draw-forever`. The file **canvas.lisp** is just a regular Lisp source file, you do what ever you like in it.
127
+
This command will load **canvas.lisp** and show a window according to the instructions of the function `draw` or `draw-forever`. The file **canvas.lisp** is just a regular Lisp source file, you do whatever you like in it.
130
128
131
-
For CALMrelated functions and parameters, please refer to the [API Reference](#api-reference).
129
+
For CALM-related functions and parameters, please refer to the [API Reference](#api-reference).
132
130
133
131
### `calm hello`
134
132
@@ -150,7 +148,7 @@ You will have the following files and directories created:
150
148
└── fonts.conf
151
149
```
152
150
153
-
Files put into **assets** and **fonts**directory will be packed with your application during distribution. If you put your favourite font into **fonts** directory, you will be able to use it inside your application.
151
+
Files put into **assets** and **fonts**directories will be packed with your application during distribution. If you put your favorite font into the**fonts** directory, you will be able to use it inside your application.
154
152
155
153
For more about font usage, please refer to the [API Reference](#api-reference).
156
154
@@ -162,13 +160,13 @@ This command will generate:
162
160
- macOS Application Bundle inside DMG
163
161
- Windows Application Installer
164
162
165
-
according to the platform it were running on.
163
+
according to the platform it was running on.
166
164
167
165
It does not take any arguments, but some options could be set through the environment variables, please check `calm publish-with-options` for the option details.
168
166
169
167
### `calm publish-with-options`
170
168
171
-
This command will do the same thing as `calm publish`, instead it will ask your opinions on all the customisable options (with a default value provided, don't worry), respectively:
169
+
This command will do the same thing as `calm publish`, instead it will ask your opinions on all the customizable options (with a default value provided, don't worry), respectively:
@@ -187,7 +185,7 @@ If you have provided the corresponding environment variable, the option will not
187
185
188
186
### `calm publish-web`
189
187
190
-
This command will generate a **web** directory containing all the necessary materials for you to serve it on the internet. The common usage could be like:
188
+
This command will generate a **web** directory containing all the necessary materials for you to serve it on the internet. The common usage could be like this:
191
189
192
190
```bash
193
191
cd my-cool-app
@@ -224,14 +222,14 @@ This command works like `calm publish-with-options` except it's for `calm publis
| LISP_FILES | Code like `(load "shape.lisp")` may cause problem for the web application, since JSCL will try to load that file via HTTP requests. <br/>If you need to include the extra files other than **canvas.lisp**, please modify your code to bypass JSCL, for example: `#-jscl (load "shape.lisp")` and then set this option, such as: `("/abs/path/to/canvas.lisp" "/abs/path/to/shape.lisp")`. Please remember to escape the double quotes if you're going to set the ENV. |
228
-
| REBUILD_WASM_P | By default WebAssembly files were not built locally, they were downloaded from the [CALM Releases](https://github.com/VitoVan/calm/releases/): **calm.tar**. This prebuilt WebAssembly binary bundled with [OpenSan-Regular.ttf](https://github.com/googlefonts/opensans/raw/main/fonts/ttf/OpenSans-Regular.ttf) and [exposed all the Cairo and SDL2 APIs](https://github.com/VitoVan/calm/blob/main/s/usr/web/wasm.lisp#L61) mentioned in the below [API Reference](#api-reference) section.<br/> If you need to bundle other **fonts** or **assets**, or you need expose more C APIs be exposed to the web, please set this option to "yes". <br/>Caution: Building WebAssembly binaries involves a whole lot of dependencies, to simplify this progress, I irresponsibly utilised docker. So, please make sure you have the `docker` command at your disposal.<br/>Default: "no" |
225
+
| LISP_FILES | Code like `(load "shape.lisp")` may cause problems for the web application, since JSCL will try to load that file via HTTP requests. <br/>If you need to include the extra files other than **canvas.lisp**, please modify your code to bypass JSCL, for example: `#-jscl (load "shape.lisp")` and then set this option, such as: `("/abs/path/to/canvas.lisp" "/abs/path/to/shape.lisp")`. Please remember to escape the double quotes if you're going to set the ENV. |
226
+
| REBUILD_WASM_P | By default WebAssembly files were not built locally, they were downloaded from the [CALM Releases](https://github.com/VitoVan/calm/releases/): **calm.tar**. This prebuilt WebAssembly binary bundled with [OpenSan-Regular.ttf](https://github.com/googlefonts/opensans/raw/main/fonts/ttf/OpenSans-Regular.ttf) and [exposed all the Cairo and SDL2 APIs](https://github.com/VitoVan/calm/blob/main/s/usr/web/wasm.lisp#L61) mentioned in the below [API Reference](#api-reference) section.<br/> If you need to bundle other **fonts** or **assets**, or you need to expose more C APIs be exposed to the web, please set this option to "yes". <br/>Caution: Building WebAssembly binaries involves a whole lot of dependencies, to simplify this progress, I irresponsibly utilized docker. So, please make sure you have the `docker` command at your disposal.<br/>Default: "no" |
229
227
230
228
Since JSCL is the backbone of CALM on the web, any change of JSCL will be considered as a change of CALM itself. The code base of JSCL used by each version of CALM is fixed, it won't change unless you update CALM. Please feel safe to use it.
231
229
232
230
### API Reference
233
231
234
-
CALM intended to be a thin layer above [SDL2](https://wiki.libsdl.org/SDL2/FrontPage), [Cairo](https://www.cairographics.org/) and some other things. So the number of APIs provided by CALM is intended to be as small as possible.
232
+
CALM is intended to be a thin layer above [SDL2](https://wiki.libsdl.org/SDL2/FrontPage), [Cairo](https://www.cairographics.org/), and some other things. So the number of APIs provided by CALM is intended to be as small as possible.
235
233
236
234
#### Fundamentals
237
235
@@ -250,15 +248,15 @@ This is the entry function for a CALM application, it will be called once the ap
250
248
(c:fill-path))
251
249
```
252
250
253
-
This function will be called passivly. That is to say, this function won't be called again after the first call, unless any event has been triggered by the user, such as: mouse motion, keydown, keyup, mousebuttondown, etc.
251
+
This function will be called passively. That is to say, this function won't be called again after the first call, unless any event has been triggered by the user, such as mouse motion, key down, key up, mouse button down, etc.
254
252
255
253
If you want to continually refresh the canvas without user interaction, you should use `draw-forever`.
256
254
257
-
Note: Functions like `c:arc` are thirdparty APIs exposed by CALM. Please refer to [Drawing on Canvas](#drawing-on-canvas) for more info.
255
+
Note: Functions like `c:arc` are third-party APIs exposed by CALM. Please refer to [Drawing on Canvas](#drawing-on-canvas) for more info.
258
256
259
257
#### Function `draw-forever`
260
258
261
-
This is also the entry function for a CALM application, just like `draw`, so please DON NOT define both of them, the consequence of having both `draw` and `draw-forever`is equivalent to killing John Wick's dog.
259
+
This function also serves as the entry point for a CALM application, similar to the `draw` function. It is important to avoid defining both `draw` and `draw-forever`as doing so would have severe consequences, comparable to killing John Wick's dog.
262
260
263
261
This function will be called every `*calm-delay*` milliseconds, regardless of user interaction.
264
262
@@ -268,15 +266,15 @@ This variable controls how many milliseconds CALM should wait before refreshing
268
266
269
267
Default: 42
270
268
271
-
This variable only works on desktop, for web platform, please check `*calm-fps*`.
269
+
This variable only works on the desktop platform, for the web platform, please check `*calm-fps*`.
272
270
273
271
#### Variable `*calm-fps*`
274
272
275
273
This variable controls how many milliseconds CALM should wait before refreshing the canvas. Setting 0 will use the browser’s `requestAnimationFrame` mechanism to refresh the canvas.
276
274
277
275
Default: 42
278
276
279
-
This variable only works on the web, for desktop platform, please check `*calm-delay*`.
277
+
This variable only works on the web, for the desktop platform, please check `*calm-delay*`.
280
278
281
279
#### Drawing on Canvas
282
280
@@ -304,7 +302,7 @@ is equivalent to
304
302
305
303
All the symbols [exported by cl-cairo2](https://github.com/rpav/cl-cairo2/blob/master/src/package.lisp#L7-L142) should be accessible through `c:` prefix, such as: `c:arc`. On the web, the accessible symbols are limited by [cairo.lisp](https://github.com/VitoVan/calm/blob/main/src/web/cairo.lisp#L266-L405).
306
304
307
-
Since Cairo is the cardinal drawing facility of CALM, any change of Cairorelated symbols will be considered as a change of CALM itself. Please feel safe to use them.
305
+
Since Cairo is the cardinal drawing facility of CALM, any change of Cairo-related symbols will be considered as a change of CALM itself. Please feel safe to use them.
308
306
309
307
#### Function `c:rrectangle`
310
308
@@ -359,7 +357,7 @@ This function is not exposed to the web due to the following reasons:
359
357
360
358
1. Pango requires multi-threading, which requires extra [HTTP HEADERS](https://web.dev/coop-coep/) to be set
361
359
2. Compiling Pango into WebAssembly will increase the time and data for loading
362
-
3. Using Pango often involves extra fonts to be bundle, this will cause more data to be loaded
360
+
3. Using Pango often involves extra fonts to be bundled, this will cause more data to be loaded
363
361
364
362
So I don't think this is a good idea to include Pango by default, albeit it is easy to implement.
365
363
@@ -369,7 +367,7 @@ So I don't think this is a good idea to include Pango by default, albeit it is e
369
367
370
368
Play a wav file.
371
369
372
-
If `c:play-wav` were called before, and the previous wav file were still playing, the sound will be merged together.
370
+
If `c:play-wav` were called before, and the previous wav file was still playing, the sound will be merged together.
@@ -395,7 +393,7 @@ Set the volume of `c:play-wav`.
395
393
(c:volume-wav 128 :channel -1)
396
394
```
397
395
398
-
The value should between 0 (silence) and 128.
396
+
The value should be between 0 (silence) and 128.
399
397
400
398
Set `:channel` to -1 means all channels.
401
399
@@ -411,15 +409,15 @@ Set `:channel` to -1 means all channels.
411
409
412
410
#### Function `c:play-music`
413
411
414
-
Play a music file, it is able to play MP3, Ogg, and WAV.
412
+
Play a music file, it can play MP3, Ogg, and WAV.
415
413
416
414
Other types of files might also work, but they are not guaranteed by CALM.
417
415
418
416
```lisp
419
417
(c:play-music "assets/bgm.ogg" :loops 0)
420
418
```
421
419
422
-
If `c:play-music` were called before, and the previous music were still playing, it will be stopped and the latest music will start playing.
420
+
If `c:play-music` were called before, and the previous music was still playing, it will be stopped and the latest music will start playing.
423
421
424
422
#### Function `c:volume-music`
425
423
@@ -429,21 +427,21 @@ Set the volume of `c:play-music`.
429
427
(c:volume-music 128)
430
428
```
431
429
432
-
The value should between 0 (silence) and 128.
430
+
The value should be between 0 (silence) and 128.
433
431
434
432
#### Function `c:halt-music`
435
433
436
434
Stop playing music.
437
435
438
436
#### Function `c:play-audio`
439
437
440
-
Play an audio file, this function is only available on the web, since it utilise the [HTMLAudioElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLAudioElement).
438
+
Play an audio file, this function is only available on the web since it utilizes the [HTMLAudioElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLAudioElement).
@@ -474,15 +472,15 @@ If call it without any arguments, it stops all the playing audio.
474
472
475
473
#### Variable `*calm-state-finger-just-tapped*`
476
474
477
-
The above variables hold the state of mouse and finger (touch device, like the mobile web browser), they are readonly. The consequence of `(setf *calm-state-mouse-x* 20)` is equivalent to drinking bleach.
475
+
The above variables hold the state of the mouse and finger (touch device, like the mobile web browser), they are read-only. The consequence of `(setf *calm-state-mouse-x* 20)` is equivalent to drinking bleach.
478
476
479
477
#### Function `c:get-ticks`
480
478
481
479
This is just [SDL_GetTicks](https://wiki.libsdl.org/SDL2/SDL_GetTicks).
482
480
483
481
#### Event Callbacks
484
482
485
-
These callbacks are functions that you should define. If you defined any of them, they will be called when the corresponding event being triggered.
483
+
These callbacks are functions that you should define. If you defined any of them, they will be called when the corresponding event was triggered.
486
484
487
485
#### Callback `on-keydown`
488
486
@@ -492,7 +490,7 @@ You know what these callbacks do, what you don't know is their should-be argumen
492
490
493
491
#### Function `c:keq`
494
492
495
-
This function compares the first argument with a infinite number of SDL2 Scancodes, if any of them matched, it will return `T`.
493
+
This function compares the first argument with an infinite number of SDL2 Scancodes, if any of them matched, it will return `T`.
496
494
497
495
```lisp
498
496
(defun on-keyup (key) ;; keyup handler for evil vimers
0 commit comments