aerothemeplasma/INSTALL.md

# Installation

## TABLE OF CONTENTS

1. [Prerequisites](#preq)
1. [Install Script](#script)
1. [KDE Plasma Settings](#plasma-settings)
1. [KDE Plasma Theme](#plasma-theme)
1. [Icons and Cursors](#icons)
1. [Qt Visual Style](#application-theme)
1. [Fonts](#fonts)
1. [Window Manager](#wm)
1. [Reflection Effect](#reflection)
1. [Plasma Widgets](#widgets)
1. [Task Switcher](#task-switcher)
1. [Look and Feel](#look-and-feel)
1. [Sounds](#sounds)
1. [SDDM](#sddm)
1. [Wine](#wine)
1. [Terminal](#terminal)
1. [Firefox](#firefox)


### Prerequisites <a name="preq"></a>

The following software is required for this project:

- KDE Plasma
- KWinFT/KWin with compositing support for blur and other effects
- Kvantum
- Qt5 GraphicalEffects package (```qt5-graphicaleffects``` on Arch)
- cmake
- extra-cmake-modules
- [Scale Minimize Animation](https://store.kde.org/p/1267839) (Can be installed through System Settings)

On Debian and Debian-based distributions (Ubuntu, Mint, etc.), the following apt packages are required:

```
$ sudo apt install cmake extra-cmake-modules build-essential qtbase5-dev libkdecorations2-dev libkf5configwidgets-dev libkf5config-dev libkf5coreaddons-dev libkf5windowsystem-dev libkf5wayland-dev kwin-dev
```

On OpenSUSE Tumbleweed, install the following packages (required for the Reflection effect):

```
$ sudo zypper install kwindowsystem-devel kwin5-devel libkdecoration2-devel libQt5Gui-devel
```

### Install Script <a name="script"></a>

AeroThemePlasma features an early experimental install script which currently serves to ease parts of the installation. It's a work in progress and marked as experimental, so things may or may not work properly. **The install script is provided as-is, and there's a nonzero chance that it might unintentionally break your system, delete your files, and/or cause a housefire. You have been warned.**

Currently, the install script just copies all the files to their intended directories, deleting any previous version of those files that might have been on the system beforehand. It also compiles the Reflection effect and installs it properly. The user still has to set up their desktop layout and other settings, as described in this document. 

Features that should be implemented into the script:

- Automatically setting up the layout and settings for the user.
- Support for Debian-based distributions.
- Font installation that migrates fonts from an existing Windows installation.
- The script should probably install the dependencies for you(?)

Important notes:

- The install script does NOT download or install fonts to the system.
- Currently, only Arch-based distributions are supported.
- The install script assumes that the user has installed all the dependencies before running the script.

To run the script, do the following in the terminal:

```
$ chmod +x install.sh
$ ./install.sh install
```

Alternatively, simply run: 

```
$ sh install.sh install 
```


### KDE Plasma Settings <a name="plasma-settings"></a>

Starting off with the simplest modifications, this is a list of recommended settings which are configurable in the system settings, to make Plasma behave more like Windows 7:

- Under Workspace Behaviour:
    - Under General Behaviour:
        - Clicking files or folders: Selects them
    - Under Desktop Effects:
        - Disable 'Background contrast' *(This theme does not make use of this option #9)*
        - Enable 'Blur', set Blur strength to 2, and Noise strength to 0
        - Enable 'Desaturate unresponsive applications'
        - Enable 'Fading popups'
        - Enable 'Login', check 'Fade to black' *(Apparently this effect is currently broken? It won't actually fade to black.)*
        - Enable 'Logout'
        - Enable 'Morphing popups'
        - Disable 'Sliding Popups'
        - Disable 'Translucency'
        - Enable 'Glide':
            - Duration: 200ms
            - Window Open Animation: Top, 8, 20
            - Window Close Animation: Bottom, 15, 30
        - Enable 'Window Aperture'
        - If using KWinFT, enable 'Flip Switch':
            - Flip animation duration: 200
            - Angle: 45°.
        - Enable 'Scale' (Appearance) - If you don't have this plugin, download 'Scale Minimize Animation' from 'Get New Desktop Effects'.
    - Under Screen Edges:
        - Turn off all 8 screen edges
    - Under Touch Screen:
        - Disable all 4 triggers
    - Under Virtual Desktops:
        - Remove all but one desktop, set maximum rows to 1

- Under Window Management:
    - Under Window Behaviour:
       - Under Window Actions:
            - Modifier key: Meta
    - Under KWin Scripts:
         - Enable 'MinimizeAll'

When editing Plasma's bottom panel, make sure its width is set to 40 pixels (30 if using a small panel).
 
### KDE Plasma Theme <a name="plasma-theme"></a>

Seven-Black is the theme for Plasma's shell. To install it, put it in the following directory (create it if it doesn't exist):

```
$ ~/.local/share/plasma/desktoptheme/
```

To apply it, go to ```System Settings -> Appearance -> Plasma Style``` to find it and select it.

### Icons and Cursors <a name="icons"></a>

The icon theme is ```windowsicon```, while ```aero-drop``` is the cursor theme. Extract the tar archives and move the icon theme into the following directory:

```
$ ~/.local/share/icons/
``` 

To apply the icon theme, go to ```System Settings -> Appearance -> Icons``` and select the theme.
It is also strongly recommended to install the [Oxygen](https://invent.kde.org/frameworks/oxygen-icons5) icon theme if it's not already installed on your system, as this project's icon theme optionally depends on it.

As for installing the cursor theme, apply the theme in ```System Settings -> Appearance -> Cursors```, and then follow [this](https://www.youtube.com/watch?v=Dj7co2R7RKw) video tutorial to ensure the cursor theme is applied everywhere consistently.  It's important to keep in mind the following:

1. Make sure that the cursor theme is installed system-wide (it has to be in ```/usr/share/icons```), or else SDDM cannot apply the theme.
2. If SDDM fails to pick up on the cursor theme, go to ```System Settings -> Startup and Shutdown -> Login Screen (SDDM)``` and click on 'Apply Plasma Settings' to ensure SDDM is properly configured.

Consult the [Arch Wiki](https://wiki.archlinux.org/title/Cursor_themes) for more information, as setting a cursor theme on Linux is not as trivial or elegant KDE's System Settings would suggest.


### Qt Visual Style <a name="application-theme"></a>

Installing Kvantum requires installing the package ```kvantum``` which is available in the community repository for Arch, and is available on most other Linux distributions as well. 

Installing the Kvantum theme is simply done through Kvantum's settings. Afterwards, Kvantum can be set as the visual style in ```System Settings -> Appearance -> Application Style```.

**Installing the color scheme:**

To install the color scheme, go to ```System Settings -> Appearance -> Colors``` and click "Install from file". Locate the following file and select it:

```
./Plasma/Color_Scheme/AeroColorScheme.colors
```

Select the color scheme and apply it.


### Fonts <a name="fonts"></a>

For the sake of keeping this theme pack relatively compact, and to avoid potential licensing issues, this repository won't include Windows fonts, but acquiring them from an already present Windows installation is easy.
On Windows, fonts are stored in the following directory:

```
C:\Windows\Fonts\
```

If you have an existing Windows installation, you can simply copy the fonts over to the following directory (note that this will install the fonts across the entire system):

```
# /usr/share/fonts/windows/
``` 

It might be necessary to also update the fontconfig cache:

```
$ fc-cache
```

As for the actual font rendering configuration, in ```System Settings -> Appearance -> Fonts``` apply the following settings:

- General: Segoe UI 9pt
- Fixed width: Fixedsys 11pt
- Small: Segoe UI 8pt
- Toolbar: Segoe UI 9pt
- Menu: Segoe UI 9pt
- Window title: Segoe UI 9pt <br>
- Anti-aliasing: Enable
- Sub-pixel rendering: RGB *(This may vary depending on the monitor, choose the setting that looks best for your monitor and eyes.)*
- Hinting: Slight

Relog into a new Plasma session to see the results.

Note: Font rendering on Linux is [largely broken now](https://gitlab.gnome.org/GNOME/pango/-/issues/656) [and has been](https://gitlab.gnome.org/GNOME/pango/-/issues/463) [for](https://gitlab.gnome.org/GNOME/pango/-/issues/404) [several](https://github.com/harfbuzz/harfbuzz/issues/2394) [years](https://www.phoronix.com/news/HarfBuzz-Hinting-Woe). As a result, **pretty much all** font hinting options are broken except for **slight** font hinting and HiDPI rendering (because at that point, subpixel rendering isn't even needed). This regression has taken away the aggressive font hinting which made rendering nearly identical to ClearType on Windows 7. Currently, full font hinting _should technically work again_, but certain glyphs aren't horizontally aligned correctly, which still makes text unreadable. Until this issue is resolved, the only viable choice is to use slight font hinting.


### Window Manager <a name="wm"></a>

The KWin decoration theme comes in two parts: The decoration theme itself and a KWin effect for the caption button glow effect. Both components can be found in the following directory:

```
$ ./KWin/smod_kwin_theme/
```

To compile the components, run the following: 

```
$ sh install-resources.sh
$ sh build-decoration.sh
$ sh install-decoration.sh
$ sh build-effect.sh
$ sh install-effect.sh
```

Log out of the Plasma session or restart KWin, and go to ```System Settings -> Appearance -> Window Decorations``` and select SMOD. In the settings for SMOD, set the shadow size to small.

To enable caption button glow, go to ```System Settings -> Desktop Effects``` and enable the SMOD Window Buttons effect. 


### Reflection Effect <a name="reflection"></a>

To install the reflection effect, it's recommended to build it from source, as dumping the precompiled files doesn't seem to work on its own.

Go to the folder:

```
cd ./KWin/kwin_reflect/
sh install.sh
```

After it has been compiled, you can log out or restart Plasma and KWin, then go to ```System settings -> Workspace Behavior -> Desktop Effects``` and enable the effect.


### Plasma Widgets <a name="widgets"></a>

Installing them can be done by moving the plasmoid folder found in the following directory:

```
$ ./Plasma/Plasma_Widgets/User/
```

to:

```
$ ~/.local/share/plasma/plasmoids/
```

Example:

To install Show Desktop (Aero), move the directory:

```
$ ./Plasma/Plasma_Widgets/User/io.wackyideas.win7showdesktop/
```

to:

```
$ ~/.local/share/plasma/plasmoids/
```

#### Seven Start

Seven Start has a feature that allows the orb button to stick out of the panel, which requires a natively compiled component. Before installing Seven Start normally, move the following file:

```
$ ./Plasma/Plasma_Widgets/User/plasma_applet_SevenStart.so
```

to:

```
# /usr/lib/qt/plugins/plasma/applets/plasma_applet_SevenStart.so
```


#### Seven Tasks

Just like Seven Start, Seven Tasks also requires a similar installation process. Move the file:

```
$ ./Plasma/Plasma_Widgets/User/plasma_applet_seventasks.so
```

to:

```
# /usr/lib/qt/plugins/plasma/applets/plasma_applet_seventasks.so
```

This library is used to create [this effect](https://superuser.com/questions/730804/how-does-windows-7-calculate-the-color-to-use-for-taskbar-color-hot-tracking) from Windows 7. 

It is possible to toggle showing labels by toggling the "Show labels on taskbar buttons" option in the configuration window like this:

<img src="Screenshots/SevenTasksConfig.png">

#### Digital Clock Lite

This plasmoid doesn't require additional configuration after installation if other steps have been completed. If for some reason the font and size do not look appropriate, set them to the following: 

- Font size px: 9
- Font style: Segoe UI

#### Desktop containment

To make the desktop look more like Windows 7 by default, right click on the desktop and click "Configure Desktop and Wallpaper...", change the following settings:

- Icons:
    - Icon size: 2
    - Label width: Narrow
    - Features: All checked except for "Folder preview popups"

### DefaultToolTip.qml

This is a QML component that defines the appearance of Plasma tooltips. Since this is a system-wide component, this file will be replaced with the upstream version whenever KDE is updated through the package manager of your system, meaning this installation step should be performed after every system upgrade.

To install, move the following file:

```
$ ./Plasma/Plasma_Widgets/System/Tooltips/DefaultTooltip.qml
```

to:

```
# /usr/lib/qt/qml/org/kde/plasma/core/private/
```

Restart plasma to apply changes.

### Task Switcher <a name="task-switcher"></a>

To install, move the following folder:

```
$ ./KWin/thumbnail_seven
```

to:

```
$ ~/.local/share/kwin/tabbox/
```

In ```System Settings -> Window Management -> Task Switcher```, set the following:

In Main:

- Visualization: Set "Thumbnail Seven" as the visualization style.
- Shortcuts (for All Windows): 
    - Forward: Alt + Tab 
    - Backward: Alt + Shift + Tab
- Check "Include "Show Desktop" icon"

In Alternative: 

- Visualization: Set "Flip Switch" as the visualization style.
- Shortcuts (for All Windows):
    - Forward: Meta + Tab
    - Backward: Meta + Shift + Tab 
- Check "Include "Show Desktop" icon"

### Look and Feel <a name="look-and-feel"></a>

To install the splash and lock screen, move the folder:

```
$ ./Plasma/Look_and_Feel/authui7
```

To the following directory:

```
$ ~/.local/share/plasma/look-and-feel/
```

Create the directory in case it doesn't exist.

To apply the splash and lock screen, go to ```System Settings -> Appearance -> Global Theme```, click 'Choose what to apply...' and uncheck everything but 'Lock Screen' and 'Splash Screen', and then hit Apply.

### Sounds <a name="sounds"></a>
On Windows, system sound files are located in:

```
C:\Windows\Media
```

To install the sound files bundled with this project, move the two following directories:

```
$ ./Plasma/Sounds/media_windows
$ ./Plasma/Sounds/stereo_windows
```

to:

```
# /usr/share/sounds/
```

To apply them, go to ```System Settings -> Notifications```. There, click on the 'Configure'
button. Scroll down to ```Plasma Workspace```, and click on the 'Configure Events' button.
Set the sounds for the following notifications:

|Sound                    |File                                                         |
|-------------------------|-------------------------------------------------------------|
|Notification             |```/usr/share/sounds/stereo_windows/dialog-information.ogg```|
|Warning Message          |```/usr/share/sounds/stereo_windows/dialog-warning.ogg```    |
|Fatal Error, Catastrophe |```/usr/share/sounds/stereo_windows/dialog-error.ogg```      |
|Logout                   |```/usr/share/sounds/stereo_windows/desktop-logout.ogg```    |
|Question                 |```/usr/share/sounds/stereo_windows/dialog-question.ogg```   |
|Login                    |```/usr/share/sounds/stereo_windows/desktop-login.ogg```     |
|Warning                  |```/usr/share/sounds/stereo_windows/dialog-warning.ogg```    |
|Trash, Emptied           |```/usr/share/sounds/media_windows/Windows Recycle.wav```    |
|Critical Message         |```/usr/share/sounds/stereo_windows/dialog-warning.ogg```    |
|Information Message      |```/usr/share/sounds/stereo_windows/dialog-information.ogg```|
|Beep                     |```/usr/share/sounds/stereo_windows/button-pressed.ogg```    |

Then, under ```Power Management```, click on the 'Configure Events' button. Set the sounds for the following
notifications:

|Sound                              |File                                                              |
|-----------------------------------|------------------------------------------------------------------|
|Battery Low, Peripheral Battery Low|```/usr/share/sounds/media_windows/Windows Battery Low.wav```     |
|Battery Critical                   |```/usr/share/sounds/media_windows/Windows Battery Critical.wav```|

### SDDM <a name="sddm"></a>

To install the SDDM theme, move the following folder:

```
$ ./Plasma/SDDM/sddm-theme-smod
```

to: 

```
# /usr/share/sddm/themes/
```

Go to ```System Settings -> Login Screen (SDDM)``` and select SMOD. If the theme doesn't look right, click the 'Apply Plasma Settings...' button and apply the changes.

### Wine <a name="wine"></a>

To install the msstyle for Wine applications, run ```winecfg```, and under the 'Desktop Integration' tab, click 'Install theme' and choose the following file:

```
$ ./Wine/VistaVG Ultimate/vistavg_ultimate.msstyles
```

After that, go through the entire 'Item' list, and change the font everywhere to:

- Font: Segoe UI
- Size: 9pt

### Terminal <a name="terminal"></a>

To make your terminal emulator of choice look a bit more like the command prompt from Windows, do the following:

- Hide the menu bar
- Hide the tab bar if there's only one tab available
- Set the terminal font to Fixedsys (Excelsior 3.01), 11pt.
- Add the following line to `~/.bashrc`: 

```printf 'Microsoft Windows [Version 6.1.7601] \nCopyright <c> 2009 Microsoft Corporation. All rights reserved.\n\n'```

The last part will print the provided string every time a new bash session is started.

### Firefox <a name="firefox"></a>

The project [Aero UserChrome](https://gitgud.io/souris/aero-userchrome) by [Souris-2d07](https://gitgud.io/souris) is recommended for use with AeroThemePlasma.

In order to correctly apply blur and reflections onto Firefox, it's required to install the Firefox Blur Region Fix KWin effect. 

To install the effect, it's recommended to build it from source, as dumping the precompiled files doesn't seem to work on its own.

Go to the folder:

```
cd ./KWin/kwin_fixblur/
sh install.sh
```

After it has been compiled, move the following folder: 

```
$ ./KWin/.ffblurfix
```

To the home directory.

You can log out or restart Plasma and KWin, then go to ```System settings -> Workspace Behavior -> Desktop Effects``` and enable the effect.

By default, this effect is enabled for Firefox. If you're using a different Firefox-based browser (Firefox ESR, Nightly, Floorp, Librewolf, etc.), then they need to be included in the config menu by adding their secondary window class name to the list.

For example, to apply the effect to both Firefox and Librewolf, the config's text box should contain the text:

```
firefox;librewolf
```