JWM Kit - A set of Graphical Apps to simplify use of JWM (Joe's Window Manager) <https://codeberg.org/JWMKit/JWM_Kit>
Copyright © 2020-2022 Calvin Kent McNabb <apps.jwmkit@gmail.com>

This file is part of JWM Kit.

JWM Kit is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License, version 2,
as published by the Free Software Foundation.

JWM Kit is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with JWM Kit.  If not, see <https://www.gnu.org/licenses/>.

### The Wiki
--------------------------------------------------------------------------------
You can find the JWM Kit Wiki at https://codeberg.org/JWMKit/JWM_Kit/wiki
The wiki includes the majority of the information in the document and provides
a much nicer presentation. The wiki also provides plenty of images which help
deliver the content presented.

### The manpages
--------------------------------------------------------------------------------
Each tool provided by JWM Kit has it's own man page.  These man pages provide
a basic amount of information, but may not be as detailed as the information
provided in the wiki.

### Additional documentation
--------------------------------------------------------------------------------
JWM Kit Does provide additonal detailed information regarding command line
syntax for jwmkit_logout and jwmkit_easy_menu.  On most systems you should find
these documents in /usr/share/doc/jwmkit/ if JWM Kit is installed.

### What's in a name
--------------------------------------------------------------------------------
The offical orginal name was JWM Kit, but the space in the name does not honor
the naming specification required for software packaing in most linux distros.
Due to this it is common to see JWM Kit refered to as JWMKit or the less common
JWM-Kit. JWM Kit should be packaged under the name jwmkit and you will notice
many of the filenames start with jwmkit.  If you wish to search the internet for
for JWM Kit content you may have better results search for JWMKit as oposed to 
JWM Kit.


#### JWM Kit's Features
--------------------------------------------------------------------------------

-   No part of this software is designed to runs in the background. It
    only runs when the user starts it, and properly quits when "closed",
    or for notifications will close when timed out in a few seconds.
-   Set the desktop background for each desktop.
-   Configure the number of virtual desktops'
-   configure desktop and window behavior
-   Preview and select JWM themes
-   Create and edit JWM themes
-   Switch JWM button sets (window buttons like: close, max, min, etc)
-   Configure the appearance and behavior of JWM trays, and menus.
-   Add & Remove JWM trays and menus
-   Add & Remove items to those trays, and menus
-   Configure commands (scripts, apps, etc) to run when JWM starts,
    restarts and/or shutdown
-   Add/remove icon paths and change the order (where JWM finds icons)
-   Save current Screen configuration for startup (resolution/frame
    rate/monitor position/etc)
-   Configure key board shortcuts for custom controls / quick access
-   Add a simple popup calendar to the tray
-   Add voume notification and control to an tray icon or keyboard
    shortcuts
-   Customize Freedesktop (.desktop) entires
-   Customized autogenerated menus
-   Settings panel (Similar XFCE's Settings dialog)
-   Create a Restore Point of the current JWM Configuration
-   Restore the JWM configuration to a previous State
-   Restore the JWM configuration to JWM Kit's default


### Dependencies *
--------------------------------------------------------------------------------

Required
-   python3
-   python3-gi
-   gir1.2-gtk-3.0

Optional 
-   alsa-utils	(for pop up volume control)
-   sndio	(for pop up volume control)

Detail Info reqarding Dependencies

- This list of dependencies uses Debian based packages name. The equivalent
  package may have a different name on non-Debian based distributions.
- The debian version of sndio is outdate and is not supported. If you wish to
  use the sndio features in debian you will have to compile from source.
 

#### JWM Kit's Tools
--------------------------------------------------------------------------------

* NOTE: JWM Kit is a suite of system tools. Some packaged version of JWM Kit may
	not include all of the tools. If fact this documentation does not include
	all them. If you are interested in a tool and it is missing from your
	installation you can get it here:
	<https://codeberg.org/JWMKit/JWM_Kit>


Name: JWM Kit Appearance -------------------------------------------------------
Filename: jwmkit_appearance
Purpose: Preview and Switch the JWM Theme, and/or button set.
         Create and edit themes. Recolor button sets.
NOTE: You can provide your own previews, or JWM Kit will create a preview.
NOTE2: If JWM Kit fails to create previews for a theme, that theme has errors.
NOTE3: If JWM Kit's previews has incorrect color. The Theme uses color names
       not compatible with JWM Kit. The theme should still work.
Bonus Feature: Create a modified copy of a SVG button set with different colors.

Name: JWM Kit Battery Menu -----------------------------------------------------
Filename: jwmkit_bat_mu
Purpose: Create a JWM menu that provides battery info
usage: create a dynamic menu on a traybutton. Clicking the button will give an
       updated battery status.  Example: Charging 81%

Name: JWM Kit Button Menu-------------------------------------------------------
Filename: jwmkit_button_mu
Purpose: Create the button config for the selected button set.
Note: JWM Kit Appearance depends on this file.

Name: JWM Kit Calendar ---------------------------------------------------------
Filename: jwmkit_calendar
Usage: Simple pop up calendar. Bind to a mouse click on the clock for
behavior similar to other desktops.
Note: if you have issues (peformance, etc) use jwmkit_yad_cal
Alternative: jwmkit_yad_cal

Name: JWM Kit Desktops ---------------------------------------------------------
Filename: jwmkit_desktops
Usage: Set the Desktop background. Set a background for each virtual desktop.
       Configure desktop and window behavior. 
Features: ROX, SpaceFM, & PCManFM Desktops are supported as well as JWM

Name: JWM Kit Easymenu ---------------------------------------------------------
Filename: jwmkit_easymenu
Usage: Generate a Application Menu using freedesktop files. 
Note: See README_easymenu.txt for advanced syntax options.
Feature: JWM Kit Menus provides graphical configuration of Easy Menu.

Name: JWM Kit First Run --------------------------------------------------------
Filename: jwmkit_first_run
Usage: Configure how JWM Kit request permission and help the user prepare
       their system for JWM Kit. Installing JWM Kit's default JWM config,
       using a restore point, or manually with the info provided.
Note: JWM Kit requires the JWM config to follow a strict structure. This tool
      assist the user in creating a compliant configuration.
Note: JWM Kit may need to request permission using su/sudo/doas/etc. This tool
      assist the user in configuring JWM Kit to use a compatible solution.

Name: JWM Kit Freedesktop ------------------------------------------------------
Filename: jwmkit_freedesktop
Additonal Files : jwmkit_button_mu - Generates the button config for the 
                  selected button set.
Usage: Create and modify desktop entry file (AKA launchers or .desktop files.
Note: By default this tool uses the system's default icon set. To use the icons
      defined in you jwm config start the app with the "jwm" Parameter.
      Example: jwmkit_freedesktop jwm
Note: By editing an apps freedesktop file you can change it's icon, and
      categories in auto-generated menus. Example you could move an app 
      from System to Settings, or remove unwanted categories to prevent
      improper placement or multiple listings. 

Name: JWM Kit Groups Editor ----------------------------------------------------
Filename: jwmkit_groups
Usage: Specify options for a group of programs by their name and/or class  
Hint: If you need a specific instance of an app to follow a group policy,
      but do not want the app to always follow the policy,  you can make
      a symbolic link to the binary and assign the rules to the link.

Name: JWM Kit Icon -------------------------------------------------------------
Filename: jwmkit_icons
Usage: Tell JWM where to find icons. Add as many paths as needed, and arrange 
       the order for search priority. The included search tool will help
       your find icons, and you can preview the directories of the search
       results with the view button before adding them to the list.

Name: JWM Kit Keys -------------------------------------------------------------
Filename: jwmkit_keys
Usage: Configure key bindings, and mouse actions 
Example: Alt+F2 will launch the run prompt

Name: JWM Kit Logout -----------------------------------------------------------
Usage: A simple logout menu with Cancel, Logout, Reboot, and Shutdown.
Filename: jwmkit_logout
Note: Use JWM Kit First Run to configure figure how JWM Kit peforms actions 

Name: JWM Kit Menu Editor ------------------------------------------------------
Filename: jwmkit_menus
Usage: Configure the appearance and behavior of JWM menus. Add, remove,
       and edit apps, RootMenus, menus, specify icons, etc

Name: JWM Kit Pop Volume -------------------------------------------------------
Filename: jwmkit_popvolume
Additonal Files : jwmkit_popmixer, and jwmkit_popmuter - -
		  - - interact with alsa/sndio and provides visual feedback
Usage: Assign volume notification to a tray icon or key shortcuts. Choice of 
       horizontal or vertical slider or simple display percent of max volume.
       (Un)mute displays the appropriate icon. To be clear it does not run in the
       background. Mouse movement or key presses triggers it to run and it 
       automatically closes in seconds.
Syntax: For info on this program’s syntax enter this command in the
terminal: jwmkit_popvolume help
Note: Total of 3 file. The popmixer, and popmuter should not be called
      directly. They are used by JWM Kit Popvolume

Name: JWM Kit Repair & Restore -------------------------------------------------
Filename: jwmkit_repair
Purpose: Provide tools to repair the JWM configuration.
	- Report status of the current JWM config.
	- Provide a helpful feedback useful in repairing damaged config files
	- Create restore points of the JWM configuration
	- Create the default config for new installs (via jwmkit_first_run)
	- Revert to a Restore Point
	- Revert to JWM Kit's default config
        - Create or fix the JWM Kit settings file

Name: JWM Kit Settings ---------------------------------------------------------
Filenames: jwmkit_settings
Usage: A simple "settings manager" as seen in larger desktop enviorments.
Note: This can replace the settings category in your application menu.

Name: JWM Kit Startups ---------------------------------------------------------
Filename: jwmkit_startups
Usage: Configure commands (scripts, apps, etc) to run when JWM starts, restarts
       and/or shutdown. Features a display button to simplify adding your 
       current display configuration to startup.

Name: JWM Kit Trays  -----------------------------------------------------------
Filename: jwmkit_trays
Usage: Configure the appearance and behavior of JWM trays as well as the items
       contained in the tray. Add, remove, & edit all possible items types,
       icons, etc and configure their behavior.

Name: JWM Kit YAD Pop Calendar -------------------------------------------------
Filename: jwmkit_yad_cal
Usage: wrapper to give pop up action to YAD's Calendar. 
Note: Alternative to JWM Kit Calendar

#### JWM Kit's Utils Module
--------------------------------------------------------------------------------

Filename: jwmkit_utils.py
Purpose: Functions used by the other apps. For example the about dialog.
Note: This file is a dependancy for the other files in this kit.
Note: This is a module not an executable and should be installed in correct path
      for debian this is /usr/lib/python3/dist-packages/

### Notes
--------------------------------------------------------------------------------

Note - Terminal apps: JWM Kit Tray & Menus intelligently chooses a terminal
       emulators when creating launchers for terminal based apps. 
       If you need/want to use a different terminal, you must manually
       edit the command entry for the each of the terminal apps.
...and Easy Menu also intelligently chooses a terminal, but allows you to
       specify a specific termianl for the generated menus.

Note - Root Privilege: Applications selected from the Application list are add
       exactly as presented in their Freedesktop file. When selecting an item
       that requires root access, it is up to the user to ensure that the method
       used to request permission is avalible on your system. It may be
       neccessary to edit the command entry or use jwmkit_freedesktops to edit
       the applications execute command. The later option bein more effective as
       it will affect the entire system.


#### JWM Kit config files and icons
--------------------------------------------------------------------------------

JWM Kit stores it's icons here: /usr/share/pixmaps/jwmkit/
JWM Kit's creates the following configuration file in ~/.config/jwmkit/

LastWallDir
       Stores the last browsed wallaper directory

settings
	The settings file records a history of removed, but not deleted menus
	and trays so they can be restored if desired. This file also help
	JWMKit find a file if it is unable to locate the file by searching your
	.jwmrc file. This could happen if a file contains no tag that identify
	the purpose of the file. If you need to create or fix the settings file
        use jwmkit_repair. optionally, you can easily create/edit the file
	yourself. Syntax and example below.

setting_su
	The setting_su file is created by jwmkit_first_run and is used to
	configure how JWM Kit Request permission.


----------------------- * End of General Information  * ------------------------


-------------------------  * Technical information *  --------------------------


### Syntax of the file   ~/.config/jwmkit/settings
--------------------------------------------------------------------------------

---------------------------- * IMPORTANT * ------------------------------
									 |
* In most cases it should be possible to create the setting file using   |
  JWM Kit Repair without manually editing the file.			 |
									 |
* Do not list active Tray and Menu files in the settings files.		 |
  Only list inactive trays and menus you wish to restore in the future	 |
									 |
---------------------------- * IMPORTANT * ------------------------------

Tray and Menu entries are for unused config files. These entriess allow JWM Kit
to provide an easy "restore" option for these configs. Such files could be
prepared for future use (like a templete), or may have been removed from a 
previous configuration.

Remaining entries are the same as the Includes in the .jwmrc file excluding
the tray, and menu files. Define each entry with the identifying key.

Syntax rules.
|--XML type-|------Rule-----|----Key----|--Recommended----|--example--|
|-----------|---------------|-----------|-----------------|-----------|
|---Tray----|must start with|---tray----|tray-description-|tray-top---|
|---Menu----|must start with|---menu----|menu-description-|menu-main--|
|--startup--|must start with|---start---|----startups-----|-startups--|
|icon paths-|must start with|---icons---|-----icons-------|--icons ---|
|preferences|must be exactly|preferences|---preferences---|preferences|
|---keys----|must be exactly|---keys----|------keys-------|---keys----|
|--groups---|must start with|---group---|-----groups------|--groups---|
|---theme---|must be exactly|---theme---|------theme------|---theme---|

Note: All entries above are required. Previously Theme was optional.
      This is no longer the case. It needs to be present.
Note: When examining the settings file you may see other entries with keys
      words not listed here.  Example: button=, menu, tray, etc. These entries
      are automatically handled by JWM Kit. No need to add them manually unless
      you really know what you are doing.

settings file example:
---------------------------------------------
|                                            |
|  tray-top=$HOME/.config/jwm/tray1          |
|  startups=$HOME/.config/jwm/startups       |
|  icons=$HOME/.config/jwm/icons             |
|  preferences=$HOME/.config/jwm/preferences |
|  keys=$HOME/.config/jwm/keys               |
|  groups=$HOME/.config/jwm/groups           |
|  theme=$HOME/.config/jwm/theme             |
|                                            |
---------------------------------------------


#### JWM Kit's behavior
--------------------------------------------------------------------------------

-   Entries in JWM Kit Startups tool must have at least one of option
    selected. Options are Startup, Restart, Shutdown. Items without an
    option selected will not be saved.

-   Comments are not preserved in the XML files. So don't bother adding
    them. It's best to avoid them. Comments should have no ill effect on
    JWM Kit.

-   JWM Kit uses the $HOME variable to represent the users home
    directory. Thus allowing a config files to be used by another user.

#### JWM Kit's Validation check  
--------------------------------------------------------------------------------

JWM Kit does check the config files for proper form and syntax.  Sometimes  
it may check a file for it's intended purpose. While these checks are
helpful, they are limited.  JWM Kit maybe unable to use a file If it was  
improperly edit either manually or by another program.
