From 95e9aa44533494686b218d8844bcfb41a8a59e81 Mon Sep 17 00:00:00 2001 From: JeremyStarTM Date: Mon, 15 Jan 2024 01:06:15 +0100 Subject: [PATCH] Change wording, fix typos, rewrite docs page --- docs/docs/about.md | 15 ++- .../getting-started/example-presentation.md | 95 ------------------- .../getting-started/writing-a-presentation.md | 72 ++++++++++++++ docs/docs/reference/_category_.json | 2 +- docs/docs/reference/api/_category_.json | 2 +- docs/docs/reference/api/logger.md | 2 +- docs/docs/reference/api/misc.md | 19 ++-- docs/docs/reference/api/pmana.md | 16 ++-- docs/docs/reference/api/preader.md | 4 +- docs/docs/reference/console.md | 2 +- docs/docs/reference/controller.md | 29 +++--- docs/docs/reference/manifest-specification.md | 12 +-- docs/docs/reference/terminology.md | 25 +++++ 13 files changed, 149 insertions(+), 146 deletions(-) delete mode 100644 docs/docs/getting-started/example-presentation.md create mode 100644 docs/docs/getting-started/writing-a-presentation.md create mode 100644 docs/docs/reference/terminology.md diff --git a/docs/docs/about.md b/docs/docs/about.md index 8567eee..9e13eea 100644 --- a/docs/docs/about.md +++ b/docs/docs/about.md @@ -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 diff --git a/docs/docs/getting-started/example-presentation.md b/docs/docs/getting-started/example-presentation.md deleted file mode 100644 index 1cac845..0000000 --- a/docs/docs/getting-started/example-presentation.md +++ /dev/null @@ -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) \ No newline at end of file diff --git a/docs/docs/getting-started/writing-a-presentation.md b/docs/docs/getting-started/writing-a-presentation.md new file mode 100644 index 0000000..183207e --- /dev/null +++ b/docs/docs/getting-started/writing-a-presentation.md @@ -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 \ No newline at end of file diff --git a/docs/docs/reference/_category_.json b/docs/docs/reference/_category_.json index 5430fe8..97c4f2e 100644 --- a/docs/docs/reference/_category_.json +++ b/docs/docs/reference/_category_.json @@ -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" } } diff --git a/docs/docs/reference/api/_category_.json b/docs/docs/reference/api/_category_.json index 3ff1a05..465cdcb 100644 --- a/docs/docs/reference/api/_category_.json +++ b/docs/docs/reference/api/_category_.json @@ -3,6 +3,6 @@ "position": 1, "link": { "type": "generated-index", - "description": "References to the Presencode API" + "description": "Presencode API reference" } } diff --git a/docs/docs/reference/api/logger.md b/docs/docs/reference/api/logger.md index d3b3156..68e2f0e 100644 --- a/docs/docs/reference/api/logger.md +++ b/docs/docs/reference/api/logger.md @@ -1,5 +1,5 @@ --- -sidebar_position: 2 +sidebar_position: 1 --- # Logger diff --git a/docs/docs/reference/api/misc.md b/docs/docs/reference/api/misc.md index 7f0e9ed..1031f69 100644 --- a/docs/docs/reference/api/misc.md +++ b/docs/docs/reference/api/misc.md @@ -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` \ No newline at end of file diff --git a/docs/docs/reference/api/pmana.md b/docs/docs/reference/api/pmana.md index fe03e10..e621203 100644 --- a/docs/docs/reference/api/pmana.md +++ b/docs/docs/reference/api/pmana.md @@ -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` diff --git a/docs/docs/reference/api/preader.md b/docs/docs/reference/api/preader.md index 9a73484..7c00437 100644 --- a/docs/docs/reference/api/preader.md +++ b/docs/docs/reference/api/preader.md @@ -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` diff --git a/docs/docs/reference/console.md b/docs/docs/reference/console.md index d5e3b7c..d1c3be5 100644 --- a/docs/docs/reference/console.md +++ b/docs/docs/reference/console.md @@ -1,5 +1,5 @@ --- -sidebar_position: 3 +sidebar_position: 4 --- # Debugging console diff --git a/docs/docs/reference/controller.md b/docs/docs/reference/controller.md index 323d211..c5773c4 100644 --- a/docs/docs/reference/controller.md +++ b/docs/docs/reference/controller.md @@ -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): diff --git a/docs/docs/reference/manifest-specification.md b/docs/docs/reference/manifest-specification.md index cd95b82..adecc4f 100644 --- a/docs/docs/reference/manifest-specification.md +++ b/docs/docs/reference/manifest-specification.md @@ -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) `.zip/manifest.json` - location (dir) `/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 diff --git a/docs/docs/reference/terminology.md b/docs/docs/reference/terminology.md new file mode 100644 index 0000000..53a714c --- /dev/null +++ b/docs/docs/reference/terminology.md @@ -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. \ No newline at end of file