updated & new guides

Author: emuell

docs/SUMMARY.md

@@ -14,13 +14,13 @@
   - [Sockets](guide/sockets.md)
   - [MIDI](guide/midi.md)
   - [OSC](guide/osc.md)
-  - [Pattern Iterator](guide/pattern_iterator.md)
-  - [Track Automation](guide/track_automation.md)
-  - [Sample Buffers](guide/sample_buffer.md)
-  - [Keybindings](guide/keybindings.md)
-  - [Menu Entries](guide/menus.md)
-  - [Views](guide/views.md)
-  - [Preferences](guide/preferences.md)
+  - [SQLite](guide/sqlite.md)
+  - [Renoise Application](guide/application.md)
+  - [Renoise Song](guide/song.md)
+  - [Tool Keybindings](guide/keybindings.md)
+  - [Tool Menu Entries](guide/menus.md)
+  - [Tool Views](guide/views.md)
+  - [Tool Preferences](guide/preferences.md)
 - [API Reference](API/README.md)
   <!-- API TOC START -->
   - [renoise](API/renoise.md)

docs/guide/README.md

@@ -1,3 +1,5 @@
 # Guides to the Renoise API
 
-In this section you can learn about different aspects of the API. These guides will assume you've already read the chapters in [our introduction](../start/development.md) and you are able to package and install tools.
+Welcome to the guides for the Renoise Scripting API.
+
+In this section, you can learn about different aspects of the API through practical examples and explanations. These guides assume you have already read the chapters in our [introduction](../start/development.md) and are familiar with how to package and install tools.

docs/guide/application.md

@@ -0,0 +1,178 @@
+# The Renoise Application
+
+The `renoise.app()` function is the entry point for interacting with the Renoise application itself. It returns a [`renoise.Application`](../API/renoise/renoise.Application.md) object, which provides access to global application states, functions for user interaction like dialogs, and control over the main window.
+
+## Controlling the Application Window
+
+The [`renoise.ApplicationWindow`](../API/renoise/renoise.ApplicationWindow.md) object, accessed via `renoise.app().window`, allows you to query and control the state of the main Renoise UI.
+
+```lua
+local window = renoise.app().window
+
+-- Toggle fullscreen mode
+window.fullscreen = not window.fullscreen
+
+-- Check if the disk browser is visible
+if window.disk_browser_is_visible then
+  print("Disk browser is currently open.")
+end
+
+-- Switch the middle frame to the Mixer view
+window.active_middle_frame = 
+  renoise.ApplicationWindow.MIDDLE_FRAME_MIXER
+```
+
+You can also attach notifiers to many window properties to react to UI changes made by the user.
+
+```lua
+local window = renoise.app().window
+
+-- Be notified when the disk browser visibility changes
+function disk_browser_visibility_changed()
+  if window.disk_browser_is_visible then
+    renoise.app():show_status("Disk browser was opened.")
+  else
+    renoise.app():show_status("Disk browser was closed.")
+  end
+end
+
+window.disk_browser_is_visible_observable:add_notifier(
+  disk_browser_visibility_changed
+)
+```
+
+## Song and File Handling
+
+The application object provides functions to load, and save songs, instrument and other kinds of components. Note that these operations are not always instantaneous, as Renoise may need to prompt the user to save changes. 
+
+To reliably execute code after a new song is created or loaded, you should use notifiers.
+
+```lua
+local app = renoise.app()
+
+-- This will show a file dialog to the user. The song is not loaded immediately.
+app:load_song("/path/to/some/song_file") 
+
+-- To run code after a new song is ready, use a notifier.
+-- This is typically done in your tool's initialization code.
+function handle_new_document()
+  print("A new song was created or loaded. The new song name is: " ..
+    renoise.song().name)
+end
+
+-- The 'new_document_observable' is fired after a new song is
+--- successfully created or loaded.
+renoise.tool().app_new_document_observable:add_notifier(handle_new_document)
+
+-- To save a song to a specific file:
+app:save_song_as("/path/to/MyNewSong.xrns")
+```
+
+## Showing Dialogs and Messages
+
+A common task for tools is to communicate with the user. The application object provides several functions to show different kinds of dialogs and messages.
+
+### Simple Messages
+
+For simple notifications, you can use `show_message`, `show_error`, `show_warning`, or `show_status`.
+
+```lua
+local app = renoise.app()
+
+-- Show a message in the status bar
+app:show_status("This is a status message.")
+
+-- Show a modal info dialog
+app:show_message("This is an informational message.")
+
+-- Show a modal warning dialog
+app:show_warning("This is a warning message.")
+
+-- Show a modal error dialog
+app:show_error("This is an error message.")
+```
+
+### User Prompts
+
+To ask the user for a choice, you can use `show_prompt`. It displays a dialog with custom buttons and returns the label of the button that was pressed.
+
+```lua
+local app = renoise.app()
+
+local pressed_button = app:show_prompt(
+  "Confirm Action", 
+  "Do you want to proceed?", 
+  { "Yes", "No", "Cancel" }
+)
+
+if pressed_button == "Yes" then
+  app:show_message("You chose to proceed.")
+elseif pressed_button == "No" then
+  app:show_message("You chose not to proceed.")
+else
+  app:show_message("You canceled the operation.")
+end
+```
+
+### Custom Dialogs
+
+For more complex user interfaces, you can create custom non-modal dialogs (tool windows) with `show_custom_dialog`. This requires using the `renoise.ViewBuilder` API to construct the UI.
+
+```lua
+-- A simple custom dialog example
+local vb = renoise.ViewBuilder()
+
+local my_dialog = nil
+local my_dialog_content = vb:column {
+  margin = renoise.ViewBuilder.DEFAULT_DIALOG_MARGIN,
+  spacing = renoise.ViewBuilder.DEFAULT_DIALOG_SPACING,
+  views = {
+    vb:text {
+      text = "This is a custom dialog."
+    },
+    vb:button {
+      text = "Close Me",
+      notifier = function()
+        -- my_dialog is defined when calling show_custom_dialog
+        my_dialog:close()
+      end
+    }
+  }
+}
+
+my_dialog = renoise.app():show_custom_dialog(
+  "My Tool Window", my_dialog_content
+)
+```
+
+## File and Path Prompts
+
+Your tool might need to read from or write to files. The API provides functions to open native file browser dialogs.
+
+```lua
+local app = renoise.app()
+
+-- Prompt the user to select a directory
+local dir_path = app:prompt_for_path("Select a Project Folder")
+if dir_path and #dir_path > 0 then
+  app:show_message("You selected the directory: " .. dir_path)
+end
+
+-- Prompt the user to select a file to open
+local file_to_read = app:prompt_for_filename_to_read(
+  { "txt", "lua" }, 
+  "Open a Text File"
+)
+if file_to_read and #file_to_read > 0 then
+  app:show_message("You selected the file: " .. file_to_read)
+end
+
+-- Prompt the user for a filename to save
+local file_to_write = app:prompt_for_filename_to_write(
+  "xml", 
+  "Save Configuration"
+)
+if file_to_write and #file_to_write > 0 then
+  app:show_message("File will be saved to: " .. file_to_write)
+end
+```

