لایه‌ها (Layers)

یک لایه مجموعه‌ای از نگاشت‌ها (bindings) است که هر کدام رفتار یک کلید خاص را مشخص می‌کنند چندین لایه می‌توانند در هر لحظه فعال باشند و پشته‌ای از نگاشت‌های پوشاننده را تشکیل دهند که به ترتیب فعال‌سازی بررسی می‌شوند لایه پیش‌فرض main نام دارد و نگاشت‌های عمومی باید در آن تعریف شوند

به عنوان مثال، قطعه پیکربندی زیر لایه‌ای به نام nav تعریف می‌کند و یک سوئیچ تغییر وضعیت برای آن در لایه main ایجاد می‌نماید:

[main]
capslock = layer(nav)
[nav]
h = left
k = up
j = down
l = right

هنگامی که capslock نگه داشته شود، لایه nav روی لایه main قرار می‌گیرد و باعث می‌شود کلیدهای hjkl به عنوان کلیدهای جهت‌نمای متناظر عمل کنند.

برخلاف اغلب ابزارهای نگاشت مجدد، keyd پشتیبانی درجه‌یکی از کلیدهای تبدیل (modifiers) فراهم می‌کند نام یک لایه می‌تواند به صورت اختیاری با یک ':' همراه با مجموعه‌ای از کلیدهای تبدیل که در صورت نبود نگاشت صریح شبیه‌سازی می‌شوند خاتمه یابد نام لایه‌ها حداکثر می‌تواند شامل ۶۴ نویسه باشد (شامل تمام کلیدهای تبدیل).

این لایه‌ها به خوبی با سایر کلیدهای تبدیل هماهنگ شده و معناشناسی پشته‌بندی موجود را حفظ می‌کنند

برای مثال:

[main]
capslock = layer(capslock)
[capslock:C]
j = down

باعث می‌شود کلید capslock مانند control رفتار کند، به جز در مورد ترکیب capslock+j که کلید down را ارسال می‌کند این امر تعریف کلیدهای تبدیل سفارشی را که با یکدیگر تداخل ندارند بسیار ساده می‌سازد.

توجه داشته باشید که نگاشت‌ها تحت تأثیر کلیدهای تبدیل لایه‌ای که در آن تعریف شده‌اند قرار نمی‌گیرند بنابراین ترکیب capslock+j یک فشرده شدن کلید down بدون تغییر تولید می‌کند، در حالی که shift+capslock+j همان‌طور که انتظار می‌رود shift+down تولید خواهد کرد.

به صورت رسمی، سربرگ هر لایه دارای فرم زیر است:

"[" <layer name>[:<modifier set>] "]"

که در آن <modifier_set> دارای فرم زیر است:

و هر کلید تبدیل یکی از موارد زیر است:

در نهایت، هر سربرگ لایه با مجموعه‌ای از نگاشت‌ها دنبال می‌شود که ساختار زیر را دارند:

برای توضیح <action> و <macro> بخش‌های ACTIONS و MACROS را ببینید.

به طور پیش‌فرض، هر کلید در لایه اصلی به خود متصل است استثنای این قاعده کلیدهای تبدیل هستند که به جای آن به لایه‌هایی هم‌نام با کلیدهای تبدیل متناظر متصل شده‌اند

برای مثال، کلید meta در واقع به layer(meta) متصل است، جایی که meta در داخل برنامه به عنوان meta:M تعریف شده است.

مجموعه کامل نگاشت‌های کلیدهای تبدیل به صورت زیر است:

control = layer(control)
meta = layer(meta)
shift = layer(shift)
leftalt = layer(alt)
rightalt = layer(altgr)

پیامد این امر این است که بازنویسی کلیدهای تبدیل صرفاً با اضافه کردن نگاشت‌های دلخواه به لایه از پیش تعریف‌شده مناسب به راحتی امکان‌پذیر است.

بنابراین:

[ids]
*
[control]
j = down

یک فایل پیکربندی کاملاً معتبر است و دقیقاً همان کاری را انجام می‌دهد که کاربر انتظار دارد در داخل سیستم، پیکربندی کامل در واقع شبیه به این است:

[ids]
*
[main]
leftcontrol = layer(control)
rightcontrol = layer(control)
[control:C]
j = down

اگر چندین نگاشت برای یک کلید یکسان وجود داشته باشد، نگاشتی که دیرتر آمده اولویت خواهد داشت.

سربرگ یک لایه می‌تواند چندین بار تکرار شود، که در این حالت لایه شامل مجموع تمام نگاشت‌ها خواهد بود توجه داشته باشید که نوع لایه را نمی‌توان مجدداً بازتعریف کرد.

