diff --git a/docs/objects/Basalt/onEvent.md b/docs/objects/Basalt/onEvent.md index ad8a790..915efdc 100644 --- a/docs/objects/Basalt/onEvent.md +++ b/docs/objects/Basalt/onEvent.md @@ -2,10 +2,20 @@ ## onEvent -Every event the computer receives, from the bulit-in event "api", will get passed into basalt.onEvent, except for all mouse events, the key events (key and key_up), char and monitor_touch. +This is the top-level method to intercept an event before sending it to the object event handlers. If you use return false, the event is not passed to the event handlers. ### Parameters +1. `function` The function which should be called + ### Usage -TODO \ No newline at end of file +```lua +local basalt = require("basalt") + +basalt.onEvent(function(event) + if(event=="terminate")then + return false + end +end) +``` diff --git a/docs/objects/Object.md b/docs/objects/Object.md index 43c4021..74afb2e 100644 --- a/docs/objects/Object.md +++ b/docs/objects/Object.md @@ -1,6 +1,6 @@ This is the base class for all visual objects. It covers positioning, sizing, showing/hiding and much more. -By default a freshly created object is visible and automatically listens to all incoming events. +By default a freshly created object is visible and doesn't listens to any incoming events. Its default position is always 1, 1 (based on it's parent frame). The default anchor is also topLeft. | | | @@ -31,16 +31,40 @@ Its default position is always 1, 1 (based on it's parent frame). The default an # Events +This is a list of all available events for all objects: + | | | |---|---| |[onClick](objects/Object/onClick.md)|Fires as soon as the object gets clicked |[onClickUp](objects/Object/onClickUp.md)|Fires as soon as the mouse button gets released on the object -|[onScroll](objects/Object/onScroll.md)|Fires as soon as you scroll with the mousewheel +|[onRelease](objects/Object/onRelease.md)|Fires as soon as the mouse button gets released +|[onScroll](objects/Object/onScroll.md)|Fires as soon as you scroll with the mousewheel |[onDrag](objects/Object/onDrag.md)|Fires as soon as the object is beeing dragged |[onKey](objects/Object/onKey.md)|Fires when the object is focused and a keyboard key has been clicked +|[onChar](objects/Object/onChar.md)|Fires when the object is focused and a character has been clicked |[onKeyUp](objects/Object/onKeyUp.md)|Fires when the object is focused and a keyboard key has been released |[onChange](objects/Object/onChange.md)|Fires when the object value has been changed |[onResize](objects/Object/onResize.md)|Fires when the object got resized |[onReposition](objects/Object/onReposition.md)|Fires when the object has been repositioned |[onGetFocus](objects/Object/onGetFocus.md)|Fires when the object is focused -|[onLoseFocus](objects/Object/onLoseFocus.md)|Fires when the object lost it's focus \ No newline at end of file +|[onLoseFocus](objects/Object/onLoseFocus.md)|Fires when the object lost it's focus +|[onEvent](objects/Object/onEvent.md)|Fires on any other event + +Sidenote: When you use return false this will skip the object's event handler. Here is a example for that. + +This code would make it impossible to write a into the input: + +```lua +local basalt = require("basalt") + +local main = basalt.createFrame() +local input = main:addInput() + :setPosition(3,3) + +function checkInput(self, event, char) + if(char=="a")then + return false + end +end +main:onChar(checkInput) +``` diff --git a/docs/objects/Object/onChar.md b/docs/objects/Object/onChar.md new file mode 100644 index 0000000..3cb4402 --- /dev/null +++ b/docs/objects/Object/onChar.md @@ -0,0 +1,25 @@ +# onChar + +`onChar(self, event, char)`
+The computercraft event which triggers this method is `char`. + +The char event always happens after the key event (just like in cc:tweaked) + +Here is a example on how to add a onChar event to your frame: + +```lua +local basalt = require("basalt") + +local main = basalt.createFrame() +local subFrame = main:addFrame() + :setPosition(3,3) + :setSize(18,6) + :hide() + +function openSubFrame(self, event, char) + if(char=="a")then + subFrame:show() + end +end +main:onChar(openSubFrame) +``` diff --git a/docs/objects/Object/onEvent.md b/docs/objects/Object/onEvent.md new file mode 100644 index 0000000..e863bf4 --- /dev/null +++ b/docs/objects/Object/onEvent.md @@ -0,0 +1,20 @@ +# onEvent + +`onEvent(self, event, ...)` + +This event gets called on any other event. Some examples: http_success, disk, modem_message, paste, peripheral, redstone,... + +You can find a full list here: [CC:Tweaked](https://tweaked.cc/) (on the left sidebar) + +Here is a example on how to add a onEvent event to your frame: + +```lua +local basalt = require("basalt") + +local main = basalt.createFrame() +main:onEvent(function(event, side, channel, replyChannel, message, distance) + if(event=="modem_message")then + basalt.debug("Mesage received: "..tostring(message)) + end +end) +``` \ No newline at end of file diff --git a/docs/objects/Object/onKey.md b/docs/objects/Object/onKey.md index 550fa77..8532061 100644 --- a/docs/objects/Object/onKey.md +++ b/docs/objects/Object/onKey.md @@ -11,6 +11,7 @@ local main = basalt.createFrame() local subFrame = main:addFrame() :setPosition(3,3) :setSize(18,6) + :hide() function openSubFrame(self, event, key) if(key==keys.c)then diff --git a/docs/objects/Object/onRelease.md b/docs/objects/Object/onRelease.md new file mode 100644 index 0000000..d8c84e4 --- /dev/null +++ b/docs/objects/Object/onRelease.md @@ -0,0 +1,27 @@ +# onRelease +`onRelease(self, event, button, x, y)`
+The computercraft event which triggers this method is `mouse_up`. + +The difference between onRelease and :onClickUp is that :onRelease is called even when the mouse is no longer over the object, while :onClickUp is only called when the mouse is over the object. + +Here is a example on how to add a onRelease event to your button: + +```lua +local basalt = require("basalt") + +local main = basalt.createFrame() +local button = main:addButton() + :setPosition(3,3) + :setSize(12,3) + :setText("Click") + +function buttonOnClick(self, button, x, y) + basalt.debug("Button got clicked!") +end +button:onClick(buttonOnClick) + +function buttonOnRelease(self, button, x, y) + basalt.debug("Button got released!") +end +button:onRelease(buttonOnRelease) +``` \ No newline at end of file diff --git a/docs/objects/Object/onResize.md b/docs/objects/Object/onResize.md index dae0ba0..08916c6 100644 --- a/docs/objects/Object/onResize.md +++ b/docs/objects/Object/onResize.md @@ -1,4 +1,5 @@ # onResize + `onResize(self)`
This is a custom event which gets triggered as soon as the parent frame gets resized. @@ -16,4 +17,4 @@ local function onButtonResize(self) end aButton:onResize(onButtonResize) -``` \ No newline at end of file +``` diff --git a/docs/objects/Program.md b/docs/objects/Program.md index 97b2d50..1ae7c22 100644 --- a/docs/objects/Program.md +++ b/docs/objects/Program.md @@ -12,3 +12,12 @@ Program objects are here for opening other executable programs in your main prog |[injectEvent](objects/Program/injectEvent.md)|Injects a event into the program |[injectEvents](objects/Program/injectEvents.md)|Injects a table of events |[getQueuedEvents](objects/Program/getQueuedEvents.md)|Returns currently queued events + +# Events + +This is a list of all available events for programs: + +| | | +|---|---| +|[onError](objects/Program/onError.md)|Fires when a program errors +|[onDone](objects/Program/onDone.md)|Fires when a program has finished diff --git a/docs/objects/Program/onDone.md b/docs/objects/Program/onDone.md new file mode 100644 index 0000000..10181f4 --- /dev/null +++ b/docs/objects/Program/onDone.md @@ -0,0 +1,19 @@ +# onDone + +`onDone(self, err)`
+This is a custom event which gets triggered as soon as the program has finished. + +Here is a example on how to add a onDone event to your program: + +```lua +local basalt = require("basalt") + +local main = basalt.createFrame() +local aProgram = main:addProgram():execute("rom/programs/shell.lua") + +local function onProgramDone() + basalt.debug("Program has finished") +end + +aProgram:onDone(onProgramDone) +``` diff --git a/docs/objects/Program/onError.md b/docs/objects/Program/onError.md new file mode 100644 index 0000000..aad1d04 --- /dev/null +++ b/docs/objects/Program/onError.md @@ -0,0 +1,34 @@ +# onError + +`onError(self, err)`
+This is a custom event which gets triggered as soon as the program catched a error. + +Here is a example on how to add a onError event to your program: + +```lua +local basalt = require("basalt") + +local main = basalt.createFrame() +local aProgram = main:addProgram():execute("rom/programs/shell.lua") + +local function onProgramError(self, err) +local errFrame = main:addFrame() + :setSize(30, 10) + :setPosition("parent.w / 2 - self.w / 2", "parent.h / 2 - self.h / 2") + +errFrame:addLabel() + :setPosition(2, 3) + :setSize("parent.w - 2", "parent.h - 3") + :setText(err) + +errFrame:addButton() + :setPosition("parent.w", 1) + :setSize(1, 1) + :setText("X") + :onClick(function() + errFrame:remove() + end) +end + +aProgram:onError(onProgramError) +``` diff --git a/docs/objects/Progressbar.md b/docs/objects/Progressbar.md index bad9a66..ebc6ebd 100644 --- a/docs/objects/Progressbar.md +++ b/docs/objects/Progressbar.md @@ -11,3 +11,10 @@ want to add some energy progress you have to do simple maths: currentValue / max |[setProgressBar](objects/Progressbar/setProgressBar.md)|Changes the progress design |[setBackgroundSymbol](objects/Progressbar/setBackgroundSymbol.md)|Sets the background symbol +# Events + +This is a list of all available events for progressbars: + +| | | +|---|---| +|[onDone](objects/Progressbar/onDone.md)|Fires when a progress has finished diff --git a/docs/objects/Progressbar/onDone.md b/docs/objects/Progressbar/onDone.md new file mode 100644 index 0000000..0d9f798 --- /dev/null +++ b/docs/objects/Progressbar/onDone.md @@ -0,0 +1,19 @@ +# onDone + +`onDone(self, err)`
+This is a custom event which gets triggered as soon as the progress is done. + +Here is a example on how to add a onDone event to your progressbar: + +```lua +local basalt = require("basalt") + +local main = basalt.createFrame() +local aProgressbar = main:addProgressbar() + +local function onProgressDone() + basalt.debug("Progress is done") +end + +aProgressbar:onDone(onProgressDone) +``` diff --git a/docs/tips/logic.md b/docs/tips/logic.md index 909031c..a59c0f2 100644 --- a/docs/tips/logic.md +++ b/docs/tips/logic.md @@ -1,6 +1,7 @@ You question yourself how you can execute your own logic while basalt is also active? There are multiple ways of doing that: ## Parallel + Using parallel.waitForAll or parallel.waitForAny ```lua @@ -21,9 +22,11 @@ end parallel.waitForAll(basalt.autoUpdate, yourCustomHandler) -- here it will handle your function (yourCustomHandler) and basalt's handlers at the same time using parallel's API ``` + [Here (tweaked.cc)](https://tweaked.cc/module/parallel.html) you can find out more about the parallel API. ## Threads + Using basalt's thread implementation. ```lua @@ -47,6 +50,7 @@ thread:start(yourCustomHandler) -- here we start the thread and pass the functio ``` ## Timers + Using basalt's implementation of timers. Remember, timers don't run asynchronly which means if you're using sleep somewhere this will freeze basalt's event system too. @@ -67,4 +71,25 @@ end timer:onCall(yourCustomHandler) :setTime(1, -1) :start() -- this will call your function every second until you :cancel() the timer -``` \ No newline at end of file +``` + +## Schedule + +Using basalt's schedule implementation. + +```lua +local basalt = require("basalt") + +local main = basalt.createFrame() -- we need a base frame +main:addButton() -- just a button + :onClick(function() + basalt.debug("Button got clicked") + end) + +local yourCustomHandler = basalt.schedule(function() -- create a new schedule task + -- add your logic here +end) + +yourCustomHandler() -- execute the schedule task + +```