buskill_gui.py

#!/usr/bin/env python3
"""
::

  File:    buskill_gui.py
  Authors: Michael Altfield <michael@buskill.in>
  Created: 2020-06-23
  Updated: 2026-06-02
  Version: 0.6

This is the code to launch the BusKill GUI app

For more info, see: https://buskill.in/
"""

################################################################################
#                                   IMPORTS                                    #
################################################################################

import packages.buskill
from packages.garden.navigationdrawer import NavigationDrawer
from packages.garden.progressspinner import ProgressSpinner
from buskill_version import BUSKILL_VERSION

import os, sys, re, webbrowser, json, operator, importlib

import multiprocessing, threading
from multiprocessing import util

import logging
logger = logging.getLogger( __name__ )
util.get_logger().setLevel(util.DEBUG)
multiprocessing.log_to_stderr().setLevel( logging.DEBUG )
#from multiprocessing import get_context

import kivy
from kivy.app import App
from kivy.properties import ObjectProperty, StringProperty
from kivy.clock import Clock
from kivy.metrics import dp
from kivy.compat import string_types, text_type
from kivy.animation import Animation

from kivy.core.text import LabelBase
from kivy.core.text import Label as CoreLabel
from kivy.core.clipboard import Clipboard
from kivy.core.window import Window

Window.size = ( 300, 500 )

# grey background color
Window.clearcolor = [ 0.188, 0.188, 0.188, 1 ]

from kivy.config import Config
from kivy.config import ConfigParser

from kivy.uix.widget import Widget
from kivy.uix.label import Label
from kivy.uix.button import Button
from kivy.uix.gridlayout import GridLayout
from kivy.uix.boxlayout import BoxLayout
from kivy.uix.floatlayout import FloatLayout
from kivy.uix.modalview import ModalView
from kivy.uix.popup import Popup
from kivy.uix.togglebutton import ToggleButton
from kivy.uix.screenmanager import ScreenManager, Screen
from kivy.uix.actionbar import ActionView
from kivy.uix.settings import Settings, SettingSpacer
from kivy.properties import ObjectProperty, StringProperty, ListProperty, BooleanProperty, NumericProperty, DictProperty
from kivy.uix.recycleview import RecycleView

################################################################################
#                                  SETTINGS                                    #
################################################################################

# n/a

################################################################################
#                                  FUNCTIONS                                   #
################################################################################

# TODO: figure out why dialog's Label fonts aren't being updated
# TODO: update this to also update RecycleView's data dicts
def update_font_recursive(widget):

	# is widget actually a list of widgets?
	if type(widget) == type(list()) \
	 or isinstance(widget, kivy.properties.ObservableList):
		# they sent us a list of widgets; call ourselves for each
		for w in widget:
			update_font_recursive(w)

	if hasattr(widget, 'dialog'):
		update_font_recursive(widget.dialog)

	if isinstance(widget, Label):

		default_font = Config.get('kivy', 'default_font')

		# is this value actually a list?
		if type(default_font) == type(list()):
			font_name = default_font[0]
			font_path = default_font[1]
		else:
			# the default_font setting is not a list; it's probably a string that
			# represents a list

			try: 
				# hack to convert a string of a list to an actual list
				# * https://stackoverflow.com/a/35461204/1174102
				default_font = json.loads(default_font.replace('\'', '"'))
				font_name = default_font[0]
				font_path = default_font[1]

			except Exception as e:
				pass

		widget.font_name = font_path
	elif hasattr(widget, 'children'):
		for child in widget.children:
			update_font_recursive(child)

################################################################################
#                                   CLASSES                                    #
################################################################################

