Task Switcher doc update

[Yuri Chornoivan]

середа, 23 грудня 2020 р. 05:43:59 EET Peter Wilding написано:
> Hello, this is my first attempt at contributing to the documentation, so
> please redirect me as needed.

Hi,

Yes, this is the right place. :)

> According to the documentation on how to
> contribute documentation, the easiest way to get started is to send a
> plaintext update to this list, so that's what I'm doing!  I would be
> happy to contribute directly via git, but I could use some help finding
> the repo that contains this particular set of documentation.

It is here.

https://invent.kde.org/plasma/kwin/-/blob/master/doc/kwintabbox/index.docbook

Actually, you can edit it just in place then create a merge request.

Just if you want to do it by yourself,

1. Register on gitlab (the "Sign in" button in the top right corner of the 
page).
2. Click on the "Edit" button and create your own fork of the repo.
3. Implement your vision of the manual.
4. Create a merge request with some appropriate title.
 
> For the Task Switcher (System Settings -> Task Switcher), I found the
> existing documentation to be a bit sparse.  After a lot of trial and
> error I have a pretty good understanding of how all the Task Switcher
> settings work, and so I wrote up new documentation to reflect this
> information. 

Many thanks for your work.

> The new text is below -- please let me know what next
> steps would be.

It depends on what is the best way for you.

1. I can create a merge request for your work.

2. You can adopt the docs yourself and create a merge request to discuss 
(please remove the second "way" in "way way" then).

So what is your choice? ;)

> Thank you all!
> 
> -Pete

Thanks again for your contribution, best regards and Merry Christmas,
Yuri

> ---------------------
> The Task Switcher allows the user to easily switch between currently
> open windows using the keyboard.  It is highly configurable, and allows
> the user to control its behavior, visual appearance, keyboard shortcuts,
> and window filtering.
> 
> The Task Switcher is often invoked using the key combination Alt + Tab,
> but this can be changed. When it is invoked, it shows a list of all the
> currently open windows, optionally filtered and augmented according to
> the configuration settings. For example, the list may be filtered to
> show only windows that meet certain criteria, such as windows that are
> currently visible.  Once the window list is shown, the user can cycle
> through all the listed windows by repeatedly hitting the Task Switcher
> key combination.  Releasing the Task Switcher key combination will
> activate the window that was selected in the list.
> 
> Because the Task Switcher offers so many configuration options, two
> distinct collections of configuration settings can be defined. These
> collections are called 'Main' and 'Alternative', and each can have a set
> of unique key combinations assigned to them.
> 
> The configuration options for each of the Main and Alternative
> collections are presented in four groupings, as follows:
> -Visualization
> -Shortcuts
> -Content
> -Filter Windows By
> 
> These four configuration groupings are described below.
> 
> Visualization
> This group of configuration options controls how the list of windows is
> displayed on the screen. The default visualization is called Breeze,
> which lists all open windows along the left-hand side of the screen. 
> Other visualizations include Cover Switch (a 3D carousel), Flip Switch
> (a 3D stack of cards), and Medium Rounded (a Microsoft Windows-style
> list of icons).  Many more visualizations can be downloaded and
> installed by clicking the Get New Task Switchers... button at the bottom
> right of the dialog box.
> 
> Once a visualization has been selected from the drop-down list, the
> button to the right of the list can be clicked to see a preview or to
> configure visualization-specific options.
> 
> The 'Show Selected Window' checkbox determines how clearly the user will
> see which window will be activated.  If this box is checked, then all
> windows will be dimmed except for the one that is currently highlighted
> in the Task Switcher.
> 
> Note: There may be cases where the desired Task Switcher visualization
> cannot be shown.  One of these situations can be when a process called
> 'compositing' is turned off or disabled.  If this ever happens, the
> window list will still be shown, but in a very simple format.
> 
> Shortcuts
> Up to four keyboard shortcuts can be defined to invoke the Task Switcher.
> In the All Windows section, the Forward and Reverse shortcuts will cycle
> forward and backward through the full list of windows.
> In the Current Application section, the Forward and Reverse shortcuts
> can be set to cycle through the windows of the current application.  For
> example, if you have three Dolphin file browser windows open, then you
> would be able to use these shortcuts to just cycle among the three
> Dolphin windows.
> To change a keyboard shortcut, click in the 'Forward' or 'Reverse' box
> and type the desired shortcut combination.  Be sure to use a modifier
> key like Control or Alt as part of the shortcut, otherwise you might not
> be able to cycle through the window list properly.
> 
> Note: To invoke the Task Switcher without using the keyboard, you can
> define screen edge actions in the Screen Edges module (go to System
> Settings and then select Screen Edges).
> 
> Content
> The content of the window list itself is partially controlled by the
> options in this section.
> 
> The 'Sort Order' drop-down list specifies whether the windows should be
> listed in 'Stacking Order' or 'Recently Used' order.  Stacking Order is
> the order in which the windows appear on the screen, while Recently Used
> order is the order in which the windows have been used.  Recently Used
> order makes it very easy to switch between the two most frequently used
> windows because they will always appear in the top 2 positions in the list.
> 
> The 'Include Show Desktop icon' option will add a Show Desktop option to
> the window list. This allows the user to easily select the Desktop as
> the 'window' to show.
> 
> The 'Only one window per application' option reduces clutter by only
> showing one window for each open application.  If an application has
> multiple windows open, then its most recently activated window will be
> shown in the list and the others will not be shown.
> 
> Filter Windows By
> This section contains options for additional filtering of the list of
> windows that are shown by the Task Switcher.
> 
> Virtual Desktops
> When checked, this option filters the list of windows according to which
> virtual desktop is currently active.  If you consistently put specific
> windows on specific virtual desktops, then this filtering option can
> make it easy to switch to windows within or across those virtual desktops.
> 
> Activities
> When checked, this option filters the list of windows according to which
> Activity is currently active.  As with Virtual Desktop filtering, this
> option can make it easier to switch to applications within or across all
> Activities.
> 
> Screens
> When checked, this option filters the list of windows according to which
> Screen is currently active.  For this option, the active screen is the
> one that the mouse pointer is currently on, not the screen that the
> currently active window is on.  This option can be useful to users who
> want to quickly switch between windows that are on the same monitor in a
> multi-monitor setup.
> 
> Minimization
> When checked, this option filters the list of windows according to
> whether they are hidden or not.
> 
> 
> All of the options described above work together to provide very
> fine-grained control of the Task Switcher's behavior and appearance. 
> For example, you could define the 'Main' settings collection to be
> invoked with the Alt+Tab key combination, to show the open windows in a
> carousel, to only show one window per application, and to only list
> windows that are on the current desktop and on the currently active
> screen.  This can provide very fast context-sensitive window switching
> if you have both 'work' and 'home' virtual desktops, and then keep all
> of your spreadsheets for work and home on the same monitor.
> 
> The availability of the 'Alternative' Task Switcher configuration gives
> you a second way way to easily filter and browse through the window
> lists. This should make it easier to navigate through large numbers of
> windows spread across multiple virtual desktops, screen, and activities.
> -------------------