fvwm-nightshade(1)
==================
:doctype: manpage

NAME
----

fvwm-nightshade - a feature rich configuration for F? Virtual Window 
Manager (FVWM) for X11.

SYNOPSIS
--------

None


DESCRIPTION
-----------

*Fvwm-Nightshade* aims to be a lightweight but feature rich and good looking 
configuration of Fvwm. It contains many useful things to make work and 
life easier with a flavour of a modern desktop. In this document you find 
how *Fvwm-Nightshade* is constructed, how to handle it, its’ bindings and 
how you can customize it (e.g. new themes or layouts).


USAGE
-----

First Start
~~~~~~~~~~~
*Fvwm-Nightshade* checks while your first login if +~/.fvwm-nightshade+ exist. 
If not *FNS-BaseSetup* dialog appears where you can change things like desktop size, 
used theme and font, which layout, default terminal and browser you want.

After clicking "Apply" your settings will be activated and 
*Fvwm-Nightshade* is ready to use. If you want to change the settings 
again you can do that over the menu point
----
Configuration -> Fvwm-Nightshade -> FNS Base Setup
----


Desktop Organisation
~~~~~~~~~~~~~~~~~~~~
Four different desktop layouts are available:

* Horizontal (default)
* Vertical
* G2like (Gnome 2 based)
* Klike (KDE based)

You can change it via *FNS Base Setup* or over the menu
----
Configuration -> Fvwm-Nightshade -> Decorations -> Layouts
----

Below each layout is described in detail.

Horizontal Layout
^^^^^^^^^^^^^^^^^
The *Horizontal Layout* has 3 elements at  the top of the screen. It consists 
from left to right.

_The "Global Iconman" Taskbar_::
+
It is a vertical growing winlist holding each window on the current page 
as a horizontal bar labeled with the name and the title of each window. 
It moves down if the mouse hovers over the right vertical bar labeled with 
"Global Iconman". If the mouse hovers over one of the horizontal bars the 
window related to this bar gets the focus.
+
There are some mouse bindings available:
+
* double clicking or scroll down on a bar iconify the window
* double clicking or scroll up on a bar deiconify the window
* right clicking  on a bar opens a windows operation menu

_The Pager_::
+
It is a miniature illustration of up to 10 virtual desktop pages (10x1) with 
mini windows. By clicking on each of a segment you can change the page. 
Also you can move each window from one page to another with holding down 
the middle mouse button. If you hover over a mini window it shows the name 
and the title of it.
+
There are also some key combinations available:
+
* _Shift-Ctrl_ and _Arrow_ key right/left switch to the next/previous page.
* _Shift-Ctrl_ and _number_ 1-0 switch to page 1-10.
* _Shift-Alt_ and _Arrow_ key right/left moves the active window to the next/previous page.
* _Shift-Alt_ and _number_ 1-0 moves the active window to page 1-10.

_The Panel_::
+
It contains from left to right:
+
* The root menu. It opens by left clicking the *Fvwm-Nightshade* icon.
* The systemtray with application applets. The amount of visible applets 
depends on the screen width. If more applets in the systray than representable 
a bar on the left and right side appears while hovering over the left or 
right end of the tray. With scrolling the mouse wheel you can move throug 
the applets.
* A cpu graph with percentage. With right click on the applet area an 
opertion menu appears with the possibility to restart the applet or open 
the governor-tool FNS-CpuPerformance to handle cpufreq or cpupower settings.
* A Clock and date applet. With right click on the applet area an opertion 
menu appears with the possibility to open a calender or an alarm clock. Is 
it also possible to set the clock and date but root or sudo permission is 
required. Sometimes this applets have problems to swallow into the panel. 
With the last point it can tried to restart.

The maximum size of a window is limited by Fvwm its' EwmhBaseStruts. So it 
will maximum growing underneath the horizontal elements. You can use _Alt-F11_ 
to grow the window to the whole screen.

Vertical Layout
^^^^^^^^^^^^^^^
The *Vertical Layout* has 3 elements on the right side of the screen. It 
consists from above to below:

_The Panel_::
+
It contains from above to below:
+
* A Clock and date applet. With right click on the applet area an opertion 
menu appears with the possibility to open a calender or an alarm clock. Is 
it also possible to set the clock and date but root or sudo permission is 
required. Sometimes this applets have problems to swallow into the panel. 
With the last point it can tried to restart.
* A cpu graph with percentage. With right click on the applet area an 
opertion menu appears with the possibility to restart the applet or open 
the governor-tool FNS-CpuPerformance to handle cpufreq or cpupower settings.
* The systemtray with application applets. The amount of visible applets 
depends on the screen width. If more applets in the systray than representable 
a bar on the left and right side appears while hovering over the left or 
right end of the tray. With scrolling the mouse wheel you can move throug 
the applets.
* The root menu. It opens by left clicking the *Fvwm-Nightshade* icon.
* The winlist. It opens a window with all windows by left clicking on the 
winlist icon.

