This library has 2 APIs: the C and the C++ API. Read both sections, as common sections are not explained twice.

Initialising and destroying the library

To initialise the library, call UOpen::init(void* displayHandle = nullptr) or UOpen_init(void* displayHandle). When using a window abstraction library, this should be called after you've created the window.

To destroy the library, call UOpen::destroy or UOpen_destroy. When using a window abstraction library, this should be called before you've destroyed the window.

Opening URIs

UntitledOpen can open URIs using the default application for the given URI. Example:

UOpen_openURI("https://google.com/", ""); // C API
UOpen::openURI("https://google.com/", ""); // C++ API

You can also provide a window ID. This is only useful for X11 and Wayland. See more here.

If the link is unable to be opened, -1 will be returned, otherwise the function returns 0 on success.

File picking

This section starts with an introduction to the structures and enums that are used by the pickFile function. Read through it carefully.

File picking operations

There are 5 file picker operations. They are represented by the UOpen_PickerOperation/UOpen::PickerOperation enums:

enum PickerOperation
{
    UOPEN_PICK_FILE,
    UOPEN_PICK_MULTIPLE,
    UOPEN_PICK_FOLDER,
    UOPEN_SAVE_FILE,
    UOPEN_PICK_MULTIPLE_FOLDERS,
};

Certain functionality may be enabled or disabled depending on the operation type you've selected.

File filters

A file filter can be used to filter by certain file extensions. They are represented by the UOpen_Filter/UOpen::Filter struct:

struct UOpen_Filter
{
    const char* name;
    const char* spec;
};

The name string represents a hint into the type of filtering that's done, while the spec represents a comma-separated list of file extensions. Example:

{ "Source code", "c,cpp,cc" }

The pickFile function

To pick a file, use the pickFile function. There are 2 definitions:

Result pickFile(PickerOperation op, const Filter* filters, size_t filtersNum, const char* defaultName = "", const char* defaultPath = nullptr, const char* title = "", const char* acceptLabel = "", const char* cancelLabel = "", WindowHandlePlatform windowHandlePlatform = UOPEN_WINDOW_HANDLE_PLATFORM_NONE, void* windowHandle = nullptr);

Result pickFile(PickerOperation op, const std::vector<Filter>& filters, const char* defaultName = "", const char* defaultPath = nullptr, const char* title = "", const char* acceptLabel = "", const char* cancelLabel = "", WindowHandlePlatform windowHandlePlatform = UOPEN_WINDOW_HANDLE_PLATFORM_NONE, void* windowHandle = nullptr);

The pickFile functions return a Result variable. This is used to keep track of the strings that are returned after picking a file.

They both require a PickerOperation enum as their first argument. Depending on the value, certain arguments passed to the pickFile function may be used or ignored.

The 2 implementations only differ by what argument they take for filters. In the first case, filters are taken in a C-way using a C-style array and a size variable. In the second case, an std::vector of filters is used.

The defaultName argument sets the default file name for the file picker. This is only used when picking folders.

The defaultPath argument sets a default path for the file picker. This is ignored on most operating systems. For example, on Unix-based systems it's completely ignored.

The title argument sets the picker window's title. This is platform- and file manager-dependent.

The acceptLabel and cancelLabel arguments set the picker's accept button and cancel button's labels respectively. This is platform- and file manager-dependent.

The windowHandlePlatform and windowHandle arguments are used when your application has a window and you want the picker window to be parented by your own window. This is important because the picker window will open predictably over your own app's window. The first argument is an enum of type UOpen::WindowHandlePlatform, which looks like this:

enum WindowHandlePlatform
{
    UOPEN_WINDOW_HANDLE_PLATFORM_NONE,
    UOPEN_WINDOW_HANDLE_PLATFORM_WIN32,
    UOPEN_WINDOW_HANDLE_PLATFORM_COCOA,
    UOPEN_WINDOW_HANDLE_PLATFORM_X11,
    UOPEN_WINDOW_HANDLE_PLATFORM_WAYLAND
};

After setting the correct platform set windowHandle to your window's handle pointer.

In the C API, the first definition is used, which is named UOpen_pickFile. Apart from that, the result is a C result struct that looks like this:

struct UOpen_Result
{
    UOpen_Status status;
    UOpen_PickerOperation operation;
    void* data;
};

Results

C

In the C API, the UOpen_Result struct is returned:

struct UOpen_Result
{
    UOpen_Status status;
    UOpen_PickerOperation operation;
    void* data;
};

You can use the status member to check if the operation was successful. The UOpen_Status/UOpen::Status enum looks like this:

enum UOpen_Status
{
    UOPEN_STATUS_ERROR,
    UOPEN_STATUS_SUCCESS,
    UOPEN_STATUS_CANCELLED
};

On error, or if cancelled by the user, nothing is allocated, and therefore nothing should be freed.

If you want to check the error message when an error is returned, use the UOpen_getPickerError/UOpen::getPickerError functions.

C++

To get the status enum in the C++ API, simply call the UOpen::Result::status() function.

Picking a single file, folder or saving a file

When UOPEN_PICK_FILE, UOPEN_PICK_FOLDER or UOPEN_SAVE_FILE are used, there is only 1 directory returned.

When the UOPEN_PICK_FOLDER operation is set, the defaultPath argument is used. This is only used for folders, where you can set the default path to save to. It can freely be left to "".

Additionally, any value in filters is unused.

C++

To get the value, use the returned C++ Result class. You can use the following:

1. Result::getPaths - Returns an std::vector of file paths that will be limited to 1 element due to the operation type
2. Result::getPath(0) - Returns the string

The returned strings are of type UniqueString. This is just a small wrapper over const char* that adds RAII. It has implicit conversion operators to const char*. If needed, it can be destroyed manually using the destroy member.

C

When UOPEN_PICK_FILE, UOPEN_PICK_FOLDER or UOPEN_SAVE_FILE are used, there is only 1 directory returned. Therefore, you can use the data member of the result struct, which you can cast to char*.

After you've used the string, you can free it using the UOpen_freeResult(UOpen_Result* result) function.

Picking multiple files

When UOPEN_PICK_MULTIPLE is set, there is more than 1 file that can be returned. For this reason, there are a couple of ways to iterate through these paths.

C

In the C API, a for loop is used to iterate the paths like this:

for (size_t i = 0; i < UOpen_getPathCount(&result); i++)
{
    char* path = (char*)UOpen_getPathMultiple(&result, i);
    printf("%s\n", path);
    UOpen_freePathMultiple(path); // Frees the path
}
UOpen_freeResult(&result); // Frees the result, which also frees the array of paths

This can also be done in the C++ API like this:

for (size_t i = 0; i < result.getPathNum(); i++)
{
    std::cout << result.getPath(i) << std::endl;
}

C++

In the C++ API, you can use the UOpen::Result::getPaths function that returns a vector of paths like this:

for (auto& a : result.getPaths())
{
    std::cout << a << std::endl;
}

Updating the Wayland display handle

Usually one sets the Wayland display handle when calling UOpen::init() and doesn't need to change it after that, however if you do need to update the handle run the UOpen::updateWaylandDisplay(void* display) function.

• Home
• Building & Configuring
• Usage