# morc_menu_v1.conf
# configuration file in support of morc_menu
#
# NOTE: All definitions must begin at the beginning of a line, ie. no
# leading whitespace.

# To begin allowing you to customize the 'look' or 'skin' of the menu,
# some explanation is called for: By default, the script uses a
# low-resource front-end application called 'dmenu' to present its
# menus. In this configuration file, you are be able to change the
# parameters that the script uses to invoke 'dmenu', or you may
# replace 'dmenu' with another front-end. The script has been tested
# with front-ends 'rofi' and 'zenity', and may also work with 'yada'
# and others. The script also allows you to import 'look' and 'skin'
# data from definitions in other configuration files, to help you
# maintain a consistent 'look' across different programs.

# If you wish to import import 'look' and 'skin' data from definitions
# in other configuration files, you may need to perform that first,
# before defining how you wish to invoke your chosen front-end
# (sensible, as in that situation, the invocation will be using
# definitions from those files). You may define as many
# 'external_definition_file's as you like. They will be read in the
# order you present them here, so in a case of conflicting
# definitions, the last one 'wins'. If the file does not exist or
# can't be read, it is ignored, and the script continues. The script
# will only read lines in the form 'foo=bar'. In our default example
# we are reading a configuration file meant for 'dmenu' usage.
external_skin_definition_file=${HOME}/.dmenurc

# Customize where on the screen you wish the menu to appear. If you
# want the menu to appear at wherever the mouse pointer is resting,
# set the variable 'use_mouse_position' to 'TRUE', and you're done -
# the script will figure out the correct x and y positions at
# run-time.
# use_mouse_position=TRUE
use_mouse_position=TRUE
# Otherwise, the script will always place the menu at the 'x_position'
# and 'y_position' definitions you set below. All the numeric values
# in this block are measured in pixels.
# IMPORTANT:
#   Menu positioning only works when the 'menu_cmd' definition below
#   correctly uses the string literals X_POSITION, Y_POSITION, as is
#   the case in the default and in the examples below. Additionally,
#   MENU_LINES and MENU_WIDTH must be correctly used, as in the
#   examples below, in order for dynamically positioned menus not to
#   try to display beyond the screen edge, and for there not to
#   display unnecessary whitespace.
x_position=300
y_position=20
# Until we learn how to directly measure font width and height, we
# need to set 'line_height', 'avg_char_width', and 'menu_width'
# manually by trial and error. If 'avg_char_width' is not zero, then
# 'menu_width' will be ignored, and the value will be calculated at
# run-time.
line_height=20
avg_char_width=9
avg_err_char_width=10
menu_width=350
err_menu_width=350

# The third and final, step in customizing the 'look' or 'skin' of the
# menu is to modify how the script invokes its menu command
# ('menu_cmd') and its error notification (error_cmd'). In general,
# the options available to you are limited by those of your chosen
# front-end, so refer to its man page and other documentation.
# Additionally, you may refer to variables defined in one of the
# 'external_skin_definition_file's you specified above, and you may
# use variables 'x_position' and 'y_position' to set where on the
# screen you want your menu. Below is the default and some examples.
# IMPORTANT:
#   In order for the script to properly position the menu, these
#   definitions must include parameters that correctly use the string
#   literals X_POSITION, Y_POSITION, MENU_LINES, and MENU_WIDTH, as is
#   the case in the default and in the examples below. Additionally,
#   MENU_LINES and MENU_WIDTH must be correctly used, as in the
#   examples below, in order for dynamically positioned menus not to
#   try to display beyond the screen edge, and for there not to
#   display unnecessary whitespace.
#
# EXAMPLE MENU COMMANDS
# =====================
# 1] The script's default, using the plain version of 'dmenu'
#      menu_cmd="dmenu -i -l MENU_LINES "
# 2] Using the extra features of 'dmenu-manjaro' (or other versions
#    of dmenu packaged with the official patches, eg. 'xyw')
#      menu_cmd="dmenu -i -l MENU_LINES -x X_POSITION -y Y_POSITION -w MENU_WIDTH "
# 3] Using a variable defined in an external_skin_definition_file,
#    in this case ${HOME}/.dmenurc
#      menu_cmd="dmenu -i -l MENU_LINES -x X_POSITION -y Y_POSITION -w MENU_WIDTH ${DMENU_OPTIONS}"
# 4] Using 'zenity' and 'rofi' - Because there ought to be some
#    reward for reading all this documentation, note the use of
#    the embedded linux command 'uname' to set the zenity column title. 
#      menu_cmd="zenity --list --column=$(uname -no) "
#      menu_cmd="rofi -dmenu -i "
menu_cmd="dmenu -i -l MENU_LINES "

