Usage - MadLadSquad/UntitledOpen GitHub Wiki
This library has 2 APIs: the C and the C++ API. Read both sections, as common sections are not explained twice.
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.
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.
This section starts with an introduction to the structures and enums that are used by the pickFile
function. Read through it carefully.
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.
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" }
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;
};
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.
To get the status enum in the C++ API, simply call the UOpen::Result::status()
function.
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.
To get the value, use the returned C++ Result
class. You can use the following:
-
Result::getPaths
- Returns anstd::vector
of file paths that will be limited to 1 element due to the operation type -
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.
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.
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.
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;
}
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;
}