class MainWindow(Screen):

	toggle_btn = ObjectProperty(None)
	status = ObjectProperty(None)
	menu = ObjectProperty(None)
	actionview = ObjectProperty(None)
	actionbar = ObjectProperty(None)

	dialog = None

	def __init__(self, **kwargs):

		# check to see if this is an old version that was already upgraded
		# as soon as we've loaded
		Clock.schedule_once(self.handle_upgrades, 1)

		super(MainWindow, self).__init__(**kwargs)

	def on_pre_enter( self, *args ):

		msg = "DEBUG: User switched to 'MainWindow' screen"
		print( msg ); logger.debug( msg )

		# set the bk object to the BusKillApp's bk object
		# note we can't set this in __init__() because that's too early. the
		# 'root_app' instance field is manually set by the BusKillApp object
		# after this Screen instances is created but before it's added with
		# add_widget()
		self.bk = self.root_app.bk

	# called to close the app
	def close( self, *args ):
		sys.exit(0)

	def toggle_menu(self):

		self.nav_drawer.toggle_state()

	def toggle_buskill(self):

		try:
			# attempt to tell the buskill object to arm/disarm
			self.bk.toggle()

		except Exception as e:
			# buskill failed to arm/disarm; tell the user
			
			msg = "Unable to toggle buskill state"
			# for some reason 'e' is sometimes undefined, but we can get the
			# exception thrown by the child process from its 'exception'
			# instance field
			if e:
				msg += "\n\nException: " +str(e)
			if self.bk.usb_handler.exception[0]:
				msg += "\n\nException: " +str(self.bk.usb_handler.exception[0])

			print( msg )
			self.dialog = DialogConfirmation(
			 title = '[font=mdicons][size=30]\ue002[/size][/font] Error',
			 body = msg,
			 button='',
			 continue_function = None
			)
			self.dialog.b_cancel.text = "OK"
			self.dialog.open()

			return False

		if self.bk.is_armed:
			self.toggle_btn.text = 'Disarm'
			self.status.text = "BusKill is armed\n"
			self.status.text += "with '" +str(self.bk.trigger)+ "' trigger."
			self.toggle_btn.background_color = self.color_red

			# set the actionview of every actionbar of every screen to red
			for screen in BusKillApp.manager.screens:
				for child in screen.actionbar.children:
					if type(child) == ActionView:
						child.background_color = self.color_red

			# check for messages from the usb_handler child process
			Clock.schedule_interval( self.bk.check_usb_handler, 0.01 )

		else:
			self.toggle_btn.text = 'Arm'
			self.status.text = "BusKill is disarmed.\n"
			self.toggle_btn.background_color = self.color_primary

			# set the actionview of every actionbar of every screen back to the
			# app's primary color
			for screen in BusKillApp.manager.screens:
				for child in screen.actionbar.children:
					if type(child) == ActionView:
						child.background_color = self.color_primary

			# stop checking for messages from the usb_handler child process
			Clock.unschedule( self.bk.check_usb_handler )

	def switchToScreen( self, screen ):
		BusKillApp.manager.current = screen

	def handle_upgrades( self, dt ):

		if self.bk.UPGRADED_TO:
			# the buskill app has already been updated; let's prompt the user to
			# restart to *that* version instead of this outdated version
			self.upgrade4_restart_prompt()

		# TODO: fix the restart on Windows so that the recursive delete after
		#       upgrade works and doesn't require a manual restart. See also:
		#  * packages/buskill/__init__()'s UPGRADED_FROM['DELETE_FAILED']
		#  * buskill_gui.py's upgrade5_restart()
		elif self.bk.UPGRADED_FROM and self.bk.UPGRADED_FROM['DELETE_FAILED']:
			# the buskill app was just updated, but it failed to delete the old
			# version. when this happens, we need the user to manually restart

			# close the dialog if it's already opened
			if self.dialog != None:
				self.dialog.dismiss()

			# open a new dialog that tells the user the error that occurred
			new_version_exe = bk.EXE_PATH
			msg = "To complete the update, this app must be manually restarted. Click to restart, then manually execute the new version at the following location.\n\n" + str(new_version_exe)
			self.dialog = DialogConfirmation(
			 title = '[font=mdicons][size=30]\ue923[/size][/font] Restart Required',
			 body = msg,
			 button = "",
			 continue_function=None
			)
			self.dialog.b_cancel.text = "Exit Now"
			self.dialog.b_cancel.on_release = self.close
			self.dialog.auto_dismiss = False
			self.dialog.open()

	def about_ref_press(self, ref):
		if ref == 'gui_help':
			return self.webbrowser_open_url( bk.url_documentation_gui )
		elif ref == 'contribute':
			return self.webbrowser_open_url( bk.url_documentation_contribute )

		return self.webbrowser_open_url( bk.url_website )

	def webbrowser_open_url(self, url ):
		msg = "DEBUG: Opening URL in webbrowser = " +str(url)
		print( msg ); logger.debug( msg )
		webbrowser.open( url )

	def about(self):

		# first close the navigation drawer
		self.nav_drawer.toggle_state()

		msg = "For latest news about BusKill, see our website at [ref=website][u]https://buskill.in[/u][/ref]\n\n"
		msg+= "For help, see our documentation at [ref=gui_help][u]https://docs.buskill.in[/u][/ref]\n\n"
		msg+= "Want to help? See [ref=contribute][u]contributing[/u][/ref]"

		self.dialog = DialogConfirmation(
		 title='BusKill ' +str(BUSKILL_VERSION['VERSION']),
		 body = msg,
		 button = "",
		 continue_function = None,
		)
		self.dialog.b_cancel.text = "OK"
		self.dialog.l_body.on_ref_press = self.about_ref_press
		self.dialog.open()

	def upgrade1(self):

		# first close the navigation drawer
		self.nav_drawer.toggle_state()

		# check to see if an upgrade was already done
		if self.bk.UPGRADED_TO and self.bk.UPGRADED_TO['EXE_PATH'] != '1':
			# a newer version has already been installed; skip upgrade() step and
			# just prompt the user to restart to the newer version
			msg = "DEBUG: Detected upgrade already installed " +str(self.bk.UPGRADED_TO)
			print( msg ); logger.debug( msg )
			self.upgrade4_restart_prompt()
			return

		msg = "Checking for updates requires internet access.\n\n"
		msg+= "Would you like to check for updates now?"

		self.dialog = DialogConfirmation(
		 title='Check for Updates?',
		 body = msg,
		 button='Check Updates',
		 continue_function=self.upgrade2,
		)
		self.dialog.open()

	def upgrade2(self):

		# close the dialog if it's already opened
		if self.dialog != None:
			self.dialog.dismiss()

		# open a new dialog with a spinning progress circle that tells the user
		# to wait for upgrade() to finish
		msg = "Please wait while we check for updates and download the latest version of BusKill."

		self.dialog = DialogConfirmation(
		 title='Updating BusKill',
		 body = msg,
		 button = "",
		 continue_function=None,
		)
		self.dialog.b_cancel.on_release = self.upgrade_cancel
		self.dialog.auto_dismiss = False

		progress_spinner = ProgressSpinner(
		 color = self.color_primary,
		)
		self.dialog.dialog_contents.add_widget( progress_spinner, 2 )
		self.dialog.dialog_contents.add_widget( Label( text='' ), 2 )
		self.dialog.size_hint = (0.9,0.9)

		self.dialog.open()

		# TODO: split this upgrade function into update() and upgrade() and
		# make the status somehow accessible from here so we can put it in a modal

		# Call the upgrade_bg() function which executes the upgrade() function in
		# an asynchronous process so it doesn't block the UI
		self.bk.upgrade_bg()

		# Register the upgrade3_tick() function as a callback to be executed
		# every second, and we'll use that to update the UI with a status
		# message from the upgrade() process and check to see if it the upgrade
		# finished running
		Clock.schedule_interval(self.upgrade3_tick, 1)

	# cancel the upgrade()
	def upgrade_cancel( self ):

		Clock.unschedule( self.upgrade3_tick )
		print( self.bk.upgrade_bg_terminate() )

	# this is the callback function that will be executed every one second
	# while buskill's upgrade() method is running
	def upgrade3_tick( self, dt ):
		print( "called upgrade3_tick()" )

		# update the dialog
		self.dialog.l_body.text = self.bk.get_upgrade_status()

		# did the upgrade process finish?
		if self.bk.upgrade_is_finished():
			# the call to upgrade() finished.
			Clock.unschedule( self.upgrade3_tick )

			try:
				self.upgrade_result = self.bk.get_upgrade_result()

			except Exception as e:
				# if the upgrade failed for some reason, alert the user

				# close the dialog if it's already opened
				if self.dialog != None:
					self.dialog.dismiss()

				# open a new dialog that tells the user the error that occurred
				self.dialog = DialogConfirmation(
				 title = '[font=mdicons][size=30]\ue002[/size][/font] Update Failed!',
				 body = str(e),
				 button = "",
				 continue_function=None
				)
				self.dialog.b_cancel.text = "OK"
				self.dialog.open()

				return

			# cleanup the pool used to launch upgrade() asynchronously asap
