pdfreading-app 0.1.0__tar.gz

pdfreading_app-0.1.0/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: pdfreading-app
+Version: 0.1.0
+Summary: A PDF reader desktop app
+Requires-Python: >=3.9
+Requires-Dist: customtkinter
+Requires-Dist: pillow
+Requires-Dist: pymupdf

pdfreading_app-0.1.0/README.md

@@ -0,0 +1 @@
+# Book-Reading-GUI-app

pdfreading_app-0.1.0/pyproject.toml

@@ -0,0 +1,20 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pdfreading-app"
+version = "0.1.0"
+description = "A PDF reader desktop app"
+requires-python = ">=3.9"
+dependencies = [
+    "pillow",
+    "pymupdf",
+    "customtkinter"
+]
+
+[project.scripts]
+pdfreading-app = "pdfreading.main:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pdfreading"]

pdfreading_app-0.1.0/src/pdfreading/main.py

@@ -0,0 +1,105 @@
+import os
+import sys
+import json
+from importlib.resources import files
+from pathlib import Path
+import customtkinter as ctk
+from PIL import Image, ImageTk
+from .utils import UI, functionality, Data
+from .utils.functionality import _register_file
+
+# store the library folder in a variable so it can be used across different os
+LIBARY_DIR = Path.home() / "ReadDaBookLibrary"
+# create a dir on the first run and does nothing
+LIBARY_DIR.mkdir(parents=True, exist_ok=True)
+# store the progress file in a variable so it can be used across different os
+PROGRESS_FILE = LIBARY_DIR / "progress.json"
+
+# the app icon or logo
+def set_app_icon(app):
+    try:
+        # windows OS
+        if sys.platform == "win32":
+            ico_path = LIBARY_DIR / "book2.ico"
+            if not ico_path.exists():
+                src = files("pdfreader.assets.title_icon").joinpath("book2.png")
+                img = Image.open(src)
+                img.save(ico_path, format="ICO", sizes=[(16, 16), (32, 32), (64, 64)])
+            app.iconbitmap(str(ico_path))
+        # macOS
+        elif sys.platform == "darwin":
+            src = files("pdfreader.assets.title_icon").joinpath("book2.png")
+            img = Image.open(src).resize((64, 64))
+            photo = ImageTk.PhotoImage(img)
+            app.iconphoto(True, photo)
+            app._icon_photo = photo
+        else:
+            # linux and other OSes
+            src = files("pdfreader.assets.title_icon").joinpath("book2.png")
+            img = Image.open(src).resize((32, 32))
+            photo = ImageTk.PhotoImage(img)
+            app.iconphoto(True, photo)
+            app._icon_photo = photo
+    except Exception as e:
+        print(f"Could not set icon: {e}")
+
+# load the user's reading progress
+def load_progress():
+    if PROGRESS_FILE.exists():
+        try:
+            with open(PROGRESS_FILE, "r") as f:
+                # load the last read pages from the progress file.
+                Data.last_read_pages.update(json.load(f))
+        except Exception:
+            # if there's an error loading the progress (e.g. file is corrupted), just ignore it and start with an empty progress.
+            pass
+
+# save the user's reading progress to a file so it can be loaded on the next startup
+def save_progress():
+    # if there's a currently selected file and an open document, save the current page to the last_read_pages dict
+    if Data.selected_file and Data.doc:
+        Data.last_read_pages[Data.selected_file] = functionality._current_page
+    try:
+        # open the progress file for writing and save the last_read_pages dict as json. this way we can restore the user's last read page for each book on the next startup.
+        with open(PROGRESS_FILE, "w") as f:
+            json.dump(Data.last_read_pages, f)
+    except Exception as e:
+        print(f"Couldn't Save Progress: {e}")
+
+def main():
+    # give functionality.py the resolved path so _copy_to_library know where to save files
+    functionality.LIBARY_DIR = LIBARY_DIR
+    # the app set up color
+    ctk.set_appearance_mode("System")
+    ctk.set_default_color_theme("blue")
+
+    # create a window to open
+    app = ctk.CTk()
+    set_app_icon(app)
+    # the app title
+    app.title("Read da book")
+    # the size of the app when not open fullscreen
+    app.geometry("1200x600")
+
+    # when the user closes the app, we want to save their progress before the app actually closes. this function is called by the WM_DELETE_WINDOW protocol handler below.
+    def on_close():
+        save_progress()
+        app.destroy()
+
+    # build the UI and attach it to the app window
+    UI.build(app)
+    load_progress()
+    # set the on_close function to be called when the user tries to close the window, so we can save their progress first
+    app.protocol("WM_DELETE_WINDOW", on_close)
+
+    '''restore previously added files from the library folder on startup'''
+    # lists every file in the library folder. sorted() puts them in alphabetical order so the list always appears in the same order regardless of filesystem ordering.
+    for fname in sorted(os.listdir(LIBARY_DIR)):
+        if fname.lower().endswith(".pdf"):
+            fpath = os.path.join(LIBARY_DIR, fname)
+            _register_file(fpath, fname)
+    app.mainloop()
+
+# open the app
+if __name__ == "__main__":
+    main()

