From 58cbce0380fc65c2998837851abffe8525fc7182 Mon Sep 17 00:00:00 2001 From: Lars Hartmann Date: Mon, 29 Jun 2009 21:54:51 +0200 Subject: [PATCH] updated doxygen docu, added FIXMEs, fixed headers to 80chars width. --- include/client.h | 35 +++--- include/commands.h | 3 +- include/config.h | 2 + include/data.h | 261 ++++++++++++++++++++++++++------------------- include/floating.h | 38 ++++--- include/handlers.h | 104 ++++++++++-------- include/layout.h | 43 ++++---- include/manage.h | 11 +- include/resize.h | 5 +- include/table.h | 26 ++++- include/util.h | 66 ++++++------ include/xcb.h | 51 +++++---- include/xinerama.h | 14 +-- 13 files changed, 383 insertions(+), 276 deletions(-) diff --git a/include/client.h b/include/client.h index 85a41531..8fbd4434 100644 --- a/include/client.h +++ b/include/client.h @@ -16,15 +16,17 @@ #define _CLIENT_H /** - * Removes the given client from the container, either because it will be inserted into another - * one or because it was unmapped + * Removes the given client from the container, either because it will be + * inserted into another one or because it was unmapped * */ -void client_remove_from_container(xcb_connection_t *conn, Client *client, Container *container, bool remove_from_focusstack); +void client_remove_from_container(xcb_connection_t *conn, Client *client, + Container *container, + bool remove_from_focusstack); /** - * Warps the pointer into the given client (in the middle of it, to be specific), therefore - * selecting it + * Warps the pointer into the given client (in the middle of it, to be + * specific), therefore selecting it * */ void client_warp_pointer_into(xcb_connection_t *conn, Client *client); @@ -36,8 +38,8 @@ void client_warp_pointer_into(xcb_connection_t *conn, Client *client); void client_kill(xcb_connection_t *conn, Client *window); /** - * Checks if the given window class and title match the given client - * Window title is passed as "normal" string and as UCS-2 converted string for + * Checks if the given window class and title match the given client Window + * title is passed as "normal" string and as UCS-2 converted string for * matching _NET_WM_NAME capable clients as well as those using legacy hints. * */ @@ -52,25 +54,26 @@ bool client_matches_class_name(Client *client, char *to_class, char *to_title, void client_enter_fullscreen(xcb_connection_t *conn, Client *client); /** - * Toggles fullscreen mode for the given client. It updates the data structures and - * reconfigures (= resizes/moves) the client and its frame to the full size of the - * screen. When leaving fullscreen, re-rendering the layout is forced. + * Toggles fullscreen mode for the given client. It updates the data + * structures and reconfigures (= resizes/moves) the client and its frame to + * the full size of the screen. When leaving fullscreen, re-rendering the + * layout is forced. * */ void client_toggle_fullscreen(xcb_connection_t *conn, Client *client); /** - * Sets the position of the given client in the X stack to the highest (tiling layer is always - * on the same position, so this doesn’t matter) below the first floating client, so that - * floating windows are always on top. + * Sets the position of the given client in the X stack to the highest (tiling + * layer is always on the same position, so this doesn’t matter) below the + * first floating client, so that floating windows are always on top. * */ void client_set_below_floating(xcb_connection_t *conn, Client *client); /** - * Returns true if the client is floating. Makes the code more beatiful, as floating - * is not simply a boolean, but also saves whether the user selected the current state - * or whether it was automatically set. + * Returns true if the client is floating. Makes the code more beatiful, as + * floating is not simply a boolean, but also saves whether the user selected + * the current state or whether it was automatically set. * */ bool client_is_floating(Client *client); diff --git a/include/commands.h b/include/commands.h index 88c735b9..30ea1110 100644 --- a/include/commands.h +++ b/include/commands.h @@ -13,7 +13,8 @@ #include -bool focus_window_in_container(xcb_connection_t *conn, Container *container, direction_t direction); +bool focus_window_in_container(xcb_connection_t *conn, Container *container, + direction_t direction); /** Switches to the given workspace */ void show_workspace(xcb_connection_t *conn, int workspace); diff --git a/include/config.h b/include/config.h index 1e85d471..cbfeaf1b 100644 --- a/include/config.h +++ b/include/config.h @@ -12,6 +12,8 @@ * */ +/* FIXME: this file lacks documentation */ + #ifndef _CONFIG_H #define _CONFIG_H diff --git a/include/data.h b/include/data.h index b468c1f7..386e49cc 100644 --- a/include/data.h +++ b/include/data.h @@ -19,24 +19,28 @@ #include "queue.h" /* - * To get the big concept: There are helper structures like struct Colorpixel or - * struct Stack_Window. Everything which is also defined as type (see forward definitions) - * is considered to be a major structure, thus important. + * To get the big concept: There are helper structures like struct Colorpixel + * or struct Stack_Window. Everything which is also defined as type (see + * forward definitions) is considered to be a major structure, thus important. * * Let’s start from the biggest to the smallest: - * - An i3Screen is a virtual screen (Xinerama). This can be a single one, though two monitors - * might be connected, if you’re running clone mode. There can also be multiple of them. * - * - Each i3Screen contains Workspaces. The concept is known from various other window managers. - * Basically, a workspace is a specific set of windows, usually grouped thematically (irc, - * www, work, …). You can switch between these. + * - An i3Screen is a virtual screen (Xinerama). This can be a single one, + * though two monitors might be connected, if you’re running clone + * mode. There can also be multiple of them. * - * - Each Workspace has a table, which is our layout abstraction. You manage your windows - * by moving them around in your table. It grows as necessary. + * - Each i3Screen contains Workspaces. The concept is known from various + * other window managers. Basically, a workspace is a specific set of + * windows, usually grouped thematically (irc, www, work, …). You can switch + * between these. * - * - Each cell of the table has a container, which can be in default or stacking mode. In default - * mode, each client is given equally much space in the container. In stacking mode, only one - * client is shown at a time, but all the titlebars are rendered at the top. + * - Each Workspace has a table, which is our layout abstraction. You manage + * your windows by moving them around in your table. It grows as necessary. + * + * - Each cell of the table has a container, which can be in default or + * stacking mode. In default mode, each client is given equally much space + * in the container. In stacking mode, only one client is shown at a time, + * but all the titlebars are rendered at the top. * * - Inside the container are clients, which is X11-speak for a window. * @@ -69,12 +73,16 @@ enum { BIND_MODE_SWITCH = (1 << 8) }; +/** + * FIXME: needs to be documented + * + */ struct Rect { uint32_t x, y; uint32_t width, height; }; -/* +/** * Defines a position in the table * */ @@ -83,20 +91,19 @@ struct Cell { int column; }; -/* +/** * Used for the cache of colorpixels. * */ struct Colorpixel { uint32_t pixel; - char *hex; - SLIST_ENTRY(Colorpixel) colorpixels; }; -/* - * Contains data for the windows needed to draw the titlebars on in stacking mode +/** + * Contains data for the windows needed to draw the titlebars on in stacking + * mode * */ struct Stack_Window { @@ -104,7 +111,7 @@ struct Stack_Window { xcb_gcontext_t gc; Rect rect; - /* Backpointer to the container this stack window is in */ + /** Backpointer to the container this stack window is in */ Container *container; SLIST_ENTRY(Stack_Window) stack_windows; @@ -117,17 +124,21 @@ struct Ignore_Event { SLIST_ENTRY(Ignore_Event) ignore_events; }; -/* - * Emulates the behaviour of tables of libxcb-wm, which in libxcb 0.3.4 suddenly vanished. +/** + * Emulates the behaviour of tables of libxcb-wm, which in libxcb 0.3.4 + * suddenly vanished. * */ struct keyvalue_element { uint32_t key; void *value; - TAILQ_ENTRY(keyvalue_element) elements; }; +/** + * FIXME: needs documentation. + * + */ typedef struct { enum xcb_atom_fast_tag_t tag; union { @@ -140,202 +151,226 @@ typedef struct { * Major types *****************************************************************************/ -/* - * The concept of Workspaces is known from various other window managers. Basically, - * a workspace is a specific set of windows, usually grouped thematically (irc, - * www, work, …). You can switch between these. +/** + * The concept of Workspaces is known from various other window + * managers. Basically, a workspace is a specific set of windows, usually + * grouped thematically (irc, www, work, …). You can switch between these. * */ struct Workspace { - /* Number of this workspace, starting from 0 */ + /** Number of this workspace, starting from 0 */ int num; - /* x, y, width, height */ + /** x, y, width, height */ Rect rect; - /* table dimensions */ + /** table dimensions */ int cols; + /** table dimensions */ int rows; - /* These are stored here only while this workspace is _not_ shown (see show_workspace()) */ + /** These are stored here only while this workspace is _not_ shown + * (see show_workspace()) */ int current_row; + /** These are stored here only while this workspace is _not_ shown + * (see show_workspace()) */ int current_col; - /* Should clients on this workspace be automatically floating? */ + /** Should clients on this workspace be automatically floating? */ bool auto_float; - /* Are the floating clients on this workspace currently hidden? */ + /** Are the floating clients on this workspace currently hidden? */ bool floating_hidden; + /** the client who is started in fullscreen mode on this workspace, + * NULL if there is none */ Client *fullscreen_client; - /* The focus stack contains the clients in the correct order of focus so that - the focus can be reverted correctly when a client is closed */ + /** The focus stack contains the clients in the correct order of focus + so that the focus can be reverted correctly when a client is + closed */ SLIST_HEAD(focus_stack_head, Client) focus_stack; - /* This tail queue contains the floating clients in order of when they were first - * set to floating (new floating clients are just appended) */ + /** This tail queue contains the floating clients in order of when + * they were first set to floating (new floating clients are just + * appended) */ TAILQ_HEAD(floating_clients_head, Client) floating_clients; - /* Backpointer to the screen this workspace is on */ + /** Backpointer to the screen this workspace is on */ i3Screen *screen; - /* This is a two-dimensional dynamic array of Container-pointers. I’ve always wanted - * to be a three-star programmer :) */ + /** This is a two-dimensional dynamic array of + * Container-pointers. I’ve always wanted to be a three-star + * programmer :) */ Container ***table; - /* width_factor and height_factor contain the amount of space (percentage) a column/row - has of all the space which is available for resized windows. This ensures that - non-resized windows (newly opened, for example) have the same size as always */ + /** width_factor and height_factor contain the amount of space + * (percentage) a column/row has of all the space which is available + * for resized windows. This ensures that non-resized windows (newly + * opened, for example) have the same size as always */ float *width_factor; float *height_factor; }; -/* - * Holds a keybinding, consisting of a keycode combined with modifiers and the command - * which is executed as soon as the key is pressed (see src/command.c) +/** + * Holds a keybinding, consisting of a keycode combined with modifiers and the + * command which is executed as soon as the key is pressed (see src/command.c) * */ struct Binding { - /* Keycode to bind */ + /** Keycode to bind */ uint32_t keycode; - /* Bitmask consisting of BIND_MOD_1, BIND_MODE_SWITCH, … */ + /** Bitmask consisting of BIND_MOD_1, BIND_MODE_SWITCH, … */ uint32_t mods; - /* Command, like in command mode */ + /** Command, like in command mode */ char *command; - TAILQ_ENTRY(Binding) bindings; }; -/* +/** * Holds a command specified by an exec-line in the config (see src/config.c) * */ struct Autostart { - /* Command, like in command mode */ + /** Command, like in command mode */ char *command; TAILQ_ENTRY(Autostart) autostarts; }; -/* +/** * Holds an assignment for a given window class/title to a specific workspace * (see src/config.c) * */ struct Assignment { char *windowclass_title; - /* floating is true if this was an assignment to the special workspace "~". - * Matching clients will be put into floating mode automatically. */ + /** floating is true if this was an assignment to the special + * workspace "~". Matching clients will be put into floating mode + * automatically. */ bool floating; + /** FIXME: needs documentation */ int workspace; TAILQ_ENTRY(Assignment) assignments; }; -/* +/** * Data structure for cached font information: * - font id in X11 (load it once) * - font height (multiple calls needed to get it) * */ struct Font { - /* The name of the font, that is what the pattern resolves to */ + /** The name of the font, that is what the pattern resolves to */ char *name; - /* A copy of the pattern to build a cache */ + /** A copy of the pattern to build a cache */ char *pattern; - /* The height of the font, built from font_ascent + font_descent */ + /** The height of the font, built from font_ascent + font_descent */ int height; - /* The xcb-id for the font */ + /** The xcb-id for the font */ xcb_font_t id; TAILQ_ENTRY(Font) fonts; }; -/* +/** * A client is X11-speak for a window. * */ struct Client { - /* initialized will be set to true if the client was fully initialized by - * manage_window() and all functions can be used normally */ + /** initialized will be set to true if the client was fully + * initialized by manage_window() and all functions can be used + * normally */ bool initialized; - /* if you set a client to floating and set it back to managed, it does remember its old - position and *tries* to get back there */ + /** if you set a client to floating and set it back to managed, it + * does remember its old position and *tries* to get back there */ Cell old_position; - /* Backpointer. A client is inside a container */ + /** Backpointer. A client is inside a container */ Container *container; - /* Because dock clients don’t have a container, we have this workspace-backpointer */ + /** Because dock clients don’t have a container, we have this + * workspace-backpointer */ Workspace *workspace; - /* x, y, width, height of the frame */ + /** x, y, width, height of the frame */ Rect rect; - /* Position in floating mode and in tiling mode are saved separately */ + /** Position in floating mode and in tiling mode are saved + * separately */ Rect floating_rect; - /* x, y, width, height of the child (relative to its frame) */ + /** x, y, width, height of the child (relative to its frame) */ Rect child_rect; - /* contains the size calculated from the hints set by the window or 0 if the client - did not send any hints */ + /** contains the size calculated from the hints set by the window or 0 + * if the client did not send any hints */ int proportional_height; int proportional_width; - /* Height which was determined by reading the _NET_WM_STRUT_PARTIAL top/bottom of the screen - reservation */ + /** Height which was determined by reading the _NET_WM_STRUT_PARTIAL + * top/bottom of the screen reservation */ int desired_height; - /* Name (= window title) */ + /** Name (= window title) */ char *name; - /* name_len stores the real string length (glyphs) of the window title if the client uses - _NET_WM_NAME. Otherwise, it is set to -1 to indicate that name should be just passed - to X as 8-bit string and therefore will not be rendered correctly. This behaviour is - to support legacy applications which do not set _NET_WM_NAME */ + /** name_len stores the real string length (glyphs) of the window + * title if the client uses _NET_WM_NAME. Otherwise, it is set to -1 + * to indicate that name should be just passed to X as 8-bit string + * and therefore will not be rendered correctly. This behaviour is to + * support legacy applications which do not set _NET_WM_NAME */ int name_len; - /* This will be set to true as soon as the first _NET_WM_NAME comes in. If set to true, - legacy window names are ignored. */ + /** This will be set to true as soon as the first _NET_WM_NAME comes + * in. If set to true, legacy window names are ignored. */ bool uses_net_wm_name; - /* Holds the WM_CLASS, useful for matching the client in commands */ + /** Holds the WM_CLASS, useful for matching the client in commands */ char *window_class; - /* fullscreen is pretty obvious */ + /** fullscreen is pretty obvious */ bool fullscreen; - /* floating? (= not in tiling layout) This cannot be simply a bool because we want to keep track - * of whether the status was set by the application (by setting WM_CLASS to tools for example) or - * by the user. The user’s choice overwrites automatic mode, of course. The order of the values - * is important because we check with >= FLOATING_AUTO_ON if a client is floating. */ + /** floating? (= not in tiling layout) This cannot be simply a bool + * because we want to keep track of whether the status was set by the + * application (by setting WM_CLASS to tools for example) or by the + * user. The user’s choice overwrites automatic mode, of course. The + * order of the values is important because we check with >= + * FLOATING_AUTO_ON if a client is floating. */ enum { FLOATING_AUTO_OFF = 0, FLOATING_USER_OFF = 1, FLOATING_AUTO_ON = 2, FLOATING_USER_ON = 3 } floating; - /* Ensure TITLEBAR_TOP maps to 0 because we use calloc for initialization later */ + /** Ensure TITLEBAR_TOP maps to 0 because we use calloc for + * initialization later */ enum { TITLEBAR_TOP = 0, TITLEBAR_LEFT, TITLEBAR_RIGHT, TITLEBAR_BOTTOM, TITLEBAR_OFF } titlebar_position; - /* If a client is set as a dock, it is placed at the very bottom of the screen and its - requested size is used */ + /** If a client is set as a dock, it is placed at the very bottom of + * the screen and its requested size is used */ bool dock; - /* After leaving fullscreen mode, a client needs to be reconfigured (configuration = - setting X, Y, width and height). By setting the force_reconfigure flag, render_layout() - will reconfigure the client. */ + /* After leaving fullscreen mode, a client needs to be reconfigured + * (configuration = setting X, Y, width and height). By setting the + * force_reconfigure flag, render_layout() will reconfigure the + * client. */ bool force_reconfigure; - /* When reparenting a window, an unmap-notify is sent. As we delete windows when they’re - unmapped, we need to ignore that one. Therefore, this flag is set when reparenting. */ + /* When reparenting a window, an unmap-notify is sent. As we delete + * windows when they’re unmapped, we need to ignore that + * one. Therefore, this flag is set when reparenting. */ bool awaiting_useless_unmap; /* XCB contexts */ - xcb_window_t frame; /* Our window: The frame around the client */ - xcb_gcontext_t titlegc; /* The titlebar’s graphic context inside the frame */ - xcb_window_t child; /* The client’s window */ + xcb_window_t frame; /**< Our window: The frame around the + * client */ + xcb_gcontext_t titlegc; /**< The titlebar’s graphic context + * inside the frame */ + xcb_window_t child; /**< The client’s window */ - /* The following entry provides the necessary list pointers to use Client with LIST_* macros */ + /** The following entry provides the necessary list pointers to use + * Client with LIST_* macros */ CIRCLEQ_ENTRY(Client) clients; SLIST_ENTRY(Client) dock_clients; SLIST_ENTRY(Client) focus_clients; TAILQ_ENTRY(Client) floating_clients; }; -/* - * A container is either in default or stacking mode. It sits inside each cell of the table. +/** + * A container is either in default or stacking mode. It sits inside each cell + * of the table. * */ struct Container { @@ -354,37 +389,41 @@ struct Container { int width; int height; - /* When in stacking mode, we draw the titlebars of each client onto a separate window */ + /* When in stacking mode, we draw the titlebars of each client onto a + * separate window */ struct Stack_Window stack_win; /* Backpointer to the workspace this container is in */ Workspace *workspace; - /* Ensure MODE_DEFAULT maps to 0 because we use calloc for initialization later */ + /* Ensure MODE_DEFAULT maps to 0 because we use calloc for + * initialization later */ enum { MODE_DEFAULT = 0, MODE_STACK } mode; CIRCLEQ_HEAD(client_head, Client) clients; }; -/* - * This is a virtual screen (Xinerama). This can be a single one, though two monitors - * might be connected, if you’re running clone mode. There can also be multiple of them. +/** + * This is a virtual screen (Xinerama). This can be a single one, though two + * monitors might be connected, if you’re running clone mode. There can also + * be multiple of them. * */ struct Screen { - /* Virtual screen number */ + /** Virtual screen number */ int num; - /* Current workspace selected on this virtual screen */ + /** Current workspace selected on this virtual screen */ int current_workspace; - /* x, y, width, height */ + /** x, y, width, height */ Rect rect; - /* The bar window */ + /** The bar window */ xcb_window_t bar; xcb_gcontext_t bargc; - /* Contains all clients with _NET_WM_WINDOW_TYPE == _NET_WM_WINDOW_TYPE_DOCK */ + /** Contains all clients with _NET_WM_WINDOW_TYPE == + * _NET_WM_WINDOW_TYPE_DOCK */ SLIST_HEAD(dock_clients_head, Client) dock_clients; TAILQ_ENTRY(Screen) screens; diff --git a/include/floating.h b/include/floating.h index b0c0b7cc..6169d7b4 100644 --- a/include/floating.h +++ b/include/floating.h @@ -18,38 +18,42 @@ typedef void(*callback_t)(Rect*, uint32_t, uint32_t); typedef enum { BORDER_LEFT, BORDER_RIGHT, BORDER_TOP, BORDER_BOTTOM} border_t; /** - * Enters floating mode for the given client. - * Correctly takes care of the position/size (separately stored for tiling/floating mode) - * and repositions/resizes/redecorates the client. + * Enters floating mode for the given client. Correctly takes care of the + * position/size (separately stored for tiling/floating mode) and + * repositions/resizes/redecorates the client. * - * If the automatic flag is set to true, this was an automatic update by a change of the - * window class from the application which can be overwritten by the user. + * If the automatic flag is set to true, this was an automatic update by a + * change of the window class from the application which can be overwritten by + * the user. * */ -void toggle_floating_mode(xcb_connection_t *conn, Client *client, bool automatic); +void toggle_floating_mode(xcb_connection_t *conn, Client *client, + bool automatic); /** - * Removes the floating client from its workspace and attaches it to the new workspace. - * This is centralized here because it may happen if you move it via keyboard and - * if you move it using your mouse. + * Removes the floating client from its workspace and attaches it to the new + * workspace. This is centralized here because it may happen if you move it + * via keyboard and if you move it using your mouse. * */ void floating_assign_to_workspace(Client *client, Workspace *new_workspace); /** - * Called whenever the user clicks on a border (not the titlebar!) of a floating window. - * Determines on which border the user clicked and launches the drag_pointer function - * with the resize_callback. + * Called whenever the user clicks on a border (not the titlebar!) of a + * floating window. Determines on which border the user clicked and launches + * the drag_pointer function with the resize_callback. * */ -int floating_border_click(xcb_connection_t *conn, Client *client, xcb_button_press_event_t *event); +int floating_border_click(xcb_connection_t *conn, Client *client, + xcb_button_press_event_t *event); /** * Called when the user clicked on the titlebar of a floating window. * Calls the drag_pointer function with the drag_window callback * */ -void floating_drag_window(xcb_connection_t *conn, Client *client, xcb_button_press_event_t *event); +void floating_drag_window(xcb_connection_t *conn, Client *client, + xcb_button_press_event_t *event); /** * Changes focus in the given direction for floating clients. @@ -58,13 +62,15 @@ void floating_drag_window(xcb_connection_t *conn, Client *client, xcb_button_pre * changing to top/bottom means cycling through the Z-index. * */ -void floating_focus_direction(xcb_connection_t *conn, Client *currently_focused, direction_t direction); +void floating_focus_direction(xcb_connection_t *conn, Client *currently_focused, + direction_t direction); /** * Moves the client 10px to the specified direction. * */ -void floating_move(xcb_connection_t *conn, Client *currently_focused, direction_t direction); +void floating_move(xcb_connection_t *conn, Client *currently_focused, + direction_t direction); /** * Hides all floating clients (or show them if they are currently hidden) on diff --git a/include/handlers.h b/include/handlers.h index b4b2c99a..74e29e4b 100644 --- a/include/handlers.h +++ b/include/handlers.h @@ -12,56 +12,65 @@ #define _HANDLERS_H /** - * Due to bindings like Mode_switch + , we need to bind some keys in XCB_GRAB_MODE_SYNC. - * Therefore, we just replay all key presses. + * Due to bindings like Mode_switch + , we need to bind some keys in + * XCB_GRAB_MODE_SYNC. Therefore, we just replay all key presses. * */ -int handle_key_release(void *ignored, xcb_connection_t *conn, xcb_key_release_event_t *event); +int handle_key_release(void *ignored, xcb_connection_t *conn, + xcb_key_release_event_t *event); /** - * There was a key press. We compare this key code with our bindings table and pass - * the bound action to parse_command(). + * There was a key press. We compare this key code with our bindings table and + * pass the bound action to parse_command(). * */ -int handle_key_press(void *ignored, xcb_connection_t *conn, xcb_key_press_event_t *event); +int handle_key_press(void *ignored, xcb_connection_t *conn, + xcb_key_press_event_t *event); /** - * When the user moves the mouse pointer onto a window, this callback gets called. + * When the user moves the mouse pointer onto a window, this callback gets + * called. * */ -int handle_enter_notify(void *ignored, xcb_connection_t *conn, xcb_enter_notify_event_t *event); +int handle_enter_notify(void *ignored, xcb_connection_t *conn, + xcb_enter_notify_event_t *event); /** - * Checks if the button press was on a stack window, handles focus setting and returns true - * if so, or false otherwise. + * Checks if the button press was on a stack window, handles focus setting and + * returns true if so, or false otherwise. * */ -int handle_button_press(void *ignored, xcb_connection_t *conn, xcb_button_press_event_t *event); +int handle_button_press(void *ignored, xcb_connection_t *conn, + xcb_button_press_event_t *event); /** * A new window appeared on the screen (=was mapped), so let’s manage it. * */ -int handle_map_request(void *prophs, xcb_connection_t *conn, xcb_map_request_event_t *event); +int handle_map_request(void *prophs, xcb_connection_t *conn, + xcb_map_request_event_t *event); /** - * Configuration notifies are only handled because we need to set up ignore for the following - * enter notify events + * Configuration notifies are only handled because we need to set up ignore + * for the following enter notify events * */ int handle_configure_event(void *prophs, xcb_connection_t *conn, xcb_configure_notify_event_t *event); /** - * Configure requests are received when the application wants to resize windows on their own. + * Configure requests are received when the application wants to resize + * windows on their own. * - * We generate a synthethic configure notify event to signalize the client its "new" position. + * We generate a synthethic configure notify event to signalize the client its + * "new" position. * */ -int handle_configure_request(void *prophs, xcb_connection_t *conn, xcb_configure_request_event_t *event); +int handle_configure_request(void *prophs, xcb_connection_t *conn, + xcb_configure_request_event_t *event); /** - * Our window decorations were unmapped. That means, the window will be killed now, - * so we better clean up before. + * Our window decorations were unmapped. That means, the window will be killed + * now, so we better clean up before. * */ int handle_unmap_notify_event(void *data, xcb_connection_t *conn, xcb_unmap_notify_event_t *event); @@ -71,67 +80,78 @@ int handle_unmap_notify_event(void *data, xcb_connection_t *conn, xcb_unmap_noti * */ int handle_windowname_change(void *data, xcb_connection_t *conn, uint8_t state, - xcb_window_t window, xcb_atom_t atom, xcb_get_property_reply_t *prop); + xcb_window_t window, xcb_atom_t atom, + xcb_get_property_reply_t *prop); /** - * We handle legacy window names (titles) which are in COMPOUND_TEXT encoding. However, we - * just pass them along, so when containing non-ASCII characters, those will be rendering - * incorrectly. In order to correctly render unicode window titles in i3, an application - * has to set _NET_WM_NAME, which is in UTF-8 encoding. + * We handle legacy window names (titles) which are in COMPOUND_TEXT + * encoding. However, we just pass them along, so when containing non-ASCII + * characters, those will be rendering incorrectly. In order to correctly + * render unicode window titles in i3, an application has to set _NET_WM_NAME, + * which is in UTF-8 encoding. * - * On every update, a message is put out to the user, so he may improve the situation and - * update applications which display filenames in their title to correctly use - * _NET_WM_NAME and therefore support unicode. + * On every update, a message is put out to the user, so he may improve the + * situation and update applications which display filenames in their title to + * correctly use _NET_WM_NAME and therefore support unicode. * */ -int handle_windowname_change_legacy(void *data, xcb_connection_t *conn, uint8_t state, - xcb_window_t window, xcb_atom_t atom, xcb_get_property_reply_t *prop); +int handle_windowname_change_legacy(void *data, xcb_connection_t *conn, + uint8_t state, xcb_window_t window, + xcb_atom_t atom, xcb_get_property_reply_t + *prop); /** * Store the window classes for jumping to them later. * */ int handle_windowclass_change(void *data, xcb_connection_t *conn, uint8_t state, - xcb_window_t window, xcb_atom_t atom, xcb_get_property_reply_t *prop); + xcb_window_t window, xcb_atom_t atom, + xcb_get_property_reply_t *prop); /** * Expose event means we should redraw our windows (= title bar) * */ -int handle_expose_event(void *data, xcb_connection_t *conn, xcb_expose_event_t *event); +int handle_expose_event(void *data, xcb_connection_t *conn, + xcb_expose_event_t *event); /** * Handle client messages (EWMH) * */ -int handle_client_message(void *data, xcb_connection_t *conn, xcb_client_message_event_t *event); +int handle_client_message(void *data, xcb_connection_t *conn, + xcb_client_message_event_t *event); /** * Handles _NET_WM_WINDOW_TYPE changes * */ -int handle_window_type(void *data, xcb_connection_t *conn, uint8_t state, xcb_window_t window, - xcb_atom_t atom, xcb_get_property_reply_t *property); +int handle_window_type(void *data, xcb_connection_t *conn, uint8_t state, + xcb_window_t window, xcb_atom_t atom, + xcb_get_property_reply_t *property); /** - * Handles the size hints set by a window, but currently only the part necessary for displaying - * clients proportionally inside their frames (mplayer for example) + * Handles the size hints set by a window, but currently only the part + * necessary for displaying clients proportionally inside their frames + * (mplayer for example) * * See ICCCM 4.1.2.3 for more details * */ -int handle_normal_hints(void *data, xcb_connection_t *conn, uint8_t state, xcb_window_t window, - xcb_atom_t name, xcb_get_property_reply_t *reply); +int handle_normal_hints(void *data, xcb_connection_t *conn, uint8_t state, + xcb_window_t window, xcb_atom_t name, + xcb_get_property_reply_t *reply); /** - * Handles the transient for hints set by a window, signalizing that this window is a popup window - * for some other window. + * Handles the transient for hints set by a window, signalizing that this + * window is a popup window for some other window. * * See ICCCM 4.1.2.6 for more details * */ -int handle_transient_for(void *data, xcb_connection_t *conn, uint8_t state, xcb_window_t window, - xcb_atom_t name, xcb_get_property_reply_t *reply); +int handle_transient_for(void *data, xcb_connection_t *conn, uint8_t state, + xcb_window_t window, xcb_atom_t name, + xcb_get_property_reply_t *reply); #endif diff --git a/include/layout.h b/include/layout.h index 53dfbb9d..7fbce691 100644 --- a/include/layout.h +++ b/include/layout.h @@ -14,24 +14,27 @@ #define _LAYOUT_H /** - * Gets the unoccupied space (= space which is available for windows which were resized by the user) - * This is necessary to render both, customly resized windows and never touched - * windows correctly, meaning that the aspect ratio will be maintained when opening new windows. + * Gets the unoccupied space (= space which is available for windows which + * were resized by the user) This is necessary to render both, customly + * resized windows and never touched windows correctly, meaning that the + * aspect ratio will be maintained when opening new windows. * */ int get_unoccupied_x(Workspace *workspace); /** - * (Re-)draws window decorations for a given Client onto the given drawable/graphic context. - * When in stacking mode, the window decorations are drawn onto an own window. + * (Re-)draws window decorations for a given Client onto the given + * drawable/graphic context. When in stacking mode, the window decorations + * are drawn onto an own window. * */ -void decorate_window(xcb_connection_t *conn, Client *client, xcb_drawable_t drawable, xcb_gcontext_t gc, int offset); +void decorate_window(xcb_connection_t *conn, Client *client, + xcb_drawable_t drawable, xcb_gcontext_t gc, int offset); /** - * Redecorates the given client correctly by checking if it’s in a stacking container and - * re-rendering the stack window or just calling decorate_window if it’s not in a stacking - * container. + * Redecorates the given client correctly by checking if it’s in a stacking + * container and re-rendering the stack window or just calling decorate_window + * if it’s not in a stacking container. * */ void redecorate_window(xcb_connection_t *conn, Client *client); @@ -49,19 +52,21 @@ void reposition_client(xcb_connection_t *conn, Client *client); void resize_client(xcb_connection_t *conn, Client *client); /** - * Renders the given container. Is called by render_layout() or individually (for example - * when focus changes in a stacking container) + * Renders the given container. Is called by render_layout() or individually + * (for example when focus changes in a stacking container) * */ void render_container(xcb_connection_t *conn, Container *container); /** - * Modifies the event mask of all clients on the given workspace to either ignore or to handle - * enter notifies. It is handy to ignore notifies because they will be sent when a window is mapped - * under the cursor, thus when the user didn’t enter the window actively at all. + * Modifies the event mask of all clients on the given workspace to either + * ignore or to handle enter notifies. It is handy to ignore notifies because + * they will be sent when a window is mapped under the cursor, thus when the + * user didn’t enter the window actively at all. * */ -void ignore_enter_notify_forall(xcb_connection_t *conn, Workspace *workspace, bool ignore_enter_notify); +void ignore_enter_notify_forall(xcb_connection_t *conn, Workspace *workspace, + bool ignore_enter_notify); /** * Renders the given workspace on the given screen @@ -70,11 +75,11 @@ void ignore_enter_notify_forall(xcb_connection_t *conn, Workspace *workspace, bo void render_workspace(xcb_connection_t *conn, i3Screen *screen, Workspace *r_ws); /** - * Renders the whole layout, that is: Go through each screen, each workspace, each container - * and render each client. This also renders the bars. + * Renders the whole layout, that is: Go through each screen, each workspace, + * each container and render each client. This also renders the bars. * - * If you don’t need to render *everything*, you should call render_container on the container - * you want to refresh. + * If you don’t need to render *everything*, you should call render_container + * on the container you want to refresh. * */ void render_layout(xcb_connection_t *conn); diff --git a/include/manage.h b/include/manage.h index 52816e37..297d7ae8 100644 --- a/include/manage.h +++ b/include/manage.h @@ -16,10 +16,12 @@ #define _MANAGE_H /** - * Go through all existing windows (if the window manager is restarted) and manage them + * Go through all existing windows (if the window manager is restarted) and + * manage them * */ -void manage_existing_windows(xcb_connection_t *conn, xcb_property_handlers_t *prophs, xcb_window_t root); +void manage_existing_windows(xcb_connection_t *conn, xcb_property_handlers_t + *prophs, xcb_window_t root); /** * Do some sanity checks and then reparent the window. @@ -29,8 +31,9 @@ void manage_window(xcb_property_handlers_t *prophs, xcb_connection_t *conn, xcb_window_t window, window_attributes_t wa); /** - * reparent_window() gets called when a new window was opened and becomes a child of the root - * window, or it gets called by us when we manage the already existing windows at startup. + * reparent_window() gets called when a new window was opened and becomes a + * child of the root window, or it gets called by us when we manage the + * already existing windows at startup. * * Essentially, this is the point where we take over control. * diff --git a/include/resize.h b/include/resize.h index 520d4398..4a206c0e 100644 --- a/include/resize.h +++ b/include/resize.h @@ -21,7 +21,8 @@ typedef enum { O_HORIZONTAL, O_VERTICAL } resize_orientation_t; * the table column/row. * */ -int resize_graphical_handler(xcb_connection_t *conn, Workspace *ws, int first, int second, - resize_orientation_t orientation, xcb_button_press_event_t *event); +int resize_graphical_handler(xcb_connection_t *conn, Workspace *ws, int first, + int second, resize_orientation_t orientation, + xcb_button_press_event_t *event); #endif diff --git a/include/table.h b/include/table.h index de83c7d0..355839b1 100644 --- a/include/table.h +++ b/include/table.h @@ -37,19 +37,35 @@ void expand_table_rows_at_head(Workspace *workspace); /** Add one column to the table */ void expand_table_cols(Workspace *workspace); -/** Inserts one column at the table’s head */ +/** + * Inserts one column at the table’s head + * + */ void expand_table_cols_at_head(Workspace *workspace); -/** Performs simple bounds checking for the given column/row */ +/** + * Performs simple bounds checking for the given column/row + * + */ bool cell_exists(int col, int row); -/** Shrinks the table by "compacting" it, that is, removing completely empty rows/columns */ +/** + * Shrinks the table by "compacting" it, that is, removing completely empty + * rows/columns + * + */ void cleanup_table(xcb_connection_t *conn, Workspace *workspace); -/** Fixes col/rowspan (makes sure there are no overlapping windows) */ +/** + * Fixes col/rowspan (makes sure there are no overlapping windows) + * + */ void fix_colrowspan(xcb_connection_t *conn, Workspace *workspace); -/** Prints the table’s contents in human-readable form for debugging */ +/** + * Prints the table’s contents in human-readable form for debugging + * + */ void dump_table(xcb_connection_t *conn, Workspace *workspace); #endif diff --git a/include/util.h b/include/util.h index 3fd6b18a..bc2dc5e0 100644 --- a/include/util.h +++ b/include/util.h @@ -32,8 +32,8 @@ } \ while (0) -/* ##__VA_ARGS__ means: leave out __VA_ARGS__ completely if it is empty, that is, - delete the preceding comma */ +/** ##__VA_ARGS__ means: leave out __VA_ARGS__ completely if it is empty, that + is, delete the preceding comma */ #define LOG(fmt, ...) slog("%s:%s:%d - " fmt, __FILE__, __FUNCTION__, __LINE__, ##__VA_ARGS__) TAILQ_HEAD(keyvalue_table_head, keyvalue_element); @@ -57,22 +57,22 @@ void slog(char *fmt, ...); void die(char *fmt, ...) __attribute__((__noreturn__)); /** - * Safe-wrapper around malloc which exits if malloc returns NULL (meaning that there - * is no more memory available) + * Safe-wrapper around malloc which exits if malloc returns NULL (meaning that + * there is no more memory available) * */ void *smalloc(size_t size); /** - * Safe-wrapper around calloc which exits if malloc returns NULL (meaning that there - * is no more memory available) + * Safe-wrapper around calloc which exits if malloc returns NULL (meaning that + * there is no more memory available) * */ void *scalloc(size_t size); /** - * Safe-wrapper around strdup which exits if malloc returns NULL (meaning that there - * is no more memory available) + * Safe-wrapper around strdup which exits if malloc returns NULL (meaning that + * there is no more memory available) * */ char *sstrdup(const char *str); @@ -84,40 +84,43 @@ char *sstrdup(const char *str); bool table_put(struct keyvalue_table_head *head, uint32_t key, void *value); /** - * Removes the element from the given keyvalue-table with the given key and returns its value; + * Removes the element from the given keyvalue-table with the given key and + * returns its value; * */ void *table_remove(struct keyvalue_table_head *head, uint32_t key); /** - * Returns the value of the element of the given keyvalue-table with the given key. + * Returns the value of the element of the given keyvalue-table with the given + * key. * */ void *table_get(struct keyvalue_table_head *head, uint32_t key); /** - * Starts the given application by passing it through a shell. We use double fork - * to avoid zombie processes. As the started application’s parent exits (immediately), - * the application is reparented to init (process-id 1), which correctly handles - * childs, so we don’t have to do it :-). + * Starts the given application by passing it through a shell. We use double + * fork to avoid zombie processes. As the started application’s parent exits + * (immediately), the application is reparented to init (process-id 1), which + * correctly handles childs, so we don’t have to do it :-). * - * The shell is determined by looking for the SHELL environment variable. If it - * does not exist, /bin/sh is used. + * The shell is determined by looking for the SHELL environment variable. If + * it does not exist, /bin/sh is used. * */ void start_application(const char *command); /** - * Checks a generic cookie for errors and quits with the given message if there - * was an error. + * Checks a generic cookie for errors and quits with the given message if + * there was an error. * */ -void check_error(xcb_connection_t *conn, xcb_void_cookie_t cookie, char *err_message); +void check_error(xcb_connection_t *conn, xcb_void_cookie_t cookie, + char *err_message); /** * Converts the given string to UCS-2 big endian for use with - * xcb_image_text_16(). The amount of real glyphs is stored in real_strlen, - * a buffer containing the UCS-2 encoded string (16 bit per glyph) is + * xcb_image_text_16(). The amount of real glyphs is stored in real_strlen, a + * buffer containing the UCS-2 encoded string (16 bit per glyph) is * returned. It has to be freed when done. * */ @@ -128,15 +131,15 @@ char *convert_utf8_to_ucs2(char *input, int *real_strlen); * the given container, optionally excluding the given client. * */ -Client *get_last_focused_client(xcb_connection_t *conn, Container *container, Client *exclude); +Client *get_last_focused_client(xcb_connection_t *conn, Container *container, + Client *exclude); /** * Unmaps all clients (and stack windows) of the given workspace. * - * This needs to be called separately when temporarily rendering - * a workspace which is not the active workspace to force - * reconfiguration of all clients, like in src/xinerama.c when - * re-assigning a workspace to another screen. + * This needs to be called separately when temporarily rendering a workspace + * which is not the active workspace to force reconfiguration of all clients, + * like in src/xinerama.c when re-assigning a workspace to another screen. * */ void unmap_workspace(xcb_connection_t *conn, Workspace *u_ws); @@ -154,8 +157,8 @@ void unmap_workspace(xcb_connection_t *conn, Workspace *u_ws); /** * Sets the given client as focused by updating the data structures correctly, - * updating the X input focus and finally re-decorating both windows (to signalize - * the user the new focus situation) + * updating the X input focus and finally re-decorating both windows (to + * signalize the user the new focus situation) * */ void set_focus(xcb_connection_t *conn, Client *client, bool set_anyways); @@ -168,7 +171,8 @@ void set_focus(xcb_connection_t *conn, Client *client, bool set_anyways); void leave_stack_mode(xcb_connection_t *conn, Container *container); /** - * Switches the layout of the given container taking care of the necessary house-keeping + * Switches the layout of the given container taking care of the necessary + * house-keeping * */ void switch_layout_mode(xcb_connection_t *conn, Container *container, int mode); @@ -179,7 +183,7 @@ void switch_layout_mode(xcb_connection_t *conn, Container *container, int mode); * will be checked. * */ -Client *get_matching_client(xcb_connection_t *conn, const char *window_classtitle, - Client *specific); +Client *get_matching_client(xcb_connection_t *conn, + const char *window_classtitle, Client *specific); #endif diff --git a/include/xcb.h b/include/xcb.h index a8a75876..de74bab6 100644 --- a/include/xcb.h +++ b/include/xcb.h @@ -17,7 +17,8 @@ #define _NET_WM_STATE_ADD 1 #define _NET_WM_STATE_TOGGLE 2 -/* This is the equivalent of XC_left_ptr. I’m not sure why xcb doesn’t have a constant for that. */ +/** This is the equivalent of XC_left_ptr. I’m not sure why xcb doesn’t have a + * constant for that. */ #define XCB_CURSOR_LEFT_PTR 68 #define XCB_CURSOR_SB_H_DOUBLE_ARROW 108 #define XCB_CURSOR_SB_V_DOUBLE_ARROW 116 @@ -25,14 +26,15 @@ /* from X11/keysymdef.h */ #define XCB_NUM_LOCK 0xff7f -/* The event masks are defined here because we don’t only set them once but we need to set slight - variations of them (without XCB_EVENT_MASK_ENTER_WINDOW while rendering the layout) */ -/* The XCB_CW_EVENT_MASK for the child (= real window) */ +/* The event masks are defined here because we don’t only set them once but we + need to set slight variations of them (without XCB_EVENT_MASK_ENTER_WINDOW + while rendering the layout) */ +/** The XCB_CW_EVENT_MASK for the child (= real window) */ #define CHILD_EVENT_MASK (XCB_EVENT_MASK_PROPERTY_CHANGE | \ XCB_EVENT_MASK_STRUCTURE_NOTIFY | \ XCB_EVENT_MASK_ENTER_WINDOW) -/* The XCB_CW_EVENT_MASK for its frame */ +/** The XCB_CW_EVENT_MASK for its frame */ #define FRAME_EVENT_MASK (XCB_EVENT_MASK_BUTTON_PRESS | /* …mouse is pressed/released */ \ XCB_EVENT_MASK_BUTTON_RELEASE | \ XCB_EVENT_MASK_EXPOSURE | /* …our window needs to be redrawn */ \ @@ -64,8 +66,8 @@ enum { _NET_SUPPORTED = 0, extern unsigned int xcb_numlock_mask; /** - * Loads a font for usage, getting its height. This function is used very often, so it - * maintains a cache. + * Loads a font for usage, getting its height. This function is used very + * often, so it maintains a cache. * */ i3Font *load_font(xcb_connection_t *conn, const char *pattern); @@ -75,39 +77,43 @@ i3Font *load_font(xcb_connection_t *conn, const char *pattern); * * The hex_color has to start with #, for example #FF00FF. * - * NOTE that get_colorpixel() does _NOT_ check the given color code for validity. - * This has to be done by the caller. + * NOTE that get_colorpixel() does _NOT_ check the given color code for + * validity. This has to be done by the caller. * */ uint32_t get_colorpixel(xcb_connection_t *conn, char *hex); /** - * Convenience wrapper around xcb_create_window which takes care of depth, generating an ID and checking - * for errors. + * Convenience wrapper around xcb_create_window which takes care of depth, + * generating an ID and checking for errors. * */ -xcb_window_t create_window(xcb_connection_t *conn, Rect r, uint16_t window_class, int cursor, - uint32_t mask, uint32_t *values); +xcb_window_t create_window(xcb_connection_t *conn, Rect r, uint16_t window_class, + int cursor, uint32_t mask, uint32_t *values); /** - * Changes a single value in the graphic context (so one doesn’t have to define an array of values) + * Changes a single value in the graphic context (so one doesn’t have to + * define an array of values) * */ -void xcb_change_gc_single(xcb_connection_t *conn, xcb_gcontext_t gc, uint32_t mask, uint32_t value); +void xcb_change_gc_single(xcb_connection_t *conn, xcb_gcontext_t gc, + uint32_t mask, uint32_t value); /** * Draws a line from x,y to to_x,to_y using the given color * */ -void xcb_draw_line(xcb_connection_t *conn, xcb_drawable_t drawable, xcb_gcontext_t gc, - uint32_t colorpixel, uint32_t x, uint32_t y, uint32_t to_x, uint32_t to_y); +void xcb_draw_line(xcb_connection_t *conn, xcb_drawable_t drawable, + xcb_gcontext_t gc, uint32_t colorpixel, uint32_t x, + uint32_t y, uint32_t to_x, uint32_t to_y); /** * Draws a rectangle from x,y with width,height using the given color * */ -void xcb_draw_rect(xcb_connection_t *conn, xcb_drawable_t drawable, xcb_gcontext_t gc, - uint32_t colorpixel, uint32_t x, uint32_t y, uint32_t width, uint32_t height); +void xcb_draw_rect(xcb_connection_t *conn, xcb_drawable_t drawable, + xcb_gcontext_t gc, uint32_t colorpixel, uint32_t x, + uint32_t y, uint32_t width, uint32_t height); /** * Generates a configure_notify event and sends it to the given window @@ -118,14 +124,15 @@ void xcb_draw_rect(xcb_connection_t *conn, xcb_drawable_t drawable, xcb_gcontext void fake_configure_notify(xcb_connection_t *conn, Rect r, xcb_window_t window); /** - * Generates a configure_notify_event with absolute coordinates (relative to the X root - * window, not to the client’s frame) for the given client. + * Generates a configure_notify_event with absolute coordinates (relative to + * the X root window, not to the client’s frame) for the given client. * */ void fake_absolute_configure_notify(xcb_connection_t *conn, Client *client); /** - * Finds out which modifier mask is the one for numlock, as the user may change this. + * Finds out which modifier mask is the one for numlock, as the user may + * change this. * */ void xcb_get_numlock_mask(xcb_connection_t *conn); diff --git a/include/xinerama.h b/include/xinerama.h index a1ae70bf..5b01789f 100644 --- a/include/xinerama.h +++ b/include/xinerama.h @@ -17,15 +17,15 @@ TAILQ_HEAD(screens_head, Screen); extern struct screens_head *virtual_screens; /** - * We have just established a connection to the X server and need the initial Xinerama - * information to setup workspaces for each screen. + * We have just established a connection to the X server and need the initial + * Xinerama information to setup workspaces for each screen. * */ void initialize_xinerama(xcb_connection_t *conn); /** - * This is called when the rootwindow receives a configure_notify event and therefore the - * number/position of the Xinerama screens could have changed. + * This is called when the rootwindow receives a configure_notify event and + * therefore the number/position of the Xinerama screens could have changed. * */ void xinerama_requery_screens(xcb_connection_t *conn); @@ -43,9 +43,9 @@ i3Screen *get_screen_at(int x, int y, struct screens_head *screenlist); i3Screen *get_screen_containing(int x, int y); /** - * Gets the screen which is the last one in the given direction, for example the screen - * on the most bottom when direction == D_DOWN, the screen most right when direction == D_RIGHT - * and so on. + * Gets the screen which is the last one in the given direction, for example + * the screen on the most bottom when direction == D_DOWN, the screen most + * right when direction == D_RIGHT and so on. * * This function always returns a screen. *