diff --git a/docs/assets/icon_128.png b/docs/assets/icon_128.png new file mode 100644 index 0000000..7fd7bf6 Binary files /dev/null and b/docs/assets/icon_128.png differ diff --git a/docs/assets/icon_32.png b/docs/assets/icon_32.png new file mode 100644 index 0000000..c104486 Binary files /dev/null and b/docs/assets/icon_32.png differ diff --git a/docs/assets/icon_512.png b/docs/assets/icon_512.png new file mode 100644 index 0000000..c1c2fd6 Binary files /dev/null and b/docs/assets/icon_512.png differ diff --git a/docs/assets/icon_64.png b/docs/assets/icon_64.png new file mode 100644 index 0000000..ec14346 Binary files /dev/null and b/docs/assets/icon_64.png differ diff --git a/docs/assets/quickstart/shapes_2.png b/docs/assets/quickstart/shapes_2.png new file mode 100644 index 0000000..2c84e0a Binary files /dev/null and b/docs/assets/quickstart/shapes_2.png differ diff --git a/docs/assets/quickstart/shapes_3.png b/docs/assets/quickstart/shapes_3.png new file mode 100644 index 0000000..6837c99 Binary files /dev/null and b/docs/assets/quickstart/shapes_3.png differ diff --git a/docs/assets/quickstart/shapes_4.1.png b/docs/assets/quickstart/shapes_4.1.png new file mode 100644 index 0000000..1ca5442 Binary files /dev/null and b/docs/assets/quickstart/shapes_4.1.png differ diff --git a/docs/assets/quickstart/shapes_4.2.png b/docs/assets/quickstart/shapes_4.2.png new file mode 100644 index 0000000..131ec26 Binary files /dev/null and b/docs/assets/quickstart/shapes_4.2.png differ diff --git a/docs/assets/quickstart/shapes_4.3.png b/docs/assets/quickstart/shapes_4.3.png new file mode 100644 index 0000000..f512fbd Binary files /dev/null and b/docs/assets/quickstart/shapes_4.3.png differ diff --git a/docs/assets/zmstyles.css b/docs/assets/zmstyles.css new file mode 100644 index 0000000..fb51219 --- /dev/null +++ b/docs/assets/zmstyles.css @@ -0,0 +1,12 @@ +h1.title { + text-align: center; + color: #363636; + margin-bottom: .25rem; +} +h2.subtitle { + text-align: center; + font-size: 1rem; + color: #4a4a4a; + margin-top: -.25rem; + margin-bottom: -1.25rem; +} diff --git a/docs/home_override/home.html b/docs/home_override/home.html new file mode 100644 index 0000000..e2e08d0 --- /dev/null +++ b/docs/home_override/home.html @@ -0,0 +1,7 @@ +{% extends "base.html" %} + +{% block tabs %} +{{ super() }} +{% endblock %} +{% block content %}{% endblock %} +{% block footer %}{% endblock %} diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..777e560 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,43 @@ + +
+ ![Zeichenmaschine.xyz](assets/icon_512.png){ width=128 } +
+ +

Zeichenmaschine.xyz

+

Eine kleine Java-Bibliothek für grafische Programmierung im +Informatikunterricht.

+ +## Projektidee + +Die **Zeichenmaschine** ist eine für den Informatikunterricht entwickelte Bibliothek, +die unter anderem an [Processing](https://processing.org/) angelehnt ist. Die +Bibliothek soll einige der üblichen Anfängerschwierigkeiten mit Java vereinfachen +und für Schülerinnen und Schüler im Unterricht nutzbar machen. + +!!! warning + + Das Projekt befindet sich noch in der Entwicklungsphase und auch wenn die + aktuelle Version schon funktionsfähig ist und einen Großteil der angestrebten + Funktionen enthält, ist noch keine stabile Version 1.0 erreicht. Vor allem + am Umfang und konsistenten Design der APIs gilt es noch zu arbeiten und es + können sich Änderungen ergeben. + + Feedback und Vorschläge zu diesem Prozess (oder auch eine Beteiligung an der + Entwicklung) können sehr gerne über [Github](https://github.com/jneug) oder + [Mastodon](https://bildung.social/@ngb) an mich kommuniziert werden. + + (Gleiches gilt für diese Webseite zum Projekt.) + +## Dokumentation +* [Schnellstart](quickstart.md) +* [Installation](install.md) +* {{ javadoc_link() }} + +## Über die Zeichenmaschine + +!!! info + + In der Zeichenmaschine werden bewusst nur englischsprachige Bezeichner für + Klassen, Methoden und Variablen verwendet. Ausnahme sind einzelne Klassen, + die im Zusammnehang mit dem Namen der Bibliothek stehen, wie die + Hauptklasse `Zeichenmaschine`. diff --git a/docs/install.md b/docs/install.md new file mode 100644 index 0000000..b047580 --- /dev/null +++ b/docs/install.md @@ -0,0 +1,44 @@ +# Installation + +Um ein einfaches Projekt mit der **Zeichenmaschine** aufzusetzen ist nicht mehr +nötig, als +die [JAR-Datei der aktuellen Version](https://github.com/jneug/zeichenmaschine/release/latest) +herunterzuladen und dem *Classpath* des Projekts hinzuzufügen. Beschreibungen +für +verschiedene Entwicklungsumgebungen sind hier aufgelistet. + +## Integration in Entwicklungsumgebungen + +### BlueJ + +[BlueJ](https://bluej.org) sucht an drei Orten nach Bibliotheken, die für ein +Projekt in den Classpath aufgenommen werden: + +- Für ein einzelnes Projekt im Projektordner im Unterordner `+libs`. +- Im Reiter "Bibliotheken" der BlueJ-Einstellungen. + + Hier können Programmbibliotheken hinzugefügt werden, die dann allen Projekten + zur Verfügung stehen. + +- Für alle Projekte und alle Nutzer dieser BlueJ-Version im + Unterordner `userlib` des Programmordners. + + Auf Windows-Systemen ist dieser im Order `lib` des Installationsordners von BlueJ zu finden. + + Auf macos-Systemen muss via Rechtsklick auf die Programmdatei `BlueJ.app` über den Menüpunkt "Paketinhalt zeigen" in den Ordner `Contents/Resources/Java/` navigiert werden. + +### VSCode / VSCodium + +> Coming soon + +### IntelliJ + +> Coming soon + +### Eclipse + +> Coming soon + +### NetBeans + +> Coming soon diff --git a/docs/macros.py b/docs/macros.py new file mode 100644 index 0000000..05be99c --- /dev/null +++ b/docs/macros.py @@ -0,0 +1,63 @@ +import re +from typing import List + + +def define_env(env): + @env.macro + def javadoc(clazz: str = None, target: str = None) -> str: + if not "javadoc_url" in env.variables: + return clazz + + if not clazz: + return f"{env.variables['javadoc_url'].rstrip('/')}/index.html" + else: + if "javadoc_default_package" in env.variables and not clazz.startswith(env.variables['javadoc_default_package']): + clazz = f"{env.variables['javadoc_default_package'].rstrip('.')}.{clazz}" + javadoc_url = env.variables["javadoc_url"].rstrip("/") + path = clazz.replace(".", "/") + ".html" + if target: + path = f"{path}#{target}" + return f"{javadoc_url}/{path}" + + @env.macro + def javadoc_link( + clazz: str = None, target: str = None, strip_package: bool = True, strip_clazz: bool = False, title: str = None + ) -> str: + name = clazz or "Javadoc" + if strip_package: + if clazz and clazz.rfind(".") > -1: + name = clazz[clazz.rfind(".") + 1 :] + if target: + # _target = re.sub(r"([^(][^,]*?\.)*?([^)]+)", lambda m: m.group(2), target) + _target = target + if strip_clazz: + name = _target + else: + name = f"{name}.{_target}" + if title: + name = title + + return f"[{name}]({javadoc(clazz, target)})" + + @env.macro + def javadoc_signature( + clazz: str = None, + member: str = None, + package: str = None, + params: List[str] = list(), + ) -> str: + sig = clazz or "" + if clazz and package: + sig = f"{package}.{sig}" + if member: + sig = f"{sig}#{member}" + + pparams = ",".join(params) + sig = f"{sig}({pparams})" + + return sig + + +# schule/ngb/zm/Zeichenmaschine.html#setCursor(java.awt.Image,int,int) +# schule/ngb/zm/Zeichenmaschine.html#getLayer(java.lang.Class) +# schule/ngb/zm/DrawableLayer.html#add(schule.ngb.zm.Drawable...) diff --git a/docs/quickstart.md b/docs/quickstart.md index e69de29..0209d69 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -0,0 +1,130 @@ +# Schnellstart mit der Zeichenmaschine + +Um ein einfaches Projekt mit der **Zeichenmaschine** aufzusetzen ist nicht mehr +nötig, als die [JAR-Datei der aktuellen Version](https://github.com/jneug/zeichenmaschine/release/latest) +herunterzuladen und dem *Classpath* des Projekts hinzuzufügen. Eine Beschreibung +für verschiedene Entwicklungsumgebungen findet sich im Abschnitt [Installation](install.md). + +## Die Basisklasse + +Um eine Zeichenmaschine zu erstellen, muss eine Unterklasse von {{ javadoc_link("schule.ngb.zm.Zeichenmaschine") }} +erstellt werden. + +```java +public class Shapes extends Zeichenmaschine { + +} +``` + +Die gezeigte Klasse ist schon eine lauffähige Zeichenmaschine und kann gestartet +werden. + +!!! note + + Bei einigen Entwicklungsumgebungen muss noch eine `main`-Methode erstellt + werden, um die Zeichenmaschine zu starten: + + ```java + public static void main(String[] args) { + new Shapes(); + } + ``` + +Es öffnet sich ein Zeichenfenster in einer vordefinierten Größe. Um die Größe und +den Titel des Fensters zu ändern, legen wir einen Konstruktor an. + +```java +public class Shapes extends Zeichenmaschine { + + public Shapes() { + super(800, 800, "Shapes"); + } + +} +``` + +Starten wir das Projekt nun, wird das Zeichenfenster in der Größe 800x800 mit +dem Titel "Shapes" angezeigt. + +
+![Shapes 2](assets/quickstart/shapes_2.png){ width=400 } +
+ +### Formen zeichnen + +Eine Zeichenmaschine hat verschiedene Möglichkeiten, Inhalte in das Zeichenfenster +zu zeichnen. Um einfach nur ein statisches Bild zu erzeugen, überschreiben wir die +{{ javadoc_link("schule.ngb.zm.Zeichenmaschine", "draw()") }} Methode. + +```java +public class Shapes extends Zeichenmaschine { + + public Shapes() { + super(800, 800, "Shapes"); + } + + @Override + public void draw() { + background.setColor(43, 128, 243); + + drawing.setFillColor(255, 223, 34); + drawing.noStroke(); + drawing.circle(400, 400, 100); + } +} +``` + +Nun haben wir einen gelben Kreis (ohne Konturlinie) auf einem blauen Hintergrund +gezeichnet. + +
+![Shapes 3](assets/quickstart/shapes_3.png){ width=400 } +
+ +### Vorbereitung der Zeichenfläche + +Im Beispiel oben setzen wir die Hintergrundfarbe auf Blau, die Füllfarbe auf Gelb +und deaktivieren die Konturlinie. Wenn diese Einstellungen für alle Zeichenobjekte +gleich sind, können wir sie statt in `draw()` auch in die `setup()` Methode schreiben. +Diese bereitet die Zeichenfläche vor dem ersten Zeichnen vor. + +```java +public class Shapes extends Zeichenmaschine { + + public Shapes() { + super(800, 800, "Shapes"); + } + + @Override + public void setup() { + background.setColor(43, 128, 243); + + drawing.setFillColor(255, 223, 34); + drawing.noStroke(); + } + + @Override + public void draw() { + for( int i = 0; i < 10; i++ ) { + drawing.circle( + random(0, canvasWidth), + random(0, canvasHeight), + random(50, 200) + ); + } + } +} +``` + +Im Beispiel setzen wir nun die Grundeinstellungen in der `setup()` Methode. In +`draw()` werden zehn gelbe Kreise an Zufallskoordinaten gezeichnet. + +
+![Shapes 4](assets/quickstart/shapes_4.1.png){ width=400 } +
+ +!!! tip "" + + Mit {{ javadoc_link("Constants", "canvasWidth", title="canvasWidth") }} und {{ javadoc_link("Constants", "canvasHeight", strip_clazz=True) }} kannst du in der Zeichenmaschine auf + die aktuelle Größe der Zeichenfläche zugreifen. {{ javadoc_link("Constants", "random(int,int)") }} + erzeugt eine Zufallszahl innerhalb der angegebenen Grenzen. diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..efa89de --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,76 @@ +site_name: Zeichenmaschine.xyz +site_description: Eine kleine Java-Bibliothek für grafische Programmierung im Informatikunterricht. +site_author: J. Neugebauer +repo_url: https://github.com/jneug/zeichenmaschine +repo_name: jneug/zeichenmaschine + +site_dir: build/docs/site + +theme: + name: material + custom_dir: docs/home_override/ + language: de + logo: assets/icon_64.png + favicon: assets/icon_32.png + features: + - content.code.annotate + - navigation.top + - navigation.tracking + - search.suggest + font: false + palette: + - media: "(prefers-color-scheme: light)" + scheme: default + primary: blue + accent: deep orange + toggle: + icon: material/weather-sunny + name: Dunkles Design aktivieren + - media: "(prefers-color-scheme: dark)" + scheme: slate + primary: blue + accent: deep orange + toggle: + icon: material/weather-night + name: Helles Design aktivieren +extra_css: + - assets/zmstyles.css + +nav: + - Einführung: index.md + - Schnellstart: quickstart.md + - Installation: install.md + +markdown_extensions: + - admonition + - attr_list + - def_list + - footnotes + - md_in_html + - toc: + permalink: true + - pymdownx.magiclink + - pymdownx.betterem: + smart_enable: all + - pymdownx.caret + - pymdownx.smartsymbols + - pymdownx.emoji: + emoji_index: !!python/name:materialx.emoji.twemoji + emoji_generator: !!python/name:materialx.emoji.to_svg + - pymdownx.highlight: + anchor_linenums: true + - pymdownx.inlinehilite + - pymdownx.snippets + - pymdownx.details + - pymdownx.superfences + +plugins: + - search: + lang: de + separator: '[\s\-\.]' + - macros: + module_name: docs/macros + +extra: + javadoc_url: https://zeichenmaschine.xyz/docs/ + javadoc_default_package: schule.ngb.zm diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 0000000..b383bb7 --- /dev/null +++ b/requirements.txt @@ -0,0 +1,25 @@ +certifi==2022.9.24 +charset-normalizer==2.1.1 +click==8.1.3 +ghp-import==2.1.0 +idna==3.4 +Jinja2==3.1.2 +Markdown==3.3.7 +MarkupSafe==2.1.1 +mergedeep==1.3.4 +mkdocs==1.4.1 +mkdocs-macros-plugin==0.7.0 +mkdocs-material==8.5.6 +mkdocs-material-extensions==1.0.3 +packaging==21.3 +Pygments==2.13.0 +pymdown-extensions==9.6 +pyparsing==3.0.9 +python-dateutil==2.8.2 +PyYAML==6.0 +pyyaml_env_tag==0.1 +requests==2.28.1 +six==1.16.0 +termcolor==2.0.1 +urllib3==1.26.12 +watchdog==2.1.9