نام (NAME)

shikane - فایل پیکربندی

توضیحات (DESCRIPTION)

برنامه shikane از قالب پرونده TOML برای فایل پیکربندی خود استفاده می‌کند و حاوی آرایه‌ای از profileها است. هر profile یک جدول است که شامل آرایه‌ای از جدول‌های output می‌باشد.

کلمات “output”، “display” و “monitor” می‌توانند به جای یکدیگر استفاده شوند. با این حال، در متن زیر تمایزی بین “display” و “output” قائل شده است. کلمه “display” به یک نمایشگر متصل فعلی اشاره دارد و “output” به یک جدول در فایل پیکربندی اشاره می‌کند. همین موضوع به ترتیب برای “mode” و “mode” نیز صدق می‌کند. (لطفاً به ضخامت قلم دقت کنید.)

برنامه shikane پروفایل‌های (profile) ممکن را هنگام راه‌اندازی و زمانی که تغییری در مجموعه نمایشگرهای متصل فعلی رخ می‌دهد، به‌طور خودکار انتخاب می‌کند. یک profile زمانی در نظر گرفته می‌شود که هر نمایشگر متصل فعلی بتواند با حداقل یک output تطبیق داده شود و هیچ output تطبیق‌نیافته‌ای باقی نماند.

یک نمایشگر با یک output تطبیق می‌یابد اگر:

•: پارامتر search با مشخصه‌های نمایشگر مطابقت داشته باشد (همچنین به OUTPUT FIELDS در زیر مراجعه کنید)

•: و نمایشگر از حالتی (mode) که در جدول output مشخص شده است، پشتیبانی کند.

پس از گردآوری فهرستی از profileهای ممکن، shikane تمام گونه‌های (variants) هر profile را تولید می‌کند. به‌محض بررسی و مرتب‌سازی تمام گونه‌ها بر اساس میزان دقت، shikane تلاش می‌کند آن‌ها را یکی پس از دیگری اعمال کند تا یکی موفق شود یا گونه‌ای برای آزمایش باقی نماند.

گونه‌ها نسخه‌های کمی متفاوت از همان profile هستند.

به عنوان مثال، یک نمایشگر مفروض دارای مجموعه‌ای از حالت‌های پشتیبانی‌شده است: 1920x1080@60Hz و 1920x1080@50Hz. اگر mode در config.toml به صورت “1920x1080” مشخص شده باشد، هر دو حالت با این مشخصات همخوانی دارند. به جای انتخاب تنها یک حالت و استفاده از آن، shikane هر دو را با تولید دو گونه بر اساس همان profile در نظر می‌گیرد. یک گونه از حالت 1920x1080@60Hz و گونه دیگر از حالت 1920x1080@50Hz استفاده می‌کند.

همین موضوع برای پارامتر search نیز صدق می‌کند. اگر چندین ترکیب (display,output,mode) ممکن باشد، shikane گونه‌هایی با تمام آن‌ها تولید می‌کند.

نیازی نیست فایل پیکربندی را با دست بنویسید. می‌توانید از هر ابزاری برای چیدمان نمایشگرها به هر شکلی که می‌خواهید استفاده کنید و سپس دستور export از shikanectl(1) را به کار ببرید. این دستور پیکربندی را برای شما تولید خواهد کرد.

قالب (FORMAT)

timeout = timeout: اختیاری. برنامه shikane هر زمان که تغییری شناسایی شود، به مدت timeout مشخص‌شده (به میلی‌ثانیه) صبر خواهد کرد. معمولاً نباید این مقدار را تنظیم کنید زیرا باعث کند شدن shikane می‌شود. مقدار پیش‌فرض 0 است.
[[profile]]: اختیاری. یک جدول جدید profile را آغاز می‌کند. یک name باید مشخص شود. برای جزئیات به PROFILE FIELDS مراجعه کنید.

فیلدهای پروفایل (PROFILE FIELDS)

name = "name": اجباری. نام (name) مربوط به profile را مشخص می‌کند.
[[profile.output]]: اجباری. یک جدول output به profile اضافه می‌کند. شامل پارامترهایی است که برای پیکربندی یک نمایشگر استفاده می‌شوند. برای جزئیات به OUTPUT FIELDS مراجعه کنید.

به عنوان مثال در sway(1)، نام‌ها (name) و توضیحات (description) نمایشگر را می‌توان از طریق swaymsg -t get_outputs به دست آورد.

exec = [ "command", ... ]: اختیاری. یک آرایه exec حاوی مجموعه‌ای از دستورها (command) است که پس از اعمال موفقیت‌آمیز profile اجرا می‌شوند. ترتیب اجرا تضمین نمی‌شود که حفظ شود. نام (name) پروفایل را می‌توان از متغیر محیطی $SHIKANE_PROFILE_NAME دریافت کرد.

فیلدهای خروجی (OUTPUT FIELDS)

