[kwin] Move the doc for kcmkwin to kwin

* desktop (virtual desktops)
* kwincompositing
* kwindecoration
* kwinscreenedges
* kwintabbox
* windowspecific
* windowbehaviour

CCMAIL: kde-doc-english@kde.org

CMakeLists.txt

@@ -508,6 +508,7 @@ ecm_install_icons( ${ICON_INSTALL_DIR} )
 add_subdirectory(qml)
 add_subdirectory(autotests)
 add_subdirectory(tests)
+add_subdirectory(doc)
 
 configure_file(KWinDBusInterfaceConfig.cmake.in "${CMAKE_CURRENT_BINARY_DIR}/KWinDBusInterfaceConfig.cmake" @ONLY)
 set(CMAKECONFIG_INSTALL_DIR "${CMAKECONFIG_INSTALL_PREFIX}/KWinDBusInterface")

doc/CMakeLists.txt

@@ -0,0 +1,7 @@
+add_subdirectory(desktop)
+add_subdirectory(kwincompositing)
+add_subdirectory(kwindecoration)
+add_subdirectory(kwinscreenedges)
+add_subdirectory(kwintabbox)
+add_subdirectory(windowbehaviour)
+add_subdirectory(windowspecific)

doc/desktop/CMakeLists.txt

@@ -0,0 +1,2 @@
+########### install files ###############
+kdoctools_create_handbook(index.docbook INSTALL_DESTINATION ${HTML_INSTALL_DIR}/en SUBDIR kcontrol/desktop)

doc/desktop/index.docbook

@@ -0,0 +1,141 @@
+<?xml version="1.0" ?>
+<!DOCTYPE article PUBLIC "-//KDE//DTD DocBook XML V4.5-Based Variant V1.1//EN"
+"dtd/kdedbx45.dtd" [
+<!ENTITY % addindex "IGNORE">
+<!ENTITY % English "INCLUDE" > <!-- change language only here -->
+]>
+
+<article id="desktop" lang="&language;">
+<title>Virtual Desktops</title>
+<articleinfo>
+
+<authorgroup>
+<author>&Mike.McBride; &Mike.McBride.mail;</author>
+<author>&Jost.Schenck; &Jost.Schenck.mail;</author>
+<!-- TRANS:ROLES_OF_TRANSLATORS -->
+</authorgroup>
+
+<date>2013-06-02</date>
+<releaseinfo>4.11</releaseinfo>
+
+<keywordset>
+<keyword>KDE</keyword>
+<keyword>Systemsettings</keyword>
+<keyword>desktop</keyword>
+</keywordset>
+</articleinfo>
+
+<!--not in kde 4
+<sect1 id="desktop">
+
+<title>Desktop</title>
+
+<sect2 id="desktop-appearance">
+<title><guilabel>Appearance Tab</guilabel></title>
+
+<para>Here you can configure how icons on your desktop appear.</para>
+
+<variablelist>
+<varlistentry>
+<term><guilabel>Standard font:</guilabel></term>
+<listitem><para>This option can be used to change the typeface used on the
+desktop.  Simply select your typeface from the dropdown box.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Font size:</guilabel></term>
+<listitem><para>You can change the relative size of the text on the Desktop.
+</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Normal text color:</guilabel></term>
+<listitem><para>This option lets you select the color of normal (or
+unhighlighted) text.</para></listitem>
+</varlistentry>
+<varlistentry><term><guilabel>Text background color:</guilabel></term>
+<listitem><para>This option lets you select the background color of
+normal text.  If left unchecked, the text has a transparent
+background.  If selected, you can choose the color by pressing the button.
+</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Underline filenames:</guilabel></term>
+<listitem><para>Determines if file names are underlined on the
+Desktop.</para></listitem>
+</varlistentry>
+</variablelist>
+</sect2>
+-->
+<sect1 id="virtual-desktops">
+
+<title>Virtual Desktops</title>
+
+<sect2 id="desktop-number">
+<title><guilabel>Desktops</guilabel></title>
+
+<para>&kde; offers you the possibility to have several virtual
+desktops. In this tab you can configure the number of desktops, the number of rows in the <guilabel>Pager</guilabel> icon
+as well as their names. Just use the input box to adjust the number of
+desktops. You can assign names to the desktops by entering text into the
+text fields below.</para> 
+
+<para>Enable <guilabel>Different widgets for each desktop</guilabel> 
+to use independent widgets and wallpapers on each individual desktop.
+</para>
+<!--not in kde4
+<para>If you enable <guilabel>Mouse wheel over desktop switches
+desktop</guilabel> then scrolling the wheel over an empty space on the
+desktop will change to the next virtual desktop numerically, in the
+direction you scrolled (either up or down).</para>
+-->
+</sect2>
+
+<sect2 id="desktop-switching">
+<title><guilabel>Switching</guilabel></title>
+
+<variablelist>
+<varlistentry>
+<term><guilabel>Desktop navigation wraps around</guilabel></term>
+<listitem><para>Enable this option if you want keyboard or active desktop border navigation 
+beyond the edge of a desktop to take you to the opposite edge of the new desktop.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Desktop Effect Animation</guilabel></term>
+<listitem><para>Select <guilabel>No Animation</guilabel>, <guilabel>Slide</guilabel>, 
+<guilabel>Desktop Cube Animation</guilabel> or <guilabel>Fade Desktop</guilabel>
+from the drop down box. If the selected animation has settings options, click on the 
+tools icon on the right of the drop down box to launch a configuration dialog. 
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Desktop Switch On-Screen Display</guilabel></term>
+<listitem><para>Enable this option if you want to have an on-screen display for desktop switching. 
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Show desktop layout indicators</guilabel></term>
+<listitem><para>Enabling this option will show a small preview of the desktop layout 
+indicating the selected desktop.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Shortcuts</guilabel></term>
+<listitem><para>This section displays the configured shortcuts for switching the desktops 
+and allows you to edit them.
+</para></listitem>
+</varlistentry>
+
+</variablelist>
+
+<para>Scrolling the mouse wheel over an empty space on the
+desktop or on the <guilabel>Pager</guilabel> icon in the panel will change to the next 
+virtual desktop numerically, in the direction you scrolled (either up or down).</para>
+
+</sect2>
+</sect1>
+
+</article>

