1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
|
Building
========
For build instructions see the README.md
Pull requests
=============
Before filing a pull request run the tests:
```sh
ninja -C _build test
```
Use descriptive commit messages, see
https://wiki.gnome.org/Git/CommitMessages
and check
https://wiki.openstack.org/wiki/GitCommitMessages
for good examples.
Coding Style
============
We're mostly using [libhandy's Coding Style][1].
These are the differences:
- We're not picky about GTK+ style function argument indentation, that is
having multiple arguments on one line is also o.k.
- For callbacks we additionally allow for the `on_<action>` pattern e.g.
`on_nm_signal_strength_changed()` since this helps to keep the namespace
clean.
- Since we're not a library we usually use `G_DEFINE_TYPE` instead of
`G_DEFINE_TYPE_WITH_PRIVATE` (except when we need a deriveable
type) since it makes the rest of the code more compact.
Source file layout
------------------
We use one file per GObject. It should be named like the GObject without
the phog prefix, lowercase and '_' replaced by '-'. So a hypothetical
`PhogThing` would go to `src/thing.c`. If there are likely name
clashes add the `phog-` prefix (see e.g. `phog-wayland.c`). The
individual C files should be structured as (top to bottom of file):
- License boilerplate
```c
/*
* Copyright (C) year copyright holder
*
* SPDX-License-Identifier: GPL-3-or-later
* Author: you <youremail@example.com>
*/
```
- A log domain
```C
#define G_LOG_DOMAIN "phog-thing"
```
Usually the filename with `phog-` prefix.
- `#include`s:
Phog ones go first, then glib/gtk, then generic C headers. These blocks
are separated by newline and each sorted alphabetically:
```
#define G_LOG_DOMAIN "phog-settings"
#include "settings.h"
#include "shell.h"
#include <gio/gdesktopappinfo.h>
#include <glib/glib.h>
#include <math.h>
```
This helps to detect missing headers in includes.
- docstring
- property enum
```c
enum {
PROP_0,
PROP_FOO,
PROP_BAR,,
LAST_PROP
};
static GParamSpec *props[LAST_PROP];
```
- signal enum
```c
enum {
FOO_HAPPENED,
BAR_TRIGGERED,
N_SIGNALS
};
static guint signals[N_SIGNALS] = { 0 };
```
- type definitions
```c
typedef struct _PhogThing {
GObject parent;
...
} PhogThing;
G_DEFINE_TYPE (PhogThing, phog_thing, G_TYPE_OBJECT)
```
- private methods and callbacks (these can also go at convenient
places above `phog_thing_constructed ()`
- `phog_thing_set_property ()`
- `phog_thing_get_property ()`
- `phog_thing_constructed ()`
- `phog_thing_dispose ()`
- `phog_thing_finalize ()`
- `phog_thing_class_init ()`
- `phog_thing_init ()`
- `phog_thing_new ()`
- Public methods, all starting with the object name(i.e. `phog_thing_`)
The reason public methods go at the bottom is that they have declarations in
the header file and can thus be referenced from anywhere else in the source
file.
CSS Theming
===========
For custom widget always set the css name using `gtk_widget_class_set_css_name ()`.
There's no need set an (additional) style class in the ui file.
*Good*:
```c
static void
phog_lockscreen_class_init (PhogLockscreenClass *klass)
{
…
gtk_widget_class_set_css_name (widget_class, "phog-lockscreen");
…
}
```
*Bad*:
```xml
<template class="PhogLockscreen" parent="…">
…
<style>
<class name="phog-lockscreen"/>
</style>
…
</template>
```
[1]: https://gitlab.gnome.org/GNOME/libhandy/blob/master/HACKING.md#coding-style
|