یعنی:

[mylayer:A]
a = b
c = d
[mylayer:C]
a = x
b = c

معادل است با:

[mylayer:A]
a = x
b = c
c = d

لایه‌های ترکیبی (Composite Layers)

نوع خاصی از لایه با نام لایه ترکیبی (composite layer) را می‌توان با ایجاد لایه‌ای با نامی متشکل از لایه‌های موجود که با علامت + از هم جدا شده‌اند تعریف کرد لایه حاصل زمانی فعال شده و اولویت می‌یابد که تمام اجزای تشکیل‌دهنده آن فعال باشند لایه‌های ترکیبی مجاز به داشتن کلیدهای تبدیل متصل نیستند و نمی‌توان آن‌ها را به صورت صریح انتساب داد.

برای مثال:

[control+alt]
h = left

باعث می‌شود توالی control+alt+h کلید left را تولید کند (با نادیده گرفتن کلیدهای تبدیل control و alt متصل به لایه‌های فعال control و alt)، در حالی که فشردن control+alt+f1 آن کلیدهای تبدیل را حفظ کرده و دقیقاً همان چیزی را که فشرده شده ارسال می‌کند، زیرا نگاشت صریحی برای f1 در لایه ترکیبی وجود ندارد.

[main]
capslock = layer(capslock)
[capslock:C]
[capslock+shift]
h = left

باعث می‌شود توالی capslock+shift+h کلید left را تولید کند، در حالی که عملکرد مورد انتظار capslock و shift را در حالت مجزا حفظ می‌نماید.

نکته: لایه‌های ترکیبی باید همیشه بعد از لایه‌هایی که از آن‌ها تشکیل شده‌اند تعریف شوند.

یعنی:

[layer1]
[layer2]
[layer1+layer2]

و نه:

[layer1+layer2]
[layer1]
[layer2]

چیدمان‌ها (Layouts)

چیدمان (layout) نوع خاصی از لایه است که برای اصلاح کلیدهای الفبایی در نظر گرفته شده است برخلاف لایه‌ها، چیدمان‌ها نمی‌توانند کلید تبدیل مرتبطی داشته باشند، و تنها یک چیدمان می‌تواند در هر لحظه فعال باشد چیدمان پیش‌فرض 'main' نام دارد و می‌توان آن را با استفاده از کنش setlayout() تغییر داد.

جهت سهولت، keyd همراه با تعدادی از چیدمان‌های حروف پرکاربرد در مسیر /usr/share/keyd/layouts عرضه می‌شود قبل از اضافه کردن آن‌ها، بررسی محتوایشان آموزنده است چیدمان‌های غیرانگلیسی شامل یک لایه shift اختصاصی هستند (که ترتیب شمول را مهم می‌سازد) و نیاز به استفاده از تعاریف compose در keyd دارند (بخش پشتیبانی از یونیکد (Unicode Support) را ببینید)

برای مثال:

# Include the shipped colemak layout.
include layouts/colemak
[global]
default_layout = mylayout
[mylayout:layout]
a = b
b = c
#etc...
[control]
1 = setlayout(customlayout)
2 = setlayout(colemak)

آکوردگذاری (Chording)

آکوردها (Chords) گروه‌هایی از کلیدها هستند که هنگام فشرده شدن هم‌زمان به عنوان یک واحد تلقی می‌شوند یک آکورد را می‌توان با استفاده از گروهی از نام‌های کلید جداشده با + به عنوان مقدار سمت چپ تعریف کرد در صورتی که همه کلیدها در بازه زمانی آکورد (chord_timeout) فشرده شوند، کنش متناظر فعال خواهد شد.

برای مثال:

j+k = esc

باعث می‌شود در صورت فشرده شدن هم‌زمان هر دوی j و k، کلید esc ارسال شود.

نکته: ممکن است برای تطابق با ویژگی‌های فیزیکی صفحه‌کلید خود بخواهید بازه زمانی پیش‌فرض آکوردگذاری (50 میلی‌ثانیه) را تغییر دهید.

پشتیبانی از یونیکد (Unicode Support)

اگر keyd با یک توالی معتبر UTF8 به عنوان مقدار سمت راست مواجه شود، تلاش می‌کند آن توالی را به یک ماکرو که توالی XKB مخصوص keyd را ارسال می‌کند ترجمه کند.

برای اینکه این قابلیت کار کند، توالی‌های تعریف‌شده در فایل compose ارائه‌شده همراه با keyd (/usr/share/keyd/keyd.compose) باید در دسترس باشند این کار را می‌توان به صورت سراسری با کپی کردن فایل در مکان مناسب در /usr/share/X11/locale یا برای هر کاربر به طور جداگانه با ایجاد یک پیوند نمادین به ~/.XCompose انجام داد.

