ClickFlash: Mouse Click Highlighter for Linux

Usage:

please specify: size, duration and color

size         Diameter of the circle in pixels.

duration     How long the flash circle should be visible.

color        Color of the flash circle as hex color code, i.e. FF0000.

Example:
             ./ClickFlash.py 33 0.1 FF0000 

#!/usr/bin/python3
################################################################################
#
# ClickFlash v1.00
#
# ClickFlash is a lightweight, Python-powered command-line tool designed to 
# make your tutorial videos pop.
# With every mouse click, it flashes a vibrant, short-lived colored circle at 
# your cursor’s position, spotlighting exactly where you’re interacting in a GUI.
# Perfect for educators, developers, or screencast creators.
#
#
# 2025-03-22 bitman@bitmania.de      https://bitmania.de
#            initial version
#
################################################################################
from Xlib import X, display
from Xlib.ext import shape
from PIL import Image, ImageDraw
import time
import os
import sys



def create_circle_image(size, color):
	img = Image.new('RGBA', (size, size), (0, 0, 0, 0))
	draw = ImageDraw.Draw(img)
	draw.ellipse(
		[0, 0, size-1, size-1],
		fill=color,  # Custom color (R, G, B, A)
		outline=None
	)
	return img

def flash(posX, posY, size=50, duration=0.5, color=(255, 0, 0, 255)):
	d = display.Display()
	screen = d.screen()
	root = screen.root

	img = create_circle_image(size, color)
	width, height = img.size

	window = root.create_window(
		posX, posY, width, height, 0,
		screen.root_depth,
		X.InputOutput,
		screen.root_visual,
		colormap=screen.default_colormap,
		background_pixel=screen.black_pixel,
		event_mask=X.ExposureMask | X.StructureNotifyMask,
		override_redirect=True
	)

	colormap = screen.default_colormap
	# Convert RGBA color to RGB for Xlib (ignore alpha)
	rgb_color = colormap.alloc_color(
		color[0] * 257,  # Convert 0-255 to 0-65535
		color[1] * 257,
		color[2] * 257
	)
	gc = window.create_gc(foreground=rgb_color.pixel, background=screen.black_pixel)

	mask = window.create_pixmap(width, height, 1)
	mask_gc = mask.create_gc(foreground=1, background=0)
	alpha = img.split()[3].convert('1')
	mask.put_pil_image(mask_gc, 0, 0, alpha)
	window.shape_mask(0, 0, 0, 0, mask)

	window.map()
	d.sync()

	drawn = False
	while True:
		event = d.next_event()
		if event.type == X.Expose or event.type == X.MapNotify:
			window.clear_area(0, 0, width, height)
			window.fill_rectangle(gc, 0, 0, width, height)
			d.sync()
			drawn = True
			break

	if drawn:
		time.sleep(duration)  # Custom duration
	window.unmap()
	window.destroy()
	d.close()




# Main execution
if __name__ == "__main__":
	script_name		= os.path.basename(__file__)		# the name of this script (ommiting path)
	flash_color = (255, 0, 0, 255)  # Default color: red (R, G, B, A)

	if len(sys.argv) <4:
		print('Usage:')
		print('')
		print('please specify: size, duration and color')
		print('')
		print('size         Diameter of the circle in pixels.')
		print('')
		print('duration     How long the flash circle should be visible.')
		print('')
		print('color        Color of the flash circle as hex color code, i.e. FF0000.')
		print('')
		print('Example:')
		print(f'             ./{script_name} 33 0.1 FF0000 ')
		print('')
		print('')
		sys.exit()
	else:
		flash_size			= int(sys.argv[1])
		print(f'flash_size     : {flash_size}')

		flash_duration	= float(sys.argv[2])
		print(f'flash_duration : {flash_duration}')

		flash_color			= sys.argv[3]
		print(f'flash_color    : {flash_color}')
		if len(flash_color)!=6:
			print(f'invalid color {flash_color}')
			sys.exit() 
		r = int(flash_color[0:2], 16)
		g = int(flash_color[2:4], 16)
		b = int(flash_color[4:6], 16)
		flash_color = (r, g, b, 255)
		print(f'flash_color    : {flash_color}')


	# Mouse Event Listener
	with os.popen('xinput test-xi2 --root') as cmd:
		motion = False
		RawButtonRelease = False
		RawButtonPress = False

		posX, posY = 0, 0
		for line in cmd:
			line = line.strip()
			#print(f'line: {line}')

			if 'EVENT type 6 (Motion)' in line:
				motion = True
			if motion and 'event:' in line:
				pos = line.replace(' ', '/').split('/')[1:3]
				posX, posY = int(float(pos[0])), int(float(pos[1]))
				motion = False


			if '(RawButtonRelease)' in line:
				RawButtonRelease = True

			if '(RawButtonPress)' in line:
				RawButtonPress = True


			#if not motion:
			#	if RawButtonRelease:
			#		print(f'---- {line}')
			#		if 'detail: 1' in line:
			#			flash(posX - int(flash_size/2), posY - int(flash_size/2), flash_size, flash_duration, (0, 255, 0, 255) )
			#			RawButtonRelease = False
			#		if 'detail: 3' in line:
			#			flash(posX - int(flash_size/2), posY - int(flash_size/2), flash_size, flash_duration, (0, 255, 0, 255) )
			#			RawButtonRelease = False

			if not motion:
				if RawButtonPress:
					#print(f'++++ {line}')
					if 'detail: 1' in line:
						flash(posX - int(flash_size/2), posY - int(flash_size/2), flash_size, flash_duration, flash_color)
						RawButtonPress = False
					if 'detail: 3' in line:
						flash(posX - int(flash_size/2), posY - int(flash_size/2), flash_size, flash_duration, flash_color)
						RawButtonPress = False