_The Pager_::
+
It is a miniature illustration of up to 10 virtual desktop pages (10x1 or 5x2) 
with mini windows. By clicking on each of a segment you can change the page. 
Also you can move each window from one page to another with holding down 
the middle mouse button. If you hover over a mini window it shows the name 
and the title of it.
+
There are also some key combinations available:
+
* _Shift-Ctrl_ and _Arrow_ key right/left/up/down switch to the next/previous/upper/down page.
* _Shift-Ctrl_ and _number_ 1-0 switch to page 1-10.
* _Shift-Alt_ and _Arrow_ key right/left/up/down moves the active window to 
the next/previous/upper/down page.
* _Shift-Alt_ and _number_ 1-0 moves the active window to page 1-10.

_The "Global Iconman" Taskbar_::
+
It is a vertical growing winlist holding each window on the current page 
as a horizontal bar labeled with the name and the title of each window. 
It moves down if the mouse hovers over the left vertical bar labeled with 
"Global Iconman". If the mouse hovers over one of the horizontal bars the 
window related to this bar gets the focus.
+
There are some mouse bindings available:
+
* double clicking or scroll down on a bar iconify the window.
* double clicking or scroll up on a bar deiconify the window.
* right clicking  on a bar opens a windows operation menu.

The maximum size of a window is limited by Fvwm its' EwmhBaseStruts. So 
it will maximum growing left to the vertical elements. You can use _Alt-F11_ 
to grow the window to the whole screen.

G2like Layout
^^^^^^^^^^^^^
The *G2like* layout is based on the Gnome 2 layout. It consist two panels - one 
on the top and one on the bottom of the screen.

_The Top Panel_::
+
This panel contains from left to right:
+
* The root menu. It opens by left clicking the *Fvwm-Nightshade* icon.
* The personal/favorite menu. It opens by left clicking the bookmark icon.
* The systemtray with application applets. The amount of visible applets 
depends on the screen width. If more applets in the systray than representable 
a bar on the left and right side appears while hovering over the left or 
right end of the tray. With scrolling the mouse wheel you can move through 
the applets.
* A cpu graph with percentage. With right click on the applet area an 
opertion menu appears with the possibility to restart the applet or open 
the governor-tool FNS-CpuPerformance to handle cpufreq or cpupower settings.
* A Clock and date applet. With right click on the applet area an opertion 
menu appears with the possibility to open a calender or an alarm clock. Is 
it also possible to set the clock and date but root or sudo permission is 
required. Sometimes this applets have problems to swallow into the panel. 
With the last point it can tried to restart.
* The Exit menu. It opens by left clicking the exit icon.

_The Bottom Panel_::
+
This panel contains from left to right:
+
* The "Show desktop" button. It iconify/deiconify all windows on the current page.
* The "Global Iconman" Taskbar. It is a winlist holding each window on the 
current page as a horizontal bar labeled with the name and the title of 
each window. If the mouse hovers over one of the horizontal bars the window 
related to this bar gets the focus.
+
There are some mouse bindings available:
+
- double clicking or scroll down on a bar iconify the window.
- double clicking or scroll up on a bar deiconify the window.
- right clicking  on a bar opens a windows operation menu.
+
* The Pager. It is a miniature illustration of up to 10 virtual desktop pages 
(10x1) with mini windows. By clicking on each of a segment you can change the 
page. Also you can move each window from one page to another with holding down 
the middle mouse button. If you hover over a mini window it shows the name 
and the title of it.
+
There are also some key combinations available:
+
* _Shift-Ctrl_ and _Arrow_ key right/left switch to the next/previous page.
* _Shift-Ctrl_ and _number_ 1-0 switch to page 1-10.
* _Shift-Alt_ and _Arrow_ key right/left moves the active window to the next/previous page.
* _Shift-Alt_ and _number_ 1-0 moves the active window to page 1-10.

The maximum size of a window is limited by Fvwm its' EwmhBaseStruts. So 
it will maximum growing inbetween the two panels. You can use _Alt-F11_ to 
grow the window to the whole screen.

Klike Layout
^^^^^^^^^^^^
The *Klike* layout is based on the KDE layout. It consists one bottom panel.

