TOML configuration guide for Tool-Tree

This guide is for Tool-Tree, the component that powers the function menu in the com.tool.tree Android app. All page configuration files must use TOML (XML is no longer supported). The parser lives in com.omarea.krscript.config.PageConfigReader and uses the org.tomlj:tomlj library.

A TOML configuration file describes the node tree of a page: each page is a list of nodes (group, action, switch, picker, text, page, editor, download, resource, menu, fab) displayed in the order they appear in the file. Nodes can be nested (e.g. [[group.action]] is an action inside a group) to build a hierarchical tree.

2. Syntax rules

2.1. Always use double brackets [[name]] for every entry

TOML does not allow mixing [name] (single brackets, single table) and [[name]] (double brackets, array of tables) for the same key at the same position - this will cause a parse error. To be safe, always use [[name]] for any entry, even if there is currently only one entry of that type. This prevents breaking the file later when you add a second entry of the same type but forget to switch the brackets.

2.2. Node type = TOML table name

There is no separate type field. A node's type is determined by its TOML table name:

2.3. Nesting = dotted path

A child node of a group is declared using the dotted path [[group.type]] (or [[group.subgroup.type]] for deeper nesting). Child nodes always belong to the most recently declared group above them in the file.

2.4. Display order = position in file

Display order is always top-to-bottom by the position of the [[name]] entry in the file, regardless of node type (group, action, page, text, switch ...) - even when types are interleaved (e.g. an action, then a page, then another action). The position is read directly from the tomlj API, so there is no need for an order field.

2.5. Boolean values - 3 accepted forms

Boolean fields such as confirm, readonly, auto-off accept:

Example: readonly = "test -f /sdcard/lock && echo 1" - the parser runs that command, and if it returns "1" then readonly = true.

2.6. String resource references

Any text field (title, desc, summary ...) may include a reference to the app's string resources via @string/name or @string:name. The parser resolves these automatically. If the resource is not found, the original string is kept.

3. Node type overview

Quick reference for all node types. Click a name to jump to its detailed section.

4. Shared fields (NodeInfoBase + ClickableNode + RunnableNode)

These are the fields that every node has (inherited from NodeInfoBase). All text fields accept @string/... references.

4.1. NodeInfoBase (present on every node)

4.2. ClickableNode (for page, action, switch, picker, editor, download)

4.3. RunnableNode (for action, switch, picker, download)

5. [[group]] - Container for child nodes

[[group]] is a container that groups related nodes. It has no icon and is not clickable - it's just a title with a list of child nodes below it.

5.1. Group fields

5.2. Demo

5.3. Multi-level nesting

Groups can be nested inside other groups to build deep trees:

6. [[page]] - Sub-page

[[page]] is not an action - it's a link to another page. Clicking it opens a new page (another .toml file, an HTML page, or another Activity).

6.1. Page fields

6.2. Demo

7. [[action]] - Action (runs a shell script)

[[action]] is the most common node type: clicking it shows a dialog (if it has confirm/params/warning), then runs the script and shows the output in a log dialog.

7.1. Action fields

7.2. Demo

8. [[action.params]] - Input parameters

Each [[action.params]] defines one input field in the dialog shown when the user clicks an action. The parameter's value is passed to the action's script via the $param_name environment variable.

8.1. Basic param fields

8.2. Common type values

8.3. Demo

8.4. Dependencies (depend-*)

A param can be hidden/shown (or switched to readonly) based on the value of another param. This is a large feature - see section 17 for details.

9. [[switch]] - On/off toggle

[[switch]] displays an ON/OFF toggle. When the user toggles it, the set script is called with the env var $state set to "1" or "0". When the page loads, the get script is called to read the current state.

9.1. Switch fields

9.2. Demo

10. [[picker]] - Value selector

[[picker]] displays a current value; clicking it opens a popup to choose one (or more) values from a list. When the user confirms, the set script is called with $state = the chosen value.

10.1. Picker fields

10.2. Demo

11. [[text]] - Rich text block

[[text]] is a non-clickable display block containing multiple rich-text rows. Use it for notices, instructions, or inline image/gif blocks.

11.1. Text fields

11.2. Demo

12. [[text.rows]] - Rich text row

This is the most common display component: used in [[text]], [[action]], [[page]], [[download]] and [[group.action.params-rows]]. Each row is a single line of text that can have style, icon, toggle, photo, etc.

12.1. Row fields

12.2. Demo

