Mercurial > molko

annotate libui/ui/label.h @ 240:d7e5e02f70a1

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc: misc
author David Demelier <markand@malikania.fr>
date Fri, 27 Nov 2020 21:34:07 +0100
parents 49639211d63b
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
99
4ac71ac10c9f core: start adding some UI elements
David Demelier <markand@malikania.fr>
parents:
diff changeset
1 /*
4ac71ac10c9f core: start adding some UI elements
David Demelier <markand@malikania.fr>
parents:
diff changeset
2 * label.h -- GUI label
4ac71ac10c9f core: start adding some UI elements
David Demelier <markand@malikania.fr>
parents:
diff changeset
3 *
4ac71ac10c9f core: start adding some UI elements
David Demelier <markand@malikania.fr>
parents:
diff changeset
4 * Copyright (c) 2020 David Demelier <markand@malikania.fr>
4ac71ac10c9f core: start adding some UI elements
David Demelier <markand@malikania.fr>
parents:
diff changeset
5 *
4ac71ac10c9f core: start adding some UI elements
David Demelier <markand@malikania.fr>
parents:
diff changeset
6 * Permission to use, copy, modify, and/or distribute this software for any
4ac71ac10c9f core: start adding some UI elements
David Demelier <markand@malikania.fr>
parents:
diff changeset
7 * purpose with or without fee is hereby granted, provided that the above
4ac71ac10c9f core: start adding some UI elements
David Demelier <markand@malikania.fr>
parents:
diff changeset
8 * copyright notice and this permission notice appear in all copies.
4ac71ac10c9f core: start adding some UI elements
David Demelier <markand@malikania.fr>
parents:
diff changeset
9 *
4ac71ac10c9f core: start adding some UI elements
David Demelier <markand@malikania.fr>
parents:
diff changeset
10 * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
4ac71ac10c9f core: start adding some UI elements
David Demelier <markand@malikania.fr>
parents:
diff changeset
11 * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
4ac71ac10c9f core: start adding some UI elements
David Demelier <markand@malikania.fr>
parents:
diff changeset
12 * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
4ac71ac10c9f core: start adding some UI elements
David Demelier <markand@malikania.fr>
parents:
diff changeset
13 * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
4ac71ac10c9f core: start adding some UI elements
David Demelier <markand@malikania.fr>
parents:
diff changeset
14 * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
4ac71ac10c9f core: start adding some UI elements
David Demelier <markand@malikania.fr>
parents:
diff changeset
15 * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
4ac71ac10c9f core: start adding some UI elements
David Demelier <markand@malikania.fr>
parents:
diff changeset
16 * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
4ac71ac10c9f core: start adding some UI elements
David Demelier <markand@malikania.fr>
parents:
diff changeset
17 */
4ac71ac10c9f core: start adding some UI elements
David Demelier <markand@malikania.fr>
parents:
diff changeset
18
4ac71ac10c9f core: start adding some UI elements
David Demelier <markand@malikania.fr>
parents:
diff changeset
19 #ifndef MOLKO_LABEL_H
4ac71ac10c9f core: start adding some UI elements
David Demelier <markand@malikania.fr>
parents:
diff changeset
20 #define MOLKO_LABEL_H
4ac71ac10c9f core: start adding some UI elements
David Demelier <markand@malikania.fr>
parents:
diff changeset
21
4ac71ac10c9f core: start adding some UI elements
David Demelier <markand@malikania.fr>
parents:
diff changeset
22 /**
4ac71ac10c9f core: start adding some UI elements
David Demelier <markand@malikania.fr>
parents:
diff changeset
23 * \file label.h
4ac71ac10c9f core: start adding some UI elements
David Demelier <markand@malikania.fr>
parents:
diff changeset
24 * \brief GUI label.
152
1008a796a9e7 ui: make UI widgets usable as actions
David Demelier <markand@malikania.fr>
parents: 151
diff changeset
25 * \ingroup ui
99
4ac71ac10c9f core: start adding some UI elements
David Demelier <markand@malikania.fr>
parents:
diff changeset
26 */
4ac71ac10c9f core: start adding some UI elements
David Demelier <markand@malikania.fr>
parents:
diff changeset
27
178
49639211d63b ui: add <stdbool.h> in label.h
David Demelier <markand@malikania.fr>
parents: 174
diff changeset
28 #include <stdbool.h>
49639211d63b ui: add <stdbool.h> in label.h
David Demelier <markand@malikania.fr>
parents: 174
diff changeset
29
152
1008a796a9e7 ui: make UI widgets usable as actions
David Demelier <markand@malikania.fr>
parents: 151
diff changeset
30 struct action;
99
4ac71ac10c9f core: start adding some UI elements
David Demelier <markand@malikania.fr>
parents:
diff changeset
31 struct theme;
4ac71ac10c9f core: start adding some UI elements
David Demelier <markand@malikania.fr>
parents:
diff changeset
32
4ac71ac10c9f core: start adding some UI elements
David Demelier <markand@malikania.fr>
parents:
diff changeset
33 /**
101
0bc32f70d67c label: add more customization
David Demelier <markand@malikania.fr>
parents: 99
diff changeset
34 * \brief Label flags.
0bc32f70d67c label: add more customization
David Demelier <markand@malikania.fr>
parents: 99
diff changeset
35 */
0bc32f70d67c label: add more customization
David Demelier <markand@malikania.fr>
parents: 99
diff changeset
36 enum label_flags {
145
7f1af54bb35a core: rework label alignment, closes #2494 @1h
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
37 LABEL_FLAGS_NONE, /*!< No flags. */
7f1af54bb35a core: rework label alignment, closes #2494 @1h
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
38 LABEL_FLAGS_SHADOW = (1 << 0), /*!< Enable shadow. */
7f1af54bb35a core: rework label alignment, closes #2494 @1h
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
39 };
7f1af54bb35a core: rework label alignment, closes #2494 @1h
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
40
7f1af54bb35a core: rework label alignment, closes #2494 @1h
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
41 /**
99
4ac71ac10c9f core: start adding some UI elements
David Demelier <markand@malikania.fr>
parents:
diff changeset
42 * \brief GUI label.
4ac71ac10c9f core: start adding some UI elements
David Demelier <markand@malikania.fr>
parents:
diff changeset
43 */
4ac71ac10c9f core: start adding some UI elements
David Demelier <markand@malikania.fr>
parents:
diff changeset
44 struct label {
147
b386d25832c8 doc: use new nomenclature, closes #2497
David Demelier <markand@malikania.fr>
parents: 145
diff changeset
45 int x; /*!< (+) Position in x. */
b386d25832c8 doc: use new nomenclature, closes #2497
David Demelier <markand@malikania.fr>
parents: 145
diff changeset
46 int y; /*!< (+) Position in y. */
b386d25832c8 doc: use new nomenclature, closes #2497
David Demelier <markand@malikania.fr>
parents: 145
diff changeset
47 const char *text; /*!< (+&) Text to show. */
b386d25832c8 doc: use new nomenclature, closes #2497
David Demelier <markand@malikania.fr>
parents: 145
diff changeset
48 enum label_flags flags; /*!< (+) Optional flags. */
174
6992085d47fd ui: major theme overhaul, closes #2509 @1h
David Demelier <markand@malikania.fr>
parents: 161
diff changeset
49 const struct theme *theme; /*!< (+&?) Theme to use. */
99
4ac71ac10c9f core: start adding some UI elements
David Demelier <markand@malikania.fr>
parents:
diff changeset
50 };
4ac71ac10c9f core: start adding some UI elements
David Demelier <markand@malikania.fr>
parents:
diff changeset
51
4ac71ac10c9f core: start adding some UI elements
David Demelier <markand@malikania.fr>
parents:
diff changeset
52 /**
151
b19d076856d2 ui: cleanup theme module, closes #2498
David Demelier <markand@malikania.fr>
parents: 150
diff changeset
53 * Default drawing function.
b19d076856d2 ui: cleanup theme module, closes #2498
David Demelier <markand@malikania.fr>
parents: 150
diff changeset
54 *
b19d076856d2 ui: cleanup theme module, closes #2498
David Demelier <markand@malikania.fr>
parents: 150
diff changeset
55 * \pre t != NULL
b19d076856d2 ui: cleanup theme module, closes #2498
David Demelier <markand@malikania.fr>
parents: 150
diff changeset
56 * \pre label != NULL
b19d076856d2 ui: cleanup theme module, closes #2498
David Demelier <markand@malikania.fr>
parents: 150
diff changeset
57 * \param t the theme
b19d076856d2 ui: cleanup theme module, closes #2498
David Demelier <markand@malikania.fr>
parents: 150
diff changeset
58 * \param label the label
b19d076856d2 ui: cleanup theme module, closes #2498
David Demelier <markand@malikania.fr>
parents: 150
diff changeset
59 */
b19d076856d2 ui: cleanup theme module, closes #2498
David Demelier <markand@malikania.fr>
parents: 150
diff changeset
60 void
174
6992085d47fd ui: major theme overhaul, closes #2509 @1h
David Demelier <markand@malikania.fr>
parents: 161
diff changeset
61 label_draw_default(const struct theme *t, const struct label *label);
6992085d47fd ui: major theme overhaul, closes #2509 @1h
David Demelier <markand@malikania.fr>
parents: 161
diff changeset
62
6992085d47fd ui: major theme overhaul, closes #2509 @1h
David Demelier <markand@malikania.fr>
parents: 161
diff changeset
63 /**
6992085d47fd ui: major theme overhaul, closes #2509 @1h
David Demelier <markand@malikania.fr>
parents: 161
diff changeset
64 * Tells if the label is usable.
6992085d47fd ui: major theme overhaul, closes #2509 @1h
David Demelier <markand@malikania.fr>
parents: 161
diff changeset
65 *
6992085d47fd ui: major theme overhaul, closes #2509 @1h
David Demelier <markand@malikania.fr>
parents: 161
diff changeset
66 * \param label the label to check (may be NULL)
6992085d47fd ui: major theme overhaul, closes #2509 @1h
David Demelier <markand@malikania.fr>
parents: 161
diff changeset
67 * \return False if label is null or as empty text.
6992085d47fd ui: major theme overhaul, closes #2509 @1h
David Demelier <markand@malikania.fr>
parents: 161
diff changeset
68 */
6992085d47fd ui: major theme overhaul, closes #2509 @1h
David Demelier <markand@malikania.fr>
parents: 161
diff changeset
69 bool
6992085d47fd ui: major theme overhaul, closes #2509 @1h
David Demelier <markand@malikania.fr>
parents: 161
diff changeset
70 label_ok(const struct label *label);
151
b19d076856d2 ui: cleanup theme module, closes #2498
David Demelier <markand@malikania.fr>
parents: 150
diff changeset
71
b19d076856d2 ui: cleanup theme module, closes #2498
David Demelier <markand@malikania.fr>
parents: 150
diff changeset
72 /**
153
aa6e70e330a1 ui: make label less smart
David Demelier <markand@malikania.fr>
parents: 152
diff changeset
73 * Update the `w` and `h` fields with the dimensions the text would needs with
aa6e70e330a1 ui: make label less smart
David Demelier <markand@malikania.fr>
parents: 152
diff changeset
74 * the current theme.
aa6e70e330a1 ui: make label less smart
David Demelier <markand@malikania.fr>
parents: 152
diff changeset
75 *
aa6e70e330a1 ui: make label less smart
David Demelier <markand@malikania.fr>
parents: 152
diff changeset
76 * \pre label != NULL
aa6e70e330a1 ui: make label less smart
David Demelier <markand@malikania.fr>
parents: 152
diff changeset
77 * \param label the label
161
31d7f23c0588 ui: label no longer has w, h fields
David Demelier <markand@malikania.fr>
parents: 153
diff changeset
78 * \param w the pointer to width (may be NULL)
31d7f23c0588 ui: label no longer has w, h fields
David Demelier <markand@malikania.fr>
parents: 153
diff changeset
79 * \param h the pointer to height (may be NULL)
153
aa6e70e330a1 ui: make label less smart
David Demelier <markand@malikania.fr>
parents: 152
diff changeset
80 */
aa6e70e330a1 ui: make label less smart
David Demelier <markand@malikania.fr>
parents: 152
diff changeset
81 void
174
6992085d47fd ui: major theme overhaul, closes #2509 @1h
David Demelier <markand@malikania.fr>
parents: 161
diff changeset
82 label_query(const struct label *label, unsigned int *w, unsigned int *h);
153
aa6e70e330a1 ui: make label less smart
David Demelier <markand@malikania.fr>
parents: 152
diff changeset
83
aa6e70e330a1 ui: make label less smart
David Demelier <markand@malikania.fr>
parents: 152
diff changeset
84 /**
99
4ac71ac10c9f core: start adding some UI elements
David Demelier <markand@malikania.fr>
parents:
diff changeset
85 * Draw the label.
4ac71ac10c9f core: start adding some UI elements
David Demelier <markand@malikania.fr>
parents:
diff changeset
86 *
4ac71ac10c9f core: start adding some UI elements
David Demelier <markand@malikania.fr>
parents:
diff changeset
87 * \pre label != NULL
4ac71ac10c9f core: start adding some UI elements
David Demelier <markand@malikania.fr>
parents:
diff changeset
88 * \param label the label to draw
4ac71ac10c9f core: start adding some UI elements
David Demelier <markand@malikania.fr>
parents:
diff changeset
89 */
4ac71ac10c9f core: start adding some UI elements
David Demelier <markand@malikania.fr>
parents:
diff changeset
90 void
4ac71ac10c9f core: start adding some UI elements
David Demelier <markand@malikania.fr>
parents:
diff changeset
91 label_draw(const struct label *label);
4ac71ac10c9f core: start adding some UI elements
David Demelier <markand@malikania.fr>
parents:
diff changeset
92
152
1008a796a9e7 ui: make UI widgets usable as actions
David Demelier <markand@malikania.fr>
parents: 151
diff changeset
93 /**
1008a796a9e7 ui: make UI widgets usable as actions
David Demelier <markand@malikania.fr>
parents: 151
diff changeset
94 * Convert the label into an action.
1008a796a9e7 ui: make UI widgets usable as actions
David Demelier <markand@malikania.fr>
parents: 151
diff changeset
95 *
1008a796a9e7 ui: make UI widgets usable as actions
David Demelier <markand@malikania.fr>
parents: 151
diff changeset
96 * The following field will be set into the action:
1008a796a9e7 ui: make UI widgets usable as actions
David Demelier <markand@malikania.fr>
parents: 151
diff changeset
97 *
1008a796a9e7 ui: make UI widgets usable as actions
David Demelier <markand@malikania.fr>
parents: 151
diff changeset
98 * - act->data: points to label (reference),
1008a796a9e7 ui: make UI widgets usable as actions
David Demelier <markand@malikania.fr>
parents: 151
diff changeset
99 * - act->draw: a wrapper to label_draw.
1008a796a9e7 ui: make UI widgets usable as actions
David Demelier <markand@malikania.fr>
parents: 151
diff changeset
100 *
1008a796a9e7 ui: make UI widgets usable as actions
David Demelier <markand@malikania.fr>
parents: 151
diff changeset
101 * The label being an UI element is considered to never completes, as such
1008a796a9e7 ui: make UI widgets usable as actions
David Demelier <markand@malikania.fr>
parents: 151
diff changeset
102 * you will need to handle this case or to use a custom update function.
1008a796a9e7 ui: make UI widgets usable as actions
David Demelier <markand@malikania.fr>
parents: 151
diff changeset
103 *
1008a796a9e7 ui: make UI widgets usable as actions
David Demelier <markand@malikania.fr>
parents: 151
diff changeset
104 * \pre frame != NULL
1008a796a9e7 ui: make UI widgets usable as actions
David Demelier <markand@malikania.fr>
parents: 151
diff changeset
105 * \pre act != NULL
1008a796a9e7 ui: make UI widgets usable as actions
David Demelier <markand@malikania.fr>
parents: 151
diff changeset
106 * \param label the label to reference
1008a796a9e7 ui: make UI widgets usable as actions
David Demelier <markand@malikania.fr>
parents: 151
diff changeset
107 * \param act the action to fill
1008a796a9e7 ui: make UI widgets usable as actions
David Demelier <markand@malikania.fr>
parents: 151
diff changeset
108 */
1008a796a9e7 ui: make UI widgets usable as actions
David Demelier <markand@malikania.fr>
parents: 151
diff changeset
109 void
1008a796a9e7 ui: make UI widgets usable as actions
David Demelier <markand@malikania.fr>
parents: 151
diff changeset
110 label_action(struct label *label, struct action *act);
1008a796a9e7 ui: make UI widgets usable as actions
David Demelier <markand@malikania.fr>
parents: 151
diff changeset
111
99
4ac71ac10c9f core: start adding some UI elements
David Demelier <markand@malikania.fr>
parents:
diff changeset
112 #endif /* !MOLKO_LABEL_H */