برای مثال:

علاوه بر این، شما باید از چیدمان پیش‌فرض US در سرور نمایش خود استفاده کنید. به کاربران چیدمان‌های غیرانگلیسی توصیه می‌شود چیدمان خود را درون keyd تنظیم کنند (بخش Layouts را ببینید) تا از تداخل بین چیدمان سرور نمایش و قابلیت‌های یونیکد keyd جلوگیری شود.

نکته: ممکن است برای اعمال تغییرات لازم باشد برنامه‌های خود را مجدداً راه‌اندازی کنید.

نکته ۲: توالی‌های compose تولیدشده طبق معمول تحت تأثیر کلیدهای تبدیل قرار می‌گیرند اگر می‌خواهید shift نماد متفاوتی تولید کند، باید یک لایه shift سفارشی تعریف کنید (برای نمونه فایل‌های چیدمان همراه برنامه را ببینید).

نکته ۳: کتابخانه GTK4 در حال حاضر دارای باگی است که باعث می‌شود در صورت وجود فایل‌های بزرگ XCompose (مانند /usr/share/keyd/keyd.compose) دچار کرش شود.

نام‌های مستعار (Aliases)

به هر کلید می‌توان به صورت اختیاری یک نام مستعار (alias) اختصاص داد این نام مستعار می‌تواند به جای کلید به عنوان یک مقدار معتبر در سمت چپ نگاشت استفاده شود چندین کلید را می‌توان به یک نام مستعار یکسان متصل کرد، اما در هر زمان تنها یک نام مستعار را می‌توان به یک کلید اختصاص داد.

به عنوان مثال، کلیدهای 'leftmeta' و 'rightmeta' به صورت پیش‌فرض به نام مستعار meta متصل شده‌اند بنابراین نگاشت 'meta = a' معادل با نگاشت‌های 'leftmeta = a' و 'rightmeta = a' است.

نام‌های مستعار در بخش ویژه‌ای به نام 'aliases' تعریف می‌شوند که هر خط آن دارای ساختار زیر است:

که در آن <key> باید یک نام کلید معتبر باشد.

توجه داشته باشید که <name> خود می‌تواند یک نام کلید معتبر باشد، که در این صورت تمام ارجاعات به آن کلید در فایل پیکربندی با کلید جدید جایگزین می‌شوند علاوه بر این، اگر نام مستعار اختصاص‌داده‌شده یک نام کلید معتبر باشد، کد کلید (keycode) متناظر به طور پیش‌فرض به آن کلید اختصاص می‌یابد این امر بازتعریف کلیدها را قبل از اعمال هرگونه نگاشت ممکن می‌سازد و به ویژه در ترکیب با سازوکار include برای هماهنگی با تفاوت‌های سخت‌افزاری بسیار کاربردی است.

برای مثال:

/etc/keyd/common:
	meta = oneshot(meta)
	alt = oneshot(alt)
	a = a
	s = o
	# etc..
/etc/keyd/default.conf:
	[ids]
	*
	[main]
	include common
/etc/keyd/magic_keyboard.conf:
	[ids]
	004c:0267
	[aliases]
	leftalt = meta
	rightalt = meta
	rightmeta = alt
	leftmeta = alt
	[main]
	include common

به کاربر اجازه می‌دهد مجموعه‌ای از نگاشت‌های سراسری را در /etc/keyd/common تعریف کند بدون اینکه نیازی باشد جابه‌جایی کلیدهای meta و alt را صراحتاً درون قطعه پیکربندیِ شامل‌شده در نظر بگیرد.

شامل‌سازی فایل (File Inclusion)

فایل‌های پیکربندی می‌توانند فایل‌های دیگر واقع در دایرکتوری پیکربندی را با استفاده از کلمه کلیدی include شامل شوند خطی به فرم include <file> می‌تواند در هر نقطه‌ای پس از بخش [ids] ظاهر شود پیکربندی حاصل طوری عمل خواهد کرد که گویی محتوای فایل شامل‌شده به جای عبارت include قرار گرفته است.

استفاده راهبردی از این عبارات، امکان اشتراک‌گذاری عملکردهای مشترک بین پیکربندی‌ها را فراهم می‌سازد.

مسیرهای include نسبی هستند و باید در یکی از دایرکتوری‌های زیر قرار داشته باشند:

برای مثال:

/etc/keyd/default.conf:
	[ids]
	*
	# Add our shared custom bindings.
	include common
	# Appends bindings to the main layer
	# defined in /etc/keyd/common (order matters)
	[main]
	capslock = layer(capslock)
	[capslock]
	1 = setlayout(colemak)
	2 = setlayout(dvorak)