#			self.upgrade_pool.close()
#			self.upgrade_pool.join()

			# 1 = poll was successful; we're on the latest version
			if self.upgrade_result == '1':

				# close the dialog if it's already opened
				if self.dialog != None:
					self.dialog.dismiss()

				# open a new dialog that tells the user that they're already
				# running the latest version
				self.dialog = DialogConfirmation(
				 title = '[font=mdicons][size=30]\ue92f[/size][/font] Update BusKill',
				 body = "You're currently using the latest version",
				 button = "",
				 continue_function=None
				)
				self.dialog.b_cancel.text = "OK"
				self.dialog.open()
				return

			# if we made it this far, it means that the we successfully finished
			# downloading and installing the latest possible version, and the
			# result is the path to that new executable
			self.upgrade4_restart_prompt()

	def upgrade4_restart_prompt( self ):

		# close the dialog if it's already opened
		if self.dialog != None:
			self.dialog.dismiss()

		# open a new dialog that tells the user that the upgrade() was a
		# success and gets confirmation from the user to restart the app
		msg = "BusKill was updated successfully. Please restart this app to continue."
		self.dialog = DialogConfirmation(
		 title = '[font=mdicons][size=30]\ue92f[/size][/font]  Update Successful',
		 body = msg,
		 button='Restart Now',
		 continue_function = self.upgrade5_restart,
		)
		self.dialog.open()

	def upgrade5_restart( self ):

		if self.bk.UPGRADED_TO:
			new_version_exe = self.bk.UPGRADED_TO['EXE_PATH']
		else:
			new_version_exe = self.upgrade_result

		msg = "DEBUG: Exiting and launching " +str(new_version_exe)
		print( msg ); logger.debug( msg )

		# TODO: fix the restart on Windows so that the recursive delete after
		#       upgrade works and doesn't require a manual restart. See also:
		#  * packages/buskill/__init__()'s UPGRADED_FROM['DELETE_FAILED']
		#  * buskill_gui.py's handle_upgrades()
		try:

			# TODO: remove me (after fixing Windows restart fail)
			msg = 'os.environ|' +str(os.environ)+ "|\n"
			msg+= "DEBUG: os.environ['PATH']:|" +str(os.environ['PATH'])+  "|\n"
			print( msg ); logger.debug( msg )

			# cleanup env; remove references to now-old version
			oldVersionPaths = [
			 #os.path.split( sys.argv[0] )[0],
			 sys.argv[0].split( os.sep )[-2],
			 os.path.split( self.bk.APP_DIR )[1]
			]

			# TODO: remove me (after fixing Windows restart fail)
			msg = 'DEBUG: removing oldVersionPaths from PATH (' +str(oldVersionPaths)+ ')'
			print( msg ); logger.debug( msg )

			os.environ['PATH'] = os.pathsep.join( [ path for path in os.environ['PATH'].split(os.pathsep) if not re.match( ".*(" +"|".join(oldVersionPaths)+ ").*", path) ] )

			if 'SSL_CERT_FILE' in os.environ:
				del os.environ['SSL_CERT_FILE']

			# TODO: remove me (after fixing Windows restart fail)
			msg = 'os.environ|' +str(os.environ)+ "|\n"
			msg+= "DEBUG: os.environ['PATH']:|" +str(os.environ['PATH'])+  "|\n"
			print( msg ); logger.debug( msg )

			# replace this process with the newer version
			self.bk.close()
			os.execv( new_version_exe, [new_version_exe] )

		except Exception as e:

			msg = "DEBUG: Restart failed (" +str(e) + ")"
			print( msg ); logger.debug( msg )

			# close the dialog if it's already opened
			if self.dialog != None:
				self.dialog.dismiss()

			# open a new dialog that tells the user the error that occurred
			msg = "Sorry, we were unable to restart the BusKill App. Please execute it manually at the following location.\n\n" + str(new_version_exe)
			self.dialog = DialogConfirmation(
			 title = '[font=mdicons][size=30]\ue002[/size][/font] Restart Error',
			 body = msg,
			 button = "",
			 continue_function=None
			)
			self.dialog.b_cancel.text = "OK"
			self.dialog.open()

class DialogConfirmation(ModalView):

	title = StringProperty(None)
	body = StringProperty(None)
	button = StringProperty(None)
	continue_function = ObjectProperty(None)

	b_continue = ObjectProperty(None)

	def __init__(self, **kwargs):

		self._parent = None
		super(ModalView, self).__init__(**kwargs)

		if self.button == "":
			self.b_continue.parent.remove_widget( self.b_continue )
		else:
			self.b_continue.text = self.button

class CriticalError(BoxLayout):

	msg = ObjectProperty(None)

	def showError( self, msg ):
		self.msg.text = msg

	def fileBugReport( self ):
		# TODO: make this a redirect on buskill.in so old versions aren't tied
		#       to github.com
		webbrowser.open( 'https://docs.buskill.in/buskill-app/en/stable/support.html' )

###################
# SETTINGS SCREEN #
###################

# We heavily use (and expand on) the built-in Kivy Settings modules in BusKill
# * https://kivy-fork.readthedocs.io/en/latest/api-kivy.uix.settings.html
#
# Kivy's Settings module does the heavy lifting of populating the GUI Screen
# with Settings and Options that are defined in a json file, and then -- when
# the user changes the options for a setting -- writing those changes to a Kivy
# Config object, which writes them to disk in a .ini file.
#
# Note that a "Setting" is a key and an "Option" is a possible value for the
# Setting.
# 
# The json file tells the GUI what Settings and Options to display, but does not
# store state. The user's chosen configuration of those settings is stored to
# the Config .ini file.
#
# See also https://github.com/BusKill/buskill-app/issues/16