13. [[editor]] - Open file in the text editor

[[editor]] lets the user open a file in the built-in text editor (TextEditorActivity) to view or edit it. If the file does not exist, the editor creates it when the user saves.

13.1. Editor fields

13.2. Demo

14. [[download]] - Download a file via HTTP

[[download]] is a new node type that displays download progress directly in the item (no separate dialog). When download completes, it runs the script with the env var $state = path of the downloaded file (cached, random name).

14.1. Download fields

14.2. Demo

15. [[resource]] - Extract assets

[[resource]] is an invisible node (it returns null after initialization). It only extracts assets from the APK to storage (typically /data/data/<pkg>/files/... or cache). This is how to ship script files, images, etc. from the APK to outside so shell can call them.

You can also put resource-file/resource-dir fields directly inside [[group]]/[[action]]/[[page]]/[[switch]]/[[picker]]/[[text]] - no need to declare a separate [[resource]] entry.

15.1. Fields

16. [[menu]] / [[fab]] - Overflow menu and FAB

This feature replaces the old [[page.options]] mechanism (declared in the parent page, built eagerly even when the sub-page was never opened). Now the menu and FAB are declared directly inside the page's own TOML file, just like [[action]]/[[text]] - they are only read (and only their inner shell runs) when the page is actually opened.

16.1. Structure

A [[menu]] or [[fab]] block is a container, NOT a single entry:

• handler (or handler-sh): the DEFAULT script that runs when clicking a child item, if that item does not declare its own script
• [[...items]]: the list of items shown in the menu/fab - each item uses the same fields as the old [[page.options]] (type/style/suffix/mime/path-home/multiple/box/silent/link/activity/html/config/config-sh/script/title...)

16.2. Item fields (inside menu/fab)

16.3. Demo

17. Dependencies (depend-*)

This is the largest feature of [[action.params]]: a param can be hidden/shown (or switched to readonly) based on the value of one (or more) other params in the same action. This is how to build complex dialogs that are still easy to manage - the UI auto-hides irrelevant fields when the user picks a different mode.

17.1. depend-* fields (only for [[action.params]])

17.2. Demo - simple dependency

17.3. depend-logic reference

17.4. depend-default and depend-initial

By default, when no condition matches, the param is shown. To change the default to hidden:

18. Shell-script fields - overview

In Tool-Tree, many fields accept either a static value (string/bool) or a dynamic shell script. The parser runs the script and uses its output as the value. Here is a summary of all shell-style fields:

19. resolveBoolOrShell

The resolveBoolOrShell() function parses fields that can take either a static boolean or a shell command. If the string evaluates to "true" or "1", it resolves to true. For non-boolean strings, it executes the shell script in the background; if the command output equals "1", it returns true, otherwise false.

20. Pending states

To maximize performance when parsing large configuration files, dynamic shell evaluations for nodes (such as get scripts for switches or lock checks) are queued into pending state batches rather than executed synchronously one by one. Once reading finishes, all pending states run asynchronously to update node UI values in a single pass.

21. process = true

Setting process = true on a [[page]] instructs the rendering engine to build and render child nodes progressively on the UI as they are parsed, accompanied by a linear progress indicator, rather than holding display until the entire tree has loaded.

22. Page lifecycle

Sub-pages trigger lifecycle callbacks during initialization and reading. before-load executes before parsing begins, followed by after-load upon parsing completion. Dependent on the parse status, load-ok or load-fail shell scripts execute accordingly.

23. Full example

A representative TOML configuration showcasing groups, actions, parameters, switches, and rich text rows:

[[group]]
title = "System Performance"

[[group.switch]]
title = "Performance Mode"
desc = "Enable performance governor"
get = "getprop sys.perf.mode"
set = "setprop sys.perf.mode $state"

[[group.action]]
title = "Set CPU Frequency"
script = "echo $freq > /sys/devices/system/cpu/cpu0/cpufreq/scaling_max_freq"

[[group.action.params]]
name = "freq"
title = "Frequency (kHz)"
type = "spinner"

[[group.action.params.options]]
title = "Mode 1"
value = "1800000"

[[group.action.params.options]]
title = "Mode 2"
value = "2200000"

24. Tips & pitfalls

• Always use double brackets [[node]] across all declarations to prevent TOML table array parser exceptions.
• Keep nesting structures under 3 levels deep to maintain responsive UI performance and code clarity.
• Use selective refresh via reload = "id1,id2" instead of reloading the entire page after action execution.