JeremyStarTM/Presencode
JeremyStarTM/Presencode
1
0
Fork 0
Code Issues Pull requests Releases Activity

Change wording, fix typos, rewrite docs page

Browse source
This commit is contained in:
JeremyStar™ 2024-01-15 01:06:15 +01:00
parent e158173104
commit 95e9aa4453
13 changed files with 149 additions and 146 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

15
docs/docs/about.md
View file

@ -3,22 +3,22 @@ sidebar_position: 1
---
# About Presencode
Presencode is a code-based presentation program written in [Godot 4](https://godotengine.org).
Presencode is a code-based presentation program written in the [Godot Engine](https://godotengine.org), version 4.
## Why does it exist?
- compatibility issues between *Microsoft Office* and *LibreOffice*/*OpenOffice*
- having images that don't load/are broken most of the time is bad
- presentation designs don't display correctly sometimes
- text colors are always missing/set to black
- text colors are often reset/set to black
- coding is fun
- fonts may not be present on another system
- bundling fonts inside a presentation fixes the missing fonts issue
- i ([JeremyStarTM](https://jstm.staropensource.de)) had nothing to do
## What it does
- load presentations from [.zip archives](https://en.wikipedia.org/wiki/ZIP_(file_format)) and directories
- loads presentations from [.zip archives](https://en.wikipedia.org/wiki/ZIP_(file_format)) and directories
- execute a so called "entrypoint file"
- manage slide navigation
- etc
- etc.
## What it doesn't
- create presentations
@ -37,7 +37,6 @@ Presencode is a code-based presentation program written in [Godot 4](https://god
- free
- open source
- all-in-one package (creator, editor, presenter)
- a bit hard
- requires little learning
- doesn't require coding skills
- compatible with OpenDocument presentations and mostly compatible with Microsoft Office presentations
@ -45,7 +44,6 @@ Presencode is a code-based presentation program written in [Godot 4](https://god
- free
- open source
- all-in-one package (creator, editor, presenter)
- a bit hard
- requires little learning
- doesn't require coding skills
- compatible with OpenDocument presentations and is somewhat compatible with Microsoft Office presentations
@ -54,14 +52,13 @@ Presencode is a code-based presentation program written in [Godot 4](https://god
## Is it for you?
### Pro
If you want something like this:
- developing using GDScript (a Python-like programming language)
- code-controlled presentations
- full control over your presentations
- access to your computer
... then Presencode is something for you!
### Cons
If you however like somthing like this:
If you however like something like this:
- visual editor
- fast and easy editing
- not coding

95
docs/docs/getting-started/example-presentation.md
View file

@ -1,95 +0,0 @@
---
sidebar_position: 3
---
# The example presentation
Setting the presentation up.
## The manifest file
The manifest file is located at `res://example/manifest.json` and contains information about the presentation.
To learn more about the manifest file and it's specification, visit [it's reference page](/reference/manifest-specification).
### Default content
```json
{
"version": 1,
"program": "Presencode",
"topic": "Example presentation",
"authors": [
"JeremyStarTM",
"Contributors"
],
"ratio": "16:9",
"entrypoint": "test.gd"
}
```
### Editing the manifest
Simply edit the `manifest.json` file to your hearts content. Just don't touch `version`, `program` or `entrypoint`. Change `ratio` to `4:3` if you want or leave it at `16:9`.
## The entrypoint script
The entrypoint script is located at `res://example/test.gd` and serves as the presentation controller and... well as the presentation entrypoint. It is responsible for loading all the assets such as images or audio the presentation needs, playing animations, switching slides, etc..
### What it contains
The default entrypoint script contains five functions and three variables.
#### Variable `viewport`
The `viewport` variable holds a reference to the area the presentation controller can use and is set by the function `presentation_start()`
#### Variable `resources_files`
The `resources_files` array holds resource names that will be loaded in `_ready()`. It supports loading `.png` and `.jpg` files by default.
#### Variable `resources`
The `resources` dictionary holds all loaded resources in memory and is empty by default as `_ready()` fills it during runtime.
#### Function `_ready`
This function is called after the entrypoint script has been injected into Presencode. Only use it for stuff you absolutely need to do before registering the presentation controller (such as loading resources). \
Default actions (in order):
- loads all resources from `resource_files` into `resources`
- registers the presentation controller by calling pmana.register() with the following settings:
- entrypoint version: 1
- amount of slides: 3
- animations: disabled
- quit on last slide: no
- presentation controller: itself
#### Function `presentation_start`
This function is called after the Presentation Manager (pmana) has registered the presentation controller and is ready. In this function you can change the presentation settings, switch slides and do anything you couldn't do in `_ready` before. \
Default actions (in order):
- set the `viewport` variable to it's first argument `viewport_`
- hide the background log
- change the slide internally to *slide 0*
#### Function `presentation_end`
This function is called before shutting down Presencode. You can use this function to cleanup temporary files, close opened FileAccess, etc.. \
This function does nothing by default.
#### Function `change_slide`
This function is called by the Presentation Manager to inform the presentation controller to switch it's slide. Do not implement animations here! \
Default actions (in order):
- check for slide number
- slide 0:
- clear the viewport
- create a new NinePatchRect
- set the name of the newly created NinePatchRect to **Educational Meme**
- set the texture of the NinePatchRect to `meme.jpg` from the `resources` array
- set the size to **680x453**
- set the position to **100x50**
- add the NinePatchRect to the viewport
- slide 1:
- clear the viewport
- create a new NinePatchRect
- set the name of the newly created NinePatchRect to **Fox**
- set the texture of the NinePatchRect to `foxxo.jpg` from the `resources` array
- set the size to **400x400**
- set the position to the viewport center (by using `misc.get_center_float()`)
- add the NinePatchRect to the viewport
- slide 2:
- clear the viewport
- invalid slide:
- print error
#### Function `display_end_slide`
This function is called by the Presentation Manager if the `quit_last_slide` argument passed to `pmana.register()` is `false` and the current slide exceeds the maximum amount of slides by one. This function is very similar to what `change_slide` does.\
Default actions (in order):
- clear the viewport
- create a new RichTextLabel
- set the name of the newly created RichTextLabel to **End**
- set the text of the RichTextLabel to **THE END**
- disable scrolling
- set the size of the RichTextLabel to **69x22**
- set the position to the viewport center (by using `misc.get_center_float()`)
- add the RichTextLabel to the viewport
#### Function `animation_switch_away`
This function is not included in the example presentation, but you can visit [it's reference](/reference/controller#animation_switch_away)
#### Function `animation_switch_to`
This function is not included in the example presentation, but you can visit [it's reference](/reference/controller#animation_switch_to)

72
docs/docs/getting-started/writing-a-presentation.md Normal file
View file

@ -0,0 +1,72 @@
---
sidebar_position: 3
---
# Writing a presentation
You can use the example presentation bundled with Presencode's source code or create your own from scratch. \
**Note: *This documentation page is not yet finished.***
## Using the example presentation
### Editing the manifest
Open the `example` directory in the Godot directory view. In it, you should see a directory structure like this:
```plain
.
├── images
│   ├── foxxo.jpg
│   ├── mario.gif
│   ├── meme.jpg
├── manifest.json
└── test.gd
```
Open `manifest.json` and modify the keys `topic`, `authors` and maybe `ratio` too. If you need help, look at the [manifest specification](/reference/manifest-specification).
### Modifying the presentation entrypoint/controller
Now close `manifest.json` and instead open `test.gd`. It serves as the presentation entrypoint and controller. For us relevant is the function `change_slide()` for now. It should look like this:
```gdscript
# Change the current slide to another one
func change_slide(new_slide: int) -> void:
logger.diag("change_slide(new_slide=" + str(new_slide) + ") called")
match(new_slide):
0:
logger.info("Displaying slide about memes")
pmana.clear_viewport()
var npr: NinePatchRect = NinePatchRect.new()
npr.name = "Educational Meme"
npr.texture = resources["meme.jpg"]
npr.size = Vector2(680, 453)
npr.position = Vector2(100, 50)
viewport.add_child(npr)
1:
logger.info("Displaying slide about foxes")
pmana.clear_viewport()
var npr: NinePatchRect = NinePatchRect.new()
npr.name = "Fox"
npr.texture = resources["foxxo.jpg"]
npr.size = Vector2(400, 400)
npr.position = misc.get_center_float(viewport.size, npr.size)
viewport.add_child(npr)
2:
logger.info("Displaying slide about mario")
pmana.clear_viewport()
# var as2d: AnimatedSprite2D = AnimatedSprite2D.new()
# as2d.name = "Mario Melee"
# as2d.sprite_frames = resources["mario.gif"]
# var size: Vector2 = as2d.sprite_frames.get_frame_texture(as2d.sprite_frames.get_animation_names()[0], 0).get_size()
# as2d.position = Vector2(viewport.size.x-size.x, viewport.size.y-size.y)
# viewport.add_child(as2d)
# as2d.play()
_:
logger.error("Invalid slide")
```
There you can see that on slide `0` for example we:
- print `Displaying slide about memes`
- clear the viewport
- create a new NinePatchRect
- name the newly created NinePatchRect as `Educational Meme`
- set the NinePatchRect texture to a `resource` Dictionary key.
- set the size of the NinePatchRect to `400x400`
- set the position of the NinePatchRect to the size of the viewport
- add the NinePatchRect to the viewport
Now edit
## Writing a presentation from scratch

2
docs/docs/reference/_category_.json
View file

@ -3,6 +3,6 @@
"position": 3,
"link": {
"type": "generated-index",
"description": "References to the Presencode API, Manifest Specification and Presentation Controller"
"description": "Presencode API, Manifest, Controller and Debugging console reference"
}
}

2
docs/docs/reference/api/_category_.json
View file

@ -3,6 +3,6 @@
"position": 1,
"link": {
"type": "generated-index",
"description": "References to the Presencode API"
"description": "Presencode API reference"
}
}

2
docs/docs/reference/api/logger.md
View file

@ -1,5 +1,5 @@
---
sidebar_position: 2
sidebar_position: 1
---
# Logger

19
docs/docs/reference/api/misc.md
View file

@ -1,5 +1,5 @@
---
sidebar_position: 4
sidebar_position: 2
---
# Miscellaneous (misc)
@ -17,14 +17,14 @@ Miscellaneous functions that do not fit into other scripts.
- `exitcode`
- type `int`
- mandatory `no`
- description `The exitcode`
- description `DUDE DO YOU DON'T KNOW WHAT A EXITCODE IS?!`
### `get_temporary_dir`
- return type `String`
- description `Return the temporary directory`
- description `Return a temporary directory`
- arguments `none`
### `get_center`
- return type `Vector2i`
- description `Calculates the center of a child inside its parent (Vector2i)`
- description `Calculates the center of a child inside its parent (Vector2i edition)`
- arguments
- `parent_size`
- type `Vector2i`
@ -36,7 +36,7 @@ Miscellaneous functions that do not fit into other scripts.
- description `The size of the child object`
### `get_center_float`
- return type `Vector2`
- description `Calculates the center of a child inside its parent (Vector2)`
- description `Calculates the center of a child inside its parent (Vector2 edition)`
- arguments
- `parent_size`
- type `Vector2`
@ -48,13 +48,16 @@ Miscellaneous functions that do not fit into other scripts.
- description `The size of the child object`
### `clear_viewport`
- return type `void`
- description `Convenience function: Clears the presentation viewport for you.`
- description `Clears the presentation viewport`
- arguments `none`
### `hide_log`
- return type `void`
- description `Hides the log output in the background`
- description `Hides log output`
- arguments `none`
### `show_log`
- return type `void`
- description `Unhides the log output in the background`
- description `Unhides log output`
- arguments `none`
### `shutdown`
- return type `void`
- description `Ends the presentation and shuts Presencode down`

16
docs/docs/reference/api/pmana.md
View file

@ -1,5 +1,5 @@
---
sidebar_position: 1
sidebar_position: 3
---
# Presentation Manager (pmana)
@ -29,7 +29,7 @@ Handles interactions between Presencode and the active presentation file.
- `quit_last_slide`
- type `bool`
- mandatory `yes`
- description `If Presencode should shutdown once you surpass "slides" (your amount of slides), set to false if you want to display a end slide instead`
- description `If Presencode should shutdown once you surpass your amount of slides, set to false if you want to display a end slide instead.`
- `controller`
- type `NodePath`
- mandatory `yes`
@ -40,25 +40,25 @@ Handles interactions between Presencode and the active presentation file.
- arguments `none`
### `change_slide`
- return type `void`
- description `Changes the current slide to some other slide`
- description `Switch to another slide`
- arguments
- `slide`
- type `int`
- mandatory `yes`
- description `The id of the new slide`
- description `Id of the new slide`
- `no_animations`
- type `bool`
- mandatory `no`
- description `Used internally, do not overwrite manually!`
- description `Does not run controller.animation_switch_away() and controller.animation_switch_to(). Used internally, do not use unless you have to`
### `clear_viewport`
- return type `void`
- description `Convenience function: Clears the presentation viewport for you.`
- description `Clears the presentation viewport`
- arguments `none`
### `hide_log`
- return type `void`
- description `Hides the log output in the background`
- description `Hides the log output`
- arguments `none`
### `show_log`
- return type `void`
- description `Unhides the log output in the background`
- description `Shows the log output`
- arguments `none`

4
docs/docs/reference/api/preader.md
View file

@ -1,9 +1,9 @@
---
sidebar_position: 3
sidebar_position: 4
---
# Presentation Reader (preader)
Reads Presencode presentation archives and directories
Reads Presencode presentation archives and directories.
## Functions
### `read_file`

2
docs/docs/reference/console.md
View file

@ -1,5 +1,5 @@
---
sidebar_position: 3
sidebar_position: 4
---
# Debugging console

29
docs/docs/reference/controller.md
View file

@ -1,5 +1,5 @@
---
sidebar_position: 2
sidebar_position: 3
---
# Presentation Controller
@ -10,7 +10,7 @@ The presentation controller controls the presentation and is required for a work
Every presentation controller needs to have these functions:
- `_ready`
- return type `void`
- description `Called by the Godot engine after injection. Use this function for controller registration and early loading`
- description `Called by Godot after injection. Use this function for controller registration and early loading`
- arguments `none`
- `presentation_start`
- return type `void`
@ -22,17 +22,17 @@ Every presentation controller needs to have these functions:
- description `Direct access to the viewport your controller should be operating in`
- `presentation_end`
- return type `void`
- description `Called before shutdown`
- description `Called before Presencode shuts down`
- arguments `none`
- `change_slide`
- return type `void`
- description `Called on slide change by the Presentation Manager`
- description `Called by pmana.change_slide()`
- arguments `none`
### Quit on last slide
You need to have these functions if you pass `quit_last_slide` to [`pmana.register()`](/reference/api/pmana#register) as `false`:
- `display_end_slide`
- return type `void`
- description `Called if the end slide should be shown. Should operate very similar to change_slide()`
- description `Called by the Presentation Manager if the slide counter is exceeded by 1. Should be similar to change_slide()`
- arguments `none`
### Animations
You need to have these functions if you pass `animations` to [`pmana.register()`](/reference/api/pmana#register) as `true`:
@ -43,11 +43,11 @@ You need to have these functions if you pass `animations` to [`pmana.register()`
- `new_slide`
- type `int`
- mandatory `yes`
- description `The id of the slide that should be shown next`
- description `The slide id you're switching to`
- `old_slide`
- type `int`
- mandatory `yes`
- description `The id of the slide that was shown previously`
- description `The slide id you're switching away from`
- `animation_switch_to`
- return type `void`
- description `Called after change_slide(), should be used (as the name suggests) for a switch to animation`
@ -55,11 +55,11 @@ You need to have these functions if you pass `animations` to [`pmana.register()`
- `new_slide`
- type `int`
- mandatory `yes`
- description `The id of the slide that is now shown`
- description `The slide id you're switching to`
- `old_slide`
- type `int`
- mandatory `yes`
- description `The id of the slide that was shown previously`
- description `The slide id you're switching away from`
## Registering a controller
Registering a presentation controller is easy, just call [`pmana.register()`](/reference/api/pmana#register):
@ -67,9 +67,9 @@ Registering a presentation controller is easy, just call [`pmana.register()`](/r
pmana.register(version, slides, animations, quit_last_slide, controller)
| | | | |
| | | | -> NodePath to the presentation controller. Use "self.get_path()" for the script executing that line or NodePath("/root/YOUR_CONTROLLER").
| | | ------------> If Presencode should shutdown once you surpass "slides" (your amount of slides), set to false if you want to display a end slide instead.
| | | ------------> If Presencode should shutdown once you surpass your amount of slides, set to false if you want to display a end slide instead.
| | ----------------------------> Set to true if you want to display slide switch animations.
| ---------------------------------------> The amount of slides you want to display.
| ---------------------------------------> The amount of slides you want to present.
----------------------------------------------> The presentation controller version. Set it to the number "1".
```
@ -86,9 +86,9 @@ Inside [`pmana.change_slide(1)`](/reference/api/pmana#change_slide) the followin
- Call `controller.animation_switch_to(new_slide: 1, old_slide: 0)` and wait for it to finish
- Set `current_slide` to new_slide (1)
With this execution order ***for example*** pull off these animations:
With this execution order you pull off these animations **for example**:
1. `animation_switch_away()` hides the old slide, `change_slide()` unloads the old slide and loads in a new one (invisible), `animation_switch_to()` shows the new slide. The best example for this approch is **fading** in and out.
2. `animation_switch_away()` does nothing, `change_slide()` loads the new slide (invisible), `animations_switch_to()` hides the old one while showing the new one at the same time. One of the best examples of this is a **slide up** animation.
2. `animation_switch_away()` does nothing, `change_slide()` loads the new slide (invisible), `animations_switch_to()` hides the old slide while showing the new one at the same time. One of the best examples of this is a **slide up/down/left/right** animation.
3. These are only examples, you can use your own imagination here!
## Basic controller example
@ -106,7 +106,8 @@ func presentation_start(viewport_: Control) -> void:
pmana.hide_log()
change_slide(0)
func presentation_end() -> void: pass
func presentation_end() -> void:
queue_free()
func change_slide(new_slide: int) -> void:
match(new_slide):

12
docs/docs/reference/manifest-specification.md
View file

@ -1,26 +1,26 @@
---
sidebar_position: 1
sidebar_position: 2
---
# Presencode Manifest Specification
The Presencode Manifest Specification specifies how presentation manifests should be constructed.
## Version 1
### Properties
- version `1`
- filename `manifest.json`
- location (zip) `<YOUR_PRESENTATION_ARCHIVE>.zip/manifest.json`
- location (dir) `<YOUR_PRESENTATION_DIRECTORY>/manifest.json`
- filetype `JSON`
- json root type `object`
- json root type `Object`
### `version`
- type `integer`
- mandatory `yes`
- description: `The manifest version`
- description: `Identifies the manifest version`
- value `1`
### `program`
- type `string`
- mandatory `yes`
- description `Manifest detection`
- description `Allows Presencode to differentiate between "normal" JSON files and Presencode manifests`
- value `Presencode`
### `topic`
- type `string`
@ -61,7 +61,7 @@ The Presencode Manifest Specification specifies how presentation manifests shoul
### `entrypoint`
- type `string`
- mandatory `yes`
- description `Path to the entrypoint script`
- description `Path inside the presentation archive/directory to the entrypoint script file`
- suggested value `entrypoint.gd`
### Example
```json

25
docs/docs/reference/terminology.md Normal file
View file

@ -0,0 +1,25 @@
---
sidebar_position: 1
---
# Terminology
You don't know a word? Look it up here.
## Viewport
The presentation viewport is a `Control` node added to the [Loader](#loader) scene. This is the area where a presentation controller should place images, text, etc..
## Presentation controller
The presentation controller is not bundled in Presencode's source code, but is rather written by you!
It communicates with [Presencode's API](/reference/api/) and the [Presentation Manager](#presentation-manager) and is responsible for displaying the actual presentation.
## Presencode Manifest / Presencode Manifest Specification
Every presentation is required to have a `manifest.json` file. It contains information, such as the topic, presentation authors, the presentation entrypoint, etc..
## Entrypoint script
The entrypoint script is loaded by Presencode and is responsible for setting up the presentation. It can also act as the [Presentation controller](#presentation-controller), they can be seperate scripts though.
## Presencode Manager
The Presentation Manager – located at `src/pmana.gd` in Presencode's source code – handles the communication between Presencode and [the active presentation controller](#presentation-controller).
The presentation manager for example handles presentation controller (un)registration, slide navigation, etc..
## Presentation Reader
The Presentation Reader – located at `src/preader.gd` in Presencode's source code – reads files from presentation archives (`.zip` or `.pcpa` files) and directories.
It's also responsible for reading the presentation manifest and entrypoint files.
## Loader
The Loader (as the name suggests) initializes Presencode and launches a presentation. It's located at `src/loader.gd` and `Loader.tscn` in Presencode's source code.
The Loader scene (renamed to `Presencode` during execution) also holds the presentation viewport.