.\" Copyright (c) 2025 Tobias Stoeckmann <tobias@stoeckmann.org>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.Dd February 4, 2025
.Dt XWALLPAPER 1
.Os xwallpaper 0.7.6
.Sh "نام (NAME)"
.Nm xwallpaper
.Nd ابزاری برای تنظیم تصویر پس‌زمینه در X
.Sh "خلاصه دستور (SYNOPSIS)"
.Nm xwallpaper
.Op Fl Fl screen Ar screen
.Op Fl Fl clear
.Op Fl Fl daemon
.Op Fl Fl debug
.Op Fl Fl no-atoms
.Op Fl Fl no-randr
.Op Fl Fl no-root
.Op Fl Fl trim Ar widthxheight[+x+y]
.Op Fl Fl output Ar output
.Op Fl Fl center Ar file
.Op Fl Fl focus Ar file
.Op Fl Fl maximize Ar file
.Op Fl Fl stretch Ar file
.Op Fl Fl tile Ar file
.Op Fl Fl zoom Ar file
.Op Fl Fl version
.Sh "توضیحات (DESCRIPTION)"
برنامه
.Nm xwallpaper
به شما امکان می‌دهد فایل‌های تصویری را به عنوان تصویر پس‌زمینه X خود تنظیم کنید.
قالب فایل PNG به‌صورت پیش‌فرض پشتیبانی شده و ترجیح داده می‌شود،
اما پشتیبانی اختیاری از JPEG نیز وجود دارد.
.Pp
تصویر پس‌زمینه همچنین به برنامه‌هایی که از پس‌زمینه‌های نیمه‌شفاف پشتیبانی می‌کنند شناسانده می‌شود.
.Sh "گزینه‌ها (OPTIONS)"
گزینه‌های مختلف به شرح زیر هستند:
.Bl -tag -width Ds
.It Fl Fl center Ar file
فایل ورودی را در مرکز خروجی قرار می‌دهد.
اگر ابعاد فایل ورودی از ابعاد خروجی کوچک‌تر باشد،
فضای باقی‌مانده با رنگ سیاه پر می‌شود.
اگر ابعاد فایل ورودی بیش از حد بزرگ باشد، بخش‌هایی از تصویر برش می‌خورد.
.It Fl Fl clear
صفحه را با یک پس‌زمینه سیاه مقداردهی اولیه می‌کند. بدون این گزینه،
محتوای فعلی اتم‌های شبه‌شفافیت (pseudo transparency) دریافت شده و به عنوان پایه استفاده می‌شود.
اگر محتوای اتم وجود نداشته باشد یا قابل استفاده مجدد نباشد، برای مثال به دلیل تغییر
وضوح تصویر یکی از خروجی‌ها، در این صورت نیز از یک پس‌زمینه اولیه سیاه استفاده می‌شود.
.It Fl Fl daemon
برنامه
.Nm xwallpaper
را در پس‌زمینه در حال اجرا نگه می‌دارد تا به رویدادهای RandR گوش دهد. در این حالت،
با تغییر اندازه خروجی‌ها، تصویرهای پس‌زمینه دوباره ترسیم می‌شوند. این گزینه تنها زمانی
قابل استفاده است که پشتیبانی از RandR موجود و فعال باشد.
.It Fl Fl debug
پیام‌های اشکال‌زدایی را هنگام اجرای
.Nm xwallpaper
روی خروجی خطای استاندارد نمایش می‌دهد. در صورت استفاده هم‌زمان با
.Fl Fl daemon
این فرایند ورودی و خروجی‌های استاندارد را تغییر نخواهد داد.
.It Fl Fl focus Ar file
در ترکیب با
.Fl Fl trim
تضمین می‌شود که کادر برش تعیین‌شده در خروجی قابل مشاهده باشد و در صورت نیاز بزرگ‌نمایی به سمت بیرون انجام می‌شود. اگر پیکسل‌های سیاه در اطراف ناحیه انتخابی ایجاد شود، تصویر ورودی بزرگ‌نمایی شده و جابه‌جا می‌شود تا آن‌ها را به بهترین نحو ممکن تحت قیدِ نگه‌داشتن کادر برش تعیین‌شده (یا کل تصویر در صورت عدم تعیین کادر برش) در خروجی پوشش دهد.
.It Fl Fl maximize Ar file
فایل ورودی را تا جای ممکن بزرگ می‌کند تا بدون برش‌خوردگی در خروجی جا بگیرد.
بسته به ابعاد فایل ورودی و خروجی، این امر می‌تواند به معنای بزرگ‌نمایی به داخل یا خارج باشد.
این گزینه تضمین می‌کند که تمام تصویر دیده شود.
اگر نسبت تصویر با خروجی هم‌خوانی نداشته باشد، فضای باقی‌مانده با رنگ سیاه پر می‌شود.
خود تصویر در مرکز خروجی قرار خواهد گرفت.
.It Fl Fl no-atoms
اتم‌هایی که برای شبه‌شفافیت استفاده می‌شوند به‌روزرسانی نمی‌شوند. با گزینه
.Fl Fl no-root
ناسازگار است (مانعة‌الجمع). به‌طور خودکار گزینه
.Fl Fl clear
را فعال می‌کند.
.It Fl Fl no-randr
خروجی‌های جداگانه را نادیده گرفته و به جای آن از کل خروجی یکپارچه استفاده می‌کند.
این ناحیه فضایی است که در سرتاسر همه خروجی‌های مختلف (مانیتورها) گسترده شده است.
.It Fl Fl no-root
پس‌زمینه پنجره ریشه (root window) به‌روزرسانی نمی‌شود. اگر می‌خواهید فقط اتم‌های مربوط به شبه‌شفافیت را به‌روزرسانی کنید از این گزینه استفاده کنید. بنابراین با گزینه
.Fl Fl no-atoms
ناسازگار است (مانعة‌الجمع).
.It Fl Fl trim Ar widthxheight+x+y
ناحیه مورد نظر را در فایل مبدأ مشخص می‌کند. اگر حالت خروجی سعی کند پیکسل‌های بیشتری از آنچه با کادر برش تعیین شده در خروجی قرار دهد، پیکسل‌های مجاور در اطراف کادر به خروجی اضافه خواهند شد. پیکسل‌های سیاه تنها زمانی اضافه می‌شوند که هیچ پیکسل مبدأ دیگری باقی نمانده باشد.
.It Fl Fl output Ar output
خروجی‌ای را مشخص می‌کند که فایل ارائه‌شده پس از آن باید به عنوان تصویر پس‌زمینه روی آن تنظیم شود.
می‌توانید با اجرای
.Xr xrandr 1
فهرستی از خروجی‌های سیستم خود را دریافت کنید.
اگر هیچ خروجی‌ای تعیین نشود، همه خروجی‌ها به‌صورت جداگانه تغییر خواهند کرد.
کلمه کلیدی خاص
.Cm all
اقدامات بعدی را روی همه نمایشگرها تکرار می‌کند.
اگر خروجی پیدا نشود، اقدام‌های مرتبط با آن نادیده گرفته می‌شوند.
.It Fl Fl screen Ar screen
یک صفحه (screen) را با شماره صفحه آن مشخص می‌کند.
به‌طور معمول همه صفحه‌های یک نمایشگر X پردازش می‌شوند.
لطفاً توجه داشته باشید که یک screen معادل با یک مانیتور تکی نیست.
برای چنین کاربردی، گزینه
.Fl Fl output
را در بالا ببینید.
.It Fl Fl stretch Ar file
فایل ورودی را می‌کشد تا خروجی را کاملاً بپوشاند.
اگر نسبت ابعاد فایل ورودی با خروجی هم‌خوانی نداشته باشد،
نسبت ابعاد فایل ورودی تغییر داده می‌شود.
.It Fl Fl tile Ar file
از حالت کاشی‌کاری استفاده می‌کند.
فایل ورودی را در گوشه سمت چپ بالای خروجی رسم می‌کند
و تصویر را تا زمانی که تمام مساحت باقی‌مانده خروجی پوشانده شود، تکرار می‌کند.
.It Fl Fl version
نسخه برنامه را چاپ کرده و خارج می‌شود.
.It Fl Fl zoom Ar file
فایل ورودی را بزرگ‌نمایی می‌کند تا با برش‌خوردگی در خروجی جا بگیرد.
بسته به ابعاد فایل ورودی و خروجی، این امر می‌تواند به معنای بزرگ‌نمایی به داخل یا خارج باشد.
اگر نسبت ابعاد با خروجی هم‌خوانی نداشته باشد،
بخش‌هایی از فایل ورودی نمایش داده نخواهند شد.
خود تصویر در مرکز خروجی قرار خواهد گرفت.
اگر هیچ گزینه‌ای انتخاب نشده باشد، این رفتار پیش‌فرض است.
.El
.Pp
اگر چندین گزینه متناقض مشخص شده باشد، آخرین گزینه ارائه‌شده اولویت خواهد داشت.
همچنین می‌توان آرگومان‌های خروجی را بدون مشخص کردن فایل‌های بعدی تکرار کرد.
در این حالت، آخرین حالت و فایل دوباره استفاده خواهند شد.
.Sh "مثال‌ها (EXAMPLES)"
قرار دادن یک فایل PNG به عنوان تصویر پس‌زمینه در مرکز خروجی LVDS-1:
.Dl $ xwallpaper --output LVDS-1 --center file.png
.Pp
تمرکز بر گوشه بالا سمت چپ یک فایل JPEG به عنوان تصویر پس‌زمینه در Virtual-1:
.Dl $ xwallpaper --output Virtual-1 --trim 1x1+0+0 --focus file.jpg
.Pp
کاشی‌کاری یک فایل PNG به عنوان تصویر پس‌زمینه در تمامی خروجی‌ها:
.Dl $ xwallpaper --no-randr --tile file.png
.Pp
بزرگ‌نمایی یک فایل JPEG به عنوان تصویر پس‌زمینه روی هر خروجی به‌صورت جداگانه:
.Dl $ xwallpaper --zoom file.jpg
.Pp
قرار دادن یک فایل JPEG در مرکز و تنظیم مجدد آن در مرکز تمام خروجی‌ها پس از به‌روزرسانی‌های خروجی:
.Dl $ xwallpaper --daemon --center file.jpg
.Pp
کاشی‌کاری یک فایل JPEG به عنوان تصویر پس‌زمینه روی VGA-1 و بزرگ‌نمایی یک فایل PNG روی LVDS-1:
.Dl $ xwallpaper --output VGA-1 --tile file.jpg --output LVDS-1 --zoom file.png
.Sh "گزارش باگ‌ها (BUGS)"
از سیستم پیگیری مشکلات در GitHub استفاده کنید:
.Lk https://github.com/stoeckmann/xwallpaper/issues
.Sh "نویسندگان (AUTHORS)"
.An Tobias Stoeckmann Aq Mt tobias@stoeckmann.org