doc/kwincompositing/CMakeLists.txt

@@ -0,0 +1,2 @@
+########### install files ###############
+kdoctools_create_handbook(index.docbook INSTALL_DESTINATION ${HTML_INSTALL_DIR}/en SUBDIR kcontrol/kwincompositing)

doc/kwincompositing/index.docbook

@@ -0,0 +1,82 @@
+<?xml version="1.0" ?>
+<!DOCTYPE article PUBLIC "-//KDE//DTD DocBook XML V4.5-Based Variant V1.1//EN"
+"dtd/kdedbx45.dtd" [
+<!ENTITY % addindex "IGNORE">
+<!ENTITY % English "INCLUDE" > <!-- change language only here -->
+]>
+
+<article id="kwincompositing" lang="&language;">
+<articleinfo>
+
+<title>Desktop Effects</title>
+<authorgroup>
+<author>&Mike.McBride; &Mike.McBride.mail;</author>
+<!-- TRANS:ROLES_OF_TRANSLATORS -->
+</authorgroup>
+
+<date>2013-12-05</date>
+<releaseinfo>&kde; 4.12</releaseinfo>
+
+<keywordset>
+<keyword>KDE</keyword>
+<keyword>KControl</keyword>
+<keyword>desktop</keyword>
+<keyword>effects</keyword>
+</keywordset>
+</articleinfo>
+<sect1 id="desktop-effects">
+<title>Desktop Effects</title>
+
+<sect2 id="desktop-effects-intro">
+<title>Introduction</title>
+
+<para>This module is used to configure desktop effects
+for &kde;.</para>
+
+
+<para>This panel is divided into three tabs:  <guilabel>General</guilabel>, 
+<guilabel>All Effects</guilabel> and <guilabel>Advanced</guilabel>.</para>
+
+<sect3 id="desktop-effects-general">
+<title><guilabel>General</guilabel> tab</title>
+
+<para>At the top of this tab in the section <guilabel>Activation</guilabel> is a checkbox labeled <guilabel>Enable 
+desktop effects at startup</guilabel>. If there is no mark in front of this checkbox, then all 
+visual effects are disabled.</para>
+<para>All desktop effects can be turned on and off using the global shortcut 
+<keycombo action="simul">&Alt;&Shift;<keycap>F12</keycap></keycombo>.
+</para>
+<para>Below that section there are some settings for the simple desktop effects like 
+improved window management, various animations, effects for desktop switching and 
+the animation speed.</para>
+</sect3>
+
+<sect3 id="desktop-alleffects">
+<title><guilabel>All Effects</guilabel> tab</title>
+
+<para>The main part of this page is a list of all available effects grouped 
+by <guilabel>Accessibility</guilabel>, <guilabel>Appearance</guilabel>, 
+<guilabel>Candy</guilabel>, <guilabel>Focus</guilabel>, <guilabel>Tools</guilabel> 
+and <guilabel>Window Management</guilabel>.
+Use the incremental search bar above the list window to find items in the list.</para>
+
+<para>Check an effect in the list to enable it. Display the <guilabel>About</guilabel> 
+dialog by clicking the info button at the right side of the list item. 
+Some effects have settings options, in this case there is a tool button 
+at the left of the info button. Click it to open a configuration dialog.</para>
+</sect3>
+
+<sect3 id="desktop-advanced">
+<title><guilabel>Advanced</guilabel> tab</title>
+
+<para>On this tab you can select a <guilabel>Compositing type</guilabel> and the <guilabel>Qt graphics system</guilabel>.
+In the next two sections you can configure <guilabel>General Options</guilabel> and <guilabel>OpenGL Options</guilabel>.
+</para>
+</sect3>
+
+
+</sect2>
+
+</sect1>
+
+</article>

doc/kwindecoration/CMakeLists.txt

@@ -0,0 +1,2 @@
+########### install files ###############
+kdoctools_create_handbook(index.docbook INSTALL_DESTINATION ${HTML_INSTALL_DIR}/en SUBDIR kcontrol/kwindecoration)

doc/kwindecoration/index.docbook

