From 43e1d086dc0fbebbecb8814f390c60b9b2eaf4f3 Mon Sep 17 00:00:00 2001 From: Robert Jelic <36573031+NoryiE@users.noreply.github.com> Date: Sun, 30 Apr 2023 19:09:33 +0200 Subject: [PATCH] Small Docs Update --- docs/Home.md | 1 + docs/_footer.md | 4 +- docs/_sidebar.md | 13 ++--- docs/guides/introduction.md | 42 ++++++++++++++ docs/index.html | 2 +- docs/tips/buttonColoring.md | 80 -------------------------- docs/tips/design.md | 112 ------------------------------------ docs/tips/dynamicvalues.md | 54 ----------------- docs/tips/logic.md | 95 ------------------------------ docs/tips/xml.md | 79 ------------------------- 10 files changed, 52 insertions(+), 430 deletions(-) create mode 100644 docs/guides/introduction.md delete mode 100644 docs/tips/buttonColoring.md delete mode 100644 docs/tips/design.md delete mode 100644 docs/tips/dynamicvalues.md delete mode 100644 docs/tips/logic.md delete mode 100644 docs/tips/xml.md diff --git a/docs/Home.md b/docs/Home.md index 04e9ad5..115b351 100644 --- a/docs/Home.md +++ b/docs/Home.md @@ -4,6 +4,7 @@ Basalt is a user-friendly UI framework for CC:Tweaked (also known as "ComputerCraft: Tweaked") - a popular Minecraft mod. It was developed to enhance user interaction through visual displays. In this wiki, you'll find information on how to use Basalt as well as examples of functional Basalt code. +This Website is made with the help of ChatGPT. ## About Basalt diff --git a/docs/_footer.md b/docs/_footer.md index dfb8692..d381de8 100644 --- a/docs/_footer.md +++ b/docs/_footer.md @@ -1 +1,3 @@ -Thanks for checking out our wiki, join our discord for more help: [discord.gg/yM7kndJdJJ](discord.gg/yM7kndJdJJ) \ No newline at end of file +--- + +Thanks for checking out our wiki, join our discord for more help: [discord.gg/yM7kndJdJJ](discord.gg/yNNnmBVBpE) diff --git a/docs/_sidebar.md b/docs/_sidebar.md index b6adffd..02a2a45 100644 --- a/docs/_sidebar.md +++ b/docs/_sidebar.md @@ -1,8 +1,9 @@ +[1.6 Docs](https://basalt.madefor.cc/docs1_6) + - About - - [Home](home) + - [Home](/) - [How To](home/How-To) - [Download](home/download) - - [1.6 Docs](docs1_6) - Objects - [Basalt](objects/Basalt.md) - [Object](objects/Object.md) @@ -33,9 +34,5 @@ - [Thread](objects/Thread.md) - [Treeview](objects/Treeview.md) - [Timer](objects/Timer.md) -- Tutorials - - [Your Logic](tips/logic.md) - - [Button coloring](tips/buttonColoring.md) - - [Designing/Animating](tips/design.md) - - [Dynamic Values](tips/dynamicvalues.md) - - [XML](tips/xml.md) +- Guides + - [Introduction to Basalt](guides/introduction.md) diff --git a/docs/guides/introduction.md b/docs/guides/introduction.md new file mode 100644 index 0000000..3363480 --- /dev/null +++ b/docs/guides/introduction.md @@ -0,0 +1,42 @@ +Basalt is a powerful and flexible user interface (UI) framework designed to make it easy for developers to create visually appealing and interactive applications. This guide will provide an overview of Basalt, its main components, and the basic concepts and terminology used in the framework. + +## What is Basalt? + +Basalt is a UI framework that simplifies the process of creating, designing, and managing user interfaces for various applications. It provides a wide range of UI elements and components, such as frames, buttons, labels, text fields, and more, making it easier for developers to create custom and responsive layouts without having to worry about the low-level details of UI rendering and event handling. + +## Main Components of Basalt + +Basalt consists of several key components that work together to create a seamless user interface experience. Some of the main components include: + +1. Objects: Basalt objects represent the various UI elements that make up an application's interface. Examples of objects include frames, buttons, text fields, and more. Each object comes with a set of properties and methods that allow you to customize its appearance and behavior. + +2. Frames: Frames are the primary containers for organizing and laying out UI objects in Basalt. They can be nested, allowing for complex and hierarchical layouts. Basalt provides different types of frames, such as basic frames, movable frames, scrollable frames, and flexboxes, each with their own unique properties and use cases. + +3. Events: Events are triggered by user interactions, such as clicks, keypresses, and other inputs. Basalt provides an event handling system that allows you to easily respond to these events and update your application's interface or behavior accordingly. + +4. Threading: Basalt supports the use of threads in applications, enabling concurrent actions and background processes to run without blocking the main program. + +This introduction should give you a basic understanding of Basalt and its main components. As you continue to explore the framework and its features, you'll gain a deeper understanding of how to create and customize your own applications using Basalt. + +## Layout Management + +Understanding how to manage and organize the layout of UI objects is important when working with Basalt. You can use different types of frames, such as Flexbox or ScrollableFrame, to create responsive and adaptive layouts for your applications. + +```lua +local main = basalt.createFrame() -- The main frame/most important frame in your project + +local column1 = main:addFrame():setSize("parent.w/2", "parent.h") +local column2 = main:addFrame():setSize("parent.w/2", "parent.h"):setPosition("parent.w/2+1", 1) +``` + +## Input Handling + +Handling user input, such as text input or slider adjustments, is essential for creating interactive applications. Basalt provides various UI elements for capturing user input and events for processing the input. + +```lua +local mainFrame = basalt.createFrame() +local aInput = mainFrame:addInput() +aInput:onChange(function(text) + basalt.debug("User entered: " .. text) +end) +``` diff --git a/docs/index.html b/docs/index.html index df0d38b..c129e2f 100644 --- a/docs/index.html +++ b/docs/index.html @@ -41,11 +41,11 @@ loadSidebar: true, loadFooter: '_footer.md', autoHeader: true, - subMaxLevel: 3, homepage: 'Home.md', name: 'Basalt', repo: 'https://github.com/Pyroxenium/Basalt', auto2top: true, + noCompileLinks: ['/docs1_6'], search: { maxAge: 86400000, // Expiration time, the default one day paths: 'auto', diff --git a/docs/tips/buttonColoring.md b/docs/tips/buttonColoring.md deleted file mode 100644 index c423f0e..0000000 --- a/docs/tips/buttonColoring.md +++ /dev/null @@ -1,80 +0,0 @@ -Here i will explain to you how you can add some coloring to your buttons in certain events. This is not only for buttons possible but also for all the other visual objects - -But first, i want to explain to you that you can also add the same event-type multiple times: -```lua -local function buttonColoring(self, event, button, x, y) --- here you can add some coloring for your button - for example: - self:setBackground(colors.black) -end -local function buttonLogic(self, event, button, x, y) --- here you can add some logic for your button - basalt.debug("Some logic") -end -local button = main:addButton() -button:onClick(buttonColoring):onClick(buttonLogic) -- yes this would work, if not its a bug! -``` -This means you can create a function wich handles only the coloring side of your button, and if your button also needs some logic you just create another function for that and add it to your button. - - -Now let's create a function where we pass a button object as an argument on which we set up the coloring -```lua -local basalt = require("basalt") -local main = basalt.createFrame() -local button = main:addButton() - :setPosition(3,3) - :setSize(12,3) - :setText("Click me") - :setBackground(colors.gray) - :setForeground(colors.black) - -local button2 = main:addButton() - :setPosition(25,3) - :setSize(16,3) - :setText("Another Btn") - :setBackground(colors.gray) - :setForeground(colors.black) - -local function setupButtonColoring(self, event, button, x, y) - self:onClick(function() - self:setBackground(colors.black) - self:setForeground(colors.lightGray) - end) - self:onClickUp(function() - self:setBackground(colors.gray) - self:setForeground(colors.black) - end) - self:onLoseFocus(function() - self:setBackground(colors.gray) - self:setForeground(colors.black) - end) -end - -setupButtonColoring(button) -setupButtonColoring(button2) - -basalt.autoUpdate() -``` - -Now you got a button which changes the color when you click on it. - - -There is also another way of doing it, but this is time based, which means it does not check if the user is holding the mousebutton down. -```lua -local basalt = require("basalt") - -local main = basalt.createFrame() -local button = main:addButton() - :setPosition(3,3) - :setSize(12,3) - :setText("Click me") - :setBackground(colors.gray) - :setForeground(colors.black) - -button:onClick(basalt.schedule(function() - button:setBackground(colors.black) - sleep(0.5) - button:setBackground(colors.gray) - end)) -``` - -Here you are using basalt.schedule, which will start the function in a coroutine \ No newline at end of file diff --git a/docs/tips/design.md b/docs/tips/design.md deleted file mode 100644 index 184daec..0000000 --- a/docs/tips/design.md +++ /dev/null @@ -1,112 +0,0 @@ -Hello! This page contains some tips on how to create cool designs with Basalt - -To understand this page, it is recommended to familiarize yourself with [Animations](../objects/Animation.md) as animations are important for creating cool looking designs - -## Animation-move -Here i will show you how you can move objects by using the animation object. - -```lua -local basalt = require("basalt") - -local main = basalt.createFrame() -local sub = main:addFrame():setSize("parent.w - 2",12):setPosition("-parent.w",4) - sub:addLabel() - :setText("Cool Title") - :setBackground(colors.black) - :setForeground(colors.lightGray) - :setSize("parent.w", 1) - -local button = sub:addButton() - :setBackground(colors.black) - :setForeground(colors.lightGray) - :setPosition(-12,9) -local button2 = sub:addButton() - :setBackground(colors.black) - :setForeground(colors.lightGray) - :setPosition("parent.w + 12",9) - -local anim = main:addAnimation() - :setObject(sub) - :move(2,4,1.5) - :setObject(button) - :move(2,9,1,1.5) - :setObject(button2) - :move(sub:getWidth()-12,9,1,1.5) - :play() - -basalt.autoUpdate() -``` - -As you can see, you only need 1 animation but you can still move 3 objects. - -## Animation-offset -Here is a example which changes the offset on your base frame. It shows you, how you could create multiple pages and switch between them in a cool looking way: -```lua -local basalt = require("basalt") - -local main = basalt.createFrame() -local mainAnim = main:addAnimation() - -local frames = { - main:addFrame():setPosition(1,2):setSize("parent.w", "parent.h-1"):setBackground(colors.lightGray), - main:addFrame():setPosition("parent.w+1",2):setSize("parent.w", "parent.h-1"):setBackground(colors.lightGray), - main:addFrame():setPosition("parent.w*2+1",2):setSize("parent.w", "parent.h-1"):setBackground(colors.lightGray), - main:addFrame():setPosition("parent.w*3+1",2):setSize("parent.w", "parent.h-1"):setBackground(colors.lightGray), -} - -frames[1]:addLabel():setText("This is frame 1") -frames[2]:addLabel():setText("This is frame 2") -frames[3]:addLabel():setText("This is frame 3") -frames[4]:addLabel():setText("This is frame 4") - -local menubar = main:addMenubar():ignoreOffset() - :addItem("Page 1",nil,nil,1) - :addItem("Page 2",nil,nil,2) - :addItem("Page 3",nil,nil,3) - :addItem("Page 4",nil,nil,4) - :setSpace(3) - :setSize("parent.w",1) - :onChange(function(self, value) - mainAnim:clear() - :cancel() - :setObject(main) - :offset(value.args[1] * main:getWidth() - main:getWidth(), 0, 2) - :play() - end) - - -basalt.autoUpdate() -``` - -## Visually showing -Here I'll show you how to visually show the user when something isn't working. this is just one example that you can apply to other topics as well. -```lua -local basalt = require("basalt") - -local password = "12345" - -local main = basalt.createFrame() - -main:addLabel():setText("Password:"):setPosition(2,2) -local input = main:addInput():setInputType("password"):setPosition(2,3):setSize(24,1) -local submit = main:addButton():setPosition(2,5):setText("Submit") -submit:onClick(basalt.schedule(function() - if(password==input:getValue())then - basalt.debug("Password correct!") - else - basalt.debug("Wrong password!") - submit:setBackground(colors.red) - sleep(0.05) - submit:setPosition(3,5) - sleep(0.05) - submit:setPosition(2,5) - sleep(0.05) - submit:setPosition(1,5) - sleep(0.05) - submit:setPosition(2,5) - submit:setBackground(colors.gray) - end -end)) - -basalt.autoUpdate() -``` \ No newline at end of file diff --git a/docs/tips/dynamicvalues.md b/docs/tips/dynamicvalues.md deleted file mode 100644 index 7f49631..0000000 --- a/docs/tips/dynamicvalues.md +++ /dev/null @@ -1,54 +0,0 @@ -Dynamic Values is a way to position or size your object based on the position/size of other objects. This makes it pretty easy to create programs where the terminal size -doesn't matter. - -A dynamic value is always a string, and you can add anything you want in there. Here are some examples:
-"5 + 2"
-"(5 + 2) * 3"
-"math.floor(5+2.2)"
-"objectid.x + objectid.y + objectid.w + objectid+h"
-"parent.w"
-"self.w"
- -Parent always refers to it's parent object, self always refers to itself. - -## Positioning -Here i will show you a example on how to position a button next to another button, doesn't matter which size it has. - -```lua -local basalt = require("basalt") - -local main = basalt.createFrame() - -local button = main:addButton("firstBtn") - :setBackground(colors.black) - :setForeground(colors.lightGray) - :setPosition(2, 2) -local button2 = main:addButton() - :setBackground(colors.black) - :setForeground(colors.lightGray) - :setPosition("firstBtn.w + firstBtn.x + 2", "firstBtn.y") - -basalt.autoUpdate() -``` -Now, you can move the first button and the second button would also move. Doesn't matter how. - -## Sizing -This is a example on how you can create buttons where the size is always based on it's parent frame -```lua -local basalt = require("basalt") - -local main = basalt.createFrame() - -local button = main:addButton("firstBtn") - :setBackground(colors.black) - :setForeground(colors.lightGray) - :setPosition(2, 2) - :setSize("parent.w - 2", 3) -local button2 = main:addButton() - :setBackground(colors.black) - :setForeground(colors.lightGray) - :setPosition(2, "firstBtn.y + firstBtn.h + 1") - :setSize("parent.w - 2", 3) - -basalt.autoUpdate() -``` \ No newline at end of file diff --git a/docs/tips/logic.md b/docs/tips/logic.md deleted file mode 100644 index a59c0f2..0000000 --- a/docs/tips/logic.md +++ /dev/null @@ -1,95 +0,0 @@ -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 -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 function yourCustomHandler() - while true do - -- add your logic here - os.sleep(1) -- you need something which calls coroutine.yield(), yes os.sleep() does that and os.pullEvent() too - end -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 -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 thread = mainFrame:addThread() -- here we create a thread - -local function yourCustomHandler() - while true do - -- add your logic here - os.sleep(1) -- you need something which calls coroutine.yield(), yes os.sleep() does that and os.pullEvent() too - end -end -thread:start(yourCustomHandler) -- here we start the thread and pass the function which you want to run. -``` - -## 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. - -```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 timer = mainFrame:addTimer() -- here we will create the timer object - -local function yourCustomHandler() - -- add your logic here -end -timer:onCall(yourCustomHandler) - :setTime(1, -1) - :start() -- this will call your function every second until you :cancel() the timer -``` - -## 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 - -``` diff --git a/docs/tips/xml.md b/docs/tips/xml.md deleted file mode 100644 index 09b0351..0000000 --- a/docs/tips/xml.md +++ /dev/null @@ -1,79 +0,0 @@ -This is a basic guide on how to create a UI with XML. - -In XML you are not able to create logic, but you could refer to logic - i will show you how. -But first i will show you how you are able to create some basic XML design. - -First we will need a .lua file - we need to process the XML stuff, and this is only possible in lua. -So let's create a lua file: - -```lua -local basalt = require("basalt") -- as always we will need basalt - -local main = basalt.createFrame() -- and atleast 1 base frame is needed - -basalt.autoUpdate() -- starting the event and draw handler is also needed -``` - -The code above you are just not able to do in XML, you are not able to create base frames and you are also not able to start the event/draw handlers. -This can only be done in Lua. - -In Basalt XML Code will always be loaded into frames. Which means all the objects created in XML are always childrens of that particular frame. Here is a example to show what i mean: - -Lua: -```lua -local basalt = require("basalt") -local main = basalt.createFrame():addLayout("example.xml") -basalt.autoUpdate() -``` - -XML: -```xml -