_The Bottom Panel_::
+
This panel contains from left to right:
+
* The root menu. It opens by left clicking the *Fvwm-Nightshade* icon.
* The "Show desktop" button. It iconify/deiconify all windows on the current page.
* The "Global Iconman" Taskbar. It is a winlist holding each window on the 
current page as a horizontal bar labeled with the name and the title of 
each window. If the mouse hovers over one of the horizontal bars the window 
related to this bar gets the focus.
+
There are some mouse bindings available:
+
- double clicking or scroll down on a bar iconify the window.
- double clicking or scroll up on a bar deiconify the window.
- right clicking  on a bar opens a windows operation menu.
+
* The Pager. It is a miniature illustration of up to 10 virtual desktop pages 
(10x1) with mini windows. By clicking on each of a segment you can change the 
page. Also you can move each window from one page to another with holding down 
the middle mouse button. If you hover over a mini window it shows the name 
and the title of it.
+
There are also some key combinations available:
+
* _Shift-Ctrl_ and _Arrow_ key right/left switch to the next/previous page.
* _Shift-Ctrl_ and _number_ 1-0 switch to page 1-10.
* _Shift-Alt_ and _Arrow_ key right/left moves the active window to the next/previous page.
* _Shift-Alt_ and _number_ 1-0 moves the active window to page 1-10.
+
* The systemtray with application applets. The amount of visible applets 
depends on the screen width. If more applets in the systray than representable 
a bar on the left and right side appears while hovering over the left or 
right end of the tray. With scrolling the mouse wheel you can move through 
the applets.
* A cpu graph with percentage. With right click on the applet area an 
opertion menu appears with the possibility to restart the applet or open 
the governor-tool FNS-CpuPerformance to handle cpufreq or cpupower settings.
* A Clock and date applet. With right click on the applet area an opertion 
menu appears with the possibility to open a calender or an alarm clock. Is 
it also possible to set the clock and date but root or sudo permission is 
required. Sometimes this applets have problems to swallow into the panel. 
With the last point it can tried to restart.

The maximum size of a window is limited by Fvwm its' EwmhBaseStruts. So 
it will maximum growing above the panel. You can use _Alt-F11_ to 
grow the window to the whole screen.

Root Menu
~~~~~~~~~
The Root menu is the main menu of *Fvwm-Nightshade*. You can call it in 
different areas with mouse or key combinations:

* In the root area with left click or with _Alt+F1_ or with the left _Window_ key. 
If icons on desktop are enabled the menu is moved around to the right click 
desktop menu because PcmanFm offered this feature take the root window is under 
its' control.
* In each window area or in an iconified windows with _Alt+left click_.

Personal Applications
^^^^^^^^^^^^^^^^^^^^^
The Personal Applications menu is for your favorite applications. As you 
open it the first entry is a graphical tool to choose applications or folders 
from the application menus found on the system. Also it is possible to create 
own application or folder entries. Entries can be sorted with drag'n'drop.

For more information about the graphical tool see manpage of *FNS-MenuBuilder*.

XDG Application Menus
^^^^^^^^^^^^^^^^^^^^^
Below of the Personal Applications menu all XDG related application menus 
found on the system are listed. No, not all. Only the important ones. You 
can configure the choice with "Regenerate (XDG) Menu".

Regenerate (XDG) Menu
^^^^^^^^^^^^^^^^^^^^^
The "Regenerate (XDG) Menu" point is to reconfigure or refresh the XDG 
application menus after software installation. 

For information about each possibility hover over the widgets to get a help 
tip or click on the "Help" button on the bottom. This will open the man page 
of fns-menu-desktop the main tool behind the GUI. 

Configuration
^^^^^^^^^^^^^
In this menu you find parts to configure the look and feel of *Fvwm-Nightshade*. 
But also some tools for Gtk and Qt applications if they are installed.

Fvwm::
+
Here you can configure the animation how windows iconify/deiconify and how 
FvwmForm windows appear (font, color, background).

Fvwm-Nightshade::
+
Here you can configure the background, the composite manager, which theme and 
layout you want, the look of your Gtk and Qt applications, the base settings and 
window behaviour of *Fvwm-Nightshade*.

System::
+
Here you can configure the keyboard, mouse, time and date, xscreensaver and, if 
you have a multi cpu system your CPU governor settings.

Help
^^^^
In this menu you’ll find many helps for Fvwm (websites, manpages), *Fvwm-Nightshade* 
and other programs like manpage viewers, online helps, etc.

Fvwm modules
^^^^^^^^^^^^
In this menu you can start and stop Fvwm modules on the fly. Also a submenu directory 
exists for useful FvwmForms.