pdfreading_app-0.1.0/src/pdfreading/openDialog/AddFile.py

@@ -0,0 +1,14 @@
+from tkinter import filedialog as fida
+import os
+
+# open file dialog and ask the user to select a pdf file
+def add_pdf():
+    filename = fida.askopenfilename(
+        initialdir="/", 
+        filetypes=[("PDF file", "*.pdf")]
+    )
+    # if a file is selected, return the file path and name, otherwise return None
+    if filename:
+        return filename, os.path.basename(filename)
+    
+    return None, None

pdfreading_app-0.1.0/src/pdfreading/openDialog/Addurl.py

@@ -0,0 +1,149 @@
+import urllib.request
+import os
+import threading
+import customtkinter as ctk
+from ..utils import functionality
+
+# clean the URL nicely remove the query parameters and get the filename, if the filename doesn't end with .pdf we just name it download.pdf, 
+# and we also remove any characters that are not alphanumeric or ._- to avoid issues with the filesystem
+def _sanitize_filename(url: str) -> str:
+    name = url.rstrip("/").split("/")[-1].split("?")[0]
+    if not name.lower().endswith(".pdf"):
+        name = "download.pdf"
+
+    new_name = ""
+    for c in name:
+        if c.isalnum() or c in "._- ":
+            new_name += c
+    name = new_name
+    return name or "download.pdf"
+
+# Opens a modal dialog asking the user for a PDF URL.
+def open_url_dialog(app, on_success):
+    dialog = ctk.CTkToplevel(app)
+    dialog.title("Load PDF from URL")
+    dialog.geometry("480x220")
+    dialog.resizable(False, False)
+    dialog.transient(app)
+    dialog.grab_set()
+
+    my_font    = ctk.CTkFont(family="Arial", size=13, weight="bold")
+    small_font = ctk.CTkFont(family="Arial", size=11)
+    # the title and entry box for the URL
+    ctk.CTkLabel(dialog, text="PDF URL:", font=my_font).pack(
+        anchor="w", padx=20, pady=(20, 2)
+    )
+    url_entry = ctk.CTkEntry(
+        dialog, 
+        width=440, 
+        font=small_font,
+        placeholder_text="https://example.com/file.pdf"
+    )
+    url_entry.pack(padx=20)
+    
+    status_label = ctk.CTkLabel(dialog, text="", font=small_font, text_color="gray70")
+    status_label.pack(pady=(8, 0))
+    # the progress bar
+    progress = ctk.CTkProgressBar(dialog, width=440, mode="indeterminate")
+
+    btn_frame = ctk.CTkFrame(dialog, fg_color="transparent")
+    btn_frame.pack(pady=12)
+
+    # helper function to update the status label and color
+    def _set_status(msg, color="gray70"):
+        status_label.configure(text=msg, text_color=color)
+
+    # helper function to re-enable the UI elements after a download attempt (whether successful or not)
+    def _re_enable():
+        progress.stop()
+        progress.pack_forget()
+        btn_download.configure(state="normal")
+        btn_cancel.configure(state="normal")
+        url_entry.configure(state="normal")
+
+    """Background thread: download → validate → callback."""
+    def _do_download():
+        url = url_entry.get().strip()
+        # if the URL field is empty, show an error and re-enable the UI so they can try again
+        if not url:
+            dialog.after(0, lambda: _set_status("Please enter a URL.", "red"))
+            dialog.after(0, _re_enable)
+            return
+        # if the URL doesn't start with http:// or https://, show an error and re-enable the UI so they can try again
+        if not url.startswith(("http://", "https://")):
+            dialog.after(0, lambda: _set_status("URL must start with http:// or https://", "red"))
+            dialog.after(0, _re_enable)
+            return
+
+        filename = _sanitize_filename(url)
+        filepath = os.path.join(functionality.LIBARY_DIR, filename)
+        # try downloading the file from the URL to a temp location
+        try:
+            urllib.request.urlretrieve(url, filepath)
+        except Exception as e:
+            dialog.after(0, lambda err=e: _set_status(f"Download failed: {err}", "red"))
+            dialog.after(0, _re_enable)
+            return
+
+        # open the downloaded file and check if it has a valid PDF header, if not it's not a valid PDF so we delete the file
+        try:
+            # open the pdf file as binary mode and read the first 5 bytes to check for the PDF header "%PDF-"
+            with open(filepath, "rb") as f:
+                header = f.read(5)
+            if header != b"%PDF-":
+                os.remove(filepath)
+                dialog.after(0, lambda: _set_status("That URL did not return a PDF file.", "red"))
+                dialog.after(0, _re_enable)
+                return
+        except Exception as e:
+            dialog.after(0, lambda err=e: _set_status(f"Error reading file: {err}", "red"))
+            dialog.after(0, _re_enable)
+            return
+
+        # schedule _finish to run on the main thread as soon as it is free
+        dialog.after(0, lambda fp=filepath, fn=filename: _finish(fp, fn))
+
+    # helper function to clean up the dialog and call the on_success callback with the downloaded file path and name
+    def _finish(filepath, filename):
+        # stop the progress bar
+        progress.stop()
+        # hide it
+        progress.pack_forget()
+        # grab_release and destroy the dialog before calling on_success to avoid any potential issues if on_success takes a long time to execute or opens another dialog
+        dialog.grab_release()
+        dialog.destroy()
+        on_success(filepath, filename)   
+
+    # helper function to start the download thread and update the UI accordingly
+    def _start():
+        url = url_entry.get().strip()
+        if not url:
+            _set_status("Please enter a URL.", "red")
+            return
+        btn_download.configure(state="disabled")
+        btn_cancel.configure(state="disabled")
+        url_entry.configure(state="disabled")
+        progress.pack(padx=20, pady=(0, 4))
+        progress.start()
+        _set_status("Downloading…", "gray70")
+        threading.Thread(target=_do_download, daemon=True).start()
+
+    btn_download = ctk.CTkButton(
+        btn_frame, 
+        text="Download & Open",
+        font=my_font, 
+        command=_start
+    )
+    btn_download.pack(side="left", padx=8)
+
+    btn_cancel = ctk.CTkButton(
+        btn_frame, 
+        text="Cancel", 
+        font=my_font,
+        fg_color="gray40", 
+        hover_color="gray30",
+        command=dialog.destroy
+    )
+    btn_cancel.pack(side="left", padx=8)
+    # allow pressing Enter to trigger the download
+    dialog.bind("<Return>", lambda e: _start())