@@ -0,0 +1,150 @@
+<?xml version="1.0" ?>
+<!DOCTYPE article PUBLIC "-//KDE//DTD DocBook XML V4.5-Based Variant V1.1//EN"
+"dtd/kdedbx45.dtd" [
+<!ENTITY % addindex "IGNORE">
+<!ENTITY % English "INCLUDE" > <!-- change language only here -->
+]>
+
+<article id="kwindecoration" lang="&language;">
+<articleinfo>
+<title>Window Decorations</title>
+<authorgroup>
+<author>&Rik.Hemsley; &Rik.Hemsley.mail;</author>
+<author>&Anne-Marie.Mahfouf; &Anne-Marie.Mahfouf.mail;</author>
+<!-- TRANS:ROLES_OF_TRANSLATORS -->
+</authorgroup>
+
+<date>2013-12-05</date>
+<releaseinfo>&kde; 4.12</releaseinfo>
+
+<keywordset>
+<keyword>KDE</keyword>
+<keyword>Systemsettings</keyword>
+<keyword>kwin</keyword>
+<keyword>window</keyword>
+<keyword>border</keyword>
+<keyword>theme</keyword>
+<keyword>style</keyword>
+</keywordset>
+</articleinfo>
+<sect1 id="window-deco">
+<title>Window Decoration</title>
+
+<para>This module allows you to select a style for the buttons and borders around
+windows.</para>
+
+<sect2>
+<title>Window Decorations</title>
+
+<para>
+<screenshot>
+<screeninfo>Window Decoration Configuration Module</screeninfo>
+  <mediaobject>
+    <imageobject>
+      <imagedata fileref="main.png" format="PNG"/>
+    </imageobject>
+    <textobject>
+      <phrase>Window Decoration Configuration Module</phrase>
+    </textobject>
+  </mediaobject>
+</screenshot>
+</para>
+
+<para>Choose a window decoration style from the preview list, using the 
+search field at the top of the screen.</para>
+
+<para>The &kde; default window decoration is called "Oxygen".</para>
+
+<para>Each style has a different look, but also a different
+<quote>feel</quote>. Some have (sometimes invisible)
+<quote>resize</quote> borders all around the edge, which make resizing
+easier but moving more difficult. Some have no borders on certain
+edges. One (<quote>BII</quote>) even has a dynamically sized and
+positioned title element.</para>
+
+<para>You are encouraged to experiment with the different styles until
+you find one which best suits your pattern of work.</para>
+
+<para>Below the preview pane you find three buttons to open configuration dialogs
+for decoration and buttons of the selected style or to download additional
+styles.</para>
+
+</sect2>
+
+<sect2>
+<title>Decorations</title>
+
+<para>In this dialog you can change the decoration of the window. 
+
+The available options depend on the selected style.
+</para>
+<para>
+<screenshot>
+<screeninfo>Oxygen Decoration Options</screeninfo>
+  <mediaobject>
+    <imageobject>
+      <imagedata fileref="decoration.png" format="PNG"/>
+    </imageobject>
+    <textobject>
+      <phrase>Oxygen Decoration Options</phrase>
+    </textobject>
+  </mediaobject>
+</screenshot>
+</para>
+</sect2>
+
+<sect2>
+<title>Buttons</title>
+
+<para>This dialog allows you to customize the buttons location on the titlebar. You can move Close button to the left for example. Check the <guilabel>Use custom titlebar button positions</guilabel> option in order to customize your titlebars. Then use the &kde; titlebar below and the buttons on its left and right to rearrange them as you want them.
+</para>
+
+<para>
+<screenshot>
+<screeninfo>Window Decoration Configuration Module</screeninfo>
+  <mediaobject>
+    <imageobject>
+      <imagedata fileref="buttons.png" format="PNG"/>
+    </imageobject>
+    <textobject>
+      <phrase>Window Decoration Configuration Module</phrase>
+    </textobject>
+  </mediaobject>
+</screenshot>
+</para>
+
+<para> By default, <guilabel>Show window button tooltips</guilabel> is checked and tooltips are shown.
+</para>
+
+<para>This page has instructions directly on it - just drag around the
+buttons until you have the order that makes you comfortable.</para>
+
+<note>
+<para>Not all the window decorations are able to comply with your custom
+set button order.  The ones that cannot are being converted, but at the
+time of this release they have not been all been changed.</para>
+</note>
+
+<para>Apart from choosing the window decoration itself, you can choose
+here two further options: if there should be a tooltip while you hover
+your mouse over a window decoration button, and if the window
+decoration should attempt to use a custom set button order.</para>
+
+<tip>
+<para>The tooltips can be quite useful if you have set a custom button
+order, and then changed to an unfamiliar window decoration.</para>
+</tip>
+
+<tip>
+<para>For accessibility purposes, some window decorations support
+extra wide borders.  If this is available, you can also choose a
+border size here.  These large borders are easier to see for low
+vision users, and easier to grab for people with limited mobility or
+difficulty using a mouse.</para>
+</tip>
+
+</sect2>
+
+</sect1>
+
+</article>

doc/kwinscreenedges/CMakeLists.txt

@@ -0,0 +1,2 @@
+########### install files ###############
+kdoctools_create_handbook(index.docbook INSTALL_DESTINATION ${HTML_INSTALL_DIR}/en SUBDIR kcontrol/kwinscreenedges)

doc/kwinscreenedges/index.docbook

