From a34b7270ec2aac691732a1688d93989a4c23a40a Mon Sep 17 00:00:00 2001
From: Robert Jelic <36573031+NoryiE@users.noreply.github.com>
Date: Sun, 26 Jun 2022 18:23:04 +0200
Subject: [PATCH] Update Dropdown.md

---
 docs/objects/Dropdown.md | 249 +++++++++++++++++++++++++++++----------
 1 file changed, 184 insertions(+), 65 deletions(-)

diff --git a/docs/objects/Dropdown.md b/docs/objects/Dropdown.md
index ba649d6..98adaf8 100644
--- a/docs/objects/Dropdown.md
+++ b/docs/objects/Dropdown.md
@@ -1,18 +1,32 @@
-Dropdowns are objects where you can create endless entrys the user can click on a button and it opens a "list" where the user can choose a entry
+Dropdowns are objects where the user can click on a button, this will open a list where the user can choose from.
 
-Here is a example of how to create a standard dropdown:
+If you want to access values inside items this is how the table for single items is made (just a example):
 
 ```lua
-local mainFrame = basalt.createFrame("myFirstFrame"):show()
-local aDropdown = mainFrame:addDropdown("myFirstDropdown"):show()
+item = {
+  text="1. Entry", 
+  bgCol=colors.black, 
+  fgCol=colors.white
+  args = {}
+}
 ```
 
-Here are all possible functions available for dropdowns: <br>
 Remember Dropdown also inherits from [Object](objects/Object.md)
 
 ## addItem
-Adds a item to the dropdown
+Adds a item into the dropdown
 
+#### Parameters: 
+1. `string` The entry name
+2. `number|color` unique default background color - optional
+3. `number|color` unique default text color - optional
+4. `any` any value - you could access this later in a :onChange() event (you need to use :getValue()) - optional
+
+#### Returns:
+1. `object` The object in use
+
+#### Usage:
+* Creates a default dropdown with 3 entries
 ```lua
 local mainFrame = basalt.createFrame("myFirstFrame"):show()
 local aDropdown = mainFrame:addDropdown("myFirstDropdown"):show()
@@ -20,12 +34,18 @@ aDropdown:addItem("1. Entry")
 aDropdown:addItem("2. Entry",colors.yellow)
 aDropdown:addItem("3. Entry",colors.yellow,colors.green)
 ```
-#### Parameters: string text, number bgcolor, number fgcolor, any ... - (text is the displayed text, bgcolor and fgcolors the colors of background/text and args (...) is something dynamic, you wont see them but if you require some more information per item you can use that)<br>
-#### Returns: self<br>
 
 ## removeItem
 Removes a item from the dropdown
 
+#### Parameters: 
+1. `number` The index which should get removed
+
+#### Returns:
+1. `object` The object in use
+
+#### Usage:
+* Creates a default dropdown with 3 entries and removes the second one.
 ```lua
 local mainFrame = basalt.createFrame("myFirstFrame"):show()
 local aDropdown = mainFrame:addDropdown("myFirstDropdown"):show()
@@ -34,26 +54,96 @@ aDropdown:addItem("2. Entry",colors.yellow)
 aDropdown:addItem("3. Entry",colors.yellow,colors.green)
 aDropdown:removeItem(2)
 ```
-#### Parameters: number index<br>
-#### Returns: self<br>
 
 ## editItem
-Edits a item on the dropdown
+Edits a item from the dropdown
 
