updated doxygen docu, added FIXMEs, fixed headers to 80chars width.

This commit is contained in:
Lars Hartmann 2009-06-29 21:54:51 +02:00 committed by Michael Stapelberg
parent 8b72c8eb31
commit 58cbce0380
13 changed files with 383 additions and 276 deletions

View File

@ -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 doesnt 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 doesnt 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);

View File

@ -13,7 +13,8 @@
#include <xcb/xcb.h>
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);

View File

@ -12,6 +12,8 @@
*
*/
/* FIXME: this file lacks documentation */
#ifndef _CONFIG_H
#define _CONFIG_H

View File

@ -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.
*
* Lets 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 youre 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 youre 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. Ive always wanted
* to be a three-star programmer :) */
/** This is a two-dimensional dynamic array of
* Container-pointers. Ive 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 dont have a container, we have this workspace-backpointer */
/** Because dock clients dont 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 users 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 users 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 theyre
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 theyre 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 titlebars graphic context inside the frame */
xcb_window_t child; /* The clients window */
xcb_window_t frame; /**< Our window: The frame around the
* client */
xcb_gcontext_t titlegc; /**< The titlebars graphic context
* inside the frame */
xcb_window_t child; /**< The clients 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 youre 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 youre 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;

View File

@ -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

View File

@ -12,56 +12,65 @@
#define _HANDLERS_H
/**
* Due to bindings like Mode_switch + <a>, we need to bind some keys in XCB_GRAB_MODE_SYNC.
* Therefore, we just replay all key presses.
* Due to bindings like Mode_switch + <a>, 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 lets 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

View File

@ -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 its in a stacking container and
* re-rendering the stack window or just calling decorate_window if its not in a stacking
* container.
* Redecorates the given client correctly by checking if its in a stacking
* container and re-rendering the stack window or just calling decorate_window
* if its 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 didnt 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 didnt 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 dont need to render *everything*, you should call render_container on the container
* you want to refresh.
* If you dont need to render *everything*, you should call render_container
* on the container you want to refresh.
*
*/
void render_layout(xcb_connection_t *conn);

View File

@ -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.
*

View File

@ -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

View File

@ -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 tables head */
/**
* Inserts one column at the tables 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 tables contents in human-readable form for debugging */
/**
* Prints the tables contents in human-readable form for debugging
*
*/
void dump_table(xcb_connection_t *conn, Workspace *workspace);
#endif

View File

@ -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 applications parent exits (immediately),
* the application is reparented to init (process-id 1), which correctly handles
* childs, so we dont 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 applications parent exits
* (immediately), the application is reparented to init (process-id 1), which
* correctly handles childs, so we dont 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

View File

@ -17,7 +17,8 @@
#define _NET_WM_STATE_ADD 1
#define _NET_WM_STATE_TOGGLE 2
/* This is the equivalent of XC_left_ptr. Im not sure why xcb doesnt have a constant for that. */
/** This is the equivalent of XC_left_ptr. Im not sure why xcb doesnt 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 dont 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 dont 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 doesnt have to define an array of values)
* Changes a single value in the graphic context (so one doesnt 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 clients frame) for the given client.
* Generates a configure_notify_event with absolute coordinates (relative to
* the X root window, not to the clients 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);

View File

@ -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.
*