# Customize the 'look' or 'skin' of the error messages by modifying
# the following string, which, as above for the menu command, will be
# used to invoke your choice of menu front end.
# Using 'dmenu' (the default)
#error_cmd="dmenu -i -l 40 -nb red -nf black -fn DejaVu"
error_cmd="dmenu -i -l 40 -nb red -nf black -fn DejaVu"
# Using 'dmenu-manjaro'
#error_cmd="dmenu -i -l 40 -x 500 -y 150 -w MENU_WIDTH -nb red -nf black -fn DejaVu"
# error_cmd="zenity --error "
# error_cmd="rofi -dmenu -i "

# Distinguish between an executable item and a sub-menu selection.
# WARNING: Your customizations for the combination of the following
# two variables, menu_prefix and menu_suffix, must uniquely
# distinguish a sub-menu entry from an executable, in order for the
# script to do just that. Thus, for example, if you set both variables
# to NULL, the script will think all entries are sub-menu identifiers,
# and no application entry will execute.
menu_prefix=" [menu]: "
menu_suffix=" >"
# If a 'menu_suffix' is defined, you can have the script align all
# vertically, but this only works if you are using a fixed width font,
# so if you've selected a proportional font, set 'align_suffix' to
# 'FALSE'.
align_suffix=TRUE

# Desired categories: Any single .desktop definition can include an
# arbitrarily long list of categories for itself, which would bloat
# the menu with duplicate clutter, so the following space-delimited
# variable white-lists the desired categories.
desired_categories="Favorites Settings Development Documentation Education System Network Utility Graphics Office AudioVideo"

# Category aliases: The common convention seems to be to rename some
# categories, as in the default below. We implement the renaming sing
# an associative array in which the index is the category as defined
# in the .desktop file, and the value is the desired output
declare -A category_aliases=( [Utility]=Accessories [AudioVideo]=Multimedia [Network]=Internet )

# Unwanted names, execs, and specifics: Entries with these names or
# execution statements should be black-listed from the menu, depending
# upon the value of variables 'exclude_from_static' and
# 'exclude_from_dynamic'. Note that this will NEVER be done for an xml
# input file, as the purpose of that command is to show what the
# external xml generator produces. Likewise, it will never be done for
# commands 'build usr' and 'build loc'. The lists are bash arrays, so
# all rules for that data structure apply. The array
# 'unwanted_specific' is meant for the special case in which a name or
# exec may have identical entries in multiple categories and only some
# of them are desired excluded. In such a case, place into the array
# 'unwanted_specific' an entry in the form of the script's menu txt
# file entry. ie "Category---Name---Execution_string" where "---" is
# the field delimiter, and spaces are permitted within fields when the
# entire entry is properly quoted.
unwanted_names=( )
unwanted_execs=( )
unwanted_specifics=( )
exclude_from_static="FALSE"
exclude_from_dynamic="TRUE"

# Additional entries: Force inclusion of entries on this list,
# depending upon the values of variables 'add_to_static' and
# 'add_to_dynamic'. Note that this will NEVER be done for an xml input
# file, as the purpose of that command is to show what the external
# xml generator produces. Likewise, it will never be done for commands
# 'build usr' and 'build loc'. The list is a bash array, so all rules
# for that data structure apply. Each entry is in the form of the
# script's menu txt file entries. ie
# "Category---Name---Execution_string" where "---" is the field
# delimiter, and spaces are permitted within fields when the entire
# entry is properly quoted. In order to add an entry to your list of
# 'favorites', ie. those that appear at the top of the main menu, not
# under any category, use category '000'
additional_entries=( )
add_to_static="FALSE"
add_to_dynamic="TRUE"

# Maximum number of backups to keep: because almost no one will notice
# accumulating cruft. Backups are automatically created in the user's
# ${HOME}/.config/morc_menu folder, in the form
# "morc_menu${ext}_%y-%m-%d-%T" where ${ext} is either ".txt"
# or "_xml.txt" and the suffix is a timestamp. If you want to keep a
# particular backup forever, rename it to fail a match against
# "morc_menu${ext}_*"
max_num_backups=5

# Information about the menu and how to customize it are by default
# presented in a trailng menu entry "about morc_menu". You may exclude
# presentation of that menu item by setting 'exclude_about' to TRUE
#exclude_about="TRUE"
exclude_about="FALSE"

# Reading a system-wide menu definition file: By default, if morc_menu
# finds a menu definition file at /etc/morc_menu.txt, it kind of
# cheats in that it uses that file instead of creating one
# dynamically. You may over-ride this behavior by setting
# 'ignore_system_txt='True'. The 'cheat' is supposedly in the interest
# of nominal speed and efficiency (at possible cost of accuracy), and
# the system-wide file would only exist by system-administrator action
# / consent / recklessness. Consult your sysadmin to learn how the
# system-wide definition file is created and updated in your
# particular case. Common ways are by using 'inotify' to monitor
# changes in /usr/share/applications, or by applying hooks to the
# system's package management system.
ignore_system_txt="FALSE"