@@ -0,0 +1,50 @@
+<?xml version="1.0" ?>
+<!DOCTYPE article PUBLIC "-//KDE//DTD DocBook XML V4.5-Based Variant V1.1//EN"
+"dtd/kdedbx45.dtd" [
+<!ENTITY % addindex "IGNORE">
+<!ENTITY % English "INCLUDE" > <!-- change language only here -->
+]>
+
+<article id="kwinscreenedges" lang="&language;">
+<articleinfo>
+
+<title>Screen Edges</title>
+<authorgroup>
+<author>&Mike.McBride; &Mike.McBride.mail;</author>
+<!-- TRANS:ROLES_OF_TRANSLATORS -->
+</authorgroup>
+
+<date>2010-10-28</date>
+<releaseinfo>&kde; 4.5</releaseinfo>
+
+<keywordset>
+<keyword>KDE</keyword>
+<keyword>Systemsettings</keyword>
+<keyword>desktop</keyword>
+<keyword>effects</keyword>
+</keywordset>
+</articleinfo>
+
+<para>Active screen edges allow you to activate effects by pushing your mouse 
+cursor against the edge of the screen. Here you can configure which effect 
+will get activated on each edge and corner of the screen.
+</para>
+
+<para>Click with any mouse button onto a square and select an effect 
+in the context menu. Edges with a black square have already an attached effect, 
+a grey colored square indicates that no effect is selected for this edge.</para>
+
+<para>The number of accessible items in the context menu depends on the settings in the module
+<ulink url="help:/kcontrol/kwincompositing/index.html">
+<guilabel>Desktop Effects</guilabel></ulink> in the <guilabel>Workspace Appearance and Behavior</guilabel>
+category. Select <guilabel>Enable desktop 
+effects</guilabel> to activate compositing, select the compositing type 
+<guilabel>OpenGL</guilabel>, and then choose your favorite effects on the 
+<guilabel>All Effects</guilabel> tab from the <guilabel>Windows Management</guilabel> 
+group. This activates the corresponding items in the context menu.</para>
+
+<para>If you are looking for the setting to enable switching of desktops by 
+pushing your mouse cursor against the edge of the screen choose one of the <guilabel>Present 
+Windows</guilabel> effects from the context menu.</para>
+
+</article>

doc/kwintabbox/CMakeLists.txt

@@ -0,0 +1,2 @@
+########### install files ###############
+kdoctools_create_handbook(index.docbook INSTALL_DESTINATION ${HTML_INSTALL_DIR}/en SUBDIR kcontrol/kwintabbox)

doc/kwintabbox/index.docbook

@@ -0,0 +1,99 @@
+<?xml version="1.0" ?>
+<!DOCTYPE article PUBLIC "-//KDE//DTD DocBook XML V4.5-Based Variant V1.1//EN"
+"dtd/kdedbx45.dtd" [
+  <!ENTITY % addindex "IGNORE">
+  <!ENTITY % English "INCLUDE">
+]>
+<article id="kwintabbox" lang="&language;">
+<articleinfo>
+<title>Task Switcher</title>
+<authorgroup>
+<author>&Martin.Graesslin;&Martin.Graesslin.mail;</author>
+<!-- TRANS:ROLES_OF_TRANSLATORS -->
+</authorgroup>
+
+<date>2010-10-28</date>
+<releaseinfo>&kde; 4.5</releaseinfo>
+
+<keywordset>
+<keyword>KDE</keyword>
+<keyword>System Settings</keyword>
+<keyword>desktop</keyword>
+<keyword>window</keyword>
+<keyword>navigation</keyword>
+</keywordset>
+</articleinfo>
+
+<sect1 id="windows-navigating">
+<title>Navigating through Windows</title>
+
+<para>This module offers the possibility to configure the behaviour for Navigating through windows often referred to as <keycombo>&Alt;&Tab;</keycombo>. There are two independent sets of effects which can have different settings. For each of this sets  there is an own tab (<guilabel>Main</guilabel> and <guilabel>Alternative</guilabel>) in this module. 
+</para>
+
+<note><para>
+The first set of effects on the <guilabel>Main</guilabel> tab has predefined shortcuts. If you want to use the second set of effects on the <guilabel>Alternative</guilabel> tab, you have to set a shortcut for these effects in the Shortcut Editor manually.</para></note>
+
+<para>The following documentation of options applies to the general settings and the alternative settings as well.</para>
+
+<sect2 id="sort-order">
+<title>List windows and Sort order</title>
+<para>You can configure which windows should be shown in the list initiated by pressing <keycombo>&Alt;&Tab;</keycombo> (predefined for the settings on the <guilabel>Main</guilabel> tab) or the user defined shortcut for the alternative settings. So it is possible to only show windows on the current desktop or windows from all desktops. It is also possible to influence the sort order, you can either use a sort order based on the last usage of the windows or the stacking order of the windows.
+</para>
+<para>If you check <guilabel>Include desktop</guilabel> an entry for the desktop will be added to list with application windows. Then you can select this entry in the list to minimize all windows.</para>
+</sect2>
+
+<sect2 id="desktop-effects">
+<title>Desktop Effects</title>
+<para>
+There are several effects which can be used instead of the normal window list when compositing is enabled. By default the <guilabel>Box Switch</guilabel> effect is used. This effect displays a small thumbnail of each window inside a box and the currently selected window is highlighted.
+</para>
+<para>
+The <guilabel>Present Windows</guilabel> effect arranges the windows in a regular grid and by that provides thumbnails in the best possible size. This effect can be used for navigating through windows without <keycombo>&Alt;&Tab;</keycombo> as well, if it is selected as screen edge action in the &systemsettings; module <ulink url="help:/kcontrol/kwinscreenedges/index.html">
+<guilabel>Screen Edges</guilabel></ulink>. This effect provides additional setting options and shortcuts in a dialog opened by clicking on the tools icon beside the drop down box.
+</para>
+<para>
+<guilabel>Cover Switch</guilabel> and <guilabel>Flip Switch</guilabel> effect are more fancy effects which require OpenGL. <guilabel>Cover Switch</guilabel> displays the windows in a gallery with a large thumbnail of the currently selected window in the center of the screen while all other windows are rotated on the left and right. <guilabel>Flip Switch</guilabel> displays all windows on a 3D stack. The selected window is on top of the stack and navigating through the windows will move the stack so that the new selected window is on the top.
+</para>
+<para>
+If the effect provides additional settings the configure button will be activated. By clicking this button a configuration dialog will be shown.
+</para>
+<note><para>
+When compositing is not active or gets suspended the normal window list will be shown. There is no loss in functionality if an effect is selected and compositing is not active.</para></note>
+</sect2>
+
+<sect2 id="lists">
+<title>Display list</title>
+<para>
+When no effect is used an outline illustrating position and size of the selected window can be shown while switching. The list can be combined with the <guilabel>Highlight selected windows</guilabel> effect when compositing is active. This effect will highlight the currently selected window by fading out all other windows.
+</para>
+<para>
+If you want to configure the layout of one item you can use the dialog which opens by clicking <guibutton>Configure Layout</guibutton>. There are several predefined layouts which provide an informative or compact view, small or large icons and window title only. You can change the way the items are laid out: horizontal, vertical or in a tabular layout.
+</para>
+<para>
+There is an additional configuration group for an optional view of the selected item. It is possible to place this view next to the list with all items. This is useful if you use an icon only layout mode and want to see the name of the current selected window as well.
+</para>
+</sect2>
+
+<sect2 id="shortcuts">
+<title>Shortcuts</title>
+<para>
+The shortcut editor provides the configuration interface for the keyboard shortcuts for navigating through windows. Each of the two possible sets of effects has two shortcuts: one for the forward direction and one for the reverse direction. Please note that the window list can only be shown if you select a shortcut with a keyboard modifier such as the &Alt; or &Ctrl; key. This modifier has to be hold while switching. Selecting a shortcut without a modifier key can break the behaviour of navigating through windows.
+</para>
+</sect2>
+
+</sect1>
+</article>
+
+<!--
+Local Variables:
+mode: xml
+sgml-minimize-attributes:nil
+sgml-general-insert-case:lower
+sgml-indent-step:0
+sgml-indent-data:nil
+End:
+
+vim:tabstop=2:shiftwidth=2:expandtab
+kate: space-indent on; indent-width 2; tab-width 2; indent-mode none;
+-->
+