pdfreading_app-0.1.0/src/pdfreading/utils/Data.py

@@ -0,0 +1,31 @@
+'''This is a shared state file that is imported by both UI.py and functionality.py'''
+
+# stores every PDF the user has added when they press the "Add PDF" button
+# key = the filename shown in the left panel  (e.g. "mybook.pdf")
+# value = the full file path on disk (e.g. "C:/Users/.../mybook.pdf")
+pdf_files = {}
+
+# stores the CTkLabel widget for each file shown in the left frame
+# key = filename  (same key as pdf_files so we can look up both together)
+# value = the CTkLabel widget — we keep this so we can highlight it when the user clicks it, and destroy it when the user removes the file
+file_labels = {} 
+
+# currently selected filename
+selected_file = None 
+
+# the fitz Document object for the PDF that is currently open and being viewed
+# fitz.open() returns this so it gives us access to page count, page sizes, and lets us render individual pages to pixel data
+doc = None # open fitz.Document
+
+# widget refs set by UI.py
+app = None
+# the CTkCanvas on the right side where we render PDF pages
+pdf_container = None
+# the CTkLabel on the left side that shows the filename
+file_list = None
+# the CTkEntry in the top-right where the user can type a page number to jump to
+page_entry = None
+# the CTkLabel in the top-right that shows "Page X / Y"
+page_total_label = None
+# store the user last read page when they close the app so it stay there
+last_read_pages = {}

pdfreading_app-0.1.0/src/pdfreading/utils/UI.py

