repdf 0.1.7__tar.gz → 0.1.9__tar.gz

{repdf-0.1.7 → repdf-0.1.9}/.github/workflows/publish.yml

@@ -8,7 +8,7 @@ on:
       tag:
         description: GitHub release tag to publish
         required: true
-        default: v0.1.7
+        default: v0.1.9
         type: string
 
 permissions:

{repdf-0.1.7 → repdf-0.1.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: repdf
-Version: 0.1.7
+Version: 0.1.9
 Summary: RePDF (Read the PDF): a desktop PDF reader with printing, search, bookmarks, OCR and page rearrangement.
 License-Expression: GPL-3.0-only
 License-File: LICENSE
@@ -99,6 +99,14 @@ repdf
 
 ### 開啟與切換檔案
 
+- 預設應用程式的 RePDF 設定頁中，`.pdf` 那一列顯示的是目前預設程式；點選該列，再選 RePDF。系統整合會安裝專用多尺寸圖示，供原始碼版與執行檔版共用。
+
+- 可使用 `repdf "文件.pdf" "另一份文件.pdf"` 一次開啟多份 PDF。RePDF 已執行時，檔案會交給既有視窗；已開啟的檔案會切換至原標籤。
+- **Windows**：按主視窗左上角程式圖示，選「系統整合 → 註冊 PDF 開啟功能」，加入 PDF 的「開啟方式」與「Open with RePDF」快顯選單。Windows 11 的獨立命令位於「顯示其他選項」。再按「開啟預設應用程式設定」，自行將 `.pdf` 指定給 RePDF。
+- 免安裝版註冊時會複製到 `%LOCALAPPDATA%\Programs\RePDF\repdf.exe`；更新後請執行新版並重新註冊。若該位置的程式正在執行，請先關閉，再從新版註冊。Python 安裝版的關聯指向目前 Python 環境，移除或搬移環境後需重新註冊。
+- 「取消註冊」移除 RePDF 的開啟功能，不會刪除 PDF 或固定位置的執行檔；更換預設程式請使用 Windows 設定。
+- **macOS**：將 `RePDF.app` 放入 Applications。在 Finder 選取 PDF，按 <kbd>⌘</kbd>+<kbd>I</kbd> 開啟「取得資訊」，於「打開檔案的應用程式」選擇 RePDF，再按「全部更改」。應用程式選單的「系統整合」也提供操作提示。
+
 - 檔案以主檔名顯示在標籤頁；將游標停在標籤上可查看完整路徑。
 - 視窗標題列顯示 `RePDF` 與版本編號。
 - 再次開啟同一路徑的檔案，會切換到既有標籤。
@@ -155,7 +163,7 @@ repdf
 ### 存檔與另存新檔
 
 - 新開啟的 PDF 預設使用 Fit 模式，自動適應閱讀區；調整比例可切換為手動縮放。
-- 「裁切檢視」優先使用有效 TrimBox；沒有 TrimBox 時辨識頁邊完整的四角向量裁切線。兩者都沒有或記號不完整時維持完整頁面，工具停用；影像中的裁切線目前不辨識。此模式只調整預覽，不修改 PDF。
+- 「裁切檢視」優先使用有效 TrimBox；沒有 TrimBox 時辨識頁邊完整的四角向量裁切線。兩者都沒有或記號不完整時維持完整頁面，工具停用；影像中的裁切線目前不辨識。啟用後頁卡依裁切範圍縮小，框外留白不再佔用檢視空間；此模式不修改 PDF。
 - 全螢幕的單頁、雙頁與封面模式也支援裁切檢視，可在懸浮工具列用裁切圖示切換；顯示組合中有可確認的裁切範圍時工具才會啟用。
 - 拖曳調整頁面順序後，標籤名稱會顯示 `*`；點「存檔」或按 <kbd>Ctrl</kbd>+<kbd>S</kbd> 儲存原 PDF。
 - 點「另存新檔」或按 <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>S</kbd>，選擇另一個檔名；儲存完成後，標籤改為新檔案。macOS 使用 <kbd>⌘</kbd> 取代 <kbd>Ctrl</kbd>。

{repdf-0.1.7 → repdf-0.1.9}/README.en.md

@@ -77,6 +77,14 @@ The controls are described below. Hover over a control to see its tooltip, inclu
 
 ### Open and switch files
 
+- On RePDF’s default app settings page, the `.pdf` row shows the current default application. Click that row, then choose RePDF. System integration installs a dedicated multi-resolution icon for both Python and packaged builds.
+
+- Run `repdf "document.pdf" "another.pdf"` to open multiple files in the existing RePDF window. Files already open select their existing tab.
+- **Windows:** click the application icon in the main window’s upper-left corner and select **System integration → Register PDF opening**. This adds RePDF to PDF **Open with** and a dedicated **Open with RePDF** command (under **Show more options** in Windows 11). Use **Open default app settings** to choose RePDF for `.pdf` yourself.
+- Registering a portable executable copies it to `%LOCALAPPDATA%\Programs\RePDF\repdf.exe`. After updating, run the new version and register again. Close any copy running at that destination before updating it. Python installations register the current Python environment; register again after moving or replacing it.
+- **Unregister** removes RePDF’s registration without deleting PDFs or the copied executable. Choose a different default application in Windows Settings.
+- **macOS:** move `RePDF.app` to Applications. Select a PDF in Finder, press <kbd>⌘</kbd>+<kbd>I</kbd>, choose RePDF under **Open with**, and click **Change All**. **System integration** in the application menu also provides these instructions.
+
 - Each tab shows the filename without its extension. Hover over a tab to see the full path.
 - The window title shows `RePDF` and its version.
 - Opening the same path again switches to its existing tab.
@@ -134,7 +142,7 @@ The controls are described below. Hover over a control to see its tooltip, inclu
 ### Save and Save As
 
 - Newly opened PDFs use Fit mode and adapt to the reading area. Changing zoom switches to manual scaling.
-- Cropped view prefers a valid TrimBox. If no TrimBox exists, it recognizes complete vector corner crop marks near page edges. Missing or incomplete marks leave the page whole and disable the tool. Raster crop marks are not detected. This changes the preview only, without modifying the PDF.
+- Cropped view prefers a valid TrimBox. If no TrimBox exists, it recognizes complete vector corner crop marks near page edges. Missing or incomplete marks leave the page whole and disable the tool. Raster crop marks are not detected. The page card shrinks to the crop area so outside margins take no viewing space; the PDF is not modified.
 - Fullscreen single-page, spread, and cover modes also support cropped view. Toggle the crop icon on the floating toolbar; it is enabled when any displayed page has a recognized crop area.
 - Reordering pages adds `*` to the tab name. Click Save or press <kbd>Ctrl</kbd>+<kbd>S</kbd> to save the original PDF.
 - Click Save As or press <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>S</kbd> to choose another filename. The tab switches to the saved file. On macOS use <kbd>⌘</kbd> instead of <kbd>Ctrl</kbd>.

{repdf-0.1.7 → repdf-0.1.9}/README.md

@@ -78,6 +78,14 @@ repdf
 
 ### 開啟與切換檔案
 
+- 預設應用程式的 RePDF 設定頁中，`.pdf` 那一列顯示的是目前預設程式；點選該列，再選 RePDF。系統整合會安裝專用多尺寸圖示，供原始碼版與執行檔版共用。
+
+- 可使用 `repdf "文件.pdf" "另一份文件.pdf"` 一次開啟多份 PDF。RePDF 已執行時，檔案會交給既有視窗；已開啟的檔案會切換至原標籤。
+- **Windows**：按主視窗左上角程式圖示，選「系統整合 → 註冊 PDF 開啟功能」，加入 PDF 的「開啟方式」與「Open with RePDF」快顯選單。Windows 11 的獨立命令位於「顯示其他選項」。再按「開啟預設應用程式設定」，自行將 `.pdf` 指定給 RePDF。
+- 免安裝版註冊時會複製到 `%LOCALAPPDATA%\Programs\RePDF\repdf.exe`；更新後請執行新版並重新註冊。若該位置的程式正在執行，請先關閉，再從新版註冊。Python 安裝版的關聯指向目前 Python 環境，移除或搬移環境後需重新註冊。
+- 「取消註冊」移除 RePDF 的開啟功能，不會刪除 PDF 或固定位置的執行檔；更換預設程式請使用 Windows 設定。
+- **macOS**：將 `RePDF.app` 放入 Applications。在 Finder 選取 PDF，按 <kbd>⌘</kbd>+<kbd>I</kbd> 開啟「取得資訊」，於「打開檔案的應用程式」選擇 RePDF，再按「全部更改」。應用程式選單的「系統整合」也提供操作提示。
+
 - 檔案以主檔名顯示在標籤頁；將游標停在標籤上可查看完整路徑。
 - 視窗標題列顯示 `RePDF` 與版本編號。
 - 再次開啟同一路徑的檔案，會切換到既有標籤。
@@ -134,7 +142,7 @@ repdf
 ### 存檔與另存新檔
 
 - 新開啟的 PDF 預設使用 Fit 模式，自動適應閱讀區；調整比例可切換為手動縮放。
-- 「裁切檢視」優先使用有效 TrimBox；沒有 TrimBox 時辨識頁邊完整的四角向量裁切線。兩者都沒有或記號不完整時維持完整頁面，工具停用；影像中的裁切線目前不辨識。此模式只調整預覽，不修改 PDF。
+- 「裁切檢視」優先使用有效 TrimBox；沒有 TrimBox 時辨識頁邊完整的四角向量裁切線。兩者都沒有或記號不完整時維持完整頁面，工具停用；影像中的裁切線目前不辨識。啟用後頁卡依裁切範圍縮小，框外留白不再佔用檢視空間；此模式不修改 PDF。
 - 全螢幕的單頁、雙頁與封面模式也支援裁切檢視，可在懸浮工具列用裁切圖示切換；顯示組合中有可確認的裁切範圍時工具才會啟用。
 - 拖曳調整頁面順序後，標籤名稱會顯示 `*`；點「存檔」或按 <kbd>Ctrl</kbd>+<kbd>S</kbd> 儲存原 PDF。
 - 點「另存新檔」或按 <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>S</kbd>，選擇另一個檔名；儲存完成後，標籤改為新檔案。macOS 使用 <kbd>⌘</kbd> 取代 <kbd>Ctrl</kbd>。

{repdf-0.1.7 → repdf-0.1.9}/docs/IMPLEMENTATION.en.md

@@ -6,6 +6,16 @@ This guide describes RePDF's current architecture, data flow, design decisions,
 
 ## 1. Project overview
 
+### Desktop file opening and associations
+
+- Registration converts `assets/repdf.png` with the shared optical sizing into multi-resolution `%LOCALAPPDATA%/Programs/RePDF/repdf.ico`, used by ProgID DefaultIcon, ApplicationIcon, Capabilities ApplicationIcon, and the context command. Icons do not depend on the Python executable or PyInstaller extraction directory.
+
+- `desktop_open.py` parses multiple file paths. `DesktopApplication` handles macOS `QFileOpenEvent`, queuing requests until the window is ready or an export completes before calling `load_pdfs()`.
+- `DesktopInstance` uses a per-user `QLocalServer` / `QLocalSocket` name and newline-terminated UTF-8 JSON containing absolute paths. A `QLockFile` guards startup and stale socket removal. Subsequent processes forward requests without starting a render backend. Sockets restrict access to the current user; messages are limited to 1 MiB.
+- `desktop_integration.py` writes HKCU RePDF ProgID, OpenWithProgids, Capabilities, RegisteredApplications, and PDF-specific shell entries only on explicit registration. It never writes UserChoice or forces a default. Portable builds copy to `%LOCALAPPDATA%/Programs/RePDF/repdf.exe`; Python builds register the current environment’s `pythonw -m repdf`.
+- Entry points use the Windows system menu and macOS PreferencesRole. `packaging/repdf.spec` declares `com.adobe.pdf`, Editor, and Alternate; Qt file events replace argv emulation.
+- Unregister removes only RePDF-owned keys and named values, leaving shared `.pdf` keys, other apps, and executables intact. A Windows 11 first-level IExplorerCommand extension is not included.
+
 RePDF is a Python desktop application for Windows and macOS. Its main features are:
 
 1. Open multiple PDFs in checkable, reorderable, closable tabs.
@@ -254,7 +264,7 @@ During export, users may switch tabs, read, and zoom, but cannot open/close file
 
 The toolbar's `language_action` cycles `system → zh → en`; `theme_action` cycles `system → light → dark`. `QSettings("repdf", "repdf")` stores `ui/language` and `ui/theme`, defaulting to `system` and falling back to it for invalid values. On first startup, valid language/theme preferences from `QSettings("PDFPick", "PDFPick")` populate unset new keys, without overwriting existing repdf preferences or deleting old settings.
 
-`preferences.LanguageController` prefers the first display language in `QLocale.system().uiLanguages()`, falling back to locale language only if none is available. Chinese selects Traditional Chinese; other languages select English. `LocaleChange` reevaluates language only in system mode. `strings.py` centralizes translations and `tr()` for GUI/core/backend errors. `localize_text()` updates existing text while preserving formatting arguments. Switching language updates text/tooltips without rebuilding documents or rerendering pages.
+On macOS, `preferences.LanguageController` reads native display-language preferences through CoreFoundation's `CFLocaleCopyPreferredLanguages()` so Qt's process locale cannot incorrectly force English. The app's `Info.plist` also declares English and Chinese support. Other platforms, or unavailable native preferences, use `QLocale.system().uiLanguages()`, falling back to locale language only if none is available. The first display language determines the result: Chinese selects Traditional Chinese; other languages select English. `LocaleChange` reevaluates language only in system mode. `strings.py` centralizes translations and `tr()` for GUI/core/backend errors. `localize_text()` updates existing text while preserving formatting arguments. Switching language updates text/tooltips without rebuilding documents or rerendering pages.
 
 File dialogs use `DontUseNativeDialog`, Qt's `qtbase_zh_TW.qm`, and standard-button translations. Packaging locates Qt translations via `QLibraryInfo.TranslationsPath` and collects qm files into `repdf/assets`. Source execution also reads Qt's translations directory. Missing translations fall back to source text. `packaging_smoke.py` checks qm availability and English translation behavior. GUI tests isolate user preferences in separate settings.
 
@@ -377,7 +387,7 @@ Packaged smoke tests must stop render backends holding cached PDFs before removi
 - `PagePreviewLabel` stores search rectangles independently of selection highlights using normalized coordinates. `DocumentView.jump_to_search_result()` locates stable page indices and preserves zoom/Fit. Before an image is available, it scrolls using placeholder geometry to trigger on-demand rendering. Actual dimensions from the target and neighboring pages refine the still-visible match position; neighboring updates do not pull users back after they scroll away.
 - The search pane starts at width 320px with resizable width and list divider. Below width 640px it shares a single pane with the PDF; below height 360px scope/flags move into a menu, preserving the 320 × 240 minimum window.
 - The main window checks loaded PDF modification time and size every two seconds, prompting once per changed version. Reload loads a replacement asynchronously and swaps tabs only after success, restoring tab position, page, and zoom; failures keep the old tab. Unsaved edits can be saved as a copy before opening the changed source.
-- TrimBox view uses PDFium's explicit TrimBox without CropBox fallback, intersected with the visible page; identical or invalid boxes disable the tool. The preview backend supplies a normalized box per page. Fit scales to that area and scrolls to its center without modifying source PDFs or exports.
+- TrimBox view uses PDFium's explicit TrimBox without CropBox fallback, intersected with the visible page; identical or invalid boxes disable the tool. The preview backend supplies a normalized box per page. In normal view `PageCard.preview_clip` shrinks the card to that box while its full-page `preview` moves negatively inside the clip, preserving original coordinates for text selection, links, and annotations. Both normal and virtual grids use visible dimensions; Fit scales to the crop area. Source PDFs and exports are unchanged.
 - Without TrimBox, `trim_view.crop_mark_box()` examines open, stroked, unfilled vector paths with object and parent Form transforms. It requires paired horizontal/vertical short marks at all four page-edge corners, choosing the inner rectangle for double marks. Path and candidate budgets bound work; incomplete marks, ordinary rectangles, and raster images leave the page whole.
 - Opening search from toolbar overflow reactivates the main window on the next event-loop turn before focusing input, avoiding a lingering active menu window on macOS.
 - Passwords travel only through local communication. No decrypted PDF, disk text index, or password log is created. Search history and results last only for the current session.

{repdf-0.1.7 → repdf-0.1.9}/docs/IMPLEMENTATION.md

@@ -6,6 +6,16 @@
 
 ## 1. 專案概觀
 
+### 系統開檔與檔案關聯
+
+- 註冊時將 `assets/repdf.png` 依共用圖示比例產生多尺寸 `%LOCALAPPDATA%/Programs/RePDF/repdf.ico`，提供 ProgID DefaultIcon、ApplicationIcon、Capabilities ApplicationIcon 與快顯命令使用。圖示不依賴 Python 執行檔或 PyInstaller 暫存路徑。
+
+- `desktop_open.py` 解析多檔路徑；`DesktopApplication` 接收 macOS `QFileOpenEvent`。主視窗尚未就緒或正在輸出時暫存開檔要求，再交由 `load_pdfs()` 處理。
+- `DesktopInstance` 使用每位使用者固定名稱的 `QLocalServer` / `QLocalSocket`，以 UTF-8 JSON 加換行傳送絕對路徑。`QLockFile` 保護啟動與殘留 socket 清理；後續程序僅送出要求，不啟動 PDF 後端。socket 限目前使用者存取，訊息上限 1 MiB。
+- `desktop_integration.py` 僅在使用者按下註冊時寫入 HKCU 的 RePDF ProgID、OpenWithProgids、Capabilities、RegisteredApplications 與 PDF 專用 shell 命令。不寫入 UserChoice 或強制覆蓋預設程式。免安裝版複製到 `%LOCALAPPDATA%/Programs/RePDF/repdf.exe`，Python 版指向目前環境的 `pythonw -m repdf`。
+- 系統整合入口位於 Windows 系統功能表及 macOS PreferencesRole。macOS 封裝在 `packaging/repdf.spec` 宣告 `com.adobe.pdf`、Editor 與 Alternate；透過 Qt 開檔事件處理，不使用 argv emulation。
+- 取消註冊只刪除 RePDF 專屬鍵與命名值，不刪除 `.pdf` 共用鍵、其他程式的關聯或執行檔。Windows 11 第一層 IExplorerCommand 擴充不在目前實作範圍。
+
 RePDF 是支援 Windows 與 macOS 的 Python 桌面程式，主要功能包括：
 
 1. 以可勾選、拖曳排序及關閉的標籤頁開啟多個 PDF。
@@ -259,7 +269,7 @@ Fit 使用最近點擊且仍可見的頁面，或距預覽區中央最近的頁
 
 工具列提供 `language_action`、`theme_action` 三態按鈕，分別循環 `system → zh → en` 與 `system → light → dark`。`QSettings("repdf", "repdf")` 的 `ui/language`、`ui/theme` 保存選擇，預設均為 `system`，無效值回退為系統模式。首次啟動會將舊版 `QSettings("PDFPick", "PDFPick")` 的有效語言與配色選擇複製到尚未設定的新欄位，不覆蓋 repdf 已有設定，也不刪除舊設定。
 
-`preferences.LanguageController` 優先使用 `QLocale.system().uiLanguages()` 的第一個顯示語言，沒有顯示語言時才回退至 locale 語言；中文使用繁體中文，其餘使用英文。主視窗收到 `LocaleChange` 時僅在系統模式重新判斷。`strings.py` 集中翻譯表與 `tr()`，由 GUI、核心和背景錯誤共用；`localize_text()` 更新既有介面文字並保留格式化參數。切換時更新文字與提示，不重建文件或重新渲染頁面。
+`preferences.LanguageController` 在 macOS 優先透過 CoreFoundation 的 `CFLocaleCopyPreferredLanguages()` 讀取原生顯示語言，避免 Qt 的程序 locale 將系統語言誤判成英文；App 的 `Info.plist` 同時宣告英文與中文支援。其他平台或原生清單無法取得時，使用 `QLocale.system().uiLanguages()`，沒有顯示語言時才回退至 locale 語言。以第一個顯示語言為準，中文使用繁體中文，其餘使用英文。主視窗收到 `LocaleChange` 時僅在系統模式重新判斷。`strings.py` 集中翻譯表與 `tr()`，由 GUI、核心和背景錯誤共用；`localize_text()` 更新既有介面文字並保留格式化參數。切換時更新文字與提示，不重建文件或重新渲染頁面。
 
 檔案對話框使用 `DontUseNativeDialog`，搭配 Qt `qtbase_zh_TW.qm` 與標準按鈕翻譯。封裝設定透過 `QLibraryInfo.TranslationsPath` 取得各平台的 Qt 翻譯資源路徑，將 qm 放入 `repdf/assets`；來源執行同樣讀取 Qt 的 translations 路徑。未翻譯文字回退原文。`packaging_smoke.py` 驗證 qm 存在與英文翻譯，GUI 測試以獨立設定檔隔離使用者偏好。
 
@@ -393,7 +403,7 @@ Fit 使用最近點擊且仍可見的頁面，或距預覽區中央最近的頁
 - `PagePreviewLabel` 的搜尋矩形獨立於文字選取高亮，以正規化座標在重繪後保留；`DocumentView.jump_to_search_result()` 依穩定頁面索引定位並保留目前縮放／Fit 模式。尚無預覽圖時先依佔位幾何捲至命中位置，讓按需渲染啟動；目標頁及鄰頁實際尺寸到達後校正仍可見的命中位置，使用者已捲離時不因鄰頁更新拉回。
 - 搜尋窗格預設寬 320px，可調整寬度及上下分隔。寬度小於 640px 時使用單一窗格；高度小於 360px 時將範圍與旗標收進選單，維持最小視窗 320 × 240。
 - 主視窗每兩秒檢查已載入 PDF 的修改時間與大小，單次變更只提示一次。重新載入先非同步開啟新文件，成功後才換掉舊標籤並還原頁碼、縮放與標籤位置；失敗則保留舊標籤。未儲存時可另存新檔後開啟更新的來源檔。
-- TrimBox 檢視以 PDFium 的實際 TrimBox（禁止回退 CropBox）與可見頁範圍交集判斷；若與原頁相同或尺寸無效則工具停用。預覽後端逐頁傳回正規化範圍，Fit 模式依裁切範圍計算縮放並捲至中心；來源 PDF 與輸出流程不改寫。
+- TrimBox 檢視以 PDFium 的實際 TrimBox（禁止回退 CropBox）與可見頁範圍交集判斷；若與原頁相同或尺寸無效則工具停用。預覽後端逐頁傳回正規化範圍；一般檢視由 `PageCard.preview_clip` 依範圍縮小頁卡，完整頁面的 `preview` 在容器內負位移，維持選字、連結與註解的原始座標。一般與虛擬網格均以可見尺寸排版，Fit 依裁切範圍計算縮放；來源 PDF 與輸出流程不改寫。
 - 缺少 TrimBox 時，`trim_view.crop_mark_box()` 讀取有描邊、無填色且不閉合的向量路徑，套用物件與父 Form 矩陣，只接受頁邊四角各有橫、直短線且可互相對應的框。雙重記號取內側範圍，設有路徑與候選數量上限；不完整記號、一般矩形及點陣影像維持原頁面。
 - 從工具列溢位選單開啟搜尋時，在下一輪事件處理恢復主視窗啟用狀態，再將焦點移至搜尋欄，避免 macOS 的選單視窗暫留啟用狀態。
 - 密碼只經既有本機通訊傳遞，不建立解密 PDF、磁碟文字索引或含密碼的記錄。搜尋歷史與結果只保留於目前工作階段。

{repdf-0.1.7 → repdf-0.1.9}/docs/UI_DESIGN.en.md

@@ -151,7 +151,7 @@ Text buttons, whole checkboxes, and the tab bar do not have a single fixed heigh
 | Card padding | Left 11, top 9, right 11, bottom 11 |
 | Header/preview spacing | 8 |
 | Card width | Preview image width + 24 |
-| Card header | Page checkbox on the left, drag handle on the right |
+| Card header | Page and odd/even checkboxes on the left, drag handle on the right; hover-color background, 1px bottom divider, 8px gap before PDF content |
 | Reorder animation | 180 ms, `OutCubic` |
 | Insertion indicator | 2px dashed accent border, radius 8 |
 | Text highlight | Accent color, alpha 90/255, approximately 35% opacity |

{repdf-0.1.7 → repdf-0.1.9}/docs/UI_DESIGN.md

@@ -309,7 +309,7 @@ reorderAnimation.durationMs = 180
 
 - 有快捷鍵的按鈕在 tooltip 列出實際綁定，依平台顯示原生按鍵名稱；切換語系同步更新。
 
-- 頁面輸出群組前後均加分隔線。奇偶頁選取工具位於各頁頁首核取方塊右側，使用標準核取方塊與「單數頁／雙數頁」文字，顯示未選、部分或全選。一般與全螢幕同步，只操作該文件原始頁碼。
+- 頁面輸出群組前後均加分隔線。奇偶頁選取工具位於各頁頁首核取方塊右側，使用標準核取方塊與「單數頁／雙數頁」文字，顯示未選、部分或全選。一般與全螢幕同步，只操作該文件原始頁碼。頁首工具列使用 hover 底色與 1 px 下緣分隔線，與白色 PDF 內容區明確區分；內容與標頭間保留 8 px 間距。
 
 - 搜尋結果維持上下分割：上方「檔案」以「檔名／筆數」兩欄顯示，筆數為個別命中數；下方「命中項目」以「頁碼／段落」分欄，點擊任一欄皆可跳頁。數字靠右，段落單行省略且保留完整提示。
 

{repdf-0.1.7 → repdf-0.1.9}/packaging/repdf.spec

@@ -48,6 +48,14 @@ if sys.platform == "darwin":
                  info_plist={"CFBundleShortVersionString": version,
                              "CFBundleName": "RePDF",
                              "CFBundleDisplayName": "RePDF",
+                             "CFBundleDevelopmentRegion": "en",
+                             "CFBundleLocalizations": ["en", "zh-Hant", "zh-Hans"],
+                             "CFBundleDocumentTypes": [{
+                                 "CFBundleTypeName": "PDF document",
+                                 "CFBundleTypeRole": "Editor",
+                                 "LSHandlerRank": "Alternate",
+                                 "LSItemContentTypes": ["com.adobe.pdf"],
+                             }],
                              "NSHighResolutionCapable": True})
 else:
     exe = EXE(pyz, a.scripts, a.binaries, a.datas, name="repdf",

{repdf-0.1.7 → repdf-0.1.9}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "repdf"
-version = "0.1.7"
+version = "0.1.9"
 description = "RePDF (Read the PDF): a desktop PDF reader with printing, search, bookmarks, OCR and page rearrangement."
 readme = "README.md"
 requires-python = ">=3.11"

{repdf-0.1.7 → repdf-0.1.9}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "repdf"
-version = "0.1.7"
+version = "0.1.9"
 description = "RePDF (Read the PDF): a desktop PDF reader with printing, search, bookmarks, OCR and page rearrangement."
 readme = "README.md"
 requires-python = ">=3.11"

{repdf-0.1.7 → repdf-0.1.9}/src/repdf/app.py

@@ -209,7 +209,7 @@ class DocumentView(QWidget):
         card.preview.set_links(self.page_links.get(page_index, []))
         card.preview.set_annotations(self.page_annotations.get(page_index, []))
         card.preview.link_activated.connect(lambda destination: self.owner.navigation.activate(self, destination))
-        self.pages.chrome = max(1, card.sizeHint().height() - card.preview.height())
+        self.pages.chrome = max(1, card.sizeHint().height() - card.preview_clip.height())
         return card
 
     def _target_preview_width(self) -> int:
@@ -321,7 +321,7 @@ class DocumentView(QWidget):
             width *= trim[2] - trim[0]
             height *= trim[3] - trim[1]
         margins = self.grid.contentsMargins()
-        chrome = max(0, card.sizeHint().height() - card.preview.height())
+        chrome = max(0, card.sizeHint().height() - card.preview_clip.height())
         available_width = max(1, self.scroll_area.viewport().width() - margins.left() - margins.right() - 26)
         # Grid margins surround the entire document, not each fitted page.
         # Fit the card to the viewport and scroll it into alignment separately.
@@ -344,9 +344,7 @@ class DocumentView(QWidget):
         trim = self.trim_boxes.get(self.fit_page_index) if self.trim_view else None
         viewport = self.scroll_area.viewport()
         if trim is not None:
-            label = self.pages.ensure_page(self.fit_page_index).preview
-            center = label.mapTo(self.grid_host, QPoint(round((trim[0] + trim[2]) * label.width() / 2),
-                                                       round((trim[1] + trim[3]) * label.height() / 2)))
+            center = card.center()
             self.scroll_area.verticalScrollBar().setValue(center.y() - viewport.height() // 2)
             self.scroll_area.horizontalScrollBar().setValue(center.x() - viewport.width() // 2)
         else:
@@ -493,11 +491,21 @@ class MainWindow(QMainWindow):
         self.about_action.setMenuRole(QAction.MenuRole.AboutRole)
         self.about_action.triggered.connect(self.show_about)
         self.addAction(self.about_action)
+        self.integration_action = QAction(tr('系統整合'), self)
+        self.integration_action.setMenuRole(QAction.MenuRole.PreferencesRole)
+        self.integration_action.triggered.connect(self.show_integration)
+        self.addAction(self.integration_action)
         if sys.platform != 'win32':
             self.menuBar().setNativeMenuBar(True)
-            self.menuBar().addMenu(tr('說明')).addAction(self.about_action)
+            help_menu = self.menuBar().addMenu(tr('說明'))
+            help_menu.addAction(self.about_action)
+            help_menu.addAction(self.integration_action)
         self._windows_system_menu = WindowsSystemMenu(self)
 
+    def show_integration(self):
+        from repdf.desktop_integration import DesktopIntegrationDialog
+        DesktopIntegrationDialog(self).exec()
+
     def show_about(self):
         if self._about_dialog is None or not isValid(self._about_dialog):
             self._about_dialog = AboutDialog(self._fullscreen_preview or self)
@@ -1099,6 +1107,7 @@ class MainWindow(QMainWindow):
         if self._about_dialog is not None and isValid(self._about_dialog):
             self._about_dialog.retranslate()
         self._windows_system_menu.refresh()
+        self.integration_action.setText(tr('系統整合'))
         if self._fullscreen_preview is not None:
             self._fullscreen_preview.floating_tools.refresh_icons()
 
@@ -1135,7 +1144,7 @@ class MainWindow(QMainWindow):
             return
         doc.trim_view = checked
         for card in doc.page_cards:
-            card.preview.set_trim_mask(doc.trim_boxes.get(card.page_index) if checked else None)
+            card.set_trim_rect(doc.trim_boxes.get(card.page_index) if checked else None)
         doc.fit_page()
         self._sync_controls()
         if self._fullscreen_preview is not None:
@@ -1983,9 +1992,26 @@ def configure_application(app: QApplication) -> None:
 
 
 def main() -> int:
-    render_backend = start_render_backend()
-    app = QApplication(sys.argv)
+    from repdf.desktop_open import DesktopApplication, DesktopInstance, file_arguments
+    paths = file_arguments(sys.argv[1:])
+    app = DesktopApplication(sys.argv)
     configure_application(app)
+    instance = DesktopInstance(app)
+    try:
+        if not instance.start(paths):
+            return 0
+    except RuntimeError as error:
+        message = QMessageBox()
+        message.setOption(QMessageBox.Option.DontUseNativeDialog, True)
+        message.setWindowTitle('RePDF')
+        message.setText(str(error))
+        message.exec()
+        return 1
+    render_backend = start_render_backend()
     window = MainWindow(render_backend)
     window.show()
-    return app.exec()
+    app.attach_window(window)
+    try:
+        return app.exec()
+    finally:
+        instance.close()

repdf-0.1.9/src/repdf/desktop_integration.py

@@ -0,0 +1,160 @@
+"""Opt-in Windows registration. Never writes the user's default association."""
+from pathlib import Path
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+from importlib.resources import files
+
+from PySide6.QtCore import QUrl
+from PySide6.QtGui import QDesktopServices
+from PySide6.QtWidgets import QDialog, QVBoxLayout, QLabel, QPushButton
+
+from repdf.strings import tr
+
+PROG_ID = 'RePDF.PDF'
+APP_KEY = r'Software\RePDF\Capabilities'
+CONTEXT_KEY = r'Software\Classes\SystemFileAssociations\.pdf\shell\RePDF'
+
+
+def registration_entries(command, icon):
+    """Declarative HKCU values, also testable on non-Windows platforms."""
+    return [
+        (rf'Software\Classes\{PROG_ID}', '', 'PDF — Read the PDF'),
+        (rf'Software\Classes\{PROG_ID}\DefaultIcon', '', icon),
+        (rf'Software\Classes\{PROG_ID}\Application', 'ApplicationName', 'RePDF'),
+        (rf'Software\Classes\{PROG_ID}\Application', 'ApplicationDescription', 'Read the PDF'),
+        (rf'Software\Classes\{PROG_ID}\Application', 'ApplicationIcon', icon),
+        (rf'Software\Classes\{PROG_ID}\shell\open\command', '', command),
+        (r'Software\Classes\.pdf\OpenWithProgids', PROG_ID, ''),
+        (APP_KEY, 'ApplicationName', 'RePDF'),
+        (APP_KEY, 'ApplicationDescription', 'Read the PDF'),
+        (APP_KEY, 'ApplicationIcon', icon),
+        (APP_KEY + r'\FileAssociations', '.pdf', PROG_ID),
+        (r'Software\RegisteredApplications', 'RePDF', APP_KEY),
+        (CONTEXT_KEY, '', 'Open with RePDF'),
+        (CONTEXT_KEY, 'Icon', icon),
+        (CONTEXT_KEY + r'\command', '', command),
+    ]
+
+
+def launch_command():
+    if getattr(sys, 'frozen', False):
+        # Keep the registered executable path stable across versioned downloads.
+        destination = Path(os.environ['LOCALAPPDATA']) / 'Programs/RePDF/repdf.exe'
+        destination.parent.mkdir(parents=True, exist_ok=True)
+        source = Path(sys.executable).resolve()
+        if source != destination.resolve():
+            with tempfile.NamedTemporaryFile(dir=destination.parent, suffix='.new', delete=False) as stream:
+                staging = Path(stream.name)
+            try:
+                shutil.copy2(source, staging)
+                os.replace(staging, destination)
+            finally:
+                staging.unlink(missing_ok=True)
+        executable = str(destination)
+        return subprocess.list2cmdline([executable]) + ' "%1"', '"' + executable + '",0'
+    executable = Path(sys.executable)
+    windowed = executable.with_name('pythonw.exe')
+    if windowed.is_file():
+        executable = windowed
+    return subprocess.list2cmdline([str(executable), '-m', 'repdf']) + ' "%1"', '"' + str(executable) + '",0'
+
+
+def notify_shell():
+    import ctypes
+    ctypes.windll.shell32.SHChangeNotify(0x08000000, 0, None, None)
+
+
+def install_application_icon(directory=None):
+    """Keep shell icons independent of Python and the one-file extraction path."""
+    from repdf.icon_layout import fitted_icon
+    directory = Path(directory) if directory else Path(os.environ['LOCALAPPDATA']) / 'Programs/RePDF'
+    directory.mkdir(parents=True, exist_ok=True)
+    icon = directory / 'repdf.ico'
+    image = fitted_icon(files('repdf').joinpath('assets', 'repdf.png'))
+    with tempfile.NamedTemporaryFile(dir=directory, suffix='.ico', delete=False) as stream:
+        staging = Path(stream.name)
+    try:
+        image.save(staging, format='ICO', sizes=[(n, n) for n in (16, 20, 24, 32, 40, 48, 64, 128, 256)])
+        os.replace(staging, icon)
+    finally:
+        staging.unlink(missing_ok=True)
+    return f'"{icon}",0'
+
+
+def register_windows():
+    import winreg
+    command, _executable_icon = launch_command()
+    icon = install_application_icon()
+    for path, name, value in registration_entries(command, icon):
+        with winreg.CreateKey(winreg.HKEY_CURRENT_USER, path) as key:
+            winreg.SetValueEx(key, name, 0, winreg.REG_SZ, value)
+    notify_shell()
+
+
+def unregister_windows():
+    import winreg
+    # Delete only our named values and exclusively owned leaf keys.
+    for path, name in ((r'Software\Classes\.pdf\OpenWithProgids', PROG_ID),
+                       (r'Software\RegisteredApplications', 'RePDF')):
+        try:
+            with winreg.OpenKey(winreg.HKEY_CURRENT_USER, path, 0, winreg.KEY_SET_VALUE) as key:
+                winreg.DeleteValue(key, name)
+        except FileNotFoundError:
+            pass
+    paths = [CONTEXT_KEY + r'\command', CONTEXT_KEY,
+             rf'Software\Classes\{PROG_ID}\shell\open\command',
+             rf'Software\Classes\{PROG_ID}\shell\open',
+             rf'Software\Classes\{PROG_ID}\shell',
+             rf'Software\Classes\{PROG_ID}\Application',
+             rf'Software\Classes\{PROG_ID}\DefaultIcon', rf'Software\Classes\{PROG_ID}',
+             APP_KEY + r'\FileAssociations', APP_KEY]
+    for path in paths:
+        try:
+            winreg.DeleteKey(winreg.HKEY_CURRENT_USER, path)
+        except FileNotFoundError:
+            pass
+    notify_shell()
+
+
+class DesktopIntegrationDialog(QDialog):
+    def __init__(self, parent=None):
+        super().__init__(parent)
+        self.setWindowTitle(tr('系統整合'))
+        self.setMinimumWidth(440)
+        layout = QVBoxLayout(self)
+        layout.setContentsMargins(24, 20, 24, 20)
+        layout.setSpacing(12)
+        self.message = QLabel()
+        self.message.setWordWrap(True)
+        layout.addWidget(self.message)
+        if sys.platform == 'win32':
+            self.message.setText(tr('將 RePDF 加入 PDF 的「開啟方式」與快顯選單。預設應用程式仍由您在 Windows 設定中選擇。免安裝版會複製至目前使用者的 Programs/RePDF 固定位置；更新後請再次註冊。'))
+            for label, callback in [('註冊 PDF 開啟功能', register_windows),
+                                    ('取消註冊', unregister_windows)]:
+                button = QPushButton(tr(label))
+                button.setMinimumHeight(34)
+                button.clicked.connect(lambda _checked=False, fn=callback: self.run_action(fn))
+                layout.addWidget(button)
+            settings = QPushButton(tr('開啟預設應用程式設定'))
+            settings.setMinimumHeight(34)
+            settings.clicked.connect(lambda: QDesktopServices.openUrl(QUrl('ms-settings:defaultapps?registeredAppUser=RePDF')))
+            layout.addWidget(settings)
+            hint = QLabel(tr('設定頁會顯示目前的 PDF 預設程式；點選 .pdf 那一列，再選 RePDF。'))
+            hint.setWordWrap(True)
+            layout.addWidget(hint)
+        else:
+            self.message.setText(tr('將 RePDF.app 放入「應用程式」。在 Finder 選取 PDF，開啟「取得資訊」，於「打開檔案的應用程式」選擇 RePDF，再按「全部更改」。'))
+        close = QPushButton(tr('關閉'))
+        close.setMinimumHeight(34)
+        close.clicked.connect(self.accept)
+        layout.addWidget(close)
+
+    def run_action(self, callback):
+        try:
+            callback()
+            self.message.setText(tr('設定已完成。取消註冊不會刪除程式或 PDF；如需更換預設程式，請使用系統設定。'))
+        except OSError as error:
+            self.message.setText(tr('無法完成系統整合設定：') + str(error))

repdf-0.1.9/src/repdf/desktop_open.py

@@ -0,0 +1,133 @@
+"""Desktop file opening and per-user single-instance delivery."""
+import argparse
+import hashlib
+import json
+from pathlib import Path
+
+from PySide6.QtCore import QElapsedTimer, QEvent, QLockFile, QObject, QStandardPaths, QThread, QTimer
+from PySide6.QtNetwork import QLocalServer, QLocalSocket
+from PySide6.QtWidgets import QApplication
+
+
+def file_arguments(arguments):
+    parser = argparse.ArgumentParser(prog='repdf', description='Read the PDF')
+    parser.add_argument('files', nargs='*', type=lambda value: str(Path(value).resolve()))
+    return parser.parse_args(arguments).files
+
+
+class DesktopApplication(QApplication):
+    def __init__(self, arguments):
+        super().__init__(arguments)
+        self.window = None
+        self.pending_files = []
+        self.delivery_timer = QTimer(self)
+        self.delivery_timer.setSingleShot(True)
+        self.delivery_timer.timeout.connect(self.deliver_pending)
+
+    def event(self, event):
+        if event.type() == QEvent.Type.FileOpen:
+            path = event.file() or event.url().toLocalFile()
+            if path:
+                self.open_files([path])
+                return True
+        return super().event(event)
+
+    def open_files(self, paths):
+        if getattr(self, 'window', None) is None or getattr(self.window, '_export_running', False):
+            self.pending_files.extend(paths)
+            if self.window is not None:
+                self.delivery_timer.start(150)
+            return
+        if paths:
+            self.window.load_pdfs([Path(path) for path in paths])
+        if self.window.isMinimized():
+            self.window.showNormal()
+        self.window.show()
+        self.window.raise_()
+        self.window.activateWindow()
+
+    def deliver_pending(self):
+        paths, self.pending_files = self.pending_files, []
+        self.open_files(paths)
+
+    def attach_window(self, window):
+        self.window = window
+        paths, self.pending_files = self.pending_files, []
+        QTimer.singleShot(0, lambda: self.open_files(paths))
+
+
+class DesktopInstance(QObject):
+    """A lock guards stale socket removal; only the lock owner may listen."""
+    def __init__(self, app, name=None):
+        super().__init__(app)
+        identity = hashlib.sha256(str(Path.home()).encode()).hexdigest()[:20]
+        self.name = name or f'io.github.codemee.repdf-{identity}'
+        directory = Path(QStandardPaths.writableLocation(QStandardPaths.StandardLocation.TempLocation))
+        self.lock = QLockFile(str(directory / (self.name + '.lock')))
+        self.server = QLocalServer(self)
+        self.server.setSocketOptions(QLocalServer.SocketOption.UserAccessOption)
+        self.server.newConnection.connect(self.accept_connections)
+        self.app = app
+        self.buffers = {}
+
+    def start(self, paths):
+        if not self.lock.tryLock(0):
+            socket = QLocalSocket()
+            timer = QElapsedTimer()
+            timer.start()
+            while timer.elapsed() < 5000:
+                socket.connectToServer(self.name)
+                if socket.waitForConnected(250):
+                    break
+                socket.abort()
+                QThread.msleep(50)
+            if socket.state() != QLocalSocket.LocalSocketState.ConnectedState:
+                raise RuntimeError('Cannot contact the running RePDF window. Please retry.')
+            socket.write(json.dumps(paths, ensure_ascii=False).encode('utf-8') + b'\n')
+            if socket.bytesToWrite() and not socket.waitForBytesWritten(5000):
+                raise RuntimeError('Could not deliver files to RePDF. Please retry.')
+            socket.disconnectFromServer()
+            return False
+        QLocalServer.removeServer(self.name)
+        if not self.server.listen(self.name):
+            self.lock.unlock()
+            raise RuntimeError(self.server.errorString())
+        self.app.open_files(paths)
+        return True
+
+    def accept_connections(self):
+        while self.server.hasPendingConnections():
+            socket = self.server.nextPendingConnection()
+            self.buffers[socket] = bytearray()
+            socket.readyRead.connect(lambda s=socket: self.read_request(s))
+            socket.disconnected.connect(lambda s=socket: self.drop_connection(s))
+            self.read_request(socket)
+
+    def read_request(self, socket):
+        buffer = self.buffers.get(socket)
+        if buffer is None:
+            return
+        buffer.extend(bytes(socket.readAll()))
+        if len(buffer) > 1024 * 1024:
+            socket.abort()
+            return
+        if b'\n' not in buffer:
+            return
+        try:
+            paths = json.loads(bytes(buffer).split(b'\n', 1)[0])
+            if isinstance(paths, list) and all(isinstance(p, str) and Path(p).is_absolute() for p in paths):
+                self.app.open_files(paths)
+        except (ValueError, OSError):
+            pass
+        self.buffers.pop(socket, None)
+        # The sender closes after its write completes. Closing the Windows pipe
+        # here can race the sender's completion notification.
+
+    def drop_connection(self, socket):
+        self.read_request(socket)
+        self.buffers.pop(socket, None)
+        socket.deleteLater()
+
+    def close(self):
+        self.server.close()
+        self.lock.unlock()