diff options
author | Drew DeVault <sir@cmpwn.com> | 2015-11-08 12:06:12 -0500 |
---|---|---|
committer | Drew DeVault <sir@cmpwn.com> | 2015-11-08 12:06:51 -0500 |
commit | edb3e4b5ab50b283a64a8099e5b2b26a9f3071b1 (patch) | |
tree | a8e94d77e39b24f2fa480bb1f2f22c0ef8994ab6 /include | |
parent | Merge pull request #217 from mikkeloscar/ipc-h (diff) | |
download | sway-edb3e4b5ab50b283a64a8099e5b2b26a9f3071b1.tar.gz sway-edb3e4b5ab50b283a64a8099e5b2b26a9f3071b1.tar.zst sway-edb3e4b5ab50b283a64a8099e5b2b26a9f3071b1.zip |
Add some documentation comments
This is mostly setting a precedent, I hope that others will continue to
write docs for more headers.
Ref #218
Diffstat (limited to 'include')
-rw-r--r-- | include/commands.h | 40 | ||||
-rw-r--r-- | include/config.h | 36 | ||||
-rw-r--r-- | include/container.h | 194 |
3 files changed, 224 insertions, 46 deletions
diff --git a/include/commands.h b/include/commands.h index f6777930..9135c670 100644 --- a/include/commands.h +++ b/include/commands.h | |||
@@ -5,29 +5,55 @@ | |||
5 | #include <wlc/wlc.h> | 5 | #include <wlc/wlc.h> |
6 | #include "config.h" | 6 | #include "config.h" |
7 | 7 | ||
8 | 8 | /** | |
9 | enum cmd_status { | 9 | * Indicates the result of a command's execution. |
10 | CMD_SUCCESS, | 10 | */ |
11 | CMD_FAILURE, // was or at least could be executed | 11 | enum cmd_status { |
12 | CMD_INVALID, // unknown or parse error | 12 | CMD_SUCCESS, /**< The command was successful */ |
13 | CMD_DEFER, | 13 | CMD_FAILURE, /**< The command resulted in an error */ |
14 | CMD_INVALID, /**< Unknown command or parser error */ | ||
15 | CMD_DEFER, /**< Command execution deferred */ | ||
14 | // Config Blocks | 16 | // Config Blocks |
15 | CMD_BLOCK_END, | 17 | CMD_BLOCK_END, |
16 | CMD_BLOCK_MODE, | 18 | CMD_BLOCK_MODE, |
17 | }; | 19 | }; |
18 | 20 | ||
21 | /** | ||
22 | * Stores the result of executing a command. | ||
23 | */ | ||
19 | struct cmd_results { | 24 | struct cmd_results { |
20 | enum cmd_status status; | 25 | enum cmd_status status; |
21 | char *input; | 26 | char *input; |
27 | /** | ||
28 | * Human friendly error message, or NULL on success | ||
29 | */ | ||
22 | char *error; | 30 | char *error; |
23 | }; | 31 | }; |
24 | 32 | ||
33 | /** | ||
34 | * Parse and handles a command. | ||
35 | */ | ||
25 | struct cmd_results *handle_command(char *command); | 36 | struct cmd_results *handle_command(char *command); |
26 | // Handles commands during config | 37 | /** |
38 | * Parse and handles a command during config file loading. | ||
39 | * | ||
40 | * Do not use this under normal conditions. | ||
41 | */ | ||
27 | struct cmd_results *config_command(char *command); | 42 | struct cmd_results *config_command(char *command); |
28 | 43 | ||
44 | /** | ||
45 | * Allocates a cmd_results object. | ||
46 | */ | ||
29 | struct cmd_results *cmd_results_new(enum cmd_status status, const char* input, const char *error, ...); | 47 | struct cmd_results *cmd_results_new(enum cmd_status status, const char* input, const char *error, ...); |
48 | /** | ||
49 | * Frees a cmd_results object. | ||
50 | */ | ||
30 | void free_cmd_results(struct cmd_results *results); | 51 | void free_cmd_results(struct cmd_results *results); |
52 | /** | ||
53 | * Serializes cmd_results to a JSON string. | ||
54 | * | ||
55 | * Free the JSON string later on. | ||
56 | */ | ||
31 | const char *cmd_results_to_json(struct cmd_results *results); | 57 | const char *cmd_results_to_json(struct cmd_results *results); |
32 | 58 | ||
33 | void remove_view_from_scratchpad(); | 59 | void remove_view_from_scratchpad(); |
diff --git a/include/config.h b/include/config.h index 636d3ec0..8338033c 100644 --- a/include/config.h +++ b/include/config.h | |||
@@ -8,22 +8,36 @@ | |||
8 | #include "layout.h" | 8 | #include "layout.h" |
9 | #include "container.h" | 9 | #include "container.h" |
10 | 10 | ||
11 | /** | ||
12 | * Describes a variable created via the `set` command. | ||
13 | */ | ||
11 | struct sway_variable { | 14 | struct sway_variable { |
12 | char *name; | 15 | char *name; |
13 | char *value; | 16 | char *value; |
14 | }; | 17 | }; |
15 | 18 | ||
19 | /** | ||
20 | * A key binding and an associated command. | ||
21 | */ | ||
16 | struct sway_binding { | 22 | struct sway_binding { |
17 | list_t *keys; | 23 | list_t *keys; |
18 | uint32_t modifiers; | 24 | uint32_t modifiers; |
19 | char *command; | 25 | char *command; |
20 | }; | 26 | }; |
21 | 27 | ||
28 | /** | ||
29 | * A "mode" of keybindings created via the `mode` command. | ||
30 | */ | ||
22 | struct sway_mode { | 31 | struct sway_mode { |
23 | char *name; | 32 | char *name; |
24 | list_t *bindings; | 33 | list_t *bindings; |
25 | }; | 34 | }; |
26 | 35 | ||
36 | /** | ||
37 | * Size and position configuration for a particular output. | ||
38 | * | ||
39 | * This is set via the `output` command. | ||
40 | */ | ||
27 | struct output_config { | 41 | struct output_config { |
28 | char *name; | 42 | char *name; |
29 | bool enabled; | 43 | bool enabled; |
@@ -31,11 +45,19 @@ struct output_config { | |||
31 | int x, y; | 45 | int x, y; |
32 | }; | 46 | }; |
33 | 47 | ||
48 | /** | ||
49 | * Maps a workspace name to an output name. | ||
50 | * | ||
51 | * Set via `workspace <x> output <y>` | ||
52 | */ | ||
34 | struct workspace_output { | 53 | struct workspace_output { |
35 | char *output; | 54 | char *output; |
36 | char *workspace; | 55 | char *workspace; |
37 | }; | 56 | }; |
38 | 57 | ||
58 | /** | ||
59 | * The configuration struct. The result of loading a config file. | ||
60 | */ | ||
39 | struct sway_config { | 61 | struct sway_config { |
40 | list_t *symbols; | 62 | list_t *symbols; |
41 | list_t *modes; | 63 | list_t *modes; |
@@ -62,12 +84,24 @@ struct sway_config { | |||
62 | int gaps_outer; | 84 | int gaps_outer; |
63 | }; | 85 | }; |
64 | 86 | ||
87 | /** | ||
88 | * Loads the config from the given path. | ||
89 | */ | ||
65 | bool load_config(const char *file); | 90 | bool load_config(const char *file); |
91 | /** Reads the config from the given FILE. | ||
92 | */ | ||
66 | bool read_config(FILE *file, bool is_active); | 93 | bool read_config(FILE *file, bool is_active); |
94 | /** | ||
95 | * Does variable replacement for a string based on the config's currently loaded variables. | ||
96 | */ | ||
67 | char *do_var_replacement(char *str); | 97 | char *do_var_replacement(char *str); |
68 | // Setup output container by applying given config | 98 | /** Sets up a WLC output handle based on a given output_config. |
99 | */ | ||
69 | void apply_output_config(struct output_config *oc, swayc_t *output); | 100 | void apply_output_config(struct output_config *oc, swayc_t *output); |
70 | 101 | ||
102 | /** | ||
103 | * Global config singleton. | ||
104 | */ | ||
71 | extern struct sway_config *config; | 105 | extern struct sway_config *config; |
72 | 106 | ||
73 | #endif | 107 | #endif |
diff --git a/include/container.h b/include/container.h index d5eb27c1..8c54ee24 100644 --- a/include/container.h +++ b/include/container.h | |||
@@ -5,42 +5,72 @@ typedef struct sway_container swayc_t; | |||
5 | 5 | ||
6 | #include "layout.h" | 6 | #include "layout.h" |
7 | 7 | ||
8 | enum swayc_types{ | 8 | /** |
9 | C_ROOT, | 9 | * Different kinds of containers. |
10 | C_OUTPUT, | 10 | * |
11 | C_WORKSPACE, | 11 | * This enum is in order. A container will never be inside of a container below |
12 | C_CONTAINER, | 12 | * it on this list. |
13 | C_VIEW, | 13 | */ |
14 | enum swayc_types { | ||
15 | C_ROOT, /**< The root container. Only one of these ever exists. */ | ||
16 | C_OUTPUT, /**< An output (aka monitor, head, etc). */ | ||
17 | C_WORKSPACE, /**< A workspace. */ | ||
18 | C_CONTAINER, /**< A manually created container. */ | ||
19 | C_VIEW, /**< A view (aka window). */ | ||
14 | // Keep last | 20 | // Keep last |
15 | C_TYPES, | 21 | C_TYPES, |
16 | }; | 22 | }; |
17 | 23 | ||
18 | 24 | /** | |
19 | enum swayc_layouts{ | 25 | * Different ways to arrange a container. |
20 | L_NONE, | 26 | */ |
27 | enum swayc_layouts { | ||
28 | L_NONE, /**< Used for containers that have no layout (views, root) */ | ||
21 | L_HORIZ, | 29 | L_HORIZ, |
22 | L_VERT, | 30 | L_VERT, |
23 | L_STACKED, | 31 | L_STACKED, |
24 | L_TABBED, | 32 | L_TABBED, |
25 | L_FLOATING, | 33 | L_FLOATING, /**< A psuedo-container, removed from the tree, to hold floating windows */ |
26 | // Keep last | 34 | // Keep last |
27 | L_LAYOUTS, | 35 | L_LAYOUTS, |
28 | }; | 36 | }; |
29 | 37 | ||
38 | /** | ||
39 | * Stores information about a container. | ||
40 | * | ||
41 | * The tree is made of these. Views are containers that cannot have children. | ||
42 | */ | ||
30 | struct sway_container { | 43 | struct sway_container { |
44 | /** | ||
45 | * If this container maps to a WLC object, this is set to that object's | ||
46 | * handle. Otherwise, NULL. | ||
47 | */ | ||
31 | wlc_handle handle; | 48 | wlc_handle handle; |
32 | 49 | ||
33 | enum swayc_types type; | 50 | enum swayc_types type; |
34 | enum swayc_layouts layout; | 51 | enum swayc_layouts layout; |
35 | 52 | ||
36 | // Not including borders or margins | 53 | /** |
54 | * Width and height of this container, without borders or gaps. | ||
55 | */ | ||
37 | double width, height; | 56 | double width, height; |
38 | 57 | ||
39 | // Used for setting floating geometry | 58 | /** |
59 | * Views may request geometry, which is stored in this and ignored until | ||
60 | * the views are floated. | ||
61 | */ | ||
40 | int desired_width, desired_height; | 62 | int desired_width, desired_height; |
41 | 63 | ||
64 | /** | ||
65 | * The coordinates that this view appear at, relative to the output they | ||
66 | * are located on. | ||
67 | */ | ||
42 | double x, y; | 68 | double x, y; |
43 | 69 | ||
70 | /** | ||
71 | * False if this view is invisible. It could be in the scratchpad or on a | ||
72 | * workspace that is not shown. | ||
73 | */ | ||
44 | bool visible; | 74 | bool visible; |
45 | bool is_floating; | 75 | bool is_floating; |
46 | bool is_focused; | 76 | bool is_focused; |
@@ -50,9 +80,18 @@ struct sway_container { | |||
50 | int gaps; | 80 | int gaps; |
51 | 81 | ||
52 | list_t *children; | 82 | list_t *children; |
83 | /** | ||
84 | * Children of this container that are floated. | ||
85 | */ | ||
53 | list_t *floating; | 86 | list_t *floating; |
54 | 87 | ||
88 | /** | ||
89 | * The parent of this container. NULL for the root container. | ||
90 | */ | ||
55 | struct sway_container *parent; | 91 | struct sway_container *parent; |
92 | /** | ||
93 | * Which of this container's children has focus. | ||
94 | */ | ||
56 | struct sway_container *focused; | 95 | struct sway_container *focused; |
57 | }; | 96 | }; |
58 | 97 | ||
@@ -60,68 +99,147 @@ enum visibility_mask { | |||
60 | VISIBLE = true | 99 | VISIBLE = true |
61 | } visible; | 100 | } visible; |
62 | 101 | ||
63 | // Container Creation | 102 | /** |
64 | 103 | * Allocates a new output container. | |
104 | */ | ||
65 | swayc_t *new_output(wlc_handle handle); | 105 | swayc_t *new_output(wlc_handle handle); |
106 | /** | ||
107 | * Allocates a new workspace container. | ||
108 | */ | ||
66 | swayc_t *new_workspace(swayc_t *output, const char *name); | 109 | swayc_t *new_workspace(swayc_t *output, const char *name); |
67 | // Creates container Around child (parent child) -> (parent (container child)) | 110 | /** |
111 | * Allocates a new container and places a child into it. | ||
112 | * | ||
113 | * This is used from the split command, which creates a new container with the | ||
114 | * requested layout and replaces the focused container in the tree with the new | ||
115 | * one. Then the removed container is added as a child of the new container. | ||
116 | */ | ||
68 | swayc_t *new_container(swayc_t *child, enum swayc_layouts layout); | 117 | swayc_t *new_container(swayc_t *child, enum swayc_layouts layout); |
69 | // Creates view as a sibling of current focused container, or as child of a workspace | 118 | /** |
119 | * Allocates a new view container. | ||
120 | * | ||
121 | * Pass in a sibling view, or a workspace to become this container's parent. | ||
122 | */ | ||
70 | swayc_t *new_view(swayc_t *sibling, wlc_handle handle); | 123 | swayc_t *new_view(swayc_t *sibling, wlc_handle handle); |
71 | // Creates view as a new floating view which is in the active workspace | 124 | /** |
125 | * Allocates a new floating view in the active workspace. | ||
126 | */ | ||
72 | swayc_t *new_floating_view(wlc_handle handle); | 127 | swayc_t *new_floating_view(wlc_handle handle); |
73 | 128 | ||
74 | // Container Destroying | 129 | /** |
75 | 130 | * Frees an output's container. | |
131 | */ | ||
76 | swayc_t *destroy_output(swayc_t *output); | 132 | swayc_t *destroy_output(swayc_t *output); |
77 | // Destroys workspace if empty and returns parent pointer, else returns NULL | 133 | /** |
134 | * Destroys a workspace container and returns the parent pointer, or NULL. | ||
135 | */ | ||
78 | swayc_t *destroy_workspace(swayc_t *workspace); | 136 | swayc_t *destroy_workspace(swayc_t *workspace); |
79 | // Destroyes container and all parent container if they are empty, returns | 137 | /** |
80 | // topmost non-empty parent. returns NULL otherwise | 138 | * Destroys a container and all empty parents. Returns the topmost non-empty |
139 | * parent container, or NULL. | ||
140 | */ | ||
81 | swayc_t *destroy_container(swayc_t *container); | 141 | swayc_t *destroy_container(swayc_t *container); |
82 | // Destroys view and all empty parent containers. return topmost non-empty | 142 | /** |
83 | // parent | 143 | * Destroys a view container and all empty parents. Returns the topmost |
144 | * non-empty parent container, or NULL. | ||
145 | */ | ||
84 | swayc_t *destroy_view(swayc_t *view); | 146 | swayc_t *destroy_view(swayc_t *view); |
85 | 147 | ||
86 | // Container Lookup | 148 | /** |
87 | 149 | * Finds a container based on test criteria. Returns the first container that | |
150 | * passes the test. | ||
151 | */ | ||
88 | swayc_t *swayc_by_test(swayc_t *container, bool (*test)(swayc_t *view, void *data), void *data); | 152 | swayc_t *swayc_by_test(swayc_t *container, bool (*test)(swayc_t *view, void *data), void *data); |
153 | /** | ||
154 | * Finds a parent container with the given swayc_type. | ||
155 | */ | ||
89 | swayc_t *swayc_parent_by_type(swayc_t *container, enum swayc_types); | 156 | swayc_t *swayc_parent_by_type(swayc_t *container, enum swayc_types); |
157 | /** | ||
158 | * Finds a parent with the given swayc_layout. | ||
159 | */ | ||
90 | swayc_t *swayc_parent_by_layout(swayc_t *container, enum swayc_layouts); | 160 | swayc_t *swayc_parent_by_layout(swayc_t *container, enum swayc_layouts); |
91 | // Follow focused until type/layout | 161 | /** |
162 | * Finds the bottom-most focused container of a type. | ||
163 | */ | ||
92 | swayc_t *swayc_focus_by_type(swayc_t *container, enum swayc_types); | 164 | swayc_t *swayc_focus_by_type(swayc_t *container, enum swayc_types); |
165 | /** | ||
166 | * Finds the bottom-most focused container of a layout. | ||
167 | */ | ||
93 | swayc_t *swayc_focus_by_layout(swayc_t *container, enum swayc_layouts); | 168 | swayc_t *swayc_focus_by_layout(swayc_t *container, enum swayc_layouts); |
94 | 169 | ||
95 | 170 | /** | |
171 | * Gets the swayc_t associated with a wlc_handle. | ||
172 | */ | ||
96 | swayc_t *swayc_by_handle(wlc_handle handle); | 173 | swayc_t *swayc_by_handle(wlc_handle handle); |
174 | /** | ||
175 | * Gets the named swayc_t. | ||
176 | */ | ||
97 | swayc_t *swayc_by_name(const char *name); | 177 | swayc_t *swayc_by_name(const char *name); |
178 | /** | ||
179 | * Gets the active output's container. | ||
180 | */ | ||
98 | swayc_t *swayc_active_output(void); | 181 | swayc_t *swayc_active_output(void); |
182 | /** | ||
183 | * Gets the active workspace's container. | ||
184 | */ | ||
99 | swayc_t *swayc_active_workspace(void); | 185 | swayc_t *swayc_active_workspace(void); |
186 | /** | ||
187 | * Gets the workspace for the given view container. | ||
188 | */ | ||
100 | swayc_t *swayc_active_workspace_for(swayc_t *view); | 189 | swayc_t *swayc_active_workspace_for(swayc_t *view); |
101 | // set focus to current pointer location and return focused container | 190 | /** |
191 | * Finds the container currently underneath the pointer. | ||
192 | */ | ||
102 | swayc_t *container_under_pointer(void); | 193 | swayc_t *container_under_pointer(void); |
103 | 194 | ||
104 | // Container information | 195 | /** |
105 | 196 | * Returns true if a container is fullscreen. | |
197 | */ | ||
106 | bool swayc_is_fullscreen(swayc_t *view); | 198 | bool swayc_is_fullscreen(swayc_t *view); |
199 | /** | ||
200 | * Returns true if this view is focused. | ||
201 | */ | ||
107 | bool swayc_is_active(swayc_t *view); | 202 | bool swayc_is_active(swayc_t *view); |
108 | // Is `parent` the parent of `child` | 203 | /** |
204 | * Returns true if the parent is an ancestor of the child. | ||
205 | */ | ||
109 | bool swayc_is_parent_of(swayc_t *parent, swayc_t *child); | 206 | bool swayc_is_parent_of(swayc_t *parent, swayc_t *child); |
110 | // Is `child` a child of `parent` | 207 | /** |
208 | * Returns true if the child is a desecendant of the parent. | ||
209 | */ | ||
111 | bool swayc_is_child_of(swayc_t *child, swayc_t *parent); | 210 | bool swayc_is_child_of(swayc_t *child, swayc_t *parent); |
112 | // Return gap of specified container | 211 | /** |
212 | * Returns the gap (padding) of the container. | ||
213 | * | ||
214 | * This returns the inner gaps for a view, the outer gaps for a workspace, and | ||
215 | * 0 otherwise. | ||
216 | */ | ||
113 | int swayc_gap(swayc_t *container); | 217 | int swayc_gap(swayc_t *container); |
114 | 218 | ||
115 | // Mapping functions | 219 | /** |
116 | 220 | * Maps a container's children over a function. | |
221 | */ | ||
117 | void container_map(swayc_t *, void (*f)(swayc_t *, void *), void *); | 222 | void container_map(swayc_t *, void (*f)(swayc_t *, void *), void *); |
118 | 223 | ||
119 | // Mappings | 224 | /** |
225 | * Set a view as visible or invisible. | ||
226 | * | ||
227 | * This will perform the required wlc calls as well; it is not sufficient to | ||
228 | * simply toggle the boolean in swayc_t. | ||
229 | */ | ||
120 | void set_view_visibility(swayc_t *view, void *data); | 230 | void set_view_visibility(swayc_t *view, void *data); |
121 | // Set or add to gaps | 231 | /** |
232 | * Set the gaps value for a view. | ||
233 | */ | ||
122 | void set_gaps(swayc_t *view, void *amount); | 234 | void set_gaps(swayc_t *view, void *amount); |
235 | /** | ||
236 | * Add to the gaps value for a view. | ||
237 | */ | ||
123 | void add_gaps(swayc_t *view, void *amount); | 238 | void add_gaps(swayc_t *view, void *amount); |
124 | 239 | ||
240 | /** | ||
241 | * Issue wlc calls to make the visibility of a container consistent. | ||
242 | */ | ||
125 | void update_visibility(swayc_t *container); | 243 | void update_visibility(swayc_t *container); |
126 | 244 | ||
127 | #endif | 245 | #endif |