/etc/keyd/common:
	[main]
	rightmeta = layer(nav)
	[nav]
	h = left
	j = down
	k = up
	l = right
/usr/share/keyd/layouts/dvorak:
	a = a
	s = o
	...

محدودیت‌ها:

سربارگذاری کلید (Key overloading)

overload(<layer>, <action>)

overloadt(<layer>, <action>, <timeout>)

overloadt2(<layer>, <action>, <timeout>)

overloadi(<action 1>, <action 2>, <idle timeout>)

a = overloadi(a, overloadt2(control, a, 200), 150)

lettermod(<layer>, <key>, <idle timeout>, <hold timeout>)

timeout(<action 1>, <timeout>, <action 2>)

macro2(<timeout>, <repeat timeout>, <macro>)

macro2(400, 50, macro(Hello space World))
macro2(120, 80, left)

نکته: دستورات توسط کاربری که فرآیند keyd را اجرا کرده است (احتمالاً root) اجرا می‌شوند، از این قابلیت با احتیاط فراوان استفاده کنید.

noop

نگاشت‌ها (Bindings)

دستور bind یک یا چند نگاشت (binding) را می‌پذیرد که هر یک باید ساختار زیر را داشته باشند:

که در آن <layer> نام یک لایه (موجود) است که کلید باید در آن نگاشت شود.

به عنوان یک حالت خاص، رشته "reset" می‌تواند به جای یک نگاشت استفاده شود، که در این حالت نگاشت کلید فعلی به وضعیت اولیه خود بازمی‌گردد (تمام نگاشت‌های اعمال‌شده به صورت پویا لغو خواهند شد).

مثال‌ها:

$ keyd bind '- = C-c'
$ keyd bind reset '+ = C-c' # Reset the keyboard before applying the '+' binding (drops the previous '-' binding)

به طور پیش‌فرض عبارت‌ها برای صفحه‌کلیدی اعمال می‌شوند که اخیراً فعال بوده است.

مثال ۱

تغییر وضعیت چیدمان حروف dvorak با فشردن ترکیب esc+q.

[ids]
*
[main]
esc = layer(esc)
[dvorak]
a = a
s = o
...
[esc]
q = toggle(dvorak)

مثال ۲

معکوس کردن رفتار کلید shift بدون برهم زدن رفتار کلید تبدیل.

[ids]
*
[main]
1 = !
2 = @
3 = #
4 = $
5 = %
6 = ^
7 = &
8 = *
9 = (
0 = )
[shift]
0 = 0
1 = 1
2 = 2
3 = 3
4 = 4
5 = 5
6 = 6
7 = 7
8 = 8
9 = 9

مثال ۳

یک بار ضربه زدن به کلید control باعث اعمال آن روی کلید بعدی می‌شود، دو بار ضربه زدن آن را تا زمانی که دوباره فشرده شود فعال نگه می‌دارد، و نگه داشتن آن رفتار مورد انتظار را ایجاد می‌کند.

[main]
control = oneshot(control)
[control]
control = toggle(control)

مثال ۴

کلید Meta رفتار عادی دارد مگر زمانی که کلید ` فشرده شود، که پس از آن لایه alt_tab در طول مدت فشردن leftmeta فعال می‌شود بنابراین فشردن‌های بعدی به جای M-\ کلید A-tab را تولید خواهند کرد.

[meta]
` = swap(alt_tab, A-tab)
[alt_tab:A]
tab = A-S-tab
` = A-tab

مثال ۵

# Uses the compose key functionality of the display server to generate
# international glyphs.  # For this to work 'setxkbmap -option  compose:menu'
# must be run after keyd has started (see NOTES).
# A list of sequences can be found in /usr/share/X11/locale/en_US.UTF-8/Compose
# on most systems.
[main]
rightalt = layer(dia)
[dia]
# Map o to ö
o = macro(compose o ")
# Map e to €
e = macro(compose c =)

مثال ۶

# Tapping both shift keys will activate capslock.
[shift]
leftshift = capslock
rightshift = capslock

مثال ۷

کلید Capslock در تمام حالات مانند control عمل می‌کند به جز زمانی که در ترکیب با 'h/j/k/l' استفاده شود که در این حالت کلیدهای جهت‌نما را تولید می‌کند در صورت ضربه زدن به آن، به عنوان escape عمل خواهد کرد.

[main]
capslock = overload(capslock, esc)
esc = capslock
[capslock:C]
h = left
k = up
j = down
l = right

مثال ۸

غیرفعال کردن کلیدهای esc و end.

[main]
esc = noop
end = noop