From 81556f4b2aad49c21058d9cc9695195a12f0239b Mon Sep 17 00:00:00 2001
From: Tony Crisci <tony@dubstepdish.com>
Date: Sat, 31 Mar 2018 20:52:34 -0400
Subject: [PATCH] add docstrings and todos
---
include/sway/tree/container.h | 63 +++++++++++++++++++++++++----------
include/sway/tree/layout.h | 9 +++++
2 files changed, 54 insertions(+), 18 deletions(-)
diff --git a/include/sway/tree/container.h b/include/sway/tree/container.h
index 285f10111..f0e87fb51 100644
--- a/include/sway/tree/container.h
+++ b/include/sway/tree/container.h
@@ -87,37 +87,55 @@ struct sway_container {
} events;
};
+// TODO make private and use the container-specific create functions
struct sway_container *container_create(enum sway_container_type type);
-// TODO only one container create function and pass the type?
-struct sway_container *container_output_create(
- struct sway_output *sway_output);
+/**
+ * Create a new container container. A container container can be a a child of
+ * a workspace container or another container container.
+ */
+struct sway_container *container_container_create();
-struct sway_container *container_workspace_create(
- struct sway_container *output, const char *name);
+/**
+ * Create a new output. Outputs are children of the root container and have no
+ * order in the tree structure.
+ */
+struct sway_container *container_output_create(struct sway_output *sway_output);
+/**
+ * Create a new workspace container. Workspaces are children of an output
+ * container and are ordered alphabetically by name.
+ */
+struct sway_container *container_workspace_create(struct sway_container *output, const char *name);
+
+/*
+ * Create a new view container. A view can be a child of a workspace container
+ * or a container container and are rendered in the order and structure of
+ * how they are attached to the tree.
+ */
+// TODO view containers should be created in a detached state.
struct sway_container *container_view_create(
struct sway_container *sibling, struct sway_view *sway_view);
-struct sway_container *container_output_destroy(struct sway_container *output);
+// TODO don't return the parent on destroy
+struct sway_container *container_destroy(struct sway_container *container);
-struct sway_container *container_workspace_destroy(
- struct sway_container *workspace);
-
-struct sway_container *container_view_destroy(struct sway_container *view);
-
-struct sway_container *container_destroy(struct sway_container *cont);
+struct sway_container *container_workspace_destroy(struct sway_container *container);
+struct sway_container *container_output_destroy(struct sway_container *container);
+struct sway_container *container_view_destroy(struct sway_container *container);
+// TODO move to layout.c
struct sway_container *container_set_layout(struct sway_container *container,
enum sway_container_layout layout);
+// TODO rename to container_descendants_for_each()
void container_descendants(struct sway_container *root,
enum sway_container_type type,
void (*func)(struct sway_container *item, void *data), void *data);
/**
- * Finds a container based on test criteria. Returns the first container that
- * passes the test.
+ * Search a container's descendants a container based on test criteria. Returns
+ * the first container that passes the test.
*/
struct sway_container *container_find(struct sway_container *container,
bool (*test)(struct sway_container *view, void *data), void *data);
@@ -125,18 +143,21 @@ struct sway_container *container_find(struct sway_container *container,
/**
* Finds a parent container with the given struct sway_containerype.
*/
+// TODO rename to container_parent_of_type()
struct sway_container *container_parent(struct sway_container *container,
enum sway_container_type type);
/**
- * Find a container at the given coordinates.
+ * Find a container at the given coordinates. Returns the the surface and
+ * surface-local coordinates of the given layout coordinates if the container
+ * is a view and the view contains a surface at those coordinates.
*/
-struct sway_container *container_at(struct sway_container *parent,
+struct sway_container *container_at(struct sway_container *container,
double lx, double ly, struct wlr_surface **surface,
double *sx, double *sy);
/**
- * Apply the function for each child of the container breadth first.
+ * Apply the function for each descendant of the container breadth first.
*/
void container_for_each_descendant_bfs(struct sway_container *container,
void (*f)(struct sway_container *container, void *data), void *data);
@@ -147,9 +168,15 @@ void container_for_each_descendant_bfs(struct sway_container *container,
void container_for_each_descendant_dfs(struct sway_container *container,
void (*f)(struct sway_container *container, void *data), void *data);
-bool container_has_anscestor(struct sway_container *descendant,
+/**
+ * Returns true if the given container is an ancestor of this container.
+ */
+bool container_has_anscestor(struct sway_container *container,
struct sway_container *anscestor);
+/**
+ * Returns true if the given container is a child descendant of this container.
+ */
bool container_has_child(struct sway_container *con,
struct sway_container *child);
diff --git a/include/sway/tree/layout.h b/include/sway/tree/layout.h
index 79c14edaf..53f72ec46 100644
--- a/include/sway/tree/layout.h
+++ b/include/sway/tree/layout.h
@@ -32,28 +32,37 @@ struct sway_root {
void layout_init(void);
+// TODO move to tree.h
void container_add_child(struct sway_container *parent, struct sway_container *child);
+// TODO move to tree.h
struct sway_container *container_add_sibling(struct sway_container *parent,
struct sway_container *child);
+// TODO move to tree.h
struct sway_container *container_remove_child(struct sway_container *child);
+// TODO PRIVATE in tree.h
struct sway_container *container_reap_empty(struct sway_container *container);
+// TODO move to tree.h
void container_move_to(struct sway_container* container,
struct sway_container* destination);
+// TODO move to output.c
enum sway_container_layout container_get_default_layout(struct sway_container *output);
+// TODO move to output.c
void container_sort_workspaces(struct sway_container *output);
void arrange_windows(struct sway_container *container,
double width, double height);
+// TODO move to container.h
struct sway_container *container_get_in_direction(struct sway_container
*container, struct sway_seat *seat, enum movement_direction dir);
+// TODO move to tree.h
struct sway_container *container_split(struct sway_container *child,
enum sway_container_layout layout);