Window Operations
^^^^^^^^^^^^^^^^^
*Fvwm-Nightshade* have different "WinOps" menus. You can call them on different 
places but here you find all of them ^^.

Lock Screen
^^^^^^^^^^^
If you have configured xscreensaver you can activate the lock screen by 
clicking this menu point. Or with the keyboard shortcut _Alt+Ctrl+L_.

Run Command
^^^^^^^^^^^
If you want to run a program you can open a mini window to enter your command. 
Or with _Alt+F2_.

Terminal
^^^^^^^^
This menu point opens your favorite terminal set with *Fvwm-Nightshades* 
base setup.

Quit
^^^^
This menu gives you the possibility to restart, refresh, quit, suspend or 
hibernate *Fvwm-Nightshade*.


Bindings
~~~~~~~~
*Fvwm-Nightshade* has some bindings for mouse and keyboard combinations. 
There are some for general and for theme related purpose. 


Below they are all listed.

Mouse
^^^^^
Mouse bindings are assigned to areas:

Root Area::
+
Button 1:   Root menu.
+
Button 2:   Window list.
+
Button 3:   Desktop menu. If you have configured icons on desktop there's a root menu, too.

Windows Area::
+
Button 1:   Root menu with ALT + click.
+
Button 2:   Drag + ALT moves window, raise or lower with ALT + click.

Windows Decoration Area::
+
Titlebar, corners and sides:::
+
Button 1:   Drag moves window, maximize on double click.
+
Button 2:   Drag moves window, raise or lower with click.
+
Button 3:   WindowOpsTrimmed menu with click, MenuWindowOpsFull menu with ALT + click.
+
Button 4/5: Rolling wheel on titlebar up/down shades/unshades.
+
Left Button:::
+
Button 1: shows WindowOpsTrimmed menu.
+
Button 2: shows Move to page menu.
+
Button 3: shows WindowOps group menu.
+
Close Button:::
+
Every button closes the window.
+
Maximize Button:::
+
Button 1: maximize window.
+
Button 2: maximize window vertically.
+
Button 2 + Alt: maximize window horizontally.
+
Button 3: maximize window smart.
+
Minimize Button:::
+
Button 1: iconify window.
+
Button 2: iconify group of same window resources.
+
Button 3: iconify/deiconify group of same window resources.

Anywhere::
+
Button 4/5: Switch to page left/right with Shift-Ctrl + rolling wheel up/down anywhere.
+
Button 4/5: Switch with active window to page left/right with Shift-Alt + rolling wheel up/down anywhere.

Help::
+
With Shift-Ctrl-Alt + Click you get a help of each mouse binding. For example 
you hold Shift-Ctrl-Alt + click on the minimize button and get a messagebox 
with all minimize bindings.

If you want to change them you have to edit the bindings in your favorite 
theme. Create a "themes" folder in the <user> directory and copy the complete 
theme directory into it. Rename the theme folder. 
Then open the "decor" file and edit the mouse bindings. After loading your 
customized theme by clicking its name in
------
Configuration -> Fvwm-Nightshade -> Decoration -> Decors
------
you have it ^^

Keys
^^^^
Key bindings are also assigned to different parts:

Window related::
+
[cols="10%,90%",frame="none",grid="none"]
|====
|Alt + F4    |Close active window.
|Alt + F6    |Cycle between same resource windows.
|Alt + F7    |Move active window.
|Alt + F8    |Resize active window.
|Alt + F9    |Minimize active window.
|Alt + F10    |Maximize/restore active window.
|Alt + F11    |Maximize active window to fullscreen and back.
|Alt + F12    |Identify active window.
|    |
|Alt + Tab    |Switching focus to next window.
|Alt-Shift + Tab|Switching focus to previous window.
|Alt-Ctrl + D|Hide/unhide all windows.
|====

Page related::
+
[cols="25%,75%",frame="none",grid="none"]
|====
|Shift-Ctrl + 1-0                   |Switch to page 1-10.
|Shift-Ctrl + cursor right/left     |Switch to page right/left.
|Shift-Ctrl + cursor up/down        |Switch to page up/down (only used in Vertical Layout).
|                                   |
|Shift-Alt-Ctrl + cursor right/left |Scroll right/left by 10% of a page.
|Shift-Alt-Ctrl + cursor up/down    |Scroll up/down by 10% of a page.
|                                   |
|Ctrl-Alt + cursor right/left       |Move mouse pointer right/left by 1% of a page.
|Ctrl-Alt + cursor up/down          |Move mouse pointer up/down by 1% of a page.
|                                   |
|Shift-Alt + 1-0                    |Switch to page 1-10 with active window.
|                                   |
|Shift-Alt + Cursor right/left      |Switch to page right/left with active window.
|Shift-Alt + Cursor up/down         |Switch to page up/down with active window (only used in Vertical Layout).
|====

