PyloidPyloid
Pyloid is a desktop application framework built on top of PySide6. It simplifies window creation, system tray management, clipboard interaction, RPC communication, file watching, and more. All functions in Pyloid are thread-safe, meaning they can be safely executed from threads other than the main thread.
Initialization
from pyloid import Pyloid
app = Pyloid(app_name="MyApp", single_instance=True)Parameters
Prop
Type
Returns
PyloidThe initialized application instanceWindow Management
create_window
from pyloid import Pyloid
app = Pyloid(app_name="MyApp", single_instance=True)
window = app.create_window(
title="Main Window",
width=1024,
height=768,
x=100,
y=100,
frame=True,
context_menu=True,
dev_tools=True,
transparent=False,
zoomable=False,
IPCs=[],
)Parameters
Prop
Type
Returns
BrowserWindowThe created browser window instanceget_windows
Returns a dictionary of all browser windows.
from pyloid import Pyloid
app = Pyloid(app_name="MyApp", single_instance=True)
window = app.create_window(title="Your Window Title")
########## Usage ##########
windows = app.get_windows()
print(windows["your-window-id"].get_title()) # "Your Window Title"Returns
Dict[str, BrowserWindow]Dictionary of all windows.get_window_by_id
Returns the window with the given ID.
from pyloid import Pyloid
app = Pyloid(app_name="MyApp", single_instance=True)
window = app.create_window(title="Your Window Title")
########## Usage ##########
window_by_id = app.get_window_by_id(window.get_id()) # BrowserWindow instance
# window == window_by_id : same instance
# you can use this to get the window instance by id for multi window application
print(window_by_id.get_title()) # "Your Window Title"Parameters
Prop
Type
Returns
Optional[BrowserWindow]Window object or None.show_main_window
Shows and focuses the first window.
from pyloid import Pyloid
app = Pyloid(app_name="MyApp", single_instance=True)
window = app.create_window(title="Your Window Title")
########## Usage ##########
app.show_main_window() # main window is the first window that was createdReturns
Nonefocus_main_window
Focuses the first window.
from pyloid import Pyloid
app = Pyloid(app_name="MyApp", single_instance=True)
window = app.create_window(title="Your Window Title")
########## Usage ##########
app.focus_main_window() # main window is the first window that was createdReturns
Noneshow_and_focus_main_window
Shows and focuses the first window.
from pyloid import Pyloid
app = Pyloid(app_name="MyApp", single_instance=True)
window = app.create_window(title="Your Window Title")
########## Usage ##########
app.show_and_focus_main_window() # main window is the first window that was createdReturns
Noneclose_all_windows
Closes all windows.
from pyloid import Pyloid
app = Pyloid(app_name="MyApp", single_instance=True)
window = app.create_window(title="Your Window Title")
########## Usage ##########
app.close_all_windows() # close all windowsReturns
Nonequit
Quits the application.
from pyloid import Pyloid
app = Pyloid(app_name="MyApp", single_instance=True)
########## Usage ##########
app.quit() # quit the applicationReturns
NoneApplication Icon
set_icon
Dynamically sets the application's icon.
from pyloid import Pyloid
app = Pyloid(app_name="MyApp", single_instance=True)
########## Usage ##########
app.set_icon("icon.png") # set the application iconParameters
Prop
Type
Returns
boolTrue if successful.Tray System
set_tray_icon
Dynamically sets the tray icon.
from pyloid import Pyloid
app = Pyloid(app_name="MyApp", single_instance=True)
########## Usage ##########
app.set_tray_icon("icon.png") # set the tray iconParameters
Prop
Type
Returns
boolTrue if successful.set_tray_menu_items
Dynamically sets the tray menu items.
from pyloid import Pyloid
app = Pyloid(app_name="MyApp", single_instance=True)
########## Usage ##########
app.set_tray_menu_items([
{"label": "Open", "callback": lambda: app.show_main_window()},
{"label": "Quit", "callback": app.quit}
])Parameters
Prop
Type
Returns
boolTrue if successful.set_tray_actions
Dynamically sets the actions for tray icon activation.
from pyloid import Pyloid
app = Pyloid(app_name="MyApp", single_instance=True)
########## Usage ##########
app.set_tray_actions({TrayEvent.DoubleClick: lambda: app.show_main_window()})Parameters
Prop
Type
Returns
boolTrue if successful.set_tray_icon_animation
Dynamically sets and starts the animation for the tray icon.
from pyloid import Pyloid
app = Pyloid(app_name="MyApp", single_instance=True)
########## Usage ##########
app.set_tray_icon_animation(
[
'frame1.png',
'frame2.png',
'frame3.png',
],
100,
)Parameters
Prop
Type
Returns
boolTrue if successful.set_tray_tooltip
Dynamically sets the tooltip for the tray icon.
from pyloid import Pyloid
app = Pyloid(app_name="MyApp", single_instance=True)
########## Usage ##########
app.set_tray_tooltip('Pyloid is running')Parameters
Prop
Type
Returns
boolTrue if successful.Notification
show_notification
Displays a notification in the system tray.
from pyloid import Pyloid
app = Pyloid(app_name="MyApp", single_instance=True)
########## Usage ##########
app.show_notification("Hello", "This is a notification.")Parameters
Prop
Type
Returns
Noneset_notification_callback
Sets the callback function to be called when a notification is clicked.
from pyloid import Pyloid
app = Pyloid(app_name="MyApp", single_instance=True)
########## Usage ##########
def on_notification_click():
print("Notification clicked")
app.set_notification_callback(on_notification_click)Parameters
Prop
Type
Returns
boolTrue if successful.Clipboard
set_clipboard_text
Copies text to the clipboard.
from pyloid import Pyloid
app = Pyloid(app_name="MyApp", single_instance=True)
########## Usage ##########
app.set_clipboard_text("Copied text")Parameters
Prop
Type
Returns
Noneget_clipboard_text
You can use this function to retrieve the text currently on the clipboard.
from pyloid import Pyloid
app = Pyloid(app_name="MyApp", single_instance=True)
########## Usage ##########
text = app.get_clipboard_text()
print(text) # "Copied text"Returns
strClipboard text.set_clipboard_image
Copies an image to the clipboard.
This function can accept not only image file paths but also byte data or os.PathLike objects.
from pyloid import Pyloid
app = Pyloid(app_name="MyApp", single_instance=True)
########## Usage ##########
app.set_clipboard_image("image.png")Parameters
Prop
Type
Returns
Noneget_clipboard_image
You can use this function to retrieve the image currently on the clipboard. The returned image is of QImage type. If there's no image on the clipboard, it returns None.
With the QImage object, you can perform various operations such as image processing, display, saving, etc.
from pyloid import Pyloid
app = Pyloid(app_name="MyApp", single_instance=True)
########## Usage ##########
img = app.get_clipboard_image()
print(img) # QImage objectReturns
Optional[QImage]Clipboard image object or NoneMonitor
get_all_monitors
Returns information about all connected monitors.
from pyloid import Pyloid
app = Pyloid(app_name="MyApp", single_instance=True)
########## Usage ##########
monitors = app.get_all_monitors()
for monitor in monitors:
print(monitor.info())Returns
List[Monitor]List containing monitor information.get_primary_monitor
Returns information about the primary monitor.
from pyloid import Pyloid
app = Pyloid(app_name="MyApp", single_instance=True)
########## Usage ##########
primary_monitor = app.get_primary_monitor()
print(primary_monitor.info())Returns
MonitorPrimary monitor information.Autostart
set_auto_start
Sets the application to start automatically at system startup. more guide here.
from pyloid import Pyloid
app = Pyloid(app_name="MyApp", single_instance=True)
########## Usage ##########
app.set_auto_start(True) # enable auto-start
app.set_auto_start(False) # disable auto-start
# in production, it will return True or False
# in development, it will return None and do nothingParameters
Prop
Type
Returns
Union[bool, None]True if enabled, False if disabled, None if unsupported.is_auto_start
Checks if the application is set to start automatically at system startup. more guide here.
from pyloid import Pyloid
app = Pyloid(app_name="MyApp", single_instance=True)
########## Usage ##########
print(app.is_auto_start()) # True or FalseReturns
boolWhether auto-start is active.File Watcher
watch_file
Adds a file to the watch list.
from pyloid import Pyloid
app = Pyloid(app_name="MyApp", single_instance=True)
########## Usage ##########
result = app.watch_file("path/to/file.txt")
print(result) # True if successfulParameters
Prop
Type
Returns
boolTrue if successful.watch_directory
Adds a directory to the watch list.
from pyloid import Pyloid
app = Pyloid(app_name="MyApp", single_instance=True)
########## Usage ##########
result = app.watch_directory("path/to/directory")Parameters
Prop
Type
Returns
boolTrue if successful.stop_watching
Removes a file or directory from the watch list.
from pyloid import Pyloid
app = Pyloid(app_name="MyApp", single_instance=True)
########## Usage ##########
result = app.stop_watching("path/to/watch")Parameters
Prop
Type
Returns
boolTrue if successful.get_watched_paths
Returns all currently watched paths.
from pyloid import Pyloid
app = Pyloid(app_name="MyApp", single_instance=True)
########## Usage ##########
paths = app.get_watched_paths()Returns
List[str]Watched paths or files or directories.get_watched_files
Returns all currently watched files.
from pyloid import Pyloid
app = Pyloid(app_name="MyApp", single_instance=True)
########## Usage ##########
files = app.get_watched_files()Returns
List[str]Watched file paths.get_watched_directories
Returns all currently watched directories.
from pyloid import Pyloid
app = Pyloid(app_name="MyApp", single_instance=True)
########## Usage ##########
directories = app.get_watched_directories()Returns
List[str]Watched directory paths.remove_all_watched_paths
Removes all paths from the watch list.
from pyloid import Pyloid
app = Pyloid(app_name="MyApp", single_instance=True)
########## Usage ##########
app.remove_all_watched_paths()Returns
Noneset_file_change_callback
Sets the callback function to be called when a file is changed.
from pyloid import Pyloid
app = Pyloid(app_name="MyApp", single_instance=True)
########## Usage ##########
app.set_file_change_callback(lambda path: print(f"File changed: {path}"))Parameters
Prop
Type
Returns
Noneset_directory_change_callback
Sets the callback function to be called when a directory is changed.
from pyloid import Pyloid
app = Pyloid(app_name="MyApp", single_instance=True)
########## Usage ##########
app.set_directory_change_callback(lambda path: print(f"Directory changed: {path}"))Parameters
Prop
Type
Returns
NoneFile Dialogs
open_file_dialog
Opens a dialog to open a file. This functionality is implemented using PySide6's QFileDialog class.
from pyloid import Pyloid
app = Pyloid(app_name="MyApp", single_instance=True)
########## Usage ##########
file_path = app.open_file_dialog(dir="/home/user", filter="Text Files (*.txt);;All Files (*)")
if file_path:
print("Selected file:", file_path)Parameters
Prop
Type
Returns
Optional[str]Returns the path of the selected file. Returns None if no file is selected.save_file_dialog
Opens a dialog to save a file. This functionality is implemented using PySide6's QFileDialog class.
from pyloid import Pyloid
app = Pyloid(app_name="MyApp", single_instance=True)
########## Usage ##########
file_path = app.save_file_dialog(dir="/home/user", filter="Text Files (*.txt);;All Files (*)")
if file_path:
print("File will be saved to:", file_path)Parameters
Prop
Type
Returns
Optional[str]Returns the path of the selected file. Returns None if no file is selected.select_directory_dialog
Opens a dialog to select a directory. This functionality is implemented using PySide6's QFileDialog class.
from pyloid import Pyloid
app = Pyloid(app_name="MyApp", single_instance=True)
########## Usage ##########
directory_path = app.select_directory_dialog(dir="/home/user")
if directory_path:
print("Selected directory:", directory_path)Parameters
Prop
Type
Returns
Optional[str]Returns the path of the selected directory. Returns None if no directory is selected.Platform Dirs
user_data_dir
Returns the user data directory path.
from pyloid import Pyloid
app = Pyloid(app_name="MyApp", single_instance=True)
########## Usage ##########
data_dir = app.user_data_dir()Returns
strPath to the user data directory.site_data_dir
Returns the site data directory path.
from pyloid import Pyloid
app = Pyloid(app_name="MyApp", single_instance=True)
########## Usage ##########
data_dir = app.site_data_dir()Returns
strPath to the site data directory.user_cache_dir
Returns the user cache directory path.
from pyloid import Pyloid
app = Pyloid(app_name="MyApp", single_instance=True)
########## Usage ##########
cache_dir = app.user_cache_dir()Returns
strPath to the user cache directory.user_log_dir
Returns the user log directory path.
from pyloid import Pyloid
app = Pyloid(app_name="MyApp", single_instance=True)
########## Usage ##########
log_dir = app.user_log_dir()Returns
strPath to the user log directory.user_documents_dir
Returns the user documents directory path.
from pyloid import Pyloid
app = Pyloid(app_name="MyApp", single_instance=True)
########## Usage ##########
docs_dir = app.user_documents_dir()Returns
strPath to the user documents directory.user_downloads_dir
Returns the user downloads directory path.
from pyloid import Pyloid
app = Pyloid(app_name="MyApp", single_instance=True)
########## Usage ##########
downloads_dir = app.user_downloads_dir()Returns
strPath to the user downloads directory.user_pictures_dir
Returns the user pictures directory path.
from pyloid import Pyloid
app = Pyloid(app_name="MyApp", single_instance=True)
########## Usage ##########
pictures_dir = app.user_pictures_dir()Returns
strPath to the user pictures directory.user_videos_dir
Returns the user videos directory path.
from pyloid import Pyloid
app = Pyloid(app_name="MyApp", single_instance=True)
########## Usage ##########
videos_dir = app.user_videos_dir()Returns
strPath to the user videos directory.user_music_dir
Returns the user music directory path.
from pyloid import Pyloid
app = Pyloid(app_name="MyApp", single_instance=True)
########## Usage ##########
music_dir = app.user_music_dir()Returns
strPath to the user music directory.user_desktop_dir
Returns the user desktop directory path.
from pyloid import Pyloid
app = Pyloid(app_name="MyApp", single_instance=True)
########## Usage ##########
desktop_dir = app.user_desktop_dir()Returns
strPath to the user desktop directory.user_runtime_dir
Returns the user runtime directory path.
from pyloid import Pyloid
app = Pyloid(app_name="MyApp", single_instance=True)
########## Usage ##########
runtime_dir = app.user_runtime_dir()Returns
strPath to the user runtime directory.Store API
store
Returns a Store instance for the given path.
from pyloid import Pyloid
app = Pyloid(app_name="MyApp", single_instance=True)
########## Usage ##########
store = app.store("settings.json")
store.set("theme", "dark")
print(store.get("theme"))Parameters
Prop
Type
Returns
StoreStore object supporting .set() and .get().Run the App
run
Runs the application event loop.
from pyloid import Pyloid
app = Pyloid(app_name="MyApp", single_instance=True)
########## Usage ##########
app.run()Returns
NoneStarts the application event loop.