# We define our own BusKillOptionItem, which is an OptionItem that will be used
# by the BusKillSettingComplexOptions class below
class BusKillOptionItem(FloatLayout):

	radio_button_icon = StringProperty('C')
	icon = StringProperty('')
	title = StringProperty('')
	desc = StringProperty('')
	confirmation = StringProperty('')
	value = ObjectProperty('')
	option_human = StringProperty('')
	parent_option = ObjectProperty()
	screen = ObjectProperty()

	def __init__(self, **kwargs):
		#print( "called BusKillOptionItem.__init__()" )

		super(BusKillOptionItem, self).__init__(**kwargs)

		# hack to call another init function, but only *after* all the
		# Kivy Properties are fully initialized
		# * https://stackoverflow.com/questions/49935190/kivy-how-to-initialize-the-viewclass-of-the-recycleview-dynamically
		Clock.schedule_once(self.init2,0)

	# this is called when all the kivy properties have been set and the object
	# is ready
	# * https://stackoverflow.com/questions/49935190/kivy-how-to-initialize-the-viewclass-of-the-recycleview-dynamically
	def init2(self, dt):
		#print( "called init2() for |"+ str(self.value)+ "|" )

		# the "main" screen
		self.main_screen = BusKillApp.manager.get_screen('main')

		# we steal (reuse) the instance field referencing the "modal dialog" from
		# the "main" screen
		self.dialog = self.main_screen.dialog

		# loop through all the OptionItems in the RecycleView data and update
		# the radio button icon to be "checked" or "unchecked" as needed
		self.screen.update_data()

	# this is called when the user clicks on this OptionItem (eg choosing the
	# 'soft-shutdown' trigger)
	def on_touch_up( self, touch ):

		# skip this touch event if it wasn't *this* widget that was touched
		# * https://kivy.org/doc/stable/guide/inputs.html#touch-event-basics
		if not self.collide_point(*touch.pos):
			return

		# skip this touch event if it was actually a scroll event
		# * https://stackoverflow.com/questions/78183125/scrolling-causes-click-on-touch-up-event-on-widgets-in-kivy-recycleview
		if touch.button != "left":
			return

		# skip this touch event if they touched on an option that's already the
		# enabled option
		if self.parent_option.value == self.value:
			msg="DEBUG: Option already equals '" +str(self.value)+ "'. Returning."
			print( msg ); logger.debug( msg )
			return

		# does this option have a warning to prompt the user to confirm their
		# selection before proceeding?
		if self.confirmation == "":
			# this option is safe; no confirmation is necessary
			self.enable_option()

		else:
			# this option can be dangerous; confirm with user before continuing

			self.dialog = DialogConfirmation(
			 title = '[font=mdicons][size=31]\ue002[/size][/font] Warning',
			 body = self.confirmation,
			 button='Continue',
			 continue_function=self.enable_option
			)
			self.dialog.b_cancel.text = "Cancel"
			self.dialog.open()
		
	# called when the user has chosen to change the setting to this option
	def enable_option( self ):

		if self.dialog != None:
			self.dialog.dismiss()

		# write change to disk in our persistent buskill .ini Config file
		key = str(self.parent_option.key)
		value = str(self.value)
		msg="DEBUG: User changed config of '" +str(key)+ "' to '" +str(value)+ "'"
		print( msg ); logger.debug( msg )

		Config.set(self.parent_option.section, key, value)
		Config.write()

		# change the text of the option's value on the main Settings Screen
		self.parent_option.value = self.value

		# also handle the case where there's a human-readable value to set
		if type(self.value) == type(list()):
			self.parent_option.value_human = self.value[0]

		# loop through all the OptionItems in the RecycleView data and update
		# the radio button icon to be "checked" or "unchecked" as needed
		self.screen.update_data()

		# was the font what was just updated by the user?
		if key == 'default_font':
			# the user changed the font; now we need to change the widgets' font

			# update fonts on all labels everywhere
			update_font_recursive(BusKillApp.manager.screens)

# We define our own BusKillSettingItem, which is a SettingItem that will be used
# by the BusKillSettingComplexOptions class below. Note that we don't have code
# here because the difference between the SettingItem and our BusKillSettingItem
# is what's defined in the buskill.kv file. that's to say, it's all visual
class BusKillSettingItem(kivy.uix.settings.SettingItem):
	pass

# Our BusKill app has this concept of a SettingItem that has "ComplexOptions"
#
# The closeset built-in Kivy SettingsItem type is a SettingOptions
#  * https://kivy-fork.readthedocs.io/en/latest/api-kivy.uix.settings.html#kivy.uix.settings.SettingOptions
#
# SettingOptions just opens a simple modal that allows the user to choose one of
# many different options for the setting. But for setting a BusKill trigger,
# we wanted a whole new screen so that we could have more space to tell the user
# what each trigger does, and also have a help button on the screen to describe
# what a trigger means. Also, the whole "New Screen for an Option" is more
# in-line with Material Design.
#  * https://m1.material.io/patterns/settings.html#settings-usage
#
# These are the reasons we create a special BusKillSettingComplexOptions class
class BusKillSettingComplexOptions(BusKillSettingItem):

	# each of these properties directly cooresponds to the key in the json
	# dictionary that's loaded with add_json_panel. the json file is what defines
	# all of our settings that will be displayed on the Settings Screen

	# icon defines the icon that's displayed on the Settings Screen for this
	# setting
	icon = ObjectProperty(None)

	# value_human defines the human-readable value that's displayed on the
	# Settings Screen for this setting
	value_human = StringProperty(None)

	# options is a parallel array of short names for different options for this
	# setting (eg 'lock-screen')
	options = ListProperty([])

	# options_human is a parallel array of short human-readable values for
	# different options for this setting (eg 'Lock Screen')
	options_human = ListProperty([])

	# options_long is a parallel array of short human-readable descriptions for
	# different options for this setting (eg 'BusKill will lock your screen')
	options_long = ListProperty([])

	# options_icons is a parallel array of icons for different options for this
	# setting. Note that this is distinct from the icon for the setting. the
	# 'icon' variable defined above is for the setting (eg 'trigger') while the
	# items in options_icons defines the icons for the options (possible values)
	# for that setting (eg 'lock-screen' or 'soft-shutdown')
	options_icons = ListProperty([])

	# confirmation is a parallel array of "confirmation messages" for the
	# different options for this setting. If a confirmation is set, then the user
	# will be presented with a popup message asking if they want to proceed
	# before the app will actually let them choose this option for this setting.
	# this is useful, for example, before they choose a possibly-dangerous option
	# (eg 'hard-shutdown'). If this is set to an empty string, then no
	# confirmation is presented to the user when they select this option
	confirmation = ListProperty([])

	def __init__(self, **kwargs):
		super(BusKillSettingComplexOptions, self).__init__(**kwargs)

		# hack to call another init function, but only *after* all the
		# Kivy Properties are fully initialized
		# * https://stackoverflow.com/questions/49935190/kivy-how-to-initialize-the-viewclass-of-the-recycleview-dynamically
		Clock.schedule_once(self.init2,0)

	# this is called when all the kivy properties have been set and the object
	# is ready
	def init2(self, dt):

		# is this value actually a list?
		try: 
			# this value is a list, which means the first item in the list is our
			# human-readable value to use in the GUI

			# hack to convert a string of a list to an actual list
			# * https://stackoverflow.com/a/35461204/1174102
			value_as_list = json.loads(self.value.replace('\'', '"'))
			self.value_human = value_as_list[0]

		except Exception as e:
			pass

	def on_panel(self, instance, value):
		if value is None:
			return
		self.fbind('on_release', self._choose_settings_screen)

	def _choose_settings_screen(self, instance):

		# create a new screen just for choosing the value of this setting, and
		# name this new screen "setting_<key>" 
		screen_name = 'setting_' +self.key

		# did we already create this sub-screen?
		if not BusKillApp.manager.has_screen( screen_name ):
			# there is no sub-screen for this Complex Option yet; create it

			# create new screen for picking the value for this ComplexOption
			setting_screen = ComplexOptionsScreen(
			 name = screen_name
			)
		
			# define the help message that should appear when the user clicks the
			# help ActionButton on the top-right of the screen
			setting_screen.set_help_msg( self.desc )

			# set the color of the actionbar in this screen equal to whatever our
			# setting's screen actionbar is set to (eg blue or red)
			setting_screen.actionview.background_color = BusKillApp.manager.current_screen.actionview.background_color

			# make the text in the actionbar match the 'title' for the setting as
			# it's defined in the settings json file
			setting_screen.set_actionbar_title( self.title )

			# loop through all possible values for this ComplexOption, zipping out
			# data from parallel arrays in the json file
			for value, option_human, desc, confirmation, icon in zip(self.options, self.options_human, self.options_long, self.confirmation, self.options_icons):

				# create an OptionItem for each of the possible values for this
				# setting option, and add them to the new ComplexOption sub-screen
				# via the ComplexOptionsScreen's Recycle View 'data' field
				option_item = [{'title': self.key, 'value': value, 'option_human': option_human, 'radio_button_icon':'U', 'icon':icon, 'desc': desc, 'confirmation': confirmation, 'parent_option': self, 'screen': setting_screen }]
				setting_screen.rv.data.extend(option_item)

			# handle the "font" option
			if self.key == 'default_font':
				# first we must determine what fonts are available on this system

				option_items = []
				for font_path in BusKillApp.get_running_app().font_paths:
					font_filename = os.path.basename( font_path )

					font_human = font_filename
					if font_filename.lower().endswith('.ttf') \
					 or font_filename.lower().endswith('.otf'):
						font_human = font_filename[:-4]

					option_items.append( {'title': 'default_font', 'value': [font_human, font_path, font_path, font_path], 'option_human': font_human, 'radio_button_icon': 'U', 'icon':'\ue167', 'desc':'', 'parent_option': self, 'screen': setting_screen } )

				option_items.sort(key=operator.itemgetter('value'))
				setting_screen.rv.data.extend(option_items)

			# add the new ComplexOption sub-screen to the Screen Manager
			BusKillApp.manager.add_widget( setting_screen )

		# change into the sub-screen now
		BusKillApp.manager.transition.direction = 'left'
		BusKillApp.manager.current = screen_name