+#### Parameters: 
+1. `number` The index which should be edited
+2. `string` The new item name
+3. `number` the new item background color - optional
+4. `number` The new item text color - optional
+5. `any` New additional information - optional
+
+#### Returns:
+1. `object` The object in use
+
+#### Usage:
+* Creates a default dropdown with 3 entries and edits the second one.
 ```lua
 local mainFrame = basalt.createFrame("myFirstFrame"):show()
 local aDropdown = mainFrame:addDropdown("myFirstDropdown"):show()
 aDropdown:addItem("1. Entry")
 aDropdown:addItem("2. Entry",colors.yellow)
 aDropdown:addItem("3. Entry",colors.yellow,colors.green)
-aDropdown:editItem(3,"3. Edited Entry",colors.yellow,colors.green)
+aDropdown:editItem(2, "Still 2. Entry", colors.red)
+```
+
+## getItem
+Returns a item by index
+
+#### Parameters: 
+1. `number` The index which should be returned
+
+#### Returns:
+1. `table` The item table example: {text="1. Entry", bgCol=colors.black, fgCol=colors.white}
+
+#### Usage:
+* Creates a default dropdown with 3 entries and edits the second one.
+```lua
+local mainFrame = basalt.createFrame("myFirstFrame"):show()
+local aDropdown = mainFrame:addDropdown("myFirstDropdown"):show()
+aDropdown:addItem("1. Entry")
+aDropdown:addItem("2. Entry",colors.yellow)
+aDropdown:addItem("3. Entry",colors.yellow,colors.green)
+basalt.debug(aDropdown:getItem(2).text)
+```
+
+## getItemCount
+Returns the current item count
+
+#### Returns:
+1. `number` The item list count
+
+#### Usage:
+* Creates a default dropdown with 3 entries and prints the current item count.
+```lua
+local mainFrame = basalt.createFrame("myFirstFrame"):show()
+local aDropdown = mainFrame:addDropdown("myFirstDropdown"):show()
+aDropdown:addItem("1. Entry")
+aDropdown:addItem("2. Entry",colors.yellow)
+aDropdown:addItem("3. Entry",colors.yellow,colors.green)
+basalt.debug(aDropdown:getItemCount())
+```
+
+## getAll
+Returns all items as table
+
+#### Returns:
+1. `table` All items
+
+#### Usage:
+* Creates a default menubar with 3 entries and prints a table.
+```lua
+local mainFrame = basalt.createFrame("myFirstFrame"):show()
+local aDropdown = mainFrame:addDropdown("myFirstDropdown"):show()
+aDropdown:addItem("1. Entry")
+aDropdown:addItem("2. Entry",colors.yellow)
+aDropdown:addItem("3. Entry",colors.yellow,colors.green)
+basalt.debug(aDropdown:getAll())
 ```
-#### Parameters: number index, string text, number bgcolor, number fgcolor, any ...<br>
-#### Returns: self<br>
 
 ## setScrollable
-Makes the dropdown scrollable
+Makes the dropdown scrollable.
 
+#### Parameters: 
+1. `boolean` if the dropdown should be scrollable or not
+
+#### Returns:
+1. `object` The object in use
+
+#### Usage:
+* Creates a default dropdown with 3 entries and makes it scrollable.
 ```lua
 local mainFrame = basalt.createFrame("myFirstFrame"):show()
 local aDropdown = mainFrame:addDropdown("myFirstDropdown"):show()
@@ -62,26 +152,35 @@ aDropdown:addItem("2. Entry",colors.yellow)
 aDropdown:addItem("3. Entry",colors.yellow,colors.green)
 aDropdown:setScrollable(true)
 ```
-#### Parameters: boolean isScrollable<br>
-#### Returns: self<br>
 
 ## selectItem
 selects a item in the dropdown (same as a player would click on a item)
 
+#### Parameters: 
+1. `number` The index which should get selected
+
+#### Returns:
+1. `object` The object in use
+
+#### Usage:
+* Creates a default dropdown with 3 entries and selects the second entry.
 ```lua
 local mainFrame = basalt.createFrame("myFirstFrame"):show()
 local aDropdown = mainFrame:addDropdown("myFirstDropdown"):show()
 aDropdown:addItem("1. Entry")
 aDropdown:addItem("2. Entry",colors.yellow)
 aDropdown:addItem("3. Entry",colors.yellow,colors.green)
-aDropdown:selectItem(1)
+aDropdown:selectItem(2)
 ```
-#### Parameters: number index<br>
-#### Returns: self<br>
 
 ## clear
-clears the entire list (dropdown)
+Removes all items.
 
+#### Returns:
+1. `object` The object in use
+
+#### Usage:
+* Creates a default dropdown with 3 entries and removes them immediatley. Which makes no sense.
 ```lua
 local mainFrame = basalt.createFrame("myFirstFrame"):show()
 local aDropdown = mainFrame:addDropdown("myFirstDropdown"):show()
@@ -90,89 +189,109 @@ aDropdown:addItem("2. Entry",colors.yellow)
 aDropdown:addItem("3. Entry",colors.yellow,colors.green)
 aDropdown:clear()
 ```
-#### Parameters: -<br>
-#### Returns: self<br>
 
 ## getItemIndex
 returns the item index of the currently selected item
 
+#### Returns:
+1. `number` The current index
+
+#### Usage:
+* Creates a default dropdown with 3 entries selects the second entry and prints the currently selected index.
 ```lua
 local mainFrame = basalt.createFrame("myFirstFrame"):show()
 local aDropdown = mainFrame:addDropdown("myFirstDropdown"):show()
 aDropdown:addItem("1. Entry")
 aDropdown:addItem("2. Entry",colors.yellow)
 aDropdown:addItem("3. Entry",colors.yellow,colors.green)
-aDropdown:getItemIndex()
+aDropdown:selectItem(2)
+basalt.debug(aDropdown:getItemIndex())
 ```
-#### Parameters: -<br>
-#### Returns: number index<br>
 
 ## setSelectedItem
-Sets the background of the item which is currently selected
+Sets the background and the foreground of the item which is currently selected
 
