iZo/README.md

# iZo

iZo is a small C++17 library that exposes common operating-system services through
one consistent API on Windows and Linux.

## Features

- Native open, save, folder, and message dialogs
- UTF-8 text clipboard access
- Standard application, user, temporary, and executable paths
- Non-blocking process launch
- Move-only dynamic library handles with automatic cleanup
- Environment variables and basic system information
- Monotonic timing and sleeping
- Recursive or non-recursive directory watching
- Crash callbacks, debugger detection, debug breaks, and debug output
- Opening paths and revealing files in the platform file manager

Linux dialogs discover `zenity` or `kdialog` at runtime. Linux clipboard access
discovers `wl-clipboard` or `xclip`. No GUI toolkit is linked into applications.

## Build

```sh
cmake -S . -B build -DIZO_BUILD_EXAMPLE=ON -DIZO_BUILD_TESTS=ON
cmake --build build
ctest --test-dir build
```

The unit test suite targets Linux and runs automatically on Gitea Actions using
an `ubuntu-latest` runner.

To consume an installed copy:

```cmake
find_package(iZo CONFIG REQUIRED)
target_link_libraries(your_target PRIVATE iZo::izo)
```

## Usage

Include individual feature headers or the complete API:

```cpp
#include <izo/izo.hpp>

izo::dialog_options options;
options.title = "Choose an image";
options.filters = {{"Images", {"*.png", "*.jpg"}}};

if (auto selection = izo::open_file(options)) {
    izo::reveal_in_file_manager(selection.paths.front());
}

auto config = izo::get_known_path(izo::known_path::config);

izo::process_options process;
process.executable = "tool";
process.arguments = {"--input", "asset.png"};
if (auto launched = izo::launch_process(process)) {
    // launched.process_id identifies the new process.
}
```

Resource-owning APIs are move-only and clean themselves up:

```cpp
std::string error;
auto library = izo::load_dynamic_library("plugin.dll", &error);
if (library) {
    void* entry = library.symbol("initialize_plugin", &error);
}

auto watcher = izo::watch_directory(
    {{"assets"}, true},
    [](const izo::file_event& event) {
        // Handle added, removed, modified, or renamed files.
        // Rename events provide the old path in event.previous_path.
    },
    &error);
```

Dialog calls block until dismissed. Directory callbacks run on the watcher's worker
thread and must not destroy their own watcher.