General::
+
[cols="15%,85%",frame="none",grid="none"]
|====
|Print              |Screenshot of the whole desktop (page).
|Alt + Print        |Screenshot of the active window.
|Alt-Ctrl + L       |Lock Screen.
|Alt-Ctrl + T       |Launch your favorite terminal.
|                   |
|Windows            |Open root menu.
|Alt + F1           |Open root menu.
|Alt + F2           |Launch 'run' dialog box.
|Alt + F3           |Show window list.
|                   |
|Shift-Ctrl + F1    |Open full windows oops menu.
|Shift-Ctrl + F2    |Launch FvwmConsole.
|====

Help::
+
With Shift-Ctrl-Alt + a special key you get a message box with the related 
key bindings (the same as with mouse bindings)
+
[cols="15%,85%",frame="none",grid="none"]
|====
|Shift-Ctrl-Alt + A     |Help message for all Alt bindings.
|Shift-Ctrl-Alt + C     |Help message for all Ctrl bindings.
|Shift-Ctrl-Alt + P     |Help message for all Page bindings.
|Shift-Ctrl-Alt + H     |Help message for summary.
|====

To change the key bindings to your own needs copy +<system>/share/fvwm-nightshade/.bindings+ 
in the <user> directory and edit it. After a restart of *Fvwm-Nightshade* 
the new key bindings are available.


CONFIGURATION
-------------
In the following chapters we describe where you find what, how and which 
files are loaded, how you can debug problems and how you can customize 
*Fvwm-Nightshade*.

Structure of Fvwm-Nightshade
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
*Fvwm-Nightshade* is splitted in a system and an user part.

The system part is located in +/usr/local+ (default), +/usr+ (distribution 
related) or if you use the local installation under +<chosen_dir>+. In the 
following named as <system>.

The user part is located in +~/.fvwm-nightshade+. Following named as <user>.

Location of Files and their Function
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
*<system>/bin* => Executables.
[cols="20%,80%",frame="none",grid="none"]
|====
|fvwm-nightshade        |start script.
|fns-built-trayapplist  |Python script for stalonetray to build applet list. Used for restoring applets after restart stalonetray.
|FNS-CpuPerformance     |Perl-SimpleGtk2 script to set CPU frequency governor.
|fns-find-icon          |Python script to find the correct icon for iconified apps or for icons used in layouts.
|FNS-MenuBuilder        |Perl-SimpleGtk2 script to build personal menu.
|fns-menu-desktop       |adapted fvwm-menu-desktop from Fvwm's CVS to create XDG menu(s).
|fns-start-programs     |shell script to start apps from a file list. Used for autostart and starting applets for stalonetray.
|====

-

*<system>/share/fvwm-nightshade/* => System home of *Fvwm-Nightshade*.
[cols="10%,90%",frame="none",grid="none"]
|====
|config             |system wide configuration file.
|fns-init           |initial config with the base functions.
|.settings          |template of the base settings. Will be copied into <user> dir.
|.bindings          |system wide key bindings.
|====

-

*<system>/share/fvwm-nightshade/artwork/*   => *Fvwm-Nightshade* icons, splash and wallpapers.

*<system>/share/fvwm-nightshade/layouts/*   => System layout files and conky rc-files.

*<system>/share/fvwm-nightshade/lib/*       => Fvwm modules written in Perl or C/C++. Directory is in the ModulePath.
[cols="20%,80%",frame="none",grid="none"]
|====
|FvwmSmartMaximize          |Perl module to maximize windows in the largest area of the desktop/page.
|FvwmTransSet               |Perl module to set true transparency to windows if a composite manager is running.
|FNS-BaseSetup              |Perl-SimpleGtk2 module to configure base settings of Fvwm-Nightshade (layouts, themes, compositing, icons on desktop, etc.).
|FNS-WindowsBehaviour       |Perl-SimpleGtk2 module to configure window behaviours (focus policies, placement, etc.).
|FNS-CompConfigurator       |Perl-SimpleGtk2 module to configure composite manager if installed (shadows, translucency, etc).
|FNS-MenuConfigurator       |Perl-SimpleGtk2 module to configure the XDG menu creation. It exchange fvwm-menu-desktop2-config.fpl.
|====

-

*<system>/share/fvwm-nightshade/modules/*   => Pager, pannels and Iconman modules.

*<system>/share/fvwm-nightshade/themes/*    => Theme files and icons.

*<system>/share/doc/fvwm-nightshade/*       => Html pages, templates, readmes.

- 

*/usr/share/fvwm/* => Scripts which must resides in Fvwm's directory or if 
local installation is chosen in the <user> directories - FvwmScripts in the 
scripts/ sub directory, all others in the <user> root.
[cols="20%,80%",frame="none",grid="none"]
|====
|FNS-Script-FileBrowser         |File browser based on FvwmScript-FileBrowser
|FNS-Script-Date                |Set time/date based on FvwmScript-Date
|FNS-Applet-Kalende             |Calendar applet
|FNS-Applet-Chrono              |Alarm applet
|====

-

*/etc/xdg/menus/* => XDG applications menu directory. If local installation 
is chosen it is located in ~/.config/menus/.
[cols="20%,80%",frame="none",grid="none"]
|====
|fns-applications.menu          |Fvwm-Nightshade's application menu.
|====

-

*/usr/share/desktop-directories/* => Directory for XDG directory files. If local 
installation is chosen it is located in <chosen_dir>/share/desktop-directories/.
[cols="20%,80%",frame="none",grid="none"]
|====
|fns-<*>.directory              |Some .directory files for fns-applications.menu.
|====

-

*/usr/share/xsessions/* => Login manager directory if a display-manager is available.
[cols="20%,80%",frame="none",grid="none"]
|====
|fvwm-nightshade.desktop        |login script.
|====

-

*/usr/local/lib/perl-site|Perl5* => Perl directories for 3rd party libraries
[cols="20%,80%",frame="none",grid="none"]
|====
|SimpleGtk2.pm        |a wrapper around Perl-Gtk2 to allow RAD.
|====

