Tutorial

Version

v0.10.1

Author

Aggelos Tselios

NvDialog Tutorial

This page provides a simple tutorial of the NvDialog library. For more information about the library itself, see https://tseli0s.github.io/nv.dialog. Proper documentation of the API used in this tutorial is also available in the documentation. This tutorial assumes you have already installed NvDialog in your system. If not, visit the GitHub Repo. NvDialog is compiler and platform independent, so this tutorial should work as expected on all platforms.

1. Creating our environment.

Skip this step if you aren't interested in the setup. Create a new file named main.c and add the following to it:

#include <nvdialog/nvdialog.h>
 
int main() {
 
}

This snippet contains a barebones C program which includes NvDialog. You can try compiling this to verify that the headers can be found at compile time.

Note

Remember that in some platforms headers are installed in non-standard places by CMake. If that's the case, you will have to manually instruct the compiler to find the headers.

2. Creating a basic dialog box.

A dialog box is the simplest and most straightforward feature of NvDialog: It shows a dialog with some parameters given. You will mainly use this for error messages (Although it can be used for literally anything, see NvdDialogType ).

To get started, we first need to initialize NvDialog. This can be done with a single call:

Initialization is mainly required by the backends. Each backend is often required to be initialized first.

if (nvd_init(argv[0]) != 0) { return -1; }

Go to your main function, and create a new dialog box object. The title and the message need to be a regular NULL terminated C string. For the sake of simplicity we will create them in seperate variables:

   const char *title = "Hello NvDialog!";
   const char *message = "This dialog box was created with NvDialog.";
</blockquote>
   
   NvdDialogBox *dialog = nvd_dialog_box_new(title, message, NVD_DIALOG_SIMPLE);

nvd_dialog_box_new will return NULL on failure, so you may want to handle that too.

3. Showing the dialog.

Before

Version

v0.3.0, creating and showing the dialog was a single call. So the above snippet would show us the dialog directly, without any extra calls. This changed because on some platforms (Especially slow ones) caused serious issues that could halt the thread for 1-2 seconds while creating the dialog! So these have been seperated since. Now, we will also have to call nvd_show_dialog :

nvd_show_dialog(dialog);

The function takes a pointer to the dialog we want to show. For more information read the documentation by clicking the function.

4. Cleanup and finally compiling.

Now, we are technically done. However, we have caused a memory leak here because after all, the NvdDialogBox type like most others is heap-allocated! Which means we need to free() it. Calling free() directly though will cause undefined behavior. So instead, we will use a special function provided by NvDialog, which frees most types. That function is called nvd_free_object .

nvd_free_object(dialog);
// Not required but let's have it here to indicate success.
return 0;

Your final source file should look like this:

  #include <nvdialog/nvdialog.h>
 
  int main() {
       if (nvd_init() != 0) return -1;
 
       const char *title = "Hello NvDialog!";
       const char *message = "This dialog box was created with NvDialog.";
       NvdDialogBox *dialog = nvd_dialog_box_new(title, message,
NVD_DIALOG_SIMPLE);
 
       nvd_show_dialog(dialog);
       nvd_free_object(dialog);
       return 0;
  }

Now let's compile it:

Note

Each compiler has different options for the same thing. In this case, I am using GCC 12.1 on Arch Linux.

On the terminal, go to the directory where your source file is located (Using cd). Then run the following command to compile your file:

$ gcc \ # Our compiler
$ main.c \ # Your file
$ -l nvdialog \ # Link with the NvDialog library
$ -o nvdialog-tutorial \ # Executable filename

And now running it should give you a dialog box. That's all you need to get started. For other dialogs to use, take a look at the following types:

• NvdQuestionBox
• NvdFileDialog
• NvdAboutDialog