# We define BusKillSettings (which extends the built-in kivy Settings) so that
# we can add a new type of Setting = 'commplex-options'). The 'complex-options'
# type becomes a new 'type' that can be defined in our settings json file
class BusKillSettings(kivy.uix.settings.Settings):

	def __init__(self, *args, **kargs):
		super(BusKillSettings, self).__init__(*args, **kargs)
		super(BusKillSettings, self).register_type('complex-options', BusKillSettingComplexOptions)

	def on_touch_down( self, touch ):
		super(BusKillSettings, self).on_touch_down(touch)

# Kivy's SettingsWithNoMenu is their simpler settings widget that doesn't
# include a navigation bar between differnt pages of settings. We extend that
# type with BusKillSettingsWithNoMenu so that we can use our custom
# BusKillSettings class (defined above) with our new 'complex-options' type
class BusKillSettingsWithNoMenu(BusKillSettings):

	def __init__(self, *args, **kwargs):
		self.interface_cls = kivy.uix.settings.ContentPanel
		super(BusKillSettingsWithNoMenu,self).__init__( *args, **kwargs )

	def on_touch_down( self, touch ):
		super(BusKillSettingsWithNoMenu, self).on_touch_down( touch )

# The ComplexOptionsScreen is a sub-screen to the Settings Screen. Kivy doesn't
# have sub-screens for defining options, but that's what's expected in Material
# Design. We needed more space, so we created ComplexOption-type Settings. And
# this is the Screen where the user transitions-to to choose the options for a
# ComplexOption
class ComplexOptionsScreen(Screen):

	actionview = ObjectProperty(None)
	settings_content = ObjectProperty(None)
	actionbar_title = ObjectProperty(None)
	help_msg = ObjectProperty(None)

	def set_help_msg(self, new_help_msg ):
		self.help_msg = new_help_msg

	def set_actionbar_title(self, new_title):
		self.actionbar_title = new_title

	def on_pre_enter(self, *args):

		msg = "DEBUG: User switched to '" \
		 +str(BusKillApp.manager.current_screen.name)+ "' screen"
		print( msg ); logger.debug( msg )

		# the "main" screen
		self.main_screen = BusKillApp.manager.get_screen('main')

		# close the navigation drawer on the main screen
		self.main_screen.nav_drawer.toggle_state()

		# we steal (reuse) the instance field referencing the "modal dialog" from
		# the "main" screen
		self.dialog = self.main_screen.dialog

	def show_help( self ):

		self.dialog = DialogConfirmation(
		 title = '[font=mdicons][size=30]\ue88f[/size][/font] ' \
		  + str(self.actionbar_title),
		 body = str(self.help_msg),
		 button = "",
		 continue_function=None
		)
		self.dialog.b_cancel.text = "OK"
		self.dialog.open()

	# update all of data dict in this Screen's RecycleView so that all of the
	# widgets get updated on changes (eg the "radio button" icon)
	def update_data(self):

		# GET INFO
		this_value = None
		set_value = None

		# get all of the widgets on this screen
		widgets = [widget for widget in self.walk()]

		# loop through all of the widgets until we get our first OptionItem
		for widget in widgets:

			# is this widget a BusKillOptionItem object?
			if isinstance( widget, BusKillOptionItem ):

				# get the title for this option (eg "trigger")
				title = widget.title

				# get the value that the user has actually set this option to
				set_value = Config.get(widget.parent_option.section, title)

				break

		# UPDATE DATA

		# loop through every dict of OptionItem data in the Recycle View's list
		# of dicts
		for n in range(0,len(self.rv.data)):

			# get the value for this specific OptionItem
			this_value = self.rv.data[n]['value']

			if str(this_value) == str(set_value):
				# this is the currently-set option
				# set the radio button icon to "selected"
				self.rv.data[n]['radio_button_icon'] = '[font=mdicons][size=18sp]\ue837[/size][/font] ' 
			else:
				# this is not the currently-set option
				# set the radio button icon to "unselected"
				self.rv.data[n]['radio_button_icon'] = '[font=mdicons][size=18sp]\ue836[/size][/font] '

		# update RecycleView data in next frame
		# * https://stackoverflow.com/questions/49935190/kivy-how-to-initialize-the-viewclass-of-the-recycleview-dynamically
		Clock.schedule_once(self.rv.refresh_from_data,0)