@@ -0,0 +1,222 @@
+import customtkinter as ctk
+from PIL import Image
+from . import Data, functionality
+from importlib.resources import files
+from .functionality import handle_add_pdf, open_pdf, remove_pdf, zoom_in, zoom_out, poll_scroll, set_canvas, prev_page, next_page, handle_add_url, jump_to_entered_page
+
+def build(app):
+    Data.app = app
+    # the font we use for all buttons and Labels in the UI
+    my_font = ctk.CTkFont(family="Arial", size=15, weight="bold")
+
+    # the top frame
+    top_frame = ctk.CTkFrame(app)
+    top_frame.pack(fill="x", padx=10, pady=5)
+    # helper function to add icons to the buttons
+    def make_icon(filename):
+        path = files("pdfreader.assets.button_icon").joinpath(filename)
+        img = Image.open(path)
+        return ctk.CTkImage(
+            light_image=img, 
+            dark_image=img, 
+            size=(20, 20)
+        )
+    
+    # add pdf button
+    btn_add = ctk.CTkButton(
+        top_frame, 
+        text="Add PDF",
+        image=make_icon("add.png"),
+        compound="left", 
+        command=handle_add_pdf, 
+        font=my_font,
+        fg_color="#a51f1f",
+        hover_color="#145a8a"
+    )
+    btn_add.pack(side="left", padx=5)
+
+    btn_url = ctk.CTkButton(
+        top_frame,
+        text="From URL",
+        image=make_icon("url.png"),
+        compound="left",
+        command=handle_add_url,
+        font=my_font,
+        fg_color="#a51f1f",
+        hover_color="#145a8a"
+    )
+    btn_url.pack(side="left", padx=5)
+    
+    # open button
+    btn_open = ctk.CTkButton(
+        top_frame, 
+        text="Open",
+        image=make_icon("open.png"),
+        compound="left", 
+        command=open_pdf, 
+        font=my_font,
+        fg_color="#a51f1f",
+        hover_color="#145a8a"
+    )
+    btn_open.pack(side="left", padx=5)
+    
+    # remove button
+    btn_remove = ctk.CTkButton(
+        top_frame, 
+        text="Remove",
+        image=make_icon("remove.png"),
+        compound="left", 
+        command=remove_pdf, 
+        font=my_font,
+        fg_color="#a51f1f",
+        hover_color="#145a8a"
+    )
+    btn_remove.pack(side="left", padx=5)
+
+    # zoom in button
+    btn_zoom_in = ctk.CTkButton(
+        top_frame, 
+        text="Zoom",
+        image=make_icon("zoom_in.png"),
+        compound="left", 
+        command=zoom_in, 
+        font=my_font,
+        fg_color="#55a51f",
+        hover_color="#145a8a"
+    )
+    btn_zoom_in.pack(side="right", padx=5)
+    
+    # zoom out button
+    btn_zoom_out = ctk.CTkButton(
+        top_frame, 
+        text="Zoom",
+        image=make_icon("zoom_out.png"),
+        compound="left", 
+        command=zoom_out, 
+        font=my_font,
+            fg_color="#55a51f",
+        hover_color="#145a8a"
+    )
+    btn_zoom_out.pack(side="right", padx=5)
+
+    # separator gap between zoom and page nav
+    ctk.CTkLabel(top_frame, text="", width=10).pack(side="right")
+
+    # next page button  ▶
+    btn_next = ctk.CTkButton(
+        top_frame,
+        text="▶",
+        width=40,
+        command=next_page,
+        font=my_font,
+        fg_color="#a57f1f",
+        hover_color="#145a8a"
+    )
+    btn_next.pack(side="right", padx=2)
+
+    # page input frame: [ entry ] / N
+    page_nav_frame = ctk.CTkFrame(top_frame, fg_color="transparent")
+    page_nav_frame.pack(side="right", padx=4)
+
+    # the editable page number entry
+    Data.page_entry = ctk.CTkEntry(
+        page_nav_frame,
+        font=my_font,
+        width=52,
+        justify="center"
+    )
+    Data.page_entry.pack(side="left")
+    Data.page_entry.bind("<Return>", lambda e: functionality.jump_to_entered_page())
+    Data.page_entry.bind("<FocusOut>", lambda e: functionality.jump_to_entered_page())
+
+    # the " / N" total pages label next to the entry
+    Data.page_total_label = ctk.CTkLabel(
+        page_nav_frame,
+        text="/ --",
+        font=my_font,
+        anchor="w",
+        width=50
+    )
+    Data.page_total_label.pack(side="left", padx=(4, 0))
+
+    # prev page button  ◀
+    btn_prev = ctk.CTkButton(
+        top_frame,
+        text="◀",
+        width=40,
+        command=prev_page,
+        font=my_font,
+        fg_color="#a57f1f",
+        hover_color="#145a8a"
+    )
+    btn_prev.pack(side="right", padx=2)
+
+    # content frame
+    content_frame = ctk.CTkFrame(app)
+    content_frame.pack(fill="both", expand=True, padx=10, pady=5)
+
+    # left frame
+    left_frame = ctk.CTkFrame(
+        content_frame,
+        fg_color="gray30",       
+        corner_radius=8,
+        width=200
+    )
+    left_frame.pack(side="left", fill="y", padx=(5, 0), pady=0)
+    left_frame.pack_propagate(False)
+
+    # inner frame sits inside with a small margin, creating the border effect
+    inner_frame = ctk.CTkFrame(left_frame, corner_radius=6)
+    inner_frame.pack(fill="both", expand=True, padx=2, pady=2)
+
+    # header row with icon and title
+    header_frame = ctk.CTkFrame(inner_frame, fg_color="transparent")
+    header_frame.pack(fill="x", padx=8, pady=(8, 4))
+
+    ctk.CTkLabel(
+        header_frame,
+        text=" My Files",
+        font=my_font,
+        anchor="w",
+        image=make_icon("folder.png"),
+        compound="left"
+    ).pack(side="left")
+
+    # thin separator line below the header
+    ctk.CTkFrame(inner_frame, height=2, fg_color="gray40").pack(fill="x", padx=6, pady=(0, 4))
+
+    Data.file_list = ctk.CTkScrollableFrame(inner_frame, fg_color="transparent")
+    Data.file_list.pack(fill="both", expand=True, padx=2, pady=(0, 2))
+
+    # right frame
+    right_frame = ctk.CTkFrame(content_frame)
+    right_frame.pack(side="right", fill="both", expand=True, padx=5)
+
+    scrollbar = ctk.CTkScrollbar(right_frame)
+    scrollbar.pack(side="right", fill="y")
+
+    # background colour matches CTk dark/light mode reasonably well
+    canvas = ctk.CTkCanvas(
+        right_frame,
+        bg="#2b2b2b",
+        highlightthickness=0,
+        yscrollcommand=scrollbar.set
+    )
+    canvas.pack(side="left", fill="both", expand=True)
+    scrollbar.configure(command=canvas.yview)
+
+    # mouse wheel scrolling
+    def _on_mousewheel(event):
+        canvas.yview_scroll(int(-1 * (event.delta / 120)), "units")
+    
+    # Windows and MacOS
+    canvas.bind("<MouseWheel>", _on_mousewheel)
+    # Linux
+    canvas.bind("<Button-4>",   lambda e: canvas.yview_scroll(-1, "units")) 
+    canvas.bind("<Button-5>",   lambda e: canvas.yview_scroll( 1, "units")) 
+
+    # hand the canvas to functionality.py
+    set_canvas(canvas)
+
+    # start the scroll polling loop
+    Data.app.after(100, poll_scroll)

