Skip to content

armgit / BUI

Public Imported from GitHub
0

Blender's GPU Accelerated UI, Decoupled from it's original codebase. Supports Rust, Python, JS, React, C & C++. Twice as good as GPUI

docs: filebrowser

nusaturn64ab193e312a
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 71b7242..38dca1e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -67,6 +67,20 @@ All notable changes to **blenderui** (BUI). The format follows
- **`fill=True`**: in a column, the component takes the spare height, as a region fills its area.
- **`tools/blender_compare.py`**: renders BUI's version of a piece of Blender's UI next to a capture from a real Blender. **`tools/png_pixels.py`** reads pixels from PNGs.
+### Added (file browser)
+- **Blender's File Browser** (`kit/intern/kit_filebrowser.c` and the `kit_file*` / `kit_fsmenu.c` files), ported from `editors/space_file`. The Blender sources are in `ui/space_file` for reference.
+ - **Node:** `BK_node_new("filebrowser")`, with properties for the folder, file name, mode (open, save, folder), multiple selection, filters, sorting and search. It is the whole browser:
+ - bookmark panels: Volumes, System, Bookmarks (saved to `bookmarks.txt`) and Recent;
+ - the folder path bar;
+ - the file list: Name, Date Modified and Size columns; click a header to sort;
+ - the execute bar.
+ - **Keys:** Blender's file browser keymap. Return, Backspace, Alt+arrows for history, Ctrl+H for hidden files, Ctrl+B to bookmark, I for a new folder, F2 to rename, R to refresh, A / Alt+A to (de)select all.
+ - **Dialog:** `BK_file_dialog` shows the browser in its own window and returns the chosen paths.
+ - **Speed:** dates, sizes and icons are computed when a row is first drawn, and hover redraws only the changed rows.
+ - **Platforms:** Linux, BSD and macOS (`kit_filebrowser_posix.c`), and Windows (`kit_filebrowser_win32.c`).
+- **Python:** `bui.filebrowser.ask("open" | "save" | "directory", ...)`. `tkinter.filedialog` (through `bui.tksyntax`) and `QFileDialog` (through `bui.qtsyntax`) now show this browser. Set `BUI_FILEDIALOG=native` to get the operating system's dialogs instead.
+- **Theme:** the `space_file` colors (`file_back`, `file_text`, `file_header`, `file_row_alternate`).
+
### Added (platforms)
- **Linux: native windows on X11** (`kit/intern/kit_window_x11.c`, the same `BK_window_*` API as Win32). Wayland sessions run it through XWayland.
- **Input:** button and key mapping after Blender's `GHOST_SystemX11`; key repeat filtered.
diff --git a/docs/c-api.md b/docs/c-api.md
index 12a0e1b..ab9b56d 100644
--- a/docs/c-api.md
+++ b/docs/c-api.md
@@ -85,6 +85,7 @@ int main(void)
| **Text** | `BUI_text_measure`, `BUI_raster_text`, `BUI_text_add_font(family, flags, data, len)` (register a font; needed on wasm) |
| **Specialised** | Canvas display list (`BK_canvas_set_item`), text area (`BK_textarea_*`), trees (`BK_tree_item_*`), menus (`BK_open_menu`, `BK_open_pie`), color ramps and curves, `BK_undo` / `BK_redo` |
| **Custom nodes** | A `custom` node draws and handles input itself: `BK_custom_set(node, &cls, data)` with `event` (pointer with all three buttons and a grab, precise wheel via `BK_scroll`, keys and text while focused, key releases, focus), `frame` (called by `BK_render` when requested with `BK_custom_request_frame(node, ms)`: immediate-mode UIs build their frame there) and `draw` (raster + rect). `BK_custom_set_cursor`, `BK_node_context`. Dear ImGui runs on it: [../bindings/imgui](../bindings/imgui/README.md). |
+| **File browser** | `BK_node_new("filebrowser")`: Blender's File Browser in any window. Strings `dir`, `file`, `button`, `search`; numbers `mode` (0 open, 1 save, 2 directory), `multiple`, `hidden`, `sort`, `invert`; list `filters` (`"Label\tpattern ..."`); read `state` and `result`. `BK_file_dialog(title, mode, dir, file, filters, n, multiple, &paths)` runs one in its own window and returns the number of chosen paths (free them with `BK_file_dialog_free`). |
| **Meshes and textures** | `BUI_texture_create/update/free` (RGBA8, shared by every raster and GPU device), `BUI_raster_mesh(r, vertices, n, indices, n_idx, flags, tex, clip, ox, oy)`: indexed triangles with position, UV and color, straight-alpha blending, per-call clip; the same pixels on the software raster, Direct3D 11 and OpenGL. |
Node types: `frame column row grid box panel tabs sidetabs scroll scrollbar
diff --git a/docs/components.md b/docs/components.md
index 79fb911..236223a 100644
--- a/docs/components.md
+++ b/docs/components.md
@@ -242,6 +242,24 @@ tkinter and Qt).
- **Keyboard.** Tab and Shift+Tab move to the next or previous field while
editing. Escape cancels.
+## File dialogs
+
+`bui.filebrowser.ask` shows Blender's File Browser in its own window and waits
+for an answer:
+
+```python
+from bui import filebrowser
+
+path = filebrowser.ask("open", title="Open Image",
+ filetypes=[("Images", "*.png *.jpg"), ("All files", "*")])
+folder = filebrowser.ask("directory")
+paths = filebrowser.ask("open", multiple=True) # a list
+name = filebrowser.ask("save", defaultextension=".txt")
+```
+
+`kind` is `"open"`, `"save"` or `"directory"`. Cancel returns `None`.
+`tkinter.filedialog` and `QFileDialog` use the same browser.
+
## Headless use (tests, screenshots)
```python
diff --git a/docs/getting-started.md b/docs/getting-started.md
index f4cae43..2428d87 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -86,6 +86,8 @@ shared (`bui.host`).
| `BUI_FONT`, `BUI_FONT_DIR` | A font file to replace the embedded Inter UI font, and an extra font folder |
| `BUI_SLUG` | `0` draws GPU text from a per-glyph bitmap atlas instead of glyph outlines (Slug); `1` forces Slug. Overrides `bui.set_slug()` / `.slug()` / `BUI_gpu_set_slug()` |
| `BUI_PROFILE=1` | Print per-phase frame times (raster and present) |
+| `BUI_FILEDIALOG=native` | File dialogs (`tkinter.filedialog`, `QFileDialog`) use the operating system's dialogs instead of Blender's File Browser |
+| `BUI_BOOKMARKS` | The file browser's bookmarks file (default `$XDG_CONFIG_HOME/bui/bookmarks.txt`, or `%APPDATA%\bui\bookmarks.txt` on Windows) |
## Window hosts
diff --git a/docs/qt.md b/docs/qt.md
index 5deb073..3f4c820 100644
--- a/docs/qt.md
+++ b/docs/qt.md
@@ -93,7 +93,7 @@ is much lower. See [getting-started.md](getting-started.md#gpu-rendering).
| Painting | `QPainter` (`fillRect`, `drawRect`, `drawRoundedRect`, `drawEllipse`, `drawLine`, `drawPolyline`, `drawPolygon`, `drawArc`, `drawPie`, `drawText`, `drawPixmap`, `translate`, `save`, `restore`, `setOpacity`), `QPen`, `QBrush`, `QColor`, `QFont`, `QPixmap` / `QImage` |
| Events | Override `mousePressEvent`, `mouseReleaseEvent`, `mouseMoveEvent`, `mouseDoubleClickEvent`, `keyPressEvent`, `wheelEvent`, `enterEvent`, `leaveEvent`, `closeEvent`, `paintEvent`. Event types: `QMouseEvent`, `QKeyEvent`, `QWheelEvent`, `QPaintEvent`, `QCloseEvent`. |
| Values | `Qt` constants (alignment, keys, orientation, check states), `QPoint`, `QSize`, `QRect`, `QMargins`, `QSizePolicy`, `QIcon` |
-| Dialogs | `QMessageBox` (static calls return immediately; not drawn yet), `QFileDialog` (the OS file dialogs) |
+| Dialogs | `QMessageBox` (static calls return immediately; not drawn yet), `QFileDialog` (`getOpenFileName(s)`, `getSaveFileName`, `getExistingDirectory`: Blender's File Browser; `BUI_FILEDIALOG=native` for the OS dialogs) |
Member-by-member tables: [../SYNTAX_COVERAGE.md](../SYNTAX_COVERAGE.md#qt-syntax-buiqtsyntax).
diff --git a/docs/tkinter.md b/docs/tkinter.md
index a9845f8..3f181fd 100644
--- a/docs/tkinter.md
+++ b/docs/tkinter.md
@@ -31,6 +31,12 @@ from tkinter import ttk
`filedialog`, `simpledialog`, `colorchooser`, `commondialog`, `dialog`,
`font`, `scrolledtext` and `constants`.
+`filedialog` (`askopenfilename`, `asksaveasfilename`, `askopenfilenames`,
+`askdirectory`, ...) shows Blender's File Browser in its own window. It accepts
+tkinter's options (`title`, `initialdir`, `initialfile`, `filetypes`,
+`defaultextension`) and returns what tkinter returns. Set
+`BUI_FILEDIALOG=native` to get the operating system's dialogs instead.
+
**3. Import it by name**
```python