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() or UOpen_init(). 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, a -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 4 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,
};

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);

Result pickFile(PickerOperation op, const std::vector<Filter>& filters, const char* defaultName = "", const char* defaultPath = 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.

Finally, the defaultPath variable sets a default path for the file picker. This is mostly ignored depending on the operating system. For example, on Unix-based systems it's completely ignored.

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 are more than 1 files 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++)
{
    const char* path = UOpen_getPathMultiple(&result, i);
    printf("%s\n", path)
    UOpen_freePathMultiple(path); // Frees the path
}
UOpen_freeResult(); // 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;
}

• Home
• Building & Configuring
• Usage