pdfreading_app-0.1.0/src/pdfreading/utils/functionality.py

@@ -0,0 +1,539 @@
+import shutil
+import os
+import threading
+import queue
+import fitz
+from PIL import Image, ImageTk
+import customtkinter as ctk
+from ..openDialog.AddFile import add_pdf
+from ..openDialog.Addurl import open_url_dialog
+from . import Data
+
+# this dir is set by UI.py when the app start, it is where all the pdf files are stored permanently
+LIBARY_DIR = None
+# the default zoom level or initial value
+zoom_level = 1.0
+# True if the user has manually zoomed; False means auto-fit on open/resize
+_zoom_manual = False
+# every time a user open a new file or zoom this generation go up by one
+# the worker thread compares its saved generation against this value, so if they are different outdated and thrown away without displaying
+render_generation = 0
+
+# store the id returned by app.after() for the zoom debounce timer
+# we keep it so we can cancel the previous timer if the user click zoom again
+_zoom_after_id = None
+# the scroll position we saw last time poll_scroll ran
+# we compare against this to avoid calling check_visible_page every 100ms
+# when the user isn't scrolling
+_last_scroll_pos = None
+
+# tracks the page number
+_current_page = 0
+
+# the vertical gap in pixels between pages on the canvas
+PAGE_GAP = 10
+# render this many pixels above/below the visible area
+BUFFER_PX = 600  
+# unload pages this far outside the visible area
+UNLOAD_PX = 1200 
+
+# canvas widget stored here so the whole module can reach it
+_canvas = None
+
+# stores the position and size of every page on the canvas
+# key   = page number (0-indexed)
+# value = (x, y, w, h) — top-left corner and size in canvas pixels
+# built once in _rebuild() and updated in _on_canvas_resize(
+_page_rects = {}
+
+# canvas image item ids  (page_num → canvas item id of the rendered image)
+_image_items = {}
+
+# PhotoImage refs — must be kept alive or tkinter GCs them
+_photo_refs  = {}
+
+# the queue that check_visible_pages pushes work onto and _worker pulls from
+# using a queue means the worker processes pages one at a time in order,
+# instead of spawning a new thread per page which causes memory spikes
+_render_queue = queue.Queue()
+
+# tracks which page numbers are currently sitting inside _render_queue
+# so _enqueue() never adds the same page twice while it's still waiting
+_queued_pages = set()
+
+# a lock that protects _queued_pages from being read/written simultaneously
+# by the main thread (_enqueue) and the worker thread (_worker)
+_queued_lock  = threading.Lock()
+
+def _worker():
+    # this loop lives forever inside the app
+    while True:
+        # block here until check_visible_pages put a page onto the queue
+        page_num, gen = _render_queue.get()
+        try:
+            # remove from the queued set so it can be re-queued later if needed
+            with _queued_lock:
+                _queued_pages.discard(page_num)
+            # if render_generation change or there's nothing in the doc skip it 
+            if gen != render_generation or Data.doc is None:
+                continue
+
+            # render the page
+            page = Data.doc[page_num]
+            pix  = page.get_pixmap(matrix=fitz.Matrix(zoom_level, zoom_level))
+            # convert to PIL
+            img  = Image.frombytes("RGB", [pix.width, pix.height], pix.samples)
+            del pix
+            # check if it is still in the same generation, if so app.after(0, fn) queues fn to run as soon as the main thread is free, which is the safe way to update the UI from a thread
+            if gen == render_generation:
+                Data.app.after(0, lambda i=img, n=page_num, g=gen: _show_page(i, n, g))
+            else:
+                del img
+        except Exception as e:
+            print(f"Render error page {page_num}: {e}")
+        finally:
+            # always call task_done so queue.join() work correctly if ever used
+            _render_queue.task_done()
+
+# start the worker thread
+threading.Thread(target=_worker, daemon=True).start()
+
+def _enqueue(page_num, gen):
+    # add a page to the render queue
+    with _queued_lock:
+        # if the page is already in the queue return
+        if page_num in _queued_pages:
+            return
+        # mark is as queue before releasing the lock
+        _queued_pages.add(page_num)
+
+    _render_queue.put((page_num, gen))
+
+# empty the render queue
+def _drain():
+    # clear the tracking set so _enqueue accept new pages immediately
+    with _queued_lock:
+        _queued_pages.clear()
+    # pull everything out of the queue without processing it
+    while not _render_queue.empty():
+        try:
+            _render_queue.get_nowait()
+            _render_queue.task_done()
+        except queue.Empty:
+            break
+
+# update the page entry and total label in the top bar
+def _update_page_label():
+    if Data.page_entry is None:
+        return
+    if Data.doc is None:
+        Data.page_entry.delete(0, "end")
+        Data.page_total_label.configure(text="/ --")
+        return
+    total = len(Data.doc)
+    # update the entry to show the current page number
+    Data.page_entry.delete(0, "end")
+    Data.page_entry.insert(0, str(_current_page + 1))
+    # update the " / N" label
+    Data.page_total_label.configure(text=f"/ {total}")
+
+# called when the user presses Enter or clicks away from the page entry
+def jump_to_entered_page():
+    if Data.doc is None or Data.page_entry is None:
+        return
+    raw = Data.page_entry.get().strip()
+    total = len(Data.doc)
+    # if empty or invalid, fall back to page 1
+    try:
+        page = int(raw)
+        if page < 1 or page > total:
+            raise ValueError
+    except ValueError:
+        page = 1
+    # update the entry to show the corrected value
+    Data.page_entry.delete(0, "end")
+    Data.page_entry.insert(0, str(page))
+    go_to_page(page - 1)  
+
+
+# Copy src_filepath into LIBRARY_DIR and return the new permanent path
+def _copy_to_library(src_filepath, filename):
+    dest = os.path.join(LIBARY_DIR, filename)
+    # if the abosulute path of the src and dest are the same, it means the file is already in the library so we don't need to copy it, just return the path
+    if os.path.abspath(src_filepath) != os.path.abspath(dest):
+        shutil.copy2(src_filepath, dest)
+    return dest
+
+# if the filename already exist in the library, we add (1), (2) etc before the extension until we find a unique name
+def _unique_filename(filename):
+    if "." in filename:
+        # base is the filename without extension, ext is the extension with dot (e.g "book.pdf" -> base="book", ext="pdf") because we split "."
+        base, ext = filename.rsplit(".", 1)
+        # add the "." back to the extension we split off
+        ext = "." + ext
+    else:
+        # else we just treat the whole filename as base and extension is empty
+        base, ext = filename, ""
+    unique = filename
+    counter = 1
+    # while the unique name is already a key in the pdf_files dict, generate a new name by adding (counter) before the extension and increment the counter
+    while unique in Data.pdf_files:
+        unique = f"{base} ({counter}){ext}"
+        counter += 1
+    return unique
+
+# this is called by both handle_add_pdf and the URL dialog when the user submit a URL, it takes care of copying the file to library, 
+# adding it to the left panel, and registering the click event to select the file when clicked
+def _register_file(filepath, filename):
+    filename = _unique_filename(filename)
+    perm_path = _copy_to_library(filepath, filename)
+    Data.pdf_files[filename] = perm_path
+    label = ctk.CTkLabel(Data.file_list, text=filename)
+    label.pack(anchor="w", padx=5, pady=2)
+    Data.file_labels[filename] = label
+    label.bind("<Button-1>", lambda e, name=filename: select_file(name))
+
+# function to handle pdf when user click add pdf button
+def handle_add_pdf():
+    # return the file path and name as filepath and filename
+    filepath, filename = add_pdf()
+    if not filepath:
+        return
+    _register_file(filepath, filename)
+
+# function to handle url when user click add url button
+def handle_add_url():
+    open_url_dialog(Data.app, _register_file)
+
+# when user clicks a file it saves which file is selected print it
+def select_file(filename):
+    Data.selected_file = filename
+    for lbl in Data.file_labels.values():
+        lbl.configure(fg_color="transparent")
+        # highlights the file text in gray background
+    Data.file_labels[filename].configure(fg_color="gray")
+    print(f"selected: {filename}")
+
+# when user click zoom in it increase the zoom level by 20%
+def zoom_in():
+    global zoom_level, _zoom_after_id, _zoom_manual
+    _zoom_manual = True
+    zoom_level += 0.2
+    # debounced so rapid clicks only trigger one render
+    if _zoom_after_id:
+        Data.app.after_cancel(_zoom_after_id)
+    _zoom_after_id = Data.app.after(300, _rebuild)
+
+# when user click zoom out it decrease the zoom level by 20% but it doesn't go beyond 40%
+def zoom_out():
+    global zoom_level, _zoom_after_id, _zoom_manual
+    _zoom_manual = True
+    zoom_level = max(0.4, zoom_level - 0.2)
+    if _zoom_after_id:
+        Data.app.after_cancel(_zoom_after_id)
+    _zoom_after_id = Data.app.after(300, _rebuild)
+
+# calculate the zoom level that makes the first page fill the canvas width
+def _fit_zoom_to_canvas():
+    global zoom_level
+    if Data.doc is None or _canvas is None:
+        return
+    canvas_w = _canvas.winfo_width()
+    if canvas_w < 10:
+        canvas_w = 800  # fallback before canvas is fully laid out
+    page_w = Data.doc[0].rect.width
+    if page_w > 0:
+        zoom_level = (canvas_w - 20) / page_w  # 10px padding each side
+
+# when user clicks open it check if there is a file selected
+def open_pdf():
+    global _zoom_manual
+    if not Data.selected_file:
+        print("No file selected")
+        return
+    # close the previous document if there is one
+    if Data.doc:
+        Data.doc.close()
+    Data.doc = fitz.open(Data.pdf_files[Data.selected_file])
+    # reset manual zoom so we auto-fit on open
+    _zoom_manual = False
+    _fit_zoom_to_canvas()
+    # draw the page placeholders and start lazy rendering 
+    _rebuild()
+    # restore the last read page after a short delay so _rebuild finish first
+    saved_page = Data.last_read_pages.get(Data.selected_file, 0)
+    if saved_page > 0:
+        Data.app.after(150, lambda: go_to_page(saved_page))
+
+# when user clicks remove it checks if there is a file selected
+def remove_pdf():
+    if not Data.selected_file:
+        print("No file selected")
+        return
+    
+    filepath = Data.pdf_files[Data.selected_file]
+
+    if Data.doc:
+        Data.doc.close()
+        Data.doc = None
+    # try to remove the file from the disk
+    try:
+        if os.path.exists(filepath):
+            os.remove(filepath)
+    except Exception as e:
+        print(f"Error removing file: {e}")
+        
+    # remove the file from the pdf_file
+    del Data.pdf_files[Data.selected_file]
+    # destroy the label widget in the left frame
+    Data.file_labels[Data.selected_file].destroy()
+    # then delete it fromn the file_labels
+    del Data.file_labels[Data.selected_file]
+    # then clear the selected file
+    Data.selected_file = None
+
+    # wipe everything off the canvas
+    _clear_canvas()
+    # clear the page label
+    _update_page_label()
+
+# (only called once by the UI.py once it created the canvas widget) it is use to store canvas reference and bind the resize event
+def set_canvas(canvas):
+    global _canvas
+    _canvas = canvas
+    # when the user resize the window, recenter all the page rectangle
+    _canvas.bind("<Configure>", lambda e: _on_canvas_resize(e))
+
+# scroll the canvas so that the top of page_num (0-indexed) is in view
+def go_to_page(page_num):
+    if Data.doc is None or not _page_rects:
+        return
+    # clamp to valid range
+    page_num = max(0, min(page_num, len(Data.doc) - 1))
+    if page_num not in _page_rects:
+        return
+
+    sr = _canvas.cget("scrollregion")
+    try:
+        total_h = float(sr.split()[3]) if sr else _canvas.winfo_height()
+    except Exception:
+        total_h = _canvas.winfo_height()
+    if total_h <= 0:
+        return
+
+    _, y, _, _ = _page_rects[page_num]
+    # scroll so the top of the page is at the top of the visible area
+    fraction = y / total_h
+    _canvas.yview_moveto(fraction)
+
+# go to the previous page relative to the current visible page
+def prev_page():
+    go_to_page(_current_page - 1)
+
+# go to the next page relative to the current visible page
+def next_page():
+    go_to_page(_current_page + 1)
+
+# when the window resizes, reposition all page rects to stay centred
+# if the user hasn't manually zoomed, re-fit the zoom to the new canvas width
+def _on_canvas_resize(e):
+    # if there is no page to loaded yet, return
+    if not _page_rects:
+        return
+    # the new canvas width in pixels
+    canvas_w = e.width
+
+    # if auto-fit mode, recalculate zoom and fully rebuild at the new scale
+    if not _zoom_manual and Data.doc is not None:
+        _fit_zoom_to_canvas()
+        _rebuild()
+        return
+
+    for page_num, (x, y, w, h) in list(_page_rects.items()):
+        # calculate the new x so the page is centered in the canvas
+        new_x = max(0, (canvas_w - w) // 2)
+        # update the stored rect with the new x position
+        _page_rects[page_num] = (new_x, y, w, h)
+        # move the gray background rectangle on canvas to a new position
+        tag = f"bg_{page_num}"
+        _canvas.coords(tag, new_x, y, new_x + w, y + h)
+        # if this page has a rendered image on the canvas, move it too
+        if page_num in _image_items:
+            _canvas.coords(_image_items[page_num], new_x + w // 2, y + h // 2)
+    # re-checked which page are visible after the resize
+    check_visible_pages()
+
+# delete everything from the canvas and reset all tracking dicts
+def _clear_canvas():
+    global _page_rects, _image_items, _photo_refs
+    if _canvas:
+        _canvas.delete("all")
+    _page_rects.clear()
+    _image_items.clear()
+    _photo_refs.clear()
+
+# redraws all page placeholder retangles on the canvas (called when opening a new pdf or zooming)
+def _rebuild():
+    global render_generation, _current_page
+    render_generation += 1
+    _drain()
+    _clear_canvas()
+    # check if there's no document is open or canvas doesn't exist yet
+    if Data.doc is None or _canvas is None:
+        return
+
+    # reset to page 1 whenever we (re)build then scroll to top first
+    _current_page = 0
+    _canvas.yview_moveto(0.0)
+
+    # total number of page
+    n_pages  = len(Data.doc)
+    # current canvas width, fall back 800
+    canvas_w = _canvas.winfo_width() or 800
+
+    # y track the vertical position of the next page as we stack them
+    y = PAGE_GAP
+
+    for page_num in range(n_pages):
+        r = Data.doc[page_num].rect
+        # scale the dimension by the current zoom level
+        w = int(r.width  * zoom_level)
+        h = int(r.height * zoom_level)
+
+        # center the page horizontally on the canvas
+        x = max(0, (canvas_w - w) // 2)
+
+        # save the position so check_visible_page can find this page later 
+        _page_rects[page_num] = (x, y, w, h)
+
+        # draw a gray rectangle as the placeholder
+        _canvas.create_rectangle(
+            x, y, x + w, y + h,
+            fill="#333333", 
+            outline="#555555",
+            tags=(f"bg_{page_num}",)
+        )
+
+        # page number label in the centre of the placeholder
+        _canvas.create_text(
+            x + w // 2, y + h // 2,
+            text=str(page_num + 1),
+            fill="#888888",
+            font=("Arial", 14),
+            tags=(f"lbl_{page_num}",)
+        )
+
+        y += h + PAGE_GAP
+
+    # set the canvas scroll region to the full document height
+    _canvas.configure(scrollregion=(0, 0, canvas_w, y))
+
+    # update the counter to show Page 1 / N
+    _update_page_label()
+
+    check_visible_pages()
+
+# run every 100ms on the main thread
+def poll_scroll():
+    global _last_scroll_pos
+    # if there is a document open and page rects to check
+    if Data.doc is not None and _page_rects:
+        # return the current scroll position as a tuple (top_fraction, bottom_fraction)
+        pos = _canvas.yview()
+        # if the scroll position changed since last time, check which page are visible and need rendering
+        if pos != _last_scroll_pos:
+            _last_scroll_pos = pos
+            check_visible_pages()
+    # schedule the next poll in 100ms
+    Data.app.after(100, poll_scroll)
+
+# look at every page rect and decide whether to render or unload it based on its position relative to the visible area of the canvas
+def check_visible_pages():
+    global _current_page
+
+    if Data.doc is None or not _page_rects or _canvas is None:
+        return
+
+    # visible range in canvas content pixels
+    sr = _canvas.cget("scrollregion")
+    try:
+        # if scrollregion is set it looks like "0 0 800 2400", we want the total height which is the 4th number
+        if sr:
+            total_h = float(sr.split()[3])
+        else:
+            # else we can get the canvas height in pixels
+            total_h = _canvas.winfo_height()
+    except Exception:
+        total_h = _canvas.winfo_height()
+    # if we can't get a valid total height, just return
+    if total_h <= 0:
+        return
+    # yview() return the fractions: (0.0, 0.1) means the top 10% of the canvas content is visible, we multiply by total_h to get the pixel position of the visible area
+    t, b = _canvas.yview()
+    vis_top = t * total_h
+    vis_bot = b * total_h
+    vis_mid = (vis_top + vis_bot) / 2
+
+    # find which page's centre is closest to the centre of the viewport
+    # this gives the most natural "current page" feel while scrolling
+    best_page = _current_page
+    best_dist = float("inf")
+
+    # loop through every page rect and check if it's within the buffer zone around the visible area, 
+    # if so enqueue it for rendering if it's not already, if it's far outside the visible area and currently rendered, unload it to save memory
+    for page_num, (x, y, w, h) in _page_rects.items():
+        page_top = y
+        page_bot = y + h
+        page_mid = y + h / 2
+
+        in_view  = page_bot + BUFFER_PX  >= vis_top and page_top - BUFFER_PX  <= vis_bot
+        far_away = page_bot + UNLOAD_PX  <  vis_top or  page_top - UNLOAD_PX  >  vis_bot
+
+        if in_view and page_num not in _image_items:
+            _enqueue(page_num, render_generation)
+        elif far_away and page_num in _image_items:
+            _unload_page(page_num)
+
+        # track the page whose centre is closest to the viewport centre
+        dist = abs(page_mid - vis_mid)
+        if dist < best_dist:
+            best_dist = dist
+            best_page = page_num
+
+    # update counter only when the page actually changes
+    if best_page != _current_page:
+        _current_page = best_page
+        _update_page_label()
+
+# when a page is far outside the visible area we call this to remove its image from the canvas and delete the reference so it can be garbage collected and free memory
+def _unload_page(page_num):
+    if page_num in _image_items:
+        _canvas.delete(_image_items[page_num])
+        del _image_items[page_num]
+    if page_num in _photo_refs:
+        del _photo_refs[page_num]
+
+# when the worker thread finish rendering a page it call this to display the image on the canvas, 
+# but only if the generation is still the same (the user might have zoomed or opened another file since then)
+def _show_page(img, page_num, gen):
+    if gen != render_generation or _canvas is None:
+        del img
+        return
+    if page_num not in _page_rects:
+        del img
+        return
+
+    x, y, w, h = _page_rects[page_num]
+
+    photo = ImageTk.PhotoImage(img)
+    del img
+
+    # keep ref so GC doesn't collect it
+    _photo_refs[page_num] = photo
+
+    # hide the page number label
+    _canvas.delete(f"lbl_{page_num}")
+
+    # draw image centred in the placeholder rect
+    item_id = _canvas.create_image(x + w // 2, y + h // 2, image=photo, anchor="center")
+    _image_items[page_num] = item_id