یک نمایشگر در میان سایر موارد، دارای ویژگی‌های name، vendor، model، serialnumber و description است و ممکن است به این صورت باشد: “DP-1”، “Company Foo”، “FooHD-24”، “12345678”، “Something Foo Something Bar”

search = "pattern"

search = "[kind]pattern"

search = "[[attrs]kind]pattern"

search = [ "[[attrs]kind]pattern", ... ]: اجباری. این فیلد از ۳ بخش تشکیل شده است. فهرست ویژگی‌ها (attribute list) attrs در ابتدا، نوع جستجو (search kind) kind در میانه، و الگو (pattern) در انتها.

فهرست ویژگی‌ها (attribute list) attrs مشخص می‌کند که کدام ویژگی‌ها با pattern مقایسه خواهند شد و چگونه وزن‌دهی می‌شوند. این فیلد توالی‌ای از حروف از مجموعه {dnmvs} است. حروف متناظر با حرف اول ویژگی‌های ذکرشده در بالا هستند. هر ویژگی نباید بیش از یک بار در هر فیلد search استفاده شود. اولین ویژگی بالاترین/بهترین وزن را دارد و آخرین ویژگی پایین‌ترین/بدترین وزن را داراست. برای اینکه یک search منفرد قابل اعمال در نظر گرفته شود، تمام ویژگی‌ها باید با pattern مطابقت داشته باشند.

نوع جستجو (search kind) kind می‌تواند یکی از موارد {=/%} باشد. این ۳ نوع جستجو (search kinds) — عبارت منظم (/)، زیررشته (%)، متن کامل (=) — مشخص می‌کنند که pattern چگونه با هر ویژگی (attribute) در فهرست attrs مقایسه می‌شود. در مقایسه متن کامل، ویژگی‌های داده‌شده از نظر برابری با pattern مقایسه می‌شوند. در مقایسه زیررشته، ویژگی‌های داده‌شده باید حاوی pattern به عنوان زیررشته باشند. وزن با تقسیم طول‌های رشته‌های pattern و ویژگی محاسبه می‌شود. طول‌های برابر همانند مقایسه متن کامل رتبه‌بندی خواهند شد. در مقایسه عبارت منظم، pattern به عنوان یک عبارت منظم تفسیر می‌شود. مقایسه با عبارت منظم همیشه رتبه پایین‌تری نسبت به دو نوع جستجوی دیگر کسب خواهد کرد.

فهرست ویژگی‌ها (attribute list) و نوع جستجو (search kind) اختیاری هستند. اگر مشخص نشود، نوع جستجو به طور پیش‌فرض روی مقایسه متن کامل قرار می‌گیرد و shikane تلاش می‌کند حداقل یک ویژگی منطبق را بیابد.

همچنین، چندین جستجو، حداکثر تا ۵ مورد، می‌توانند در یک آرایه مشخص شوند.

enable = true | false: اجباری. نمایشگر تطبیق‌یافته را فعال یا غیرفعال می‌کند.
exec = [ "command", ... ]: اختیاری. یک آرایه exec حاوی مجموعه‌ای از دستورها است که پس از اعمال موفقیت‌آمیز profile اجرا می‌شوند. ترتیب اجرا تضمین نمی‌شود که حفظ شود. نام (name) نمایشگر را می‌توان از متغیر محیطی $SHIKANE_OUTPUT_NAME دریافت کرد.

گزینه‌های mode، position، scale، transform و adaptive_sync تنها در صورتی ویژگی‌های مربوط به نمایشگر را تغییر می‌دهند که مشخص شده باشند (برای نمونه، اگر فیلد scale وجود نداشته باشد، مقیاس‌بندی نمایشگر تغییر نخواهد کرد).

mode = "best" | "preferred"

mode = "[!]widthxheight[@rate[Hz]]"

mode = { width = width, height = height, refresh = rate[, custom = true | false] }: اختیاری. نمایشگر تطبیق‌یافته را برای استفاده از حالت منطبق پیکربندی می‌کند. حالت‌ها ترکیبی از عرض (width) و ارتفاع (height) (به پیکسل) و نرخ نوسازی (rate) (به هرتز) هستند که نمایشگر شما می‌تواند برای استفاده از آن‌ها پیکربندی شود. نرخ نوسازی (rate) همچنین می‌تواند یک عدد اعشاری باشد. اگر نمایشگر از حالت مشخص‌شده (mode) پشتیبانی نکند، با یک output تطبیق داده نخواهد شد.

یک mode پارامتری را می‌توان به صورت اختیاری با افزودن علامت تعجب (!) به عنوان پیشوند، به عنوان سفارشی اعلام کرد. در این حالت، shikane تلاشی برای یافتن حالتی با همان پارامترها نخواهد کرد و فقط مقادیر ارائه‌شده را به compositor ارسال می‌کند.

