From 700f5bd443e18433470d6077817d193ada8067de Mon Sep 17 00:00:00 2001 From: Michael Stapelberg Date: Wed, 27 Jul 2011 17:05:28 +0200 Subject: [PATCH] docs/hacking-howto: a few little updates --- docs/hacking-howto | 36 ++++++++++++++++++++---------------- 1 file changed, 20 insertions(+), 16 deletions(-) diff --git a/docs/hacking-howto b/docs/hacking-howto index a91f5b01..a2a6e8c2 100644 --- a/docs/hacking-howto +++ b/docs/hacking-howto @@ -244,11 +244,14 @@ image:bigpicture.png[The Big Picture] So, the hierarchy is: +. *X11 root window*, the root container . *Virtual screens* (Screen 0 in this example) -. *Workspaces* (Workspace 1 in this example) -. *Table* (There can only be one table per Workspace) -. *Container* (left and right in this example) -. *Client* (The two clients in the left container) +. *Content container* (there are also containers for dock windows) +. *Workspaces* (Workspace 1 in this example, with horizontal orientation) +. *Split container* (vertically split) +. *X11 window containers* + +The data type is +Con+, in all cases. === Virtual screens @@ -269,7 +272,7 @@ screen you are currently on. === Workspace -A workspace is identified by its number. Basically, you could think of +A workspace is identified by its name. Basically, you could think of workspaces as different desks in your office, if you like the desktop methaphor. They just contain different sets of windows and are completely separate of each other. Other window managers also call this ``Virtual @@ -300,11 +303,11 @@ ensure that the operating system on which i3 is compiled has all the expected features, i3 comes with `include/queue.h`. On BSD systems, you can use man `queue(3)`. On Linux, you have to use google (or read the source). -The lists used are `SLIST` (single linked lists), `CIRCLEQ` (circular -queues) and TAILQ (tail queues). Usually, only forward traversal is necessary, +The lists used are +SLIST+ (single linked lists), +CIRCLEQ+ (circular +queues) and +TAILQ+ (tail queues). Usually, only forward traversal is necessary, so an `SLIST` works fine. If inserting elements at arbitrary positions or at -the end of a list is necessary, a `TAILQ` is used instead. However, for the -windows inside a container, a `CIRCLEQ` is necessary to go from the currently +the end of a list is necessary, a +TAILQ+ is used instead. However, for the +windows inside a container, a +CIRCLEQ+ is necessary to go from the currently selected window to the window above/below. == Naming conventions @@ -314,14 +317,14 @@ should be chosen for those: * ``conn'' is the xcb_connection_t * ``event'' is the event of the particular type - * ``container'' names a container - * ``client'' names a client, for example when using a +CIRCLEQ_FOREACH+ + * ``con'' names a container + * ``current'' is a loop variable when using +TAILQ_FOREACH+ etc. == Startup (src/mainx.c, main()) * Establish the xcb connection - * Check for XKB extension on the separate X connection - * Check for RandR screens + * Check for XKB extension on the separate X connection, load Xcursor + * Check for RandR screens (with a fall-back to Xinerama) * Grab the keycodes for which bindings exist * Manage all existing windows * Enter the event loop @@ -359,9 +362,10 @@ the correct state. Then, it looks through all bindings and gets the one which matches the received event. -The bound command is parsed directly in command mode. +The bound command is parsed by the cmdparse lexer/parser, see +parse_cmd+ in ++src/cmdparse.y+. -== Manage windows (src/mainx.c, manage_window() and reparent_window()) +== Manage windows (src/main.c, manage_window() and reparent_window()) `manage_window()` does some checks to decide whether the window should be managed at all: @@ -381,7 +385,7 @@ After reparenting, the window type (`_NET_WM_WINDOW_TYPE`) is checked to see whether this window is a dock (`_NET_WM_WINDOW_TYPE_DOCK`), like dzen2 for example. Docks are handled differently, they don’t have decorations and are not assigned to a specific container. Instead, they are positioned at the bottom -of the screen. To get the height which needsd to be reserved for the window, +of the screen. To get the height which needs to be reserved for the window, the `_NET_WM_STRUT_PARTIAL` property is used. Furthermore, the list of assignments (to other workspaces, which may be on