From 7415f1444894805d39b3f5400e887302a0fdf69f Mon Sep 17 00:00:00 2001 From: Michael Stapelberg Date: Tue, 13 Jul 2010 11:35:05 +0200 Subject: [PATCH] Add more documentation to functions/header files --- include/con.h | 94 +++++++++++++++++++++++++++++++++++++++++++++++- include/match.h | 10 ++++++ include/render.h | 8 +++++ include/tree.h | 60 +++++++++++++++++++++++++++++++ include/window.h | 19 ++++++++++ include/x.h | 39 ++++++++++++++++++++ src/con.c | 34 +++++++++++++++++- src/match.c | 15 ++++++++ src/tree.c | 29 ++++++++++++++- src/x.c | 12 +++++++ 10 files changed, 317 insertions(+), 3 deletions(-) diff --git a/include/con.h b/include/con.h index 5a6f0c15..f2d05dbc 100644 --- a/include/con.h +++ b/include/con.h @@ -1,24 +1,116 @@ #ifndef _CON_H #define _CON_H +/** + * Create a new container (and attach it to the given parent, if not NULL). + * This function initializes the data structures and creates the appropriate + * X11 IDs using x_con_init(). + * + */ Con *con_new(Con *parent); + +/** + * Sets input focus to the given container. Will be updated in X11 in the next + * run of x_push_changes(). + * + */ void con_focus(Con *con); + +/** + * Returns true when this node is a leaf node (has no children) + * + */ bool con_is_leaf(Con *con); + +/** + * Returns true if this node accepts a window (if the node swallows windows, + * it might already have swallowed enough and cannot hold any more). + * + */ bool con_accepts_window(Con *con); + +/** + * Gets the output container (first container with CT_OUTPUT in hierarchy) this + * node is on. + * + */ Con *con_get_output(Con *con); + +/** + * Gets the workspace container this node is on. + * + */ Con *con_get_workspace(Con *con); + +/** + * Returns the first fullscreen node below this node. + * + */ Con *con_get_fullscreen_con(Con *con); + +/** + * Returns true if the node is floating. + * + */ bool con_is_floating(Con *con); + +/** + * Returns the container with the given client window ID or NULL if no such + * container exists. + * + */ Con *con_by_window_id(xcb_window_t window); + +/** + * Returns the container with the given frame ID or NULL if no such container + * exists. + * + */ Con *con_by_frame_id(xcb_window_t frame); + +/** + * Returns the first container which wants to swallow this window + * TODO: priority + * + */ Con *con_for_window(i3Window *window, Match **store_match); + +/** + * Attaches the given container to the given parent. This happens when moving + * a container or when inserting a new container at a specific place in the + * tree. + * + */ void con_attach(Con *con, Con *parent); + +/** + * Detaches the given container from its current parent + * + */ void con_detach(Con *con); -enum { WINDOW_ADD = 0, WINDOW_REMOVE = 1 }; +/** + * Updates the percent attribute of the children of the given container. This + * function needs to be called when a window is added or removed from a + * container. + * + */ void con_fix_percent(Con *con, int action); +enum { WINDOW_ADD = 0, WINDOW_REMOVE = 1 }; + +/** + * Toggles fullscreen mode for the given container. Fullscreen mode will not be + * entered when there already is a fullscreen container on this workspace. + * + */ void con_toggle_fullscreen(Con *con); +/** + * Moves the given container to the currently focused container on the given + * workspace. + * TODO: is there a better place for this function? + * + */ void con_move_to_workspace(Con *con, Con *workspace); #endif diff --git a/include/match.h b/include/match.h index eb6aec1b..923be2e1 100644 --- a/include/match.h +++ b/include/match.h @@ -1,7 +1,17 @@ #ifndef _MATCH_H #define _MATCH_H +/** + * Check if a match is empty. This is necessary while parsing commands to see + * whether the user specified a match at all. + * + */ bool match_is_empty(Match *match); + +/** + * Check if a match data structure matches the given window. + * + */ bool match_matches_window(Match *match, i3Window *window); #endif diff --git a/include/render.h b/include/render.h index 26ae8d51..849f214e 100644 --- a/include/render.h +++ b/include/render.h @@ -5,6 +5,14 @@ #ifndef _RENDER_H #define _RENDER_H +/** + * "Renders" the given container (and its children), meaning that all rects are + * updated correctly. Note that this function does not call any xcb_* + * functions, so the changes are completely done in memory only (and + * side-effect free). As soon as you call x_push_changes(), the changes will be + * updated in X11. + * + */ void render_con(Con *con); #endif diff --git a/include/tree.h b/include/tree.h index fd393d8b..449f67ef 100644 --- a/include/tree.h +++ b/include/tree.h @@ -12,16 +12,76 @@ extern Con *focused; TAILQ_HEAD(all_cons_head, Con); extern struct all_cons_head all_cons; +/** + * Initializes the tree by creating the root node, adding all RandR outputs + * to the tree (that means randr_init() has to be called before) and + * assigning a workspace to each RandR output. + * + */ void tree_init(); + +/** + * Opens an empty container in the current container + * + */ Con *tree_open_con(Con *con); + +/** + * Splits (horizontally or vertically) the given container by creating a new + * container which contains the old one and the future ones. + * + */ void tree_split(Con *con, orientation_t orientation); + +/** + * Moves focus one level up. + * + */ void level_up(); + +/** + * Moves focus one level down. + * + */ void level_down(); + +/** + * Renders the tree, that is rendering all outputs using render_con() and + * pushing the changes to X11 using x_push_changes(). + * + */ void tree_render(); + +/** + * Closes the current container using tree_close(). + * + */ void tree_close_con(); + +/** + * Changes focus in the given way (next/previous) and given orientation + * (horizontal/vertical). + * + */ void tree_next(char way, orientation_t orientation); + +/** + * Moves the current container in the given way (next/previous) and given + * orientation (horizontal/vertical). + * + */ void tree_move(char way, orientation_t orientation); + +/** + * Closes the given container including all children + * + */ void tree_close(Con *con, bool kill_window); + +/** + * Loads tree from ~/.i3/_restart.json (used for in-place restarts). + * + */ bool tree_restore(); #endif diff --git a/include/window.h b/include/window.h index a126a36c..044bde70 100644 --- a/include/window.h +++ b/include/window.h @@ -1,8 +1,27 @@ #ifndef _WINDOW_H #define _WINDOW_H +/** + * Updates the WM_CLASS (consisting of the class and instance) for the + * given window. + * + */ void window_update_class(i3Window *win, xcb_get_property_reply_t *prop); + +/** + * Updates the name by using _NET_WM_NAME (encoded in UTF-8) for the given + * window. Further updates using window_update_name_legacy will be ignored. + * + */ void window_update_name(i3Window *win, xcb_get_property_reply_t *prop); + +/** + * Updates the name by using WM_NAME (encoded in COMPOUND_TEXT). We do not + * touch what the client sends us but pass it to xcb_image_text_8. To get + * proper unicode rendering, the application has to use _NET_WM_NAME (see + * window_update_name()). + * + */ void window_update_name_legacy(i3Window *win, xcb_get_property_reply_t *prop); #endif diff --git a/include/x.h b/include/x.h index 1e564d4f..91af5014 100644 --- a/include/x.h +++ b/include/x.h @@ -5,12 +5,51 @@ #ifndef _X_H #define _X_H +/** + * Initializes the X11 part for the given container. Called exactly once for + * every container from con_new(). + * + */ void x_con_init(Con *con); + +/** + * Re-initializes the associated X window state for this container. You have + * to call this when you assign a client to an empty container to ensure that + * its state gets updated correctly. + * + */ void x_reinit(Con *con); + +/** + * Kills the window decoration associated with the given container. + * + */ void x_con_kill(Con *con); + +/** + * Kills the given X11 window using WM_DELETE_WINDOW (if supported). + * + */ void x_window_kill(xcb_window_t window); + +/** + * Draws the decoration of the given container onto its parent. + * + */ void x_draw_decoration(Con *con); + +/** + * Pushes all changes (state of each node, see x_push_node() and the window + * stack) to X11. + * + */ void x_push_changes(Con *con); + +/** + * Raises the specified container in the internal stack of X windows. The + * next call to x_push_changes() will make the change visible in X11. + * + */ void x_raise_con(Con *con); #endif diff --git a/src/con.c b/src/con.c index 1d8ca82e..dc9e0a54 100644 --- a/src/con.c +++ b/src/con.c @@ -24,7 +24,12 @@ char *colors[] = { "#aa00aa" }; - +/* + * Create a new container (and attach it to the given parent, if not NULL). + * This function initializes the data structures and creates the appropriate + * X11 IDs using x_con_init(). + * + */ Con *con_new(Con *parent) { Con *new = scalloc(sizeof(Con)); TAILQ_INSERT_TAIL(&all_cons, new, all_cons); @@ -56,6 +61,12 @@ Con *con_new(Con *parent) { return new; } +/* + * Attaches the given container to the given parent. This happens when moving + * a container or when inserting a new container at a specific place in the + * tree. + * + */ void con_attach(Con *con, Con *parent) { con->parent = parent; Con *current = TAILQ_FIRST(&(parent->focus_head)); @@ -72,6 +83,10 @@ void con_attach(Con *con, Con *parent) { TAILQ_INSERT_TAIL(&(parent->focus_head), con, focused); } +/* + * Detaches the given container from its current parent + * + */ void con_detach(Con *con) { if (con->type == CT_FLOATING_CON) { TAILQ_REMOVE(&(con->parent->floating_head), con, floating_windows); @@ -222,6 +237,11 @@ bool con_is_floating(Con *con) { return (con->floating >= FLOATING_AUTO_ON); } +/* + * Returns the container with the given client window ID or NULL if no such + * container exists. + * + */ Con *con_by_window_id(xcb_window_t window) { Con *con; TAILQ_FOREACH(con, &all_cons, all_cons) @@ -230,6 +250,11 @@ Con *con_by_window_id(xcb_window_t window) { return NULL; } +/* + * Returns the container with the given frame ID or NULL if no such container + * exists. + * + */ Con *con_by_frame_id(xcb_window_t frame) { Con *con; TAILQ_FOREACH(con, &all_cons, all_cons) @@ -286,6 +311,11 @@ void con_fix_percent(Con *con, int action) { } } +/* + * Toggles fullscreen mode for the given container. Fullscreen mode will not be + * entered when there already is a fullscreen container on this workspace. + * + */ void con_toggle_fullscreen(Con *con) { Con *workspace, *fullscreen; LOG("toggling fullscreen for %p / %s\n", con, con->name); @@ -324,6 +354,8 @@ void con_toggle_fullscreen(Con *con) { } /* + * Moves the given container to the currently focused container on the given + * workspace. * TODO: is there a better place for this function? * */ diff --git a/src/match.c b/src/match.c index 603be7bf..c384c41a 100644 --- a/src/match.c +++ b/src/match.c @@ -4,10 +4,21 @@ * i3 - an improved dynamic tiling window manager * © 2009-2010 Michael Stapelberg and contributors (see also: LICENSE) * + * A "match" is a data structure which acts like a mask or expression to match + * certain windows or not. For example, when using commands, you can specify a + * command like this: [title="*Firefox*"] kill. The title member of the match + * data structure will then be filled and i3 will check each window using + * match_matches_window() to find the windows affected by this command. + * */ #include "all.h" +/* + * Check if a match is empty. This is necessary while parsing commands to see + * whether the user specified a match at all. + * + */ bool match_is_empty(Match *match) { /* we cannot simply use memcmp() because the structure is part of a * TAILQ and I don’t want to start with things like assuming that the @@ -22,6 +33,10 @@ bool match_is_empty(Match *match) { match->floating == M_ANY); } +/* + * Check if a match data structure matches the given window. + * + */ bool match_matches_window(Match *match, i3Window *window) { /* TODO: pcre, full matching, … */ if (match->class != NULL && window->class_class != NULL && strcasecmp(match->class, window->class_class) == 0) { diff --git a/src/tree.c b/src/tree.c index 29b85730..9dc777c2 100644 --- a/src/tree.c +++ b/src/tree.c @@ -10,7 +10,7 @@ struct Con *focused; struct all_cons_head all_cons = TAILQ_HEAD_INITIALIZER(all_cons); /* - * Loads tree from ~/.i3/_restart.json + * Loads tree from ~/.i3/_restart.json (used for in-place restarts). * */ bool tree_restore() { @@ -201,6 +201,10 @@ void tree_close(Con *con, bool kill_window) { con_focus(next); } +/* + * Closes the current container using tree_close(). + * + */ void tree_close_con() { assert(focused != NULL); if (focused->type == CT_WORKSPACE) { @@ -248,6 +252,10 @@ void tree_split(Con *con, orientation_t orientation) { con_attach(con, new); } +/* + * Moves focus one level up. + * + */ void level_up() { /* We can focus up to the workspace, but not any higher in the tree */ if (focused->parent->type != CT_CON && @@ -258,6 +266,10 @@ void level_up() { con_focus(focused->parent); } +/* + * Moves focus one level down. + * + */ void level_down() { /* Go down the focus stack of the current node */ Con *next = TAILQ_FIRST(&(focused->focus_head)); @@ -276,6 +288,11 @@ static void mark_unmapped(Con *con) { mark_unmapped(current); } +/* + * Renders the tree, that is rendering all outputs using render_con() and + * pushing the changes to X11 using x_push_changes(). + * + */ void tree_render() { if (croot == NULL) return; @@ -296,6 +313,11 @@ void tree_render() { printf("-- END RENDERING --\n"); } +/* + * Changes focus in the given way (next/previous) and given orientation + * (horizontal/vertical). + * + */ void tree_next(char way, orientation_t orientation) { /* 1: get the first parent with the same orientation */ Con *parent = focused->parent; @@ -333,6 +355,11 @@ void tree_next(char way, orientation_t orientation) { con_focus(next); } +/* + * Moves the current container in the given way (next/previous) and given + * orientation (horizontal/vertical). + * + */ void tree_move(char way, orientation_t orientation) { /* 1: get the first parent with the same orientation */ Con *parent = focused->parent; diff --git a/src/x.c b/src/x.c index 8e879993..8fa52e02 100644 --- a/src/x.c +++ b/src/x.c @@ -105,6 +105,10 @@ void x_reinit(Con *con) { memset(&(state->window_rect), 0, sizeof(Rect)); } +/* + * Kills the window decoration associated with the given container. + * + */ void x_con_kill(Con *con) { con_state *state; @@ -137,6 +141,10 @@ static bool window_supports_protocol(xcb_window_t window, xcb_atom_t atom) { return result; } +/* + * Kills the given X11 window using WM_DELETE_WINDOW (if supported). + * + */ void x_window_kill(xcb_window_t window) { /* if this window does not support WM_DELETE_WINDOW, we kill it the hard way */ if (!window_supports_protocol(window, atoms[WM_DELETE_WINDOW])) { @@ -161,6 +169,10 @@ void x_window_kill(xcb_window_t window) { xcb_flush(conn); } +/* + * Draws the decoration of the given container onto its parent. + * + */ void x_draw_decoration(Con *con) { Con *parent;