+#### Parameters: 
+1. `number|color` The background color which should be used
+2. `number|color` The text color which should be used
+
+#### Returns:
+1. `object` The object in use
+
+#### Usage:
+* Creates a default dropdown with 4 entries and sets the selection background color to green.
 ```lua
 local mainFrame = basalt.createFrame("myFirstFrame"):show()
 local aDropdown = mainFrame:addDropdown("myFirstDropdown"):show()
 aDropdown:addItem("1. Entry")
 aDropdown:addItem("2. Entry",colors.yellow)
 aDropdown:addItem("3. Entry",colors.yellow,colors.green)
-aDropdown:setSelectedItem(colors.green, colors.blue)
+aDropdown:addItem("4. Entry")
+aDropdown:setSelectedItem(colors.green)
 ```
-#### Parameters: number bgcolor, number fgcolor, boolean isActive (isActive means if different colors for selected item should be used)<br>
-#### Returns: self<br>
 
-## setOffset
-sets the dropdown offset (will automatically change if scrolling is active)
+## setIndexOffset
+Sets the offset of the dropdown (the same as you would scroll) - default is 0
 
+#### Parameters: 
+1. `number` The offset value
+
+#### Returns:
+1. `object` The object in use
+
+#### Usage:
+* Creates a default dropdown with 6 entries and sets the offset to 3.
 ```lua
 local mainFrame = basalt.createFrame("myFirstFrame"):show()
 local aDropdown = mainFrame:addDropdown("myFirstDropdown"):show()
 aDropdown:addItem("1. Entry")
-aDropdown:addItem("2. Entry",colors.yellow)
-aDropdown:addItem("3. Entry",colors.yellow,colors.green)
-aDropdown:setOffset(3)
+aDropdown:addItem("2. Entry")
+aDropdown:addItem("3. Entry")
+aDropdown:addItem("4. Entry")
+aDropdown:addItem("5. Entry")
+aDropdown:addItem("6. Entry")
+aDropdown:setIndexOffset(3)
 ```
-#### Parameters: number offsetValue<br>
-#### Returns: self<br>
 
-## getOffset
-returns the current offset
 
+## getIndexOffset
+Returns the current index offset
+
+#### Returns:
+1. `number` offset value
+
+#### Usage:
+* Creates a default dropdown with 6 entries and sets the offset to 3, also prints the current offset.
 ```lua
 local mainFrame = basalt.createFrame("myFirstFrame"):show()
 local aDropdown = mainFrame:addDropdown("myFirstDropdown"):show()
 aDropdown:addItem("1. Entry")
-aDropdown:addItem("2. Entry",colors.yellow)
-aDropdown:addItem("3. Entry",colors.yellow,colors.green)
-aDropdown:getOffset()
+aDropdown:addItem("2. Entry")
+aDropdown:addItem("3. Entry")
+aDropdown:addItem("4. Entry")
+aDropdown:addItem("5. Entry")
+aDropdown:addItem("6. Entry")
+aDropdown:setIndexOffset(3)
+basalt.debug(aDropdown:getIndexOffset())
 ```
-#### Parameters: -<br>
-#### Returns: number offsetValue<br>
-
-## getOffset
-returns the current offset
-
-```lua
-local mainFrame = basalt.createFrame("myFirstFrame"):show()
-local aDropdown = mainFrame:addDropdown("myFirstDropdown"):show()
-aDropdown:addItem("1. Entry")
-aDropdown:addItem("2. Entry",colors.yellow)
-aDropdown:addItem("3. Entry",colors.yellow,colors.green)
-aDropdown:getOffset()
-```
-#### Parameters: -<br>
-#### Returns: number offsetValue<br>
 
 ## setDropdownSize
-sets the dropdown size (if you click on the button)
+Sets the size of the opened dropdown
 
+#### Parameters: 
+1. `number` The width value
+2. `number` The height value
+
+#### Returns:
+1. `object` The object in use
+
+#### Usage:
+* Creates a default dropdown, adds 3 entries and sets the dropdown size to 15w, 8h
 ```lua
 local mainFrame = basalt.createFrame("myFirstFrame"):show()
-local aDropdown = mainFrame:addDropdown("myFirstDropdown"):show()
+local aDropdown = mainFrame:addDropdown("myFirstDropdown"):setDropdownSize(15,8):show()
 aDropdown:addItem("1. Entry")
-aDropdown:addItem("2. Entry",colors.yellow)
-aDropdown:addItem("3. Entry",colors.yellow,colors.green)
-aDropdown:setDropdownSize(12, 4)
+aDropdown:addItem("2. Entry")
+aDropdown:addItem("3. Entry")
 ```
-#### Parameters: number width, number height<br>
-#### Returns: self<br>
\ No newline at end of file
+