docs/guide/classes.md

@@ -1,16 +1,15 @@
 # Classes
 
-The Lua language has by default no `class` construct. But the Renoises lua API has a simple OO support inbuilt -> `class "MyClass"`. All Renoise API objects use such classes and you can use them too in your tools.
+The Lua language does not have a built-in `class` construct. However, the Renoise Lua API provides simple object-oriented programming support via a global `class()` function. All Renoise API objects use such classes, and you can use them in your tools as well.
 
-See [luabind docs](https://www.rasterbar.com/products/luabind/docs.html#defining-classes-in-lua)
-for more technical info and below for some simple examples
+See the [luabind documentation](https://www.rasterbar.com/products/luabind/docs.html#defining-classes-in-lua) for more technical information, and the examples below for how to use them.
 
 ## Examples
 
 ```lua
 -- abstract class
-
 class 'Animal'
+
   function Animal:__init(name)
     self.name = name
     self.can_fly = nil
@@ -19,29 +18,32 @@ class 'Animal'
   function Animal:__tostring()
     assert(self.can_fly ~= nil, "I don't know if I can fly or not")
 
-    return ("I am a %s (%s) and I %s fly"):format(self.name, type(self), 
-      (self.can_fly and "can fly" or "can not fly"))
+    return ("I am a %s (%s) and I %s"):format(self.name, type(self), 
+      (self.can_fly and "can fly" or "cannot fly"))
   end
 
 
 -- derived classes
 
 -- MAMMAL
 class 'Mammal' (Animal)
+
   function Mammal:__init(str)
     Animal.__init(self, str)
     self.can_fly = false
   end
 
 -- BIRD
 class 'Bird' (Animal)
+
   function Bird:__init(str)
     Animal.__init(self, str)
     self.can_fly = true
   end
 
 -- FISH
 class 'Fish' (Animal)
+
   function Fish:__init(str)
     Animal.__init(self, str)
     self.can_fly = false
@@ -50,50 +52,43 @@ class 'Fish' (Animal)
 
 -- run
 
-local farm = table.create()
+local farm = {}
 
-farm:insert(Mammal("cow"))
-farm:insert(Bird("sparrow"))
-farm:insert(Fish("bass"))
+table.insert(farm, Mammal("cow"))
+table.insert(farm, Bird("sparrow"))
+table.insert(farm, Fish("bass"))
 
 print(("type(Mammal('cow')) -> %s"):format(type(Mammal("cow"))))
 print(("type(Mammal) -> %s"):format(type(Mammal)))
 
-for _,animal in pairs(farm) do
+for _,animal in ipairs(farm) do
   print(animal)
 end
 ```
 
 Something to keep in mind:
 
-* constructor `function MyClass:__init(args)` must be defined for each class, 
-  or the class can't be used to instantiate objects.
-  
-* class defs are always global, so even locally defined classes will be 
-  registered globally.
+*   A constructor, `function MyClass:__init(args)`, must be defined for each class, or the class cannot be used to instantiate objects.
+*   Class definitions are always global, so even locally defined classes will be registered globally.
 
 
 ## Class operators
 
-You can overload most operators in Lua for your classes. You do this by 
-simply declaring a member function with the same name as an operator 
-(the name of the metamethods in Lua).
+You can overload most operators in Lua for your classes. You do this by simply declaring a member function with the same name as an operator's corresponding metamethod in Lua.
 
 The operators you can overload are:
 
-* __add
-* __sub
-* __mul
-* __div
-* __pow
-* __lt
-* __le
-* __eq
-* __call
-* __unm
-* __tostring
-* __len
-
-Note: `__tostring` isn't really an operator, but it's the metamethod that is 
-called by the standard library's tostring() function. 
-
+*   `__add` (addition)
+*   `__sub` (subtraction)
+*   `__mul` (multiplication)
+*   `__div` (division)
+*   `__pow` (exponentiation)
+*   `__lt` (less than)
+*   `__le` (less than or equal to)
+*   `__eq` (equality)
+*   `__call` (function call)
+*   `__unm` (unary minus)
+*   `__tostring`
+*   `__len` (length operator `#`)
+
+Note: `__tostring` isn't really an operator, but it's the metamethod that is called by the standard library's `tostring()` function.

docs/guide/files&bits.md

@@ -1,18 +1,19 @@
-# Files&Bits.lua
+# Files & Bits
 
-In order to access the raw bits and bytes of some data, e.g. to read or write binary (file) streams, you can use the Lua `bit` library. It's built into the Renoise API. There's no need to `require` it.  
+To access the raw bits and bytes of some data, for example, to read or write binary file streams, you can use the `bit` library. It's built into the Renoise API, so there's no need to `require` it.
 
-See [bit documentation](https://bitop.luajit.org/) for more info and examples.
+See the [LuaJIT bit library documentation](https://bitop.luajit.org/api.html) for more info and examples. For file operations, you can use Lua's standard [io library](https://www.lua.org/pil/21.html).
 
 ```lua
--- reading integer numbers or raw bytes from a file
+-- Reading integer numbers or raw bytes from a file
 
 local function read_word(file)
   local bytes = file:read(2)
   if (not bytes or #bytes < 2) then 
     return nil 
   else
-    return bit.bor(bytes:byte( 1),
+    -- little-endian
+    return bit.bor(bytes:byte(1),
       bit.lshift(bytes:byte(2), 8))
   end
 end
@@ -22,16 +23,21 @@ local function read_dword(file)
   if (not bytes or #bytes < 4) then 
     return nil 
   else
+    -- little-endian
     return bit.bor(bytes:byte(1),
       bit.lshift(bytes:byte(2), 8),
       bit.lshift(bytes:byte(3), 16),
       bit.lshift(bytes:byte(4), 24))  
   end   
 end
 
--- and so on (adapt as needed to mess with endianess!) ...
+-- and so on (adapt as needed to mess with endianness!) ...
 
-local file = io.open("some_binary_file.bin", "rb")
+local file, err = io.open("some_binary_file.bin", "rb")
+if not file then
+  print("Could not open file: " .. tostring(err))
+  return
+end
 
 local bytes = file:read(512)
 
@@ -45,5 +51,6 @@ end
 
 print(read_word(file) or "unexpected end of file")
 print(read_dword(file) or "unexpected end of file")
-```
 
+file:close()
+```