Check that user only passes one char to jngl::keyDown(const std::stri…

…ng&)

src/jngl/input.hpp

@@ -93,6 +93,22 @@ bool keyDown(key::KeyType key);
 bool keyDown(char key);
 
 /// Whether \p key is down, where \p key should be exactly one UTF-8 character
+///
+/// Example:
+/// \code
+/// if (jngl::keyDown("a")) {
+///     player1Pos.x += 1;
+/// }
+/// if (jngl::keyDown("s")) {
+///     player1Pos.x -= 1;
+/// }
+/// if (jngl::keyDown("ö")) {
+///     player2Pos.x += 1;
+/// }
+/// if (jngl::keyDown("ä")) {
+///     player2Pos.x -= 1;
+/// }
+/// \endcode
 bool keyDown(const std::string& key);
 
 /// Whether \p key has been pressed since the next to last call to updateInput()
@@ -119,6 +135,8 @@ void setMouseVisible(bool visible);
 bool isMouseVisible();
 
 /// Returns true when there's more than one finger touching the screen
+///
+/// Equivalent to `jngl::getTouchPositions().size() > 1`.
 bool isMultitouch();
 
 /// Returns all positions where a finger touches the screen. Includes the mouse position if the
@@ -132,6 +150,9 @@ std::vector<jngl::Vec2> getTouchPositions();
 Vec2 getMousePos();
 
 /// Returns the position of the mouse pointer if a mouse is connected/available
+///
+/// On Android, iOS and for the Nintendo Switch this will always return std::nullopt. While Android
+/// supports connecting mice this isn't supported by JNGL yet.
 optional<Vec2> getCursorPos();
 
 /// Retrieve mouse position in pixels

src/jngl/job.hpp

@@ -54,9 +54,47 @@ class Job {
 };
 
 /// Add a new Job which will be always be stepped and drawn by App::mainLoop()
+///
+/// Example:
+/// \code
+/// class MyJob : public jngl::Job {
+/// public:
+///     MyJob();
+///     // ...
+/// };
+///
+/// jngl::AppParameters jnglInit() {
+///     jngl::AppParameters params;
+///     // ...
+///     params.start = []() {
+///         jngl::addJob(std::make_shared<MyJob>());
+///         // ...
+///     };
+///     return params;
+/// }
+/// \endcode
 void addJob(std::shared_ptr<Job> job);
 
 /// The same as addJob(std::shared_ptr<Job>) but creates the Job for you
+///
+/// Example:
+/// \code
+/// class MyJob : public jngl::Job {
+/// public:
+///     MyJob(int x, float y, std::string foo);
+///     // ...
+/// };
+///
+/// jngl::AppParameters jnglInit() {
+///     jngl::AppParameters params;
+///     // ...
+///     params.start = []() {
+///         jngl::addJob<MyJob>(42, 3.14f, "Hello, World!");
+///         // ...
+///     };
+///     return params;
+/// }
+/// \endcode
 template <class T, class... Args>
 void addJob(Args&&... args) {
 	addJob(std::make_shared<T>(std::forward<Args>(args)...));

src/main.cpp

@@ -386,6 +386,33 @@ bool keyPressed(const key::KeyType key) {
 }
 
 bool keyDown(const std::string& key) {
+	const static auto TOO_LONG = "Only pass one character.";
+	if (key[0] & 0x80) { // first bit (Check if this is an Unicode character)
+		// sourceEnd has to be the next character after the utf-8 sequence
+		const static auto ERROR_MSG = "Invalid UTF-8 string!";
+		if (key.size() < 2) {
+			throw std::runtime_error(ERROR_MSG);
+		}
+		if (key[0] & 0x20) { // third bit
+			if (key.size() < 3) {
+				throw std::runtime_error(ERROR_MSG);
+			}
+			if (key[0] & 0x10) {
+				if (key.size() < 4) { // fourth bit
+					throw std::runtime_error(ERROR_MSG);
+				}
+				if (key.size() > 4) {
+					throw std::runtime_error(TOO_LONG);
+				}
+			} else if (key.size() > 3) {
+				throw std::runtime_error(TOO_LONG);
+			}
+		} else if (key.size() > 2) {
+			throw std::runtime_error(TOO_LONG);
+		}
+	} else if (key.size() > 1) {
+		throw std::runtime_error(TOO_LONG);
+	}
 	return pWindow->getKeyDown(key);
 }
 

src/unittest/misc.cpp

@@ -1,9 +1,11 @@
-// Copyright 2018-2023 Jan Niklas Hasse <[email protected]>
+// Copyright 2018-2024 Jan Niklas Hasse <[email protected]>
 // For conditions of distribution and use, see copyright notice in LICENSE.txt
 
 #include "../jngl/Finally.hpp"
+#include "../jngl/input.hpp"
 #include "../jngl/other.hpp"
 #include "../jngl/sprite.hpp"
+#include "Fixture.hpp"
 
 #include <boost/ut.hpp>
 #include <filesystem>
@@ -66,4 +68,12 @@ boost::ut::suite _ = [] {
 		expect(!jngl::readAsset("non existing file"));
 		expect(throws<std::runtime_error>([] { jngl::readAsset("/some/absolute/path"); }));
 	};
+
+	"keyDown"_test = [] {
+		Fixture f(1);
+		jngl::keyDown("a");
+		expect(throws<std::runtime_error>([] { jngl::keyDown("aa"); }));
+		jngl::keyDown("ä");
+		expect(throws<std::runtime_error>([] { jngl::keyDown("ää"); }));
+	};
 };