# This is our main Screen when the user clicks "Settings" in the nav drawer
class BusKillSettingsScreen(Screen):

	actionview = ObjectProperty(None)

	def on_pre_enter(self, *args):

		msg = "DEBUG: User switched to 'Settings' screen"
		print( msg ); logger.debug( msg )

		# set the bk object to the BusKillApp's bk object
		# note we can't set this in __init__() because that's too early. the
		# 'root_app' instance field is manually set by the BusKillApp object
		# after this Screen instances is created but before it's added with
		# add_widget()
		self.bk = self.root_app.bk

		# the "main" screen
		self.main_screen = BusKillApp.manager.get_screen('main')

		# close the navigation drawer on the main screen
		self.main_screen.nav_drawer.toggle_state()

		# we steal (reuse) the instance field referencing the "modal dialog" from
		# the "main" screen
		self.dialog = self.main_screen.dialog

		# is the contents of 'settings_content' empty?
		if self.settings_content.children == []:
			# we haven't added the settings widget yet; add it now

			# kivy's Settings module is designed to use many different kinds of
			# "menus" (sidebars) for navigating different sections of the settings.
			# while this is powerful, it conflicts with the Material Design spec,
			# so we don't use it. Instead we use BusKillSettingsWithNoMenu, which
			# inherets kivy's SettingsWithNoMenu and we add sub-screens for
			# "ComplexOptions"; 
			s = BusKillSettingsWithNoMenu()
			s.root_app = self.root_app

			# create a new Kivy SettingsPanel using Config (our buskill.ini config
			# file) and a set of options to be drawn in the GUI as defined-by
			# the 'settings_buskill.json' file
			s.add_json_panel( 'buskill', Config, os.path.join(self.bk.SRC_DIR, 'packages', 'buskill', 'settings_buskill.json') )

			# our BusKillSettingsWithNoMenu object's first child is an "interface"
			# the add_json_panel() call above auto-pouplated that interface with
			# a bunch of "ComplexOptions". Let's add those to the screen's contents
			self.settings_content.add_widget( s )

	# called when the user leaves the Settings screen
	def on_pre_leave(self):
		# update runtime 'bk' instance with any settings changes, as needed

		# is the user going back to the main screen or some sub-Settings screen?
		if BusKillApp.manager.current == "main":
			# the user is leaving the Settings screen to go back to the main Screen

			# attempt to re-arm BusKill if the trigger changed
			self.rearm_if_required()

			self.refresh_values()

	# called when the user clicks the "reset" button in the actionbar
	def reset_defaults(self):

		msg = "Are you sure you want to reset all your settings back to defaults?"

		self.dialog = DialogConfirmation(
		 title = '[font=mdicons][size=31]\ue002[/size][/font] Warning',
		 body = msg,
		 button='Erase Settings',
		 continue_function=self.reset_defaults2
		)
		self.dialog.b_cancel.text = "Cancel"
		self.dialog.open()

	# called when the user confirms they want to reset their settings
	def reset_defaults2(self):
		msg = "DEBUG: User initiated settings reset"
		print( msg ); logger.debug( msg )

		# close the dialog if it's already opened
		if self.dialog != None:
			self.dialog.dismiss()

		# delete all the options saved to the config file
		sections = ['kivy','buskill']
		for section in sections:
			for key in Config[section]:
				try:
					Config.remove_option( section, key )
				except Exception as e:
					msg = "DEBUG: Skipped reset of key. (" +str(e) + ")"
					print( msg ); logger.debug( msg )

		# save the changes to the .ini config file
		Config.write()

		# setup the defaults again to avoid configparser.NoOptionError
		self.root_app.build_config(Config)

		# refresh all the values on the Settings Screen (and sub-screens)
		self.refresh_values()

	# updates the values of all the options on the Settings Screen and all
	# ComplexOptions sub-screens
	def refresh_values(self):

		# UPDATE SETTINGS SCREEN

		# loop through all the widgets on the Settings Screen
		for widget in self.settings_content.walk():

			# is this widget a BusKillSettingComplexOptions object?
			if isinstance( widget, BusKillSettingComplexOptions ) \
			 or isinstance( widget, kivy.uix.settings.SettingBoolean ) \
			 or isinstance( widget, kivy.uix.settings.SettingNumeric ) \
			 or isinstance( widget, kivy.uix.settings.SettingOptions ) \
			 or isinstance( widget, kivy.uix.settings.SettingString ) \
			 or isinstance( widget, kivy.uix.settings.SettingPath ):

				# get the key for this SettingItem
				key = widget.key

				# get the value that the user has actually set this option to
				set_value = Config.get(widget.section, key)

				# update the value for this SettingItem, which will update the text
				# in the Label on the Settings Screen
				widget.value = set_value

				# also update the value_human, if needed
				try: 
					# hack to convert a string of a list to an actual list
					# * https://stackoverflow.com/a/35461204/1174102
					value_as_list = json.loads(set_value.replace('\'', '"'))
					widget.value_human = value_as_list[0]
				except Exception as e:
					pass

		# UPDATE SUB-SETTINGS SCREENS (for ComplexOptions)
		# loop through all the OptionItems in the RecycleView data and update
		# the radio button icon to be "checked" or "unchecked" as needed

		# loop through every screen
		for screen in BusKillApp.manager.screens:

			# is this screen a ComplexOptionsScreen?
			if isinstance( screen, ComplexOptionsScreen):

				# this screen is a ComplexOptionsScreen with a RecycleView of
				# OptionItem widgets whoose radio buttons we need to update
				screen.update_data()

		# update fonts on all labels everywhere
		update_font_recursive(BusKillApp.manager.screens)

	# determine if we need to re-arm BusKill (eg if they changed the trigger
	# while BusKill is arm, we'd need to re-arm else it'll trigger not what the
	# user expects it to trigger)
	def rearm_if_required(self):

		# this changes to true if we have to disarm & arm BusKill again in order to
		# apply the settings that the user changed
		rearm_required = False

		# trigger
		old_trigger = self.bk.trigger
		new_trigger = Config.get('buskill', 'buskill_trigger')

		# was the trigger just changed by the user?
		if old_trigger != new_trigger:
			try: 
				# the trigger was changed; update the runtime bk instance
				self.bk.set_trigger( new_trigger )
			except Exception as e:
				# we got an exception when trying to change the trigger; show in GUI
				msg = "Unable to set trigger to '" +str(new_trigger)+ "'"
				msg += "\n\n" +str(e)
				print( msg )
				self.dialog = DialogConfirmation(
				 title = '[font=mdicons][size=30]\ue002[/size][/font] Error',
				 body = msg,
				 button='',
				 continue_function = None
				)
				self.dialog.b_cancel.text = "OK"
				self.dialog.open()

				# revert back to the trigger before
				Config.set('buskill', 'buskill_trigger', old_trigger)
				self.bk.set_trigger(old_trigger)

				return False

			# is BusKill currently armed?
			if self.bk.is_armed == True:
				# buskill is currently armed; rearming is required to apply the change
				rearm_required = True

		# is it necessary to disarm and arm BusKill in order to apply the user's
		# changes to BusKill's settings?
		if rearm_required:
			msg = "DEBUG: Re-arm from '" +str(old_trigger)+ "' to '" +str(new_trigger)+ "' trigger?"
			print( msg ); logger.debug( msg )

			msg = "You've made changes to your settings that require disarming & arming again to apply."
			self.dialog = DialogConfirmation(
			 title = '[font=mdicons][size=30]\ue92f[/size][/font]  Apply Changes?',
			 body = msg,
			 button='Disarm & Arm Now',
			 continue_function = self.rearm
			)
			self.dialog.open()

	# re-arms BusKill
	def rearm(self):

		# close the dialog if it's already opened
		if self.dialog != None:
			self.dialog.dismiss()

		# turn it off and on again
		self.main_screen.toggle_buskill()
		self.main_screen.toggle_buskill()

