/usr/share/doc/i3-wm/userguide.html is in i3-wm 4.14.1-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 1318 1319 1320 1321 1322 1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 1335 1336 1337 1338 1339 1340 1341 1342 1343 1344 1345 1346 1347 1348 1349 1350 1351 1352 1353 1354 1355 1356 1357 1358 1359 1360 1361 1362 1363 1364 1365 1366 1367 1368 1369 1370 1371 1372 1373 1374 1375 1376 1377 1378 1379 1380 1381 1382 1383 1384 1385 1386 1387 1388 1389 1390 1391 1392 1393 1394 1395 1396 1397 1398 1399 1400 1401 1402 1403 1404 1405 1406 1407 1408 1409 1410 1411 1412 1413 1414 1415 1416 1417 1418 1419 1420 1421 1422 1423 1424 1425 1426 1427 1428 1429 1430 1431 1432 1433 1434 1435 1436 1437 1438 1439 1440 1441 1442 1443 1444 1445 1446 1447 1448 1449 1450 1451 1452 1453 1454 1455 1456 1457 1458 1459 1460 1461 1462 1463 1464 1465 1466 1467 1468 1469 1470 1471 1472 1473 1474 1475 1476 1477 1478 1479 1480 1481 1482 1483 1484 1485 1486 1487 1488 1489 1490 1491 1492 1493 1494 1495 1496 1497 1498 1499 1500 1501 1502 1503 1504 1505 1506 1507 1508 1509 1510 1511 1512 1513 1514 1515 1516 1517 1518 1519 1520 1521 1522 1523 1524 1525 1526 1527 1528 1529 1530 1531 1532 1533 1534 1535 1536 1537 1538 1539 1540 1541 1542 1543 1544 1545 1546 1547 1548 1549 1550 1551 1552 1553 1554 1555 1556 1557 1558 1559 1560 1561 1562 1563 1564 1565 1566 1567 1568 1569 1570 1571 1572 1573 1574 1575 1576 1577 1578 1579 1580 1581 1582 1583 1584 1585 1586 1587 1588 1589 1590 1591 1592 1593 1594 1595 1596 1597 1598 1599 1600 1601 1602 1603 1604 1605 1606 1607 1608 1609 1610 1611 1612 1613 1614 1615 1616 1617 1618 1619 1620 1621 1622 1623 1624 1625 1626 1627 1628 1629 1630 1631 1632 1633 1634 1635 1636 1637 1638 1639 1640 1641 1642 1643 1644 1645 1646 1647 1648 1649 1650 1651 1652 1653 1654 1655 1656 1657 1658 1659 1660 1661 1662 1663 1664 1665 1666 1667 1668 1669 1670 1671 1672 1673 1674 1675 1676 1677 1678 1679 1680 1681 1682 1683 1684 1685 1686 1687 1688 1689 1690 1691 1692 1693 1694 1695 1696 1697 1698 1699 1700 1701 1702 1703 1704 1705 1706 1707 1708 1709 1710 1711 1712 1713 1714 1715 1716 1717 1718 1719 1720 1721 1722 1723 1724 1725 1726 1727 1728 1729 1730 1731 1732 1733 1734 1735 1736 1737 1738 1739 1740 1741 1742 1743 1744 1745 1746 1747 1748 1749 1750 1751 1752 1753 1754 1755 1756 1757 1758 1759 1760 1761 1762 1763 1764 1765 1766 1767 1768 1769 1770 1771 1772 1773 1774 1775 1776 1777 1778 1779 1780 1781 1782 1783 1784 1785 1786 1787 1788 1789 1790 1791 1792 1793 1794 1795 1796 1797 1798 1799 1800 1801 1802 1803 1804 1805 1806 1807 1808 1809 1810 1811 1812 1813 1814 1815 1816 1817 1818 1819 1820 1821 1822 1823 1824 1825 1826 1827 1828 1829 1830 1831 1832 1833 1834 1835 1836 1837 1838 1839 1840 1841 1842 1843 1844 1845 1846 1847 1848 1849 1850 1851 1852 1853 1854 1855 1856 1857 1858 1859 1860 1861 1862 1863 1864 1865 1866 1867 1868 1869 1870 1871 1872 1873 1874 1875 1876 1877 1878 1879 1880 1881 1882 1883 1884 1885 1886 1887 1888 1889 1890 1891 1892 1893 1894 1895 1896 1897 1898 1899 1900 1901 1902 1903 1904 1905 1906 1907 1908 1909 1910 1911 1912 1913 1914 1915 1916 1917 1918 1919 1920 1921 1922 1923 1924 1925 1926 1927 1928 1929 1930 1931 1932 1933 1934 1935 1936 1937 1938 1939 1940 1941 1942 1943 1944 1945 1946 1947 1948 1949 1950 1951 1952 1953 1954 1955 1956 1957 1958 1959 1960 1961 1962 1963 1964 1965 1966 1967 1968 1969 1970 1971 1972 1973 1974 1975 1976 1977 1978 1979 1980 1981 1982 1983 1984 1985 1986 1987 1988 1989 1990 1991 1992 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003 2004 2005 2006 2007 2008 2009 2010 2011 2012 2013 2014 2015 2016 2017 2018 2019 2020 2021 2022 2023 2024 2025 2026 2027 2028 2029 2030 2031 2032 2033 2034 2035 2036 2037 2038 2039 2040 2041 2042 2043 2044 2045 2046 2047 2048 2049 2050 2051 2052 2053 2054 2055 2056 2057 2058 2059 2060 2061 2062 2063 2064 2065 2066 2067 2068 2069 2070 2071 2072 2073 2074 2075 2076 2077 2078 2079 2080 2081 2082 2083 2084 2085 2086 2087 2088 2089 2090 2091 2092 2093 2094 2095 2096 2097 2098 2099 2100 2101 2102 2103 2104 2105 2106 2107 2108 2109 2110 2111 2112 2113 2114 2115 2116 2117 2118 2119 2120 2121 2122 2123 2124 2125 2126 2127 2128 2129 2130 2131 2132 2133 2134 2135 2136 2137 2138 2139 2140 2141 2142 2143 2144 2145 2146 2147 2148 2149 2150 2151 2152 2153 2154 2155 2156 2157 2158 2159 2160 2161 2162 2163 2164 2165 2166 2167 2168 2169 2170 2171 2172 2173 2174 2175 2176 2177 2178 2179 2180 2181 2182 2183 2184 2185 2186 2187 2188 2189 2190 2191 2192 2193 2194 2195 2196 2197 2198 2199 2200 2201 2202 2203 2204 2205 2206 2207 2208 2209 2210 2211 2212 2213 2214 2215 2216 2217 2218 2219 2220 2221 2222 2223 2224 2225 2226 2227 2228 2229 2230 2231 2232 2233 2234 2235 2236 2237 2238 2239 2240 2241 2242 2243 2244 2245 2246 2247 2248 2249 2250 2251 2252 2253 2254 2255 2256 2257 2258 2259 2260 2261 2262 2263 2264 2265 2266 2267 2268 2269 2270 2271 2272 2273 2274 2275 2276 2277 2278 2279 2280 2281 2282 2283 2284 2285 2286 2287 2288 2289 2290 2291 2292 2293 2294 2295 2296 2297 2298 2299 2300 2301 2302 2303 2304 2305 2306 2307 2308 2309 2310 2311 2312 2313 2314 2315 2316 2317 2318 2319 2320 2321 2322 2323 2324 2325 2326 2327 2328 2329 2330 2331 2332 2333 2334 2335 2336 2337 2338 2339 2340 2341 2342 2343 2344 2345 2346 2347 2348 2349 2350 2351 2352 2353 2354 2355 2356 2357 2358 2359 2360 2361 2362 2363 2364 2365 2366 2367 2368 2369 2370 2371 2372 2373 2374 2375 2376 2377 2378 2379 2380 2381 2382 2383 2384 2385 2386 2387 2388 2389 2390 2391 2392 2393 2394 2395 2396 2397 2398 2399 2400 2401 2402 2403 2404 2405 2406 2407 2408 2409 2410 2411 2412 2413 2414 2415 2416 2417 2418 2419 2420 2421 2422 2423 2424 2425 2426 2427 2428 2429 2430 2431 2432 2433 2434 2435 2436 2437 2438 2439 2440 2441 2442 2443 2444 2445 2446 2447 2448 2449 2450 2451 2452 2453 2454 2455 2456 2457 2458 2459 2460 2461 2462 2463 2464 2465 2466 2467 2468 2469 2470 2471 2472 2473 2474 2475 2476 2477 2478 2479 2480 2481 2482 2483 2484 2485 2486 2487 2488 2489 2490 2491 2492 2493 2494 2495 2496 2497 2498 2499 2500 2501 2502 2503 2504 2505 2506 2507 2508 2509 2510 2511 2512 2513 2514 2515 2516 2517 2518 2519 2520 2521 2522 2523 2524 2525 2526 2527 2528 2529 2530 2531 2532 2533 2534 2535 2536 2537 2538 2539 2540 2541 2542 2543 2544 2545 2546 2547 2548 2549 2550 2551 2552 2553 2554 2555 2556 2557 2558 2559 2560 2561 2562 2563 2564 2565 2566 2567 2568 2569 2570 2571 2572 2573 2574 2575 2576 2577 2578 2579 2580 2581 2582 2583 2584 2585 2586 2587 2588 2589 2590 2591 2592 2593 2594 2595 2596 2597 2598 2599 2600 2601 2602 2603 2604 2605 2606 2607 2608 2609 2610 2611 2612 2613 2614 2615 2616 2617 2618 2619 2620 2621 2622 2623 2624 2625 2626 2627 2628 2629 2630 2631 2632 2633 2634 2635 2636 2637 2638 2639 2640 2641 2642 2643 2644 2645 2646 2647 2648 2649 2650 2651 2652 2653 2654 2655 2656 2657 2658 2659 2660 2661 2662 2663 2664 2665 2666 2667 2668 2669 2670 2671 2672 2673 2674 2675 2676 2677 2678 2679 2680 2681 2682 2683 2684 2685 2686 2687 2688 2689 2690 2691 2692 2693 2694 2695 2696 2697 2698 2699 2700 2701 2702 2703 2704 2705 2706 2707 2708 2709 2710 2711 2712 2713 2714 2715 2716 2717 2718 2719 2720 2721 2722 2723 2724 2725 2726 2727 2728 2729 2730 2731 2732 2733 2734 2735 2736 2737 2738 2739 2740 2741 2742 2743 2744 2745 2746 2747 2748 2749 2750 2751 2752 2753 2754 2755 2756 2757 2758 2759 2760 2761 2762 2763 2764 2765 2766 2767 2768 2769 2770 2771 2772 2773 2774 2775 2776 2777 2778 2779 2780 2781 2782 2783 2784 2785 2786 2787 2788 2789 2790 2791 2792 2793 2794 2795 2796 2797 2798 2799 2800 2801 2802 2803 2804 2805 2806 2807 2808 2809 2810 2811 2812 2813 2814 2815 2816 2817 2818 2819 2820 2821 2822 2823 2824 2825 2826 2827 2828 2829 2830 2831 2832 2833 2834 2835 2836 2837 2838 2839 2840 2841 2842 2843 2844 2845 2846 2847 2848 2849 2850 2851 2852 2853 2854 2855 2856 2857 2858 2859 2860 2861 2862 2863 2864 2865 2866 2867 2868 2869 2870 2871 2872 2873 2874 2875 2876 2877 2878 2879 2880 2881 2882 2883 2884 2885 2886 2887 2888 2889 2890 2891 2892 2893 2894 2895 2896 2897 2898 2899 2900 2901 2902 2903 2904 2905 2906 2907 2908 2909 2910 2911 2912 2913 2914 2915 2916 2917 2918 2919 2920 2921 2922 2923 2924 2925 2926 2927 2928 2929 2930 2931 2932 2933 2934 2935 2936 2937 2938 2939 2940 2941 2942 2943 2944 2945 2946 2947 2948 2949 2950 2951 2952 2953 2954 2955 2956 2957 2958 2959 2960 2961 2962 2963 2964 2965 2966 2967 2968 2969 2970 2971 2972 2973 2974 2975 2976 2977 2978 2979 2980 2981 2982 2983 2984 2985 2986 2987 2988 2989 2990 2991 2992 2993 2994 2995 2996 2997 2998 2999 3000 3001 3002 3003 3004 3005 3006 3007 3008 3009 3010 3011 3012 3013 3014 3015 3016 3017 3018 3019 3020 3021 3022 3023 3024 3025 3026 3027 3028 3029 3030 3031 3032 3033 3034 3035 3036 3037 3038 3039 3040 3041 3042 3043 3044 3045 3046 3047 3048 3049 3050 3051 3052 3053 3054 3055 3056 3057 3058 3059 3060 3061 3062 3063 3064 3065 3066 3067 3068 3069 3070 3071 3072 3073 3074 3075 3076 3077 3078 3079 3080 3081 3082 3083 3084 3085 3086 3087 3088 3089 3090 3091 3092 3093 3094 3095 3096 3097 3098 3099 3100 3101 3102 3103 3104 3105 3106 3107 3108 3109 3110 3111 3112 3113 3114 3115 3116 3117 3118 3119 3120 3121 3122 3123 3124 3125 3126 3127 3128 3129 3130 3131 3132 3133 3134 3135 3136 3137 3138 3139 3140 3141 3142 3143 3144 3145 3146 3147 3148 3149 3150 3151 3152 3153 3154 3155 3156 3157 3158 3159 3160 3161 3162 3163 3164 3165 3166 3167 3168 3169 3170 3171 3172 3173 3174 3175 3176 3177 3178 3179 3180 3181 3182 3183 3184 3185 3186 3187 3188 3189 3190 3191 3192 3193 3194 3195 3196 3197 3198 3199 3200 3201 3202 3203 3204 3205 3206 3207 3208 3209 3210 3211 3212 3213 3214 3215 3216 3217 3218 3219 3220 3221 3222 3223 3224 3225 3226 3227 3228 3229 3230 3231 3232 3233 3234 3235 3236 3237 3238 3239 3240 3241 3242 3243 3244 3245 3246 3247 3248 3249 3250 3251 3252 3253 3254 3255 3256 3257 3258 3259 3260 3261 3262 3263 3264 3265 3266 3267 3268 3269 3270 3271 3272 3273 3274 3275 3276 3277 3278 3279 3280 3281 3282 3283 3284 3285 3286 3287 3288 3289 3290 3291 3292 3293 3294 3295 3296 3297 3298 3299 3300 3301 3302 3303 3304 3305 3306 3307 3308 3309 3310 3311 3312 3313 3314 3315 3316 3317 3318 3319 3320 3321 3322 3323 3324 3325 3326 3327 3328 3329 3330 3331 3332 3333 3334 3335 3336 3337 3338 3339 3340 3341 3342 3343 3344 3345 3346 3347 3348 3349 3350 3351 3352 3353 3354 3355 3356 3357 3358 3359 3360 3361 3362 3363 3364 3365 3366 3367 3368 3369 3370 3371 3372 3373 3374 3375 3376 3377 3378 3379 3380 3381 3382 3383 3384 3385 3386 3387 3388 3389 3390 3391 3392 3393 3394 3395 3396 3397 3398 3399 3400 3401 3402 3403 3404 3405 3406 3407 3408 3409 3410 3411 3412 3413 3414 3415 3416 3417 3418 3419 3420 3421 3422 3423 3424 3425 3426 3427 3428 3429 3430 3431 3432 3433 3434 3435 3436 3437 3438 3439 3440 3441 3442 3443 3444 3445 3446 3447 3448 3449 3450 3451 3452 3453 3454 3455 3456 3457 3458 3459 3460 3461 3462 3463 3464 3465 3466 3467 3468 3469 3470 3471 3472 3473 3474 3475 3476 3477 3478 3479 3480 3481 3482 3483 3484 3485 3486 3487 3488 3489 3490 3491 3492 3493 3494 3495 3496 3497 3498 3499 3500 3501 3502 3503 3504 3505 3506 3507 3508 3509 3510 3511 3512 3513 3514 3515 3516 3517 3518 3519 3520 3521 3522 3523 3524 3525 3526 3527 3528 3529 3530 3531 3532 3533 3534 3535 3536 3537 3538 3539 3540 3541 3542 3543 3544 3545 3546 3547 3548 3549 3550 3551 3552 3553 3554 3555 3556 3557 3558 3559 3560 3561 3562 3563 3564 3565 3566 3567 3568 3569 3570 3571 3572 3573 3574 3575 3576 3577 3578 3579 3580 3581 3582 3583 3584 3585 3586 3587 3588 3589 3590 3591 3592 3593 3594 3595 3596 3597 3598 3599 3600 3601 3602 3603 3604 3605 3606 3607 3608 3609 3610 3611 3612 3613 3614 3615 3616 3617 3618 3619 3620 3621 3622 3623 3624 3625 3626 3627 3628 3629 3630 3631 3632 3633 3634 3635 3636 3637 3638 3639 3640 3641 3642 3643 3644 3645 3646 3647 3648 3649 3650 3651 3652 3653 3654 3655 3656 3657 3658 3659 3660 3661 3662 3663 3664 3665 3666 3667 3668 3669 3670 3671 3672 3673 3674 3675 3676 3677 3678 3679 3680 3681 3682 3683 3684 3685 3686 3687 3688 3689 3690 3691 3692 3693 3694 3695 3696 3697 3698 3699 3700 3701 3702 3703 3704 3705 3706 3707 3708 3709 3710 3711 3712 3713 3714 3715 3716 3717 3718 3719 3720 3721 3722 3723 3724 3725 3726 3727 3728 3729 3730 3731 3732 3733 3734 3735 3736 3737 3738 3739 3740 3741 3742 3743 3744 3745 3746 3747 3748 3749 3750 3751 3752 3753 3754 3755 3756 3757 3758 3759 3760 3761 3762 3763 3764 3765 3766 3767 3768 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
<meta http-equiv="Content-Type" content="application/xhtml+xml; charset=UTF-8" />
<meta name="generator" content="AsciiDoc 8.6.9" />
<title>i3 User’s Guide</title>
<style type="text/css">
/* Shared CSS for AsciiDoc xhtml11 and html5 backends */
/* Default font. */
body {
font-family: Georgia,serif;
}
/* Title font. */
h1, h2, h3, h4, h5, h6,
div.title, caption.title,
thead, p.table.header,
#toctitle,
#author, #revnumber, #revdate, #revremark,
#footer {
font-family: Arial,Helvetica,sans-serif;
}
body {
margin: 1em 5% 1em 5%;
}
a {
color: blue;
text-decoration: underline;
}
a:visited {
color: fuchsia;
}
em {
font-style: italic;
color: navy;
}
strong {
font-weight: bold;
color: #083194;
}
h1, h2, h3, h4, h5, h6 {
color: #527bbd;
margin-top: 1.2em;
margin-bottom: 0.5em;
line-height: 1.3;
}
h1, h2, h3 {
border-bottom: 2px solid silver;
}
h2 {
padding-top: 0.5em;
}
h3 {
float: left;
}
h3 + * {
clear: left;
}
h5 {
font-size: 1.0em;
}
div.sectionbody {
margin-left: 0;
}
hr {
border: 1px solid silver;
}
p {
margin-top: 0.5em;
margin-bottom: 0.5em;
}
ul, ol, li > p {
margin-top: 0;
}
ul > li { color: #aaa; }
ul > li > * { color: black; }
.monospaced, code, pre {
font-family: "Courier New", Courier, monospace;
font-size: inherit;
color: navy;
padding: 0;
margin: 0;
}
pre {
white-space: pre-wrap;
}
#author {
color: #527bbd;
font-weight: bold;
font-size: 1.1em;
}
#email {
}
#revnumber, #revdate, #revremark {
}
#footer {
font-size: small;
border-top: 2px solid silver;
padding-top: 0.5em;
margin-top: 4.0em;
}
#footer-text {
float: left;
padding-bottom: 0.5em;
}
#footer-badges {
float: right;
padding-bottom: 0.5em;
}
#preamble {
margin-top: 1.5em;
margin-bottom: 1.5em;
}
div.imageblock, div.exampleblock, div.verseblock,
div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
div.admonitionblock {
margin-top: 1.0em;
margin-bottom: 1.5em;
}
div.admonitionblock {
margin-top: 2.0em;
margin-bottom: 2.0em;
margin-right: 10%;
color: #606060;
}
div.content { /* Block element content. */
padding: 0;
}
/* Block element titles. */
div.title, caption.title {
color: #527bbd;
font-weight: bold;
text-align: left;
margin-top: 1.0em;
margin-bottom: 0.5em;
}
div.title + * {
margin-top: 0;
}
td div.title:first-child {
margin-top: 0.0em;
}
div.content div.title:first-child {
margin-top: 0.0em;
}
div.content + div.title {
margin-top: 0.0em;
}
div.sidebarblock > div.content {
background: #ffffee;
border: 1px solid #dddddd;
border-left: 4px solid #f0f0f0;
padding: 0.5em;
}
div.listingblock > div.content {
border: 1px solid #dddddd;
border-left: 5px solid #f0f0f0;
background: #f8f8f8;
padding: 0.5em;
}
div.quoteblock, div.verseblock {
padding-left: 1.0em;
margin-left: 1.0em;
margin-right: 10%;
border-left: 5px solid #f0f0f0;
color: #888;
}
div.quoteblock > div.attribution {
padding-top: 0.5em;
text-align: right;
}
div.verseblock > pre.content {
font-family: inherit;
font-size: inherit;
}
div.verseblock > div.attribution {
padding-top: 0.75em;
text-align: left;
}
/* DEPRECATED: Pre version 8.2.7 verse style literal block. */
div.verseblock + div.attribution {
text-align: left;
}
div.admonitionblock .icon {
vertical-align: top;
font-size: 1.1em;
font-weight: bold;
text-decoration: underline;
color: #527bbd;
padding-right: 0.5em;
}
div.admonitionblock td.content {
padding-left: 0.5em;
border-left: 3px solid #dddddd;
}
div.exampleblock > div.content {
border-left: 3px solid #dddddd;
padding-left: 0.5em;
}
div.imageblock div.content { padding-left: 0; }
span.image img { border-style: none; vertical-align: text-bottom; }
a.image:visited { color: white; }
dl {
margin-top: 0.8em;
margin-bottom: 0.8em;
}
dt {
margin-top: 0.5em;
margin-bottom: 0;
font-style: normal;
color: navy;
}
dd > *:first-child {
margin-top: 0.1em;
}
ul, ol {
list-style-position: outside;
}
ol.arabic {
list-style-type: decimal;
}
ol.loweralpha {
list-style-type: lower-alpha;
}
ol.upperalpha {
list-style-type: upper-alpha;
}
ol.lowerroman {
list-style-type: lower-roman;
}
ol.upperroman {
list-style-type: upper-roman;
}
div.compact ul, div.compact ol,
div.compact p, div.compact p,
div.compact div, div.compact div {
margin-top: 0.1em;
margin-bottom: 0.1em;
}
tfoot {
font-weight: bold;
}
td > div.verse {
white-space: pre;
}
div.hdlist {
margin-top: 0.8em;
margin-bottom: 0.8em;
}
div.hdlist tr {
padding-bottom: 15px;
}
dt.hdlist1.strong, td.hdlist1.strong {
font-weight: bold;
}
td.hdlist1 {
vertical-align: top;
font-style: normal;
padding-right: 0.8em;
color: navy;
}
td.hdlist2 {
vertical-align: top;
}
div.hdlist.compact tr {
margin: 0;
padding-bottom: 0;
}
.comment {
background: yellow;
}
.footnote, .footnoteref {
font-size: 0.8em;
}
span.footnote, span.footnoteref {
vertical-align: super;
}
#footnotes {
margin: 20px 0 20px 0;
padding: 7px 0 0 0;
}
#footnotes div.footnote {
margin: 0 0 5px 0;
}
#footnotes hr {
border: none;
border-top: 1px solid silver;
height: 1px;
text-align: left;
margin-left: 0;
width: 20%;
min-width: 100px;
}
div.colist td {
padding-right: 0.5em;
padding-bottom: 0.3em;
vertical-align: top;
}
div.colist td img {
margin-top: 0.3em;
}
@media print {
#footer-badges { display: none; }
}
#toc {
margin-bottom: 2.5em;
}
#toctitle {
color: #527bbd;
font-size: 1.1em;
font-weight: bold;
margin-top: 1.0em;
margin-bottom: 0.1em;
}
div.toclevel0, div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
margin-top: 0;
margin-bottom: 0;
}
div.toclevel2 {
margin-left: 2em;
font-size: 0.9em;
}
div.toclevel3 {
margin-left: 4em;
font-size: 0.9em;
}
div.toclevel4 {
margin-left: 6em;
font-size: 0.9em;
}
span.aqua { color: aqua; }
span.black { color: black; }
span.blue { color: blue; }
span.fuchsia { color: fuchsia; }
span.gray { color: gray; }
span.green { color: green; }
span.lime { color: lime; }
span.maroon { color: maroon; }
span.navy { color: navy; }
span.olive { color: olive; }
span.purple { color: purple; }
span.red { color: red; }
span.silver { color: silver; }
span.teal { color: teal; }
span.white { color: white; }
span.yellow { color: yellow; }
span.aqua-background { background: aqua; }
span.black-background { background: black; }
span.blue-background { background: blue; }
span.fuchsia-background { background: fuchsia; }
span.gray-background { background: gray; }
span.green-background { background: green; }
span.lime-background { background: lime; }
span.maroon-background { background: maroon; }
span.navy-background { background: navy; }
span.olive-background { background: olive; }
span.purple-background { background: purple; }
span.red-background { background: red; }
span.silver-background { background: silver; }
span.teal-background { background: teal; }
span.white-background { background: white; }
span.yellow-background { background: yellow; }
span.big { font-size: 2em; }
span.small { font-size: 0.6em; }
span.underline { text-decoration: underline; }
span.overline { text-decoration: overline; }
span.line-through { text-decoration: line-through; }
div.unbreakable { page-break-inside: avoid; }
/*
* xhtml11 specific
*
* */
div.tableblock {
margin-top: 1.0em;
margin-bottom: 1.5em;
}
div.tableblock > table {
border: 3px solid #527bbd;
}
thead, p.table.header {
font-weight: bold;
color: #527bbd;
}
p.table {
margin-top: 0;
}
/* Because the table frame attribute is overriden by CSS in most browsers. */
div.tableblock > table[frame="void"] {
border-style: none;
}
div.tableblock > table[frame="hsides"] {
border-left-style: none;
border-right-style: none;
}
div.tableblock > table[frame="vsides"] {
border-top-style: none;
border-bottom-style: none;
}
/*
* html5 specific
*
* */
table.tableblock {
margin-top: 1.0em;
margin-bottom: 1.5em;
}
thead, p.tableblock.header {
font-weight: bold;
color: #527bbd;
}
p.tableblock {
margin-top: 0;
}
table.tableblock {
border-width: 3px;
border-spacing: 0px;
border-style: solid;
border-color: #527bbd;
border-collapse: collapse;
}
th.tableblock, td.tableblock {
border-width: 1px;
padding: 4px;
border-style: solid;
border-color: #527bbd;
}
table.tableblock.frame-topbot {
border-left-style: hidden;
border-right-style: hidden;
}
table.tableblock.frame-sides {
border-top-style: hidden;
border-bottom-style: hidden;
}
table.tableblock.frame-none {
border-style: hidden;
}
th.tableblock.halign-left, td.tableblock.halign-left {
text-align: left;
}
th.tableblock.halign-center, td.tableblock.halign-center {
text-align: center;
}
th.tableblock.halign-right, td.tableblock.halign-right {
text-align: right;
}
th.tableblock.valign-top, td.tableblock.valign-top {
vertical-align: top;
}
th.tableblock.valign-middle, td.tableblock.valign-middle {
vertical-align: middle;
}
th.tableblock.valign-bottom, td.tableblock.valign-bottom {
vertical-align: bottom;
}
/*
* manpage specific
*
* */
body.manpage h1 {
padding-top: 0.5em;
padding-bottom: 0.5em;
border-top: 2px solid silver;
border-bottom: 2px solid silver;
}
body.manpage h2 {
border-style: none;
}
body.manpage div.sectionbody {
margin-left: 3em;
}
@media print {
body.manpage div#toc { display: none; }
}
</style>
<script type="text/javascript">
/*<+'])');
// Function that scans the DOM tree for header elements (the DOM2
// nodeIterator API would be a better technique but not supported by all
// browsers).
var iterate = function (el) {
for (var i = el.firstChild; i != null; i = i.nextSibling) {
if (i.nodeType == 1 /* Node.ELEMENT_NODE */) {
var mo = re.exec(i.tagName);
if (mo && (i.getAttribute("class") || i.getAttribute("className")) != "float") {
result[result.length] = new TocEntry(i, getText(i), mo[1]-1);
}
iterate(i);
}
}
}
iterate(el);
return result;
}
var toc = document.getElementById("toc");
if (!toc) {
return;
}
// Delete existing TOC entries in case we're reloading the TOC.
var tocEntriesToRemove = [];
var i;
for (i = 0; i < toc.childNodes.length; i++) {
var entry = toc.childNodes[i];
if (entry.nodeName.toLowerCase() == 'div'
&& entry.getAttribute("class")
&& entry.getAttribute("class").match(/^toclevel/))
tocEntriesToRemove.push(entry);
}
for (i = 0; i < tocEntriesToRemove.length; i++) {
toc.removeChild(tocEntriesToRemove[i]);
}
// Rebuild TOC entries.
var entries = tocEntries(document.getElementById("content"), toclevels);
for (var i = 0; i < entries.length; ++i) {
var entry = entries[i];
if (entry.element.id == "")
entry.element.id = "_toc_" + i;
var a = document.createElement("a");
a.href = "#" + entry.element.id;
a.appendChild(document.createTextNode(entry.text));
var div = document.createElement("div");
div.appendChild(a);
div.className = "toclevel" + entry.toclevel;
toc.appendChild(div);
}
if (entries.length == 0)
toc.parentNode.removeChild(toc);
},
/////////////////////////////////////////////////////////////////////
// Footnotes generator
/////////////////////////////////////////////////////////////////////
/* Based on footnote generation code from:
* http://www.brandspankingnew.net/archive/2005/07/format_footnote.html
*/
footnotes: function () {
// Delete existing footnote entries in case we're reloading the footnodes.
var i;
var noteholder = document.getElementById("footnotes");
if (!noteholder) {
return;
}
var entriesToRemove = [];
for (i = 0; i < noteholder.childNodes.length; i++) {
var entry = noteholder.childNodes[i];
if (entry.nodeName.toLowerCase() == 'div' && entry.getAttribute("class") == "footnote")
entriesToRemove.push(entry);
}
for (i = 0; i < entriesToRemove.length; i++) {
noteholder.removeChild(entriesToRemove[i]);
}
// Rebuild footnote entries.
var cont = document.getElementById("content");
var spans = cont.getElementsByTagName("span");
var refs = {};
var n = 0;
for (i=0; i<spans.length; i++) {
if (spans[i].className == "footnote") {
n++;
var note = spans[i].getAttribute("data-note");
if (!note) {
// Use [\s\S] in place of . so multi-line matches work.
// Because JavaScript has no s (dotall) regex flag.
note = spans[i].innerHTML.match(/\s*\[([\s\S]*)]\s*/)[1];
spans[i].innerHTML =
"[<a id='_footnoteref_" + n + "' href='#_footnote_" + n +
"' title='View footnote' class='footnote'>" + n + "</a>]";
spans[i].setAttribute("data-note", note);
}
noteholder.innerHTML +=
"<div class='footnote' id='_footnote_" + n + "'>" +
"<a href='#_footnoteref_" + n + "' title='Return to text'>" +
n + "</a>. " + note + "</div>";
var id =spans[i].getAttribute("id");
if (id != null) refs["#"+id] = n;
}
}
if (n == 0)
noteholder.parentNode.removeChild(noteholder);
else {
// Process footnoterefs.
for (i=0; i<spans.length; i++) {
if (spans[i].className == "footnoteref") {
var href = spans[i].getElementsByTagName("a")[0].getAttribute("href");
href = href.match(/#.*/)[0]; // Because IE return full URL.
n = refs[href];
spans[i].innerHTML =
"[<a href='#_footnote_" + n +
"' title='View footnote' class='footnote'>" + n + "</a>]";
}
}
}
},
install: function(toclevels) {
var timerId;
function reinstall() {
asciidoc.footnotes();
if (toclevels) {
asciidoc.toc(toclevels);
}
}
function reinstallAndRemoveTimer() {
clearInterval(timerId);
reinstall();
}
timerId = setInterval(reinstall, 500);
if (document.addEventListener)
document.addEventListener("DOMContentLoaded", reinstallAndRemoveTimer, false);
else
window.onload = reinstallAndRemoveTimer;
}
}
asciidoc.install(2);
/*]]>*/
</script>
</head>
<body class="article">
<div id="header">
<h1>i3 User’s Guide</h1>
<span id="author">Michael Stapelberg</span><br />
<span id="email"><code><<a href="mailto:michael@i3wm.org">michael@i3wm.org</a>></code></span><br />
<span id="revdate">March 2013</span>
<div id="toc">
<div id="toctitle">Table of Contents</div>
<noscript><p><b>JavaScript must be enabled in your browser to display the table of contents.</b></p></noscript>
</div>
</div>
<div id="content">
<div id="preamble">
<div class="sectionbody">
<div class="paragraph"><p>This document contains all the information you need to configure and use the i3
window manager. If it does not, please check <a href="https://www.reddit.com/r/i3wm/">https://www.reddit.com/r/i3wm/</a>
first, then contact us on IRC (preferred) or post your question(s) on the
mailing list.</p></div>
</div>
</div>
<div class="sect1">
<h2 id="_default_keybindings">1. Default keybindings</h2>
<div class="sectionbody">
<div class="paragraph"><p>For the "too long; didn’t read" people, here is an overview of the default
keybindings (click to see the full size image):</p></div>
<div class="paragraph"><p><strong>Keys to use with $mod (Alt):</strong></p></div>
<div class="paragraph"><p><span class="image">
<a class="image" href="keyboard-layer1.png">
<img src="keyboard-layer1.png" alt="Keys to use with $mod (Alt)" width="600" />
</a>
</span></p></div>
<div class="paragraph"><p><strong>Keys to use with Shift+$mod:</strong></p></div>
<div class="paragraph"><p><span class="image">
<a class="image" href="keyboard-layer2.png">
<img src="keyboard-layer2.png" alt="Keys to use with Shift+$mod" width="600" />
</a>
</span></p></div>
<div class="paragraph"><p>The red keys are the modifiers you need to press (by default), the blue keys
are your homerow.</p></div>
<div class="paragraph"><p>Note that when starting i3 without a config file, i3-config-wizard will offer
you to create a config file in which the key positions (!) match what you see
in the image above, regardless of the keyboard layout you are using. If you
prefer to use a config file where the key letters match what you are seeing
above, just decline i3-config-wizard’s offer and base your config on
<code>/etc/i3/config</code>.</p></div>
</div>
</div>
<div class="sect1">
<h2 id="_using_i3">2. Using i3</h2>
<div class="sectionbody">
<div class="paragraph"><p>Throughout this guide, the keyword <code>$mod</code> will be used to refer to the
configured modifier. This is the Alt key (<code>Mod1</code>) by default, with the Windows
key (<code>Mod4</code>) being a popular alternative.</p></div>
<div class="sect2">
<h3 id="_opening_terminals_and_moving_around">2.1. Opening terminals and moving around</h3>
<div class="paragraph"><p>One very basic operation is opening a new terminal. By default, the keybinding
for this is <code>$mod+Enter</code>, that is Alt+Enter (<code>Mod1+Enter</code>) in the default
configuration. By pressing <code>$mod+Enter</code>, a new terminal will be opened. It
will fill the whole space available on your screen.</p></div>
<div class="paragraph"><p><span class="image">
<img src="single_terminal.png" alt="Single terminal" />
</span></p></div>
<div class="paragraph"><p>If you now open another terminal, i3 will place it next to the current one,
splitting the screen size in half. Depending on your monitor, i3 will put the
created window beside the existing window (on wide displays) or below the
existing window (rotated displays).</p></div>
<div class="paragraph"><p><span class="image">
<img src="two_terminals.png" alt="Two terminals" />
</span></p></div>
<div class="paragraph"><p>To move the focus between the two terminals, you can use the direction keys
which you may know from the editor <code>vi</code>. However, in i3, your homerow is used
for these keys (in <code>vi</code>, the keys are shifted to the left by one for
compatibility with most keyboard layouts). Therefore, <code>$mod+j</code> is left, <code>$mod+k</code>
is down, <code>$mod+l</code> is up and <code>$mod+;</code> is right. So, to switch between the
terminals, use <code>$mod+k</code> or <code>$mod+l</code>. Of course, you can also use the arrow keys.</p></div>
<div class="paragraph"><p>At the moment, your workspace is split (it contains two terminals) in a
specific direction (horizontal by default). Every window can be split
horizontally or vertically again, just like the workspace. The terminology is
"window" for a container that actually contains an X11 window (like a terminal
or browser) and "split container" for containers that consist of one or more
windows.</p></div>
<div class="paragraph"><p>TODO: picture of the tree</p></div>
<div class="paragraph"><p>To split a window vertically, press <code>$mod+v</code> before you create the new window.
To split it horizontally, press <code>$mod+h</code>.</p></div>
</div>
<div class="sect2">
<h3 id="_changing_the_container_layout">2.2. Changing the container layout</h3>
<div class="paragraph"><p>A split container can have one of the following layouts:</p></div>
<div class="dlist"><dl>
<dt class="hdlist1">
splith/splitv
</dt>
<dd>
<p>
Windows are sized so that every window gets an equal amount of space in the
container. splith distributes the windows horizontally (windows are right next
to each other), splitv distributes them vertically (windows are on top of each
other).
</p>
</dd>
<dt class="hdlist1">
stacking
</dt>
<dd>
<p>
Only the focused window in the container is displayed. You get a list of
windows at the top of the container.
</p>
</dd>
<dt class="hdlist1">
tabbed
</dt>
<dd>
<p>
The same principle as <code>stacking</code>, but the list of windows at the top is only
a single line which is vertically split.
</p>
</dd>
</dl></div>
<div class="paragraph"><p>To switch modes, press <code>$mod+e</code> for splith/splitv (it toggles), <code>$mod+s</code> for
stacking and <code>$mod+w</code> for tabbed.</p></div>
<div class="paragraph"><p><span class="image">
<img src="modes.png" alt="Container modes" />
</span></p></div>
</div>
<div class="sect2">
<h3 id="_toggling_fullscreen_mode_for_a_window">2.3. Toggling fullscreen mode for a window</h3>
<div class="paragraph"><p>To display a window in fullscreen mode or to go out of fullscreen mode again,
press <code>$mod+f</code>.</p></div>
<div class="paragraph"><p>There is also a global fullscreen mode in i3 in which the client will span all
available outputs (the command is <code>fullscreen toggle global</code>).</p></div>
</div>
<div class="sect2">
<h3 id="_opening_other_applications">2.4. Opening other applications</h3>
<div class="paragraph"><p>Aside from opening applications from a terminal, you can also use the handy
<code>dmenu</code> which is opened by pressing <code>$mod+d</code> by default. Just type the name
(or a part of it) of the application which you want to open. The corresponding
application has to be in your <code>$PATH</code> for this to work.</p></div>
<div class="paragraph"><p>Additionally, if you have applications you open very frequently, you can
create a keybinding for starting the application directly. See the section
<a href="#configuring">[configuring]</a> for details.</p></div>
</div>
<div class="sect2">
<h3 id="_closing_windows">2.5. Closing windows</h3>
<div class="paragraph"><p>If an application does not provide a mechanism for closing (most applications
provide a menu, the escape key or a shortcut like <code>Control+w</code> to close), you
can press <code>$mod+Shift+q</code> to kill a window. For applications which support
the WM_DELETE protocol, this will correctly close the application (saving
any modifications or doing other cleanup). If the application doesn’t support
the WM_DELETE protocol your X server will kill the window and the behaviour
depends on the application.</p></div>
</div>
<div class="sect2">
<h3 id="_using_workspaces">2.6. Using workspaces</h3>
<div class="paragraph"><p>Workspaces are an easy way to group a set of windows. By default, you are on
the first workspace, as the bar on the bottom left indicates. To switch to
another workspace, press <code>$mod+num</code> where <code>num</code> is the number of the workspace
you want to use. If the workspace does not exist yet, it will be created.</p></div>
<div class="paragraph"><p>A common paradigm is to put the web browser on one workspace, communication
applications (<code>mutt</code>, <code>irssi</code>, …) on another one, and the ones with which you
work, on the third one. Of course, there is no need to follow this approach.</p></div>
<div class="paragraph"><p>If you have multiple screens, a workspace will be created on each screen at
startup. If you open a new workspace, it will be bound to the screen you
created it on. When you switch to a workspace on another screen, i3 will set
focus to that screen.</p></div>
</div>
<div class="sect2">
<h3 id="_moving_windows_to_workspaces">2.7. Moving windows to workspaces</h3>
<div class="paragraph"><p>To move a window to another workspace, simply press <code>$mod+Shift+num</code> where
<code>num</code> is (like when switching workspaces) the number of the target workspace.
Similarly to switching workspaces, the target workspace will be created if
it does not yet exist.</p></div>
</div>
<div class="sect2">
<h3 id="_resizing">2.8. Resizing</h3>
<div class="paragraph"><p>The easiest way to resize a container is by using the mouse: Grab the border
and move it to the wanted size.</p></div>
<div class="paragraph"><p>You can also use <a href="#binding_modes">[binding_modes]</a> to define a mode for resizing via the
keyboard. To see an example for this, look at the
<a href="https://github.com/i3/i3/blob/next/etc/config.keycodes">default config</a> provided
by i3.</p></div>
</div>
<div class="sect2">
<h3 id="_restarting_i3_inplace">2.9. Restarting i3 inplace</h3>
<div class="paragraph"><p>To restart i3 in place (and thus get into a clean state if there is a bug, or
to upgrade to a newer version of i3) you can use <code>$mod+Shift+r</code>.</p></div>
</div>
<div class="sect2">
<h3 id="_exiting_i3">2.10. Exiting i3</h3>
<div class="paragraph"><p>To cleanly exit i3 without killing your X server, you can use <code>$mod+Shift+e</code>.
By default, a dialog will ask you to confirm if you really want to quit.</p></div>
</div>
<div class="sect2">
<h3 id="_floating">2.11. Floating</h3>
<div class="paragraph"><p>Floating mode is the opposite of tiling mode. The position and size of
a window are not managed automatically by i3, but manually by
you. Using this mode violates the tiling paradigm but can be useful
for some corner cases like "Save as" dialog windows, or toolbar
windows (GIMP or similar). Those windows usually set the appropriate
hint and are opened in floating mode by default.</p></div>
<div class="paragraph"><p>You can toggle floating mode for a window by pressing <code>$mod+Shift+Space</code>. By
dragging the window’s titlebar with your mouse you can move the window
around. By grabbing the borders and moving them you can resize the window. You
can also do that by using the <a href="#floating_modifier">[floating_modifier]</a>. Another way to resize
floating windows using the mouse is to right-click on the titlebar and drag.</p></div>
<div class="paragraph"><p>For resizing floating windows with your keyboard, see the resizing binding mode
provided by the i3 <a href="https://github.com/i3/i3/blob/next/etc/config.keycodes">default config</a>.</p></div>
<div class="paragraph"><p>Floating windows are always on top of tiling windows.</p></div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_tree">3. Tree</h2>
<div class="sectionbody">
<div class="paragraph"><p>i3 stores all information about the X11 outputs, workspaces and layout of the
windows on them in a tree. The root node is the X11 root window, followed by
the X11 outputs, then dock areas and a content container, then workspaces and
finally the windows themselves. In previous versions of i3 we had multiple lists
(of outputs, workspaces) and a table for each workspace. That approach turned
out to be complicated to use (snapping), understand and implement.</p></div>
<div class="sect2">
<h3 id="_the_tree_consists_of_containers">3.1. The tree consists of Containers</h3>
<div class="paragraph"><p>The building blocks of our tree are so called <code>Containers</code>. A <code>Container</code> can
host a window (meaning an X11 window, one that you can actually see and use,
like a browser). Alternatively, it could contain one or more <code>Containers</code>. A
simple example is the workspace: When you start i3 with a single monitor, a
single workspace and you open two terminal windows, you will end up with a tree
like this:</p></div>
<div class="imageblock" style="float:right;">
<div class="content">
<img src="tree-layout2.png" alt="layout2" />
</div>
</div>
<div class="imageblock">
<div class="content">
<img src="tree-shot4.png" alt="shot4" />
</div>
<div class="title">Figure 1. Two terminals on standard workspace</div>
</div>
</div>
<div class="sect2">
<h3 id="OrientationSplit">3.2. Orientation and Split Containers</h3>
<div class="paragraph"><p>It is only natural to use so-called <code>Split Containers</code> in order to build a
layout when using a tree as data structure. In i3, every <code>Container</code> has an
orientation (horizontal, vertical or unspecified) and the orientation depends
on the layout the container is in (vertical for splitv and stacking, horizontal
for splith and tabbed). So, in our example with the workspace, the default
layout of the workspace <code>Container</code> is splith (most monitors are widescreen
nowadays). If you change the layout to splitv (<code>$mod+v</code> in the default config)
and <strong>then</strong> open two terminals, i3 will configure your windows like this:</p></div>
<div class="imageblock">
<div class="content">
<img src="tree-shot2.png" alt="shot2" />
</div>
<div class="title">Figure 2. Vertical Workspace Orientation</div>
</div>
<div class="paragraph"><p>An interesting new feature of i3 since version 4 is the ability to split anything:
Let’s assume you have two terminals on a workspace (with splith layout, that is
horizontal orientation), focus is on the right terminal. Now you want to open
another terminal window below the current one. If you would just open a new
terminal window, it would show up to the right due to the splith layout.
Instead, press <code>$mod+v</code> to split the container with the splitv layout (to
open a <code>Horizontal Split Container</code>, use <code>$mod+h</code>). Now you can open a new
terminal and it will open below the current one:</p></div>
<div class="imageblock" style="float:right;">
<div class="content">
<img src="tree-layout1.png" alt="Layout" />
</div>
</div>
<div class="imageblock">
<div class="content">
<img src="tree-shot1.png" alt="shot" />
</div>
<div class="title">Figure 3. Vertical Split Container</div>
</div>
<div style="clear:both;"></div>
<div class="paragraph"><p>You probably guessed it already: There is no limit on how deep your hierarchy
of splits can be.</p></div>
</div>
<div class="sect2">
<h3 id="_focus_parent">3.3. Focus parent</h3>
<div class="paragraph"><p>Let’s stay with our example from above. We have a terminal on the left and two
vertically split terminals on the right, focus is on the bottom right one. When
you open a new terminal, it will open below the current one.</p></div>
<div class="paragraph"><p>So, how can you open a new terminal window to the <strong>right</strong> of the current one?
The solution is to use <code>focus parent</code>, which will focus the <code>Parent Container</code> of
the current <code>Container</code>. In this case, you would focus the <code>Vertical Split
Container</code> which is <strong>inside</strong> the horizontally oriented workspace. Thus, now new
windows will be opened to the right of the <code>Vertical Split Container</code>:</p></div>
<div class="imageblock">
<div class="content">
<img src="tree-shot3.png" alt="shot3" />
</div>
<div class="title">Figure 4. Focus parent, then open new terminal</div>
</div>
</div>
<div class="sect2">
<h3 id="_implicit_containers">3.4. Implicit containers</h3>
<div class="paragraph"><p>In some cases, i3 needs to implicitly create a container to fulfill your
command.</p></div>
<div class="paragraph"><p>One example is the following scenario: You start i3 with a single monitor and a
single workspace on which you open three terminal windows. All these terminal
windows are directly attached to one node inside i3’s layout tree, the
workspace node. By default, the workspace node’s orientation is <code>horizontal</code>.</p></div>
<div class="paragraph"><p>Now you move one of these terminals down (<code>$mod+Shift+k</code> by default). The
workspace node’s orientation will be changed to <code>vertical</code>. The terminal window
you moved down is directly attached to the workspace and appears on the bottom
of the screen. A new (horizontal) container was created to accommodate the
other two terminal windows. You will notice this when switching to tabbed mode
(for example). You would end up having one tab with a representation of the split
container (e.g., "H[urxvt firefox]") and the other one being the terminal window
you moved down.</p></div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="configuring">4. Configuring i3</h2>
<div class="sectionbody">
<div class="paragraph"><p>This is where the real fun begins ;-). Most things are very dependent on your
ideal working environment so we can’t make reasonable defaults for them.</p></div>
<div class="paragraph"><p>While not using a programming language for the configuration, i3 stays
quite flexible in regards to the things you usually want your window manager
to do.</p></div>
<div class="paragraph"><p>For example, you can configure bindings to jump to specific windows,
you can set specific applications to start on specific workspaces, you can
automatically start applications, you can change the colors of i3, and you
can bind your keys to do useful things.</p></div>
<div class="paragraph"><p>To change the configuration of i3, copy <code>/etc/i3/config</code> to <code>~/.i3/config</code>
(or <code>~/.config/i3/config</code> if you like the XDG directory scheme) and edit it
with a text editor.</p></div>
<div class="paragraph"><p>On first start (and on all following starts, unless you have a configuration
file), i3 will offer you to create a configuration file. You can tell the
wizard to use either Alt (<code>Mod1</code>) or Windows (<code>Mod4</code>) as modifier in the config
file. Also, the created config file will use the key symbols of your current
keyboard layout. To start the wizard, use the command <code>i3-config-wizard</code>.
Please note that you must not have <code>~/.i3/config</code>, otherwise the wizard will
exit.</p></div>
<div class="paragraph"><p>Since i3 4.0, a new configuration format is used. i3 will try to automatically
detect the format version of a config file based on a few different keywords,
but if you want to make sure that your config is read with the new format,
include the following line in your config file:</p></div>
<div class="listingblock">
<div class="content">
<pre><code># i3 config file (v4)</code></pre>
</div></div>
<div class="sect2">
<h3 id="_comments">4.1. Comments</h3>
<div class="paragraph"><p>It is possible and recommended to use comments in your configuration file to
properly document your setup for later reference. Comments are started with
a # and can only be used at the beginning of a line:</p></div>
<div class="paragraph"><p><strong>Examples</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code># This is a comment</code></pre>
</div></div>
</div>
<div class="sect2">
<h3 id="fonts">4.2. Fonts</h3>
<div class="paragraph"><p>i3 has support for both X core fonts and FreeType fonts (through Pango) to
render window titles.</p></div>
<div class="paragraph"><p>To generate an X core font description, you can use <code>xfontsel(1)</code>. To see
special characters (Unicode), you need to use a font which supports the
ISO-10646 encoding.</p></div>
<div class="paragraph"><p>A FreeType font description is composed by a font family, a style, a weight,
a variant, a stretch and a size.
FreeType fonts support right-to-left rendering and contain often more
Unicode glyphs than X core fonts.</p></div>
<div class="paragraph"><p>If i3 cannot open the configured font, it will output an error in the logfile
and fall back to a working font.</p></div>
<div class="paragraph"><p><strong>Syntax</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>font <X core font description>
font pango:<family list> [<style options>] <size></code></pre>
</div></div>
<div class="paragraph"><p><strong>Examples</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>font -misc-fixed-medium-r-normal--13-120-75-75-C-70-iso10646-1
font pango:DejaVu Sans Mono 10
font pango:DejaVu Sans Mono, Terminus Bold Semi-Condensed 11
font pango:Terminus 11px</code></pre>
</div></div>
</div>
<div class="sect2">
<h3 id="keybindings">4.3. Keyboard bindings</h3>
<div class="paragraph"><p>A keyboard binding makes i3 execute a command (see below) upon pressing a
specific key. i3 allows you to bind either on keycodes or on keysyms (you can
also mix your bindings, though i3 will not protect you from overlapping ones).</p></div>
<div class="ulist"><ul>
<li>
<p>
A keysym (key symbol) is a description for a specific symbol, like "a"
or "b", but also more strange ones like "underscore" instead of "_". These
are the ones you use in Xmodmap to remap your keys. To get the current
mapping of your keys, use <code>xmodmap -pke</code>. To interactively enter a key and
see what keysym it is configured to, use <code>xev</code>.
</p>
</li>
<li>
<p>
Keycodes do not need to have a symbol assigned (handy for custom vendor
hotkeys on some notebooks) and they will not change their meaning as you
switch to a different keyboard layout (when using <code>xmodmap</code>).
</p>
</li>
</ul></div>
<div class="paragraph"><p>My recommendation is: If you often switch keyboard layouts but you want to keep
your bindings in the same physical location on the keyboard, use keycodes.
If you don’t switch layouts, and want a clean and simple config file, use
keysyms.</p></div>
<div class="paragraph"><p>Some tools (such as <code>import</code> or <code>xdotool</code>) might be unable to run upon a
KeyPress event, because the keyboard/pointer is still grabbed. For these
situations, the <code>--release</code> flag can be used, which will execute the command
after the keys have been released.</p></div>
<div class="paragraph"><p><strong>Syntax</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>bindsym [--release] [<Group>+][<Modifiers>+]<keysym> command
bindcode [--release] [<Group>+][<Modifiers>+]<keycode> command</code></pre>
</div></div>
<div class="paragraph"><p><strong>Examples</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code># Fullscreen
bindsym $mod+f fullscreen toggle
# Restart
bindsym $mod+Shift+r restart
# Notebook-specific hotkeys
bindcode 214 exec --no-startup-id /home/michael/toggle_beamer.sh
# Simulate ctrl+v upon pressing $mod+x
bindsym --release $mod+x exec --no-startup-id xdotool key --clearmodifiers ctrl+v
# Take a screenshot upon pressing $mod+x (select an area)
bindsym --release $mod+x exec --no-startup-id import /tmp/latest-screenshot.png</code></pre>
</div></div>
<div class="paragraph"><p>Available Modifiers:</p></div>
<div class="dlist"><dl>
<dt class="hdlist1">
Mod1-Mod5, Shift, Control
</dt>
<dd>
<p>
Standard modifiers, see <code>xmodmap(1)</code>
</p>
</dd>
<dt class="hdlist1">
Group1, Group2, Group3, Group4
</dt>
<dd>
<p>
When using multiple keyboard layouts (e.g. with <code>setxkbmap -layout us,ru</code>), you
can specify in which XKB group (also called “layout”) a keybinding should be
active. By default, keybindings are translated in Group1 and are active in all
groups. If you want to override keybindings in one of your layouts, specify the
corresponding group. For backwards compatibility, the group “Mode_switch” is an
alias for Group2.
</p>
</dd>
</dl></div>
</div>
<div class="sect2">
<h3 id="mousebindings">4.4. Mouse bindings</h3>
<div class="paragraph"><p>A mouse binding makes i3 execute a command upon pressing a specific mouse
button in the scope of the clicked container (see <a href="#command_criteria">[command_criteria]</a>). You
can configure mouse bindings in a similar way to key bindings.</p></div>
<div class="paragraph"><p><strong>Syntax</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>bindsym [--release] [--border] [--whole-window] [--exclude-titlebar] [<Modifiers>+]button<n> command</code></pre>
</div></div>
<div class="paragraph"><p>By default, the binding will only run when you click on the titlebar of the
window. If the <code>--release</code> flag is given, it will run when the mouse button
is released.</p></div>
<div class="paragraph"><p>If the <code>--whole-window</code> flag is given, the binding will also run when any part
of the window is clicked, with the exception of the border. To have a bind run
when the border is clicked, specify the <code>--border</code> flag.</p></div>
<div class="paragraph"><p>If the <code>--exclude-titlebar</code> flag is given, the titlebar will not be considered
for the keybinding.</p></div>
<div class="paragraph"><p><strong>Examples</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code># The middle button over a titlebar kills the window
bindsym --release button2 kill
# The middle button and a modifer over any part of the window kills the window
bindsym --whole-window $mod+button2 kill
# The right button toggles floating
bindsym button3 floating toggle
bindsym $mod+button3 floating toggle
# The side buttons move the window around
bindsym button9 move left
bindsym button8 move right</code></pre>
</div></div>
</div>
<div class="sect2">
<h3 id="binding_modes">4.5. Binding modes</h3>
<div class="paragraph"><p>You can have multiple sets of bindings by using different binding modes. When
you switch to another binding mode, all bindings from the current mode are
released and only the bindings defined in the new mode are valid for as long as
you stay in that binding mode. The only predefined binding mode is <code>default</code>,
which is the mode i3 starts out with and to which all bindings not defined in a
specific binding mode belong.</p></div>
<div class="paragraph"><p>Working with binding modes consists of two parts: defining a binding mode and
switching to it. For these purposes, there are one config directive and one
command, both of which are called <code>mode</code>. The directive is used to define the
bindings belonging to a certain binding mode, while the command will switch to
the specified mode.</p></div>
<div class="paragraph"><p>It is recommended to use binding modes in combination with <a href="#variables">[variables]</a> in
order to make maintenance easier. Below is an example of how to use a binding
mode.</p></div>
<div class="paragraph"><p>Note that it is advisable to define bindings for switching back to the default
mode.</p></div>
<div class="paragraph"><p>Note that it is possible to use <a href="#pango_markup">[pango_markup]</a> for binding modes, but you
need to enable it explicitly by passing the <code>--pango_markup</code> flag to the mode
definition.</p></div>
<div class="paragraph"><p><strong>Syntax</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code># config directive
mode [--pango_markup] <name>
# command
mode <name></code></pre>
</div></div>
<div class="paragraph"><p><strong>Example</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code># Press $mod+o followed by either f, t, Escape or Return to launch firefox,
# thunderbird or return to the default mode, respectively.
set $mode_launcher Launch: [f]irefox [t]hunderbird
bindsym $mod+o mode "$mode_launcher"
mode "$mode_launcher" {
bindsym f exec firefox
bindsym t exec thunderbird
bindsym Escape mode "default"
bindsym Return mode "default"
}</code></pre>
</div></div>
</div>
<div class="sect2">
<h3 id="floating_modifier">4.6. The floating modifier</h3>
<div class="paragraph"><p>To move floating windows with your mouse, you can either grab their titlebar
or configure the so called floating modifier which you can then press and
click anywhere in the window itself to move it. The most common setup is to
use the same key you use for managing windows (Mod1 for example). Then
you can press Mod1, click into a window using your left mouse button, and drag
it to the position you want.</p></div>
<div class="paragraph"><p>When holding the floating modifier, you can resize a floating window by
pressing the right mouse button on it and moving around while holding it. If
you hold the shift button as well, the resize will be proportional (the aspect
ratio will be preserved).</p></div>
<div class="paragraph"><p><strong>Syntax</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>floating_modifier <Modifier></code></pre>
</div></div>
<div class="paragraph"><p><strong>Example</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>floating_modifier Mod1</code></pre>
</div></div>
</div>
<div class="sect2">
<h3 id="_constraining_floating_window_size">4.7. Constraining floating window size</h3>
<div class="paragraph"><p>The maximum and minimum dimensions of floating windows can be specified. If
either dimension of <code>floating_maximum_size</code> is specified as -1, that dimension
will be unconstrained with respect to its maximum value. If either dimension of
<code>floating_maximum_size</code> is undefined, or specified as 0, i3 will use a default
value to constrain the maximum size. <code>floating_minimum_size</code> is treated in a
manner analogous to <code>floating_maximum_size</code>.</p></div>
<div class="paragraph"><p><strong>Syntax</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>floating_minimum_size <width> x <height>
floating_maximum_size <width> x <height></code></pre>
</div></div>
<div class="paragraph"><p><strong>Example</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>floating_minimum_size 75 x 50
floating_maximum_size -1 x -1</code></pre>
</div></div>
</div>
<div class="sect2">
<h3 id="_orientation_for_new_workspaces">4.8. Orientation for new workspaces</h3>
<div class="paragraph"><p>New workspaces get a reasonable default orientation: Wide-screen monitors
(anything wider than high) get horizontal orientation, rotated monitors
(anything higher than wide) get vertical orientation.</p></div>
<div class="paragraph"><p>With the <code>default_orientation</code> configuration directive, you can override that
behavior.</p></div>
<div class="paragraph"><p><strong>Syntax</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>default_orientation horizontal|vertical|auto</code></pre>
</div></div>
<div class="paragraph"><p><strong>Example</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>default_orientation vertical</code></pre>
</div></div>
</div>
<div class="sect2">
<h3 id="_layout_mode_for_new_containers">4.9. Layout mode for new containers</h3>
<div class="paragraph"><p>This option determines in which mode new containers on workspace level will
start.</p></div>
<div class="paragraph"><p><strong>Syntax</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>workspace_layout default|stacking|tabbed</code></pre>
</div></div>
<div class="paragraph"><p><strong>Example</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>workspace_layout tabbed</code></pre>
</div></div>
</div>
<div class="sect2">
<h3 id="_border_style_for_new_windows">4.10. Border style for new windows</h3>
<div class="paragraph"><p>This option determines which border style new windows will have. The default is
<code>normal</code>. Note that new_float applies only to windows which are starting out as
floating windows, e.g., dialog windows, but not windows that are floated later on.</p></div>
<div class="paragraph"><p><strong>Syntax</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>new_window normal|none|pixel
new_window normal|pixel <px>
new_float normal|none|pixel
new_float normal|pixel <px></code></pre>
</div></div>
<div class="paragraph"><p><strong>Example</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>new_window pixel</code></pre>
</div></div>
<div class="paragraph"><p>The "normal" and "pixel" border styles support an optional border width in
pixels:</p></div>
<div class="paragraph"><p><strong>Example</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code># The same as new_window none
new_window pixel 0
# A 3 px border
new_window pixel 3</code></pre>
</div></div>
</div>
<div class="sect2">
<h3 id="_hiding_vertical_borders">4.11. Hiding borders adjacent to the screen edges</h3>
<div class="paragraph"><p>You can hide container borders adjacent to the screen edges using
<code>hide_edge_borders</code>. This is useful if you are using scrollbars, or do not want
to waste even two pixels in displayspace. The "smart" setting hides borders on
workspaces with only one window visible, but keeps them on workspaces with
multiple windows visible. Default is none.</p></div>
<div class="paragraph"><p><strong>Syntax</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>hide_edge_borders none|vertical|horizontal|both|smart</code></pre>
</div></div>
<div class="paragraph"><p><strong>Example</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>hide_edge_borders vertical</code></pre>
</div></div>
</div>
<div class="sect2">
<h3 id="for_window">4.12. Arbitrary commands for specific windows (for_window)</h3>
<div class="paragraph"><p>With the <code>for_window</code> command, you can let i3 execute any command when it
encounters a specific window. This can be used to set windows to floating or to
change their border style, for example.</p></div>
<div class="paragraph"><p><strong>Syntax</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>for_window <criteria> <command></code></pre>
</div></div>
<div class="paragraph"><p><strong>Examples</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code># enable floating mode for all XTerm windows
for_window [class="XTerm"] floating enable
# Make all urxvts use a 1-pixel border:
for_window [class="urxvt"] border pixel 1
# A less useful, but rather funny example:
# makes the window floating as soon as I change
# directory to ~/work
for_window [title="x200: ~/work"] floating enable</code></pre>
</div></div>
<div class="paragraph"><p>The valid criteria are the same as those for commands, see <a href="#command_criteria">[command_criteria]</a>.</p></div>
</div>
<div class="sect2">
<h3 id="no_focus">4.13. Don’t focus window upon opening</h3>
<div class="paragraph"><p>When a new window appears, it will be focused. The <code>no_focus</code> directive allows preventing
this from happening and must be used in combination with <a href="#command_criteria">[command_criteria]</a>.</p></div>
<div class="paragraph"><p>Note that this does not apply to all cases, e.g., when feeding data into a running application
causing it to request being focused. To configure the behavior in such cases, refer to
<a href="#focus_on_window_activation">[focus_on_window_activation]</a>.</p></div>
<div class="paragraph"><p><code>no_focus</code> will also be ignored for the first window on a workspace as there shouldn’t be
a reason to not focus the window in this case. This allows for better usability in
combination with <code>workspace_layout</code>.</p></div>
<div class="paragraph"><p><strong>Syntax</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>no_focus <criteria></code></pre>
</div></div>
<div class="paragraph"><p><strong>Example</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>no_focus [window_role="pop-up"]</code></pre>
</div></div>
</div>
<div class="sect2">
<h3 id="variables">4.14. Variables</h3>
<div class="paragraph"><p>As you learned in the section about keyboard bindings, you will have
to configure lots of bindings containing modifier keys. If you want to save
yourself some typing and be able to change the modifier you use later,
variables can be handy.</p></div>
<div class="paragraph"><p><strong>Syntax</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>set $<name> <value></code></pre>
</div></div>
<div class="paragraph"><p><strong>Example</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>set $m Mod1
bindsym $m+Shift+r restart</code></pre>
</div></div>
<div class="paragraph"><p>Variables are directly replaced in the file when parsing. Variables expansion
is not recursive so it is not possible to define a variable with a value
containing another variable. There is no fancy handling and there are
absolutely no plans to change this. If you need a more dynamic configuration
you should create a little script which generates a configuration file and run
it before starting i3 (for example in your <code>~/.xsession</code> file).</p></div>
<div class="paragraph"><p>Also see <a href="#xresources">[xresources]</a> to learn how to create variables based on resources
loaded from the X resource database.</p></div>
</div>
<div class="sect2">
<h3 id="xresources">4.15. X resources</h3>
<div class="paragraph"><p><a href="#variables">[variables]</a> can also be created using a value configured in the X resource
database. This is useful, for example, to avoid configuring color values within
the i3 configuration. Instead, the values can be configured, once, in the X
resource database to achieve an easily maintainable, consistent color theme
across many X applications.</p></div>
<div class="paragraph"><p>Defining a resource will load this resource from the resource database and
assign its value to the specified variable. A fallback must be specified in
case the resource cannot be loaded from the database.</p></div>
<div class="paragraph"><p><strong>Syntax</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>set_from_resource $<name> <resource_name> <fallback></code></pre>
</div></div>
<div class="paragraph"><p><strong>Example</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code># The ~/.Xresources should contain a line such as
# *color0: #121212
# and must be loaded properly, e.g., by using
# xrdb ~/.Xresources
# This value is picked up on by other applications (e.g., the URxvt terminal
# emulator) and can be used in i3 like this:
set_from_resource $black i3wm.color0 #000000</code></pre>
</div></div>
</div>
<div class="sect2">
<h3 id="assign_workspace">4.16. Automatically putting clients on specific workspaces</h3>
<div class="paragraph"><p>To automatically make a specific window show up on a specific workspace, you
can use an <strong>assignment</strong>. You can match windows by using any criteria,
see <a href="#command_criteria">[command_criteria]</a>. It is recommended that you match on window classes
(and instances, when appropriate) instead of window titles whenever possible
because some applications first create their window, and then worry about
setting the correct title. Firefox with Vimperator comes to mind. The window
starts up being named Firefox, and only when Vimperator is loaded does the
title change. As i3 will get the title as soon as the application maps the
window (mapping means actually displaying it on the screen), you’d need to have
to match on <em>Firefox</em> in this case.</p></div>
<div class="paragraph"><p>Assignments are processed by i3 in the order in which they appear in the config
file. The first one which matches the window wins and later assignments are not
considered.</p></div>
<div class="paragraph"><p><strong>Syntax</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>assign <criteria> [→] [workspace] <workspace></code></pre>
</div></div>
<div class="paragraph"><p><strong>Examples</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code># Assign URxvt terminals to workspace 2
assign [class="URxvt"] 2
# Same thing, but more precise (exact match instead of substring)
assign [class="^URxvt$"] 2
# Same thing, but with a beautiful arrow :)
assign [class="^URxvt$"] → 2
# Assignment to a named workspace
assign [class="^URxvt$"] → work
# Start urxvt -name irssi
assign [class="^URxvt$" instance="^irssi$"] → 3</code></pre>
</div></div>
<div class="paragraph"><p>Note that the arrow is not required, it just looks good :-). If you decide to
use it, it has to be a UTF-8 encoded arrow, not <code>-></code> or something like that.</p></div>
<div class="paragraph"><p>To get the class and instance, you can use <code>xprop</code>. After clicking on the
window, you will see the following output:</p></div>
<div class="paragraph"><p><strong>xprop</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>WM_CLASS(STRING) = "irssi", "URxvt"</code></pre>
</div></div>
<div class="paragraph"><p>The first part of the WM_CLASS is the instance ("irssi" in this example), the
second part is the class ("URxvt" in this example).</p></div>
<div class="paragraph"><p>Should you have any problems with assignments, make sure to check the i3
logfile first (see <a href="https://i3wm.org/docs/debugging.html">https://i3wm.org/docs/debugging.html</a>). It includes more
details about the matching process and the window’s actual class, instance and
title when starting up.</p></div>
<div class="paragraph"><p>Note that if you want to start an application just once on a specific
workspace, but you don’t want to assign all instances of it permanently, you
can make use of i3’s startup-notification support (see <a href="#exec">[exec]</a>) in your config
file in the following way:</p></div>
<div class="paragraph"><p><strong>Start iceweasel on workspace 3 (once)</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code># Start iceweasel on workspace 3, then switch back to workspace 1
# (Being a command-line utility, i3-msg does not support startup notifications,
# hence the exec --no-startup-id.)
# (Starting iceweasel with i3’s exec command is important in order to make i3
# create a startup notification context, without which the iceweasel window(s)
# cannot be matched onto the workspace on which the command was started.)
exec --no-startup-id i3-msg 'workspace 3; exec iceweasel; workspace 1'</code></pre>
</div></div>
</div>
<div class="sect2">
<h3 id="_automatically_starting_applications_on_i3_startup">4.17. Automatically starting applications on i3 startup</h3>
<div class="paragraph"><p>By using the <code>exec</code> keyword outside a keybinding, you can configure
which commands will be performed by i3 on initial startup. <code>exec</code>
commands will not run when restarting i3, if you need a command to run
also when restarting i3 you should use the <code>exec_always</code>
keyword. These commands will be run in order.</p></div>
<div class="paragraph"><p>See <a href="#command_chaining">[command_chaining]</a> for details on the special meaning of <code>;</code> (semicolon)
and <code>,</code> (comma): they chain commands together in i3, so you need to use quoted
strings (as shown in <a href="#exec_quoting">[exec_quoting]</a>) if they appear in your command.</p></div>
<div class="paragraph"><p><strong>Syntax</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>exec [--no-startup-id] <command>
exec_always [--no-startup-id] <command></code></pre>
</div></div>
<div class="paragraph"><p><strong>Examples</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>exec chromium
exec_always ~/my_script.sh
# Execute the terminal emulator urxvt, which is not yet startup-notification aware.
exec --no-startup-id urxvt</code></pre>
</div></div>
<div class="paragraph"><p>The flag --no-startup-id is explained in <a href="#exec">[exec]</a>.</p></div>
</div>
<div class="sect2">
<h3 id="workspace_screen">4.18. Automatically putting workspaces on specific screens</h3>
<div class="paragraph"><p>If you assign clients to workspaces, it might be handy to put the
workspaces on specific screens. Also, the assignment of workspaces to screens
will determine which workspace i3 uses for a new screen when adding screens
or when starting (e.g., by default it will use 1 for the first screen, 2 for
the second screen and so on).</p></div>
<div class="paragraph"><p><strong>Syntax</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>workspace <workspace> output <output></code></pre>
</div></div>
<div class="paragraph"><p>The <em>output</em> is the name of the RandR output you attach your screen to. On a
laptop, you might have VGA1 and LVDS1 as output names. You can see the
available outputs by running <code>xrandr --current</code>.</p></div>
<div class="paragraph"><p>If your X server supports RandR 1.5 or newer, i3 will use RandR monitor objects
instead of output objects. Run <code>xrandr --listmonitors</code> to see a list. Usually,
a monitor object contains exactly one output, and has the same name as the
output; but should that not be the case, you may specify the name of either the
monitor or the output in i3’s configuration. For example, the Dell UP2414Q uses
two scalers internally, so its output names might be “DP1” and “DP2”, but the
monitor name is “Dell UP2414Q”.</p></div>
<div class="paragraph"><p>(Note that even if you specify the name of an output which doesn’t span the
entire monitor, i3 will still use the entire area of the containing monitor
rather than that of just the output’s.)</p></div>
<div class="paragraph"><p>If you use named workspaces, they must be quoted:</p></div>
<div class="paragraph"><p><strong>Examples</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>workspace 1 output LVDS1
workspace 5 output VGA1
workspace "2: vim" output VGA1</code></pre>
</div></div>
</div>
<div class="sect2">
<h3 id="_changing_colors">4.19. Changing colors</h3>
<div class="paragraph"><p>You can change all colors which i3 uses to draw the window decorations.</p></div>
<div class="paragraph"><p><strong>Syntax</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code><colorclass> <border> <background> <text> <indicator> <child_border></code></pre>
</div></div>
<div class="paragraph"><p>Where colorclass can be one of:</p></div>
<div class="dlist"><dl>
<dt class="hdlist1">
client.focused
</dt>
<dd>
<p>
A client which currently has the focus.
</p>
</dd>
<dt class="hdlist1">
client.focused_inactive
</dt>
<dd>
<p>
A client which is the focused one of its container, but it does not have
the focus at the moment.
</p>
</dd>
<dt class="hdlist1">
client.unfocused
</dt>
<dd>
<p>
A client which is not the focused one of its container.
</p>
</dd>
<dt class="hdlist1">
client.urgent
</dt>
<dd>
<p>
A client which has its urgency hint activated.
</p>
</dd>
<dt class="hdlist1">
client.placeholder
</dt>
<dd>
<p>
Background and text color are used to draw placeholder window contents
(when restoring layouts). Border and indicator are ignored.
</p>
</dd>
<dt class="hdlist1">
client.background
</dt>
<dd>
<p>
Background color which will be used to paint the background of the
client window on top of which the client will be rendered. Only clients
which do not cover the whole area of this window expose the color. Note
that this colorclass only takes a single color.
</p>
</dd>
</dl></div>
<div class="paragraph"><p>Colors are in HTML hex format (#rrggbb), see the following example:</p></div>
<div class="paragraph"><p><strong>Examples (default colors)</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code># class border backgr. text indicator child_border
client.focused #4c7899 #285577 #ffffff #2e9ef4 #285577
client.focused_inactive #333333 #5f676a #ffffff #484e50 #5f676a
client.unfocused #333333 #222222 #888888 #292d2e #222222
client.urgent #2f343a #900000 #ffffff #900000 #900000
client.placeholder #000000 #0c0c0c #ffffff #000000 #0c0c0c
client.background #ffffff</code></pre>
</div></div>
<div class="paragraph"><p>Note that for the window decorations, the color around the child window is the
"child_border", and "border" color is only the two thin lines around the
titlebar.</p></div>
<div class="paragraph"><p>The indicator color is used for indicating where a new window will be opened.
For horizontal split containers, the right border will be painted in indicator
color, for vertical split containers, the bottom border. This only applies to
single windows within a split container, which are otherwise indistinguishable
from single windows outside of a split container.</p></div>
</div>
<div class="sect2">
<h3 id="_interprocess_communication">4.20. Interprocess communication</h3>
<div class="paragraph"><p>i3 uses Unix sockets to provide an IPC interface. This allows third-party
programs to get information from i3, such as the current workspaces
(to display a workspace bar), and to control i3.</p></div>
<div class="paragraph"><p>The IPC socket is enabled by default and will be created in
<code>/tmp/i3-%u.XXXXXX/ipc-socket.%p</code> where <code>%u</code> is your UNIX username, <code>%p</code> is
the PID of i3 and XXXXXX is a string of random characters from the portable
filename character set (see mkdtemp(3)).</p></div>
<div class="paragraph"><p>You can override the default path through the environment-variable <code>I3SOCK</code> or
by specifying the <code>ipc-socket</code> directive. This is discouraged, though, since i3
does the right thing by default. If you decide to change it, it is strongly
recommended to set this to a location in your home directory so that no other
user can create that directory.</p></div>
<div class="paragraph"><p><strong>Examples</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>ipc-socket ~/.i3/i3-ipc.sock</code></pre>
</div></div>
<div class="paragraph"><p>You can then use the <code>i3-msg</code> application to perform any command listed in
the next section.</p></div>
</div>
<div class="sect2">
<h3 id="_focus_follows_mouse">4.21. Focus follows mouse</h3>
<div class="paragraph"><p>By default, window focus follows your mouse movements as the mouse crosses
window borders. However, if you have a setup where your mouse usually is in your
way (like a touchpad on your laptop which you do not want to disable
completely), you might want to disable <em>focus follows mouse</em> and control focus
only by using your keyboard. The mouse will still be useful inside the
currently active window (for example to click on links in your browser window).</p></div>
<div class="paragraph"><p><strong>Syntax</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>focus_follows_mouse yes|no</code></pre>
</div></div>
<div class="paragraph"><p><strong>Example</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>focus_follows_mouse no</code></pre>
</div></div>
</div>
<div class="sect2">
<h3 id="_mouse_warping">4.22. Mouse warping</h3>
<div class="paragraph"><p>By default, when switching focus to a window on a different output (e.g.
focusing a window on workspace 3 on output VGA-1, coming from workspace 2 on
LVDS-1), the mouse cursor is warped to the center of that window.</p></div>
<div class="paragraph"><p>With the <code>mouse_warping</code> option, you can control when the mouse cursor should
be warped. <code>none</code> disables warping entirely, whereas <code>output</code> is the default
behavior described above.</p></div>
<div class="paragraph"><p><strong>Syntax</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>mouse_warping output|none</code></pre>
</div></div>
<div class="paragraph"><p><strong>Example</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>mouse_warping none</code></pre>
</div></div>
</div>
<div class="sect2">
<h3 id="_popups_during_fullscreen_mode">4.23. Popups during fullscreen mode</h3>
<div class="paragraph"><p>When you are in fullscreen mode, some applications still open popup windows
(take Xpdf for example). This is because these applications may not be aware
that they are in fullscreen mode (they do not check the corresponding hint).
There are three things which are possible to do in this situation:</p></div>
<div class="olist arabic"><ol class="arabic">
<li>
<p>
Display the popup if it belongs to the fullscreen application only. This is
the default and should be reasonable behavior for most users.
</p>
</li>
<li>
<p>
Just ignore the popup (don’t map it). This won’t interrupt you while you are
in fullscreen. However, some apps might react badly to this (deadlock until
you go out of fullscreen).
</p>
</li>
<li>
<p>
Leave fullscreen mode.
</p>
</li>
</ol></div>
<div class="paragraph"><p><strong>Syntax</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>popup_during_fullscreen smart|ignore|leave_fullscreen</code></pre>
</div></div>
<div class="paragraph"><p><strong>Example</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>popup_during_fullscreen smart</code></pre>
</div></div>
</div>
<div class="sect2">
<h3 id="_focus_wrapping">4.24. Focus wrapping</h3>
<div class="paragraph"><p>When being in a tabbed or stacked container, the first container will be
focused when you use <code>focus down</code> on the last container — the focus wraps. If
however there is another stacked/tabbed container in that direction, focus will
be set on that container. This is the default behavior so you can navigate to
all your windows without having to use <code>focus parent</code>.</p></div>
<div class="paragraph"><p>If you want the focus to <strong>always</strong> wrap and you are aware of using <code>focus
parent</code> to switch to different containers, you can use the
<code>force_focus_wrapping</code> configuration directive. After enabling it, the focus
will always wrap.</p></div>
<div class="paragraph"><p><strong>Syntax</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>force_focus_wrapping yes|no</code></pre>
</div></div>
<div class="paragraph"><p><strong>Example</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>force_focus_wrapping yes</code></pre>
</div></div>
</div>
<div class="sect2">
<h3 id="_forcing_xinerama">4.25. Forcing Xinerama</h3>
<div class="paragraph"><p>As explained in-depth in <a href="https://i3wm.org/docs/multi-monitor.html">https://i3wm.org/docs/multi-monitor.html</a>, some X11
video drivers (especially the nVidia binary driver) only provide support for
Xinerama instead of RandR. In such a situation, i3 must be told to use the
inferior Xinerama API explicitly and therefore don’t provide support for
reconfiguring your screens on the fly (they are read only once on startup and
that’s it).</p></div>
<div class="paragraph"><p>For people who cannot modify their <code>~/.xsession</code> to add the
<code>--force-xinerama</code> commandline parameter, a configuration option is provided:</p></div>
<div class="paragraph"><p><strong>Syntax</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>force_xinerama yes|no</code></pre>
</div></div>
<div class="paragraph"><p><strong>Example</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>force_xinerama yes</code></pre>
</div></div>
<div class="paragraph"><p>Also note that your output names are not descriptive (like <code>HDMI1</code>) when using
Xinerama, instead they are counted up, starting at 0: <code>xinerama-0</code>, <code>xinerama-1</code>, …</p></div>
</div>
<div class="sect2">
<h3 id="_automatic_back_and_forth_when_switching_to_the_current_workspace">4.26. Automatic back-and-forth when switching to the current workspace</h3>
<div class="paragraph"><p>This configuration directive enables automatic <code>workspace back_and_forth</code> (see
<a href="#back_and_forth">[back_and_forth]</a>) when switching to the workspace that is currently focused.</p></div>
<div class="paragraph"><p>For instance: Assume you are on workspace "1: www" and switch to "2: IM" using
mod+2 because somebody sent you a message. You don’t need to remember where you
came from now, you can just press $mod+2 again to switch back to "1: www".</p></div>
<div class="paragraph"><p><strong>Syntax</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>workspace_auto_back_and_forth yes|no</code></pre>
</div></div>
<div class="paragraph"><p><strong>Example</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>workspace_auto_back_and_forth yes</code></pre>
</div></div>
</div>
<div class="sect2">
<h3 id="_delaying_urgency_hint_reset_on_workspace_change">4.27. Delaying urgency hint reset on workspace change</h3>
<div class="paragraph"><p>If an application on another workspace sets an urgency hint, switching to this
workspace may lead to immediate focus of the application, which also means the
window decoration color would be immediately reset to <code>client.focused</code>. This
may make it unnecessarily hard to tell which window originally raised the
event.</p></div>
<div class="paragraph"><p>In order to prevent this, you can tell i3 to delay resetting the urgency state
by a certain time using the <code>force_display_urgency_hint</code> directive. Setting the
value to 0 disables this feature.</p></div>
<div class="paragraph"><p>The default is 500ms.</p></div>
<div class="paragraph"><p><strong>Syntax</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>force_display_urgency_hint <timeout> ms</code></pre>
</div></div>
<div class="paragraph"><p><strong>Example</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>force_display_urgency_hint 500 ms</code></pre>
</div></div>
</div>
<div class="sect2">
<h3 id="focus_on_window_activation">4.28. Focus on window activation</h3>
<div class="paragraph"><p>If a window is activated, e.g., via <code>google-chrome www.google.com</code>, it may request
to take focus. Since this may not preferable, different reactions can be configured.</p></div>
<div class="paragraph"><p>Note that this may not affect windows that are being opened. To prevent new windows
from being focused, see <a href="#no_focus">[no_focus]</a>.</p></div>
<div class="paragraph"><p><strong>Syntax</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>focus_on_window_activation smart|urgent|focus|none</code></pre>
</div></div>
<div class="paragraph"><p>The different modes will act as follows:</p></div>
<div class="dlist"><dl>
<dt class="hdlist1">
smart
</dt>
<dd>
<p>
This is the default behavior. If the window requesting focus is on an active
workspace, it will receive the focus. Otherwise, the urgency hint will be set.
</p>
</dd>
<dt class="hdlist1">
urgent
</dt>
<dd>
<p>
The window will always be marked urgent, but the focus will not be stolen.
</p>
</dd>
<dt class="hdlist1">
focus
</dt>
<dd>
<p>
The window will always be focused and not be marked urgent.
</p>
</dd>
<dt class="hdlist1">
none
</dt>
<dd>
<p>
The window will neither be focused, nor be marked urgent.
</p>
</dd>
</dl></div>
</div>
<div class="sect2">
<h3 id="show_marks">4.29. Drawing marks on window decoration</h3>
<div class="paragraph"><p>If activated, marks (see <a href="#vim_like_marks">[vim_like_marks]</a>) on windows are drawn in their window
decoration. However, any mark starting with an underscore in its name (<code>_</code>) will
not be drawn even if this option is activated.</p></div>
<div class="paragraph"><p>The default for this option is <code>yes</code>.</p></div>
<div class="paragraph"><p><strong>Syntax</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>show_marks yes|no</code></pre>
</div></div>
<div class="paragraph"><p><strong>Example</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>show_marks yes</code></pre>
</div></div>
</div>
<div class="sect2">
<h3 id="line_continuation">4.30. Line continuation</h3>
<div class="paragraph"><p>Config files support line continuation, meaning when you end a line in a
backslash character (<code>\</code>), the line-break will be ignored by the parser. This
feature can be used to create more readable configuration files.
Commented lines are not continued.</p></div>
<div class="paragraph"><p><strong>Examples</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>bindsym Mod1+f \
fullscreen toggle
# this line is not continued \
bindsym Mod1+F fullscreen toggle</code></pre>
</div></div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_configuring_i3bar">5. Configuring i3bar</h2>
<div class="sectionbody">
<div class="paragraph"><p>The bar at the bottom of your monitor is drawn by a separate process called
i3bar. Having this part of "the i3 user interface" in a separate process has
several advantages:</p></div>
<div class="olist arabic"><ol class="arabic">
<li>
<p>
It is a modular approach. If you don’t need a workspace bar at all, or if
you prefer a different one (dzen2, xmobar, maybe even gnome-panel?), you can
just remove the i3bar configuration and start your favorite bar instead.
</p>
</li>
<li>
<p>
It follows the UNIX philosophy of "Make each program do one thing well".
While i3 manages your windows well, i3bar is good at displaying a bar on
each monitor (unless you configure it otherwise).
</p>
</li>
<li>
<p>
It leads to two separate, clean codebases. If you want to understand i3, you
don’t need to bother with the details of i3bar and vice versa.
</p>
</li>
</ol></div>
<div class="paragraph"><p>That said, i3bar is configured in the same configuration file as i3. This is
because it is tightly coupled with i3 (in contrary to i3lock or i3status which
are useful for people using other window managers). Therefore, it makes no
sense to use a different configuration place when we already have a good
configuration infrastructure in place.</p></div>
<div class="paragraph"><p>Configuring your workspace bar starts with opening a <code>bar</code> block. You can have
multiple bar blocks to use different settings for different outputs (monitors):</p></div>
<div class="paragraph"><p><strong>Example</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>bar {
status_command i3status
}</code></pre>
</div></div>
<div class="sect2">
<h3 id="_i3bar_command">5.1. i3bar command</h3>
<div class="paragraph"><p>By default i3 will just pass <code>i3bar</code> and let your shell handle the execution,
searching your <code>$PATH</code> for a correct version.
If you have a different <code>i3bar</code> somewhere or the binary is not in your <code>$PATH</code> you can
tell i3 what to execute.</p></div>
<div class="paragraph"><p>The specified command will be passed to <code>sh -c</code>, so you can use globbing and
have to have correct quoting etc.</p></div>
<div class="paragraph"><p><strong>Syntax</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>i3bar_command <command></code></pre>
</div></div>
<div class="paragraph"><p><strong>Example</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>bar {
i3bar_command /home/user/bin/i3bar
}</code></pre>
</div></div>
</div>
<div class="sect2">
<h3 id="status_command">5.2. Statusline command</h3>
<div class="paragraph"><p>i3bar can run a program and display every line of its <code>stdout</code> output on the
right hand side of the bar. This is useful to display system information like
your current IP address, battery status or date/time.</p></div>
<div class="paragraph"><p>The specified command will be passed to <code>sh -c</code>, so you can use globbing and
have to have correct quoting etc. Note that for signal handling, depending on
your shell (users of dash(1) are known to be affected), you have to use the
shell’s exec command so that signals are passed to your program, not to the
shell.</p></div>
<div class="paragraph"><p><strong>Syntax</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>status_command <command></code></pre>
</div></div>
<div class="paragraph"><p><strong>Example</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>bar {
status_command i3status --config ~/.i3status.conf
# For dash(1) users who want signal handling to work:
status_command exec ~/.bin/my_status_command
}</code></pre>
</div></div>
</div>
<div class="sect2">
<h3 id="_display_mode">5.3. Display mode</h3>
<div class="paragraph"><p>You can either have i3bar be visible permanently at one edge of the screen
(<code>dock</code> mode) or make it show up when you press your modifier key (<code>hide</code> mode).
It is also possible to force i3bar to always stay hidden (<code>invisible</code>
mode). The modifier key can be configured using the <code>modifier</code> option.</p></div>
<div class="paragraph"><p>The mode option can be changed during runtime through the <code>bar mode</code> command.
On reload the mode will be reverted to its configured value.</p></div>
<div class="paragraph"><p>The hide mode maximizes screen space that can be used for actual windows. Also,
i3bar sends the <code>SIGSTOP</code> and <code>SIGCONT</code> signals to the statusline process to
save battery power.</p></div>
<div class="paragraph"><p>Invisible mode allows to permanently maximize screen space, as the bar is never
shown. Thus, you can configure i3bar to not disturb you by popping up because
of an urgency hint or because the modifier key is pressed.</p></div>
<div class="paragraph"><p>In order to control whether i3bar is hidden or shown in hide mode, there exists
the hidden_state option, which has no effect in dock mode or invisible mode. It
indicates the current hidden_state of the bar: (1) The bar acts like in normal
hide mode, it is hidden and is only unhidden in case of urgency hints or by
pressing the modifier key (<code>hide</code> state), or (2) it is drawn on top of the
currently visible workspace (<code>show</code> state).</p></div>
<div class="paragraph"><p>Like the mode, the hidden_state can also be controlled through i3, this can be
done by using the <code>bar hidden_state</code> command.</p></div>
<div class="paragraph"><p>The default mode is dock mode; in hide mode, the default modifier is Mod4 (usually
the windows key). The default value for the hidden_state is hide.</p></div>
<div class="paragraph"><p><strong>Syntax</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>mode dock|hide|invisible
hidden_state hide|show
modifier <Modifier>|none</code></pre>
</div></div>
<div class="paragraph"><p><strong>Example</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>bar {
mode hide
hidden_state hide
modifier Mod1
}</code></pre>
</div></div>
<div class="paragraph"><p>Available modifiers are Mod1-Mod5, Shift, Control (see <code>xmodmap(1)</code>). You can
also use "none" if you don’t want any modifier to trigger this behavior.</p></div>
</div>
<div class="sect2">
<h3 id="_mouse_button_commands">5.4. Mouse button commands</h3>
<div class="paragraph"><p>Specifies a command to run when a button was pressed on i3bar to override the
default behavior. This is useful, e.g., for disabling the scroll wheel action
or running scripts that implement custom behavior for these buttons.</p></div>
<div class="paragraph"><p>A button is always named <code>button<n></code>, where 1 to 5 are default buttons as follows and higher
numbers can be special buttons on devices offering more buttons:</p></div>
<div class="dlist"><dl>
<dt class="hdlist1">
button1
</dt>
<dd>
<p>
Left mouse button.
</p>
</dd>
<dt class="hdlist1">
button2
</dt>
<dd>
<p>
Middle mouse button.
</p>
</dd>
<dt class="hdlist1">
button3
</dt>
<dd>
<p>
Right mouse button.
</p>
</dd>
<dt class="hdlist1">
button4
</dt>
<dd>
<p>
Scroll wheel up.
</p>
</dd>
<dt class="hdlist1">
button5
</dt>
<dd>
<p>
Scroll wheel down.
</p>
</dd>
</dl></div>
<div class="paragraph"><p>Please note that the old <code>wheel_up_cmd</code> and <code>wheel_down_cmd</code> commands are deprecated
and will be removed in a future release. We strongly recommend using the more general
<code>bindsym</code> with <code>button4</code> and <code>button5</code> instead.</p></div>
<div class="paragraph"><p><strong>Syntax</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>bindsym button<n> <command></code></pre>
</div></div>
<div class="paragraph"><p><strong>Example</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>bar {
# disable clicking on workspace buttons
bindsym button1 nop
# execute custom script when scrolling downwards
bindsym button5 exec ~/.i3/scripts/custom_wheel_down
}</code></pre>
</div></div>
</div>
<div class="sect2">
<h3 id="_bar_id">5.5. Bar ID</h3>
<div class="paragraph"><p>Specifies the bar ID for the configured bar instance. If this option is missing,
the ID is set to <em>bar-x</em>, where x corresponds to the position of the embedding
bar block in the config file (<em>bar-0</em>, <em>bar-1</em>, …).</p></div>
<div class="paragraph"><p><strong>Syntax</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>id <bar_id></code></pre>
</div></div>
<div class="paragraph"><p><strong>Example</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>bar {
id bar-1
}</code></pre>
</div></div>
</div>
<div class="sect2">
<h3 id="i3bar_position">5.6. Position</h3>
<div class="paragraph"><p>This option determines in which edge of the screen i3bar should show up.</p></div>
<div class="paragraph"><p>The default is bottom.</p></div>
<div class="paragraph"><p><strong>Syntax</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>position top|bottom</code></pre>
</div></div>
<div class="paragraph"><p><strong>Example</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>bar {
position top
}</code></pre>
</div></div>
</div>
<div class="sect2">
<h3 id="_output_s">5.7. Output(s)</h3>
<div class="paragraph"><p>You can restrict i3bar to one or more outputs (monitors). The default is to
handle all outputs. Restricting the outputs is useful for using different
options for different outputs by using multiple <em>bar</em> blocks.</p></div>
<div class="paragraph"><p>To make a particular i3bar instance handle multiple outputs, specify the output
directive multiple times.</p></div>
<div class="paragraph"><p><strong>Syntax</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>output primary|<output></code></pre>
</div></div>
<div class="paragraph"><p><strong>Example</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code># big monitor: everything
bar {
# The display is connected either via HDMI or via DisplayPort
output HDMI2
output DP2
status_command i3status
}
# laptop monitor: bright colors and i3status with less modules.
bar {
output LVDS1
status_command i3status --config ~/.i3status-small.conf
colors {
background #000000
statusline #ffffff
}
}
# show bar on the primary monitor and on HDMI2
bar {
output primary
output HDMI2
status_command i3status
}</code></pre>
</div></div>
<div class="paragraph"><p>Note that you might not have a primary output configured yet. To do so, run:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>xrandr --output <output> --primary</code></pre>
</div></div>
</div>
<div class="sect2">
<h3 id="_tray_output">5.8. Tray output</h3>
<div class="paragraph"><p>i3bar by default provides a system tray area where programs such as
NetworkManager, VLC, Pidgin, etc. can place little icons.</p></div>
<div class="paragraph"><p>You can configure on which output (monitor) the icons should be displayed or
you can turn off the functionality entirely.</p></div>
<div class="paragraph"><p>You can use multiple <code>tray_output</code> directives in your config to specify a list
of outputs on which you want the tray to appear. The first available output in
that list as defined by the order of the directives will be used for the tray
output.</p></div>
<div class="paragraph"><p><strong>Syntax</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>tray_output none|primary|<output></code></pre>
</div></div>
<div class="paragraph"><p><strong>Example</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code># disable system tray
bar {
tray_output none
}
# show tray icons on the primary monitor
bar {
tray_output primary
}
# show tray icons on the big monitor
bar {
tray_output HDMI2
}</code></pre>
</div></div>
<div class="paragraph"><p>Note that you might not have a primary output configured yet. To do so, run:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>xrandr --output <output> --primary</code></pre>
</div></div>
<div class="paragraph"><p>Note that when you use multiple bar configuration blocks, either specify
<code>tray_output primary</code> in all of them or explicitly specify <code>tray_output none</code>
in bars which should not display the tray, otherwise the different instances
might race each other in trying to display tray icons.</p></div>
</div>
<div class="sect2">
<h3 id="_tray_padding">5.9. Tray padding</h3>
<div class="paragraph"><p>The tray is shown on the right-hand side of the bar. By default, a padding of 2
pixels is used for the upper, lower and right-hand side of the tray area and
between the individual icons.</p></div>
<div class="paragraph"><p><strong>Syntax</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>tray_padding <px> [px]</code></pre>
</div></div>
<div class="paragraph"><p><strong>Example</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code># Obey Fitts's law
tray_padding 0</code></pre>
</div></div>
</div>
<div class="sect2">
<h3 id="_font">5.10. Font</h3>
<div class="paragraph"><p>Specifies the font to be used in the bar. See <a href="#fonts">[fonts]</a>.</p></div>
<div class="paragraph"><p><strong>Syntax</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>font <font></code></pre>
</div></div>
<div class="paragraph"><p><strong>Example</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>bar {
font -misc-fixed-medium-r-normal--13-120-75-75-C-70-iso10646-1
font pango:DejaVu Sans Mono 10
}</code></pre>
</div></div>
</div>
<div class="sect2">
<h3 id="_custom_separator_symbol">5.11. Custom separator symbol</h3>
<div class="paragraph"><p>Specifies a custom symbol to be used for the separator as opposed to the vertical,
one pixel thick separator.</p></div>
<div class="paragraph"><p><strong>Syntax</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>separator_symbol <symbol></code></pre>
</div></div>
<div class="paragraph"><p><strong>Example</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>bar {
separator_symbol ":|:"
}</code></pre>
</div></div>
</div>
<div class="sect2">
<h3 id="_workspace_buttons">5.12. Workspace buttons</h3>
<div class="paragraph"><p>Specifies whether workspace buttons should be shown or not. This is useful if
you want to display a statusline-only bar containing additional information.</p></div>
<div class="paragraph"><p>The default is to show workspace buttons.</p></div>
<div class="paragraph"><p><strong>Syntax</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>workspace_buttons yes|no</code></pre>
</div></div>
<div class="paragraph"><p><strong>Example</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>bar {
workspace_buttons no
}</code></pre>
</div></div>
</div>
<div class="sect2">
<h3 id="_strip_workspace_numbers">5.13. Strip workspace numbers</h3>
<div class="paragraph"><p>Specifies whether workspace numbers should be displayed within the workspace
buttons. This is useful if you want to have a named workspace that stays in
order on the bar according to its number without displaying the number prefix.</p></div>
<div class="paragraph"><p>When <code>strip_workspace_numbers</code> is set to <code>yes</code>, any workspace that has a name of
the form "[n]:[NAME]" will display only the name. You could use this, for
instance, to display Roman numerals rather than digits by naming your
workspaces to "1:I", "2:II", "3:III", "4:IV", …</p></div>
<div class="paragraph"><p>The default is to display the full name within the workspace button.</p></div>
<div class="paragraph"><p><strong>Syntax</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>strip_workspace_numbers yes|no</code></pre>
</div></div>
<div class="paragraph"><p><strong>Example</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>bar {
strip_workspace_numbers yes
}</code></pre>
</div></div>
</div>
<div class="sect2">
<h3 id="_binding_mode_indicator">5.14. Binding Mode indicator</h3>
<div class="paragraph"><p>Specifies whether the current binding mode indicator should be shown or not.
This is useful if you want to hide the workspace buttons but still be able
to see the current binding mode indicator. See <a href="#binding_modes">[binding_modes]</a> to learn what
modes are and how to use them.</p></div>
<div class="paragraph"><p>The default is to show the mode indicator.</p></div>
<div class="paragraph"><p><strong>Syntax</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>binding_mode_indicator yes|no</code></pre>
</div></div>
<div class="paragraph"><p><strong>Example</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>bar {
binding_mode_indicator no
}</code></pre>
</div></div>
</div>
<div class="sect2">
<h3 id="_colors">5.15. Colors</h3>
<div class="paragraph"><p>As with i3, colors are in HTML hex format (#rrggbb). The following colors can
be configured at the moment:</p></div>
<div class="dlist"><dl>
<dt class="hdlist1">
background
</dt>
<dd>
<p>
Background color of the bar.
</p>
</dd>
<dt class="hdlist1">
statusline
</dt>
<dd>
<p>
Text color to be used for the statusline.
</p>
</dd>
<dt class="hdlist1">
separator
</dt>
<dd>
<p>
Text color to be used for the separator.
</p>
</dd>
<dt class="hdlist1">
focused_background
</dt>
<dd>
<p>
Background color of the bar on the currently focused monitor output. If
not used, the color will be taken from <code>background</code>.
</p>
</dd>
<dt class="hdlist1">
focused_statusline
</dt>
<dd>
<p>
Text color to be used for the statusline on the currently focused
monitor output. If not used, the color will be taken from <code>statusline</code>.
</p>
</dd>
<dt class="hdlist1">
focused_separator
</dt>
<dd>
<p>
Text color to be used for the separator on the currently focused
monitor output. If not used, the color will be taken from <code>separator</code>.
</p>
</dd>
<dt class="hdlist1">
focused_workspace
</dt>
<dd>
<p>
Border, background and text color for a workspace button when the workspace
has focus.
</p>
</dd>
<dt class="hdlist1">
active_workspace
</dt>
<dd>
<p>
Border, background and text color for a workspace button when the workspace
is active (visible) on some output, but the focus is on another one.
You can only tell this apart from the focused workspace when you are
using multiple monitors.
</p>
</dd>
<dt class="hdlist1">
inactive_workspace
</dt>
<dd>
<p>
Border, background and text color for a workspace button when the workspace
does not have focus and is not active (visible) on any output. This
will be the case for most workspaces.
</p>
</dd>
<dt class="hdlist1">
urgent_workspace
</dt>
<dd>
<p>
Border, background and text color for a workspace button when the workspace
contains a window with the urgency hint set.
</p>
</dd>
<dt class="hdlist1">
binding_mode
</dt>
<dd>
<p>
Border, background and text color for the binding mode indicator. If not used,
the colors will be taken from <code>urgent_workspace</code>.
</p>
</dd>
</dl></div>
<div class="paragraph"><p><strong>Syntax</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>colors {
background <color>
statusline <color>
separator <color>
<colorclass> <border> <background> <text>
}</code></pre>
</div></div>
<div class="paragraph"><p><strong>Example (default colors)</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>bar {
colors {
background #000000
statusline #ffffff
separator #666666
focused_workspace #4c7899 #285577 #ffffff
active_workspace #333333 #5f676a #ffffff
inactive_workspace #333333 #222222 #888888
urgent_workspace #2f343a #900000 #ffffff
binding_mode #2f343a #900000 #ffffff
}
}</code></pre>
</div></div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_list_of_commands">6. List of commands</h2>
<div class="sectionbody">
<div class="paragraph"><p>Commands are what you bind to specific keypresses. You can also issue commands
at runtime without pressing a key by using the IPC interface. An easy way to
do this is to use the <code>i3-msg</code> utility:</p></div>
<div class="paragraph"><p><strong>Example</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code># execute this on your shell to make the current container borderless
i3-msg border none</code></pre>
</div></div>
<div class="paragraph" id="command_chaining"><p>Commands can be chained by using <code>;</code> (a semicolon). So, to move a window to a
specific workspace and immediately switch to that workspace, you can configure
the following keybinding:</p></div>
<div class="paragraph"><p><strong>Example</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>bindsym $mod+x move container to workspace 3; workspace 3</code></pre>
</div></div>
<div class="paragraph" id="command_criteria"><p>Furthermore, you can change the scope of a command - that is, which containers
should be affected by that command, by using various criteria. The criteria
are specified before any command in a pair of square brackets and are separated
by space.</p></div>
<div class="paragraph"><p>When using multiple commands, separate them by using a <code>,</code> (a comma) instead of
a semicolon. Criteria apply only until the next semicolon, so if you use a
semicolon to separate commands, only the first one will be executed for the
matched window(s).</p></div>
<div class="paragraph"><p><strong>Example</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code># if you want to kill all windows which have the class Firefox, use:
bindsym $mod+x [class="Firefox"] kill
# same thing, but case-insensitive
bindsym $mod+x [class="(?i)firefox"] kill
# kill only the About dialog from Firefox
bindsym $mod+x [class="Firefox" window_role="About"] kill
# enable floating mode and move container to workspace 4
for_window [class="^evil-app$"] floating enable, move container to workspace 4
# move all floating windows to the scratchpad
bindsym $mod+x [floating] move scratchpad</code></pre>
</div></div>
<div class="paragraph"><p>The criteria which are currently implemented are:</p></div>
<div class="dlist"><dl>
<dt class="hdlist1">
class
</dt>
<dd>
<p>
Compares the window class (the second part of WM_CLASS). Use the
special value <code>__focused__</code> to match all windows having the same window
class as the currently focused window.
</p>
</dd>
<dt class="hdlist1">
instance
</dt>
<dd>
<p>
Compares the window instance (the first part of WM_CLASS). Use the
special value <code>__focused__</code> to match all windows having the same window
instance as the currently focused window.
</p>
</dd>
<dt class="hdlist1">
window_role
</dt>
<dd>
<p>
Compares the window role (WM_WINDOW_ROLE). Use the special value
<code>__focused__</code> to match all windows having the same window role as the
currently focused window.
</p>
</dd>
<dt class="hdlist1">
window_type
</dt>
<dd>
<p>
Compare the window type (_NET_WM_WINDOW_TYPE). Possible values are
<code>normal</code>, <code>dialog</code>, <code>utility</code>, <code>toolbar</code>, <code>splash</code>, <code>menu</code>, <code>dropdown_menu</code>,
<code>popup_menu</code>, <code>tooltip</code> and <code>notification</code>.
</p>
</dd>
<dt class="hdlist1">
id
</dt>
<dd>
<p>
Compares the X11 window ID, which you can get via <code>xwininfo</code> for example.
</p>
</dd>
<dt class="hdlist1">
title
</dt>
<dd>
<p>
Compares the X11 window title (_NET_WM_NAME or WM_NAME as fallback).
Use the special value <code>__focused__</code> to match all windows having the
same window title as the currently focused window.
</p>
</dd>
<dt class="hdlist1">
urgent
</dt>
<dd>
<p>
Compares the urgent state of the window. Can be "latest" or "oldest".
Matches the latest or oldest urgent window, respectively.
(The following aliases are also available: newest, last, recent, first)
</p>
</dd>
<dt class="hdlist1">
workspace
</dt>
<dd>
<p>
Compares the workspace name of the workspace the window belongs to. Use
the special value <code>__focused__</code> to match all windows in the currently
focused workspace.
</p>
</dd>
<dt class="hdlist1">
con_mark
</dt>
<dd>
<p>
Compares the marks set for this container, see <a href="#vim_like_marks">[vim_like_marks]</a>. A
match is made if any of the container’s marks matches the specified
mark.
</p>
</dd>
<dt class="hdlist1">
con_id
</dt>
<dd>
<p>
Compares the i3-internal container ID, which you can get via the IPC
interface. Handy for scripting. Use the special value <code>__focused__</code>
to match only the currently focused window.
</p>
</dd>
<dt class="hdlist1">
floating
</dt>
<dd>
<p>
Only matches floating windows. This criterion requires no value.
</p>
</dd>
<dt class="hdlist1">
tiling
</dt>
<dd>
<p>
Only matches tiling windows. This criterion requires no value.
</p>
</dd>
</dl></div>
<div class="paragraph"><p>The criteria <code>class</code>, <code>instance</code>, <code>role</code>, <code>title</code>, <code>workspace</code> and <code>mark</code> are
actually regular expressions (PCRE). See <code>pcresyntax(3)</code> or <code>perldoc perlre</code> for
information on how to use them.</p></div>
<div class="sect2">
<h3 id="exec">6.1. Executing applications (exec)</h3>
<div class="paragraph"><p>What good is a window manager if you can’t actually start any applications?
The exec command starts an application by passing the command you specify to a
shell. This implies that you can use globbing (wildcards) and programs will be
searched in your <code>$PATH</code>.</p></div>
<div class="paragraph"><p>See <a href="#command_chaining">[command_chaining]</a> for details on the special meaning of <code>;</code> (semicolon)
and <code>,</code> (comma): they chain commands together in i3, so you need to use quoted
strings (as shown in <a href="#exec_quoting">[exec_quoting]</a>) if they appear in your command.</p></div>
<div class="paragraph"><p><strong>Syntax</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>exec [--no-startup-id] <command></code></pre>
</div></div>
<div class="paragraph"><p><strong>Example</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code># Start the GIMP
bindsym $mod+g exec gimp
# Start the terminal emulator urxvt which is not yet startup-notification-aware
bindsym $mod+Return exec --no-startup-id urxvt</code></pre>
</div></div>
<div class="paragraph"><p>The <code>--no-startup-id</code> parameter disables startup-notification support for this
particular exec command. With startup-notification, i3 can make sure that a
window appears on the workspace on which you used the exec command. Also, it
will change the X11 cursor to <code>watch</code> (a clock) while the application is
launching. So, if an application is not startup-notification aware (most GTK
and Qt using applications seem to be, though), you will end up with a watch
cursor for 60 seconds.</p></div>
<div class="paragraph" id="exec_quoting"><p>If the command to be executed contains a <code>;</code> (semicolon) and/or a <code>,</code> (comma),
the entire command must be quoted. For example, to have a keybinding for the
shell command <code>notify-send Hello, i3</code>, you would add an entry to your
configuration file like this:</p></div>
<div class="paragraph"><p><strong>Example</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code># Execute a command with a comma in it
bindsym $mod+p exec "notify-send Hello, i3"</code></pre>
</div></div>
<div class="paragraph"><p>If however a command with a comma and/or semicolon itself requires quotes, you
must escape the internal quotation marks with double backslashes, like this:</p></div>
<div class="paragraph"><p><strong>Example</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code># Execute a command with a comma, semicolon and internal quotes
bindsym $mod+p exec "notify-send \\"Hello, i3; from $USER\\""</code></pre>
</div></div>
</div>
<div class="sect2">
<h3 id="_splitting_containers">6.2. Splitting containers</h3>
<div class="paragraph"><p>The split command makes the current window a split container. Split containers
can contain multiple windows. Depending on the layout of the split container,
new windows get placed to the right of the current one (splith) or new windows
get placed below the current one (splitv).</p></div>
<div class="paragraph"><p>If you apply this command to a split container with the same orientation,
nothing will happen. If you use a different orientation, the split container’s
orientation will be changed (if it does not have more than one window).
The <code>toggle</code> option will toggle the orientation of the split container if it
contains a single window. Otherwise it makes the current window a split
container with opposite orientation compared to the parent container.
Use <code>layout toggle split</code> to change the layout of any split container from
splitv to splith or vice-versa. You can also define a custom sequence of layouts
to cycle through with <code>layout toggle</code>, see <a href="#manipulating_layout">[manipulating_layout]</a>.</p></div>
<div class="paragraph"><p><strong>Syntax</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>split vertical|horizontal|toggle</code></pre>
</div></div>
<div class="paragraph"><p><strong>Example</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>bindsym $mod+v split vertical
bindsym $mod+h split horizontal
bindsym $mod+t split toggle</code></pre>
</div></div>
</div>
<div class="sect2">
<h3 id="_manipulating_layout">6.3. Manipulating layout</h3>
<div class="paragraph"><p>Use <code>layout toggle split</code>, <code>layout stacking</code>, <code>layout tabbed</code>, <code>layout splitv</code>
or <code>layout splith</code> to change the current container layout to splith/splitv,
stacking, tabbed layout, splitv or splith, respectively.</p></div>
<div class="paragraph"><p>Specify up to four layouts after <code>layout toggle</code> to cycle through them. Every
time the command is executed, the layout specified after the currently active
one will be applied. If the currently active layout is not in the list, the
first layout in the list will be activated.</p></div>
<div class="paragraph"><p>To make the current window (!) fullscreen, use <code>fullscreen enable</code> (or
<code>fullscreen enable global</code> for the global mode), to leave either fullscreen
mode use <code>fullscreen disable</code>, and to toggle between these two states use
<code>fullscreen toggle</code> (or <code>fullscreen toggle global</code>).</p></div>
<div class="paragraph"><p>Likewise, to make the current window floating (or tiling again) use <code>floating
enable</code> respectively <code>floating disable</code> (or <code>floating toggle</code>):</p></div>
<div class="paragraph"><p><strong>Syntax</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>layout default|tabbed|stacking|splitv|splith
layout toggle [split|all]
layout toggle [split|tabbed|stacking|splitv|splith] [split|tabbed|stacking|splitv|splith]…</code></pre>
</div></div>
<div class="paragraph"><p><strong>Examples</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>bindsym $mod+s layout stacking
bindsym $mod+l layout toggle split
bindsym $mod+w layout tabbed
# Toggle between stacking/tabbed/split:
bindsym $mod+x layout toggle
# Toggle between stacking/tabbed/splith/splitv:
bindsym $mod+x layout toggle all
# Toggle between stacking/tabbed/splith:
bindsym $mod+x layout toggle stacking tabbed splith
# Toggle between splitv/tabbed
bindsym $mod+x layout toggle splitv tabbed
# Toggle between last split layout/tabbed/stacking
bindsym $mod+x layout toggle split tabbed stacking
# Toggle fullscreen
bindsym $mod+f fullscreen toggle
# Toggle floating/tiling
bindsym $mod+t floating toggle</code></pre>
</div></div>
</div>
<div class="sect2">
<h3 id="_focusing_moving_containers">6.4. Focusing containers</h3>
<div class="paragraph"><p>To change focus, you can use the <code>focus</code> command. The following options are
available:</p></div>
<div class="dlist"><dl>
<dt class="hdlist1">
left|right|up|down
</dt>
<dd>
<p>
Sets focus to the nearest container in the given direction.
</p>
</dd>
<dt class="hdlist1">
parent
</dt>
<dd>
<p>
Sets focus to the parent container of the current container.
</p>
</dd>
<dt class="hdlist1">
child
</dt>
<dd>
<p>
The opposite of <code>focus parent</code>, sets the focus to the last focused
child container.
</p>
</dd>
<dt class="hdlist1">
floating
</dt>
<dd>
<p>
Sets focus to the last focused floating container.
</p>
</dd>
<dt class="hdlist1">
tiling
</dt>
<dd>
<p>
Sets focus to the last focused tiling container.
</p>
</dd>
<dt class="hdlist1">
mode_toggle
</dt>
<dd>
<p>
Toggles between floating/tiling containers.
</p>
</dd>
<dt class="hdlist1">
output
</dt>
<dd>
<p>
Followed by a direction or an output name, this will focus the
corresponding output.
</p>
</dd>
</dl></div>
<div class="paragraph"><p><strong>Syntax</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>focus left|right|down|up
focus parent|child|floating|tiling|mode_toggle
focus output left|right|up|down|primary|<output></code></pre>
</div></div>
<div class="paragraph"><p><strong>Examples</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code># Focus container on the left, bottom, top, right
bindsym $mod+j focus left
bindsym $mod+k focus down
bindsym $mod+l focus up
bindsym $mod+semicolon focus right
# Focus parent container
bindsym $mod+u focus parent
# Focus last floating/tiling container
bindsym $mod+g focus mode_toggle
# Focus the output right to the current one
bindsym $mod+x focus output right
# Focus the big output
bindsym $mod+x focus output HDMI-2
# Focus the primary output
bindsym $mod+x focus output primary</code></pre>
</div></div>
<div class="paragraph"><p>Note that you might not have a primary output configured yet. To do so, run:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>xrandr --output <output> --primary</code></pre>
</div></div>
</div>
<div class="sect2">
<h3 id="_moving_containers">6.5. Moving containers</h3>
<div class="paragraph"><p>Use the <code>move</code> command to move a container.</p></div>
<div class="paragraph"><p><strong>Syntax</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code># Moves the container into the given direction.
# The optional pixel argument specifies how far the
# container should be moved if it is floating and
# defaults to 10 pixels.
move <left|right|down|up> [<px> px]
# Moves the container either to a specific location
# or to the center of the screen. If 'absolute' is
# used, it is moved to the center of all outputs.
move [absolute] position <pos_x> [px] <pos_y> [px]
move [absolute] position center
# Moves the container to the current position of the
# mouse cursor. Only affects floating containers.
move position mouse</code></pre>
</div></div>
<div class="paragraph"><p><strong>Examples</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code># Move container to the left, bottom, top, right
bindsym $mod+j move left
bindsym $mod+k move down
bindsym $mod+l move up
bindsym $mod+semicolon move right
# Move container, but make floating containers
# move more than the default
bindsym $mod+j move left 20 px
# Move floating container to the center of all outputs
bindsym $mod+c move absolute position center
# Move container to the current position of the cursor
bindsym $mod+m move position mouse</code></pre>
</div></div>
</div>
<div class="sect2">
<h3 id="_swapping_containers">6.6. Swapping containers</h3>
<div class="paragraph"><p>Two containers can be swapped (i.e., move to each other’s position) by using
the <code>swap</code> command. They will assume the position and geometry of the container
they are swapped with.</p></div>
<div class="paragraph"><p>The first container to participate in the swapping can be selected through the
normal command criteria process with the focused window being the usual
fallback if no criteria are specified. The second container can be selected
using one of the following methods:</p></div>
<div class="dlist"><dl>
<dt class="hdlist1">
<code>id</code>
</dt>
<dd>
<p>
The X11 window ID of a client window.
</p>
</dd>
<dt class="hdlist1">
<code>con_id</code>
</dt>
<dd>
<p>
The i3 container ID of a container.
</p>
</dd>
<dt class="hdlist1">
<code>mark</code>
</dt>
<dd>
<p>
A container with the specified mark, see <a href="#vim_like_marks">[vim_like_marks]</a>.
</p>
</dd>
</dl></div>
<div class="paragraph"><p>Note that swapping does not work with all containers. Most notably, swapping
floating containers or containers that have a parent-child relationship to one
another does not work.</p></div>
<div class="paragraph"><p><strong>Syntax</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>swap container with id|con_id|mark <arg></code></pre>
</div></div>
<div class="paragraph"><p><strong>Examples</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code># Swaps the focused container with the container marked »swapee«.
swap container with mark swapee
# Swaps container marked »A« and »B«
[con_mark="^A$"] swap container with mark B</code></pre>
</div></div>
</div>
<div class="sect2">
<h3 id="_sticky_floating_windows">6.7. Sticky floating windows</h3>
<div class="paragraph"><p>If you want a window to stick to the glass, i.e., have it stay on screen even
if you switch to another workspace, you can use the <code>sticky</code> command. For
example, this can be useful for notepads, a media player or a video chat
window.</p></div>
<div class="paragraph"><p>Note that while any window can be made sticky through this command, it will
only take effect if the window is floating.</p></div>
<div class="paragraph"><p><strong>Syntax</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>sticky enable|disable|toggle</code></pre>
</div></div>
<div class="paragraph"><p><strong>Examples</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code># make a terminal sticky that was started as a notepad
for_window [instance=notepad] sticky enable</code></pre>
</div></div>
</div>
<div class="sect2">
<h3 id="_changing_named_workspaces_moving_to_workspaces">6.8. Changing (named) workspaces/moving to workspaces</h3>
<div class="paragraph"><p>To change to a specific workspace, use the <code>workspace</code> command, followed by the
number or name of the workspace. Pass the optional flag
<code>--no-auto-back-and-forth</code> to disable <a href="#back_and_forth">[back_and_forth]</a> for this specific call
only.</p></div>
<div class="paragraph"><p>To move containers to specific workspaces, use <code>move container to workspace</code>.</p></div>
<div class="paragraph"><p>You can also switch to the next and previous workspace with the commands
<code>workspace next</code> and <code>workspace prev</code>, which is handy, for example, if you have
workspace 1, 3, 4 and 9 and you want to cycle through them with a single key
combination. To restrict those to the current output, use <code>workspace
next_on_output</code> and <code>workspace prev_on_output</code>. Similarly, you can use <code>move
container to workspace next</code>, <code>move container to workspace prev</code> to move a
container to the next/previous workspace and <code>move container to workspace current</code>
(the last one makes sense only when used with criteria).</p></div>
<div class="paragraph"><p><code>workspace next</code> cycles through either numbered or named workspaces. But when it
reaches the last numbered/named workspace, it looks for named workspaces after
exhausting numbered ones and looks for numbered ones after exhausting named ones.</p></div>
<div class="paragraph"><p>See <a href="#move_to_outputs">[move_to_outputs]</a> for how to move a container/workspace to a different
RandR output.</p></div>
<div class="paragraph"><p>Workspace names are parsed as
<a href="https://developer.gnome.org/pango/stable/PangoMarkupFormat.html">Pango markup</a>
by i3bar.</p></div>
<div class="paragraph" id="back_and_forth"><p>To switch back to the previously focused workspace, use <code>workspace
back_and_forth</code>; likewise, you can move containers to the previously focused
workspace using <code>move container to workspace back_and_forth</code>.</p></div>
<div class="paragraph"><p><strong>Syntax</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>workspace next|prev|next_on_output|prev_on_output
workspace back_and_forth
workspace [--no-auto-back-and-forth] <name>
workspace [--no-auto-back-and-forth] number <name>
move [--no-auto-back-and-forth] [window|container] [to] workspace <name>
move [--no-auto-back-and-forth] [window|container] [to] workspace number <name>
move [window|container] [to] workspace prev|next|current</code></pre>
</div></div>
<div class="paragraph"><p><strong>Examples</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>bindsym $mod+1 workspace 1
bindsym $mod+2 workspace 2
bindsym $mod+3 workspace 3:<span foreground="red">vim</span>
...
bindsym $mod+Shift+1 move container to workspace 1
bindsym $mod+Shift+2 move container to workspace 2
...
# switch between the current and the previously focused one
bindsym $mod+b workspace back_and_forth
bindsym $mod+Shift+b move container to workspace back_and_forth
# move the whole workspace to the next output
bindsym $mod+x move workspace to output right
# move firefox to current workspace
bindsym $mod+F1 [class="Firefox"] move workspace current</code></pre>
</div></div>
<div class="sect3">
<h4 id="_named_workspaces">6.8.1. Named workspaces</h4>
<div class="paragraph"><p>Workspaces are identified by their name. So, instead of using numbers in the
workspace command, you can use an arbitrary name:</p></div>
<div class="paragraph"><p><strong>Example</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>bindsym $mod+1 workspace mail
...</code></pre>
</div></div>
<div class="paragraph"><p>If you want the workspace to have a number <strong>and</strong> a name, just prefix the
number, like this:</p></div>
<div class="paragraph"><p><strong>Example</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>bindsym $mod+1 workspace 1: mail
bindsym $mod+2 workspace 2: www
...</code></pre>
</div></div>
<div class="paragraph"><p>Note that the workspace will really be named "1: mail". i3 treats workspace
names beginning with a number in a slightly special way. Normally, named
workspaces are ordered the way they appeared. When they start with a number, i3
will order them numerically. Also, you will be able to use <code>workspace number 1</code>
to switch to the workspace which begins with number 1, regardless of which name
it has. This is useful in case you are changing the workspace’s name
dynamically. To combine both commands you can use <code>workspace number 1: mail</code> to
specify a default name if there’s currently no workspace starting with a "1".</p></div>
</div>
<div class="sect3">
<h4 id="_renaming_workspaces">6.8.2. Renaming workspaces</h4>
<div class="paragraph"><p>You can rename workspaces. This might be useful to start with the default
numbered workspaces, do your work, and rename the workspaces afterwards to
reflect what’s actually on them. You can also omit the old name to rename
the currently focused workspace. This is handy if you want to use the
rename command with <code>i3-input</code>.</p></div>
<div class="paragraph"><p><strong>Syntax</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>rename workspace <old_name> to <new_name>
rename workspace to <new_name></code></pre>
</div></div>
<div class="paragraph"><p><strong>Examples</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>i3-msg 'rename workspace 5 to 6'
i3-msg 'rename workspace 1 to "1: www"'
i3-msg 'rename workspace "1: www" to "10: www"'
i3-msg 'rename workspace to "2: mail"'
bindsym $mod+r exec i3-input -F 'rename workspace to "%s"' -P 'New name: '</code></pre>
</div></div>
<div class="paragraph"><p>If you want to rename workspaces on demand while keeping the navigation stable,
you can use a setup like this:</p></div>
<div class="paragraph"><p><strong>Example</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>bindsym $mod+1 workspace number "1: www"
bindsym $mod+2 workspace number "2: mail"
...</code></pre>
</div></div>
<div class="paragraph"><p>If a workspace does not exist, the command <code>workspace number "1: mail"</code> will
create workspace "1: mail".</p></div>
<div class="paragraph"><p>If a workspace with number 1 does already exist, the command will switch to this
workspace and ignore the text part. So even when the workspace has been renamed
to "1: web", the above command will still switch to it.</p></div>
</div>
</div>
<div class="sect2">
<h3 id="_moving_workspaces_to_a_different_screen">6.9. Moving workspaces to a different screen</h3>
<div class="paragraph"><p>See <a href="#move_to_outputs">[move_to_outputs]</a> for how to move a container/workspace to a different
RandR output.</p></div>
</div>
<div class="sect2">
<h3 id="_moving_containers_workspaces_to_randr_outputs">6.10. Moving containers/workspaces to RandR outputs</h3>
<div class="paragraph"><p>To move a container to another RandR output (addressed by names like <code>LVDS1</code> or
<code>VGA1</code>) or to a RandR output identified by a specific direction (like <code>left</code>,
<code>right</code>, <code>up</code> or <code>down</code>), there are two commands:</p></div>
<div class="paragraph"><p><strong>Syntax</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>move container to output left|right|down|up|current|primary|<output>
move workspace to output left|right|down|up|current|primary|<output></code></pre>
</div></div>
<div class="paragraph"><p><strong>Examples</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code># Move the current workspace to the next output
# (effectively toggles when you only have two outputs)
bindsym $mod+x move workspace to output right
# Put this window on the presentation output.
bindsym $mod+x move container to output VGA1
# Put this window on the primary output.
bindsym $mod+x move container to output primary</code></pre>
</div></div>
<div class="listingblock">
<div class="content">
<pre><code>Note that you might not have a primary output configured yet. To do so, run:</code></pre>
</div></div>
<div class="paragraph"><p>xrandr --output <output> --primary</p></div>
<div class="listingblock">
<div class="content">
<pre><code>=== Moving containers/windows to marks
To move a container to another container with a specific mark (see <<vim_like_marks>>),
you can use the following command.
The window will be moved right after the marked container in the tree, i.e., it ends up
in the same position as if you had opened a new window when the marked container was
focused. If the mark is on a split container, the window will appear as a new child
after the currently focused child within that container.
*Syntax*:</code></pre>
</div></div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_move_window_container_to_mark_lt_mark_gt">7. move window|container to mark <mark></h2>
<div class="sectionbody">
<div class="paragraph"><p><strong>Example</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>for_window [instance="tabme"] move window to mark target</code></pre>
</div></div>
<div class="sect2">
<h3 id="resizingconfig">7.1. Resizing containers/windows</h3>
<div class="paragraph"><p>If you want to resize containers/windows using your keyboard, you can use the
<code>resize</code> command:</p></div>
<div class="paragraph"><p><strong>Syntax</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>resize grow|shrink <direction> [<px> px [or <ppt> ppt]]
resize set <width> [px] <height> [px]</code></pre>
</div></div>
<div class="paragraph"><p>Direction can either be one of <code>up</code>, <code>down</code>, <code>left</code> or <code>right</code>. Or you can be
less specific and use <code>width</code> or <code>height</code>, in which case i3 will take/give
space from all the other containers. The optional pixel argument specifies by
how many pixels a <strong>floating container</strong> should be grown or shrunk (the default
is 10 pixels). The ppt argument means percentage points and specifies by how
many percentage points a <strong>tiling container</strong> should be grown or shrunk (the
default is 10 percentage points). Note that <code>resize set</code> will only work for
floating containers.</p></div>
<div class="paragraph"><p>It is recommended to define bindings for resizing in a dedicated binding mode.
See <a href="#binding_modes">[binding_modes]</a> and the example in the i3
<a href="https://github.com/i3/i3/blob/next/etc/config.keycodes">default config</a> for more
context.</p></div>
<div class="paragraph"><p><strong>Example</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>for_window [class="urxvt"] resize set 640 480</code></pre>
</div></div>
</div>
<div class="sect2">
<h3 id="_jumping_to_specific_windows">7.2. Jumping to specific windows</h3>
<div class="paragraph"><p>Often when in a multi-monitor environment, you want to quickly jump to a
specific window. For example, while working on workspace 3 you may want to
jump to your mail client to email your boss that you’ve achieved some
important goal. Instead of figuring out how to navigate to your mail client,
it would be more convenient to have a shortcut. You can use the <code>focus</code> command
with criteria for that.</p></div>
<div class="paragraph"><p><strong>Syntax</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>[class="class"] focus
[title="title"] focus</code></pre>
</div></div>
<div class="paragraph"><p><strong>Examples</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code># Get me to the next open VIM instance
bindsym $mod+a [class="urxvt" title="VIM"] focus</code></pre>
</div></div>
</div>
<div class="sect2">
<h3 id="vim_like_marks">7.3. VIM-like marks (mark/goto)</h3>
<div class="paragraph"><p>This feature is like the jump feature: It allows you to directly jump to a
specific window (this means switching to the appropriate workspace and setting
focus to the windows). However, you can directly mark a specific window with
an arbitrary label and use it afterwards. You can unmark the label in the same
way, using the unmark command. If you don’t specify a label, unmark removes all
marks. You do not need to ensure that your windows have unique classes or
titles, and you do not need to change your configuration file.</p></div>
<div class="paragraph"><p>As the command needs to include the label with which you want to mark the
window, you cannot simply bind it to a key. <code>i3-input</code> is a tool created
for this purpose: It lets you input a command and sends the command to i3. It
can also prefix this command and display a custom prompt for the input dialog.</p></div>
<div class="paragraph"><p>The additional <code>--toggle</code> option will remove the mark if the window already has
this mark or add it otherwise. Note that you may need to use this in
combination with <code>--add</code> (see below) as any other marks will otherwise be
removed.</p></div>
<div class="paragraph"><p>By default, a window can only have one mark. You can use the <code>--add</code> flag to
put more than one mark on a window.</p></div>
<div class="paragraph"><p>Refer to <a href="#show_marks">[show_marks]</a> if you don’t want marks to be shown in the window decoration.</p></div>
<div class="paragraph"><p><strong>Syntax</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>mark [--add|--replace] [--toggle] <identifier>
[con_mark="identifier"] focus
unmark <identifier></code></pre>
</div></div>
<div class="paragraph"><p><strong>Example (in a terminal)</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code># marks the focused container
mark irssi
# focus the container with the mark "irssi"
'[con_mark="irssi"] focus'
# remove the mark "irssi" from whichever container has it
unmark irssi
# remove all marks on all firefox windows
[class="(?i)firefox"] unmark</code></pre>
</div></div>
</div>
<div class="sect2">
<h3 id="pango_markup">7.4. Window title format</h3>
<div class="paragraph"><p>By default, i3 will simply print the X11 window title. Using <code>title_format</code>,
this can be customized by setting the format to the desired output. This
directive supports
<a href="https://developer.gnome.org/pango/stable/PangoMarkupFormat.html">Pango markup</a>
and the following placeholders which will be replaced:</p></div>
<div class="dlist"><dl>
<dt class="hdlist1">
<code>%title</code>
</dt>
<dd>
<p>
For normal windows, this is the X11 window title (_NET_WM_NAME or WM_NAME
as fallback). When used on containers without a window (e.g., a split
container inside a tabbed/stacked layout), this will be the tree
representation of the container (e.g., "H[xterm xterm]").
</p>
</dd>
<dt class="hdlist1">
<code>%class</code>
</dt>
<dd>
<p>
The X11 window class (second part of WM_CLASS). This corresponds to the
<code>class</code> criterion, see <a href="#command_criteria">[command_criteria]</a>.
</p>
</dd>
<dt class="hdlist1">
<code>%instance</code>
</dt>
<dd>
<p>
The X11 window instance (first part of WM_CLASS). This corresponds to the
<code>instance</code> criterion, see <a href="#command_criteria">[command_criteria]</a>.
</p>
</dd>
</dl></div>
<div class="paragraph"><p>Using the <a href="#for_window">[for_window]</a> directive, you can set the title format for any window
based on <a href="#command_criteria">[command_criteria]</a>.</p></div>
<div class="paragraph"><p><strong>Syntax</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>title_format <format></code></pre>
</div></div>
<div class="paragraph"><p><strong>Examples</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code># give the focused window a prefix
bindsym $mod+p title_format "Important | %title"
# print all window titles bold
for_window [class=".*"] title_format "<b>%title</b>"
# print window titles of firefox windows red
for_window [class="(?i)firefox"] title_format "<span foreground='red'>%title</span>"</code></pre>
</div></div>
</div>
<div class="sect2">
<h3 id="_changing_border_style">7.5. Changing border style</h3>
<div class="paragraph"><p>To change the border of the current client, you can use <code>border normal</code> to use the normal
border (including window title), <code>border pixel 1</code> to use a 1-pixel border (no window title)
and <code>border none</code> to make the client borderless.</p></div>
<div class="paragraph"><p>There is also <code>border toggle</code> which will toggle the different border styles.</p></div>
<div class="paragraph"><p>Note that "pixel" refers to logical pixel. On HiDPI displays, a logical pixel
may be represented by multiple physical pixels, so <code>pixel 1</code> might not
necessarily translate into a single pixel row wide border.</p></div>
<div class="paragraph"><p><strong>Syntax</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>border normal|pixel [<n>]
border none|toggle
# legacy syntax, equivalent to "border pixel 1"
border 1pixel</code></pre>
</div></div>
<div class="paragraph"><p><strong>Examples</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code># use window title, but no border
bindsym $mod+t border normal 0
# use no window title and a thick border
bindsym $mod+y border pixel 3
# use neither window title nor border
bindsym $mod+u border none</code></pre>
</div></div>
</div>
<div class="sect2">
<h3 id="shmlog">7.6. Enabling shared memory logging</h3>
<div class="paragraph"><p>As described in <a href="https://i3wm.org/docs/debugging.html">https://i3wm.org/docs/debugging.html</a>, i3 can log to a shared
memory buffer, which you can dump using <code>i3-dump-log</code>. The <code>shmlog</code> command
allows you to enable or disable the shared memory logging at runtime.</p></div>
<div class="paragraph"><p>Note that when using <code>shmlog <size_in_bytes></code>, the current log will be
discarded and a new one will be started.</p></div>
<div class="paragraph"><p><strong>Syntax</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>shmlog <size_in_bytes>
shmlog on|off|toggle</code></pre>
</div></div>
<div class="paragraph"><p><strong>Examples</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code># Enable/disable logging
bindsym $mod+x shmlog toggle
# or, from a terminal:
# increase the shared memory log buffer to 50 MiB
i3-msg shmlog $((50*1024*1024))</code></pre>
</div></div>
</div>
<div class="sect2">
<h3 id="_enabling_debug_logging">7.7. Enabling debug logging</h3>
<div class="paragraph"><p>The <code>debuglog</code> command allows you to enable or disable debug logging at
runtime. Debug logging is much more verbose than non-debug logging. This
command does not activate shared memory logging (shmlog), and as such is most
likely useful in combination with the above-described <a href="#shmlog">[shmlog]</a> command.</p></div>
<div class="paragraph"><p><strong>Syntax</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>debuglog on|off|toggle</code></pre>
</div></div>
<div class="paragraph"><p><strong>Examples</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code># Enable/disable logging
bindsym $mod+x debuglog toggle</code></pre>
</div></div>
</div>
<div class="sect2">
<h3 id="_reloading_restarting_exiting">7.8. Reloading/Restarting/Exiting</h3>
<div class="paragraph"><p>You can make i3 reload its configuration file with <code>reload</code>. You can also
restart i3 inplace with the <code>restart</code> command to get it out of some weird state
(if that should ever happen) or to perform an upgrade without having to restart
your X session. To exit i3 properly, you can use the <code>exit</code> command,
however you don’t need to (simply killing your X session is fine as well).</p></div>
<div class="paragraph"><p><strong>Examples</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>bindsym $mod+Shift+r restart
bindsym $mod+Shift+w reload
bindsym $mod+Shift+e exit</code></pre>
</div></div>
</div>
<div class="sect2">
<h3 id="_scratchpad">7.9. Scratchpad</h3>
<div class="paragraph"><p>There are two commands to use any existing window as scratchpad window. <code>move
scratchpad</code> will move a window to the scratchpad workspace. This will make it
invisible until you show it again. There is no way to open that workspace.
Instead, when using <code>scratchpad show</code>, the window will be shown again, as a
floating window, centered on your current workspace (using <code>scratchpad show</code> on
a visible scratchpad window will make it hidden again, so you can have a
keybinding to toggle). Note that this is just a normal floating window, so if
you want to "remove it from scratchpad", you can simple make it tiling again
(<code>floating toggle</code>).</p></div>
<div class="paragraph"><p>As the name indicates, this is useful for having a window with your favorite
editor always at hand. However, you can also use this for other permanently
running applications which you don’t want to see all the time: Your music
player, alsamixer, maybe even your mail client…?</p></div>
<div class="paragraph"><p><strong>Syntax</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>move scratchpad
scratchpad show</code></pre>
</div></div>
<div class="paragraph"><p><strong>Examples</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code># Make the currently focused window a scratchpad
bindsym $mod+Shift+minus move scratchpad
# Show the first scratchpad window
bindsym $mod+minus scratchpad show
# Show the sup-mail scratchpad window, if any.
bindsym mod4+s [title="^Sup ::"] scratchpad show</code></pre>
</div></div>
</div>
<div class="sect2">
<h3 id="_nop">7.10. Nop</h3>
<div class="paragraph"><p>There is a no operation command <code>nop</code> which allows you to override default
behavior. This can be useful for, e.g., disabling a focus change on clicks with
the middle mouse button.</p></div>
<div class="paragraph"><p>The optional <code>comment</code> argument is ignored, but will be printed to the log file
for debugging purposes.</p></div>
<div class="paragraph"><p><strong>Syntax</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>nop [<comment>]</code></pre>
</div></div>
<div class="paragraph"><p><strong>Example</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code># Disable focus change for clicks on titlebars
# with the middle mouse button
bindsym button2 nop</code></pre>
</div></div>
</div>
<div class="sect2">
<h3 id="_i3bar_control">7.11. i3bar control</h3>
<div class="paragraph"><p>There are two options in the configuration of each i3bar instance that can be
changed during runtime by invoking a command through i3. The commands <code>bar
hidden_state</code> and <code>bar mode</code> allow setting the current hidden_state
respectively mode option of each bar. It is also possible to toggle between
hide state and show state as well as between dock mode and hide mode. Each
i3bar instance can be controlled individually by specifying a bar_id, if none
is given, the command is executed for all bar instances.</p></div>
<div class="paragraph"><p><strong>Syntax</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>bar hidden_state hide|show|toggle [<bar_id>]
bar mode dock|hide|invisible|toggle [<bar_id>]</code></pre>
</div></div>
<div class="paragraph"><p><strong>Examples</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code># Toggle between hide state and show state
bindsym $mod+m bar hidden_state toggle
# Toggle between dock mode and hide mode
bindsym $mod+n bar mode toggle
# Set the bar instance with id 'bar-1' to switch to hide mode
bindsym $mod+b bar mode hide bar-1
# Set the bar instance with id 'bar-1' to always stay hidden
bindsym $mod+Shift+b bar mode invisible bar-1</code></pre>
</div></div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="multi_monitor">8. Multiple monitors</h2>
<div class="sectionbody">
<div class="paragraph"><p>As you can see in the goal list on the website, i3 was specifically developed
with support for multiple monitors in mind. This section will explain how to
handle multiple monitors.</p></div>
<div class="paragraph"><p>When you have only one monitor, things are simple. You usually start with
workspace 1 on your monitor and open new ones as you need them.</p></div>
<div class="paragraph"><p>When you have more than one monitor, each monitor will get an initial
workspace. The first monitor gets 1, the second gets 2 and a possible third
would get 3. When you switch to a workspace on a different monitor, i3 will
switch to that monitor and then switch to the workspace. This way, you don’t
need shortcuts to switch to a specific monitor, and you don’t need to remember
where you put which workspace. New workspaces will be opened on the currently
active monitor. It is not possible to have a monitor without a workspace.</p></div>
<div class="paragraph"><p>The idea of making workspaces global is based on the observation that most
users have a very limited set of workspaces on their additional monitors.
They are often used for a specific task (browser, shell) or for monitoring
several things (mail, IRC, syslog, …). Thus, using one workspace on one monitor
and "the rest" on the other monitors often makes sense. However, as you can
create an unlimited number of workspaces in i3 and tie them to specific
screens, you can have the "traditional" approach of having X workspaces per
screen by changing your configuration (using modes, for example).</p></div>
<div class="sect2">
<h3 id="_configuring_your_monitors">8.1. Configuring your monitors</h3>
<div class="paragraph"><p>To help you get going if you have never used multiple monitors before, here is
a short overview of the xrandr options which will probably be of interest to
you. It is always useful to get an overview of the current screen configuration.
Just run "xrandr" and you will get an output like the following:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>$ xrandr
Screen 0: minimum 320 x 200, current 1280 x 800, maximum 8192 x 8192
VGA1 disconnected (normal left inverted right x axis y axis)
LVDS1 connected 1280x800+0+0 (normal left inverted right x axis y axis) 261mm x 163mm
1280x800 60.0*+ 50.0
1024x768 85.0 75.0 70.1 60.0
832x624 74.6
800x600 85.1 72.2 75.0 60.3 56.2
640x480 85.0 72.8 75.0 59.9
720x400 85.0
640x400 85.1
640x350 85.1</code></pre>
</div></div>
<div class="paragraph"><p>Several things are important here: You can see that <code>LVDS1</code> is connected (of
course, it is the internal flat panel) but <code>VGA1</code> is not. If you have a monitor
connected to one of the ports but xrandr still says "disconnected", you should
check your cable, monitor or graphics driver.</p></div>
<div class="paragraph"><p>The maximum resolution you can see at the end of the first line is the maximum
combined resolution of your monitors. By default, it is usually too low and has
to be increased by editing <code>/etc/X11/xorg.conf</code>.</p></div>
<div class="paragraph"><p>So, say you connected VGA1 and want to use it as an additional screen:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>xrandr --output VGA1 --auto --left-of LVDS1</code></pre>
</div></div>
<div class="paragraph"><p>This command makes xrandr try to find the native resolution of the device
connected to <code>VGA1</code> and configures it to the left of your internal flat panel.
When running "xrandr" again, the output looks like this:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>$ xrandr
Screen 0: minimum 320 x 200, current 2560 x 1024, maximum 8192 x 8192
VGA1 connected 1280x1024+0+0 (normal left inverted right x axis y axis) 338mm x 270mm
1280x1024 60.0*+ 75.0
1280x960 60.0
1152x864 75.0
1024x768 75.1 70.1 60.0
832x624 74.6
800x600 72.2 75.0 60.3 56.2
640x480 72.8 75.0 66.7 60.0
720x400 70.1
LVDS1 connected 1280x800+1280+0 (normal left inverted right x axis y axis) 261mm x 163mm
1280x800 60.0*+ 50.0
1024x768 85.0 75.0 70.1 60.0
832x624 74.6
800x600 85.1 72.2 75.0 60.3 56.2
640x480 85.0 72.8 75.0 59.9
720x400 85.0
640x400 85.1
640x350 85.1</code></pre>
</div></div>
<div class="paragraph"><p>Please note that i3 uses exactly the same API as xrandr does, so it will see
only what you can see in xrandr.</p></div>
<div class="paragraph"><p>See also <a href="#presentations">[presentations]</a> for more examples of multi-monitor setups.</p></div>
</div>
<div class="sect2">
<h3 id="_interesting_configuration_for_multi_monitor_environments">8.2. Interesting configuration for multi-monitor environments</h3>
<div class="paragraph"><p>There are several things to configure in i3 which may be interesting if you
have more than one monitor:</p></div>
<div class="olist arabic"><ol class="arabic">
<li>
<p>
You can specify which workspace should be put on which screen. This
allows you to have a different set of workspaces when starting than just
1 for the first monitor, 2 for the second and so on. See
<a href="#workspace_screen">[workspace_screen]</a>.
</p>
</li>
<li>
<p>
If you want some applications to generally open on the bigger screen
(MPlayer, Firefox, …), you can assign them to a specific workspace, see
<a href="#assign_workspace">[assign_workspace]</a>.
</p>
</li>
<li>
<p>
If you have many workspaces on many monitors, it might get hard to keep
track of which window you put where. Thus, you can use vim-like marks to
quickly switch between windows. See <a href="#vim_like_marks">[vim_like_marks]</a>.
</p>
</li>
<li>
<p>
For information on how to move existing workspaces between monitors,
see <a href="#move_to_outputs">[move_to_outputs]</a>.
</p>
</li>
</ol></div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_i3_and_the_rest_of_your_software_world">9. i3 and the rest of your software world</h2>
<div class="sectionbody">
<div class="sect2">
<h3 id="_displaying_a_status_line">9.1. Displaying a status line</h3>
<div class="paragraph"><p>A very common thing amongst users of exotic window managers is a status line at
some corner of the screen. It is an often superior replacement to the widget
approach you have in the task bar of a traditional desktop environment.</p></div>
<div class="paragraph"><p>If you don’t already have your favorite way of generating such a status line
(self-written scripts, conky, …), then i3status is the recommended tool for
this task. It was written in C with the goal of using as few syscalls as
possible to reduce the time your CPU is woken up from sleep states. Because
i3status only spits out text, you need to combine it with some other tool, like
i3bar. See <a href="#status_command">[status_command]</a> for how to display i3status in i3bar.</p></div>
<div class="paragraph"><p>Regardless of which application you use to display the status line, you
want to make sure that it registers as a dock window using EWMH hints. i3 will
position the window either at the top or at the bottom of the screen, depending
on which hint the application sets. With i3bar, you can configure its position,
see <a href="#i3bar_position">[i3bar_position]</a>.</p></div>
</div>
<div class="sect2">
<h3 id="presentations">9.2. Giving presentations (multi-monitor)</h3>
<div class="paragraph"><p>When giving a presentation, you typically want the audience to see what you see
on your screen and then go through a series of slides (if the presentation is
simple). For more complex presentations, you might want to have some notes
which only you can see on your screen, while the audience can only see the
slides.</p></div>
<div class="sect3">
<h4 id="_case_1_everybody_gets_the_same_output">9.2.1. Case 1: everybody gets the same output</h4>
<div class="paragraph"><p>This is the simple case. You connect your computer to the video projector,
turn on both (computer and video projector) and configure your X server to
clone the internal flat panel of your computer to the video output:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>xrandr --output VGA1 --mode 1024x768 --same-as LVDS1</code></pre>
</div></div>
<div class="paragraph"><p>i3 will then use the lowest common subset of screen resolutions, the rest of
your screen will be left untouched (it will show the X background). So, in
our example, this would be 1024x768 (my notebook has 1280x800).</p></div>
</div>
<div class="sect3">
<h4 id="_case_2_you_can_see_more_than_your_audience">9.2.2. Case 2: you can see more than your audience</h4>
<div class="paragraph"><p>This case is a bit harder. First of all, you should configure the VGA output
somewhere near your internal flat panel, say right of it:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>xrandr --output VGA1 --mode 1024x768 --right-of LVDS1</code></pre>
</div></div>
<div class="paragraph"><p>Now, i3 will put a new workspace (depending on your settings) on the new screen
and you are in multi-monitor mode (see <a href="#multi_monitor">[multi_monitor]</a>).</p></div>
<div class="paragraph"><p>Because i3 is not a compositing window manager, there is no ability to
display a window on two screens at the same time. Instead, your presentation
software needs to do this job (that is, open a window on each screen).</p></div>
</div>
</div>
</div>
</div>
</div>
<div id="footnotes"><hr /></div>
<div id="footer">
<div id="footer-text">
Last updated
2017-09-24 19:21:26 CEST
</div>
</div>
</body>
</html>
|