تنظیم mode روی best یا preferred به shikane دستور می‌دهد که خودش حالت را انتخاب کند. حالت best توسط shikane به عنوان حالتی با بالاترین تعداد پیکسل، عرض، ارتفاع و نرخ نوسازی تعیین می‌شود. بیشتر نمایشگرها حالتی را که ترجیح می‌دهند اعلام می‌کنند. اگر mode روی preferred تنظیم شده باشد، shikane در صورت وجود، حالت ترجیح‌داده‌شده را انتخاب می‌کند. در غیر این صورت، بهترین حالت به عنوان جایگزین انتخاب می‌شود.

position = "x,y": اختیاری. نمایشگر را در موقعیت مشخص‌شده در فضای مختصات جهانی قرار می‌دهد.
scale = factor: اختیاری. نمایشگر را با ضریب اعشاری مشخص‌شده (factor) مقیاس‌بندی می‌کند.
transform = "transform": اختیاری. تبدیل هندسی نمایشگر را تنظیم می‌کند. می‌تواند یکی از مقادیر 90، 180، 270 برای چرخش؛ یا flipped، flipped-90، flipped-180، flipped-270 برای قرینه‌سازی و چرخش؛ یا normal برای بدون تبدیل باشد.
adaptive_sync = true | false: اختیاری. همگام‌سازی تطبیقی را برای نمایشگر فعال یا غیرفعال می‌کند (همچنین با نام VRR یا نرخ نوسازی متغیر شناخته می‌شود).

مثال‌ها (EXAMPLES)

فاصله‌گذاری‌های ابتدای خطوط ضروری نیستند و در اینجا تنها برای نمایش سلسله‌مراتب استفاده شده‌اند.

[[profile]]
name = "Company Foo with one vertical display"
    [[profile.output]]
    search = "v=Company Foo"
    enable = true
    mode = "1920x1080@50Hz"
    position = "0,0"
    scale = 1.3
    [[profile.output]]
    search = "n/HDMI-[ABC]-[1-9]"
    enable = true
    exec = [ "echo This is output $SHIKANE_OUTPUT_NAME" ]
    position = "1920,0"
    transform = "270"
        [profile.output.mode]
        width = 2560
        height = 1440
        refresh = 75
[[profile]]
name = "custom DP-[1-9] flip"
exec = [ "echo This is an unusual display" ]
    [[profile.output]]
    search = "/DP-[1-9]"
    enable = true
    transform = "flipped"
    position = "0,0"
    mode = "!2000x1500@55.194Hz"

یک لپ‌تاپ دارای یک نمایشگر توکار است که همیشه متصل می‌باشد.

[[profile]]
name = "laptop builtin"
    [[profile.output]]
    search = "eDP-1"
    enable = true
[[profile]]
name = "no builtin + HDMI"
    [[profile.output]]
    search = "n=eDP-1"
    enable = false
    [[profile.output]]
    search = "n=HDMI-A-1"
    mode = "best"
    enable = true

برنامه shikane به شما اجازه می‌دهد چندین جستجو را مشخص کنید. به این ترتیب پروفایل‌ها می‌توانند تا حد امکان دقیق باشند.

[[profile]]
name = "home setup"
    [[profile.output]]
    search = "n=eDP-1"
    enable = false
    [[profile.output]]
    search = [ "n=HDMI-A-1", "s=1234VBAM", "m=1QX04Z", "v=specific company" ]
    enable = true
    [[profile.output]]
    search = "smv=1234abcd"
    enable = true

برای مثال در sway(1)، از exec می‌توان برای انتقال فضاهای کاری به نمایشگر مورد نظر استفاده کرد:

[[profile]]
name = "double monitor"
exec = [
    "swaymsg workspace 1, move workspace to eDP-1",
    "swaymsg workspace 2, move workspace to DP-1" ]
output = [
    {search = "eDP-1", enable = true},
    {search = "DP-1", enable = true} ]

برنامه shikane متغیر $SHIKANE_PROFILE_NAME را در محیط پردازه‌های اجراشده از آرایه profile.exec و متغیر $SHIKANE_OUTPUT_NAME را در محیط پردازه‌های output.exec فراهم می‌کند. اگر از sway(1) استفاده می‌کنید، متغیر اخیر به‌ویژه در ترکیب با swayws مفید است.

[[profile]]
name = "generic profile"
exec = ["notify-send shikane \"Profile $SHIKANE_PROFILE_NAME has been applied\""]
    [[profile.output]]
    search = "/DP-[1-9]"
    enable = true
    exec = ["swayws range --numeric 1 5 $SHIKANE_OUTPUT_NAME"]
    [[profile.output]]
    search = "n%HDMI-"
    enable = true
    mode = "preferred"
    exec = ["swayws range --numeric 6 10 $SHIKANE_OUTPUT_NAME"]

نویسندگان (AUTHORS)

Hendrik Wolff hendrik.wolff@agdsn.me

همچنین ببینید (SEE ALSO)

shikane(1)، shikanectl(1)، swayws، TOML