#############
# DEBUG LOG #
#############

class DebugLog(Screen):

	debug_header = ObjectProperty(None)
	actionview = ObjectProperty(None)

	def __init__(self, **kwargs):

		self.show_debug_log_thread = None

		super(DebugLog, self).__init__(**kwargs)

	def on_pre_enter(self, *args):

		msg = "DEBUG: User switched to 'DebugLog' screen"
		print( msg ); logger.debug( msg )

		# set the bk object to the BusKillApp's bk object
		# note we can't set this in __init__() because that's too early. the
		# 'root_app' instance field is manually set by the BusKillApp object
		# after this Screen instances is created but before it's added with
		# add_widget()
		self.bk = self.root_app.bk

		# register the function for clicking the "help" icon at the top
		self.debug_header.bind( on_ref_press=self.ref_press )

		# the "main" screen
		self.main_screen = BusKillApp.manager.get_screen('main')

		# close the navigation drawer on the main screen
		self.main_screen.nav_drawer.toggle_state()

		# we steal (reuse) the instance field referencing the "modal dialog" from
		# the "main" screen
		self.dialog = self.main_screen.dialog

		if logger.root.hasHandlers():
			self.logfile_path = logger.root.handlers[0].baseFilename

			with open(self.logfile_path) as log_file:
				self.debug_log_contents = log_file.read()

			# we use treading.Thread() instead of multiprocessing.Process
			# because it can update the widget's contents directly without
			# us having to pass data in-memory between the child process.
			# Con: We can't kill threads, so it should only be used for
			# short-running background tasks that won't get stuck
			self.show_debug_log_thread = threading.Thread(
			 target = self.show_debug_log
			)
			self.show_debug_log_thread.start()

	def show_debug_log( self ):
		lines = []
		for line in self.debug_log_contents.splitlines(keepends=False):
			lines.append({'text': line})
		self.rv.data = lines

	def copy_debug_log( self ):

		msg = "DEBUG: User copied contents of 'DebugLog' to clipboard"
		print( msg ); logger.debug( msg )

		Clipboard.copy( self.debug_log_contents )

		msg = "The full Debug Log has been copied to your clipboard.\n\n"
		self.dialog = DialogConfirmation(
		 title = '[font=mdicons][size=31]\ue88f[/size][/font] Debug Log',
		 body = msg,
		 button = "",
		 continue_function=None
		)
		self.dialog.b_cancel.text = "OK"
		self.dialog.l_body.bind( on_ref_press=self.ref_press )
		self.dialog.open()

	def go_back(self):
		BusKillApp.manager.switch_to('main')

	def ref_press(self, widget, ref):

		# what did the user click?
		if ref == 'help_debug_log':
			# the user clicked the "help" icon; show them the help modal

			msg = "The Debug Log shows detailed information about the app's activity since it was started. This can be helpful to diagnose bugs if the app is not functioning as expected.\n\n"
			msg+= "For more info on how to submit a bug report, see [ref=bug_report][u]our documentation[/u][/ref]\n\n"
			msg+= "Your full Debug Log is stored in " +self.logfile_path+ "\n\n"
			self.dialog = DialogConfirmation(
			 title = '[font=mdicons][size=30]\ue88f[/size][/font] Debug Log',
			 body = msg,
			 button = "",
			 continue_function=None
			)
			self.dialog.b_cancel.text = "OK"
			self.dialog.l_body.bind( on_ref_press=self.ref_press )
			self.dialog.open()

		elif ref == 'bug_report':
			self.report_bug()

	def report_bug( self ):

		# for privacy reasons, we don't do in-app bug reporting; just point the
		# user to our documentation
		self.main_screen.webbrowser_open_url( self.bk.url_documentation_bug_report )