-

*~/.fvwm-nightshade/* => the user home directory (<user>)
[cols="20%,80%",frame="none",grid="none"]
|====
|.autostart         |optional file with application commands.
|.fns-menu.cfg      |config file of Regenerate XDG Menus.
|.FvwmTransSet      |local config file of FvwmTransSet.
|.layout            |link to current layout file.
|.menu              |Fvwm menu file.
|.personal          |Menu file of your personal apps.
|.settings          |settings like layout, theme, font, splash, etc.
|.systray.log       |stalonetray log file.
|.trayapplist       |internal list of current systray apps.
|.user              |config file for FNS-WindowsBehaviour and custom user settings.
|.wallpaper         |link to current wallpaper
|====

-

*<user>/wallpapers/*    => default wallpaper directory.

*<user>/screenshots/*   => default screenshots directory.

*<user>/scripts/*       => Optional user FvwmScripts directory.

*<user>/icons/*         => Menu icon directory created by Regenerate XDG Menus.

*<user>/layouts/*       => Optional user layout directory.

*<user>/lib/*           => Optional user module directory. Is in the ModulPath.

*<user>/themes/*        => Optional user themes directory.

*<user>/locales/*       => Optional user language directory.

Call Sequence while Startup
~~~~~~~~~~~~~~~~~~~~~~~~~~~
The first file which is called while startup is +<system>/bin/fvwm-nightshade+. 
It initialize some environment variables, creates +~/.fvwm-nightshade+ if not 
available and starts Fvwm. But not with the +<user>/config+ or +<system>/config+. 

First Fvwm starts with a pre config - +<system>/share/fvwm-nightshade/fns-init+. 
It contains some important functions which allows *Fvwm-Nightshade* to handle 
another directory than +~/.fvwm+. 

The script calls then the main config via the "Load" function. This function 
looks first in the <user> dir and then in the <system> dir. It makes it 
possible to load parts created by the user or the default ones. With that 
function the user can copy the config or bindings in the <user> dir, alter 
it and restart *Fvwm-Nightshade* without changing anything in the process.

This works with themes and layouts, too. If you create under +~/.fvwm-nightshade+ 
the directory structures of themes/layouts as in the +<system>/share/fvwm-nightshade+ 
you can build themes or layouts by your own (see THEME and LAYOUT CREATION below).

Autostart of Applications
~~~~~~~~~~~~~~~~~~~~~~~~~
*Fvwm-Nightshade* has the possibility to start applications while startup 
like email daemons or systemtools (e.g. gkrellm). Therefore a file ".autostart" 
must created in the <user> directory and filled with application commands per 
line e.g.
----
thunderbird
----

Another possibility is to use the function "FuncStartSystrayApplets" in the 
config file but then you have to copy the system file 'config' into the <user> 
directory and add your app like
-----
+ I Test (x nm-applet) exec exec nm-applet
-----


ENVIRONMENT SPECIFICATIONS
--------------------------

Global Variables
~~~~~~~~~~~~~~~~
There are some *Fvwm-Nightshade* specific variables. Valid in the shell and 
Fvwm namespace:
[cols="20%,80%",frame="none",grid="none"]
|====
|FVWM_USERDIR       |It holds the user directory ~/.fvwm-nightshade.
|FNS_SYSTEMDIR      |It contains the system path to the shared files of Fvwm-Nightshade - /usr/local/share/fvwm-nightshade or /usr/share/fvwm-nightshade.
|FNS_INITFILE       |It holds the path to the pre config fns-init.
|FNS_DEBUG          |If you want to raise the message output of Fvwm-Nightshade into ~/.xsession-errors set it to 1. Default is 0.
|$[MenuIconSize]    |It holds the used menu icon size set with fvwm-menu-desktop2-config to adapt menu icons on the fly.
|====

Fvwm related Variables
~~~~~~~~~~~~~~~~~~~~~~
There are also some variables in the *Fvwm-Nightshade* namespace defined in 
the system config and .settings file.

config::
+
[cols="20%,80%",frame="none",grid="none"]
|====
|$[infostore.wallpaper_dir]     |The wallpaper directory located in $[FVWM_USERDIR]/wallpapers.
|$[infostore.fvwm_wallpaper]    |The current wallpaper located in $[FVWM_USERDIR]/.wallpaper.
|$[infostore.ratio]             |The screen ratio used for layout, panel, pager calculations.
|$[infostore.hratio]            |The height ratio used for layout, panel, pager calculations.
|$[infostore.wratio]            |The width ratio used for layout, panel, pager calculations.
|====

settings::
+
[cols="20%,80%",frame="none",grid="none"]
|====
|$[infostore.used_theme]                |The actual theme. Changed dynamically via FuncChangeDecor.
|$[SplashOn]                            |Run Banner at startup.
|$[infostore.used_banner]               |Banner image for FvwmBanner.
|$[infostore.used_font]                 |Default used font for all Fvwm parts.
|$[infostore.fontsize]                  |Default font size for all Fvwm parts.
|$[infostore.used_layout]               |The actual layout.
|$[infostore.x_desks]                   |The actual desktop count X.
|$[infostore.y_desks]                   |The actual desktop count Y.
|$[infostore.used_menutint]             |The actual menu tint level.
|$[use_composite]              	        |Use composite manager.
|$[infostore.comp_command]              |Composite manager command.
|$[infostore.used_windowtransparency]   |The actual (inactive) window transparency level (used by transset).
|$[infostore.used_windowopacity]        |The actual (active) window opacity level (used by transset).
|$[infostore.DesktopIconsOn]            |Use Icons on desktop.
|$[infostore.DesktopScrollOn]           |Activate page scrolling.
|$[infostore.PcmanFmStatus]             |State of pcmanfm.
|$[infostore.additional_wp_dirs]        |Additional wallpaper directories.
|$[infostore.default_terminal]          |The default used terminal program.
|$[infostore.default_editor]            |The default used editor.
|$[infostore.default_browser]           |The default used browser.
|$[infostore.default_transset]          |The default used transset program.
|====


DEBUGING
--------
If you want to debug something there are some functions available you can 
use to get output in +~/.xsession-errors+:

[cols="30%,70%",frame="none",grid="none"]
|====
|FuncPrintDbgMsg <string or value>     |This prints debug message but only if you have set FNS_DEBUG to 1 in <system>/share/fvwm-nightshade/fns-init.
|FuncPrintMsg <name> <string or value> |This function prints normal messages. Yo can use it for normal messages.
|====


THEME CREATION
--------------
A theme consists of the following parts either in +<system>/share/fvwm-nightshade/themes/<name>/+ 
or +<user>/themes/<name>/+:
[cols="10%,90%",frame="none",grid="none"]
|====
|colorsets  |Colorsets of decorations, menus, modules etc.
|decor      |Styles of titlebar, buttons, menus and theme related mouse bindings.
|images     |optional folder for button images (SVG).
|====

If you want to build a new theme create in +<user>/themes/+ a theme directory 
with it’s name and copy the colorset template from +<system>/share/docs/fvwm-nightshade/templates+ 
into the directory.

Two different decors exist - vector based (Clean theme) and image based (Air, Ambiance, 
CrystalBalls, etc.). Copy one of these decor files into your theme directory.

If you want to build an image related theme create also an "images" folder for 
the button images.

IMPORTANT: All image related themes are SVG themes! You can use bitmaps, but than you 
have problems with the button scaling! Also bear in mind If you want to 
send us an image related theme only SVG themes will be accepted.

Now you can adapt the files for your needs. The theme appears automatically 
in the menu
------
Configuration -> Fvwm-Nightshade -> Decoration -> Decors
------
and can be tested by clicking on the name easily.


LAYOUT CREATION
---------------
Layouts are a summary of different parts of modules like FvwmPager, FvwmButtons 
or FvwmIconMan and applets from e.g. conky.

The main part is the layout file where the positions, calculations, key 
bindings and module loadings are done. This can be very tricky and the 
only thing we can say is - look into the Horizontal, Vertical or G2like 
layout to get an overview

Generally the structure is as follow:

1. You have to thought about the positioning of your elements and their 
dependencies to each other.
2. You must define your working area (maximized window) and the Iconbox 
for your iconified windows.
3. Now the "Load" part follows to initialize your modules with the calculated 
positioning values.
4. The next step is to include your modules in the Start Function that your 
theme will be loaded correctly after a restart.
5. In the ReloadLayoutParts function you define all your layout needed to 
function properly after calling it from the configuration menu.
6. Next you have to define your key bindings if any. Mostly needed for the 
pager module or if you have other special things implemented.
7. Then the menus following. Also needed mostly for the pager.

You can test it easily by clicking your layout name under
----
Configuration -> Fvwm-Nightshade -> Decoration -> Layouts
----

if it found under +<user>/layouts/+. It appears automatically.

That’s it. Not much but hopefully enough for playing ;).

LANGUAGE CREATION
-----------------
*Fvwm-Nightshade* supports a couple of languages - at the moment german, 
russian, spanish, italian and french. If you want to create your own 
translation you can use the "fvwm-nightshade.pot" template located in +<system>/templates+.

We support *two* locations where your translation can copy to:

. The system wide in +/usr/share/locale/+ or +/usr/local/share/locale/+
. The user wide in +~/fvwm-nightshade/locale/+

The following Howto uses the user wide one.

Steps for your own translation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
. Create the directory with its' sub directories:
+
----
~/.fvwm-nightshade/locale/<your_lang>/LC_MESSAGES
----
. Copy fvwm-nightshade.pot to this directory:
+
----
$> cp <system>/templates/fvwm-nightshade.pot ~/.fvwm-nightshade/locale/<your_lang>/LC_MESSAGES/fvwm-nightshade.po
----
+
TIP: You can look to +/usr/share/locale+ which token is normally used for your language.

. Open it with your favorite editor, fill out the header and translate 
the messages into your language. 

. Create the machine readable code with _msgfmt_
+
----
$> msgfmt fvwm-nightshade.po -o fvwm-nightshade.mo
----

. Restart *Fvwm-Nightshade*.

Now all menus, messages and tools should be shown in your language.

*Remark:*

* Some messages have a fixed size and spaces at the beginning or the end. 
They should used in the translation just as well! For example:
+
----
msgid "              (E.g. 10, 11, 13)"
msgstr "              (z.B. 10, 11, 13)"
----
* Menu entries have *&* for hotkeys. So you should set them that no double 
underlines exist.
* Every time you change something in the *po* file a restart of *Fvwm-Nightshade* 
is necessary if it is related to menu entries. All others like in *FvwmScripts* 
or *FvwmForms* are shown after restart of the application.

TIP: You can use *poedit* or *KBabel* instead of an editor for translation. It's 
a matter of choice ;-) ...

If you need more information about the used translation process see 
http://www.gnu.org/software/gettext/manual/gettext.html

MODULE CREATION
---------------
If you want to create your own modules based on fvwm-perlib you have three 
possibilities to put them in:

. Fvwm its own directory, usually /usr/lib/fvwm/<Fvwm-version/
. Fvwm-Nightshades system directory - <system>/share/fvwm-nightshade/lib/
. The user directory in <user>/lib/

The easiest way is the user directory. Create the directory ~/.fvwm-nightshade/lib 
and put your module in it. Now you can start it from within FvwmConsole with

----
Module <Modulename>
----

or in the StartFunction with

----
+ I Module <Modulename>
----

AUTHORS
-------
(C) 2013 - 2016 by the Fvwm-Nightshade team <fvwmnightshade@gmail.com>.


COPYRIGHT
---------
*Fvwm-Nightshade* and all the scripts and other files coming with 
the distribution are subject to the GNU General Public License (GPL). 
Please refer to the COPYING file that came with *Fvwm-Nightshade* for details.


BUGS
----
Bug reports can be sent to the fvwmnightshade-workers mailing list at 
<https://groups.google.com/forum/?hl=en#!forum/fvwmnightshade-workers>
or submit them under https://github.com/Fvwm-Nightshade/Fvwm-Nightshade/issues.




