NvDialog 0.10.1
A cross-platform modal dialogs library for C/C++ that uses the native OS theme.
Loading...
Searching...
No Matches
nvdialog_tutorial.h
Go to the documentation of this file.
1/************************************************************************************
2 * This file is NOT source code. It will just be used by Doxygen when
3 * generating documentation for a tutorial page. It won't be installed, it won't
4 * be used within the library or by a user, and probably isn't of interest to
5 * anyone outside this.
6 ************************************************************************************/
7
8/**
9 * @page NvDialog Tutorial
10 * @version v0.10.1
11 * @author Aggelos Tselios
12
13 * # NvDialog Tutorial
14 * This page provides a simple tutorial of the NvDialog library. For more
15 information about the
16 * library itself, see <b>https://tseli0s.github.io/nv.dialog</b>.
17 * Proper documentation of the API used in this tutorial is also available in
18 the documentation.
19 * This tutorial assumes you have already installed NvDialog in your system. If
20 not, visit the [GitHub
21 Repo](https://github.com/tseli0s/nvdialog/#installation).
22 * NvDialog is compiler and platform independent, so this tutorial should work
23 as expected on all platforms.
24 * # 1. Creating our environment.
25 * <b>Skip this step if you aren't interested in the setup.</b>
26 * Create a new file named `main.c` and add the following to it:
27 * @code
28 * #include <nvdialog/nvdialog.h>
29 *
30 * int main() {
31 *
32 * }
33 * @endcode
34 * This snippet contains a barebones C program which includes NvDialog. You can
35 try compiling this
36 * to verify that the headers can be found at compile time.
37 * @note Remember that in some platforms headers are installed in non-standard
38 places by CMake. If that's the
39 * case, you will have to manually instruct the compiler to find the headers.
40 * # 2. Creating a basic dialog box.
41 * A dialog box is the simplest and most straightforward feature of NvDialog: It
42 shows a dialog
43 * with some parameters given. You will mainly use this for error messages
44 (Although it can be used
45 * for literally anything, see @ref NvdDialogType ).
46 *
47 * To get started, we first need to initialize NvDialog. This can be done with a
48 single call:
49 * > Initialization is mainly required by the backends. Each backend is often
50 required to be initialized first.
51 * @code
52 * if (nvd_init(argv[0]) != 0) { return -1; }
53 * @endcode
54 * Go to your main function, and create a new dialog box object. The title and
55 the message need to be
56 * a regular NULL terminated C string. For the sake of simplicity we will create
57 them in seperate variables:
58 * @code
59 * const char *title = "Hello NvDialog!";
60 * const char *message = "This dialog box was created with NvDialog.";
61 *
62 * NvdDialogBox *dialog = nvd_dialog_box_new(title, message, NVD_DIALOG_SIMPLE);
63 * @endcode
64 * @ref nvd_dialog_box_new will return NULL on failure, so you may want to
65 handle that too.
66 * # 3. Showing the dialog.
67 * Before @version v0.3.0, creating and showing the dialog was a single call. So
68 the above snippet
69 * would show us the dialog directly, without any extra calls.
70 * This changed because on some platforms (Especially slow ones) caused serious
71 issues that could halt
72 * the thread for 1-2 seconds while creating the dialog! So these have been
73 seperated since.
74 * Now, we will also have to call @ref nvd_show_dialog :
75 * @code
76 * nvd_show_dialog(dialog);
77 * @endcode
78 * The function takes a pointer to the dialog we want to show. For more
79 information read the documentation
80 * by clicking the function.
81 * # 4. Cleanup and finally compiling.
82 * Now, we are technically done. However, we have caused a memory leak here
83 because after all, the
84 * @ref NvdDialogBox type like most others is heap-allocated! Which means we
85 need to `free()` it.
86 * Calling `free()` directly though will cause undefined behavior. So instead,
87 we will use a special
88 * function provided by NvDialog, which frees most types. That function is
89 called @ref nvd_free_object .
90 * @code
91 * nvd_free_object(dialog);
92 * // Not required but let's have it here to indicate success.
93 * return 0;
94 * @endcode
95 * Your final source file should look like this:
96 * @code
97 #include <nvdialog/nvdialog.h>
98
99 int main() {
100 if (nvd_init() != 0) return -1;
101
102 const char *title = "Hello NvDialog!";
103 const char *message = "This dialog box was created with NvDialog.";
104 NvdDialogBox *dialog = nvd_dialog_box_new(title, message,
105 NVD_DIALOG_SIMPLE);
106
107 nvd_show_dialog(dialog);
108 nvd_free_object(dialog);
109 return 0;
110 }
111 * @endcode
112 * <b>Now let's compile it:</b>
113 * @note Each compiler has different options for the same thing. In this case, I
114 am using GCC 12.1
115 * on Arch Linux.
116 *
117 * On the terminal, go to the directory where your source file is located (Using
118 `cd`).
119 * Then run the following command to compile your file:
120 * ```sh
121 * $ gcc \ # Our compiler
122 * $ main.c \ # Your file
123 * $ -l nvdialog \ # Link with the NvDialog library
124 * $ -o nvdialog-tutorial \ # Executable filename
125 * ```
126 * And now running it should give you a dialog box.
127 * That's all you need to get started. For other dialogs to use, take a look at
128 the
129 * following types:
130 * - @ref NvdQuestionBox
131 * - @ref NvdFileDialog
132 * - @ref NvdAboutDialog
133 */