   Kickshaw - A Menu Editor for Openbox

   Copyright (c) 2010–2021        Marcus Schätzle

   This program is free software; you can redistribute it and/or modify
   it under the terms of the GNU General Public License as published by
   the Free Software Foundation; either version 2 of the License, or
   (at your option) any later version.

   This program 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 Kickshaw. If not, see http://www.gnu.org/licenses/.


---

DEPENDENCIES

Kickshaw is dependent on GTK3 and, since version 1.60, PCRE2. The PCRE2 
library must have been built with unicode support, which is usually the 
case. The code makes use of GNU extensions, so a compiler is needed that 
supports them. Since the standard compilers on current systems provide such 
support this shouldn't cause any extra preparations (Clang supports the GNU 
extensions used by Kickshaw).

The program is not dependent on Openbox; it can be used inside all window 
managers/desktop environments that support GTK applications.

COMPILING AND INSTALLING THE PROGRAM

A makefile is included in the source directory. "make" and "make install"
are sufficient to compile and install this program; there is no configure 
script file which has to be started first. The default compiler set in the 
makefile is GCC, but can be switched to Clang by using "make CC=clang". An 
installation of a GTK3 devel package should supply all packages that are 
needed for compilation, if they haven't been installed yet.

By the means of conditional compilation it is ensured that the program can 
be compiled on older systems that have a GLib version >= 2.44 installed.
(This version of GLib was released in 2015). The minimum GTK version is 
3.18 (also released in 2015). As of 2021, apart from exceptions such as 
Red Hat Enterprise Linux older versions of GTK/GLib have become rare in 
active installations so a minimum version check is not included in the 
source code and there is no extra configure script for this purpose.

The standard used for compilation is by default gnu99.

REQUIREMENTS REGARDING MENU FILES

The program uses GLib's XML subset parser to read menu files, so it will 
be able to read a menu file regardless its formatting; it is necessary 
though that the file is encoded in UTF-8 (the program checks if the text of 
the menu file is valid UTF-8). In the case of an error the program gives a 
detailed error message, if possible. In some cases, for example if options 
have a wrong value or an image file that can't be loaded, the program will 
offer the option to correct such errors to avoid a premature termination.

FEATURES

- Support for icons. Changes done outside the program to the image files, 
  for example a replacement of the image file with a new one under the 
  same name, are taken over within a second, and the program will show the 
  new image.
- (Unlimited) Undo/Redo
- (Multirow) Drag and drop
- UTF-8 based search functionality with optional case sensitivity, 
  "word only" search and processing of regular expressions (incl. validity 
  check)
- Find and replace with the same options as for the search functionality 
  and prevention of invalid replacements (creating double menu IDs, 
  "enabled" options other than "yes" and "no")
- It is impossible to accidentally create a double menu ID, either by 
  entering it manually or by a find and replace action. The program will 
  always block this and show an error message.
- Auto-backup of overwritten menu (can be deactivated)
- Auto-reconfiguration of the menu after saving
- Context menu
- Editable tree view cells (dependent on the type of the content type)
- Fast and compact, avoidance of overhead (programmed natively in C, 
  only dependency is GTK3, no additional packages or files used with the 
  exception of a settings file created by the program itself, no inclusion 
  of external Glade UI files)
- Dynamic, context sensitive interface
- Autosave
- The GUI adapts to dark themes/themes with a gradient
- The tree view can be customised (show/hide columns, grid etc.)
- In the "About" dialog, users are informed about the availability of a 
  newer version than the one currently installed (requires active internet 
  connection)
- The text of the menu file is checked for UTF-8 validity
- The program informs the user if there are missing menu/item labels, 
  invalid icon paths and menus defined outside the root menu that are not 
  included inside the latter. By request the program creates labels for 
  these invisible menus/items, integrates the orphaned menus into the root 
  menu and opens a file chooser dialog so that invalid icon paths can be 
  corrected.
- Handling of double/contradictory menu attribute values (explained in 
  the "Hints" window, see section below)
- Deprecated "execute" options are converted to "command" options
- The options of an "Execute" action and "startupnotify" option block can 
  be auto-sorted to obtain a constant menu structure
- The GUI can be reconfigured (server side decorations <-> client side 
  decorations, menu button <-> menubar)
- Saved menu files can either have a separate root menu with links to the 
  menus, which are then listed above the root menu, or have everything 
  packed into the root menu. It is also possible to choose between tabs 
  and four spaces for indentations.

The variety of English used in the program is American English.
Capitalization adheres to the APA Style.

Static analyzers that are used to find bugs, superfluous code, etc. are 
Cppcheck, Infer, and Clang Static Analyzer.
Bug reports can be submitted at
https://savannah.nongnu.org/bugs/?group=obladi&func=additem
This page can also be reached via the "Help" menu of the program.

HINTS

Hints for the usage of Kickshaw can be found in the program by choosing 
"Hints" from the "Help" menu or by pressing F1.

KNOWN ISSUE

(As of July 2021)
Sometimes, when changing the client decorations type or the menu type, 
the app won't restart as expected, apparently because of a problem with 
D-Bus. In that case, simply restart Kickshaw manually.