class BusKillApp(App):

	# instantiate our screen manager instance so it can be accessed by other
	# objects for changing the kivy screen
	manager = ScreenManager()

	# copied mostly from 'site-packages/kivy/app.py'
	def __init__(self, bk, **kwargs):

		# instantiate our BusKill object instance so it can be accessed by
		# other objects for doing Buskill stuff
		self.bk = bk

		self._app_settings = None
		self._app_window = None
		super(BusKillApp, self).__init__(**kwargs)
		self.options = kwargs
		self.built = False

		# FONTS
		font_dirs = LabelBase.get_system_fonts_dir()
		font_dirs.append( self.bk.APP_DIR )
		self.font_paths = set()
		for fonts_dir_path in font_dirs:

			for root, dirs, files in os.walk(fonts_dir_path):
				for file in files:
					if file.lower().endswith(".ttf") \
					 or file.lower().endswith(".otf"):
						font_path = str(os.path.join(root, file))
						self.font_paths.add( font_path )

		# TODO: remove me
		msg = "DEBUG: font_dirs:|" +str(font_dirs)+ "|"
		print( msg ); logger.debug( msg )

		msg = "DEBUG: Found " +str(len(self.font_paths))+ " font files."
		print( msg ); logger.debug( msg )

		msg = "DEBUG: Default font = " + str(Config.get('kivy', 'default_font'))
		print( msg ); logger.debug( msg )
		
		# register font aliases so we don't have to specify their full file path
		# when setting font names in our kivy language .kv files
		try:

			# did the user set a custom font?
			default_font = Config.get('kivy', 'default_font')
			if 'Roboto' not in default_font:
				# the user set a custom font; use it

				try: 
					# hack to convert a string of a list to an actual list
					# * https://stackoverflow.com/a/35461204/1174102
					default_font = json.loads(default_font.replace('\'', '"'))
					font_name = default_font[0]
					font_path = default_font[1]

				except Exception as e:
					pass

				# bkmono = "BusKill Mono"; we just overwrite it with the user's font
				LabelBase.register( "bkmono", default_font[1] )

				# TODO; add logic to try to actually find an "italic", "bold", and
				# "bolditalic" version of the user-selected font

			else:
				# the user did *not* set a custom font; use Roboto

				# TODO: remove me
				msg = "DEBUG: attempt to load bkmono from:|" +str(os.path.join( 'fonts', 'RobotoMono-Regular.ttf' ))+ "|"
				print( msg ); logger.debug( msg )

				LabelBase.register(
				 "bkmono",
				 os.path.join( 'fonts', 'RobotoMono-Regular.ttf' ),
				)

				# TODO: remove me
			msg = "DEBUG: attempt to load mdicons from:|" +str(os.path.join( 'fonts', 'MaterialIcons-Regular.ttf'))+ "|"
			print( msg ); logger.debug( msg )

			LabelBase.register(
			 "mdicons",
			 os.path.join( 'fonts', 'MaterialIcons-Regular.ttf' ),
			)

		except Exception as e:

			msg = "INFO: Failed to load fonts (" +str(e) + ")"
			print( msg ); logger.info( msg )

			try: 

				font_roboto_mono_path = [f for f in self.font_paths if f.lower().endswith("robotomono-regular.ttf")]
				font_mdicons_path = [f for f in self.font_paths if f.lower().endswith("materialicons-regular.ttf")]

				msg = "DEBUG: Found Roboto Mono " + str(font_roboto_mono_path)
				print( msg ); logger.debug( msg )
				msg = "DEBUG: Found Material Icons " + str(font_mdicons_path)
				print( msg ); logger.debug( msg )

				# just get the first file we found in all cases
				font_roboto_mono_path = font_roboto_mono_path[0]
				font_mdicons_path = font_mdicons_path[0]

				LabelBase.register( "bkmono", font_roboto_mono_path )
				LabelBase.register( "mdicons", font_mdicons_path )

			except Exception as e:

				msg = "WARNING: Failed to find fonts (" +str(e) + ")"
				print( msg ); logger.warning( msg )

	# does rapid-fire UI-agnostic cleanup stuff when the GUI window is closed
	def close( self, *args ):
		self.bk.close()

	def build_config(self, config):

		# this is a hack that executes the orphaned code in kivy/config.py
		# which sets all the default config files for a new kivy config file.
		# if we omit it, kivy may cause a fatal error because some expected keys
		# are missing. we have to use importlib.reload() to force it to run again,
		# else it'll do nothing. For more info, see:
		#  * https://stackoverflow.com/questions/79950555/how-to-force-re-import-of-from-x-import-y-statement-in-python
		#  * https://stackoverflow.com/questions/437589/how-do-i-unload-reload-a-python-module
		#  * https://github.com/BusKill/buskill-app/issues/123
		importlib.reload( kivy.config )

		Config.read( self.bk.CONF_FILE )
		Config.setdefaults('buskill', {
		 'buskill_trigger': 'lock-screen',
		 'persistent_log': 'False'
		})	

		# TODO: don't hard-code this, pull it from kivy/config.py
		# * https://stackoverflow.com/questions/78216476/how-to-get-kivy-to-set-its-defaults-in-the-config-at-runtime
		Config.setdefault('kivy', 'default_font', [
		 'Roboto',
		 'data/fonts/Roboto-Regular.ttf',
		 'data/fonts/Roboto-Italic.ttf',
		 'data/fonts/Roboto-Bold.ttf',
		 'data/fonts/Roboto-BoldItalic.ttf']
		)

		Config.set('kivy', 'exit_on_escape', '0')
		Config.set('input', 'mouse', 'mouse,multitouch_on_demand')
		Config.write()

	def build(self):

		# this doesn't work in Linux, so instead we just overwrite the built-in
		# kivy icons with ours, but that's done in the linux build script
		#  * https://github.com/kivy/kivy/issues/2202
		self.icon = 'buskill-icon-150.png'

		# is the OS that we're running on supported?
		if self.bk.IS_PLATFORM_SUPPORTED:

			# yes, this platform is supported; show the main window
			Window.bind( on_request_close = self.close )

			# create all the Screens we need for our app
			screens = [
			 MainWindow(name='main'),
			 DebugLog(name='debug_log'),
			 BusKillSettingsScreen(name='settings'),
			]

			# loop through each screen created above
			for screen in screens:
				msg = "DEBUG: adding screen:|" +str(screen)+ "|"
				print( msg ); logger.debug( msg )

				# assign an instance field named 'root_app' to each of our Screens
				# that references <this> BusKillApp object so that we can access
				# the App's instance fields (like 'bk') from within the Screen.
				# I know no built-in way to do this, since the root/parent of each
				# screen is None
				# 
				# Note: This must be done *before* adding the Screen to 'manager',
				# or the 'root_app' instance field will be unavailable in the
				# Screen's on_pre_load() functions
				screen.root_app = self

				# add the screen to the Screen Manager
				self.manager.add_widget( screen )

			return self.manager

		else:
			# the current platform isn't supported; show critical error window

			msg = buskill.ERR_PLATFORM_NOT_SUPPORTED
			print( msg ); logger.error( msg )

			crit = CriticalError()
			cirit.showError( buskill.ERR_PLATFORM_NOT_SUPPORTED )
			return crit