doc/windowbehaviour/CMakeLists.txt

@@ -0,0 +1,2 @@
+########### install files ###############
+kdoctools_create_handbook(index.docbook INSTALL_DESTINATION ${HTML_INSTALL_DIR}/en SUBDIR kcontrol/windowbehaviour)

doc/windowbehaviour/index.docbook

@@ -0,0 +1,676 @@
+<?xml version="1.0" ?>
+<!DOCTYPE article PUBLIC "-//KDE//DTD DocBook XML V4.5-Based Variant V1.1//EN"
+"dtd/kdedbx45.dtd" [
+<!ENTITY % addindex "IGNORE">
+<!ENTITY % English "INCLUDE" > <!-- change language only here -->
+]>
+
+<!--copy from r308626 Tue May 4 17:11:51 2004 UTC -->
+
+<article id="windowbehaviour" lang="&language;">
+<articleinfo>
+<title>Window Behavior</title>
+<authorgroup>
+<author>&Mike.McBride; &Mike.McBride.mail;</author>
+<author>&Jost.Schenck; &Jost.Schenck.mail;</author>
+<!-- TRANS:ROLES_OF_TRANSLATORS -->
+</authorgroup>
+
+<date>2013-11-15</date>
+<releaseinfo>&kde; 4.12</releaseinfo>
+
+<keywordset>
+<keyword>KDE</keyword>
+<keyword>KControl</keyword>
+<keyword>system settings</keyword>
+<keyword>actions</keyword>
+<keyword>window placement</keyword>
+<keyword>window size</keyword>
+</keywordset>
+</articleinfo>
+<sect1 id="window-behavior">
+<title>Window Behavior</title>
+
+<para> In the upper part of this control module you can see several
+tabs: <guilabel>Focus</guilabel>, <guilabel>Titlebar Actions</guilabel>,
+<guilabel>Window Actions</guilabel>, <guilabel>Moving</guilabel> and
+<guilabel>Advanced</guilabel>. In the
+<guilabel>Focus</guilabel> panel you can configure how windows gain or
+lose focus, &ie; become active or inactive.  Using
+<guilabel>Titlebar Actions</guilabel> and <guilabel>Window Actions</guilabel>
+you can configure how titlebars and windows react to
+mouse clicks. <guilabel>Moving</guilabel> allows you to configure how
+windows move and place themselves when started.  The
+<guilabel>Advanced</guilabel> options cover some specialized options
+like <quote>window tabbing</quote> and <quote>window
+shading</quote>.
+</para>
+
+<note>
+<para>
+Please note that the configuration in this module will not take effect
+if you do not use &kde;'s native window manager, &kwin;. If you do use a
+different window manager, please refer to its documentation for how to
+customize window behavior.
+</para>
+</note>
+
+<sect2 id="action-focus">
+<title>Focus</title>
+
+<para>
+The <quote>focus</quote> of the desktop refers to the window which the
+user is currently working on. The window with focus is often referred to
+as the <quote>active window</quote>.
+</para>
+
+<para>Focus does not necessarily mean the window is the one at the
+front &mdash; this is referred to as <quote>raised</quote>, and
+although this is configured here as well, focus and raising of windows
+are configured independently.</para>
+
+<sect3 id="action-focus-focuspolicy">
+<title>Focus Policy</title>
+
+<para>
+There are six methods &kde; can use to determine the current focus:
+</para>
+
+<variablelist>
+<varlistentry>
+<term><guilabel>Click To Focus</guilabel></term>
+<listitem>
+<para>
+A window becomes active when you click into it.
+This behaviour is common on other operating systems and likely what you want.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Click To Focus - Mouse Precedence</guilabel></term>
+<listitem>
+<para>
+This is mostly the same as <guilabel>Click To Focus</guilabel>.
+If an active window has to be chosen by the system
+(&eg; because the currently active one was closed) 
+the window under the mouse is the preferred candidate.
+Unusual, but possible variant of <guilabel>Click To Focus</guilabel>.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Focus Follows Mouse</guilabel></term>
+<listitem>
+<para>
+Moving the mouse pointer actively over a normal window activates it. New
+windows such as the mini command line invoked with
+<keycombo action="simul">&Alt;<keycap>F2</keycap></keycombo> will receive the focus,
+without you having to point the mouse at them explicitly.
+&eg; windows randomly appearing under the mouse will not gain the focus.
+Focus stealing prevention takes place as usual.
+Think as <guilabel>Click To Focus</guilabel> just without having to actually click.
+</para>
+
+<para>
+In other window managers, this is sometimes known as <quote>Sloppy focus
+follows mouse</quote>.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Focus Follows Mouse - Mouse Precedence</guilabel></term>
+<listitem>
+<para>
+This is mostly the same as <guilabel>Focus Follows Mouse</guilabel>.
+If an active window has to be chosen by the system
+(&eg; because the currently active one was closed) 
+the window under the mouse is the preferred candidate.
+Choose this, if you want a hover controlled focus.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Focus Under Mouse</guilabel></term>
+<listitem>
+<para>
+The window that happens to be under the mouse pointer becomes active.  If
+the mouse is not over a window (for instance, it's on the desktop) the last
+window that was under the mouse has focus.  New windows such as the mini
+command line invoked with <keycombo action="simul">&Alt;<keycap>F2</keycap></keycombo> will
+not receive the focus, you must move the mouse over them to type.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Focus Strictly Under Mouse</guilabel></term>
+<listitem>
+<para>Similar to <guilabel>Focus Under Mouse</guilabel>, but even more
+strict with its interpretation.  Only the window under the mouse pointer is
+active.  If the mouse pointer is not over a window, no window has focus.
+New windows such as the mini command line invoked with
+<keycombo action="simul">&Alt;<keycap>F2</keycap></keycombo> will not receive the focus,
+you must move the mouse over them to type. 
+</para>
+
+</listitem>
+</varlistentry>
+</variablelist>
+
+<note><para>Note that <guilabel>Focus Under Mouse</guilabel> and
+<guilabel>Focus Strictly Under Mouse</guilabel> prevent certain
+features, such as <guilabel>Focus stealing prevention</guilabel> and the 
+<keycombo action="simul">&Alt;&Tab;</keycombo>
+walk-through-windows dialog, from working properly.</para>
+</note>
+
+</sect3>
+
+<sect3 id="action-focus-focusstealin">
+<title>Focus stealing prevention level</title>
+
+<para>This option specifies how much KWin will try to prevent unwanted focus 
+stealing caused by unexpected activation of new windows.</para> 
+
+<variablelist>
+<varlistentry>
+<term><guilabel>None</guilabel></term>
+<listitem><para>Prevention is turned off and new windows always become activated.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Low</guilabel></term>
+<listitem><para>Prevention is enabled; when some window does not have support 
+for the underlying mechanism and KWin cannot reliably decide whether to activate 
+the window or not, it will be activated. This setting may have both worse and better 
+results than the medium level, depending on the applications.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Medium</guilabel></term>
+<listitem><para>Prevention is enabled.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>High</guilabel></term>
+<listitem><para>New windows get activated only 
+if no window is currently active or if they belong to the currently active 
+application. This setting is probably not really usable when not using mouse 
+focus policy.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Extreme</guilabel></term>
+<listitem><para>All windows must be explicitly activated by the user.</para></listitem>
+</varlistentry>
+</variablelist>
+<para>Windows that are prevented from stealing focus are marked as demanding 
+attention, which by default means their taskbar entry will be highlighted. 
+This can be changed in the Notifications control module.</para>
+</sect3>
+  
+<sect3 id="action-focus-raisingwindow">
+<title>Raising window</title>
+<para>
+Once you have determined the focus policy, there are the window
+raising options.
+</para>
+
+<para>
+By placing a mark in front of <guilabel>Raise on hover, delayed by</guilabel>, &kde; can
+bring a window to the front if the mouse is over that window for a
+specified period of time. You can determine the delay for this option by using the spin box control.
+</para>
+
+<tip>
+<para>
+Setting the delay too short will cause a rapid fire changing of
+windows, which can be quite distracting.  Most people will like a delay
+of 100-300 ms.  This is responsive, but it will let you slide over the
+corners of a window on your way to your destination without bringing
+that window to the front.  
+</para>
+</tip>
+
+<para>
+If you do not use auto raise, make sure the
+<guilabel>Click raises active window</guilabel> option has a mark in front of it.  You
+will not be happy with both auto raise and
+<guilabel>Click raise active window</guilabel> disabled, the net effect is that
+windows are not raised at all.
+</para>
+
+</sect3>
+
+</sect2>
+
+<sect2 id="titlebar-actions">
+<title>Titlebar Actions</title>
+
+<para>
+In this panel you can configure what happens to windows when a mousebutton is
+clicked on their titlebars.
+</para>
+
+<sect3 id="action-actions-sec1">
+<title>Titlebar double-click</title>
+
+<para>
+In this drop down box you can select either
+<guilabel>Shade</guilabel>, several variations of
+<guilabel>Maximize</guilabel> or <guilabel>Lower</guilabel>.
+</para>
+
+<para>
+Selecting <guilabel>Maximize</guilabel> causes &kde; to maximize the
+window whenever you doubleclick on the titlebar. You can further
+choose to maximize windows only horizontally or only
+vertically.</para>
+
+<para><guilabel>Shade</guilabel>, on the other hand, causes the window to be
+reduced to simply the titlebar.  Double clicking on the titlebar again,
+restores the window to its normal size.
+</para>
+
+<!--FIXME <guilabel>Wheel event</guilabel> missing -->
+
+<tip>
+<para>
+You can have windows automatically unshade when you simply place the
+mouse over their shaded titlebar. Just check the <guilabel>Enable
+hover</guilabel> check box in the <guilabel>Advanced</guilabel> tab of
+this module.  This is a great way to reclaim desktop space when you are
+cutting and pasting between a lot of windows, for example.
+</para>
+</tip>
+
+</sect3>
+
+<sect3 id="action-actions-sec2">
+<title><guilabel>Titlebar &amp; Frame</guilabel></title>
+
+<para>
+This section allows you to determine what happens when you single click
+on the titlebar or frame of a window.  Notice that you can have
+different actions associated with the same click depending on whether
+the window is active or not.
+</para>
+
+<para> For each combination of mousebuttons, Active and
+Inactive, you can select the most appropriate choice.  The actions are
+as follows: </para>
+
+<variablelist>
+<varlistentry>
+<term><guilabel>Activate</guilabel></term>
+<listitem>
+<para>
+Make this window active.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Lower</guilabel></term>
+<listitem>
+<para>
+Will move this window to the bottom of the display.  This will get the
+window out of the way.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Nothing</guilabel></term>
+<listitem>
+<para>
+Just like it says.  Nothing happens.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Operations Menu</guilabel></term>
+<listitem>
+<para>
+Will bring up a small submenu, where you can choose window related
+commands (&ie; Maximize, Minimize, Close, &etc;).
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Raise</guilabel></term>
+<listitem>
+<para>
+Will bring the window to the top of the display.  All other windows
+which overlap with this one, will be hidden <quote>below</quote> it.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Toggle Raise &amp; Lower</guilabel></term>
+<listitem>
+<para>
+This will raise windows which are not on top, and lower windows which
+are already on top.
+</para>
+</listitem>
+</varlistentry>
+<!--FIXME missing:
+Shade, Close, Start Window Tab Drag
+-->
+</variablelist>
+</sect3>
+
+<sect3 id="action-actions-maximize-button">
+<title><guilabel>Maximize Button</guilabel></title>
+<para>
+This section allows you to determine the behavior of the three mouse buttons 
+onto the maximize button. You have the choice between vertical only, horizontal 
+only or both directions.
+</para>
+</sect3>
+
+</sect2>
+
+<sect2 id="window-actions">
+<title>Window Actions</title>
+
+<sect3 id="action-actions-sec3">
+<title><guilabel>Inactive Inner Window</guilabel></title>
+
+<para>
+This part of the module, allows you to configure what happens when you
+click on an inactive window, with any of the three mouse buttons or use
+the mouse wheel.
+</para>
+
+<para>
+Your choices are as follows:
+</para>
+
+<variablelist>
+<varlistentry>
+<term><guilabel>Activate, Raise &amp; Pass Click</guilabel></term>
+<listitem>
+<para>
+This makes the clicked window active, raises it to the top of the
+display, and passes a mouse click to the application within the window.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Activate &amp; Pass Click</guilabel></term>
+<listitem>
+<para>
+This makes the clicked window active and passes a mouse click to the
+application within the window.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Activate</guilabel></term>
+<listitem>
+<para>
+This simply makes the clicked window active. The mouse click is not
+passed on to the application within the window.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Activate &amp; Raise</guilabel></term>
+<listitem>
+<para>
+This makes the clicked window active and raises the window to the top of
+the display. The mouse click is not passed on to the application within
+the window.
+</para>
+</listitem>
+</varlistentry>
+
+<!--FIXME Mouse wheel Scroll, Activate & Scroll, Activate, Raise & Scroll-->
+
+</variablelist>
+</sect3>
+
+<sect3 id="action-actions-sec4">
+<title><guilabel>Inner Window, Titlebar &amp; Frame</guilabel></title>
+
+<para>
+This bottom section, allows you to configure additional actions, when
+a modifier key (by default &Alt;) is pressed, and a mouse click is
+made on a window.</para>
+
+<para>
+Once again, you can select different actions for
+<mousebutton>Left</mousebutton>, <mousebutton>Middle</mousebutton> and
+<mousebutton>Right</mousebutton> button clicks and the <guilabel>Mouse 
+wheel</guilabel>.
+</para>
+
+<para>Your choices are:</para>
+
+<variablelist>
+<varlistentry>
+<term><guilabel>Lower</guilabel></term>
+<listitem>
+<para>
+Will move this window to the bottom of the display.  This will get the
+window out of the way.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Move</guilabel></term>
+<listitem>
+<para>
+Allows you to drag the selected window around the desktop.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Nothing</guilabel></term>
+<listitem>
+<para>
+Just like it says.  Nothing happens.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Raise</guilabel></term>
+<listitem>
+<para>
+Will bring the window to the top of the display.  All other windows
+which overlap with this one, will be hidden <quote>below</quote> it.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Resize</guilabel></term>
+<listitem>
+<para>
+Allows you to change the size of the selected window.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Toggle Raise &amp; Lower</guilabel></term>
+<listitem>
+<para>
+This will raise windows which are not on top, and lower windows which
+are already on top.
+</para>
+</listitem>
+</varlistentry>
+</variablelist>
+<!-- FIXME missing:
+Activate, Raise &amp; Move
+Minimize
+Increase Opacity + Decrease Opacity
+-->
+<!--FIXME
+Mouse Wheel has different choices:
+Raise/Lower, Shade/Unshade, Maximize/Restore, Keep Above/Below, 
+Move to Previous/Next Desktop, Change Opacity, Switch to Window Tab to the Left/Right
+Nothing
+-->
+
+</sect3>
+
+</sect2>
+
+<sect2 id="action-moving">
+<title>Moving</title>
+
+<sect3>
+<title><guilabel>Windows</guilabel></title>
+<para>
+The options here determine how windows appear on screen when you
+are moving them.</para>
+
+<variablelist>
+<varlistentry>
+<term><guilabel>Display window geometry when moving or resizing</guilabel></term>
+<listitem>
+<para>Enable this option if you want a window's geometry to be displayed 
+while it is being moved or resized. The window position relative to the top-left 
+corner of the screen is displayed together with its size.</para>
+</listitem>
+</varlistentry>
+</variablelist>
+
+</sect3>
+
+<sect3>
+<title><guilabel>Snap Zones</guilabel></title>
+
+<para>The rest of this page allows you to configure the <guilabel>Snap
+Zones</guilabel>.  These are like a magnetic field along the side of
+the desktop and each window, which will make windows snap alongside
+when moved near.</para>
+
+<variablelist>
+<varlistentry>
+<term><guilabel>Border snap zone:</guilabel></term>
+<listitem>
+
+<para>Here you can set the snap zone for screen borders.  Moving a
+window within the configured distance will make it snap to the edge of
+the desktop.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Window snap zone:</guilabel></term>
+<listitem>
+
+<para>Here you can set the snap zone for windows.  As with screen
+borders, moving a window near to another will make it snap to the edge
+as if the windows were magnetized.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Center snap zone:</guilabel></term>
+<listitem>
+
+<para>Here you can set the snap zone for the screen center, &ie; the 
+<quote>strength</quote> of the magnetic field which will make windows snap 
+to the center of the screen when moved near it.</para>
+</listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><guilabel>Snap windows only when overlapping</guilabel></term>
+<listitem>
+
+<para>If checked, windows will not snap together if they are only near
+each other, they must be overlapping, by the configured amount or
+less.</para>
+</listitem>
+</varlistentry>
+</variablelist>
+</sect3>
+
+</sect2>
+
+<sect2 id="action-advanced">
+<title>Advanced</title>
+
+<para>
+In the <guilabel>Advanced</guilabel> panel you can do more advanced fine
+tuning to the window behavior.
+</para>
+
+<variablelist>
+<title>Shading</title>
+
+<varlistentry>
+<term><guilabel>Enable hover</guilabel></term>
+<listitem>
+<para>
+If this option is enabled, a shaded window will un-shade automatically
+when the mouse pointer has been over the titlebar for some time. Use
+the spinbox to configure the delay un-shading.
+</para>
+</listitem>
+</varlistentry>
+</variablelist>
+
+<variablelist>
+<title>Window Tabbing</title>
+
+<varlistentry>
+<term><guilabel>Automatically group similar windows</guilabel></term>
+<listitem><para>When turned on attempt to automatically detect when a newly opened window is 
+related to an existing one and place them in the same window group.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Switch to automatically grouped windows immediately</guilabel></term>
+<listitem><para>When turned on immediately switch to any new window tabs that were 
+automatically added to the current group.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Placement</guilabel></term>
+<listitem><para>The placement policy determines where a new window will appear
+on the desktop.  <guilabel>Smart</guilabel> will try to achieve a minimum
+overlap of windows, <guilabel>Cascade</guilabel> will cascade the
+windows, and <guilabel>Random</guilabel> will use a random
+position.  <guilabel>Centered</guilabel> will open all new windows in
+the center of the screen, and <guilabel>Zero-Cornered</guilabel> will
+open all windows with their top left corner in the top left corner of
+the screen.</para></listitem>
+</varlistentry>
+
+</variablelist>
+
+<variablelist>
+<title>Special Window</title>
+<varlistentry>
+<term><guilabel>Hide utility windows for inactive applications</guilabel></term>
+<listitem><para>When turned on, utility windows (tool windows, torn-off menus,...) of 
+inactive applications will be hidden and will be shown only when the 
+application becomes active. Note that applications have to mark the windows 
+with the proper window type for this feature to work.</para></listitem>
+</varlistentry>
+
+</variablelist>
+
+</sect2>
+
+</sect1>
+
+</article>

doc/windowspecific/CMakeLists.txt

@@ -0,0 +1,2 @@
+########### install files ###############
+kdoctools_create_handbook(index.docbook INSTALL_DESTINATION ${HTML_INSTALL_DIR}/en SUBDIR kcontrol/windowspecific)