توقيعات الدوال المضمَّنة

كل دالة مضمَّنة، مجمَّعة حسب المجال. يعرض كل سطر أسماء المعلمات وأنواعها بالترتيب، والنوع المُرجَع. تشير بسيط إلى الدوال المضمَّنة التي يعرضها الوضع البسيط في واجهة التكوين. يصفّي أمثلة مكتبة الأمثلة لتقتصر على البرامج النصية التي تستدعي تلك الدالة المضمَّنة. يعرض تلميح الإكمال التلقائي في المحرر التوقيعات نفسها.

AutoHotkey

AutoHotkeyExecuteScript

AutoHotkeyExecuteScript(script: Text) → Integer · بسيط

يشغّل تعليمات AutoHotkey v2 البرمجية باستخدام برنامج AutoHotkey المعيَّن في الإعدادات وينتظر حتى ينتهي. يُمرَّر سياق المشغِّل كمتغيرات، وتُطبع أسطر الإخراج مسبوقة بالبادئة AHK:.

المعلمات

• script: Text — نص البرنامج النصي AutoHotkey v2 المراد تشغيله. يؤدي إيقاف الإجراء إلى إنهاء عملية AutoHotkey.

القيمة المُرجَعة

رمز خروج AutoHotkey، أو -1 إذا كان دعم AutoHotkey متوقفًا، أو لم يُعيَّن مسار برنامجه أو لم يُعثر عليه، أو فشل بدء تشغيل البرنامج.

١ مثال: التسليم إلى AutoHotkey

Capture

CaptureSaveRegion

CaptureSaveRegion(fileName: Text, x: Integer, y: Integer, width: Integer, height: Integer) → Bool

يلتقط مستطيلًا من الشاشة ويحفظه كملف صورة. يزيل أولًا أثر الإيماءة والتلميح الخاصين بهذا التطبيق من الشاشة، وينتظر ذلك لمدة تصل إلى 250 مللي ثانية.

المعلمات

• fileName: Text — مسار ملف الصورة المراد كتابته. يحدد امتداده (.bmp أو .png أو .jpg أو .jpeg) التنسيق. يُستبدل الملف الموجود، ولا تُنشأ المجلدات المفقودة.
• x: Integer — الحافة اليسرى للمستطيل، بوحدات بكسل الشاشة.
• y: Integer — الحافة العلوية للمستطيل، بوحدات بكسل الشاشة.
• width: Integer — عرض المستطيل، بالبكسل. يجب أن يكون أكبر من 0.
• height: Integer — ارتفاع المستطيل، بالبكسل. يجب أن يكون أكبر من 0.

القيمة المُرجَعة

true إذا تمت كتابة ملف الصورة؛ false إذا لم يكن العرض أو الارتفاع موجبًا، أو فشل الالتقاط، أو تعذّرت كتابة الملف. قيمة fileName لا تنتهي بـ .bmp أو .png أو .jpg أو .jpeg توقف البرنامج النصي بخطأ.

١ مثال: لقطة شاشة للمنطقة التي أحطتها بدائرة

CaptureShowImage

CaptureShowImage(fileName: Text) → Bool

يعرض ملف صورة بحجمه الأصلي في نافذة معاينة بلا حدود تظهر دائمًا في المقدمة، في وسط الشاشة الموجودة أسفل المؤشر. اسحبها لتحريكها، وانقر نقرًا مزدوجًا لإغلاقها، وانقر بزر الماوس الأيمن للنسخ والحفظ والإغلاق.

المعلمات

• fileName: Text — مسار ملف .bmp أو .png أو .jpg أو .jpeg المراد عرضه.

القيمة المُرجَعة

true إذا تم تحميل الصورة وكانت نافذة المعاينة الخاصة بها قيد الفتح؛ false إذا كان الملف مفقودًا أو لم يكن صورة قابلة للقراءة. قيمة fileName لا تنتهي بـ .bmp أو .png أو .jpg أو .jpeg توقف البرنامج النصي بخطأ.

CaptureShowRegion

CaptureShowRegion(x: Integer, y: Integer, width: Integer, height: Integer) → Bool

يلتقط مستطيلًا من الشاشة ويعرض النسخة في نافذة معاينة بلا حدود تظهر دائمًا في المقدمة، موضوعة تمامًا فوق تلك المنطقة. يزيل أولًا أثر الإيماءة والتلميح الخاصين بهذا التطبيق، وينتظر لمدة تصل إلى 250 مللي ثانية.

المعلمات

• x: Integer — الحافة اليسرى للمستطيل، بوحدات بكسل الشاشة.
• y: Integer — الحافة العلوية للمستطيل، بوحدات بكسل الشاشة.
• width: Integer — عرض المستطيل، بالبكسل. يجب أن يكون أكبر من 0.
• height: Integer — ارتفاع المستطيل، بالبكسل. يجب أن يكون أكبر من 0.

القيمة المُرجَعة

true إذا نجح الالتقاط وكانت نافذة المعاينة الخاصة به قيد الفتح؛ false إذا لم يكن العرض أو الارتفاع موجبًا أو تعذّر التقاط الشاشة.

Clipboard

ClipboardClear

ClipboardClear() → Bool

يُفرغ الحافظة، فيزيل النص والصور وكل تنسيق آخر، دون وضع أي شيء جديد فيها.

المعلمات

لا توجد معلمات.

القيمة المُرجَعة

true إذا تم إفراغ الحافظة؛ false إذا أبقى برنامج آخر الحافظة مشغولة.

١ مثال: تحويل النص المحدد إلى أحرف كبيرة

ClipboardCopySelection

ClipboardCopySelection(timeoutMs: Integer) → Text · بسيط

يرسل Ctrl+C إلى النافذة النشطة ويُرجع النص المنسوخ، بعد أن ينتظر أولًا تحرير مفاتيح Ctrl وShift وAlt وWindows. تحل النسخة محل محتوى الحافظة؛ استخدم ClipboardSave وClipboardRestore للاحتفاظ به.

المعلمات

• timeoutMs: Integer — إجمالي مدة انتظار تحرير المفاتيح ووصول النسخة، بالمللي ثانية، من 0 إلى 60000. تُحتسب القيم الأكبر على أنها 60000. القيمة 1000 تناسب معظم البرامج.

القيمة المُرجَعة

النص المنسوخ، أو نص فارغ إذا ظلت المفاتيح مضغوطة، أو لم يُنسخ شيء (لا يوجد تحديد)، أو لم تحتوِ النسخة على نص قبل انقضاء timeoutMs.

١ مثال: البحث في الويب عن النص المحدد

ClipboardGetHtml

ClipboardGetHtml() → Text

يُرجع محتوى HTML الموجود في الحافظة، مثل ما يضعه المستعرض فيها عند نسخ جزء من صفحة ويب.

المعلمات

لا توجد معلمات.

القيمة المُرجَعة

جزء HTML المنسوخ بدون عنوان HTML الخاص بالحافظة، أو نص فارغ إذا لم تحتوِ الحافظة على HTML أو كانت مشغولة.

ClipboardGetRtf

ClipboardGetRtf() → Text

يُرجع النص المنسَّق (RTF) الموجود في الحافظة، مثل ما يضعه معالج النصوص فيها عند نسخ نص منسَّق.

المعلمات

لا توجد معلمات.

القيمة المُرجَعة

ترميز RTF كنص، أو نص فارغ إذا لم تحتوِ الحافظة على RTF أو كانت مشغولة.

ClipboardGetSequenceNumber

ClipboardGetSequenceNumber() → Integer

يُرجع رقمًا يغيّره Windows في كل مرة يتغير فيها محتوى الحافظة. اقرأه قبل عملية يُفترض أن تنسخ شيئًا، ثم قارن لتعرف أن النسخة قد وصلت.

المعلمات

لا توجد معلمات.

القيمة المُرجَعة

رقم تسلسل الحافظة الحالي. التغيّر في الرقم فقط هو ما له معنى، لا القيمة نفسها.

ClipboardGetText

ClipboardGetText() → Text · بسيط

يُرجع النص العادي الموجود حاليًا في الحافظة. يتم تجاهل التنسيق والصور والملفات الموجودة في الحافظة.

المعلمات

لا توجد معلمات.

القيمة المُرجَعة

نص الحافظة، أو نص فارغ إذا لم تحتوِ الحافظة على نص أو أبقاها برنامج آخر مشغولة.

٦ أمثلة: استخراج قيمة من نص منسوخ باستخدام تعبير نمطي, عدّ الكلمات في الحافظة, ضم أسطر الحافظة في سطر واحد, تاريخ اليوم، واسم ملف مختوم بالوقت, تحويل النص المحدد إلى أحرف كبيرة, البحث في الويب عن التحديد

ClipboardLoadImage

ClipboardLoadImage(path: Text) → Bool

يحمّل ملف صورة ويضعه في الحافظة بدلًا من المحتوى الحالي، جاهزًا للصق في برامج أخرى. تصبح المناطق الشفافة في ملف PNG بيضاء.

المعلمات

• path: Text — المسار الكامل لملف الصورة، منتهيًا بـ .bmp أو .png أو .jpg أو .jpeg. أي امتداد آخر يوقف البرنامج النصي بخطأ.

القيمة المُرجَعة

true إذا أصبحت الصورة في الحافظة؛ false إذا كان الملف مفقودًا، أو لم يكن صورة قابلة للقراءة، أو كانت الحافظة مشغولة.

ClipboardPasteReplacementText

ClipboardPasteReplacementText(text: Text) → Bool · بسيط

يضع نصًا في الحافظة ويرسل Ctrl+V للصقه في النافذة النشطة. لا ينتظر اكتمال اللصق، لذا انتظر قليلًا باستخدام UtilityWait قبل ClipboardRestore.

المعلمات

• text: Text — النص المراد لصقه.

القيمة المُرجَعة

true إذا تم تعيين الحافظة وإرسال Ctrl+V؛ false إذا كانت الحافظة مشغولة أو حظر Windows ضغطات المفاتيح.

٢ مثالان: ملء قالب ولصقه, تحويل النص المحدد إلى أحرف كبيرة

ClipboardRestore

ClipboardRestore() → Bool

يعيد محتوى الحافظة الذي حفظه آخر استدعاء لـ ClipboardSave في تشغيل البرنامج النصي هذا، بكل التنسيقات. إذا لم يسبقه استدعاء لـ ClipboardSave في هذا التشغيل، فإنه يُفرغ الحافظة.

المعلمات

لا توجد معلمات.

القيمة المُرجَعة

true إذا أُعيد كل ما تم حفظه؛ false إذا كانت الحافظة مشغولة أو تعذّرت استعادة أحد التنسيقات.

٥ أمثلة: ملء قالب ولصقه, البحث في الويب عن النص المحدد, تحويل النص المحدد إلى أحرف كبيرة, البحث في الويب عن التحديد, السماح لإجراء واحد فقط بتشغيل مقطع في كل مرة

ClipboardSave

ClipboardSave() → Bool

يحفظ نسخة من كل ما في الحافظة، بكل التنسيقات، حتى يتمكن ClipboardRestore من إعادتها لاحقًا في تشغيل البرنامج النصي نفسه. يحل الاستدعاء الثاني محل النسخة المحفوظة.

المعلمات

لا توجد معلمات.

القيمة المُرجَعة

true إذا تمت قراءة الحافظة؛ false إذا أبقاها برنامج آخر مشغولة.

٥ أمثلة: ملء قالب ولصقه, البحث في الويب عن النص المحدد, تحويل النص المحدد إلى أحرف كبيرة, البحث في الويب عن التحديد, السماح لإجراء واحد فقط بتشغيل مقطع في كل مرة

ClipboardSaveImage

ClipboardSaveImage(path: Text) → Bool

يحفظ الصورة الموجودة في الحافظة، مثل لقطة شاشة مأخوذة بمفتاح Print Screen، في ملف بالتنسيق الذي يحدده امتداد الملف. يُستبدل الملف الموجود.

المعلمات

• path: Text — المسار الكامل للملف المراد كتابته، منتهيًا بـ .bmp أو .png أو .jpg أو .jpeg. أي امتداد آخر يوقف البرنامج النصي بخطأ.

القيمة المُرجَعة

true إذا تمت كتابة الملف؛ false إذا لم تحتوِ الحافظة على صورة أو تعذّرت كتابة الملف.

١ مثال: حفظ صورة منسوخة في ملف

ClipboardSetHtml

ClipboardSetHtml(html: Text) → Bool

يضع جزء HTML في الحافظة بدلًا من المحتوى الحالي، بحيث يحتفظ اللصق في رسالة بريد إلكتروني أو معالج نصوص بالتنسيق. تُضاف أيضًا نسخة بنص عادي بعد إزالة العلامات، للبرامج التي لا تلصق إلا النص.

المعلمات

• html: Text — جزء HTML المراد وضعه، مثل نص <b>bold</b>. لا تُضف عنوان HTML الخاص بالحافظة؛ فهو يُضاف تلقائيًا.

القيمة المُرجَعة

true إذا تم وضع HTML ونسخته بالنص العادي في الحافظة؛ false إذا كانت الحافظة مشغولة.

ClipboardSetRtf

ClipboardSetRtf(rtf: Text) → Bool

يضع نصًا منسَّقًا (RTF) في الحافظة بدلًا من المحتوى الحالي، بحيث يحتفظ اللصق في WordPad أو Word أو Outlook بالتنسيق. تُضاف أيضًا نسخة بنص عادي من الكلمات، للبرامج التي لا تلصق إلا النص.

المعلمات

• rtf: Text — مستند RTF كامل كنص. يمكن كتابة أي حرف مباشرة؛ إذ تُكتب الأحرف الواقعة خارج ASCII العادي كتسلسلات هروب Unicode في RTF تلقائيًا.

القيمة المُرجَعة

true إذا تم وضع RTF ونسخته بالنص العادي في الحافظة؛ false إذا كانت الحافظة مشغولة.

ClipboardSetText

ClipboardSetText(text: Text) → Bool · بسيط

يضع نصًا في الحافظة بدلًا من أي محتوى موجود فيها، جاهزًا للصق في أي برنامج.

المعلمات

• text: Text — النص المراد وضعه في الحافظة.

القيمة المُرجَعة

true إذا تم وضع النص في الحافظة؛ false إذا أبقى برنامج آخر الحافظة مشغولة.

٢ مثالان: استخراج قيمة من نص منسوخ باستخدام تعبير نمطي, ضم أسطر الحافظة في سطر واحد

Context

ContextGetActionName

ContextGetActionName() → Text

يُرجع اسم الإجراء قيد التشغيل. يُرجع الحدث العام Global_Event_ متبوعًا بمعرّف الحدث، مثل Global_Event_release.

المعلمات

لا توجد معلمات.

القيمة المُرجَعة

اسم الإجراء، أو اسم يبدأ بـ Global_Event_ لحدث عام، أو نص فارغ في البرنامج النصي لمؤقت أو لمراقبة مجلد أو لمراقب تسلسلي.

١ مثال: كل ما يعرفه سياق المشغِّل

ContextGetApplicationName

ContextGetApplicationName() → Text

يُرجع اسم مجموعة التطبيقات التي يعمل إجراؤها، لإجراء شغّلته إيماءة أو مفتاح اختصار أو توسيع نص.

المعلمات

لا توجد معلمات.

القيمة المُرجَعة

اسم مجموعة التطبيقات (عادةً Global للمجموعة العامة)، أو نص فارغ لحدث عام أو لبرنامج نصي لمؤقت أو لمراقبة مجلد أو لمراقب تسلسلي.

٤ أمثلة: ملء قالب ولصقه, كل ما يعرفه سياق المشغِّل, تمرير رسم غير متعرَّف عليه, الإلحاق بملف سجل

ContextGetBoundingBoxHeight

ContextGetBoundingBoxHeight() → Integer

يُرجع ارتفاع المستطيل المحيط بالإيماءة المرسومة كاملةً، بالبكسل. خارج الإيماءة يُرجع 0.

المعلمات

لا توجد معلمات.

القيمة المُرجَعة

الارتفاع بالبكسل، أو 0 خارج الإيماءة.

٢ مثالان: كل ما يعرفه سياق المشغِّل, لقطة شاشة للمنطقة التي أحطتها بدائرة

ContextGetBoundingBoxWidth

ContextGetBoundingBoxWidth() → Integer

يُرجع عرض المستطيل المحيط بالإيماءة المرسومة كاملةً، بالبكسل. خارج الإيماءة يُرجع 0.

المعلمات

لا توجد معلمات.

القيمة المُرجَعة

العرض بالبكسل، أو 0 خارج الإيماءة.

٢ مثالان: كل ما يعرفه سياق المشغِّل, لقطة شاشة للمنطقة التي أحطتها بدائرة

ContextGetBoundingBoxX

ContextGetBoundingBoxX() → Integer

يُرجع الحافة اليسرى للمستطيل المحيط بالإيماءة المرسومة كاملةً، بوحدات بكسل الشاشة الظاهرية. خارج الإيماءة يُرجع 0.

المعلمات

لا توجد معلمات.

القيمة المُرجَعة

الحافة اليسرى بوحدات بكسل الشاشة الظاهرية، أو 0 خارج الإيماءة.

٢ مثالان: كل ما يعرفه سياق المشغِّل, لقطة شاشة للمنطقة التي أحطتها بدائرة

ContextGetBoundingBoxY

ContextGetBoundingBoxY() → Integer

يُرجع الحافة العلوية للمستطيل المحيط بالإيماءة المرسومة كاملةً، بوحدات بكسل الشاشة الظاهرية. خارج الإيماءة يُرجع 0.

المعلمات

لا توجد معلمات.

القيمة المُرجَعة

الحافة العلوية بوحدات بكسل الشاشة الظاهرية، أو 0 خارج الإيماءة.

٢ مثالان: كل ما يعرفه سياق المشغِّل, لقطة شاشة للمنطقة التي أحطتها بدائرة

ContextGetButtonState

ContextGetButtonState() → Text

يُرجع ما إذا كان حدث زر الماوس العام قد انطلق عند ضغط الزر أو عند تحريره. يحصل على قيمة البرنامج النصي لحدث زر الماوس العام فقط.

المعلمات

لا توجد معلمات.

القيمة المُرجَعة

'down' للضغط، و'up' للتحرير، أو نص فارغ لأي مشغِّل آخر، بما في ذلك الإيماءة.

ContextGetControl

ContextGetControl() → Window

يُرجع عنصر التحكم الدقيق الذي استهدفه المشغِّل، مثل مربع تحرير أسفل الإيماءة أو الماوس، أو النافذة التي عليها التركيز لمفتاح اختصار أو توسيع نص. استخدم ContextGetWindow للحصول على نافذة التطبيق الخاصة به.

المعلمات

لا توجد معلمات.

القيمة المُرجَعة

عنصر التحكم كقيمة Window، أو نافذة فارغة عندما لا تكون للمشغِّل نافذة، كما في البرنامج النصي لمؤقت أو لمراقبة مجلد أو لمراقب تسلسلي أو في البرنامج النصي Load.

ContextGetGestureName

ContextGetGestureName() → Text

يُرجع اسم الإيماءة التي رُسمت لتشغيل هذا الإجراء. هذا هو اسم الإيماءة نفسها، لا اسم الإجراء؛ راجع ContextGetActionName.

المعلمات

لا توجد معلمات.

القيمة المُرجَعة

اسم الإيماءة، أو نص فارغ خارج الإيماءة.

٢ مثالان: كل ما يعرفه سياق المشغِّل, الإلحاق بملف سجل

ContextGetPointCount

ContextGetPointCount() → Integer

يُرجع عدد مواضع المؤشر التي سُجّلت على طول الإيماءة المرسومة. اقرأ كل موضع باستخدام ContextGetPointX وContextGetPointY.

المعلمات

لا توجد معلمات.

القيمة المُرجَعة

عدد النقاط، أو 0 خارج الإيماءة.

٣ أمثلة: طول خط الإيماءة, كل ما يعرفه سياق المشغِّل, في أي اتجاه سار الخط؟

ContextGetPointX

ContextGetPointX(index: Integer) → Integer

يُرجع الموضع الأفقي على الشاشة لنقطة واحدة مسجَّلة من الإيماءة المرسومة، بوحدات بكسل الشاشة الظاهرية.

المعلمات

• index: Integer — رقم النقطة بدءًا من الصفر، من 0 إلى ContextGetPointCount() ناقص 1. النقطة 0 هي حيث بدأت الإيماءة.

القيمة المُرجَعة

الإحداثي x، أو 0 إذا كان index خارج النطاق أو لم تشغّل الإجراءَ إيماءةٌ.

٢ مثالان: طول خط الإيماءة, في أي اتجاه سار الخط؟

ContextGetPointY

ContextGetPointY(index: Integer) → Integer

يُرجع الموضع الرأسي على الشاشة لنقطة واحدة مسجَّلة من الإيماءة المرسومة، بوحدات بكسل الشاشة الظاهرية.

المعلمات

• index: Integer — رقم النقطة بدءًا من الصفر، من 0 إلى ContextGetPointCount() ناقص 1. النقطة 0 هي حيث بدأت الإيماءة.

القيمة المُرجَعة

الإحداثي y، أو 0 إذا كان index خارج النطاق أو لم تشغّل الإجراءَ إيماءةٌ.

٢ مثالان: طول خط الإيماءة, في أي اتجاه سار الخط؟

ContextGetSerialMonitorName

ContextGetSerialMonitorName() → Text

يُرجع اسم المراقب التسلسلي الذي بدأ السطرُ المستلَم منه هذا البرنامج النصي، كما مُرِّر إلى SerialMonitorCreate. يحصل على قيمة البرنامج النصي للمراقب التسلسلي فقط.

المعلمات

لا توجد معلمات.

القيمة المُرجَعة

اسم المراقب، أو نص فارغ لأي مشغِّل آخر.

ContextGetSerialPortName

ContextGetSerialPortName() → Text

يُرجع منفذ COM، مثل COM3، الذي وصل عليه السطر المستلَم. يحصل على قيمة البرنامج النصي للمراقب التسلسلي فقط.

المعلمات

لا توجد معلمات.

القيمة المُرجَعة

اسم المنفذ، أو نص فارغ لأي مشغِّل آخر.

ContextGetSerialTextLine

ContextGetSerialTextLine() → Text

يُرجع سطر النص الذي وصل على المنفذ التسلسلي وبدأ هذا البرنامج النصي، مثل قراءة مستشعر أرسلها Arduino باستخدام Serial.println. تتم إزالة نهاية السطر.

المعلمات

لا توجد معلمات.

القيمة المُرجَعة

السطر المستلَم بدون فاصل نهايته، أو نص فارغ لأي مشغِّل آخر.

٢ مثالان: ربط أزرار جهاز تسلسلي بمفاتيح الوسائط, تحويل مقبض Arduino إلى عنصر تحكم في مستوى الصوت

ContextGetStrokeButton

ContextGetStrokeButton() → Integer

يُرجع زر الماوس الذي رسم الإيماءة، أو الذي أطلق حدث زر الماوس العام، كثابت MouseButton: MouseButton.Primary أو MouseButton.Secondary للزرين اللذين يعاملهما Windows كنقرة يسرى ونقرة يمنى، بعد أي تبديل بين الزر الأساسي والثانوي، وإلا MouseButton.Middle أو MouseButton.X1 أو MouseButton.X2. مرِّره إلى MouseClick أو MouseButtonDown للضغط على الزر نفسه.

المعلمات

لا توجد معلمات.

القيمة المُرجَعة

قيمة MouseButton مثل MouseButton.Secondary، أو -1 لأي مشغِّل آخر.

٢ مثالان: كل ما يعرفه سياق المشغِّل, التفرع حسب زر الخط

ContextGetWatchAction

ContextGetWatchAction() → Text

يُرجع ما حدث في المجلد المراقَب وأدى إلى بدء هذا البرنامج النصي: 'created' أو 'deleted' أو 'modified' أو 'renamed-old-name' أو 'renamed-new-name' أو 'overflow'.

المعلمات

لا توجد معلمات.

القيمة المُرجَعة

نوع التغيير، أو نص فارغ لأي مشغِّل آخر. تعني 'overflow' أن عددًا كبيرًا جدًا من التغييرات وصل دفعة واحدة وأنه يجب فحص المجلد مرة أخرى.

١ مثال: مراقبة مجلد

ContextGetWatchName

ContextGetWatchName() → Text

يُرجع اسم مراقبة المجلد التي بدأت هذا البرنامج النصي، كما مُرِّر إلى FolderWatchCreate. يحصل على قيمة البرنامج النصي لمراقبة المجلد فقط.

المعلمات

لا توجد معلمات.

القيمة المُرجَعة

اسم المراقبة، أو نص فارغ لأي مشغِّل آخر.

ContextGetWatchPath

ContextGetWatchPath() → Text

يُرجع مسار الملف أو المجلد الذي تغيّر وبدأ هذا البرنامج النصي لمراقبة المجلد، نسبةً إلى المجلد المراقَب.

المعلمات

لا توجد معلمات.

القيمة المُرجَعة

مسار العنصر الذي تغيّر نسبةً إلى المجلد المراقَب، أو نص فارغ لتغيير من نوع 'overflow' أو لأي مشغِّل آخر.

١ مثال: مراقبة مجلد

ContextGetWindow

ContextGetWindow() → Window

يُرجع نافذة التطبيق التي استهدفها المشغِّل: النافذة ذات المستوى الأعلى المحيطة بعنصر التحكم الموجود أسفل الإيماءة أو الماوس، أو المحيطة بعنصر التحكم الذي عليه التركيز لمفتاح اختصار أو توسيع نص.

المعلمات

لا توجد معلمات.

القيمة المُرجَعة

النافذة، أو نافذة فارغة عندما لا تكون للمشغِّل نافذة، كما في البرنامج النصي لمؤقت أو لمراقبة مجلد أو لمراقب تسلسلي أو في البرنامج النصي Load.

١٦ مثالًا: إيماءة واحدة، عدة خيارات, تبديل التكبير لنافذة الإيماءة, تثبيت نافذة في المقدمة, التنقل بين مستويات شفافية النافذة, محاذاة نافذة إلى خلية في شبكة 3×2 أسفل المؤشر, نقل نافذة إلى الشاشة التالية, تذكّر موضع النافذة واستعادته, فحص عناصر التحكم التابعة للنافذة, إخفاء نافذة في منطقة الإعلامات, كل ما يعرفه سياق المشغِّل, التفرع حسب زر الخط, حصر المؤشر داخل نافذة لمدة 5 ثوانٍ, تغيير السلوك أثناء الضغط على Ctrl, قائمة محفوظة في Storage, إرسال نافذة إلى شاشة محددة, المقتطفات كدوال قابلة لإعادة الاستخدام

ContextRelayGesture

ContextRelayGesture() → Bool

يعيد تشغيل الإيماءة المرسومة كسحب حقيقي بالماوس بالزر نفسه وعلى المسار نفسه، فيستقبله التطبيق الموجود أسفلها، مثلًا لتحديد نص. يُحجز الإدخال الحقيقي أثناء السحب.

المعلمات

لا توجد معلمات.

القيمة المُرجَعة

true إذا أُرسل السحب كاملًا؛ false خارج الإيماءة أو إذا رفض Windows جزءًا من الإدخال.

١ مثال: تمرير رسم غير متعرَّف عليه

DateTime

DateTimeFormat

DateTimeFormat(iso: Text, style: Integer) → Text · بسيط

ينسّق تاريخًا ووقتًا كنص مقروء بالتنسيق الإقليمي للمستخدم، أو كقيمة FileStamp قابلة للفرز. يُحوَّل الوقت الذي يحتوي على Z أو على إزاحة UTC إلى التوقيت المحلي أولًا.

المعلمات

• iso: Text — تاريخ ووقت بتنسيق ISO 8601، كما يُرجعه DateTimeGetNow (2026-10-05T14:05:09-04:00). التاريخ وحده يعني منتصف الليل؛ وبدون Z أو إزاحة يُعتبر توقيتًا محليًا. السنوات من 1601 إلى 9999.
• style: Integer — ثابت DateTimeStyle، مثل DateTimeStyle.ShortDate أو DateTimeStyle.LongDateTime أو DateTimeStyle.FileStamp. أي قيمة أخرى توقف الإجراء بخطأ.

القيمة المُرجَعة

النص المنسَّق، مثل 20261005-140509 لـ DateTimeStyle.FileStamp، أو نص فارغ إذا كانت قيمة iso فارغة. النص الذي ليس بتنسيق ISO 8601 يوقف الإجراء بخطأ.

١ مثال: تاريخ اليوم، واسم ملف مختوم بالوقت

DateTimeGetNow

DateTimeGetNow() → Text · بسيط

يُرجع التاريخ والوقت المحليين الحاليين كنص ISO 8601، بدقة الثانية، مع إزاحة UTC. مرِّره إلى DateTimeFormat أو DateTimeGetPart.

المعلمات

لا توجد معلمات.

القيمة المُرجَعة

نص مثل 2026-10-05T14:05:09-04:00، أو نص فارغ إذا لم يتمكن Windows من الإبلاغ عن المنطقة الزمنية.

١ مثال: تاريخ اليوم، واسم ملف مختوم بالوقت

DateTimeGetPart

DateTimeGetPart(iso: Text, part: Integer) → Integer

يُرجع جزءًا واحدًا من تاريخ ووقت كرقم: السنة أو الشهر أو اليوم أو الساعة أو الدقيقة أو الثانية أو يوم الأسبوع، بالتوقيت المحلي.

المعلمات

• iso: Text — تاريخ ووقت بتنسيق ISO 8601، كما يُرجعه DateTimeGetNow. يُحوَّل الوقت الذي يحتوي على Z أو على إزاحة UTC إلى التوقيت المحلي؛ وبدونهما يُعتبر توقيتًا محليًا.
• part: Integer — ثابت DateTimePart، مثل DateTimePart.Hour أو DateTimePart.Weekday. أي قيمة أخرى توقف الإجراء بخطأ.

القيمة المُرجَعة

قيمة الجزء: الشهر من 1 إلى 12، والساعة من 0 إلى 23، ويوم الأسبوع من 1 (الاثنين) إلى 7 (الأحد). -1 إذا كانت قيمة iso فارغة. النص الذي ليس بتنسيق ISO 8601 يوقف الإجراء بخطأ.

١ مثال: تاريخ اليوم، واسم ملف مختوم بالوقت

Display

DisplayGetMonitorDpiFromPoint

DisplayGetMonitorDpiFromPoint(x: Integer, y: Integer) → Integer

يُرجع قيمة DPI التي يستخدمها Windows حاليًا للشاشة التي تحتوي على نقطة على الشاشة. النقطة الواقعة خارج كل الشاشات تستخدم أقرب شاشة.

المعلمات

• x: Integer — الموضع الأفقي على الشاشة، بالبكسل.
• y: Integer — الموضع الرأسي على الشاشة، بالبكسل.

القيمة المُرجَعة

قيمة DPI، مثل 96 عند التحجيم بنسبة 100 بالمائة أو 144 عند 150 بالمائة. إذا لم يتمكن Windows من الإبلاغ عنها، فقيمة DPI الخاصة بالنظام.

DisplayGetPixelColorFromPoint

DisplayGetPixelColorFromPoint(x: Integer, y: Integer) → Integer

يُرجع لون بكسل الشاشة عند نقطة ما، كما يظهر حاليًا على الشاشة.

المعلمات

• x: Integer — الموضع الأفقي للبكسل على الشاشة، بالبكسل.
• y: Integer — الموضع الرأسي للبكسل على الشاشة، بالبكسل.

القيمة المُرجَعة

اللون كقيمة Integer محزومة بالصيغة 0xRRGGBB (الأحمر في البايت الأعلى، والأزرق في البايت الأدنى)، أو -1 إذا كانت النقطة خارج كل الشاشات أو تعذّرت قراءة الشاشة.

١ مثال: قراءة لون البكسل أسفل المؤشر

DisplayMonitorEnumeratedAll

DisplayMonitorEnumeratedAll() → Integer

يلتقط لقطة لكل الشاشات المتصلة، مرتبةً من اليسار إلى اليمين ثم من الأعلى إلى الأسفل، لتقرأها الدوال المضمَّنة DisplayMonitorGetEnumerated حسب الفهرس. استدعِه مرة أخرى بعد تغيّر الشاشات.

المعلمات

لا توجد معلمات.

القيمة المُرجَعة

عدد الشاشات في اللقطة. تتراوح الفهارس الصالحة من 0 إلى هذا العدد ناقص 1.

٢ مثالان: سرد الشاشات, إرسال نافذة إلى شاشة محددة

DisplayMonitorExistsByName

DisplayMonitorExistsByName(name: Text) → Bool

يتحقق مما إذا كانت شاشة محفوظة بالاسم متصلة الآن. استخدمه قبل الدوال المضمَّنة FromName الخاصة بالمستطيل، التي تُرجع 0 لكل من الشاشة المفقودة والإحداثي 0 الحقيقي.

المعلمات

• name: Text — مسار جهاز الشاشة (الخيار الموثوق، من DisplayMonitorGetDevicePathFromPoint) أو اسم طراز مثل DELL U2720Q. غير حساس لحالة الأحرف؛ وتتقدم المطابقة التامة لمسار الجهاز على اسم الطراز.

القيمة المُرجَعة

true إذا تطابقت شاشة متصلة مع الاسم؛ false إذا لم تتطابق أي شاشة أو كانت قيمة name فارغة.

DisplayMonitorGetDevicePathFromPoint

DisplayMonitorGetDevicePathFromPoint(x: Integer, y: Integer) → Text

يُرجع مسار جهاز الشاشة التي تحتوي على نقطة على الشاشة: اسم فريد يمكن حفظه وتمريره لاحقًا إلى الدوال المضمَّنة FromName. يتغير إذا نُقلت الشاشة إلى منفذ فيديو آخر.

المعلمات

• x: Integer — الموضع الأفقي على الشاشة، بالبكسل.
• y: Integer — الموضع الرأسي على الشاشة، بالبكسل.

القيمة المُرجَعة

مسار الجهاز، أو نص فارغ إذا لم يتمكن Windows من التعرف على الشاشة. النقطة الواقعة خارج كل الشاشات تستخدم أقرب شاشة.

DisplayMonitorGetEnumeratedDevicePathAt

DisplayMonitorGetEnumeratedDevicePathAt(index: Integer) → Text

يُرجع مسار الجهاز، وهو اسم فريد يمكن حفظه، لشاشة في آخر لقطة من DisplayMonitorEnumeratedAll.

المعلمات

• index: Integer — موضع الشاشة بدءًا من الصفر في آخر لقطة من DisplayMonitorEnumeratedAll (من اليسار إلى اليمين، ثم من الأعلى إلى الأسفل).

القيمة المُرجَعة

مسار الجهاز، أو نص فارغ إذا كان index خارج النطاق أو تغيّرت الشاشات منذ اللقطة.

DisplayMonitorGetEnumeratedDpiAt

DisplayMonitorGetEnumeratedDpiAt(index: Integer) → Integer

يُرجع قيمة DPI لشاشة في آخر لقطة من DisplayMonitorEnumeratedAll، كما كانت عند التقاط اللقطة.

المعلمات

• index: Integer — موضع الشاشة بدءًا من الصفر في آخر لقطة من DisplayMonitorEnumeratedAll (من اليسار إلى اليمين، ثم من الأعلى إلى الأسفل).

القيمة المُرجَعة

قيمة DPI، مثل 96 عند التحجيم بنسبة 100 بالمائة أو 144 عند 150 بالمائة، أو 0 إذا كان index خارج النطاق.

١ مثال: سرد الشاشات

DisplayMonitorGetEnumeratedFriendlyNameAt

DisplayMonitorGetEnumeratedFriendlyNameAt(index: Integer) → Text

يُرجع اسم الطراز الذي تُبلغ عنه الشاشة، مثل DELL U2720Q، لشاشة في آخر لقطة من DisplayMonitorEnumeratedAll. تُبلغ شاشتان متطابقتان عن الاسم نفسه.

المعلمات

• index: Integer — موضع الشاشة بدءًا من الصفر في آخر لقطة من DisplayMonitorEnumeratedAll (من اليسار إلى اليمين، ثم من الأعلى إلى الأسفل).

القيمة المُرجَعة

اسم الطراز، أو نص فارغ إذا كان index خارج النطاق، أو لم تُبلغ الشاشة عن اسم (أمر شائع في الشاشات المدمجة في أجهزة الكمبيوتر المحمولة)، أو تغيّرت الشاشات منذ اللقطة.

١ مثال: سرد الشاشات

DisplayMonitorGetEnumeratedHeightAt

DisplayMonitorGetEnumeratedHeightAt(index: Integer, workArea: Bool) → Integer

يُرجع ارتفاع شاشة في آخر لقطة من DisplayMonitorEnumeratedAll، سواء لمساحتها الكاملة أو لمنطقة العمل فيها، كما كان عند التقاط اللقطة.

المعلمات

• index: Integer — موضع الشاشة بدءًا من الصفر في آخر لقطة من DisplayMonitorEnumeratedAll (من اليسار إلى اليمين، ثم من الأعلى إلى الأسفل).
• workArea: Bool — true لمنطقة العمل، التي تستثني شريط المهام وأشرطة الأدوات المرساة؛ false للشاشة كاملةً.

القيمة المُرجَعة

الارتفاع بالبكسل، أو 0 إذا كان index خارج النطاق.

١ مثال: سرد الشاشات

DisplayMonitorGetEnumeratedWidthAt

DisplayMonitorGetEnumeratedWidthAt(index: Integer, workArea: Bool) → Integer

يُرجع عرض شاشة في آخر لقطة من DisplayMonitorEnumeratedAll، سواء لمساحتها الكاملة أو لمنطقة العمل فيها، كما كان عند التقاط اللقطة.

المعلمات

• index: Integer — موضع الشاشة بدءًا من الصفر في آخر لقطة من DisplayMonitorEnumeratedAll (من اليسار إلى اليمين، ثم من الأعلى إلى الأسفل).
• workArea: Bool — true لمنطقة العمل، التي تستثني شريط المهام وأشرطة الأدوات المرساة؛ false للشاشة كاملةً.

القيمة المُرجَعة

العرض بالبكسل، أو 0 إذا كان index خارج النطاق.

١ مثال: سرد الشاشات

DisplayMonitorGetEnumeratedXAt

DisplayMonitorGetEnumeratedXAt(index: Integer, workArea: Bool) → Integer

يُرجع الحافة اليسرى لشاشة في آخر لقطة من DisplayMonitorEnumeratedAll، سواء لمساحتها الكاملة أو لمنطقة العمل فيها، كما كانت عند التقاط اللقطة.

المعلمات

• index: Integer — موضع الشاشة بدءًا من الصفر في آخر لقطة من DisplayMonitorEnumeratedAll (من اليسار إلى اليمين، ثم من الأعلى إلى الأسفل).
• workArea: Bool — true لمنطقة العمل، التي تستثني شريط المهام وأشرطة الأدوات المرساة؛ false للشاشة كاملةً.

القيمة المُرجَعة

الحافة اليسرى بوحدات بكسل الشاشة (سالبة لشاشة تقع يسار الشاشة الرئيسية)، أو 0 إذا كان index خارج النطاق. القيمة 0 قد تكون أيضًا حافة حقيقية، لذا تحقق من index مقابل عدد الشاشات.

DisplayMonitorGetEnumeratedYAt

DisplayMonitorGetEnumeratedYAt(index: Integer, workArea: Bool) → Integer

يُرجع الحافة العلوية لشاشة في آخر لقطة من DisplayMonitorEnumeratedAll، سواء لمساحتها الكاملة أو لمنطقة العمل فيها، كما كانت عند التقاط اللقطة.

المعلمات

• index: Integer — موضع الشاشة بدءًا من الصفر في آخر لقطة من DisplayMonitorEnumeratedAll (من اليسار إلى اليمين، ثم من الأعلى إلى الأسفل).
• workArea: Bool — true لمنطقة العمل، التي تستثني شريط المهام وأشرطة الأدوات المرساة؛ false للشاشة كاملةً.

القيمة المُرجَعة

الحافة العلوية بوحدات بكسل الشاشة (سالبة لشاشة تقع أعلى الشاشة الرئيسية)، أو 0 إذا كان index خارج النطاق. القيمة 0 قد تكون أيضًا حافة حقيقية، لذا تحقق من index مقابل عدد الشاشات.

DisplayMonitorGetFriendlyNameFromPoint

DisplayMonitorGetFriendlyNameFromPoint(x: Integer, y: Integer) → Text

يُرجع اسم الطراز، مثل DELL U2720Q، للشاشة التي تحتوي على نقطة على الشاشة. مقروء لكنه غير فريد: تُبلغ شاشتان متطابقتان عن الاسم نفسه.

المعلمات

• x: Integer — الموضع الأفقي على الشاشة، بالبكسل.
• y: Integer — الموضع الرأسي على الشاشة، بالبكسل.

القيمة المُرجَعة

اسم الطراز، أو نص فارغ إذا لم تُبلغ الشاشة عن أي اسم (أمر شائع في الشاشات المدمجة في أجهزة الكمبيوتر المحمولة). النقطة الواقعة خارج كل الشاشات تستخدم أقرب شاشة.

DisplayMonitorGetRectHeightFromName

DisplayMonitorGetRectHeightFromName(name: Text, workArea: Bool) → Integer

يُرجع ارتفاع شاشة متصلة يُعثر عليها بمسار جهازها المحفوظ أو باسم طرازها، سواء لمساحتها الكاملة أو لمنطقة العمل فيها.

المعلمات

• name: Text — مسار جهاز الشاشة (الخيار الموثوق) أو اسم طراز مثل DELL U2720Q. غير حساس لحالة الأحرف؛ وتتقدم المطابقة التامة لمسار الجهاز على اسم الطراز.
• workArea: Bool — true لمنطقة العمل، التي تستثني شريط المهام وأشرطة الأدوات المرساة؛ false للشاشة كاملةً.

القيمة المُرجَعة

الارتفاع بالبكسل، أو 0 إذا لم تتطابق أي شاشة متصلة مع الاسم.

DisplayMonitorGetRectHeightFromPoint

DisplayMonitorGetRectHeightFromPoint(x: Integer, y: Integer, workArea: Bool) → Integer

يُرجع ارتفاع الشاشة التي تحتوي على نقطة على الشاشة، سواء لمساحتها الكاملة أو لمنطقة العمل فيها. النقطة الواقعة خارج كل الشاشات تستخدم أقرب شاشة.

المعلمات

• x: Integer — الموضع الأفقي على الشاشة، بالبكسل.
• y: Integer — الموضع الرأسي على الشاشة، بالبكسل.
• workArea: Bool — true لمنطقة العمل، التي تستثني شريط المهام وأشرطة الأدوات المرساة؛ false للشاشة كاملةً.

القيمة المُرجَعة

الارتفاع بالبكسل.

٢ مثالان: محاذاة النافذة النشطة إلى النصف الأيسر من شاشتها, محاذاة نافذة إلى خلية في شبكة 3×2 أسفل المؤشر

DisplayMonitorGetRectWidthFromName

DisplayMonitorGetRectWidthFromName(name: Text, workArea: Bool) → Integer

يُرجع عرض شاشة متصلة يُعثر عليها بمسار جهازها المحفوظ أو باسم طرازها، سواء لمساحتها الكاملة أو لمنطقة العمل فيها.

المعلمات

• name: Text — مسار جهاز الشاشة (الخيار الموثوق) أو اسم طراز مثل DELL U2720Q. غير حساس لحالة الأحرف؛ وتتقدم المطابقة التامة لمسار الجهاز على اسم الطراز.
• workArea: Bool — true لمنطقة العمل، التي تستثني شريط المهام وأشرطة الأدوات المرساة؛ false للشاشة كاملةً.

القيمة المُرجَعة

العرض بالبكسل، أو 0 إذا لم تتطابق أي شاشة متصلة مع الاسم.

DisplayMonitorGetRectWidthFromPoint

DisplayMonitorGetRectWidthFromPoint(x: Integer, y: Integer, workArea: Bool) → Integer

يُرجع عرض الشاشة التي تحتوي على نقطة على الشاشة، سواء لمساحتها الكاملة أو لمنطقة العمل فيها. النقطة الواقعة خارج كل الشاشات تستخدم أقرب شاشة.

المعلمات

• x: Integer — الموضع الأفقي على الشاشة، بالبكسل.
• y: Integer — الموضع الرأسي على الشاشة، بالبكسل.
• workArea: Bool — true لمنطقة العمل، التي تستثني شريط المهام وأشرطة الأدوات المرساة؛ false للشاشة كاملةً.

القيمة المُرجَعة

العرض بالبكسل.

٣ أمثلة: سلسلة else-if, محاذاة النافذة النشطة إلى النصف الأيسر من شاشتها, محاذاة نافذة إلى خلية في شبكة 3×2 أسفل المؤشر

DisplayMonitorGetRectXFromName

DisplayMonitorGetRectXFromName(name: Text, workArea: Bool) → Integer

يُرجع الحافة اليسرى لشاشة متصلة يُعثر عليها بمسار جهازها المحفوظ أو باسم طرازها، سواء لمساحتها الكاملة أو لمنطقة العمل فيها.

المعلمات

• name: Text — مسار جهاز الشاشة (الخيار الموثوق) أو اسم طراز مثل DELL U2720Q. غير حساس لحالة الأحرف؛ وتتقدم المطابقة التامة لمسار الجهاز على اسم الطراز.
• workArea: Bool — true لمنطقة العمل، التي تستثني شريط المهام وأشرطة الأدوات المرساة؛ false للشاشة كاملةً.

القيمة المُرجَعة

الحافة اليسرى بوحدات بكسل الشاشة، أو 0 إذا لم تتطابق أي شاشة متصلة مع الاسم. القيمة 0 قد تكون أيضًا حافة حقيقية، لذا تحقق أولًا باستخدام DisplayMonitorExistsByName.

DisplayMonitorGetRectXFromPoint

DisplayMonitorGetRectXFromPoint(x: Integer, y: Integer, workArea: Bool) → Integer

يُرجع الحافة اليسرى للشاشة التي تحتوي على نقطة على الشاشة، سواء لمساحتها الكاملة أو لمنطقة العمل فيها. النقطة الواقعة خارج كل الشاشات تستخدم أقرب شاشة.

المعلمات

• x: Integer — الموضع الأفقي على الشاشة، بالبكسل.
• y: Integer — الموضع الرأسي على الشاشة، بالبكسل.
• workArea: Bool — true لمنطقة العمل، التي تستثني شريط المهام وأشرطة الأدوات المرساة؛ false للشاشة كاملةً.

القيمة المُرجَعة

الحافة اليسرى بوحدات بكسل الشاشة؛ سالبة لشاشة تقع يسار الشاشة الرئيسية.

٣ أمثلة: سلسلة else-if, محاذاة النافذة النشطة إلى النصف الأيسر من شاشتها, محاذاة نافذة إلى خلية في شبكة 3×2 أسفل المؤشر

DisplayMonitorGetRectYFromName

DisplayMonitorGetRectYFromName(name: Text, workArea: Bool) → Integer

يُرجع الحافة العلوية لشاشة متصلة يُعثر عليها بمسار جهازها المحفوظ أو باسم طرازها، سواء لمساحتها الكاملة أو لمنطقة العمل فيها.

المعلمات

• name: Text — مسار جهاز الشاشة (الخيار الموثوق) أو اسم طراز مثل DELL U2720Q. غير حساس لحالة الأحرف؛ وتتقدم المطابقة التامة لمسار الجهاز على اسم الطراز.
• workArea: Bool — true لمنطقة العمل، التي تستثني شريط المهام وأشرطة الأدوات المرساة؛ false للشاشة كاملةً.

القيمة المُرجَعة

الحافة العلوية بوحدات بكسل الشاشة، أو 0 إذا لم تتطابق أي شاشة متصلة مع الاسم. القيمة 0 قد تكون أيضًا حافة حقيقية، لذا تحقق أولًا باستخدام DisplayMonitorExistsByName.

DisplayMonitorGetRectYFromPoint

DisplayMonitorGetRectYFromPoint(x: Integer, y: Integer, workArea: Bool) → Integer

يُرجع الحافة العلوية للشاشة التي تحتوي على نقطة على الشاشة، سواء لمساحتها الكاملة أو لمنطقة العمل فيها. النقطة الواقعة خارج كل الشاشات تستخدم أقرب شاشة.

المعلمات

• x: Integer — الموضع الأفقي على الشاشة، بالبكسل.
• y: Integer — الموضع الرأسي على الشاشة، بالبكسل.
• workArea: Bool — true لمنطقة العمل، التي تستثني شريط المهام وأشرطة الأدوات المرساة؛ false للشاشة كاملةً.

القيمة المُرجَعة

الحافة العلوية بوحدات بكسل الشاشة؛ سالبة لشاشة تقع أعلى الشاشة الرئيسية.

٢ مثالان: محاذاة النافذة النشطة إلى النصف الأيسر من شاشتها, محاذاة نافذة إلى خلية في شبكة 3×2 أسفل المؤشر

Engine

EngineConsumePhysicalInput

EngineConsumePhysicalInput(enable: Bool, timeoutSeconds: Integer) → Bool

يمنع إدخال الماوس ولوحة المفاتيح الحقيقي للمستخدم من الوصول إلى أي نافذة، أو يُنهي هذا الحظر. يظل الإدخال الذي ترسله البرامج النصية يعمل، وينتهي الحظر من تلقاء نفسه بعد انقضاء المهلة.

المعلمات

• enable: Bool — true لبدء حظر الإدخال الحقيقي أو إعادة بدئه؛ false لإنهاء الحظر، أيًّا كان البرنامج النصي الذي بدأه.
• timeoutSeconds: Integer — أطول مدة يستمر فيها الحظر، بالثواني؛ 1 أو أكثر عندما تكون قيمة enable هي true. تُقصَّر القيم الأطول إلى الحد الأقصى المعيَّن في صفحة إعدادات البرامج النصية (120 ثانية افتراضيًا). يتم تجاهلها عندما تكون قيمة enable هي false.

القيمة المُرجَعة

true دائمًا. عند تعيين enable إلى true، تؤدي قيمة timeoutSeconds تساوي 0 أو أقل إلى إيقاف البرنامج النصي بخطأ.

EngineDisable

EngineDisable() → Bool · بسيط

يعطّل المحرك، تمامًا كتعطيله من أيقونة منطقة الإعلامات، حتى يعيد EngineEnable أو منطقة الإعلامات تشغيله. يحدث التغيير بعد عودة الاستدعاء مباشرةً. لا يفعل شيئًا في الوضع الآمن.

المعلمات

لا توجد معلمات.

القيمة المُرجَعة

true إذا تم إرسال الطلب؛ false إذا لم ينتهِ المحرك من بدء التشغيل بعد.

١ مثال: حالة المحرك

EngineDisableNextGesture

EngineDisableNextGesture() → Bool · بسيط

يسمح للضغطة التالية على زر الرسم بالمرور مباشرةً إلى التطبيق بدلًا من بدء إيماءة، لمرة واحدة فقط. ليس له أي تأثير أثناء تعطيل المحرك.

المعلمات

لا توجد معلمات.

القيمة المُرجَعة

true دائمًا.

١ مثال: تمرير السحب التالي بالزر الأيمن

EngineEnable

EngineEnable() → Bool · بسيط

يمكّن المحرك مرة أخرى بعد EngineDisable أو بعد تعطيله من أيقونة منطقة الإعلامات. يحدث التغيير بعد عودة الاستدعاء مباشرةً. لا يفعل شيئًا في الوضع الآمن.

المعلمات

لا توجد معلمات.

القيمة المُرجَعة

true إذا تم إرسال الطلب؛ false إذا لم ينتهِ المحرك من بدء التشغيل بعد.

EngineExit

EngineExit() → Bool · بسيط

يغلق المحرك بإيقاف تشغيل عادي، تمامًا كالأمر «إنهاء» في قائمة منطقة الإعلامات: تُستعاد النوافذ المخفية في منطقة الإعلامات وتُغلق واجهة التكوين. يبدأ إيقاف التشغيل بعد عودة الاستدعاء مباشرةً.

المعلمات

لا توجد معلمات.

القيمة المُرجَعة

true إذا تم إرسال طلب إيقاف التشغيل؛ false إذا لم ينتهِ المحرك من بدء التشغيل بعد.

EngineIsDisabled

EngineIsDisabled() → Bool

يُرجع ما إذا كان المحرك معطّلًا الآن، سواء بواسطة EngineDisable أو أيقونة منطقة الإعلامات، أو تلقائيًا للتطبيق الذي عليه التركيز.

المعلمات

لا توجد معلمات.

القيمة المُرجَعة

true إذا كان المحرك معطّلًا؛ false إذا كان نشطًا.

١ مثال: حالة المحرك

EngineIsSafeMode

EngineIsSafeMode() → Bool

يُرجع ما إذا كان المحرك قد بدأ في الوضع الآمن. في الوضع الآمن، لا يمكن تشغيل سوى البرامج النصية التي تُشغَّل من وحدة التحكم التشخيصية.

المعلمات

لا توجد معلمات.

القيمة المُرجَعة

true في الوضع الآمن؛ وإلا false.

١ مثال: حالة المحرك

EngineReload

EngineReload() → Bool · بسيط

يعيد تحميل التكوين من القرص دون إعادة التشغيل، مثل «إعادة تحميل التكوين» في قائمة منطقة الإعلامات. ينتظر لمدة تصل إلى 3 ثوانٍ. يتم إيقاف كل برنامج نصي آخر قيد التشغيل؛ ويستمر هذا البرنامج.

المعلمات

لا توجد معلمات.

القيمة المُرجَعة

true بمجرد أن يصبح التكوين الجديد قيد الاستخدام؛ false إذا تعذّر تحميله أو استغرقت إعادة التحميل أكثر من 3 ثوانٍ.

EngineStopAllActions

EngineStopAllActions() → Bool · بسيط

يطلب من كل إجراء وبرنامج نصي قيد التشغيل التوقف، بما في ذلك البرنامج الذي يستدعيه. لا يُنهى أي شيء قسرًا: يتوقف كل برنامج نصي عند خطوته التالية، لذا قد يتقدم البرنامج المستدعي قليلًا أولًا.

المعلمات

لا توجد معلمات.

القيمة المُرجَعة

true دائمًا.

File

FileAppendText

FileAppendText(path: Text, text: Text) → Bool

يضيف نصًا إلى نهاية ملف نصي، وينشئ الملف إذا لم يكن موجودًا. مفيد للسجلات. يُكتب النص بترميز UTF-8 ولا يُضاف فاصل أسطر تلقائيًا.

المعلمات

• path: Text — المسار الكامل للملف. يجب أن يكون مجلده موجودًا بالفعل.
• text: Text — النص المراد إضافته. أنهِه بـ '\n' للاحتفاظ بإدخال واحد في كل سطر.

القيمة المُرجَعة

true إذا تمت كتابة النص؛ false إذا لم يكن المجلد موجودًا، أو كان الملف مؤمَّنًا، أو بدت بداية الملف الموجود كبيانات ثنائية.

١ مثال: الإلحاق بملف سجل

FileCopy

FileCopy(source: Text, destination: Text, overwrite: Bool) → Bool

ينسخ ملفًا من أي نوع إلى مسار جديد. يجب أن يكون المجلد الوجهة موجودًا بالفعل.

المعلمات

• source: Text — المسار الكامل للملف المراد نسخه.
• destination: Text — المسار الكامل للنسخة الجديدة، بما في ذلك اسم الملف.
• overwrite: Bool — true لاستبدال ملف موجود في destination؛ false لتركه كما هو وإرجاع false.

القيمة المُرجَعة

true إذا تم نسخ الملف؛ false إذا كان المصدر مفقودًا، أو كانت الوجهة موجودة وقيمة overwrite هي false، أو فشل النسخ.

١ مثال: نسخ ملف احتياطيًا قبل تحريره

FileCreate

FileCreate(path: Text, text: Text) → Bool

ينشئ ملفًا نصيًا جديدًا بالمحتوى المحدد، مكتوبًا بترميز UTF-8. يرفض العملية إذا كان أي شيء موجودًا بالفعل في ذلك المسار؛ استخدم FileEditText لاستبدال محتوى ملف موجود.

المعلمات

• path: Text — المسار الكامل للملف الجديد. يجب أن يكون مجلده موجودًا بالفعل.
• text: Text — محتوى الملف. النص الفارغ ينشئ ملفًا فارغًا.

القيمة المُرجَعة

true إذا تم إنشاء الملف؛ false إذا كان ملف أو مجلد موجودًا هناك بالفعل، أو تعذّرت كتابة الملف.

٢ مثالان: تاريخ اليوم، واسم ملف مختوم بالوقت, الإلحاق بملف سجل

FileDelete

FileDelete(path: Text) → Bool

يحذف ملفًا نهائيًا؛ فلا ينتقل إلى سلة المحذوفات. الملف غير الموجود بالفعل يُعتبر نجاحًا. لا يُحذف مجلد أبدًا؛ استخدم FolderDelete لذلك.

المعلمات

• path: Text — المسار الكامل للملف المراد حذفه.

القيمة المُرجَعة

true إذا لم يعد الملف موجودًا، بما في ذلك عندما لم يكن موجودًا أصلًا؛ false إذا كان المسار مجلدًا، أو كان الملف مؤمَّنًا أو تم رفض الوصول.

FileEditText

FileEditText(path: Text, text: Text) → Bool

يستبدل المحتوى الكامل لملف نصي موجود، مكتوبًا بترميز UTF-8. يرفض الملف الذي يبدو كبيانات ثنائية. استخدم FileCreate لملف جديد.

المعلمات

• path: Text — المسار الكامل لملف نصي موجود.
• text: Text — المحتوى الجديد، الذي يحل محل كل ما في الملف.

القيمة المُرجَعة

true إذا أُعيدت كتابة الملف؛ false إذا لم يكن موجودًا، أو بدت بدايته كبيانات ثنائية، أو تعذّرت كتابته.

١ مثال: نسخ ملف احتياطيًا قبل تحريره

FileExists

FileExists(path: Text) → Bool

يتحقق مما إذا كان ملف موجودًا في مسار ما. لا يُحتسب المجلد الموجود في ذلك المسار؛ استخدم FolderExists للمجلدات.

المعلمات

• path: Text — المسار الكامل للملف المراد التحقق منه.

القيمة المُرجَعة

true إذا كان ملف موجودًا هناك؛ false إذا لم يكن هناك شيء، أو كان مجلدًا.

٢ مثالان: الإلحاق بملف سجل, نسخ ملف احتياطيًا قبل تحريره

FileGetCreationDate

FileGetCreationDate(path: Text) → Text

يُرجع وقت إنشاء ملف، كتاريخ ووقت بتنسيق ISO 8601 بالتوقيت العالمي المنسَّق (UTC) يمكن أن يقرأه DateTimeFormat والدوال المضمَّنة DateTime الأخرى.

المعلمات

• path: Text — المسار الكامل للملف.

القيمة المُرجَعة

وقت الإنشاء، مثل 2026-10-01T18:05:09Z، أو نص فارغ إذا لم يكن الملف موجودًا أو كان المسار مجلدًا.

FileGetModifiedDate

FileGetModifiedDate(path: Text) → Text

يُرجع وقت آخر تغيير لمحتوى ملف، كتاريخ ووقت بتنسيق ISO 8601 بالتوقيت العالمي المنسَّق (UTC) يمكن أن يقرأه DateTimeFormat والدوال المضمَّنة DateTime الأخرى.

المعلمات

• path: Text — المسار الكامل للملف.

القيمة المُرجَعة

وقت آخر تعديل، مثل 2026-10-01T18:05:09Z، أو نص فارغ إذا لم يكن الملف موجودًا أو كان المسار مجلدًا.

١ مثال: قراءة ملف وعدّ أسطره

FileGetProductVersion

FileGetProductVersion(path: Text) → Text

يُرجع إصدار المنتج المخزَّن في ملف برنامج أو مكتبة، مثل ملف .exe أو .dll. هذا هو إصدار المنتج الذي يأتي معه الملف، وقد يختلف عن FileGetVersion.

المعلمات

• path: Text — المسار الكامل لملف .exe أو .dll أو أي ملف آخر يحتوي على معلومات إصدار.

القيمة المُرجَعة

الإصدار كأربعة أرقام، مثل 10.0.22621.1، أو نص فارغ إذا لم تكن للملف معلومات إصدار أو لم يكن موجودًا.

FileGetSize

FileGetSize(path: Text) → Integer

يُرجع حجم ملف بالبايت، دون فتح الملف أو قراءته.

المعلمات

• path: Text — المسار الكامل للملف.

القيمة المُرجَعة

الحجم بالبايت، أو -1 إذا لم يكن الملف موجودًا أو كان المسار مجلدًا.

١ مثال: قراءة ملف وعدّ أسطره

FileGetVersion

FileGetVersion(path: Text) → Text

يُرجع إصدار الملف المخزَّن في ملف برنامج أو مكتبة، مثل ملف .exe أو .dll، كما يظهر في علامة التبويب «التفاصيل» في «خصائص» الملف.

المعلمات

• path: Text — المسار الكامل لملف .exe أو .dll أو أي ملف آخر يحتوي على معلومات إصدار.

القيمة المُرجَعة

الإصدار كأربعة أرقام، مثل 10.0.22621.1، أو نص فارغ إذا لم تكن للملف معلومات إصدار أو لم يكن موجودًا.

FileMove

FileMove(source: Text, destination: Text, overwrite: Bool) → Bool

ينقل ملفًا من أي نوع إلى مسار جديد، مما يتيح أيضًا منحه اسمًا جديدًا، بما في ذلك تغيير حالة الأحرف فقط. يجب أن يكون المجلد الوجهة موجودًا بالفعل.

المعلمات

• source: Text — المسار الكامل للملف المراد نقله.
• destination: Text — المسار الكامل للموقع الجديد للملف، بما في ذلك اسم الملف.
• overwrite: Bool — true لاستبدال ملف موجود في destination بخطوة واحدة؛ false لتركه كما هو وإرجاع false. الوجهة التي تختلف عن المصدر في حالة الأحرف فقط لا تُعتبر ملفًا موجودًا.

القيمة المُرجَعة

true إذا تم نقل الملف؛ false إذا كان المصدر مفقودًا، أو كانت الوجهة موجودة وقيمة overwrite هي false، أو فشل النقل.

FileReadText

FileReadText(path: Text) → Text

يقرأ ملفًا نصيًا كاملًا ويُرجع محتواه. يفهم ترميز UTF-8، وUTF-16 مع علامة ترتيب البايت، والملفات المكتوبة بصفحة الترميز القديمة للنظام. يرفض الملفات الثنائية.

المعلمات

• path: Text — المسار الكامل للملف النصي.

القيمة المُرجَعة

محتوى الملف، أو نص فارغ إذا لم يكن الملف موجودًا، أو تعذّرت قراءته، أو بدا كبيانات ثنائية.

٢ مثالان: قراءة ملف وعدّ أسطره, نسخ ملف احتياطيًا قبل تحريره

FileRename

FileRename(path: Text, newName: Text) → Bool

يعيد تسمية ملف ويبقيه في مجلده الحالي. يعمل أيضًا تغيير حالة الأحرف فقط، مثل report.txt إلى Report.txt. لنقل ملف إلى مجلد آخر، استخدم FileMove.

المعلمات

• path: Text — المسار الكامل للملف المراد إعادة تسميته.
• newName: Text — اسم الملف الجديد فقط، مثل report-old.txt. الاسم الذي يحتوي على شرطة مائلة أو شرطة مائلة عكسية يوقف البرنامج النصي بخطأ.

القيمة المُرجَعة

true إذا تمت إعادة تسمية الملف؛ false إذا لم يكن موجودًا، أو كان هناك ملف أو مجلد آخر بالاسم الجديد بالفعل، أو فشلت إعادة التسمية.

Folder

FolderCreate

FolderCreate(path: Text) → Bool

ينشئ مجلدًا، بما في ذلك أي مجلدات أصل مفقودة. المجلد الموجود بالفعل يُعتبر نجاحًا.

المعلمات

• path: Text — المسار الكامل للمجلد المراد إنشاؤه.

القيمة المُرجَعة

true إذا كان المجلد موجودًا بعد ذلك؛ false إذا اعترض ملفٌ الطريق أو تعذّر إنشاء المجلد.

FolderDelete

FolderDelete(path: Text, recursive: Bool) → Bool

يحذف مجلدًا نهائيًا؛ فلا ينتقل إلى سلة المحذوفات. عند تعيين recursive إلى true، يُحذف كل ما بداخله أيضًا. المجلد غير الموجود بالفعل يُعتبر نجاحًا. لا يُحذف ملف أبدًا؛ استخدم FileDelete لذلك.

المعلمات

• path: Text — المسار الكامل للمجلد المراد حذفه.
• recursive: Bool — true لحذف المجلد وكل ما بداخله؛ false لحذفه فقط عندما يكون فارغًا.

القيمة المُرجَعة

true إذا لم يعد المجلد موجودًا؛ false إذا كان المسار ملفًا، أو لم يكن المجلد فارغًا وقيمة recursive هي false، أو كان شيء بداخله مؤمَّنًا أو محميًا.

FolderEnumerateAll

FolderEnumerateAll(path: Text, recursive: Bool) → Integer

يسرد الملفات والمجلدات الفرعية في مجلد ويُرجع عددها. اقرأ كل مسار كامل باستخدام FolderGetEnumeratedPathAt. يتم تخطي المجلدات الفرعية التي يتعذّر الوصول إليها.

المعلمات

• path: Text — المسار الكامل للمجلد المراد سرده.
• recursive: Bool — true لسرد كل ما بداخل جميع المجلدات الفرعية أيضًا؛ false للمحتويات المباشرة للمجلد فقط.

القيمة المُرجَعة

عدد الإدخالات التي عُثر عليها، أو -1 إذا لم يكن المجلد موجودًا أو تعذّرت قراءته.

١ مثال: عدّ أنواع الملفات في مجلد

FolderExists

FolderExists(path: Text) → Bool

يتحقق مما إذا كان مجلد موجودًا في مسار ما. لا يُحتسب الملف الموجود في ذلك المسار؛ استخدم FileExists للملفات.

المعلمات

• path: Text — المسار الكامل للمجلد المراد التحقق منه.

القيمة المُرجَعة

true إذا كان مجلد موجودًا هناك؛ false إذا لم يكن هناك شيء، أو كان ملفًا.

FolderGetEnumeratedPathAt

FolderGetEnumeratedPathAt(index: Integer) → Text

يُرجع مسارًا كاملًا واحدًا من القائمة التي أنشأها آخر استدعاء لـ FolderEnumerateAll في تشغيل البرنامج النصي هذا.

المعلمات

• index: Integer — الموضع في القائمة، من 0 إلى العدد الذي أرجعه FolderEnumerateAll ناقص 1.

القيمة المُرجَعة

المسار الكامل لملف أو مجلد، أو نص فارغ إذا كان index خارج النطاق أو لم يتم استدعاء FolderEnumerateAll.

١ مثال: عدّ أنواع الملفات في مجلد

FolderRename

FolderRename(path: Text, newName: Text) → Bool

يعيد تسمية مجلد ويبقيه، مع محتوياته، في المجلد الأصل الحالي. يعمل أيضًا تغيير حالة الأحرف فقط.

المعلمات

• path: Text — المسار الكامل للمجلد المراد إعادة تسميته.
• newName: Text — اسم المجلد الجديد فقط. الاسم الذي يحتوي على شرطة مائلة أو شرطة مائلة عكسية يوقف البرنامج النصي بخطأ.

القيمة المُرجَعة

true إذا تمت إعادة تسمية المجلد؛ false إذا لم يكن موجودًا، أو كان هناك ملف أو مجلد آخر بالاسم الجديد بالفعل، أو فشلت إعادة التسمية، مثلًا بسبب ملف مفتوح بداخله.

FolderWatchCreate

FolderWatchCreate(name: Text, path: Text, recursive: Bool, filterMask: Integer, script: Text) → Bool

يبدأ مراقبة مجلد ويشغّل برنامجًا نصيًا لكل تغيير يُبلغ عنه Windows، مثل إنشاء ملف أو تغييره أو إعادة تسميته أو حذفه. تستمر المراقبة في العمل بعد انتهاء هذا البرنامج النصي.

المعلمات

• name: Text — اسم للمراقبة. يؤدي إنشاء مراقبة باسم مستخدَم بالفعل إلى استبدال تلك المراقبة. الأسماء حساسة لحالة الأحرف.
• path: Text — المسار الكامل للمجلد المراد مراقبته.
• recursive: Bool — true لمراقبة كل المجلدات الفرعية أيضًا؛ false لمراقبة المجلد نفسه فقط.
• filterMask: Integer — أنواع التغيير المراد الإبلاغ عنها: ثوابت FileNotify مجمَّعة باستخدام |، مثل FileNotify.FileName | FileNotify.LastWrite.
• script: Text — البرنامج النصي المراد تشغيله لكل تغيير، كقيمة Text. يقرأ التغيير باستخدام ContextGetWatchAction (created أو deleted أو modified أو renamed-old-name أو renamed-new-name أو overflow) وContextGetWatchPath.

القيمة المُرجَعة

true إذا كانت المراقبة قيد التشغيل؛ false إذا لم يكن المجلد موجودًا، أو تعذّر فتحه، أو كانت قيمة filterMask تساوي 0.

١ مثال: مراقبة مجلد

FolderWatchDelete

FolderWatchDelete(name: Text) → Bool

يوقف مراقبة مجلد أُنشئت باستخدام FolderWatchCreate، فلا يعود برنامجها النصي يعمل.

المعلمات

• name: Text — الاسم الذي مُرِّر إلى FolderWatchCreate. الأسماء حساسة لحالة الأحرف.

القيمة المُرجَعة

true إذا عُثر على مراقبة بهذا الاسم وتم إيقافها؛ false إذا لم توجد أي مراقبة.

١ مثال: مراقبة مجلد

FolderWatchDeleteAll

FolderWatchDeleteAll() → Bool

يوقف كل مراقبات المجلدات التي أُنشئت باستخدام FolderWatchCreate، فلا يعود أي من برامجها النصية يعمل.

المعلمات

لا توجد معلمات.

القيمة المُرجَعة

true دائمًا.

FolderWatchGetCount

FolderWatchGetCount() → Integer

يُرجع عدد مراقبات المجلدات قيد التشغيل ويلتقط لقطة لأسمائها من أجل FolderWatchGetEnumeratedNameAt.

المعلمات

لا توجد معلمات.

القيمة المُرجَعة

عدد مراقبات المجلدات قيد التشغيل، أو 0 إذا لم توجد أي منها.

FolderWatchGetEnumeratedNameAt

FolderWatchGetEnumeratedNameAt(index: Integer) → Text

يُرجع اسم مراقبة واحدة من اللقطة التي التقطها آخر استدعاء لـ FolderWatchGetCount في تشغيل البرنامج النصي هذا.

المعلمات

• index: Integer — الموضع في اللقطة، من 0 إلى العدد ناقص 1. لا معنى للترتيب.

القيمة المُرجَعة

اسم المراقبة، أو نص فارغ إذا كان index خارج النطاق أو لم يتم استدعاء FolderWatchGetCount.

GestureProfile

GestureProfileEnumerateAll

GestureProfileEnumerateAll() → Integer

يأخذ قائمة بكل ملفات تعريف الإيماءات في التكوين ويُرجع عددها. اقرأ كل ملف تعريف باستخدام GestureProfileGetEnumeratedIdAt وGestureProfileGetEnumeratedNameAt.

المعلمات

لا توجد معلمات.

القيمة المُرجَعة

عدد ملفات تعريف الإيماءات، أو 0 إذا لم توجد أي منها.

١ مثال: الانتقال إلى ملف تعريف الإيماءات التالي

GestureProfileGetActiveId

GestureProfileGetActiveId() → Text

يُرجع معرّف ملف تعريف الإيماءات النشط الآن.

المعلمات

لا توجد معلمات.

القيمة المُرجَعة

معرّف ملف التعريف النشط، أو نص فارغ إذا لم يكن أي ملف تعريف نشطًا.

٢ مثالان: إعلام Windows, الانتقال إلى ملف تعريف الإيماءات التالي

GestureProfileGetEnumeratedIdAt

GestureProfileGetEnumeratedIdAt(index: Integer) → Text

يُرجع معرّف ملف تعريف واحد من القائمة التي أخذها GestureProfileEnumerateAll آخر مرة في هذا البرنامج النصي. مرِّر المعرّف إلى GestureProfileSwitch.

المعلمات

• index: Integer — الموضع في القائمة بدءًا من الصفر، من 0 إلى العدد ناقص 1.

القيمة المُرجَعة

معرّف ملف التعريف، أو نص فارغ إذا كان index خارج النطاق أو لم يتم استدعاء GestureProfileEnumerateAll.

١ مثال: الانتقال إلى ملف تعريف الإيماءات التالي

GestureProfileGetEnumeratedNameAt

GestureProfileGetEnumeratedNameAt(index: Integer) → Text

يُرجع الاسم المعروض لملف تعريف واحد من القائمة التي أخذها GestureProfileEnumerateAll آخر مرة في هذا البرنامج النصي.

المعلمات

• index: Integer — الموضع في القائمة بدءًا من الصفر، من 0 إلى العدد ناقص 1.

القيمة المُرجَعة

اسم ملف التعريف، أو نص فارغ إذا كان index خارج النطاق أو لم يتم استدعاء GestureProfileEnumerateAll.

١ مثال: الانتقال إلى ملف تعريف الإيماءات التالي

GestureProfileSwitch

GestureProfileSwitch(profileId: Text) → Bool · بسيط

يبدِّل إلى ملف تعريف إيماءات آخر، تمامًا كاختياره من قائمة منطقة الإعلامات، ويتذكر الاختيار بعد إعادة التشغيل. يحدث التبديل بعد عودة الاستدعاء مباشرةً.

المعلمات

• profileId: Text — معرّف ملف التعريف المراد التبديل إليه، مثل معرّف من GestureProfileGetEnumeratedIdAt، أو نص فارغ لعدم استخدام أي ملف تعريف.

القيمة المُرجَعة

true إذا تم إرسال الطلب؛ false لمعرّف لا يملكه أي ملف تعريف، ولا يتغير شيء. يحدث التبديل بعد عودة الاستدعاء مباشرة؛ استخدم GestureProfileGetActiveId للتأكد منه.

١ مثال: الانتقال إلى ملف تعريف الإيماءات التالي

Keyboard

KeyboardGetKeyState

KeyboardGetKeyState(key: Integer) → Integer

يُرجع حالة Windows الأولية لمفتاح كما هي الآن. عندما يكون سطح مكتب آخر في المقدمة، مثل مطالبة UAC أو شاشة القفل، يُقرأ كل مفتاح على أنه غير مضغوط. للحصول على نعم أو لا ببساطة، استخدم KeyboardIsKeyDown أو KeyboardIsKeyToggled.

المعلمات

• key: Integer — ثابت VirtualKey، مثل VirtualKey.CapsLock، أو رمز مفتاح ظاهري من 0 إلى 255. أي قيمة أخرى توقف البرنامج النصي بخطأ.

القيمة المُرجَعة

قيمة Integer أولية: سالبة (البت الأعلى معيَّن) عندما يكون المفتاح مضغوطًا، وفردية (البت الأدنى معيَّن) عندما يكون مفتاح تأمين مثل Caps Lock قيد التشغيل.

١ مثال: بتات حالة المفتاح

KeyboardGetKeyStateAsync

KeyboardGetKeyStateAsync(key: Integer) → Integer

يُرجع حالة Windows الأولية لمفتاح في هذه اللحظة بالذات، أيًّا كانت النافذة التي عليها التركيز.

المعلمات

• key: Integer — ثابت VirtualKey، مثل VirtualKey.ShiftKey، أو رمز مفتاح ظاهري من 0 إلى 255. أي قيمة أخرى توقف البرنامج النصي بخطأ.

القيمة المُرجَعة

قيمة Integer أولية: سالبة (البت الأعلى معيَّن) عندما يكون المفتاح مضغوطًا الآن. قد يكون البت الأدنى معيَّنًا إذا ضُغط المفتاح منذ فحص سابق، وهو أمر لا يضمنه Windows.

KeyboardIsKeyDown

KeyboardIsKeyDown(key: Integer) → Bool

يتحقق مما إذا كان مفتاح مضغوطًا باستمرار الآن. عندما يكون سطح مكتب آخر في المقدمة، مثل مطالبة UAC أو شاشة القفل، يُقرأ كل مفتاح على أنه غير مضغوط.

المعلمات

• key: Integer — ثابت VirtualKey، مثل VirtualKey.ControlKey، أو رمز مفتاح ظاهري من 0 إلى 255. أي قيمة أخرى توقف البرنامج النصي بخطأ.

القيمة المُرجَعة

true إذا كان المفتاح مضغوطًا؛ false إذا كان محرَّرًا.

٢ مثالان: بتات حالة المفتاح, تغيير السلوك أثناء الضغط على Ctrl

KeyboardIsKeyToggled

KeyboardIsKeyToggled(key: Integer) → Bool

يتحقق مما إذا كان مفتاح تأمين قيد التشغيل. له معنى فقط مع VirtualKey.CapsLock وVirtualKey.NumLock وVirtualKey.Scroll.

المعلمات

• key: Integer — ثابت VirtualKey، مثل VirtualKey.CapsLock، أو رمز مفتاح ظاهري من 0 إلى 255. أي قيمة أخرى توقف البرنامج النصي بخطأ.

القيمة المُرجَعة

true إذا كان مفتاح التأمين قيد التشغيل؛ false إذا كان متوقفًا.

١ مثال: بتات حالة المفتاح

KeyboardKeyDown

KeyboardKeyDown(key: Integer) → Bool

يضغط مفتاحًا ويبقيه مضغوطًا حتى يحرره KeyboardKeyUp. عند تشغيل الإعداد «إرسال مفاتيح الوسائط والمستعرض كأوامر»، يرسل مفتاح الوسائط أو مستوى الصوت أو المستعرض الأمر الخاص به بدلًا من ذلك.

المعلمات

• key: Integer — ثابت VirtualKey، مثل VirtualKey.ShiftKey، أو رمز مفتاح ظاهري من 0 إلى 255. أي قيمة أخرى توقف البرنامج النصي بخطأ.

القيمة المُرجَعة

true إذا تم إرسال ضغطة المفتاح؛ false إذا حظرها Windows أو، بالنسبة لمفتاح يُرسل كأمر، إذا لم تكن هناك نافذة عليها التركيز.

١ مثال: النقر مع Shift

KeyboardKeyUp

KeyboardKeyUp(key: Integer) → Bool

يحرر مفتاحًا مضغوطًا باستخدام KeyboardKeyDown. بالنسبة لمفتاح وسائط أو مستوى صوت أو مستعرض يُرسل كأمر، لا يفعل شيئًا، لأن الأمر أُرسل بالفعل عند الضغط.

المعلمات

• key: Integer — ثابت VirtualKey، مثل VirtualKey.ShiftKey، أو رمز مفتاح ظاهري من 0 إلى 255. أي قيمة أخرى توقف البرنامج النصي بخطأ.

القيمة المُرجَعة

true إذا تم إرسال تحرير المفتاح، وtrue دائمًا لمفتاح يُرسل كأمر؛ false إذا حظره Windows.

١ مثال: النقر مع Shift

KeyboardPressKey

KeyboardPressKey(key: Integer) → Bool · بسيط

يضغط مفتاحًا واحدًا ويحرره، ويمكن أن يكون أي مفتاح له رمز في Windows، بما في ذلك مفاتيح الوسائط. عند تشغيل الإعداد «إرسال مفاتيح الوسائط والمستعرض كأوامر»، ترسل تلك المفاتيح الأمر الخاص بها بدلًا من ذلك.

المعلمات

• key: Integer — ثابت VirtualKey، مثل VirtualKey.MediaPlayPause، أو رمز مفتاح ظاهري من 0 إلى 255. أي قيمة أخرى توقف البرنامج النصي بخطأ.

القيمة المُرجَعة

true إذا تم إرسال ضغطة المفتاح؛ false إذا حظرها Windows أو، بالنسبة لمفتاح يُرسل كأمر، إذا لم تكن هناك نافذة عليها التركيز.

٣ أمثلة: الثوابت المسماة مقابل الأرقام الخام, مفاتيح الوسائط, ربط أزرار جهاز تسلسلي بمفاتيح الوسائط

KeyboardPressKeyCombo

KeyboardPressKeyCombo(combo: Text) → Bool · بسيط

يضغط تركيبة مفاتيح واحدة مثل Ctrl+C: يضغط مفاتيح التعديل باستمرار، ثم يضغط المفتاح ويحرره، ثم يحرر مفاتيح التعديل. يرسل تركيبة واحدة في كل استدعاء.

المعلمات

• combo: Text — رموز تعديل اختيارية (^ لـ Ctrl، و+ لـ Shift، و@ لـ Windows، وعلامة النسبة المئوية لـ Alt) متبوعة بحرف أو رقم واحد، أو باسم مفتاح بين أقواس معقوفة مثل {ENTER} أو {F5} أو {LEFT}، بأي حالة أحرف. مثال: '^c' تعني Ctrl+C.

القيمة المُرجَعة

true إذا تم إرسال ضغطات المفاتيح؛ false إذا حظرها Windows. التركيبة التي لا يفهمها توقف البرنامج النصي بخطأ.

٤ أمثلة: تركيبات المفاتيح, كتابة توقيع, تحويل النص المحدد إلى أحرف كبيرة, البحث في الويب عن التحديد

KeyboardTypeText

KeyboardTypeText(text: Text) → Bool · بسيط

يكتب نصًا في النافذة التي عليها التركيز حرفًا بحرف، بأي لغة وبما في ذلك الرموز التعبيرية، أيًّا كان تخطيط لوحة المفاتيح. ينتظر المدة المعيَّنة في الإعداد «تأخير الكتابة» قبل كل حرف.

المعلمات

• text: Text — النص المراد كتابته. يُرسل كل فاصل أسطر كضغطة واحدة على Enter. في البرنامج النصي لتوسيع النص، يُكتب بعده المفتاح الذي أنهى المشغِّل.

القيمة المُرجَعة

true إذا تم إرسال كل الأحرف، أو كان النص فارغًا؛ false إذا حظر Windows بعضها.

٣ أمثلة: تشغيل برنامج وانتظار نافذته والعمل عليها, تاريخ اليوم، واسم ملف مختوم بالوقت, كتابة توقيع

Macro

MacroClearTemporary

MacroClearTemporary() → Bool

يتجاهل الماكرو المسجَّل باستخدام MacroRecordTemporary.

المعلمات

لا توجد معلمات.

القيمة المُرجَعة

true إذا كان هناك ماكرو مسجَّل لتجاهله؛ false إذا لم يوجد أي ماكرو.

MacroExpectFocusedWindow

MacroExpectFocusedWindow(exeName: Text, windowClass: Text) → Bool

ينتظر حتى تنتمي النافذة الأمامية إلى البرنامج وفئة النافذة المحددين، لمدة تصل إلى مدة انتظار إعادة تشغيل الماكرو المعيَّنة في الإعدادات (ثانيتان افتراضيًا). إذا لم تتطابق أبدًا، يعرض إعلامًا ويوقف البرنامج النصي.

المعلمات

• exeName: Text — اسم ملف البرنامج، مثل notepad.exe. غير حساس لحالة الأحرف؛ والنص الفارغ يطابق أي برنامج.
• windowClass: Text — اسم فئة النافذة ذات المستوى الأعلى، مثل Notepad. غير حساس لحالة الأحرف؛ والنص الفارغ يطابق أي فئة.

القيمة المُرجَعة

true عندما تتطابق النافذة؛ false إذا طُلب من البرنامج النصي التوقف أثناء الانتظار.

MacroExpectWindowAt

MacroExpectWindowAt(x: Integer, y: Integer, exeName: Text, windowClass: Text) → Bool

ينتظر حتى تنتمي النافذة ذات المستوى الأعلى عند نقطة على الشاشة إلى البرنامج وفئة النافذة المحددين، لمدة تصل إلى مدة انتظار إعادة تشغيل الماكرو المعيَّنة في الإعدادات (ثانيتان افتراضيًا). إذا لم تتطابق أبدًا، يعرض إعلامًا ويوقف البرنامج النصي.

المعلمات

• x: Integer — الموضع الأفقي المراد فحصه على الشاشة، بوحدات بكسل الشاشة الظاهرية.
• y: Integer — الموضع الرأسي المراد فحصه على الشاشة، بوحدات بكسل الشاشة الظاهرية.
• exeName: Text — اسم ملف البرنامج، مثل notepad.exe. غير حساس لحالة الأحرف؛ والنص الفارغ يطابق أي برنامج.
• windowClass: Text — اسم فئة النافذة ذات المستوى الأعلى، مثل Notepad. غير حساس لحالة الأحرف؛ والنص الفارغ يطابق أي فئة.

القيمة المُرجَعة

true عندما تتطابق النافذة؛ false إذا طُلب من البرنامج النصي التوقف أثناء الانتظار.

MacroGetTemporaryScript

MacroGetTemporaryScript() → Text

يُرجع الماكرو المسجَّل باستخدام MacroRecordTemporary كنص برنامج نصي بصيغة خطوات، حتى يتمكن برنامج نصي من حفظه أو فحصه.

المعلمات

لا توجد معلمات.

القيمة المُرجَعة

نص خطوات لآخر تسجيل مكتمل، أو نص فارغ إذا لم يُسجَّل شيء أو تم مسحه. أثناء تشغيل تسجيل جديد، يظل يُرجع التسجيل السابق.

MacroPlayTemporary

MacroPlayTemporary(timeoutSeconds: Integer) → Bool

يعيد تشغيل الماكرو المسجَّل باستخدام MacroRecordTemporary وينتظر حتى ينتهي أو تنقضي المهلة. يُحجز إدخال الماوس ولوحة المفاتيح الحقيقي للمستخدم أثناء إعادة التشغيل.

المعلمات

• timeoutSeconds: Integer — أطول مدة للانتظار، بالثواني؛ 1 أو أكثر، وإلا يتوقف البرنامج النصي بخطأ. الماكرو الذي لا يزال قيد التشغيل بعد ذلك يستمر، لكن الإدخال الحقيقي لا يعود محجوزًا.

القيمة المُرجَعة

true إذا اكتمل تشغيل الماكرو حتى النهاية في الوقت المحدد؛ false إذا لم يُسجَّل شيء، أو فشلت خطوة أو فحص نافذة، أو تم إيقاف التشغيل، أو كان لا يزال قيد التشغيل عند انقضاء المهلة.

MacroRecordTemporary

MacroRecordTemporary() → Bool

يبدأ تسجيل إدخال الماوس ولوحة المفاتيح في ماكرو مؤقت يُحتفظ به في الذاكرة؛ اضغط Ctrl+Break للإيقاف. يعود فورًا، قبل بدء التسجيل. قد يظهر مربع تأكيد أولًا.

المعلمات

لا توجد معلمات.

القيمة المُرجَعة

true إذا تم إرسال طلب التسجيل؛ false إذا كان هناك تسجيل قيد التشغيل أو قيد البدء أو مطلوب بالفعل، أو لم ينتهِ المحرك من بدء التشغيل بعد.

Math

MathAbs

MathAbs(value: Any) → Any

يُرجع القيمة المطلقة لرقم، أي الرقم بدون علامة السالب. يعمل مع قيم Integer وReal.

المعلمات

• value: Any — الرقم من نوع Integer أو Real.

القيمة المُرجَعة

القيمة المطلقة، من نوع value نفسه (Integer أو Real)؛ و0.0 لقيمة Real تساوي NaN أو لا نهائية. القيمة التي ليست رقمًا توقف الإجراء بخطأ.

٢ مثالان: حصر قيمة ضمن نطاق, في أي اتجاه سار الخط؟

MathAtan2

MathAtan2(y: Any, x: Any) → Real

يُرجع الزاوية، بالراديان، من نقطة الأصل إلى النقطة (x, y). يزداد y على الشاشة نحو الأسفل، لذا للحصول على زاوية خط الرسم بالاتجاه الرياضي المعتاد، مرِّر التغيّر الرأسي بإشارة معكوسة.

المعلمات

• y: Any — الإحداثي الرأسي للنقطة. Integer أو Real. لاحظ أن y يأتي أولًا.
• x: Any — الإحداثي الأفقي للنقطة. Integer أو Real.

القيمة المُرجَعة

الزاوية بالراديان، من -pi إلى pi، كقيمة Real؛ و0.0 إذا كانت أي من الوسيطتين NaN أو لا نهائية. الوسيطات التي ليست أرقامًا توقف الإجراء بخطأ.

MathCeil

MathCeil(value: Real) → Integer

يقرّب رقمًا للأعلى إلى أقرب عدد صحيح. MathCeil(2.1) يساوي 3؛ وMathCeil(-2.1) يساوي -2.

المعلمات

• value: Real — الرقم المراد تقريبه للأعلى. تُقبل قيمة Integer كما هي.

القيمة المُرجَعة

القيمة المقرَّبة كقيمة Integer. 0 إذا كانت value تساوي NaN أو لا نهائية؛ والقيمة التي تتجاوز نطاق Integer تعطي أكبر أو أصغر قيمة Integer.

١ مثال: التقريب والدوال المضمَّنة الرياضية لقيم Real

MathClamp

MathClamp(value: Any, min: Any, max: Any) → Any

يُبقي رقمًا داخل نطاق: يُرجع min إذا كانت value أقل منه، وmax إذا كانت value أعلى منه، وvalue فيما عدا ذلك. يعمل مع قيم Integer وReal.

المعلمات

• value: Any — الرقم المراد إبقاؤه داخل النطاق.
• min: Any — أدنى قيمة مسموح بها. يجب ألا تكون أكبر من max.
• max: Any — أعلى قيمة مسموح بها.

القيمة المُرجَعة

ما اختير من value أو min أو max، مع الاحتفاظ بنوعه (Integer أو Real)؛ و0.0 إذا كانت أي وسيطة NaN أو لا نهائية. القيم التي ليست أرقامًا، أو كون min أكبر من max، توقف الإجراء بخطأ.

١ مثال: حصر قيمة ضمن نطاق

MathCos

MathCos(radians: Real) → Real

يُرجع جيب تمام زاوية معطاة بالراديان. لتحويل الدرجات، اضرب في MathGetPi() واقسم على 180.

المعلمات

• radians: Real — الزاوية بالراديان. تُقبل قيمة Integer كما هي.

القيمة المُرجَعة

جيب التمام، من -1 إلى 1، كقيمة Real؛ و0.0 إذا كانت radians تساوي NaN أو لا نهائية.

١ مثال: تحريك الماوس في دائرة

MathFloor

MathFloor(value: Real) → Integer

يقرّب رقمًا للأسفل إلى أقرب عدد صحيح. MathFloor(2.9) يساوي 2؛ وMathFloor(-2.1) يساوي -3.

المعلمات

• value: Real — الرقم المراد تقريبه للأسفل. تُقبل قيمة Integer كما هي.

القيمة المُرجَعة

القيمة المقرَّبة كقيمة Integer. 0 إذا كانت value تساوي NaN أو لا نهائية؛ والقيمة التي تتجاوز نطاق Integer تعطي أكبر أو أصغر قيمة Integer.

١ مثال: التقريب والدوال المضمَّنة الرياضية لقيم Real

MathGetE

MathGetE() → Real

يُرجع الثابت الرياضي e (حوالي 2.71828)، أساس اللوغاريتمات الطبيعية.

المعلمات

لا توجد معلمات.

القيمة المُرجَعة

قيمة e كقيمة Real.

MathGetPi

MathGetPi() → Real

يُرجع الثابت الرياضي pi (حوالي 3.14159). استخدمه للتحويل بين الدرجات والراديان.

المعلمات

لا توجد معلمات.

القيمة المُرجَعة

قيمة pi كقيمة Real.

١ مثال: تحريك الماوس في دائرة

MathLog

MathLog(value: Real) → Real

يُرجع اللوغاريتم الطبيعي (للأساس e) لرقم. اقسم على MathLog(10.0) للحصول على لوغاريتم للأساس 10.

المعلمات

• value: Real — الرقم، أكبر من 0. تُقبل قيمة Integer كما هي.

القيمة المُرجَعة

اللوغاريتم الطبيعي كقيمة Real، أو 0 إذا كانت value تساوي 0 أو كانت سالبة أو NaN أو لا نهائية.

MathMax

MathMax(a: Any, b: Any) → Any

يُرجع الأكبر من رقمين. يعمل مع قيم Integer وReal.

المعلمات

• a: Any — الرقم الأول.
• b: Any — الرقم الثاني.

القيمة المُرجَعة

الأكبر من a أو b، مع الاحتفاظ بنوعه؛ وa إذا كانا متساويين؛ و0.0 إذا كان أي منهما NaN أو لا نهائيًا.الوسيطات التي ليست أرقامًا توقف الإجراء بخطأ.

MathMin

MathMin(a: Any, b: Any) → Any

يُرجع الأصغر من رقمين. يعمل مع قيم Integer وReal.

المعلمات

• a: Any — الرقم الأول.
• b: Any — الرقم الثاني.

القيمة المُرجَعة

الأصغر من a أو b، مع الاحتفاظ بنوعه؛ وa إذا كانا متساويين؛ و0.0 إذا كان أي منهما NaN أو لا نهائيًا.الوسيطات التي ليست أرقامًا توقف الإجراء بخطأ.

١ مثال: رفع مستوى الصوت مع عرض على الشاشة

MathMod

MathMod(value: Any, divisor: Any) → Any

يُرجع باقي قسمة value على divisor. تأخذ النتيجة إشارة المقسوم عليه، لذا MathMod(-30, 360) يساوي 330: وهذا مناسب لالتفاف زاوية أو تدوير فهرس.

المعلمات

• value: Any — الرقم المراد قسمته. Integer أو Real.
• divisor: Any — الرقم المراد القسمة عليه. Integer أو Real.

القيمة المُرجَعة

الباقي: قيمة Integer عندما تكون كلتا الوسيطتين Integer، وإلا قيمة Real. 0 إذا كانت divisor تساوي 0 أو كانت أي من الوسيطتين NaN أو لا نهائية.الوسيطات التي ليست أرقامًا توقف الإجراء بخطأ.

MathPow

MathPow(base: Real, exponent: Real) → Real

يرفع رقمًا إلى قوة، مثل التربيع أو التكعيب. MathPow(2.0, 10.0) يساوي 1024.

المعلمات

• base: Real — الرقم المراد رفعه. تُقبل قيمة Integer كما هي.
• exponent: Real — القوة المراد الرفع إليها. يمكن أن تكون سالبة أو كسرية؛ 0.5 تعطي الجذر التربيعي.

القيمة المُرجَعة

النتيجة كقيمة Real، أو 0 إذا كانت إحدى الوسيطتين NaN أو لا نهائية أو لم تكن هناك نتيجة محدودة، مثل 0 مرفوعًا إلى قوة سالبة أو نتيجة أكبر من أن تُخزَّن.

MathRandom

MathRandom(min: Integer, max: Integer) → Integer

يُرجع عددًا صحيحًا عشوائيًا بين min وmax، شاملًا كليهما. MathRandom(1, 6) يرمي حجر نرد.

المعلمات

• min: Integer — أدنى نتيجة ممكنة.
• max: Integer — أعلى نتيجة ممكنة. يجب ألا تكون أقل من min.

القيمة المُرجَعة

قيمة Integer عشوائية من min إلى max. كون min أكبر من max يوقف الإجراء بخطأ.

٢ مثالان: while (true) مع علامة خروج, أرقام عشوائية ورمي عملة

MathRound

MathRound(value: Real) → Integer

يقرّب رقمًا إلى أقرب عدد صحيح. تُقرَّب الأنصاف بعيدًا عن الصفر: 2.5 تصبح 3 و-2.5 تصبح -3.

المعلمات

• value: Real — الرقم المراد تقريبه. للاحتفاظ بمنزلتين عشريتين كعدد صحيح، قرّب value مضروبة في 100.

القيمة المُرجَعة

القيمة المقرَّبة كقيمة Integer. 0 إذا كانت value تساوي NaN أو لا نهائية؛ والقيمة التي تتجاوز نطاق Integer تعطي أكبر أو أصغر قيمة Integer.

٥ أمثلة: التقريب والدوال المضمَّنة الرياضية لقيم Real, طول خط الإيماءة, تحريك الماوس في دائرة, تنسيق قيمة Real بدون ست خانات عشرية, رفع مستوى الصوت مع عرض على الشاشة

MathSin

MathSin(radians: Real) → Real

يُرجع جيب زاوية معطاة بالراديان. لتحويل الدرجات، اضرب في MathGetPi() واقسم على 180.

المعلمات

• radians: Real — الزاوية بالراديان. تُقبل قيمة Integer كما هي.

القيمة المُرجَعة

الجيب، من -1 إلى 1، كقيمة Real؛ و0.0 إذا كانت radians تساوي NaN أو لا نهائية.

١ مثال: تحريك الماوس في دائرة

MathSqrt

MathSqrt(value: Real) → Real

يُرجع الجذر التربيعي لرقم. MathSqrt(dx * dx + dy * dy) هي المسافة بين نقطتين.

المعلمات

• value: Real — الرقم، 0 أو أكبر. تُقبل قيمة Integer كما هي.

القيمة المُرجَعة

الجذر التربيعي كقيمة Real، أو 0 إذا كانت value سالبة أو NaN أو لا نهائية.

٢ مثالان: التقريب والدوال المضمَّنة الرياضية لقيم Real, طول خط الإيماءة

MathTan

MathTan(radians: Real) → Real

يُرجع ظل زاوية معطاة بالراديان. بالقرب من الزاوية القائمة تصبح النتيجة كبيرة جدًا.

المعلمات

• radians: Real — الزاوية بالراديان. تُقبل قيمة Integer كما هي.

القيمة المُرجَعة

الظل كقيمة Real؛ و0.0 إذا كانت radians تساوي NaN أو لا نهائية.

Mouse

MouseButtonDown

MouseButtonDown(button: Integer) → Bool

يضغط زر ماوس عند موضع المؤشر الحالي ويبقيه مضغوطًا حتى MouseButtonUp. اجمعه مع MouseMoveTo لبرمجة عملية سحب.

المعلمات

• button: Integer — ثابت MouseButton، مثل MouseButton.Primary. يتبع Primary وSecondary إعداد تبديل الأزرار في Windows؛ أما Left وRight فهما الزران الفعليان.

القيمة المُرجَعة

true إذا تم إرسال ضغطة الزر؛ false إذا حظرها Windows. الزر غير المعروف يوقف البرنامج النصي بخطأ.

١ مثال: سحب ببرنامج نصي

MouseButtonUp

MouseButtonUp(button: Integer) → Bool

يحرر زر ماوس عند موضع المؤشر الحالي، وعادةً ما يكون زرًا مضغوطًا باستخدام MouseButtonDown.

المعلمات

• button: Integer — ثابت MouseButton، مثل MouseButton.Primary. يتبع Primary وSecondary إعداد تبديل الأزرار في Windows؛ أما Left وRight فهما الزران الفعليان.

القيمة المُرجَعة

true إذا تم إرسال تحرير الزر؛ false إذا حظره Windows. الزر غير المعروف يوقف البرنامج النصي بخطأ.

١ مثال: سحب ببرنامج نصي

MouseClick

MouseClick(x: Integer, y: Integer, button: Integer) → Bool · بسيط

ينقل المؤشر إلى نقطة على الشاشة وينقر زر ماوس هناك. يبقى المؤشر عند تلك النقطة بعد ذلك.

المعلمات

• x: Integer — الموضع الأفقي المراد النقر عليه على الشاشة، بالبكسل.
• y: Integer — الموضع الرأسي المراد النقر عليه على الشاشة، بالبكسل.
• button: Integer — ثابت MouseButton، مثل MouseButton.Primary. يتبع Primary وSecondary إعداد تبديل الأزرار في Windows؛ أما Left وRight فهما الزران الفعليان.

القيمة المُرجَعة

true إذا تم إرسال النقرة؛ false إذا تعذّر نقل المؤشر إلى النقطة، وعندئذ لا يُنقر شيء، أو إذا حظر Windows النقرة.الزر غير المعروف يوقف البرنامج النصي بخطأ.

٢ مثالان: النقر في مكان ما، ثم إعادة المؤشر, النقر مع Shift

MouseClickAtClientPoint

MouseClickAtClientPoint(window: Window, x: Integer, y: Integer, button: Integer) → Bool

ينقر زر ماوس عند نقطة تُقاس من الزاوية العلوية اليسرى لمنطقة العميل في نافذة (الجزء الداخلي، بدون شريط العنوان والحدود). ينتقل المؤشر إلى هناك ويبقى.

المعلمات

• window: Window — النافذة التي تُقاس x وy من منطقة العميل الخاصة بها.
• x: Integer — المسافة من الحافة اليسرى لمنطقة العميل، بوحدات البكسل الخاصة بتلك النافذة، والتي قد تختلف عن بكسلات الشاشة في نافذة يحجّمها Windows وفقًا لقيمة DPI.
• y: Integer — المسافة من الحافة العلوية لمنطقة العميل، بوحدات البكسل الخاصة بتلك النافذة، والتي قد تختلف عن بكسلات الشاشة في نافذة يحجّمها Windows وفقًا لقيمة DPI.
• button: Integer — ثابت MouseButton، مثل MouseButton.Primary. يتبع Primary وSecondary إعداد تبديل الأزرار في Windows؛ أما Left وRight فهما الزران الفعليان.

القيمة المُرجَعة

true إذا تم إرسال النقرة؛ false إذا كانت النافذة غير صالحة أو لم تعد موجودة أو تعذّر نقل المؤشر إلى النقطة، وعندئذ لا يُنقر شيء، أو إذا حظر Windows النقرة. الزر غير المعروف يوقف البرنامج النصي بخطأ.

١ مثال: النقر على نقطة داخل نافذة

MouseDoubleClick

MouseDoubleClick(x: Integer, y: Integer, button: Integer) → Bool · بسيط

ينقل المؤشر إلى نقطة على الشاشة وينقر نقرًا مزدوجًا بزر ماوس هناك. يبقى المؤشر عند تلك النقطة بعد ذلك.

المعلمات

• x: Integer — الموضع الأفقي المراد النقر عليه نقرًا مزدوجًا على الشاشة، بالبكسل.
• y: Integer — الموضع الرأسي المراد النقر عليه نقرًا مزدوجًا على الشاشة، بالبكسل.
• button: Integer — ثابت MouseButton، مثل MouseButton.Primary. يتبع Primary وSecondary إعداد تبديل الأزرار في Windows؛ أما Left وRight فهما الزران الفعليان.

القيمة المُرجَعة

true إذا تم إرسال النقرتين كلتيهما؛ false إذا تعذّر نقل المؤشر إلى النقطة، وعندئذ لا يُنقر شيء، أو إذا حظر Windows النقرتين.الزر غير المعروف يوقف البرنامج النصي بخطأ.

MouseGetCursorX

MouseGetCursorX() → Integer

يُرجع الموضع الأفقي لمؤشر الماوس على الشاشة.

المعلمات

لا توجد معلمات.

القيمة المُرجَعة

الموضع x للمؤشر بوحدات بكسل الشاشة؛ سالب على شاشة تقع يسار الشاشة الرئيسية.

٨ أمثلة: سلسلة else-if, تحريك الماوس في دائرة, قراءة لون البكسل أسفل المؤشر, محاذاة نافذة إلى خلية في شبكة 3×2 أسفل المؤشر, وصف ما يوجد أسفل المؤشر, النقر في مكان ما، ثم إعادة المؤشر, سحب ببرنامج نصي, النقر مع Shift

MouseGetCursorY

MouseGetCursorY() → Integer

يُرجع الموضع الرأسي لمؤشر الماوس على الشاشة.

المعلمات

لا توجد معلمات.

القيمة المُرجَعة

الموضع y للمؤشر بوحدات بكسل الشاشة؛ سالب على شاشة تقع أعلى الشاشة الرئيسية.

٨ أمثلة: سلسلة else-if, تحريك الماوس في دائرة, قراءة لون البكسل أسفل المؤشر, محاذاة نافذة إلى خلية في شبكة 3×2 أسفل المؤشر, وصف ما يوجد أسفل المؤشر, النقر في مكان ما، ثم إعادة المؤشر, سحب ببرنامج نصي, النقر مع Shift

MouseIsButtonDown

MouseIsButtonDown(button: Integer) → Bool

يتحقق مما إذا كان زر ماوس مضغوطًا باستمرار في هذه اللحظة.

المعلمات

• button: Integer — ثابت MouseButton، مثل MouseButton.Primary. يتبع Primary وSecondary إعداد تبديل الأزرار في Windows؛ أما Left وRight فهما الزران الفعليان.

القيمة المُرجَعة

true إذا كان الزر مضغوطًا؛ false إذا كان محرَّرًا. الزر غير المعروف يوقف البرنامج النصي بخطأ.

MouseLockToRect

MouseLockToRect(x: Integer, y: Integer, width: Integer, height: Integer) → Bool

يحصر مؤشر الماوس داخل مستطيل على الشاشة. يستمر القفل بعد انتهاء البرنامج النصي حتى يُستدعى MouseUnlock أو يغيّره برنامج آخر، لذا ألغِ القفل دائمًا عند الانتهاء.

المعلمات

• x: Integer — الحافة اليسرى للمستطيل، بوحدات بكسل الشاشة.
• y: Integer — الحافة العلوية للمستطيل، بوحدات بكسل الشاشة.
• width: Integer — عرض المستطيل، بالبكسل. يجب أن يكون أكبر من 0.
• height: Integer — ارتفاع المستطيل، بالبكسل. يجب أن يكون أكبر من 0.

القيمة المُرجَعة

true إذا أصبح المؤشر محصورًا الآن؛ false إذا لم يكن العرض أو الارتفاع موجبًا أو رفض Windows ذلك.

١ مثال: حصر المؤشر داخل نافذة لمدة 5 ثوانٍ

MouseMoveTo

MouseMoveTo(x: Integer, y: Integer) → Bool · بسيط

ينقل مؤشر الماوس إلى نقطة على الشاشة على أي شاشة، كما لو أن المستخدم حرّك الماوس.

المعلمات

• x: Integer — الموضع الأفقي على الشاشة، بالبكسل.
• y: Integer — الموضع الرأسي على الشاشة، بالبكسل.

القيمة المُرجَعة

true إذا تم إرسال الحركة؛ false إذا حظرها Windows.

٣ أمثلة: تحريك الماوس في دائرة, النقر في مكان ما، ثم إعادة المؤشر, سحب ببرنامج نصي

MouseScrollHorizontal

MouseScrollHorizontal(amount: Integer) → Bool · بسيط

يدير عجلة الماوس الأفقية عند موضع المؤشر الحالي. استخدم MouseMoveTo أولًا للتمرير في مكان آخر.

المعلمات

• amount: Integer — مسافة العجلة، حيث 120 تساوي درجة واحدة: القيمة الموجبة تمرّر لليمين، والسالبة تمرّر لليسار. القيم الأصغر تمرّر بدقة أكبر في التطبيقات التي تدعم ذلك.

القيمة المُرجَعة

true إذا تم إرسال التمرير؛ false إذا حظره Windows.

١ مثال: التمرير بالدرجات

MouseScrollVertical

MouseScrollVertical(amount: Integer) → Bool · بسيط

يدير عجلة الماوس الرأسية عند موضع المؤشر الحالي. استخدم MouseMoveTo أولًا للتمرير في مكان آخر.

المعلمات

• amount: Integer — مسافة العجلة، حيث 120 تساوي درجة واحدة: القيمة الموجبة تمرّر لأعلى، والسالبة تمرّر لأسفل. القيم الأصغر تمرّر بدقة أكبر في التطبيقات التي تدعم ذلك.

القيمة المُرجَعة

true إذا تم إرسال التمرير؛ false إذا حظره Windows.

١ مثال: التمرير بالدرجات

MouseUnlock

MouseUnlock() → Bool

يحرر مؤشر الماوس من أي حصر، سواء عيّنه MouseLockToRect أو برنامج آخر.

المعلمات

لا توجد معلمات.

القيمة المُرجَعة

true إذا أصبح المؤشر حرًا؛ false إذا رفض Windows ذلك.

١ مثال: حصر المؤشر داخل نافذة لمدة 5 ثوانٍ

Multimedia

MultimediaGetMute

MultimediaGetMute(endpoint: Integer) → Bool

يُبلغ عما إذا كان جهاز التشغيل الافتراضي أو الميكروفون الذي يحدده endpoint مكتوم الصوت في Windows.

المعلمات

• endpoint: Integer — الجهاز المراد فحصه: AudioEndpoint.Playback (السماعات أو سماعات الرأس الافتراضية)، أو AudioEndpoint.Capture (الميكروفون الافتراضي)، أو AudioEndpoint.Communications (الميكروفون الذي يستخدمه Windows للمكالمات). أي قيمة أخرى توقف الإجراء بخطأ.

القيمة المُرجَعة

true إذا كان الجهاز مكتوم الصوت؛ false إذا لم يكن مكتوم الصوت أو لم يكن موجودًا (مثلًا، لا يوجد ميكروفون متصل).

١ مثال: تبديل كتم الميكروفون

MultimediaGetVolume

MultimediaGetVolume(endpoint: Integer) → Real

يُرجع مستوى الصوت الرئيسي لجهاز التشغيل الافتراضي أو الميكروفون الذي يحدده endpoint، كقيمة Real من 0.0 إلى 1.0.

المعلمات

• endpoint: Integer — الجهاز المراد قراءته: AudioEndpoint.Playback (السماعات أو سماعات الرأس الافتراضية)، أو AudioEndpoint.Capture (الميكروفون الافتراضي)، أو AudioEndpoint.Communications (الميكروفون الذي يستخدمه Windows للمكالمات). أي قيمة أخرى توقف الإجراء بخطأ.

القيمة المُرجَعة

مستوى الصوت من 0.0 (صامت) إلى 1.0 (كامل)، بالمقياس نفسه الذي يستخدمه MultimediaSetVolume؛ 0.0 إذا لم يكن الجهاز موجودًا.

١ مثال: رفع مستوى الصوت مع عرض على الشاشة

MultimediaPlayMp3File

MultimediaPlayMp3File(path: Text) → Bool · بسيط

يبدأ تشغيل ملف MP3 ويعود فورًا أثناء تشغيله. يؤدي بدء تشغيل ملف MP3 آخر إلى إيقاف الملف الذي لا يزال قيد التشغيل.

المعلمات

• path: Text — المسار الكامل لملف .mp3، مثل C:/Music/done.mp3.

القيمة المُرجَعة

true إذا بدأ التشغيل؛ false إذا كان الملف مفقودًا، أو تعذّر على Windows فتحه أو تشغيله خلال 10 ثوانٍ، أو أنهى «إيقاف الكل» الانتظار.

MultimediaPlayWavFile

MultimediaPlayWavFile(path: Text) → Bool · بسيط

يبدأ تشغيل ملف صوت .wav ويعود فورًا أثناء تشغيله. يؤدي بدء تشغيل ملف WAV آخر إلى إيقاف الملف الذي لا يزال قيد التشغيل. تعمل ملفات .wav فقط؛ استخدم MultimediaPlayMp3File لملفات MP3.

المعلمات

• path: Text — المسار الكامل لملف .wav، مثل C:/Windows/Media/chimes.wav.

القيمة المُرجَعة

true إذا كان الملف موجودًا وبدأ التشغيل؛ false إذا لم يكن هناك ملف في ذلك المسار. الملف الموجود الذي ليس ملف WAV قابلًا للتشغيل يُرجع true ولا يشغّل شيئًا.

١ مثال: تشغيل صوت

MultimediaSetMute

MultimediaSetMute(endpoint: Integer, muted: Bool) → Bool · بسيط

يكتم صوت جهاز التشغيل الافتراضي أو الميكروفون الذي يحدده endpoint أو يلغي كتمه، كما يفعل زر كتم الصوت في عنصر التحكم بمستوى الصوت في Windows.

المعلمات

• endpoint: Integer — الجهاز المراد تغييره: AudioEndpoint.Playback (السماعات أو سماعات الرأس الافتراضية)، أو AudioEndpoint.Capture (الميكروفون الافتراضي)، أو AudioEndpoint.Communications (الميكروفون الذي يستخدمه Windows للمكالمات). أي قيمة أخرى توقف الإجراء بخطأ.
• muted: Bool — true لكتم صوت الجهاز؛ false لإلغاء كتمه.

القيمة المُرجَعة

true إذا تم تعيين حالة الكتم؛ false إذا لم يكن الجهاز موجودًا أو رفض التغيير.

١ مثال: مفتاح تبديل يبقى بين مرات التشغيل

MultimediaSetVolume

MultimediaSetVolume(endpoint: Integer, level: Real) → Bool · بسيط

يعيّن مستوى الصوت الرئيسي لجهاز التشغيل الافتراضي أو الميكروفون الذي يحدده endpoint إلى مستوى محدد بدقة.

المعلمات

• endpoint: Integer — الجهاز المراد تغييره: AudioEndpoint.Playback (السماعات أو سماعات الرأس الافتراضية)، أو AudioEndpoint.Capture (الميكروفون الافتراضي)، أو AudioEndpoint.Communications (الميكروفون الذي يستخدمه Windows للمكالمات). أي قيمة أخرى توقف الإجراء بخطأ.
• level: Real — مستوى الصوت الجديد من 0.0 (صامت) إلى 1.0 (كامل)؛ القيمة 0.5 تقابل 50 على شريط تمرير مستوى الصوت في Windows. تُقيَّد القيم الواقعة خارج النطاق من 0.0 إلى 1.0 بحدوده.

القيمة المُرجَعة

true إذا تم تعيين مستوى الصوت؛ false إذا لم يكن الجهاز موجودًا أو رفض التغيير.

٢ مثالان: رفع مستوى الصوت مع عرض على الشاشة, تحويل مقبض Arduino إلى عنصر تحكم في مستوى الصوت

MultimediaToggleMute

MultimediaToggleMute(endpoint: Integer) → Bool · بسيط

يكتم صوت جهاز التشغيل الافتراضي أو الميكروفون الذي يحدده endpoint إذا لم يكن مكتومًا، أو يلغي كتمه إذا كان مكتومًا. استدعِ MultimediaGetMute بعد ذلك لمعرفة الحالة الجديدة.

المعلمات

• endpoint: Integer — الجهاز المراد تبديل حالته: AudioEndpoint.Playback (السماعات أو سماعات الرأس الافتراضية)، أو AudioEndpoint.Capture (الميكروفون الافتراضي)، أو AudioEndpoint.Communications (الميكروفون الذي يستخدمه Windows للمكالمات). أي قيمة أخرى توقف الإجراء بخطأ.

القيمة المُرجَعة

true إذا تم تبديل حالة الكتم؛ false إذا لم يكن الجهاز موجودًا أو رفض التغيير. هذه ليست حالة الكتم الجديدة.

١ مثال: تبديل كتم الميكروفون

Plugin

PluginSendMessage

PluginSendMessage(pluginName: Text, message: Text, timeoutSeconds: Integer) → Text

يرسل رسالة نصية إلى مكوّن إضافي قيد التشغيل يقبل الأوامر وينتظر رده. يعالج المكوّن الإضافي رسالة واحدة في كل مرة؛ والرسائل المرسلة أثناء انشغاله تنتظر في قائمة انتظار.

المعلمات

• pluginName: Text — الاسم المعروض للمكوّن الإضافي، مطابَقًا تمامًا، بما في ذلك حالة الأحرف.
• message: Text — النص المراد إرساله. يحدد المكوّن الإضافي معناه.
• timeoutSeconds: Integer — مدة انتظار الرد، بالثواني، من 0 إلى 10؛ أي قيمة أخرى توقف البرنامج النصي بخطأ. مع القيمة 0 يعود الاستدعاء فورًا بنص فارغ.

القيمة المُرجَعة

رد المكوّن الإضافي، أو نص فارغ إذا لم يرد في الوقت المحدد. عدم وجود مكوّن إضافي كهذا قيد التشغيل، أو امتلاء قائمة الانتظار، أو رسالة طويلة جدًا يوقف البرنامج النصي بخطأ.

١ مثال: التواصل مع مكوّن إضافي

Region

RegionGetCellIndexAt

RegionGetCellIndexAt(rectX: Integer, rectY: Integer, rectWidth: Integer, rectHeight: Integer, columns: Integer, rows: Integer, pointX: Integer, pointY: Integer) → Integer

يقسّم مستطيلًا إلى شبكة من الأعمدة والصفوف ويُرجع الخلية التي تحتوي على نقطة. تُرقَّم الخلايا بدءًا من 0، من اليسار إلى اليمين، ثم من الأعلى إلى الأسفل.

المعلمات

• rectX: Integer — الحافة اليسرى للمستطيل المراد تقسيمه، بالبكسل.
• rectY: Integer — الحافة العلوية للمستطيل المراد تقسيمه، بالبكسل.
• rectWidth: Integer — عرض المستطيل، بالبكسل. يجب أن يكون أكبر من 0.
• rectHeight: Integer — ارتفاع المستطيل، بالبكسل. يجب أن يكون أكبر من 0.
• columns: Integer — عدد الأعمدة في الشبكة. يجب أن يكون أكبر من 0. تُوزَّع وحدات البكسل المتبقية بواقع بكسل واحد لكل عمود من الأعمدة الأولى.
• rows: Integer — عدد الصفوف في الشبكة. يجب أن يكون أكبر من 0. تُوزَّع وحدات البكسل المتبقية بواقع بكسل واحد لكل صف من الصفوف الأولى.
• pointX: Integer — الموضع الأفقي للنقطة المراد البحث عنها، بوحدات البكسل نفسها المستخدمة في rectX.
• pointY: Integer — الموضع الرأسي للنقطة المراد البحث عنها، بوحدات البكسل نفسها المستخدمة في rectY.

القيمة المُرجَعة

رقم الخلية (رقم الصف مضروبًا في عدد الأعمدة، زائد رقم العمود)، أو -1 إذا كانت النقطة خارج المستطيل أو لم تكن rectWidth أو rectHeight أو columns أو rows موجبة.

١ مثال: محاذاة نافذة إلى خلية في شبكة 3×2 أسفل المؤشر

RegionGetHeight

RegionGetHeight(rectX: Integer, rectY: Integer, rectWidth: Integer, rectHeight: Integer, columns: Integer, rows: Integer, index: Integer) → Integer

يُرجع ارتفاع خلية واحدة عند تقسيم مستطيل إلى شبكة من الأعمدة والصفوف. تُوزَّع وحدات البكسل المتبقية بواقع بكسل واحد لكل صف من الصفوف الأولى.

المعلمات

• rectX: Integer — الحافة اليسرى للمستطيل المراد تقسيمه، بالبكسل.
• rectY: Integer — الحافة العلوية للمستطيل المراد تقسيمه، بالبكسل.
• rectWidth: Integer — عرض المستطيل، بالبكسل. يجب أن يكون أكبر من 0.
• rectHeight: Integer — ارتفاع المستطيل، بالبكسل. يجب أن يكون أكبر من 0.
• columns: Integer — عدد الأعمدة في الشبكة. يجب أن يكون أكبر من 0.
• rows: Integer — عدد الصفوف في الشبكة. يجب أن يكون أكبر من 0.
• index: Integer — رقم الخلية بدءًا من الصفر، يُعد من اليسار إلى اليمين، ثم من الأعلى إلى الأسفل، من 0 إلى عدد الأعمدة مضروبًا في عدد الصفوف ناقص 1.

القيمة المُرجَعة

ارتفاع الخلية بالبكسل، أو -1 إذا كان index خارج النطاق أو لم تكن rectWidth أو rectHeight أو columns أو rows موجبة.

١ مثال: محاذاة نافذة إلى خلية في شبكة 3×2 أسفل المؤشر

RegionGetWidth

RegionGetWidth(rectX: Integer, rectY: Integer, rectWidth: Integer, rectHeight: Integer, columns: Integer, rows: Integer, index: Integer) → Integer

يُرجع عرض خلية واحدة عند تقسيم مستطيل إلى شبكة من الأعمدة والصفوف. تُوزَّع وحدات البكسل المتبقية بواقع بكسل واحد لكل عمود من الأعمدة الأولى.

المعلمات

• rectX: Integer — الحافة اليسرى للمستطيل المراد تقسيمه، بالبكسل.
• rectY: Integer — الحافة العلوية للمستطيل المراد تقسيمه، بالبكسل.
• rectWidth: Integer — عرض المستطيل، بالبكسل. يجب أن يكون أكبر من 0.
• rectHeight: Integer — ارتفاع المستطيل، بالبكسل. يجب أن يكون أكبر من 0.
• columns: Integer — عدد الأعمدة في الشبكة. يجب أن يكون أكبر من 0.
• rows: Integer — عدد الصفوف في الشبكة. يجب أن يكون أكبر من 0.
• index: Integer — رقم الخلية بدءًا من الصفر، يُعد من اليسار إلى اليمين، ثم من الأعلى إلى الأسفل، من 0 إلى عدد الأعمدة مضروبًا في عدد الصفوف ناقص 1.

القيمة المُرجَعة

عرض الخلية بالبكسل، أو -1 إذا كان index خارج النطاق أو لم تكن rectWidth أو rectHeight أو columns أو rows موجبة.

١ مثال: محاذاة نافذة إلى خلية في شبكة 3×2 أسفل المؤشر

RegionGetX

RegionGetX(rectX: Integer, rectY: Integer, rectWidth: Integer, rectHeight: Integer, columns: Integer, rows: Integer, index: Integer) → Integer

يُرجع الحافة اليسرى لخلية واحدة عند تقسيم مستطيل إلى شبكة من الأعمدة والصفوف. تُوزَّع وحدات البكسل المتبقية بواقع بكسل واحد لكل عمود من الأعمدة الأولى.

المعلمات

• rectX: Integer — الحافة اليسرى للمستطيل المراد تقسيمه، بالبكسل.
• rectY: Integer — الحافة العلوية للمستطيل المراد تقسيمه، بالبكسل.
• rectWidth: Integer — عرض المستطيل، بالبكسل. يجب أن يكون أكبر من 0.
• rectHeight: Integer — ارتفاع المستطيل، بالبكسل. يجب أن يكون أكبر من 0.
• columns: Integer — عدد الأعمدة في الشبكة. يجب أن يكون أكبر من 0.
• rows: Integer — عدد الصفوف في الشبكة. يجب أن يكون أكبر من 0.
• index: Integer — رقم الخلية بدءًا من الصفر، يُعد من اليسار إلى اليمين، ثم من الأعلى إلى الأسفل، من 0 إلى عدد الأعمدة مضروبًا في عدد الصفوف ناقص 1.

القيمة المُرجَعة

الحافة اليسرى للخلية، أو -1 إذا كان index خارج النطاق أو لم تكن rectWidth أو rectHeight أو columns أو rows موجبة. قد تبدأ خلية حقيقية أيضًا عند -1، لذا تحقق من index أولًا.

١ مثال: محاذاة نافذة إلى خلية في شبكة 3×2 أسفل المؤشر

RegionGetY

RegionGetY(rectX: Integer, rectY: Integer, rectWidth: Integer, rectHeight: Integer, columns: Integer, rows: Integer, index: Integer) → Integer

يُرجع الحافة العلوية لخلية واحدة عند تقسيم مستطيل إلى شبكة من الأعمدة والصفوف. تُوزَّع وحدات البكسل المتبقية بواقع بكسل واحد لكل صف من الصفوف الأولى.

المعلمات

• rectX: Integer — الحافة اليسرى للمستطيل المراد تقسيمه، بالبكسل.
• rectY: Integer — الحافة العلوية للمستطيل المراد تقسيمه، بالبكسل.
• rectWidth: Integer — عرض المستطيل، بالبكسل. يجب أن يكون أكبر من 0.
• rectHeight: Integer — ارتفاع المستطيل، بالبكسل. يجب أن يكون أكبر من 0.
• columns: Integer — عدد الأعمدة في الشبكة. يجب أن يكون أكبر من 0.
• rows: Integer — عدد الصفوف في الشبكة. يجب أن يكون أكبر من 0.
• index: Integer — رقم الخلية بدءًا من الصفر، يُعد من اليسار إلى اليمين، ثم من الأعلى إلى الأسفل، من 0 إلى عدد الأعمدة مضروبًا في عدد الصفوف ناقص 1.

القيمة المُرجَعة

الحافة العلوية للخلية، أو -1 إذا كان index خارج النطاق أو لم تكن rectWidth أو rectHeight أو columns أو rows موجبة. قد تبدأ خلية حقيقية أيضًا عند -1، لذا تحقق من index أولًا.

١ مثال: محاذاة نافذة إلى خلية في شبكة 3×2 أسفل المؤشر

Serial

SerialClosePort

SerialClosePort(port: Text) → Bool

يغلق منفذ COM مفتوحًا باستخدام SerialOpenPort، فيحرره لبرامج أخرى مثل Arduino IDE. يتم تجاهل الأسطر المستلَمة التي لم تُقرأ بعد.

المعلمات

• port: Text — اسم المنفذ الذي مُرِّر إلى SerialOpenPort، مثل COM3. حالة الأحرف غير مهمة.

القيمة المُرجَعة

true إذا كان المنفذ مفتوحًا وأصبح مغلقًا الآن؛ false إذا لم يكن مفتوحًا، أو كان مراقب تسلسلي يحتجزه (استخدم SerialMonitorDelete).

١ مثال: طرح سؤال على جهاز تسلسلي

SerialEnumeratePorts

SerialEnumeratePorts() → Integer

يعثر على المنافذ التسلسلية (COM) في هذا الكمبيوتر، مثل Arduino أو ESP32 أو محوّل من USB إلى تسلسلي موصول عبر USB، ويُرجع عددها. اقرأ كل اسم باستخدام SerialGetEnumeratedPortAt.

المعلمات

لا توجد معلمات.

القيمة المُرجَعة

عدد منافذ COM التي عُثر عليها، أو 0 إذا لم توجد أي منها.

١ مثال: سرد منافذ COM

SerialGetEnumeratedPortAt

SerialGetEnumeratedPortAt(index: Integer) → Text

يُرجع اسم منفذ واحد، مثل COM3، من القائمة التي أنشأها آخر استدعاء لـ SerialEnumeratePorts في تشغيل البرنامج النصي هذا. تعرض «إدارة الأجهزة» الجهاز الموجود على كل منفذ.

المعلمات

• index: Integer — الموضع في القائمة، من 0 إلى العدد ناقص 1. تُفرز الأسماء حسب الرقم، لذا يأتي COM3 قبل COM10.

القيمة المُرجَعة

اسم المنفذ، أو نص فارغ إذا كان index خارج النطاق أو لم يتم استدعاء SerialEnumeratePorts.

١ مثال: سرد منافذ COM

SerialGetTextLine

SerialGetTextLine(port: Text, timeoutSeconds: Integer, baudRate: Integer) → Text

ينتظر السطر الكامل التالي من منفذ COM ويُرجعه، مثل قراءة مستشعر أو مسح رمز شريطي أو رد جهاز. يحظر البرنامج النصي لمدة تصل إلى timeoutSeconds؛ ويُنهي «إيقاف الكل» الانتظار.

المعلمات

• port: Text — اسم المنفذ، مثل COM3. افتحه أولًا باستخدام SerialOpenPort لاختيار الإعدادات وللاحتفاظ بالأسطر التي تصل مبكرًا؛ وإلا فإنه يُفتح بسرعة baudRate لهذا الانتظار فقط.
• timeoutSeconds: Integer — أطول مدة للانتظار، بالثواني. القيمة 0 تنتظر حتى يصل سطر أو يتم إيقاف البرنامج النصي. القيمة السالبة توقف البرنامج النصي بخطأ.
• baudRate: Integer — السرعة بالبت في الثانية، وتُستخدم فقط عندما يفتح هذا الاستدعاء المنفذ بنفسه، مثل 9600 أو 115200؛ ويتم تجاهلها لمنفذ مفتوح باستخدام SerialOpenPort. القيمة 0 أو أقل توقف البرنامج النصي بخطأ.

القيمة المُرجَعة

السطر بدون فاصل نهايته، أو نص فارغ إذا لم يصل أي سطر في الوقت المحدد، أو تعذّر فتح المنفذ، أو فُصل الجهاز. يوقف البرنامج النصي بخطأ إذا كان مراقب تسلسلي يحتجز المنفذ.

٢ مثالان: طرح سؤال على جهاز تسلسلي, إبقاء منفذ Arduino مفتوحًا وإرسال الأوامر إليه

SerialMonitorCreate

SerialMonitorCreate(name: Text, port: Text, baudRate: Integer, parity: Integer, dataBits: Integer, stopBits: Integer, terminator: Text, script: Text) → Bool

يفتح منفذ COM ويشغّل برنامجًا نصيًا لكل سطر يرسله الجهاز، مثلًا لتحويل صندوق أزرار Arduino أو لوحة ماكرو إلى اختصارات. يستمر المراقب في العمل بعد انتهاء هذا البرنامج النصي. يوقف «إيقاف الكل» البرنامج النصي الذي يعمل لسطر ويتخلص من الأسطر المنتظرة؛ ويستمر المراقب في العمل.

المعلمات

• name: Text — اسم للمراقب. إعادة استخدام اسم المراقب الحالي لهذا المنفذ تستبدله؛ والاسم الذي يراقب منفذًا آخر بالفعل يوقف البرنامج النصي بخطأ. حالة الأحرف غير مهمة.
• port: Text — اسم المنفذ، مثل COM3. تعرض «إدارة الأجهزة» المنفذ الذي توجد عليه اللوحة.
• baudRate: Integer — السرعة بالبت في الثانية. يجب أن تطابق الجهاز، مثل 9600 أو 115200 في Serial.begin ضمن برنامج Arduino.
• parity: Integer — ثابت SerialParity. تستخدم معظم الأجهزة، بما فيها لوحات Arduino، القيمة SerialParity.None.
• dataBits: Integer — عدد البتات لكل حرف، كرقم عادي. تستخدم كل الأجهزة تقريبًا 8.
• stopBits: Integer — ثابت SerialStopBits، عادةً SerialStopBits.One. استخدم الثابت: فالرقم العادي 1 يعني بت توقف ونصف.
• terminator: Text — النص الذي ينهي كل سطر: يُزال من الأسطر المستلَمة ويُضاف إلى كل سطر يرسله SerialWriteTextLine. النص الفارغ يعني CR LF، وهو ما يرسله Serial.println في Arduino. استخدم '\n' للأجهزة التي تنهي الأسطر بـ LF فقط، أو '\r' لـ CR فقط.
• script: Text — البرنامج النصي المراد تشغيله لكل سطر مستلَم، كقيمة Text. يقرأ السطر باستخدام ContextGetSerialTextLine. تُعالَج الأسطر واحدًا تلو الآخر بترتيب وصولها؛ ينتظر ما يصل إلى 256 سطرًا أثناء تشغيل البرنامج النصي، وبعد ذلك يُتخلَّص من الأقدم.

القيمة المُرجَعة

true بمجرد أن يصبح المراقب قيد التشغيل؛ false إذا كان المنفذ مفقودًا أو مفصولًا أو يستخدمه برنامج آخر. يوقف البرنامج النصي بخطأ إذا كان المنفذ مفتوحًا باستخدام SerialOpenPort أو مراقَبًا باسم آخر، أو كان هذا الاسم يراقب منفذًا آخر بالفعل. يؤدي فصل الجهاز إلى إنهاء المراقب وتسجيل سطر في علامة التبويب «النظام» في وحدة التحكم.

٢ مثالان: ربط أزرار جهاز تسلسلي بمفاتيح الوسائط, تحويل مقبض Arduino إلى عنصر تحكم في مستوى الصوت

SerialMonitorDelete

SerialMonitorDelete(name: Text) → Bool

يوقف مراقبًا تسلسليًا أُنشئ باستخدام SerialMonitorCreate ويغلق منفذ COM الخاص به، حتى تتمكن البرامج الأخرى من استخدام المنفذ مرة أخرى. يُتخلَّص من الأسطر التي لم تُعالَج بعد؛ ويكتمل البرنامج النصي الذي يعمل بالفعل.

المعلمات

• name: Text — الاسم الذي مُرِّر إلى SerialMonitorCreate. حالة الأحرف غير مهمة.

القيمة المُرجَعة

true إذا عُثر على مراقب بهذا الاسم وتم إيقافه؛ false إذا لم يوجد أي مراقب.

SerialMonitorDeleteAll

SerialMonitorDeleteAll() → Bool

يوقف كل المراقبات التسلسلية ويغلق منافذ COM الخاصة بها. تظل المنافذ المفتوحة باستخدام SerialOpenPort مفتوحة.

المعلمات

لا توجد معلمات.

القيمة المُرجَعة

true دائمًا.

SerialMonitorGetCount

SerialMonitorGetCount() → Integer

يُرجع عدد المراقبات التسلسلية قيد التشغيل ويلتقط لقطة لأسمائها من أجل SerialMonitorGetEnumeratedNameAt.

المعلمات

لا توجد معلمات.

القيمة المُرجَعة

عدد المراقبات التسلسلية قيد التشغيل، أو 0 إذا لم توجد أي منها.

SerialMonitorGetEnumeratedNameAt

SerialMonitorGetEnumeratedNameAt(index: Integer) → Text

يُرجع اسم مراقب واحد من اللقطة التي التقطها آخر استدعاء لـ SerialMonitorGetCount في تشغيل البرنامج النصي هذا.

المعلمات

• index: Integer — الموضع في اللقطة، من 0 إلى العدد ناقص 1. لا معنى للترتيب.

القيمة المُرجَعة

اسم المراقب، أو نص فارغ إذا كان index خارج النطاق أو لم يتم استدعاء SerialMonitorGetCount.

SerialOpenPort

SerialOpenPort(port: Text, baudRate: Integer, parity: Integer, dataBits: Integer, stopBits: Integer, terminator: Text) → Bool

يفتح منفذ COM ويبقيه مفتوحًا حتى SerialClosePort، ويجمع كل سطر مستلَم من أجل SerialGetTextLine. يؤدي الفتح إلى تشغيل إشارتي DTR وRTS، مما يعيد تشغيل كثير من لوحات Arduino تمامًا كما يفعل Arduino IDE، لذا افتحه مرة واحدة وأعد استخدامه.

المعلمات

• port: Text — اسم المنفذ، مثل COM3. تعرضه «إدارة الأجهزة» أو SerialEnumeratePorts. النص الفارغ يوقف البرنامج النصي بخطأ.
• baudRate: Integer — السرعة بالبت في الثانية. يجب أن تطابق الجهاز، مثل 9600 أو 115200 في Serial.begin ضمن برنامج Arduino.
• parity: Integer — ثابت SerialParity. تستخدم معظم الأجهزة، بما فيها لوحات Arduino، القيمة SerialParity.None.
• dataBits: Integer — عدد البتات لكل حرف، كرقم عادي. تستخدم كل الأجهزة تقريبًا 8.
• stopBits: Integer — ثابت SerialStopBits، عادةً SerialStopBits.One. استخدم الثابت: فالرقم العادي 1 يعني بت توقف ونصف.
• terminator: Text — النص الذي ينهي كل سطر: يُزال من الأسطر المستلَمة ويُضاف إلى كل سطر يرسله SerialWriteTextLine. النص الفارغ يعني CR LF، وهو ما يرسله Serial.println في Arduino. استخدم '\n' للأجهزة التي تنهي الأسطر بـ LF فقط، أو '\r' لـ CR فقط.

القيمة المُرجَعة

true إذا كان المنفذ مفتوحًا؛ false إذا كان مفقودًا، أو مفصولًا، أو قيد الاستخدام من برنامج آخر مثل مراقب تسلسلي، أو رفض الإعدادات. يوقف البرنامج النصي بخطأ إذا كان Input.Observer قد فتح المنفذ بالفعل أو كان مراقب تسلسلي يحتجزه.

٢ مثالان: طرح سؤال على جهاز تسلسلي, إبقاء منفذ Arduino مفتوحًا وإرسال الأوامر إليه

SerialWriteTextLine

SerialWriteTextLine(port: Text, text: Text, baudRate: Integer) → Bool

يرسل سطرًا نصيًا متبوعًا بنهاية السطر الخاصة بالمنفذ إلى منفذ COM، مثل أمر لـ Arduino أو سطر G-code لطابعة ثلاثية الأبعاد. يعمل على منفذ مفتوح باستخدام SerialOpenPort أو يحتجزه مراقب تسلسلي، بحيث يستطيع البرنامج النصي للمراقب الرد على جهازه. المنفذ غير المفتوح يُفتح بسرعة baudRate، 8-N-1، لعملية الكتابة هذه فقط.

المعلمات

• port: Text — اسم المنفذ، مثل COM3. افتحه أولًا باستخدام SerialOpenPort لاختيار الإعدادات ولتجنب إعادة تشغيل اللوحات التي تُعاد تهيئتها عند فتح المنفذ.
• text: Text — السطر المراد إرساله، مرمَّزًا بـ UTF-8. لا تُضف نهاية سطر: يُضاف terminator الذي فُتح به المنفذ، أو CR LF عندما يفتح هذا الاستدعاء المنفذ بنفسه.
• baudRate: Integer — السرعة بالبت في الثانية، وتُستخدم فقط عندما يفتح هذا الاستدعاء المنفذ بنفسه، مثل 9600 أو 115200؛ ويتم تجاهلها لمنفذ مفتوح بالفعل أو مراقَب. القيمة 0 أو أقل توقف البرنامج النصي بخطأ.

القيمة المُرجَعة

true إذا تم إرسال السطر؛ false إذا تعذّر فتح المنفذ أو فشلت الكتابة أو انتهت مهلتها.

٢ مثالان: طرح سؤال على جهاز تسلسلي, إبقاء منفذ Arduino مفتوحًا وإرسال الأوامر إليه

Shell

ShellEmptyRecycleBins

ShellEmptyRecycleBins() → Bool · بسيط

يحذف نهائيًا كل ما في سلة المحذوفات على كل محرك أقراص، دون طلب تأكيد. لا يمكن التراجع عن ذلك.

المعلمات

لا توجد معلمات.

القيمة المُرجَعة

true إذا تم إفراغ سلال المحذوفات أو كانت فارغة بالفعل؛ وإلا false.

ShellEnumerateProcessIdsByExeRegex

ShellEnumerateProcessIdsByExeRegex(pattern: Text) → Integer

يعثر على كل عملية قيد التشغيل يطابق اسم ملف برنامجها، مثل notepad.exe، تعبيرًا عاديًا، ويُرجع عددها. اقرأ كل معرّف عملية باستخدام ShellGetEnumeratedProcessIdAt.

المعلمات

• pattern: Text — تعبير عادي، تتم مطابقته دون مراعاة حالة الأحرف مع اسم الملف فقط، لا المسار الكامل. استخدم ^ و$ لمطابقة الاسم كاملًا، مثل ^notepad[.]exe$.

القيمة المُرجَعة

عدد العمليات المطابقة، أو 0 إذا لم تتطابق أي عملية. النمط غير الصالح يوقف البرنامج النصي بخطأ.

١ مثال: من العملية إلى النافذة

ShellExpandEnvironmentVariables

ShellExpandEnvironmentVariables(text: Text) → Text

يستبدل كل متغير بيئة في النص، مكتوبًا كاسم بين علامتي نسبة مئوية مثل USERPROFILE أو TEMP، بقيمته. مفيد لإنشاء مسارات تعمل على أي كمبيوتر.

المعلمات

• text: Text — نص يحتوي على أسماء متغيرات بيئة بين علامتي نسبة مئوية، مثل مسار في مجلد ملف تعريف المستخدم.

القيمة المُرجَعة

النص بعد استبدال كل متغير معروف؛ وتُترك المتغيرات غير المعروفة كما كُتبت. نص فارغ إذا فشل التوسيع.

٨ أمثلة: تاريخ اليوم، واسم ملف مختوم بالوقت, لقطة شاشة للمنطقة التي أحطتها بدائرة, حفظ صورة منسوخة في ملف, الإلحاق بملف سجل, عدّ أنواع الملفات في مجلد, نسخ ملف احتياطيًا قبل تحريره, مراقبة مجلد, توسيع متغيرات البيئة

ShellGetEnumeratedProcessIdAt

ShellGetEnumeratedProcessIdAt(index: Integer) → Integer

يُرجع معرّف عملية واحدًا من القائمة التي أنشأها آخر استدعاء لـ ShellEnumerateProcessIdsByExeRegex في تشغيل البرنامج النصي هذا.

المعلمات

• index: Integer — الموضع في القائمة، من 0 إلى العدد ناقص 1.

القيمة المُرجَعة

معرّف العملية، أو 0 إذا كان index خارج النطاق أو لم يتم استدعاء ShellEnumerateProcessIdsByExeRegex.

١ مثال: من العملية إلى النافذة

ShellGetSystemMetricsByIndex

ShellGetSystemMetricsByIndex(index: Integer) → Integer

يُرجع قياسًا أو إعدادًا من قياسات نظام Windows بواسطة فهرس GetSystemMetrics الخاص به، مثل 0 لعرض الشاشة الرئيسية أو 80 لعدد الشاشات.

المعلمات

• index: Integer — رقم فهرس SM_ في Windows، مثل 0 (SM_CXSCREEN) أو 1 (SM_CYSCREEN). لا توجد ثوابت مسماة لهذه القيم.

القيمة المُرجَعة

القيمة التي يُبلغ عنها Windows، غالبًا بالبكسل، أو 0 لفهرس غير معروف.

ShellRun

ShellRun(command: Text) → Bool · بسيط

يشغّل برنامجًا أو يفتح ملفًا أو مجلدًا أو عنوان ويب، مثل كتابته في مربع «تشغيل» في Windows (Win+R). لا ينتظر انتهاء البرنامج.

المعلمات

• command: Text — اسم برنامج مثل notepad.exe، أو مسار، أو عنوان ويب، متبوعًا اختياريًا بوسيطات. ضع المسار الذي يحتوي على مسافات بين علامتي اقتباس مفردتين عندما تليه وسيطات.

القيمة المُرجَعة

true إذا بدأ Windows تشغيله؛ false إذا تعذّر العثور عليه أو بدء تشغيله. لا يُعرض مربع خطأ من Windows عند الفشل.

٤ أمثلة: حلقة while: انتظار نافذة، مع مهلة, تشغيل برنامج وانتظار نافذته والعمل عليها, البحث في الويب عن النص المحدد, البحث في الويب عن التحديد

ShellRunOrActivate

ShellRunOrActivate(exeName: Text) → Bool · بسيط

يُحضر نافذة برنامج إلى المقدمة إذا كان البرنامج قيد التشغيل بالفعل، أو يشغّل الأمر إذا لم يكن كذلك. مفيد لإيماءة تنقلك دائمًا إلى البرنامج نفسه.

المعلمات

• exeName: Text — اسم ملف البرنامج، مثل notepad أو notepad.exe، أو مساره الكامل، متبوعًا اختياريًا بوسيطات لا تُستخدم إلا عندما يلزم بدء تشغيله. تُطابَق النوافذ قيد التشغيل حسب اسم ملف الكلمة الأولى، مع إضافة .exe عندما لا يكون له امتداد؛ ضع المسار الذي يحتوي على مسافات بين علامتي اقتباس مفردتين.

القيمة المُرجَعة

true إذا تم إحضار نافذة إلى المقدمة أو بدأ تشغيل البرنامج؛ false إذا رفض Windows إحضار النافذة إلى المقدمة أو فشل بدء التشغيل.

١ مثال: تشغيل تطبيق أو التبديل إليه

ShellRunProgram

ShellRunProgram(path: Text, arguments: Text, verb: Any, windowStyle: Integer, waitForExit: Bool) → Bool

يشغّل برنامجًا أو يفتح ملفًا بإجراء مختار (فعل) ونمط نافذة، ويمكنه انتظار إغلاقه. استخدم ShellVerb.RunAs لتشغيل برنامج كمسؤول.

المعلمات

• path: Text — البرنامج أو المستند أو المجلد المراد فتحه، مثل notepad.exe أو مسار ملف كامل.
• arguments: Text — وسيطات سطر الأوامر للبرنامج، أو نص فارغ لعدم وجود أي وسيطات.
• verb: Any — ثابت ShellVerb، مثل ShellVerb.Open أو ShellVerb.Print، أو أي فعل يدعمه نوع الملف كقيمة Text. النص الفارغ يستخدم الإجراء الافتراضي.
• windowStyle: Integer — ثابت WindowStyle: WindowStyle.Normal أو WindowStyle.Minimized أو WindowStyle.Maximized أو WindowStyle.Hidden. أي قيمة أخرى توقف البرنامج النصي بخطأ. تتجاهله بعض البرامج.
• waitForExit: Bool — true لحظر البرنامج النصي حتى يُغلق البرنامج؛ يُنهي «إيقاف الكل» الانتظار ويترك البرنامج قيد التشغيل. false للمتابعة فورًا.

القيمة المُرجَعة

true إذا بدأ Windows تشغيله (وأُغلق، مع waitForExit)؛ false إذا تعذّر بدء تشغيله، أو تم رفض مطالبة المسؤول، أو أنهى «إيقاف الكل» الانتظار. لا يُعرض مربع خطأ من Windows عند الفشل.

٢ مثالان: تشغيل برنامج بفعل ونمط نافذة, التشغيل وانتظار الخروج

ShellRunStoreApp

ShellRunStoreApp(packageName: Text) → Bool · بسيط

يبدأ تشغيل تطبيق Microsoft Store مثبَّت بواسطة اسم حزمته، أو جزء منه، أو اسمه في قائمة «ابدأ»، مثل Microsoft.WindowsCalculator أو Calculator. لا تتم مطابقة برامج سطح المكتب العادية؛ استخدم ShellRun لها.

المعلمات

• packageName: Text — اسم عائلة حزمة التطبيق أو جزء منه، أو اسمه المطابق تمامًا في قائمة «ابدأ»، تتم مطابقته دون مراعاة حالة الأحرف. تفوز المطابقة التامة لاسم عائلة الحزمة، ثم المطابقة التامة لاسم قائمة «ابدأ»، ثم أول تطبيق يحتوي اسم عائلة حزمته على النص.

القيمة المُرجَعة

true إذا بدأ تشغيل التطبيق؛ false إذا كانت قيمة packageName فارغة، أو لم يتطابق أي تطبيق Store مثبَّت، أو فشل بدء التشغيل.

ShellShowToast

ShellShowToast(title: Text, message: Text) → Bool · بسيط

يعرض إعلامًا من Windows (إعلامًا منبثقًا) بعنوان ورسالة. ينتظر فقط حتى يقبله Windows، لا حتى يتم تجاهله.

المعلمات

• title: Text — السطر الأول الغامق من الإعلام.
• message: Text — النص المعروض أسفل العنوان.

القيمة المُرجَعة

true إذا تم عرض الإعلام؛ false إذا كانت الإعلامات متوقفة في الإعدادات «عام»، أو رفضه Windows، أو أنهى «إيقاف الكل» الانتظار.

٩ أمثلة: تثبيت نافذة في المقدمة, لقطة شاشة للمنطقة التي أحطتها بدائرة, حفظ صورة منسوخة في ملف, مفتاح تبديل يبقى بين مرات التشغيل, إعلام Windows, تبديل كتم الميكروفون, التشغيل وانتظار الخروج, الانتقال إلى ملف تعريف الإيماءات التالي, حالة المحرك

ShellTerminateProcess

ShellTerminateProcess(processId: Integer) → Bool

يُنهي عملية فورًا، مثل «إنهاء المهمة» في «إدارة المهام». يُفقد العمل غير المحفوظ في ذلك البرنامج.

المعلمات

• processId: Integer — معرّف العملية، مثلًا من WindowGetProcessId أو ShellGetEnumeratedProcessIdAt. القيمة 0 أو أقل، وعملية Input.Observer نفسها، وعمليات نظام Windows توقف البرنامج النصي بخطأ.

القيمة المُرجَعة

true إذا تم إنهاء العملية؛ false إذا كانت قد خرجت بالفعل أو رفض Windows الوصول، كما في حالة برنامج يعمل كمسؤول.

Snippet

SnippetExecuteScript

SnippetExecuteScript(name: Text) → Bool · بسيط

يشغّل المقتطف الذي يحمل هذا الاسم وينتظر حتى ينتهي. يرى المقتطف سياق المشغِّل الخاص بالمستدعي، لكن له متغيراته الخاصة.

المعلمات

• name: Text — اسم المقتطف، مطابَقًا تمامًا، بما في ذلك حالة الأحرف.

القيمة المُرجَعة

true إذا اكتمل تشغيل المقتطف حتى النهاية؛ false إذا لم يكن هناك مقتطف بهذا الاسم، أو كان المقتطف فارغًا، أو به خطأ، أو تم إيقافه.

١ مثال: المقتطفات كدوال قابلة لإعادة الاستخدام

SnippetGetScript

SnippetGetScript(name: Text) → Text

يُرجع نص البرنامج النصي للمقتطف الذي يحمل هذا الاسم دون تشغيله، مثلًا لتمريره إلى TimerCreate.

المعلمات

• name: Text — اسم المقتطف، مطابَقًا تمامًا، بما في ذلك حالة الأحرف.

القيمة المُرجَعة

نص البرنامج النصي للمقتطف، أو نص فارغ إذا لم يكن هناك مقتطف بهذا الاسم.

١ مثال: برنامج نصي للمؤقت من مقتطف، بلا تهريب

Storage

StorageClearAll

StorageClearAll() → Bool

يزيل كل قيمة مخزَّنة باستخدام StorageSetValue، لكل الإجراءات. لا تتأثر القيم الدائمة.

المعلمات

لا توجد معلمات.

القيمة المُرجَعة

true دائمًا.

StorageClearAllPersistent

StorageClearAllPersistent() → Bool

يزيل كل قيمة دائمة ويمسحها من storage.toml، فلا يعود أي منها بعد إعادة التشغيل. لا تتأثر القيم المخزَّنة باستخدام StorageSetValue.

المعلمات

لا توجد معلمات.

القيمة المُرجَعة

true دائمًا.

StorageClearPersistentValue

StorageClearPersistentValue(key: Text) → Bool

يزيل قيمة دائمة واحدة ويمسحها من storage.toml. لا يحدث شيء إذا لم يكن المفتاح مخزَّنًا.

المعلمات

• key: Text — اسم القيمة المراد إزالتها. تُعتبر الأحرف الكبيرة والصغيرة مختلفة.

القيمة المُرجَعة

true دائمًا، سواء كان المفتاح مخزَّنًا أم لا.

StorageClearValue

StorageClearValue(key: Text) → Bool

يزيل قيمة واحدة مخزَّنة باستخدام StorageSetValue. لا يحدث شيء إذا لم يكن المفتاح مخزَّنًا.

المعلمات

• key: Text — اسم القيمة المراد إزالتها. تُعتبر الأحرف الكبيرة والصغيرة مختلفة.

القيمة المُرجَعة

true دائمًا، سواء كان المفتاح مخزَّنًا أم لا.

StorageGetPersistentValue

StorageGetPersistentValue(key: Text) → Any

يقرأ قيمة محفوظة باستخدام StorageSetPersistentValue، بما في ذلك قيمة حُفظت قبل آخر إعادة تشغيل لـ Input.Observer.

المعلمات

• key: Text — الاسم الذي حُفظت القيمة تحته. تُعتبر الأحرف الكبيرة والصغيرة مختلفة.

القيمة المُرجَعة

القيمة المخزَّنة بنوعها (Bool أو Integer أو Real أو Text)، أو القيمة Integer 0 إذا لم يكن المفتاح مخزَّنًا. استخدم StorageHasPersistentValue للتمييز بين مفتاح مفقود وقيمة 0 مخزَّنة.

١ مثال: عدّاد يبقى بعد إعادة التشغيل

StorageGetValue

StorageGetValue(key: Text) → Any

يقرأ قيمة مخزَّنة باستخدام StorageSetValue بواسطة هذا الإجراء أو أي إجراء آخر منذ بدء تشغيل Input.Observer.

المعلمات

• key: Text — الاسم الذي خُزِّنت القيمة تحته. تُعتبر الأحرف الكبيرة والصغيرة مختلفة.

القيمة المُرجَعة

القيمة المخزَّنة بنوعها (Bool أو Integer أو Real أو Text أو Window)، أو القيمة Integer 0 إذا لم يكن المفتاح مخزَّنًا. استخدم StorageHasValue للتمييز بين مفتاح مفقود وقيمة 0 مخزَّنة.

٥ أمثلة: && و|| تُقيِّمان الطرفين, مؤقت متكرر يعدّ, مفتاح تبديل يبقى بين مرات التشغيل, قائمة محفوظة في Storage, المقتطفات كدوال قابلة لإعادة الاستخدام

StorageHasPersistentValue

StorageHasPersistentValue(key: Text) → Bool

يتحقق مما إذا كانت قيمة دائمة مخزَّنة تحت اسم ما. استخدمه للتمييز بين مفتاح مفقود وقيمة 0 أو false أو نص فارغ مخزَّن.

المعلمات

• key: Text — الاسم المراد البحث عنه. تُعتبر الأحرف الكبيرة والصغيرة مختلفة.

القيمة المُرجَعة

true إذا كانت قيمة دائمة مخزَّنة تحت key؛ وإلا false.

StorageHasValue

StorageHasValue(key: Text) → Bool

يتحقق مما إذا كانت قيمة مخزَّنة تحت اسم ما باستخدام StorageSetValue. استخدمه للتمييز بين مفتاح مفقود وقيمة 0 أو false أو نص فارغ مخزَّن.

المعلمات

• key: Text — الاسم المراد البحث عنه. تُعتبر الأحرف الكبيرة والصغيرة مختلفة.

القيمة المُرجَعة

true إذا كانت قيمة مخزَّنة تحت key؛ وإلا false.

StorageSetPersistentValue

StorageSetPersistentValue(key: Text, value: Any) → Bool

يحفظ قيمة تحت اسم تبقى بعد إعادة التشغيل، في storage.toml بجوار ملف التكوين. الملف نص عادي غير مشفَّر أبدًا: لا تحتفظ فيه بكلمات المرور أو بأي أسرار أخرى.

المعلمات

• key: Text — الاسم المراد الحفظ تحته، حتى 256 حرفًا. تُعتبر الأحرف الكبيرة والصغيرة مختلفة. يستبدل أي قيمة مخزَّنة تحته بالفعل.
• value: Any — القيمة المراد حفظها: Bool أو Integer أو Real أو Text (حتى 32768 حرفًا). تعود بالنوع نفسه. لا يمكن حفظ قيمة Window.

القيمة المُرجَعة

true بمجرد تخزين القيمة. false عندما يكون storage.toml موجودًا لكن تعذّرت قراءته عند بدء التشغيل: يتوقف الحفظ حينئذ حتى بدء التشغيل التالي، ولا تُحتفظ بالقيمة إلا حتى خروج Input.Observer. قيمة نافذة، أو مفتاح يزيد على 256 حرفًا، أو قيمة Text تزيد على 32768 حرفًا، أو مفتاح جديد بعد بلوغ 1024 قيمة مخزَّنة، يوقف الإجراء بخطأ.

١ مثال: عدّاد يبقى بعد إعادة التشغيل

StorageSetValue

StorageSetValue(key: Text, value: Any) → Bool

يخزّن قيمة تحت اسم حتى تتمكن عمليات التشغيل اللاحقة لهذا الإجراء أو لأي إجراء آخر من قراءتها. تُحفظ القيم حتى خروج Input.Observer؛ استخدم StorageSetPersistentValue للاحتفاظ بقيمة عبر عمليات إعادة التشغيل.

المعلمات

• key: Text — الاسم المراد التخزين تحته، حتى 256 حرفًا. تُعتبر الأحرف الكبيرة والصغيرة مختلفة. يستبدل أي قيمة مخزَّنة تحته بالفعل، أيًّا كان نوعها.
• value: Any — القيمة المراد تخزينها: Bool أو Integer أو Real أو Text (حتى 32768 حرفًا) أو Window. تعود بالنوع نفسه.

القيمة المُرجَعة

true بمجرد تخزين القيمة. مفتاح يزيد على 256 حرفًا، أو قيمة Text تزيد على 32768 حرفًا، أو مفتاح جديد بعد بلوغ 1024 قيمة مخزَّنة، يوقف الإجراء بخطأ.

٥ أمثلة: && و|| تُقيِّمان الطرفين, مؤقت متكرر يعدّ, مفتاح تبديل يبقى بين مرات التشغيل, قائمة محفوظة في Storage, المقتطفات كدوال قابلة لإعادة الاستخدام

String

StringContains

StringContains(text: Text, search: Text) → Bool

يتحقق مما إذا كان النص يحتوي على نص آخر في أي موضع. يجب أن تتطابق الأحرف الكبيرة والصغيرة؛ استخدم StringToLower على كليهما لفحص غير حساس لحالة الأحرف.

المعلمات

• text: Text — النص المراد البحث فيه.
• search: Text — النص المراد البحث عنه.

القيمة المُرجَعة

true إذا ورد search في text، أو إذا كانت قيمة search فارغة؛ وإلا false.

١ مثال: مقارنات غير حساسة لحالة الأحرف

StringEndsWith

StringEndsWith(text: Text, suffix: Text) → Bool

يتحقق مما إذا كان النص ينتهي بنص معيَّن، مثل امتداد ملف. يجب أن تتطابق الأحرف الكبيرة والصغيرة.

المعلمات

• text: Text — النص المراد فحصه.
• suffix: Text — النهاية المراد البحث عنها، مثل '.pdf'.

القيمة المُرجَعة

true إذا انتهى text بـ suffix، أو إذا كانت قيمة suffix فارغة؛ وإلا false.

١ مثال: عدّ أنواع الملفات في مجلد

StringFormat

StringFormat(format: Text, value0: Any, value1: Any) → Text

ينشئ نصًا باستبدال كل {0} في format بـ value0 وكل {1} بـ value1. هذه هي طريقة تحويل رقم أو قيمة Bool أو نافذة إلى Text.

المعلمات

• format: Text — النص الذي يحتوي على العنصرين النائبين {0} و{1}. لا يوجد {2}؛ استخدم استدعاءات متداخلة لمزيد من القيم. يُستبدل {0} أولًا، لذا يُستبدل أيضًا أي {1} داخل value0.
• value0: Any — القيمة لـ {0}، من أي نوع.
• value1: Any — القيمة لـ {1}، من أي نوع. مرِّر نصًا فارغًا إذا لم يحتوِ format على {1}.

القيمة المُرجَعة

نص format بعد استبدال العناصر النائبة. تظهر قيمة Real بست منازل عشرية؛ وتظهر true وfalse ككلمات.

٥٠ مثالًا: أنواع القيم الخمسة, حلقات العد: تصاعديًا وتنازليًا وبخطوات, حلقات متداخلة: جدول الضرب, while (true) مع علامة خروج, مفاجآت الأولوية, && و|| تُقيِّمان الطرفين, المساواة بين الأنواع, العمليات الحسابية على الأنواع المختلطة ترجع إلى 0, التعليقات والعبارات الفارغة والكتل, قسمة Integer مقابل Real، والقسمة على صفر, باقي القسمة بدون %, التقريب والدوال المضمَّنة الرياضية لقيم Real, حصر قيمة ضمن نطاق, أرقام عشوائية ورمي عملة, طول خط الإيماءة, تنسيق قيمة Real بدون ست خانات عشرية, أقنعة العلامات: التعيين والمسح والتبديل والاختبار, قراءة لون البكسل أسفل المؤشر, عدّ البتات المعيَّنة, الحالات الحدية للإزاحة, تبديل قيمتي Integer, بتات حالة المفتاح, تنسيق أكثر من قيمتين, التقسيم والمرور على الأجزاء, التقسيمات المتداخلة: أزواج key=value, آخر فهرس: امتداد الملف, حشو رقم بالأصفار, عدّ الكلمات في الحافظة, ترتيب النص ترتيبي, الثوابت المسماة مقابل الأرقام الخام, سرد النوافذ المرئية ذات المستوى الأعلى, تصغير كل نوافذ تطبيق واحد, إغلاق النوافذ حسب نمط العنوان، بعد التأكيد, فحص عناصر التحكم التابعة للنافذة, من العملية إلى النافذة, وصف ما يوجد أسفل المؤشر, كل ما يعرفه سياق المشغِّل, الإلحاق بملف سجل, قراءة ملف وعدّ أسطره, عدّ أنواع الملفات في مجلد, مؤقت متكرر يعدّ, عدّاد يبقى بعد إعادة التشغيل, قائمة محفوظة في Storage, رفع مستوى الصوت مع عرض على الشاشة, رسالة عرض تتحدث مباشرة, إعلام Windows, سرد الشاشات, حالة المحرك, المقتطفات كدوال قابلة لإعادة الاستخدام, إبقاء منفذ Arduino مفتوحًا وإرسال الأوامر إليه

StringFromNumber

StringFromNumber(number: Any, decimals: Integer, invariantCulture: Bool) → Text

يحوّل رقمًا إلى نص، إما بالتنسيق الإقليمي للمستخدم مع تجميع الأرقام للعرض، أو بتنسيق آلي ثابت للملفات والأجهزة.

المعلمات

• number: Any — قيمة Integer أو Real المراد تحويلها.
• decimals: Integer — عدد الأرقام بعد الفاصل العشري، من 0 إلى 15، مع التقريب؛ أو -1 لعدد الأرقام الذي تحتاجه القيمة (لا شيء لقيمة Integer).
• invariantCulture: Bool — true لنص آلي: نقطة كفاصل عشري، بلا تجميع، ويمكن قراءته مرة أخرى باستخدام StringToNumber(text, true). false للتنسيق الإقليمي للمستخدم.

القيمة المُرجَعة

الرقم كنص، مثل 1,234.50 أو 1234.5. نص فارغ إذا لم تكن قيمة Real رقمًا محدودًا. القيمة التي ليست رقمًا، أو قيمة decimals خارج النطاق، توقف الإجراء بخطأ.

١ مثال: قراءة رقم كتبه شخص

StringGetIndexOf

StringGetIndexOf(text: Text, search: Text) → Integer

يعثر على موضع أول ورود لنص داخل نص آخر. يجب أن تتطابق الأحرف الكبيرة والصغيرة. تبدأ المواضع من 0.

المعلمات

• text: Text — النص المراد البحث فيه.
• search: Text — النص المراد البحث عنه.

القيمة المُرجَعة

موضع أول ورود بدءًا من الصفر، أو 0 إذا كانت قيمة search فارغة، أو -1 إذا لم يرد search في text.

١ مثال: && و|| تُقيِّمان الطرفين

StringGetLength

StringGetLength(text: Text) → Integer

يُرجع عدد الأحرف في النص، بما في ذلك المسافات وفواصل الأسطر. تُحسب المواضع التي يستخدمها StringGetSubstring بالطريقة نفسها.

المعلمات

• text: Text — النص المراد قياسه.

القيمة المُرجَعة

عدد الأحرف، أو 0 للنص الفارغ. بعض الرموز التعبيرية والأحرف النادرة تُحسب كحرفين.

٣ أمثلة: آخر فهرس: امتداد الملف, حشو رقم بالأصفار, عكس قيمة Text

StringGetSplitPartAt

StringGetSplitPartAt(index: Integer) → Text

يُرجع جزءًا واحدًا من آخر استدعاء لـ StringSplit في تشغيل البرنامج النصي هذا.

المعلمات

• index: Integer — رقم الجزء بدءًا من الصفر، من 0 إلى العدد الذي أرجعه StringSplit ناقص 1.

القيمة المُرجَعة

نص الجزء، أو نص فارغ إذا كان index خارج النطاق أو لم يتم استدعاء StringSplit في هذا التشغيل.

٦ أمثلة: break وcontinue, التقسيم والمرور على الأجزاء, التقسيمات المتداخلة: أزواج key=value, عدّ الكلمات في الحافظة, ضم أسطر الحافظة في سطر واحد, قراءة ملف وعدّ أسطره

StringGetSubstring

StringGetSubstring(text: Text, start: Integer, length: Integer) → Text

يُرجع جزءًا من النص: حتى length من الأحرف، بدءًا من الموضع start. تبدأ المواضع من 0.

المعلمات

• text: Text — النص المراد أخذ الجزء منه.
• start: Integer — موضع أول حرف يؤخذ، بدءًا من الصفر. يجب ألا يكون سالبًا.
• length: Integer — أقصى عدد من الأحرف يؤخذ. يجب ألا يكون سالبًا.

القيمة المُرجَعة

الجزء المطلوب، أقصر إذا انتهى النص أولًا، أو نص فارغ إذا كان start عند النهاية أو بعدها. القيمة السالبة لـ start أو length توقف الإجراء بخطأ.

٤ أمثلة: && و|| تُقيِّمان الطرفين, Integer إلى نص ست عشري, آخر فهرس: امتداد الملف, عكس قيمة Text

StringIsNumber

StringIsNumber(text: Text, invariantCulture: Bool) → Bool

يتحقق مما إذا كان النص رقمًا يستطيع StringToNumber قراءته، مثل ما كتبه المستخدم في UIShowInputBox. يتم تجاهل المسافات المحيطة بالرقم.

المعلمات

• text: Text — النص المراد فحصه.
• invariantCulture: Bool — true لنص آلي: نقطة كفاصل عشري وبلا تجميع للأرقام. false للتنسيق الإقليمي للمستخدم، كما يكتبه الشخص؛ ويجب حينئذ أن تتبع مجموعات الأرقام أحجام المجموعات في ذلك التنسيق.

القيمة المُرجَعة

true إذا كان النص رقمًا بالتنسيق المختار؛ وإلا false، بما في ذلك للنص الفارغ.

٢ مثالان: قراءة رقم كتبه شخص, تحويل مقبض Arduino إلى عنصر تحكم في مستوى الصوت

StringRegexGetGroupAt

StringRegexGetGroupAt(index: Integer) → Text

يُرجع التطابق الكامل أو مجموعة التقاط واحدة من آخر استدعاء ناجح لـ StringRegexMatch في تشغيل البرنامج النصي هذا.

المعلمات

• index: Integer — 0 للتطابق الكامل؛ و1 فما فوق لمجموعات الالتقاط، بترتيب ظهور أقواسها الافتتاحية. المجموعات المسماة مرقَّمة أيضًا.

القيمة المُرجَعة

النص المطابق، أو نص فارغ إذا كان index خارج النطاق، أو لم تشارك المجموعة في التطابق، أو لم يعثر آخر استدعاء لـ StringRegexMatch على تطابق.

١ مثال: استخراج قيمة من نص منسوخ باستخدام تعبير نمطي

StringRegexMatch

StringRegexMatch(text: Text, pattern: Text) → Bool

يتحقق مما إذا كان تعبير عادي (بصيغة PCRE2) يتطابق في أي موضع من النص، ويتذكر التطابق ومجموعاته من أجل StringRegexGetGroupAt.

المعلمات

• text: Text — النص المراد البحث فيه.
• pattern: Text — التعبير العادي. حساس لحالة الأحرف؛ ابدأه بـ (?i) لتجاهل حالة الأحرف. تتبع فئات الأحرف مثل الكلمة والرقم معيار Unicode.

القيمة المُرجَعة

true إذا تطابق النمط؛ وإلا false. النمط غير الصالح، أو الذي يحتاج إلى عدد كبير جدًا من الخطوات على هذا النص، يوقف الإجراء بخطأ.

١ مثال: استخراج قيمة من نص منسوخ باستخدام تعبير نمطي

StringRegexReplace

StringRegexReplace(text: Text, pattern: Text, replacement: Text) → Text

يستبدل كل تطابق لتعبير عادي (بصيغة PCRE2) في النص، بنص بديل يمكن أن يتضمن المجموعات المطابقة.

المعلمات

• text: Text — النص المراد تغييره.
• pattern: Text — التعبير العادي. حساس لحالة الأحرف؛ ابدأه بـ (?i) لتجاهل حالة الأحرف.
• replacement: Text — النص المراد وضعه مكان كل تطابق. يُدرج $1 أو ${1} المجموعة 1، و${name} مجموعة مسماة، و$0 التطابق الكامل، و$$ علامة دولار حرفية.

القيمة المُرجَعة

النص بعد استبدال كل تطابق، أو النص دون تغيير إذا لم يتطابق شيء. النمط أو النص البديل غير الصالح، أو العدد الكبير جدًا من الخطوات، أو النتيجة التي تزيد على 16 مليون حرف، يوقف الإجراء بخطأ.

١ مثال: استخراج قيمة من نص منسوخ باستخدام تعبير نمطي

StringReplace

StringReplace(text: Text, search: Text, replacement: Text) → Text

يستبدل كل ورود لنص بنص آخر. يجب أن تتطابق الأحرف الكبيرة والصغيرة. البحث عن نص حرفي، لا عن نمط.

المعلمات

• text: Text — النص المراد تغييره.
• search: Text — النص المراد العثور عليه. يجب ألا يكون فارغًا.
• replacement: Text — النص المراد وضعه مكانه. يمكن أن يكون فارغًا لإزالة كل ورود.

القيمة المُرجَعة

النص بعد استبدال كل ورود، أو النص دون تغيير إذا لم يرد search. قيمة search الفارغة توقف الإجراء بخطأ.

٣ أمثلة: عدّ الكلمات في الحافظة, ملء قالب ولصقه, البحث في الويب عن التحديد

StringSplit

StringSplit(text: Text, delimiter: Text) → Integer

يقسّم النص إلى أجزاء عند كل ورود لمحدِّد ويتذكر الأجزاء من أجل StringGetSplitPartAt. المحدِّدات المتجاورة، أو المحدِّد في أي من الطرفين، تعطي أجزاء فارغة.

المعلمات

• text: Text — النص المراد تقسيمه.
• delimiter: Text — النص الحرفي المراد التقسيم عنده، مثل ',' أو فاصل أسطر. يجب ألا يكون فارغًا.

القيمة المُرجَعة

عدد الأجزاء، 1 على الأقل. قيمة delimiter الفارغة توقف الإجراء بخطأ.

٦ أمثلة: break وcontinue, التقسيم والمرور على الأجزاء, التقسيمات المتداخلة: أزواج key=value, عدّ الكلمات في الحافظة, ضم أسطر الحافظة في سطر واحد, قراءة ملف وعدّ أسطره

StringStartsWith

StringStartsWith(text: Text, prefix: Text) → Bool

يتحقق مما إذا كان النص يبدأ بنص معيَّن. يجب أن تتطابق الأحرف الكبيرة والصغيرة.

المعلمات

• text: Text — النص المراد فحصه.
• prefix: Text — البداية المراد البحث عنها.

القيمة المُرجَعة

true إذا بدأ text بـ prefix، أو إذا كانت قيمة prefix فارغة؛ وإلا false.

٢ مثالان: break وcontinue, قراءة ملف وعدّ أسطره

StringToLower

StringToLower(text: Text) → Text

يحوّل النص إلى أحرف صغيرة، وفقًا لقواعد حالة الأحرف في التنسيق الإقليمي لـ Windows لدى المستخدم (مثل حرف i المنقوط وغير المنقوط في التركية).

المعلمات

• text: Text — النص المراد تحويله.

القيمة المُرجَعة

النص بأحرف صغيرة، أو النص دون تغيير إذا تعذّر على Windows تحويله.

٤ أمثلة: مقارنات غير حساسة لحالة الأحرف, ترتيب النص ترتيبي, تمرير رسم غير متعرَّف عليه, عدّ أنواع الملفات في مجلد

StringToNumber

StringToNumber(text: Text, invariantCulture: Bool) → Any

يقرأ رقمًا من نص، مثل إدخال المستخدم أو ملف أو جهاز تسلسلي. يتم تجاهل المسافات المحيطة بالرقم؛ ويُسمح بأس مثل 1.5e3.

المعلمات

• text: Text — النص المراد قراءته.
• invariantCulture: Bool — true لنص آلي: نقطة كفاصل عشري وبلا تجميع للأرقام، لذا '1,5' ليس رقمًا. false للتنسيق الإقليمي للمستخدم، كما يكتبه الشخص؛ ويجب حينئذ أن تتبع مجموعات الأرقام ذلك التنسيق، لذا يُقرأ '1,234.5' في العربية (المملكة العربية السعودية) أما '1,5' فلا.

القيمة المُرجَعة

قيمة Integer إذا لم يحتوِ النص على فاصل عشري أو أس وكان ضمن النطاق، وإلا قيمة Real. 0 إذا لم يكن النص رقمًا؛ تحقق أولًا باستخدام StringIsNumber.

٢ مثالان: قراءة رقم كتبه شخص, تحويل مقبض Arduino إلى عنصر تحكم في مستوى الصوت

StringToUpper

StringToUpper(text: Text) → Text

يحوّل النص إلى أحرف كبيرة، وفقًا لقواعد حالة الأحرف في التنسيق الإقليمي لـ Windows لدى المستخدم (مثل حرف i المنقوط وغير المنقوط في التركية).

المعلمات

• text: Text — النص المراد تحويله.

القيمة المُرجَعة

النص بأحرف كبيرة، أو النص دون تغيير إذا تعذّر على Windows تحويله.

٢ مثالان: تحويل النص المحدد إلى أحرف كبيرة, نسخ ملف احتياطيًا قبل تحريره

StringTrim

StringTrim(text: Text) → Text

يزيل المسافات وعلامات الجدولة وفواصل الأسطر وغيرها من المسافات البيضاء من بداية النص ونهايته. تُحفظ المسافات البيضاء داخل النص.

المعلمات

• text: Text — النص المراد اقتطاعه.

القيمة المُرجَعة

النص بعد الاقتطاع، أو نص فارغ إذا كان النص مسافات بيضاء فقط.

٦ أمثلة: عدّ الكلمات في الحافظة, ضم أسطر الحافظة في سطر واحد, البحث في الويب عن النص المحدد, البحث في الويب عن التحديد, قراءة ملف وعدّ أسطره, ربط أزرار جهاز تسلسلي بمفاتيح الوسائط

StringUrlEncode

StringUrlEncode(text: Text) → Text · بسيط

يرمّز النص بحيث يمكن وضعه داخل عنوان ويب، مثل مصطلح بحث مأخوذ من النص المحدد. رمّز القيمة فقط، لا العنوان بأكمله.

المعلمات

• text: Text — النص المراد ترميزه، مثل مصطلح بحث.

القيمة المُرجَعة

النص المرمَّز: تبقى الأحرف والأرقام و- . _ ~ كما هي؛ ويصبح كل بايت آخر من نص UTF-8 تسلسل هروب يبدأ بعلامة النسبة المئوية ويتبعه رقمان سداسيان عشريان. تصبح المسافة علامة النسبة المئوية متبوعة بـ 20، لا علامة الجمع.

١ مثال: البحث في الويب عن النص المحدد

Style

StyleGetCurrent

StyleGetCurrent() → Text · بسيط

يُرجع مفتاح نمط الأثر الذي يرسمه المكوّن الإضافي لأداة العرض الآن، مثل neonglow، أو shuffle عند تحديد «عشوائي».

المعلمات

لا توجد معلمات.

القيمة المُرجَعة

مفتاح النمط، أو النمط الافتراضي لأداة العرض عندما لا يكون هناك نمط صالح للاستخدام محدَّدًا، أو نص فارغ عندما لا تكون هناك أداة عرض قيد التشغيل أو لم تُبلغ عن أنماطها.

StyleNext

StyleNext() → Bool · بسيط

يحدد نمط الأثر غير المؤمَّن التالي في قائمة أداة العرض، ويعود إلى البداية عند الوصول إلى النهاية. يُرسم النمط الجديد بدءًا من الإيماءة التالية.

المعلمات

لا توجد معلمات.

القيمة المُرجَعة

true إذا تم طلب تغيير النمط؛ false عندما لا تكون هناك أداة عرض قيد التشغيل أو لا يوجد نمط آخر لتحديده.

StyleSet

StyleSet(key: Text) → Bool · بسيط

يحدد نمط الأثر الخاص بأداة العرض الذي له هذا المفتاح، ويُرسم بدءًا من الإيماءة التالية. زر الرسم الذي له نمطه الخاص يحتفظ به.

المعلمات

• key: Text — مفتاح النمط، مثل neonglow أو auto؛ غير حساس لحالة الأحرف. استخدم shuffle للحصول على نمط مختلف في كل إيماءة.

القيمة المُرجَعة

true إذا تم طلب تغيير النمط؛ false إذا لم تكن هناك أداة عرض قيد التشغيل، أو لا يوجد نمط بهذا المفتاح، أو كان النمط مؤمَّنًا.

System

SystemHibernate

SystemHibernate() → Bool · بسيط

يدخل الكمبيوتر في وضع الإسبات دون سؤال. ينتظر البرنامج النصي هنا ويتابع بعد تشغيل الكمبيوتر مرة أخرى. لا يفعل شيئًا إذا كان الإسبات متوقفًا في Windows.

المعلمات

لا توجد معلمات.

القيمة المُرجَعة

true بعد أن يدخل الكمبيوتر في وضع الإسبات ثم يستأنف؛ false إذا لم يكن الإسبات متاحًا أو رفض Windows ذلك.

SystemLock

SystemLock() → Bool · بسيط

يقفل الكمبيوتر ويعرض شاشة تسجيل الدخول إلى Windows، كما يفعل Windows+L. تظل التطبيقات قيد التشغيل.

المعلمات

لا توجد معلمات.

القيمة المُرجَعة

true إذا قفل Windows الكمبيوتر؛ false إذا رفض Windows ذلك، مثلًا بسبب نهج يعطّل القفل.

SystemMonitorOff

SystemMonitorOff() → Bool · بسيط

يوقف تشغيل الشاشات. تعيد حركة الماوس أو ضغطة المفتاح التالية تشغيلها، لذا يجب على البرنامج النصي الذي بدأته إيماءة أن يستدعي UtilityWait(500) أولًا.

المعلمات

لا توجد معلمات.

القيمة المُرجَعة

true بمجرد إرسال الطلب إلى Windows؛ false إذا تعذّر إرساله.

SystemRestart

SystemRestart(force: Bool) → Bool · بسيط

يعيد تشغيل الكمبيوتر دون طلب تأكيد؛ ويغلق Windows التطبيقات قيد التشغيل أولًا. اعرض UIShowMessageBox أولًا إذا أردت التأكيد.

المعلمات

• force: Bool — false يتيح للتطبيقات طلب حفظ العمل غير المحفوظ (لا تُغلق قسرًا إلا التطبيقات التي لا تستجيب)؛ true يغلق كل التطبيقات فورًا ويُفقد العمل غير المحفوظ.

القيمة المُرجَعة

true إذا قبل Windows طلب إعادة التشغيل (ثم يتابع من تلقاء نفسه)؛ false إذا رفضه Windows.

SystemShutDown

SystemShutDown(force: Bool) → Bool · بسيط

يوقف تشغيل الكمبيوتر ويفصل عنه الطاقة دون طلب تأكيد. اعرض UIShowMessageBox أولًا إذا أردت التأكيد.

المعلمات

• force: Bool — false يتيح للتطبيقات طلب حفظ العمل غير المحفوظ (لا تُغلق قسرًا إلا التطبيقات التي لا تستجيب)؛ true يغلق كل التطبيقات فورًا ويُفقد العمل غير المحفوظ.

القيمة المُرجَعة

true إذا قبل Windows طلب إيقاف التشغيل (ثم يتابع من تلقاء نفسه)؛ false إذا رفضه Windows.

SystemSignOut

SystemSignOut(force: Bool) → Bool · بسيط

يسجّل خروج المستخدم الحالي من Windows دون طلب تأكيد، فيغلق كل التطبيقات ومعها Input.Observer.

المعلمات

• force: Bool — false يتيح للتطبيقات طلب حفظ العمل غير المحفوظ (لا تُغلق قسرًا إلا التطبيقات التي لا تستجيب)؛ true يغلق كل التطبيقات فورًا ويُفقد العمل غير المحفوظ.

القيمة المُرجَعة

true إذا قبل Windows طلب تسجيل الخروج (ثم يتابع من تلقاء نفسه)؛ false إذا رفضه Windows.

SystemSleep

SystemSleep() → Bool · بسيط

يضع الكمبيوتر في وضع السكون دون سؤال. ينتظر البرنامج النصي هنا ويتابع بعد استيقاظ الكمبيوتر. لا يفعل شيئًا على كمبيوتر يدعم «الاستعداد الحديث»؛ استخدم SystemMonitorOff هناك.

المعلمات

لا توجد معلمات.

القيمة المُرجَعة

true بعد أن يدخل الكمبيوتر في وضع السكون ثم يستيقظ؛ false إذا لم تكن لدى هذا الكمبيوتر حالة سكون يمكن لبرنامج بدؤها، أو رفض Windows ذلك.

Timer

TimerCreate

TimerCreate(name: Text, startDelayMs: Integer, intervalMs: Integer, repeatCount: Integer, script: Text) → Bool

ينشئ مؤقتًا مسمى يشغّل نص برنامج نصي بعد تأخير ثم على فترات ثابتة، أو يستبدل المؤقت الذي يحمل ذلك الاسم. تستمر المؤقتات في العمل بعد انتهاء البرنامج النصي، حتى تُحذف أو يخرج المحرك.

المعلمات

• name: Text — اسم للمؤقت، يستخدمه TimerDelete. حساس لحالة الأحرف؛ ويُستبدل المؤقت الموجود الذي يحمل هذا الاسم.
• startDelayMs: Integer — التأخير قبل التشغيل الأول، بالمللي ثانية؛ 0 أو أكثر.
• intervalMs: Integer — الوقت بين عمليات التشغيل، بالمللي ثانية؛ 1 أو أكثر. لا ينتظر التشغيل انتهاء التشغيل السابق.
• repeatCount: Integer — عدد مرات التشغيل الإجمالي؛ القيمة 0 تكرر حتى يُحذف المؤقت.
• script: Text — نص البرنامج النصي المراد تشغيله عند كل نبضة. يعمل بشكل مستقل، بدون سياق مشغِّل وبدون أي من متغيرات هذا البرنامج النصي.

القيمة المُرجَعة

true بمجرد تعيين المؤقت. القيمة السالبة لـ startDelayMs أو repeatCount، أو قيمة intervalMs أقل من 1، توقف البرنامج النصي بخطأ.

٢ مثالان: مؤقت متكرر يعدّ, برنامج نصي للمؤقت من مقتطف، بلا تهريب

TimerDelete

TimerDelete(name: Text) → Bool

يزيل المؤقت الذي يحمل هذا الاسم حتى لا يعمل مرة أخرى.

المعلمات

• name: Text — اسم المؤقت، كما مُرِّر إلى TimerCreate. حساس لحالة الأحرف.

القيمة المُرجَعة

true إذا كان المؤقت موجودًا وتمت إزالته؛ false إذا لم يكن هناك مؤقت بهذا الاسم.

١ مثال: سرد المؤقتات وإيقافها

TimerDeleteAll

TimerDeleteAll() → Bool

يزيل كل مؤقت أُنشئ باستخدام TimerCreate، فلا يعمل أي منها مرة أخرى.

المعلمات

لا توجد معلمات.

القيمة المُرجَعة

true دائمًا.

١ مثال: سرد المؤقتات وإيقافها

TimerEnumerateAll

TimerEnumerateAll() → Integer

يأخذ قائمة بأسماء كل المؤقتات الحالية ويُرجع عددها. اقرأ كل اسم باستخدام TimerGetEnumeratedNameAt.

المعلمات

لا توجد معلمات.

القيمة المُرجَعة

عدد المؤقتات، أو 0 إذا لم توجد أي منها.

١ مثال: سرد المؤقتات وإيقافها

TimerGetEnumeratedNameAt

TimerGetEnumeratedNameAt(index: Integer) → Text

يُرجع اسم مؤقت واحد من القائمة التي أخذها TimerEnumerateAll آخر مرة في هذا البرنامج النصي.

المعلمات

• index: Integer — الموضع في القائمة بدءًا من الصفر، من 0 إلى العدد ناقص 1. لا معنى للترتيب.

القيمة المُرجَعة

اسم المؤقت، أو نص فارغ إذا كان index خارج النطاق أو لم يتم استدعاء TimerEnumerateAll.

١ مثال: سرد المؤقتات وإيقافها

Tray

TrayMinimizeWindow

TrayMinimizeWindow(window: Window) → Bool

يخفي نافذة ويعرض لها أيقونة في منطقة الإعلامات بأيقونة النافذة وعنوانها. يؤدي النقر فوق الأيقونة إلى استعادة النافذة حيث كانت. بالنسبة لعنصر تحكم، تُخفى نافذته ذات المستوى الأعلى.

المعلمات

• window: Window — النافذة المراد إخفاؤها، مثل ContextGetWindow().

القيمة المُرجَعة

true إذا تم قبول الطلب؛ false لنافذة فارغة أو نافذة لم تعد موجودة.

١ مثال: إخفاء نافذة في منطقة الإعلامات

TrayRestoreAllWindows

TrayRestoreAllWindows() → Bool

يستعيد كل نافذة أُخفيت باستخدام TrayMinimizeWindow ويزيل أيقوناتها من منطقة الإعلامات.

المعلمات

لا توجد معلمات.

القيمة المُرجَعة

true إذا تم إرسال الطلب؛ false إذا لم ينتهِ المحرك من بدء التشغيل بعد.

UI

UIClearPrintLog

UIClearPrintLog() → Bool

يمسح علامة التبويب «المستخدم» في وحدة التحكم التشخيصية، حيث يظهر إخراج UtilityPrint، بما في ذلك الإخراج المحفوظ أثناء إغلاق وحدة التحكم.

المعلمات

لا توجد معلمات.

القيمة المُرجَعة

true دائمًا.

UICloseDisplayMessage

UICloseDisplayMessage(sessionId: Integer) → Bool

يغلق رسالة واحدة على الشاشة فتحها UIShowDisplayMessage. لا يفعل شيئًا إذا كانت تلك الرسالة قد أُغلقت بالفعل.

المعلمات

• sessionId: Integer — المعرّف الذي أرجعه UIShowDisplayMessage للرسالة المراد إغلاقها.

القيمة المُرجَعة

true دائمًا، بما في ذلك عندما تكون الرسالة قد أُغلقت بالفعل.

١ مثال: رسالة عرض تتحدث مباشرة

UIGetCulture

UIGetCulture() → Text

يُرجع اللغة والمنطقة اللتين يستخدمهما Input.Observer لنصوصه الخاصة (قائمة منطقة الإعلامات، والرسائل، ونصوص الأخطاء)، كما عيّنها UISetCulture أو إعداد اللغة أو Windows.

المعلمات

لا توجد معلمات.

القيمة المُرجَعة

اسم الثقافة كما تم تعيينه، مثل en-US أو es-ES، حتى عندما تحل ترجمة منطقة أخرى محله.

UISetCulture

UISetCulture(culture: Text) → Bool

يبدّل اللغة التي يستخدمها Input.Observer لنصوصه الخاصة (قائمة منطقة الإعلامات، والرسائل، ونصوص الأخطاء) حتى خروجه أو تغيّر إعداد اللغة. لا يغيّر نافذة الإعدادات ولا الإعداد المحفوظ.

المعلمات

• culture: Text — اسم ثقافة مثل en-US أو de-DE أو es-MX.

القيمة المُرجَعة

true إذا تم تطبيق الثقافة؛ false، وتبقى اللغة كما كانت، إذا لم تكن قيمة culture ثقافة يعرفها Windows أو لم تكن لدى Input.Observer ترجمة بلغتها. تُقبل منطقة أخرى للغة مترجمة، مثل es-ES.

UIShowConsole

UIShowConsole() → Bool

يفتح وحدة التحكم التشخيصية، أو يُحضرها إلى المقدمة إذا كانت مفتوحة بالفعل، وينتظر حتى تُفتح. إذا كان التكوين محميًا بكلمة مرور، فإنه ينتظر أثناء طلب كلمة المرور. لا يغلقها سوى زر الإغلاق الخاص بها.

المعلمات

لا توجد معلمات.

القيمة المُرجَعة

true بمجرد فتح وحدة التحكم؛ false إذا لم تُفتح، مثلًا لأن مطالبة كلمة المرور أُلغيت أو تعذّرت قراءة الحالة المحفوظة لوحدة التحكم.

UIShowDisplayMessage

UIShowDisplayMessage(title: Text, message: Text, durationMs: Integer, opacity: Real, location: Any, titleFontFamily: Text, titleFontSizePt: Integer, titleBold: Bool, titleItalic: Bool, messageFontFamily: Text, messageFontSizePt: Integer, messageBold: Bool, messageItalic: Bool, foreColor: Text, backColor: Text, paddingPx: Integer, usePrimaryScreen: Bool, titleAlign: Integer, messageAlign: Integer) → Integer · بسيط

يعرض لوحة بسطر عنوان وسطر رسالة في مكان ثابت على الشاشة، ويعود فورًا. يمكن فتح عدة لوحات معًا؛ احتفظ بالمعرّف المُرجع لتحديث هذه اللوحة أو إغلاقها.

المعلمات

• title: Text — نص السطر العلوي، مرسومًا بخط العنوان. النص الفارغ يحذف السطر.
• message: Text — نص السطر الثاني، مرسومًا بخط الرسالة. يلتف النص الطويل على أسطر إضافية. النص الفارغ يحذف السطر.
• durationMs: Integer — مدة بقاء اللوحة، بالمللي ثانية. القيمة 0 أو أقل تبقيها حتى يغلقها UICloseDisplayMessage (تُغلق اللوحة المضمَّنة أيضًا بالنقر المزدوج).
• opacity: Real — مدى تعتيم اللوحة، من 0.05 (شبه غير مرئية) إلى 1.0 (معتمة تمامًا). تُقيَّد القيم الواقعة خارج هذا النطاق بحدوده.
• location: Any — مكان العرض: ثابت Location مثل Location.BottomCenter (يوضع داخل منطقة الشاشة التي لا يغطيها شريط المهام)، أو قيمة Text بالصيغة 'x,y' بلا مسافات تحدد الزاوية العلوية اليسرى للوحة بوحدات بكسل الشاشة، مثل '100,200'. أي شيء آخر يوقف الإجراء بخطأ.
• titleFontFamily: Text — اسم الخط لسطر العنوان، مثل Segoe UI.
• titleFontSizePt: Integer — حجم خط العنوان بالنقاط. القيم الأقل من 1 تُحتسب 1.
• titleBold: Bool — true لرسم سطر العنوان بخط غامق.
• titleItalic: Bool — true لرسم سطر العنوان بخط مائل.
• messageFontFamily: Text — اسم الخط لسطر الرسالة، مثل Segoe UI.
• messageFontSizePt: Integer — حجم خط الرسالة بالنقاط. القيم الأقل من 1 تُحتسب 1.
• messageBold: Bool — true لرسم سطر الرسالة بخط غامق.
• messageItalic: Bool — true لرسم سطر الرسالة بخط مائل.
• foreColor: Text — لون النص لكلا السطرين: اسم لون مثل white أو black، أو '#RRGGBB'، أو 'R,G,B' بحيث يكون كل رقم من 0 إلى 255 وبلا مسافات. أي شيء آخر يوقف الإجراء بخطأ.
• backColor: Text — لون الخلفية، بالصيغ نفسها المستخدمة في foreColor، مثل '#F7F7F5'. استخدم opacity، لا اللون، لجعل اللوحة شفافة.
• paddingPx: Integer — المساحة الفارغة حول النص، بالبكسل عند تحجيم العرض بنسبة 100 بالمائة؛ وتكبر مع مقياس العرض. القيم الأقل من 0 تُحتسب 0.
• usePrimaryScreen: Bool — true لوضع Location على الشاشة الرئيسية؛ false لاستخدام الشاشة التي يوجد عليها مؤشر الماوس الآن. يتم تجاهله لموقع بالصيغة 'x,y'.
• titleAlign: Integer — محاذاة سطر العنوان: TextAlign.Left أو TextAlign.Center أو TextAlign.Right. أي قيمة أخرى توقف الإجراء بخطأ.
• messageAlign: Integer — محاذاة سطر الرسالة: TextAlign.Left أو TextAlign.Center أو TextAlign.Right. أي قيمة أخرى توقف الإجراء بخطأ.

القيمة المُرجَعة

معرّف جلسة الرسالة، وهو دائمًا أكبر من 0، لاستخدامه مع UIUpdateDisplayMessage وUICloseDisplayMessage. يُرجَع معرّف حتى عندما تكون الرسائل متوقفة في الإعدادات ولا يظهر شيء.

٢ مثالان: رفع مستوى الصوت مع عرض على الشاشة, رسالة عرض تتحدث مباشرة

UIShowInputBox

UIShowInputBox(prompt: Text, title: Text, defaultText: Text) → Text · بسيط

يعرض مربعًا يطلب من المستخدم كتابة سطر نصي واحد، مع زري OK وCancel. يحظر البرنامج النصي حتى يُغلق المربع، ثم يعيد التركيز إلى النافذة التي كان عليها.

المعلمات

• prompt: Text — السؤال المعروض أعلى حقل النص. يُقتطع النص الذي يزيد على 2000 حرف.
• title: Text — العنوان المعروض في شريط عنوان المربع.
• defaultText: Text — النص الموجود في الحقل عند فتح المربع، محدَّدًا بحيث تحل الكتابة محله. استخدم نصًا فارغًا لحقل فارغ.

القيمة المُرجَعة

النص المكتوب عندما ينقر المستخدم OK (حتى 4096 حرفًا)، أو نص فارغ عند Cancel أو Esc أو زر الإغلاق. النقر على OK مع حقل فارغ يُرجع أيضًا نصًا فارغًا.

٢ مثالان: قراءة رقم كتبه شخص, إيماءة واحدة، عدة خيارات

UIShowMenu

UIShowMenu(items: Text) → Integer · بسيط

يعرض قائمة منبثقة عند مؤشر الماوس، بحيث يمكن لإيماءة أو مفتاح اختصار واحد تقديم عدة خيارات. يحظر البرنامج النصي حتى يختار المستخدم عنصرًا أو يغلق القائمة.

المعلمات

• items: Text — عناصر القائمة، عنصر في كل سطر. السطر الذي يحتوي على - فقط يكون فاصلًا؛ ويتم تخطي الأسطر الفارغة. من 1 إلى 100 عنصر، وإلا يتوقف الإجراء بخطأ؛ ويُقتطع العنصر الذي يزيد على 260 حرفًا. ضع & قبل حرف لجعله مفتاح الاختصار للعنصر؛ و&& تعرض & واحدة.

القيمة المُرجَعة

موضع العنصر المختار بدءًا من الصفر، مع عدّ العناصر فقط (لا الفواصل)، أو -1 إذا أُغلقت القائمة أو تعذّر عرضها.

١ مثال: إيماءة واحدة، عدة خيارات

UIShowMessageBox

UIShowMessageBox(message: Text, title: Text, buttons: Text, icon: Text) → Text · بسيط

يعرض مربع رسالة قياسيًا من Windows أمام النوافذ الأخرى وينتظر أن يضغط المستخدم زرًا. يحظر البرنامج النصي حتى يُغلق المربع.

المعلمات

• message: Text — نص الرسالة المعروض في المربع.
• title: Text — العنوان المعروض في شريط عنوان المربع.
• buttons: Text — الأزرار المراد عرضها، مكتوبة كما هي تمامًا: OK أو OKCancel أو YesNo أو YesNoCancel أو RetryCancel أو AbortRetryIgnore. أي شيء آخر يوقف الإجراء بخطأ.
• icon: Text — الأيقونة المراد عرضها، مكتوبة كما هي تمامًا: None أو Information أو Warning أو Error أو Question. أي شيء آخر يوقف الإجراء بخطأ.

القيمة المُرجَعة

الزر الذي تم ضغطه: OK أو Cancel أو Yes أو No أو Retry أو Abort أو Ignore (إغلاق المربع بـ Esc أو بزر الإغلاق الخاص به يُرجع Cancel عندما يكون هناك زر Cancel). نص فارغ إذا تعذّر عرض المربع.

٣ أمثلة: قراءة رقم كتبه شخص, إغلاق النوافذ حسب نمط العنوان، بعد التأكيد, طرح سؤال

UIShowSettings

UIShowSettings() → Bool · بسيط

يفتح نافذة إعدادات Input.Observer، أو يُحضرها إلى المقدمة إذا كانت مفتوحة بالفعل. يعود دون انتظار انتهاء تحميل النافذة.

المعلمات

لا توجد معلمات.

القيمة المُرجَعة

true إذا تم إحضار نافذة الإعدادات إلى المقدمة أو بدأ تشغيلها؛ false إذا كان Input.Observer.UI.exe مفقودًا، أو تعذّر بدء تشغيله، أو لم يستجب المحرك خلال 3 ثوانٍ.

UIUpdateDisplayMessage

UIUpdateDisplayMessage(sessionId: Integer, title: Text, message: Text, durationMs: Integer, opacity: Real, location: Any, titleFontFamily: Text, titleFontSizePt: Integer, titleBold: Bool, titleItalic: Bool, messageFontFamily: Text, messageFontSizePt: Integer, messageBold: Bool, messageItalic: Bool, foreColor: Text, backColor: Text, paddingPx: Integer, usePrimaryScreen: Bool, titleAlign: Integer, messageAlign: Integer) → Bool

يستبدل كل خصائص لوحة UIShowDisplayMessage مفتوحة (النص والموضع والخطوط والألوان والمدة) بقيم جديدة. تبدأ المدة من جديد اعتبارًا من هذا الاستدعاء.

المعلمات

• sessionId: Integer — المعرّف الذي أرجعه UIShowDisplayMessage للرسالة المراد تغييرها.
• title: Text — النص الجديد للسطر العلوي، مرسومًا بخط العنوان. النص الفارغ يحذف السطر.
• message: Text — النص الجديد للسطر الثاني، مرسومًا بخط الرسالة. يلتف النص الطويل على أسطر إضافية. النص الفارغ يحذف السطر.
• durationMs: Integer — مدة بقاء اللوحة اعتبارًا من الآن، بالمللي ثانية. القيمة 0 أو أقل تبقيها حتى يغلقها UICloseDisplayMessage (تُغلق اللوحة المضمَّنة أيضًا بالنقر المزدوج).
• opacity: Real — مدى تعتيم اللوحة، من 0.05 (شبه غير مرئية) إلى 1.0 (معتمة تمامًا). تُقيَّد القيم الواقعة خارج هذا النطاق بحدوده.
• location: Any — مكان العرض: ثابت Location مثل Location.BottomCenter (يوضع داخل منطقة الشاشة التي لا يغطيها شريط المهام)، أو قيمة Text بالصيغة 'x,y' بلا مسافات تحدد الزاوية العلوية اليسرى للوحة بوحدات بكسل الشاشة، مثل '100,200'. أي شيء آخر يوقف الإجراء بخطأ.
• titleFontFamily: Text — اسم الخط لسطر العنوان، مثل Segoe UI.
• titleFontSizePt: Integer — حجم خط العنوان بالنقاط. القيم الأقل من 1 تُحتسب 1.
• titleBold: Bool — true لرسم سطر العنوان بخط غامق.
• titleItalic: Bool — true لرسم سطر العنوان بخط مائل.
• messageFontFamily: Text — اسم الخط لسطر الرسالة، مثل Segoe UI.
• messageFontSizePt: Integer — حجم خط الرسالة بالنقاط. القيم الأقل من 1 تُحتسب 1.
• messageBold: Bool — true لرسم سطر الرسالة بخط غامق.
• messageItalic: Bool — true لرسم سطر الرسالة بخط مائل.
• foreColor: Text — لون النص لكلا السطرين: اسم لون مثل white أو black، أو '#RRGGBB'، أو 'R,G,B' بحيث يكون كل رقم من 0 إلى 255 وبلا مسافات. أي شيء آخر يوقف الإجراء بخطأ.
• backColor: Text — لون الخلفية، بالصيغ نفسها المستخدمة في foreColor، مثل '#F7F7F5'. استخدم opacity، لا اللون، لجعل اللوحة شفافة.
• paddingPx: Integer — المساحة الفارغة حول النص، بالبكسل عند تحجيم العرض بنسبة 100 بالمائة؛ وتكبر مع مقياس العرض. القيم الأقل من 0 تُحتسب 0.
• usePrimaryScreen: Bool — true لوضع Location على الشاشة الرئيسية؛ false لاستخدام الشاشة التي يوجد عليها مؤشر الماوس الآن. يتم تجاهله لموقع بالصيغة 'x,y'.
• titleAlign: Integer — محاذاة سطر العنوان: TextAlign.Left أو TextAlign.Center أو TextAlign.Right. أي قيمة أخرى توقف الإجراء بخطأ.
• messageAlign: Integer — محاذاة سطر الرسالة: TextAlign.Left أو TextAlign.Center أو TextAlign.Right. أي قيمة أخرى توقف الإجراء بخطأ.

القيمة المُرجَعة

true دائمًا، بما في ذلك عندما تكون الرسالة قد أُغلقت بالفعل (وعندئذ لا يفعل الاستدعاء شيئًا).

١ مثال: رسالة عرض تتحدث مباشرة

Utility

UtilityGetTickCount

UtilityGetTickCount() → Integer

يُرجع عدد المللي ثانية منذ بدء تشغيل Windows. اطرح قراءتين لقياس الوقت المنقضي، مثلًا لاكتشاف تشغيل مزدوج. هذه ليست ساعة؛ استخدم DateTimeGetNow لمعرفة الوقت من اليوم.

المعلمات

لا توجد معلمات.

القيمة المُرجَعة

المللي ثانية منذ بدء تشغيل Windows، كقيمة Integer.

UtilityLockAcquire

UtilityLockAcquire(name: Text, timeoutSeconds: Integer) → Integer

يأخذ قفلًا مسمى بحيث لا يشغّل قسمًا من البرنامج النصي سوى إجراء واحد في كل مرة. يحظر البرنامج النصي حتى يصبح القفل حرًا أو تنقضي timeoutSeconds. يُحرَّر القفل تلقائيًا عند انتهاء البرنامج النصي.

المعلمات

• name: Text — اسم القفل، من 1 إلى 255 حرفًا، مشترك بين كل الإجراءات؛ والأحرف الكبيرة والصغيرة متماثلة. يُسمح بأخذ قفل يحتجزه هذا البرنامج النصي بالفعل مرة أخرى، ويتطلب ذلك استدعاءً إضافيًا لـ UtilityLockRelease.
• timeoutSeconds: Integer — أطول مدة للانتظار، بالثواني. القيمة 0، أو أكثر من 24 يومًا، تنتظر حتى يصبح القفل حرًا أو يتم إيقاف الإجراء. القيمة السالبة توقف الإجراء بخطأ.

القيمة المُرجَعة

LockResult.Acquired، أو LockResult.TimedOut (أيضًا عند إيقاف الإجراء أثناء الانتظار)، أو LockResult.Pinned فورًا إذا كان القفل مثبَّتًا.

١ مثال: السماح لإجراء واحد فقط بتشغيل مقطع في كل مرة

UtilityLockAcquirePinned

UtilityLockAcquirePinned(name: Text, timeoutSeconds: Integer) → Integer

يأخذ قفلًا مسمى ويثبّته، فيبقى مأخوذًا بعد انتهاء البرنامج النصي. لا يحرره إلا UtilityLockRelease من تشغيل البرنامج النصي نفسه، أو إعادة تحميل التكوين. يحظر مثل UtilityLockAcquire.

المعلمات

• name: Text — اسم القفل، من 1 إلى 255 حرفًا، مشترك بين كل الإجراءات؛ والأحرف الكبيرة والصغيرة متماثلة. القفل الذي يحتجزه هذا البرنامج النصي بالفعل يصبح مثبَّتًا.
• timeoutSeconds: Integer — أطول مدة للانتظار، بالثواني. القيمة 0، أو أكثر من 24 يومًا، تنتظر حتى يصبح القفل حرًا أو يتم إيقاف الإجراء. القيمة السالبة توقف الإجراء بخطأ.

القيمة المُرجَعة

LockResult.Acquired، أو LockResult.TimedOut (أيضًا عند إيقاف الإجراء أثناء الانتظار)، أو LockResult.Pinned فورًا إذا كان القفل مثبَّتًا بالفعل.

UtilityLockGetState

UtilityLockGetState(name: Text) → Integer

يُبلغ عما إذا كان قفل مسمى حرًا، أو يحتجزه هذا البرنامج النصي، أو يحتجزه إجراء آخر، أو مثبَّتًا. لا ينتظر أبدًا.

المعلمات

• name: Text — اسم القفل، من 1 إلى 255 حرفًا؛ والأحرف الكبيرة والصغيرة متماثلة.

القيمة المُرجَعة

LockState.Free أو LockState.HeldByMe أو LockState.HeldByOther أو LockState.Pinned. يُبلغ القفل المثبَّت عن LockState.Pinned حتى للبرنامج النصي الذي ثبّته.

UtilityLockRelease

UtilityLockRelease(name: Text) → Bool

يحرر قفلًا مسمى يحتجزه هذا البرنامج النصي، أو يزيل تثبيته. القفل المأخوذ عدة مرات يُحرَّر بعد العدد نفسه من عمليات التحرير.

المعلمات

• name: Text — اسم القفل، من 1 إلى 255 حرفًا؛ والأحرف الكبيرة والصغيرة متماثلة.

القيمة المُرجَعة

true إذا كان هذا البرنامج النصي يحتجز القفل؛ false، دون فعل أي شيء، إذا لم يكن أحد يحتجزه أو كان إجراء آخر يحتجزه.

١ مثال: السماح لإجراء واحد فقط بتشغيل مقطع في كل مرة

UtilityPrint

UtilityPrint(text: Text) → Bool

يكتب سطرًا نصيًا في قسم «المستخدم» في وحدة التحكم التشخيصية، أو في إخراج قسم «البرنامج النصي» عندما يعمل البرنامج النصي من هناك. تظهر الأسطر المطبوعة أثناء إغلاق وحدة التحكم عند فتحها في المرة التالية.

المعلمات

• text: Text — النص المراد كتابته. حوّل الرقم إلى Text أولًا باستخدام StringFormat أو StringFromNumber.

القيمة المُرجَعة

true دائمًا.

٧٠ مثالًا: مرحبًا، وحدة التحكم, أنواع القيم الخمسة, قيمة الصدق لكل نوع, سلسلة else-if, حلقات العد: تصاعديًا وتنازليًا وبخطوات, حلقات متداخلة: جدول الضرب, حلقة while: انتظار نافذة، مع مهلة, while (true) مع علامة خروج, break وcontinue, مفاجآت الأولوية, && و|| تُقيِّمان الطرفين, المساواة بين الأنواع, العمليات الحسابية على الأنواع المختلطة ترجع إلى 0, التعليقات والعبارات الفارغة والكتل, قسمة Integer مقابل Real، والقسمة على صفر, باقي القسمة بدون %, التقريب والدوال المضمَّنة الرياضية لقيم Real, حصر قيمة ضمن نطاق, أرقام عشوائية ورمي عملة, طول خط الإيماءة, تنسيق قيمة Real بدون ست خانات عشرية, أقنعة العلامات: التعيين والمسح والتبديل والاختبار, قراءة لون البكسل أسفل المؤشر, Integer إلى نص ست عشري, عدّ البتات المعيَّنة, الحالات الحدية للإزاحة, تبديل قيمتي Integer, بتات حالة المفتاح, تسلسلات الهروب في السلاسل النصية ومسارات Windows, تنسيق أكثر من قيمتين, التقسيم والمرور على الأجزاء, التقسيمات المتداخلة: أزواج key=value, آخر فهرس: امتداد الملف, قراءة رقم كتبه شخص, تشغيل برنامج وانتظار نافذته والعمل عليها, استخراج قيمة من نص منسوخ باستخدام تعبير نمطي, حشو رقم بالأصفار, عكس قيمة Text, عدّ الكلمات في الحافظة, مقارنات غير حساسة لحالة الأحرف, ترتيب النص ترتيبي, تاريخ اليوم، واسم ملف مختوم بالوقت, الثوابت المسماة مقابل الأرقام الخام, سرد النوافذ المرئية ذات المستوى الأعلى, تصغير كل نوافذ تطبيق واحد, فحص عناصر التحكم التابعة للنافذة, من العملية إلى النافذة, وصف ما يوجد أسفل المؤشر, كل ما يعرفه سياق المشغِّل, في أي اتجاه سار الخط؟, التفرع حسب زر الخط, حفظ صورة منسوخة في ملف, قراءة ملف وعدّ أسطره, عدّ أنواع الملفات في مجلد, مراقبة مجلد, مؤقت متكرر يعدّ, سرد المؤقتات وإيقافها, عدّاد يبقى بعد إعادة التشغيل, قائمة محفوظة في Storage, السماح لإجراء واحد فقط بتشغيل مقطع في كل مرة, طرح سؤال, توسيع متغيرات البيئة, التسليم إلى AutoHotkey, سرد الشاشات, حالة المحرك, المقتطفات كدوال قابلة لإعادة الاستخدام, التواصل مع مكوّن إضافي, طرح سؤال على جهاز تسلسلي, سرد منافذ COM, إبقاء منفذ Arduino مفتوحًا وإرسال الأوامر إليه

UtilityWait

UtilityWait(milliseconds: Integer) → Bool · بسيط

يوقف البرنامج النصي مؤقتًا لعدد من المللي ثانية، مثلًا لإتاحة الوقت لنافذة أو للحافظة لتلحق بالركب. ينتهي الانتظار مبكرًا إذا تم إيقاف الإجراء.

المعلمات

• milliseconds: Integer — مدة الانتظار، بالمللي ثانية، من 0 إلى 60000 (دقيقة واحدة). القيم الأكبر تنتظر دقيقة واحدة؛ والقيم السالبة لا تنتظر.

القيمة المُرجَعة

true دائمًا.

١٠ أمثلة: حلقة while: انتظار نافذة، مع مهلة, تحريك الماوس في دائرة, ملء قالب ولصقه, النقر في مكان ما، ثم إعادة المؤشر, سحب ببرنامج نصي, حصر المؤشر داخل نافذة لمدة 5 ثوانٍ, مفاتيح الوسائط, تحويل النص المحدد إلى أحرف كبيرة, البحث في الويب عن التحديد, رسالة عرض تتحدث مباشرة

Window

WindowCenterToScreen

WindowCenterToScreen(window: Window) → Bool · بسيط

ينقل نافذة بحيث تتوسط منطقة العمل (الشاشة باستثناء شريط المهام) في الشاشة الموجودة عليها، مع الاحتفاظ بحجمها.

المعلمات

• window: Window — النافذة المراد توسيطها.

القيمة المُرجَعة

true إذا تحركت النافذة؛ false إذا كانت النافذة فارغة أو مغلقة، أو رفضت التحرك.

٢ مثالان: حلقة while: انتظار نافذة، مع مهلة, تذكّر موضع النافذة واستعادته

WindowClipToScreen

WindowClipToScreen(window: Window) → Bool

يقلّص نافذة وينقلها بالقدر الكافي فقط بحيث لا تتجاوز أي حافة منها منطقة العمل (الشاشة باستثناء شريط المهام) في الشاشة الموجودة عليها. النافذة الواقعة بالكامل خارج منطقة العمل تُنقل أولًا إليها بحجمها الحالي.

المعلمات

• window: Window — النافذة المراد قصّها لتناسب منطقة العمل.

القيمة المُرجَعة

true إذا تم وضع النافذة، بما في ذلك عندما تكون داخل منطقة العمل بالفعل؛ false إذا كانت النافذة فارغة أو مغلقة، أو رفضت التغيير.

WindowClose

WindowClose(window: Window) → Bool · بسيط

يطلب من نافذة أن تُغلق، كما لو نقر المستخدم زر الإغلاق الخاص بها. قد يطلب البرنامج حفظ التغييرات أو يرفض؛ استخدم WindowWaitClose للانتظار حتى تختفي.

المعلمات

• window: Window — النافذة المراد إغلاقها.

القيمة المُرجَعة

true إذا تم إرسال طلب الإغلاق، وهذا لا يعني أن النافذة أُغلقت؛ false إذا كانت النافذة فارغة أو مغلقة، أو كانت تنتمي إلى برنامج يعمل بصلاحيات أعلى، مثل التشغيل كمسؤول.

٣ أمثلة: إغلاق النوافذ حسب نمط العنوان، بعد التأكيد, التفرع حسب زر الخط, تغيير السلوك أثناء الضغط على Ctrl

WindowContainsTitle

WindowContainsTitle(window: Window, text: Text) → Bool

يتحقق مما إذا كان عنوان نافذة يحتوي على نص ما، مع تجاهل حالة الأحرف.

المعلمات

• window: Window — النافذة المراد فحص عنوانها.
• text: Text — النص المراد البحث عنه في أي موضع من العنوان. يتم تجاهل حالة الأحرف.

القيمة المُرجَعة

true إذا احتوى العنوان على text، وtrue دائمًا عندما تكون قيمة text فارغة؛ وإلا false، بما في ذلك لنافذة فارغة أو مغلقة.

WindowControlFromPoint

WindowControlFromPoint(x: Integer, y: Integer) → Window

يُرجع النافذة الأعمق عند نقطة على الشاشة، مثل زر أو مربع نص أو عنصر تحكم آخر داخل نافذة برنامج. يتم تخطي النوافذ المخفية والمعطّلة.

المعلمات

• x: Integer — الموضع الأفقي على الشاشة، بوحدات بكسل الشاشة الظاهرية.
• y: Integer — الموضع الرأسي على الشاشة، بوحدات بكسل الشاشة الظاهرية.

القيمة المُرجَعة

عنصر التحكم أو النافذة أسفل النقطة، أو نافذة فارغة إذا لم يوجد أي منهما.

١ مثال: وصف ما يوجد أسفل المؤشر

WindowEnsureVisible

WindowEnsureVisible(window: Window) → Bool

يزلق نافذة لتصبح بالكامل داخل منطقة العمل في الشاشة الموجودة عليها، دون تغيير حجمها. النافذة الأكبر من منطقة العمل تُحاذى مع الزاوية العلوية اليسرى لمنطقة العمل.

المعلمات

• window: Window — النافذة المراد إظهارها بالكامل على الشاشة.

القيمة المُرجَعة

true إذا تم وضع النافذة، بما في ذلك عندما تكون مرئية بالكامل بالفعل؛ false إذا كانت النافذة فارغة أو مغلقة، أو رفضت التحرك.

WindowFindAllByModuleRegex

WindowFindAllByModuleRegex(pattern: Text) → Integer

يعثر على كل نافذة ذات مستوى أعلى، بما فيها المخفية، يطابق مسار ملف برنامجها تعبيرًا عاديًا، ويحتفظ بالقائمة من أجل WindowGetEnumeratedAt. يستبدل أي قائمة نوافذ سابقة.

المعلمات

• pattern: Text — تعبير عادي تتم مطابقته، مع تجاهل حالة الأحرف، مع المسار الكامل للبرنامج الذي يملك كل نافذة، مثل 'notepad[.]exe$'.

القيمة المُرجَعة

عدد النوافذ المطابقة، أو 0 إذا لم تتطابق أي نافذة. النمط غير الصالح يوقف الإجراء بخطأ.

١ مثال: تصغير كل نوافذ تطبيق واحد

WindowFindAllByTitleRegex

WindowFindAllByTitleRegex(pattern: Text) → Integer

يعثر على كل نافذة ذات مستوى أعلى، بما فيها المخفية، يطابق عنوانها تعبيرًا عاديًا، ويحتفظ بالقائمة من أجل WindowGetEnumeratedAt. يستبدل أي قائمة نوافذ سابقة.

المعلمات

• pattern: Text — تعبير عادي تتم مطابقته مع عنوان كل نافذة، مع تجاهل حالة الأحرف. يتطابق في أي موضع من العنوان ما لم يُثبَّت بـ ^ أو $.

القيمة المُرجَعة

عدد النوافذ المطابقة، أو 0 إذا لم تتطابق أي نافذة. النمط غير الصالح يوقف الإجراء بخطأ.

١ مثال: إغلاق النوافذ حسب نمط العنوان، بعد التأكيد

WindowFindByClassName

WindowFindByClassName(className: Text) → Window

يعثر على النافذة المرئية ذات المستوى الأعلى الأقرب إلى المقدمة التي يحتوي اسم فئتها على النص المحدد، مع تجاهل حالة الأحرف.

المعلمات

• className: Text — النص المراد البحث عنه في اسم الفئة، مثل 'Notepad'. يتطابق جزء من الاسم؛ والنص الفارغ يطابق النافذة المرئية الأقرب إلى المقدمة.

القيمة المُرجَعة

النافذة التي عُثر عليها، أو نافذة فارغة إذا لم تتطابق أي نافذة مرئية ذات مستوى أعلى.

WindowFindByTitle

WindowFindByTitle(title: Text) → Window

يعثر على النافذة المرئية ذات المستوى الأعلى الأقرب إلى المقدمة التي يحتوي عنوانها على النص المحدد، مع تجاهل حالة الأحرف.

المعلمات

• title: Text — النص المراد البحث عنه في أي موضع من العنوان. يتم تجاهل حالة الأحرف؛ والنص الفارغ يطابق النافذة المرئية الأقرب إلى المقدمة.

القيمة المُرجَعة

النافذة التي عُثر عليها، أو نافذة فارغة إذا لم تتطابق أي نافذة مرئية ذات مستوى أعلى.

٤ أمثلة: قيمة الصدق لكل نوع, حلقة while: انتظار نافذة، مع مهلة, المساواة بين الأنواع, النقر على نقطة داخل نافذة

WindowFitToScreen

WindowFitToScreen(window: Window) → Bool · بسيط

يغيّر حجم نافذة وينقلها بحيث تملأ حوافها المرئية منطقة العمل (الشاشة باستثناء شريط المهام) في الشاشة الموجودة عليها، دون تكبيرها إلى الحد الأقصى.

المعلمات

• window: Window — النافذة المراد ملاءمتها لمنطقة العمل.

القيمة المُرجَعة

true إذا تم تغيير حجم النافذة؛ false إذا كانت النافذة فارغة أو مغلقة، أو رفضت التغيير.

WindowFromPoint

WindowFromPoint(x: Integer, y: Integer) → Window

يُرجع النافذة ذات المستوى الأعلى عند نقطة على الشاشة، مثل نافذة البرنامج أسفل الماوس، بدلًا من عنصر التحكم الموجود داخلها.

المعلمات

• x: Integer — الموضع الأفقي على الشاشة، بوحدات بكسل الشاشة الظاهرية.
• y: Integer — الموضع الرأسي على الشاشة، بوحدات بكسل الشاشة الظاهرية.

القيمة المُرجَعة

النافذة ذات المستوى الأعلى أسفل النقطة، أو نافذة فارغة إذا لم توجد أي نافذة.

WindowFromProcessId

WindowFromProcessId(processId: Integer) → Window

يُرجع النافذة الرئيسية لبرنامج قيد التشغيل: النافذة المرئية ذات المستوى الأعلى الأقرب إلى المقدمة التي تملكها تلك العملية.

المعلمات

• processId: Integer — معرّف العملية، كما يُرجعه WindowGetProcessId أو ShellGetEnumeratedProcessIdAt.

القيمة المُرجَعة

النافذة، أو نافذة فارغة إذا لم تكن للعملية نافذة مرئية ذات مستوى أعلى أو كانت قيمة processId تساوي 0.

١ مثال: من العملية إلى النافذة

WindowGetActive

WindowGetActive() → Window

يُرجع النافذة الأمامية: النافذة ذات المستوى الأعلى التي يعمل فيها المستخدم حاليًا.

المعلمات

لا توجد معلمات.

القيمة المُرجَعة

النافذة النشطة، أو نافذة فارغة إذا لم تكن هناك نافذة نشطة في تلك اللحظة، مثلًا أثناء انتقال التركيز.

٤ أمثلة: أنواع القيم الخمسة, تنسيق أكثر من قيمتين, مقارنات غير حساسة لحالة الأحرف, محاذاة النافذة النشطة إلى النصف الأيسر من شاشتها

WindowGetAllChildren

WindowGetAllChildren(window: Window, directOnly: Bool) → Integer

يسرد النوافذ التابعة (عناصر التحكم) داخل نافذة ويحتفظ بالقائمة من أجل WindowGetEnumeratedAt. يستبدل أي قائمة نوافذ سابقة.

المعلمات

• window: Window — النافذة المراد سرد نوافذها التابعة.
• directOnly: Bool — true للنوافذ التابعة المباشرة للنافذة فقط؛ false لكل الفروع على كل المستويات.

القيمة المُرجَعة

عدد النوافذ التابعة التي عُثر عليها، أو 0 إذا لم توجد أي منها أو كانت النافذة فارغة.

١ مثال: فحص عناصر التحكم التابعة للنافذة

WindowGetAllProps

WindowGetAllProps(window: Window) → Integer

يسرد كل خاصية مخزَّنة على نافذة، سواء خزّنها هذا المحرك أو البرنامج نفسه أو برامج أخرى، ويحتفظ بالقائمة من أجل WindowGetEnumeratedPropNameAt وWindowGetEnumeratedPropValueAt.

المعلمات

• window: Window — النافذة المراد سرد خصائصها.

القيمة المُرجَعة

عدد الخصائص التي عُثر عليها، أو 0 إذا لم توجد أي منها أو كانت النافذة فارغة.

WindowGetAllTopLevel

WindowGetAllTopLevel() → Integer

يسرد كل نافذة ذات مستوى أعلى على سطح المكتب، من الأمام إلى الخلف، بما فيها المخفية والمحجوبة، ويحتفظ بالقائمة من أجل WindowGetEnumeratedAt. يستبدل أي قائمة نوافذ سابقة.

المعلمات

لا توجد معلمات.

القيمة المُرجَعة

عدد النوافذ ذات المستوى الأعلى التي عُثر عليها.

١ مثال: سرد النوافذ المرئية ذات المستوى الأعلى

WindowGetAlpha

WindowGetAlpha(window: Window) → Integer

يُرجع مستوى شفافية نافذة، كما عيّنه WindowSetAlpha أو البرنامج نفسه.

المعلمات

• window: Window — النافذة المراد قراءتها.

القيمة المُرجَعة

قيمة من 0 (شفافة تمامًا) إلى 255 (معتمة تمامًا). القيمة 255 لنافذة لم تُعيَّن لها شفافية، ولنافذة فارغة أو مغلقة.

١ مثال: التنقل بين مستويات شفافية النافذة

WindowGetClassName

WindowGetClassName(window: Window) → Text

يُرجع اسم فئة نافذة، وهو اسم النوع الذي يستخدمه Windows لها، مثل 'Notepad' أو 'Button'. مفيد للتعرف على النوافذ التي تتغير عناوينها.

المعلمات

• window: Window — النافذة المراد قراءتها.

القيمة المُرجَعة

اسم الفئة، أو نص فارغ إذا كانت النافذة فارغة أو مغلقة.

٢ مثالان: فحص عناصر التحكم التابعة للنافذة, وصف ما يوجد أسفل المؤشر

WindowGetControlText

WindowGetControlText(window: Window) → Text

يقرأ نص عنصر تحكم في أي برنامج، مثل مربع نص أو شريط حالة أو رسالة مربع حوار. يعمل مع عناصر تحكم Windows الكلاسيكية فقط. يحظر البرنامج النصي لمدة تصل إلى ثانيتين إذا لم يستجب البرنامج.

المعلمات

• window: Window — عنصر التحكم أو النافذة المراد قراءتها، مثلًا من WindowControlFromPoint أو WindowGetEnumeratedAt.

القيمة المُرجَعة

نص عنصر التحكم، حتى مليون حرف تقريبًا، أو نص فارغ إذا لم يكن له نص، أو كانت النافذة فارغة أو مغلقة، أو لم يستجب البرنامج. مربع كلمة المرور في برنامج آخر يعطي نصًا فارغًا.

WindowGetDpi

WindowGetDpi(window: Window) → Integer

يُرجع قيمة DPI للشاشة الموجودة عليها نافذة: 96 عند تحجيم العرض بنسبة 100 بالمائة، و144 عند 150 بالمائة.

المعلمات

• window: Window — النافذة المراد فحصها.

القيمة المُرجَعة

قيمة DPI، أو 0 إذا كانت النافذة فارغة أو مغلقة.

WindowGetEnabled

WindowGetEnabled(window: Window) → Bool

يتحقق مما إذا كانت نافذة تقبل إدخال الماوس ولوحة المفاتيح. تظهر النافذة أو عنصر التحكم المعطّل عادةً باللون الرمادي.

المعلمات

• window: Window — النافذة المراد فحصها.

القيمة المُرجَعة

true إذا كانت النافذة ممكَّنة؛ false إذا كانت معطّلة أو فارغة أو مغلقة.

WindowGetEnumeratedAt

WindowGetEnumeratedAt(index: Integer) → Window

يُرجع نافذة واحدة من القائمة التي أنشأها آخر استدعاء لـ WindowGetAllTopLevel أو WindowGetAllChildren أو WindowFindAllByTitleRegex أو WindowFindAllByModuleRegex.

المعلمات

• index: Integer — الموضع في القائمة، من 0 حتى العدد الذي أرجعه استدعاء السرد ناقص 1.

القيمة المُرجَعة

النافذة في ذلك الموضع، أو نافذة فارغة إذا كان index خارج النطاق.

٤ أمثلة: سرد النوافذ المرئية ذات المستوى الأعلى, تصغير كل نوافذ تطبيق واحد, إغلاق النوافذ حسب نمط العنوان، بعد التأكيد, فحص عناصر التحكم التابعة للنافذة

WindowGetEnumeratedPropNameAt

WindowGetEnumeratedPropNameAt(index: Integer) → Text

يُرجع اسم خاصية واحدة من القائمة التي أنشأها آخر استدعاء لـ WindowGetAllProps.

المعلمات

• index: Integer — الموضع في القائمة، من 0 حتى العدد الذي أرجعه WindowGetAllProps ناقص 1.

القيمة المُرجَعة

اسم الخاصية، أو نص فارغ إذا كان index خارج النطاق.

WindowGetEnumeratedPropValueAt

WindowGetEnumeratedPropValueAt(index: Integer) → Integer

يُرجع القيمة الصحيحة الأولية لخاصية واحدة من القائمة التي أنشأها آخر استدعاء لـ WindowGetAllProps. الخاصية المعيَّنة باستخدام WindowSetPropertyText تُظهر هنا رقمًا داخليًا، لا نصها.

المعلمات

• index: Integer — الموضع في القائمة، من 0 حتى العدد الذي أرجعه WindowGetAllProps ناقص 1.

القيمة المُرجَعة

قيمة الخاصية، أو 0 إذا كان index خارج النطاق.

WindowGetExecutableFolder

WindowGetExecutableFolder(window: Window) → Text

يُرجع المجلد الذي يحتوي على البرنامج الذي يملك نافذة، بدون اسم الملف وبدون فاصل في النهاية. استخدم WindowGetExecutableName للحصول على اسم الملف، أو WindowGetExecutableFullPath للحصول على كليهما.

المعلمات

• window: Window — النافذة المراد تحديد موقع برنامجها.

القيمة المُرجَعة

مسار المجلد، أو نص فارغ إذا كانت النافذة فارغة أو مغلقة أو تعذّر الاستعلام عن البرنامج.

WindowGetExecutableFullPath

WindowGetExecutableFullPath(window: Window) → Text

يُرجع المسار الكامل للبرنامج الذي يملك نافذة، المجلد واسم الملف معًا، مثل مسار notepad.exe في مجلد Windows. استخدم WindowGetExecutableFolder أو WindowGetExecutableName للحصول على جزء واحد.

المعلمات

• window: Window — النافذة المراد تحديد موقع برنامجها.

القيمة المُرجَعة

المسار الكامل، أو نص فارغ إذا كانت النافذة فارغة أو مغلقة أو تعذّر الاستعلام عن البرنامج.

WindowGetExecutableName

WindowGetExecutableName(window: Window) → Text

يُرجع اسم ملف البرنامج الذي يملك نافذة، مثل 'notepad.exe'.

المعلمات

• window: Window — النافذة المراد التعرف على برنامجها.

القيمة المُرجَعة

اسم ملف البرنامج، أو نص فارغ إذا كانت النافذة فارغة أو مغلقة أو تعذّر الاستعلام عن البرنامج.

٢ مثالان: مقارنات غير حساسة لحالة الأحرف, سرد النوافذ المرئية ذات المستوى الأعلى

WindowGetHeight

WindowGetHeight(window: Window) → Integer

يُرجع الارتفاع المرئي لنافذة، باستثناء حد تغيير الحجم غير المرئي الذي يضيفه Windows حول معظم النوافذ.

المعلمات

• window: Window — النافذة المراد قياسها.

القيمة المُرجَعة

الارتفاع بالبكسل، أو 0 إذا كانت النافذة فارغة أو مغلقة.

٣ أمثلة: تنسيق أكثر من قيمتين, محاذاة النافذة النشطة إلى النصف الأيسر من شاشتها, حصر المؤشر داخل نافذة لمدة 5 ثوانٍ

WindowGetLastFocus

WindowGetLastFocus() → Window

يُرجع النافذة أو عنصر التحكم الذي تلقى تركيز لوحة المفاتيح مؤخرًا في أي مكان على سطح المكتب. غالبًا ما يكون عنصر تحكم مثل مربع نص بدلًا من نافذته ذات المستوى الأعلى.

المعلمات

لا توجد معلمات.

القيمة المُرجَعة

آخر نافذة أو عنصر تحكم تلقى التركيز، أو نافذة فارغة إذا لم يتغير التركيز منذ بدء تشغيل المحرك.

WindowGetMovableAncestor

WindowGetMovableAncestor(window: Window) → Window

يُرجع أقرب نافذة يمكن سحبها: النافذة نفسها أو أول نافذة أصل فوقها لها قائمة نظام. يحوّل عنصر التحكم أسفل الماوس إلى النافذة المراد نقلها.

المعلمات

• window: Window — النافذة أو عنصر التحكم المراد البدء منه.

القيمة المُرجَعة

النافذة نفسها أو أول نافذة أصل لها قائمة نظام، أو نافذة فارغة إذا لم تكن لأي منها قائمة نظام أو كانت النافذة فارغة.

WindowGetParent

WindowGetParent(window: Window) → Window

يُرجع النافذة التي تحتوي على عنصر تحكم. بالنسبة لنافذة منبثقة مثل مربع حوار، قد تكون هذه هي النافذة التي تملكها.

المعلمات

• window: Window — النافذة أو عنصر التحكم المراد الحصول على النافذة الأصل له.

القيمة المُرجَعة

النافذة الأصل أو المالكة، أو نافذة فارغة إذا لم توجد أو كانت النافذة فارغة أو مغلقة.

WindowGetProcessId

WindowGetProcessId(window: Window) → Integer

يُرجع معرّف العملية (البرنامج قيد التشغيل) التي تملك نافذة، وهو الرقم نفسه الذي تعرضه «إدارة المهام».

المعلمات

• window: Window — النافذة المراد التعرف على عمليتها.

القيمة المُرجَعة

معرّف العملية، أو 0 إذا كانت النافذة فارغة أو مغلقة.

WindowGetPropertyInteger

WindowGetPropertyInteger(window: Window, name: Text) → Integer

يقرأ عددًا صحيحًا مسمى مخزَّنًا على نافذة، مثل عدد خُزِّن سابقًا باستخدام WindowSetPropertyInteger لتذكّر شيء ما عن تلك النافذة.

المعلمات

• window: Window — النافذة المراد القراءة منها.
• name: Text — اسم الخاصية.

القيمة المُرجَعة

القيمة المخزَّنة، أو 0 إذا لم تكن الخاصية موجودة أو كانت النافذة فارغة. القيمة 0 المخزَّنة تبدو تمامًا مثل الخاصية المفقودة.

٢ مثالان: تثبيت نافذة في المقدمة, تذكّر موضع النافذة واستعادته

WindowGetPropertyText

WindowGetPropertyText(window: Window, name: Text) → Text

يقرأ قيمة نصية مسماة خزّنها هذا المحرك على نافذة باستخدام WindowSetPropertyText.

المعلمات

• window: Window — النافذة المراد القراءة منها.
• name: Text — اسم الخاصية.

القيمة المُرجَعة

النص المخزَّن، أو نص فارغ إذا لم تكن الخاصية موجودة، أو لم يخزّنها هذا المحرك كنص، أو تمت الكتابة فوقها منذ ذلك الحين، أو كانت النافذة فارغة.

WindowGetRoot

WindowGetRoot(window: Window) → Window

يُرجع النافذة ذات المستوى الأعلى التي تحتوي على نافذة أو عنصر تحكم، مثل نافذة البرنامج المحيطة بزر.

المعلمات

• window: Window — النافذة أو عنصر التحكم المراد البدء منه.

القيمة المُرجَعة

النافذة ذات المستوى الأعلى، وهي النافذة نفسها إذا كانت ذات مستوى أعلى بالفعل؛ أو نافذة فارغة إذا كانت النافذة فارغة أو مغلقة.

١ مثال: وصف ما يوجد أسفل المؤشر

WindowGetTitle

WindowGetTitle(window: Window) → Text

يُرجع النص الموجود في شريط عنوان نافذة. بالنسبة لعناصر التحكم في البرامج الأخرى يكون فارغًا عادةً؛ استخدم WindowGetControlText لها.

المعلمات

• window: Window — النافذة المراد قراءتها.

القيمة المُرجَعة

العنوان، أو نص فارغ إذا لم يكن للنافذة عنوان أو كانت فارغة أو مغلقة.

٩ أمثلة: مقارنات غير حساسة لحالة الأحرف, إيماءة واحدة، عدة خيارات, تثبيت نافذة في المقدمة, سرد النوافذ المرئية ذات المستوى الأعلى, فحص عناصر التحكم التابعة للنافذة, من العملية إلى النافذة, وصف ما يوجد أسفل المؤشر, كل ما يعرفه سياق المشغِّل, قائمة محفوظة في Storage

WindowGetVisible

WindowGetVisible(window: Window) → Bool

يتحقق مما إذا كانت نافذة معيَّنة للعرض. قد تكون النافذة المرئية مع ذلك مصغَّرة، أو مغطاة بنوافذ أخرى، أو خارج الشاشة، أو على سطح مكتب ظاهري آخر.

المعلمات

• window: Window — النافذة المراد فحصها.

القيمة المُرجَعة

true إذا كانت النافذة وكل النوافذ الأصل لها معروضة؛ false إذا كانت مخفية أو فارغة أو مغلقة.

١ مثال: سرد النوافذ المرئية ذات المستوى الأعلى

WindowGetWidth

WindowGetWidth(window: Window) → Integer

يُرجع العرض المرئي لنافذة، باستثناء حد تغيير الحجم غير المرئي الذي يضيفه Windows حول معظم النوافذ.

المعلمات

• window: Window — النافذة المراد قياسها.

القيمة المُرجَعة

العرض بالبكسل، أو 0 إذا كانت النافذة فارغة أو مغلقة.

٣ أمثلة: تنسيق أكثر من قيمتين, محاذاة النافذة النشطة إلى النصف الأيسر من شاشتها, حصر المؤشر داخل نافذة لمدة 5 ثوانٍ

WindowGetX

WindowGetX(window: Window) → Integer

يُرجع الموضع على الشاشة للحافة اليسرى المرئية لنافذة، باستثناء حد تغيير الحجم غير المرئي. بالنسبة لنافذة مصغَّرة، يكون هذا موضع إيقاف خارج الشاشة.

المعلمات

• window: Window — النافذة المراد تحديد موقعها.

القيمة المُرجَعة

الحافة اليسرى، بوحدات بكسل الشاشة الظاهرية، أو 0 إذا كانت النافذة فارغة أو مغلقة.

٤ أمثلة: تنسيق أكثر من قيمتين, محاذاة النافذة النشطة إلى النصف الأيسر من شاشتها, تذكّر موضع النافذة واستعادته, حصر المؤشر داخل نافذة لمدة 5 ثوانٍ

WindowGetY

WindowGetY(window: Window) → Integer

يُرجع الموضع على الشاشة للحافة العلوية المرئية لنافذة، باستثناء حد تغيير الحجم غير المرئي. بالنسبة لنافذة مصغَّرة، يكون هذا موضع إيقاف خارج الشاشة.

المعلمات

• window: Window — النافذة المراد تحديد موقعها.

القيمة المُرجَعة

الحافة العلوية، بوحدات بكسل الشاشة الظاهرية، أو 0 إذا كانت النافذة فارغة أو مغلقة.

٤ أمثلة: تنسيق أكثر من قيمتين, محاذاة النافذة النشطة إلى النصف الأيسر من شاشتها, تذكّر موضع النافذة واستعادته, حصر المؤشر داخل نافذة لمدة 5 ثوانٍ

WindowHide

WindowHide(window: Window) → Bool

يخفي نافذة بالكامل، بما في ذلك زرها في شريط المهام. يعرضها المحرك مرة أخرى عند خروجه، ويعيدها الأمر «إظهار النوافذ المخفية» في قائمة منطقة الإعلامات في أي وقت.

المعلمات

• window: Window — النافذة المراد إخفاؤها.

القيمة المُرجَعة

true إذا أُخفيت النافذة أو كانت مخفية بالفعل؛ false إذا كانت فارغة أو مغلقة، أو كانت سطح المكتب أو شريط المهام أو إحدى نوافذ هذا المحرك، أو كان المحرك يتتبع بالفعل 256 نافذة مخفية.

WindowIsCloaked

WindowIsCloaked(window: Window) → Bool

يتحقق مما إذا كان Windows يُبقي نافذة بعيدًا عن الأنظار رغم أنها تُعتبر معروضة، مثل نافذة على سطح مكتب ظاهري آخر أو تطبيق Store معلَّق. مفيد لتخطي مثل هذه النوافذ في قائمة.

المعلمات

• window: Window — النافذة المراد فحصها.

القيمة المُرجَعة

true إذا كانت النافذة محجوبة؛ false إذا لم تكن كذلك، أو كانت النافذة فارغة أو مغلقة.

١ مثال: سرد النوافذ المرئية ذات المستوى الأعلى

WindowIsMaximized

WindowIsMaximized(window: Window) → Bool

يتحقق مما إذا كانت نافذة مكبَّرة إلى الحد الأقصى، مثلًا قبل تقرير ما إذا كان سيتم استدعاء WindowRestore أو WindowMaximize.

المعلمات

• window: Window — النافذة المراد فحصها.

القيمة المُرجَعة

true إذا كانت النافذة مكبَّرة إلى الحد الأقصى؛ false إذا لم تكن كذلك، أو كانت النافذة فارغة أو مغلقة.

١ مثال: تبديل التكبير لنافذة الإيماءة

WindowIsMinimized

WindowIsMinimized(window: Window) → Bool

يتحقق مما إذا كانت نافذة مصغَّرة إلى شريط المهام، مثلًا قبل تقرير ما إذا كان سيتم استدعاء WindowRestore.

المعلمات

• window: Window — النافذة المراد فحصها.

القيمة المُرجَعة

true إذا كانت النافذة مصغَّرة؛ false إذا لم تكن كذلك، أو كانت النافذة فارغة أو مغلقة.

WindowMapClientPointToScreenX

WindowMapClientPointToScreenX(window: Window, x: Integer, y: Integer) → Integer

يحوّل نقطة في منطقة العميل لنافذة (الجزء الداخلي من النافذة، أسفل شريط العنوان وداخل الحدود) إلى موضع على الشاشة ويُرجع جزأه الأفقي.

المعلمات

• window: Window — النافذة التي تقع النقطة في منطقة العميل الخاصة بها.
• x: Integer — الموضع الأفقي من الحافة اليسرى لمنطقة العميل، بالبكسل.
• y: Integer — الموضع الرأسي من الحافة العلوية لمنطقة العميل، بالبكسل.

القيمة المُرجَعة

الموضع X على الشاشة، بوحدات بكسل الشاشة الظاهرية، أو 0 إذا كانت النافذة فارغة أو مغلقة.

WindowMapClientPointToScreenY

WindowMapClientPointToScreenY(window: Window, x: Integer, y: Integer) → Integer

يحوّل نقطة في منطقة العميل لنافذة (الجزء الداخلي من النافذة، أسفل شريط العنوان وداخل الحدود) إلى موضع على الشاشة ويُرجع جزأه الرأسي.

المعلمات

• window: Window — النافذة التي تقع النقطة في منطقة العميل الخاصة بها.
• x: Integer — الموضع الأفقي من الحافة اليسرى لمنطقة العميل، بالبكسل.
• y: Integer — الموضع الرأسي من الحافة العلوية لمنطقة العميل، بالبكسل.

القيمة المُرجَعة

الموضع Y على الشاشة، بوحدات بكسل الشاشة الظاهرية، أو 0 إذا كانت النافذة فارغة أو مغلقة.

WindowMapScreenPointToClientX

WindowMapScreenPointToClientX(window: Window, x: Integer, y: Integer) → Integer

يحوّل موضعًا على الشاشة إلى نقطة نسبةً إلى منطقة العميل لنافذة (الجزء الداخلي من النافذة، أسفل شريط العنوان وداخل الحدود) ويُرجع جزأها الأفقي.

المعلمات

• window: Window — النافذة التي يُقاس من منطقة العميل الخاصة بها.
• x: Integer — الموضع الأفقي على الشاشة، بوحدات بكسل الشاشة الظاهرية.
• y: Integer — الموضع الرأسي على الشاشة، بوحدات بكسل الشاشة الظاهرية.

القيمة المُرجَعة

الموضع X من الحافة اليسرى لمنطقة العميل، بالبكسل؛ سالب إذا كانت النقطة على يسارها. 0 إذا كانت النافذة فارغة أو مغلقة.

١ مثال: وصف ما يوجد أسفل المؤشر

WindowMapScreenPointToClientY

WindowMapScreenPointToClientY(window: Window, x: Integer, y: Integer) → Integer

يحوّل موضعًا على الشاشة إلى نقطة نسبةً إلى منطقة العميل لنافذة (الجزء الداخلي من النافذة، أسفل شريط العنوان وداخل الحدود) ويُرجع جزأها الرأسي.

المعلمات

• window: Window — النافذة التي يُقاس من منطقة العميل الخاصة بها.
• x: Integer — الموضع الأفقي على الشاشة، بوحدات بكسل الشاشة الظاهرية.
• y: Integer — الموضع الرأسي على الشاشة، بوحدات بكسل الشاشة الظاهرية.

القيمة المُرجَعة

الموضع Y من الحافة العلوية لمنطقة العميل، بالبكسل؛ سالب إذا كانت النقطة أعلاها. 0 إذا كانت النافذة فارغة أو مغلقة.

١ مثال: وصف ما يوجد أسفل المؤشر

WindowMaximize

WindowMaximize(window: Window) → Bool · بسيط

يكبّر نافذة إلى الحد الأقصى بحيث تملأ الشاشة الموجودة عليها، وينشّطها. النافذة المخفية باستخدام WindowHide تُعرض ولا يعود يُتتبَّع أنها مخفية.

المعلمات

• window: Window — النافذة المراد تكبيرها إلى الحد الأقصى.

القيمة المُرجَعة

true إذا كانت النافذة مكبَّرة إلى الحد الأقصى بعد ذلك؛ false إذا كانت النافذة فارغة أو مغلقة، أو لم تُكبَّر.

٢ مثالان: إيماءة واحدة، عدة خيارات, تبديل التكبير لنافذة الإيماءة

WindowMinimize

WindowMinimize(window: Window) → Bool · بسيط

يصغّر نافذة إلى شريط المهام. ثم ينشّط Windows النافذة التالية. النافذة المخفية باستخدام WindowHide تُعرض مصغَّرة ولا يعود يُتتبَّع أنها مخفية.

المعلمات

• window: Window — النافذة المراد تصغيرها.

القيمة المُرجَعة

true إذا كانت النافذة مصغَّرة بعد ذلك؛ false إذا كانت النافذة فارغة أو مغلقة، أو لم تُصغَّر.

٤ أمثلة: إيماءة واحدة، عدة خيارات, تصغير كل نوافذ تطبيق واحد, التفرع حسب زر الخط, تغيير السلوك أثناء الضغط على Ctrl

WindowMoveTo

WindowMoveTo(window: Window, x: Integer, y: Integer) → Bool

ينقل نافذة بحيث تكون زاويتها العلوية اليسرى المرئية عند موضع على الشاشة، مع الاحتفاظ بحجمها. يستخدم الإحداثيات نفسها التي يستخدمها WindowGetX وWindowGetY؛ ولا تتم استعادة النافذة المكبَّرة إلى الحد الأقصى أولًا.

المعلمات

• window: Window — النافذة المراد نقلها.
• x: Integer — الحافة اليسرى الجديدة للإطار المرئي، بوحدات بكسل الشاشة الظاهرية.
• y: Integer — الحافة العلوية الجديدة للإطار المرئي، بوحدات بكسل الشاشة الظاهرية.

القيمة المُرجَعة

true إذا تحركت النافذة؛ false إذا كانت النافذة فارغة أو مغلقة، أو رفضت التحرك.

٣ أمثلة: محاذاة النافذة النشطة إلى النصف الأيسر من شاشتها, محاذاة نافذة إلى خلية في شبكة 3×2 أسفل المؤشر, تذكّر موضع النافذة واستعادته

WindowRemoveProp

WindowRemoveProp(window: Window, name: Text) → Integer

يزيل خاصية مسماة من نافذة، سواء خُزِّنت باستخدام WindowSetPropertyInteger أو WindowSetPropertyText أو بواسطة برامج أخرى.

المعلمات

• window: Window — النافذة المراد إزالة الخاصية منها.
• name: Text — اسم الخاصية.

القيمة المُرجَعة

القيمة الأولية للخاصية التي تمت إزالتها، أو 0 إذا لم تكن موجودة أو كانت النافذة فارغة. بالنسبة لخاصية نصية، تكون هذه رقمًا داخليًا، لا النص.

٢ مثالان: تثبيت نافذة في المقدمة, تذكّر موضع النافذة واستعادته

WindowResizeTo

WindowResizeTo(window: Window, width: Integer, height: Integer) → Bool

يغيّر حجم الإطار المرئي لنافذة، مع إبقاء زاويتها العلوية اليسرى في مكانها. يستخدم الحجم نفسه الذي يستخدمه WindowGetWidth وWindowGetHeight؛ ولا تتم استعادة النافذة المكبَّرة إلى الحد الأقصى أولًا.

المعلمات

• window: Window — النافذة المراد تغيير حجمها.
• width: Integer — العرض المرئي الجديد، بالبكسل.
• height: Integer — الارتفاع المرئي الجديد، بالبكسل.

القيمة المُرجَعة

true إذا تم تغيير حجم النافذة؛ false إذا كانت النافذة فارغة أو مغلقة، أو رفضت التغيير.

٢ مثالان: محاذاة النافذة النشطة إلى النصف الأيسر من شاشتها, محاذاة نافذة إلى خلية في شبكة 3×2 أسفل المؤشر

WindowRestore

WindowRestore(window: Window) → Bool · بسيط

يعيد نافذة مصغَّرة أو مكبَّرة إلى الحد الأقصى إلى حجمها وموضعها العاديين، وينشّطها. النافذة المخفية باستخدام WindowHide تُعرض ولا يعود يُتتبَّع أنها مخفية.

المعلمات

• window: Window — النافذة المراد استعادتها.

القيمة المُرجَعة

true إذا انتهت النافذة بحجمها العادي، لا مصغَّرة ولا مكبَّرة إلى الحد الأقصى؛ false إذا كانت النافذة فارغة أو مغلقة، أو لم تصل إلى ذلك. النافذة المصغَّرة التي كانت مكبَّرة إلى الحد الأقصى من قبل تعود مكبَّرة إلى الحد الأقصى، وهذا يُحتسب false.

٣ أمثلة: تبديل التكبير لنافذة الإيماءة, محاذاة النافذة النشطة إلى النصف الأيسر من شاشتها, محاذاة نافذة إلى خلية في شبكة 3×2 أسفل المؤشر

WindowSendToBottom

WindowSendToBottom(window: Window) → Bool · بسيط

ينقل نافذة خلف كل النوافذ الأخرى دون تنشيطها. النافذة التي كانت تظهر دائمًا في المقدمة تفقد هذا الإعداد.

المعلمات

• window: Window — النافذة المراد إرسالها إلى الخلف.

القيمة المُرجَعة

true إذا نُقلت النافذة إلى الخلف؛ false إذا كانت النافذة فارغة أو مغلقة، أو رفضت التغيير.

WindowSendToMonitorAt

WindowSendToMonitorAt(window: Window, x: Integer, y: Integer, mouseFollows: Bool) → Bool

ينقل نافذة إلى الشاشة التي تحتوي على نقطة على الشاشة، مع الاحتفاظ بحجمها وموضعها النسبي داخل منطقة العمل. النافذة المكبَّرة إلى الحد الأقصى تصبح مكبَّرة إلى الحد الأقصى على الشاشة الجديدة؛ وإذا أدى ذلك إلى تنشيطها، تستعيد النافذة التي كانت نشطة من قبل التركيز عندما يسمح Windows بذلك.

المعلمات

• window: Window — النافذة المراد نقلها.
• x: Integer — الموضع الأفقي لأي نقطة على الشاشة الهدف، بوحدات بكسل الشاشة الظاهرية. النقطة الواقعة خارج كل الشاشات تختار أقرب شاشة.
• y: Integer — الموضع الرأسي لأي نقطة على الشاشة الهدف، بوحدات بكسل الشاشة الظاهرية.
• mouseFollows: Bool — true لنقل مؤشر الماوس إلى الموضع النسبي نفسه على الشاشة الجديدة عندما تنتقل النافذة؛ false لتركه حيث هو.

القيمة المُرجَعة

true إذا تحركت النافذة؛ false إذا كانت النافذة فارغة أو مغلقة، أو رفضت التحرك.

WindowSendToMonitorIndex

WindowSendToMonitorIndex(window: Window, index: Integer, mouseFollows: Bool) → Bool

ينقل نافذة إلى شاشة تُختار بموضعها في القائمة الناتجة عن آخر استدعاء لـ DisplayMonitorEnumeratedAll، مع الاحتفاظ بحجمها وموضعها النسبي. تبقى النافذة المكبَّرة إلى الحد الأقصى مكبَّرة؛ وإذا أدت إعادة تكبيرها إلى تنشيطها، تستعيد النافذة التي كانت نشطة من قبل التركيز عندما يسمح Windows بذلك.

المعلمات

• window: Window — النافذة المراد نقلها.
• index: Integer — الموضع في قائمة الشاشات، بدءًا من 0. الشاشات مرتبة من اليسار إلى اليمين، ثم من الأعلى إلى الأسفل.
• mouseFollows: Bool — true لنقل مؤشر الماوس إلى الموضع النسبي نفسه على الشاشة الجديدة عندما تنتقل النافذة؛ false لتركه حيث هو.

القيمة المُرجَعة

true إذا تحركت النافذة؛ false إذا كانت النافذة فارغة أو مغلقة، أو كان index خارج النطاق أو لم يُشغَّل DisplayMonitorEnumeratedAll في هذا البرنامج النصي، أو رفضت النافذة التحرك.

١ مثال: إرسال نافذة إلى شاشة محددة

WindowSendToMonitorName

WindowSendToMonitorName(window: Window, name: Text, mouseFollows: Bool) → Bool

ينقل نافذة إلى الشاشة التي لها مسار جهاز أو اسم مألوف محدد، مع الاحتفاظ بحجمها وموضعها النسبي. تبقى النافذة المكبَّرة إلى الحد الأقصى مكبَّرة؛ وإذا أدت إعادة تكبيرها إلى تنشيطها، تستعيد النافذة التي كانت نشطة من قبل التركيز عندما يسمح Windows بذلك. مفيد للتخطيطات التي تصمد عند توصيل الكمبيوتر بقاعدة الإرساء وفصله عنها.

المعلمات

• window: Window — النافذة المراد نقلها.
• name: Text — مسار جهاز الشاشة أو اسمها المألوف، كما يُرجعه DisplayMonitorGetDevicePathFromPoint أو DisplayMonitorGetFriendlyNameFromPoint. مسار الجهاز هو الخيار الموثوق. يتم تجاهل حالة الأحرف.
• mouseFollows: Bool — true لنقل مؤشر الماوس إلى الموضع النسبي نفسه على الشاشة الجديدة عندما تنتقل النافذة؛ false لتركه حيث هو.

القيمة المُرجَعة

true إذا تحركت النافذة؛ false إذا لم تكن هناك شاشة متصلة بهذا الاسم، أو كانت النافذة فارغة أو مغلقة، أو رفضت النافذة التحرك.

WindowSendToNextScreen

WindowSendToNextScreen(window: Window, mouseFollows: Bool) → Bool · بسيط

ينقل نافذة إلى الشاشة التالية، من اليسار إلى اليمين ثم من الأعلى إلى الأسفل، مع العودة من الأخيرة إلى الأولى، مع الاحتفاظ بحجمها وموضعها النسبي. تبقى النافذة المكبَّرة إلى الحد الأقصى مكبَّرة؛ وإذا أدت إعادة تكبيرها إلى تنشيطها، تستعيد النافذة التي كانت نشطة من قبل التركيز عندما يسمح Windows بذلك.

المعلمات

• window: Window — النافذة المراد نقلها.
• mouseFollows: Bool — true لنقل مؤشر الماوس إلى الموضع النسبي نفسه على الشاشة الجديدة عندما تنتقل النافذة؛ false لتركه حيث هو.

القيمة المُرجَعة

true إذا تحركت النافذة، بما في ذلك عندما تكون هناك شاشة واحدة فقط؛ false إذا كانت النافذة فارغة أو مغلقة، أو رفضت التحرك.

٢ مثالان: نقل نافذة إلى الشاشة التالية, إرسال نافذة إلى شاشة محددة

WindowSendToPreviousScreen

WindowSendToPreviousScreen(window: Window, mouseFollows: Bool) → Bool · بسيط

ينقل نافذة إلى الشاشة السابقة، من اليمين إلى اليسار ثم من الأسفل إلى الأعلى، مع العودة من الأولى إلى الأخيرة، مع الاحتفاظ بحجمها وموضعها النسبي. تبقى النافذة المكبَّرة إلى الحد الأقصى مكبَّرة؛ وإذا أدت إعادة تكبيرها إلى تنشيطها، تستعيد النافذة التي كانت نشطة من قبل التركيز عندما يسمح Windows بذلك.

المعلمات

• window: Window — النافذة المراد نقلها.
• mouseFollows: Bool — true لنقل مؤشر الماوس إلى الموضع النسبي نفسه على الشاشة الجديدة عندما تنتقل النافذة؛ false لتركه حيث هو.

القيمة المُرجَعة

true إذا تحركت النافذة، بما في ذلك عندما تكون هناك شاشة واحدة فقط؛ false إذا كانت النافذة فارغة أو مغلقة، أو رفضت التحرك.

WindowSetActive

WindowSetActive(window: Window) → Bool

يُحضر نافذة إلى المقدمة ويمنحها تركيز لوحة المفاتيح، بعد استعادتها أولًا إذا كانت مصغَّرة وإظهارها إذا كانت مخفية. النافذة المخفية باستخدام WindowHide لا يعود يُتتبَّع أنها مخفية. قد يرفض Windows ذلك ويجعل زرها في شريط المهام يومض بدلًا من ذلك.

المعلمات

• window: Window — النافذة المراد تنشيطها.

القيمة المُرجَعة

true إذا أصبحت النافذة هي النافذة الأمامية؛ false إذا رفض Windows ذلك، أو كانت النافذة فارغة أو مغلقة.

٢ مثالان: تشغيل برنامج وانتظار نافذته والعمل عليها, النقر على نقطة داخل نافذة

WindowSetAlpha

WindowSetAlpha(window: Window, alpha: Integer) → Bool

يعيّن مدى شفافية نافذة، من شفافة تمامًا إلى معتمة تمامًا. عند 255 تتوقف النافذة عن كونها نافذة ذات طبقات، مما يزيل أيضًا أي شفافية عيّنها البرنامج بنفسه. لا يمكن تغيير نوافذ البرامج التي تعمل كمسؤول ما لم يكن المحرك يعمل كمسؤول أيضًا.

المعلمات

• window: Window — النافذة المراد تغييرها.
• alpha: Integer — العتامة من 0 (شفافة تمامًا) إلى 255 (معتمة تمامًا). تُقيَّد القيم الواقعة خارج هذا النطاق بحدوده.

القيمة المُرجَعة

true إذا تم تطبيق الشفافية؛ false إذا كانت النافذة فارغة أو مغلقة، أو تم رفض التغيير.

١ مثال: التنقل بين مستويات شفافية النافذة

WindowSetBounds

WindowSetBounds(window: Window, x: Integer, y: Integer, width: Integer, height: Integer) → Bool

ينقل نافذة ويغيّر حجمها في خطوة واحدة، باستخدام إحداثيات الإطار المرئي نفسها التي يستخدمها WindowGetX وWindowGetY وWindowGetWidth وWindowGetHeight. يتجنب الوميض الناتج عن WindowMoveTo متبوعًا بـ WindowResizeTo.

المعلمات

• window: Window — النافذة المراد نقلها وتغيير حجمها.
• x: Integer — الحافة اليسرى الجديدة للإطار المرئي، بوحدات بكسل الشاشة الظاهرية.
• y: Integer — الحافة العلوية الجديدة للإطار المرئي، بوحدات بكسل الشاشة الظاهرية.
• width: Integer — العرض المرئي الجديد، بالبكسل.
• height: Integer — الارتفاع المرئي الجديد، بالبكسل.

القيمة المُرجَعة

true إذا تم تطبيق التغيير؛ false إذا كانت النافذة فارغة أو مغلقة، أو رفضت التغيير.

WindowSetEnabled

WindowSetEnabled(window: Window, enabled: Bool) → Bool

يمكّن نافذة أو عنصر تحكم أو يعطّلهما. تتجاهل النافذة المعطّلة نقرات الماوس وضغطات المفاتيح حتى يتم تمكينها مرة أخرى.

المعلمات

• window: Window — النافذة أو عنصر التحكم المراد تغييره.
• enabled: Bool — true لتمكين النافذة؛ false لتعطيلها.

القيمة المُرجَعة

true بمجرد تقديم الطلب؛ false إذا كانت النافذة فارغة أو مغلقة.

WindowSetPropertyInteger

WindowSetPropertyInteger(window: Window, name: Text, value: Integer) → Bool

يخزّن عددًا صحيحًا مسمى على نافذة، مثلًا لتذكّر شيء ما عن تلك النافذة بين الإجراءات. يزيل المحرك الخصائص التي خزّنها عند خروجه.

المعلمات

• window: Window — النافذة المراد تخزين القيمة عليها.
• name: Text — اسم الخاصية. اختر اسمًا مميزًا حتى لا يتعارض مع الخصائص التي يستخدمها البرنامج نفسه.
• value: Integer — العدد الصحيح المراد تخزينه.

القيمة المُرجَعة

true إذا تم تخزين القيمة؛ false إذا كانت النافذة فارغة أو مغلقة.

٢ مثالان: تثبيت نافذة في المقدمة, تذكّر موضع النافذة واستعادته

WindowSetPropertyText

WindowSetPropertyText(window: Window, name: Text, value: Text) → Bool

يخزّن قيمة نصية مسماة على نافذة، تُقرأ مرة أخرى باستخدام WindowGetPropertyText. يحتفظ المحرك بالنص كما أُعطي تمامًا، بما في ذلك حالة الأحرف، ويمكن أن يكون فارغًا. يزيل المحرك الخصائص التي خزّنها عند خروجه.

المعلمات

• window: Window — النافذة المراد تخزين النص عليها.
• name: Text — اسم الخاصية. اختر اسمًا مميزًا حتى لا يتعارض مع الخصائص التي يستخدمها البرنامج نفسه.
• value: Text — النص المراد تخزينه، بحد أقصى 1024 حرفًا.

القيمة المُرجَعة

true إذا تم تخزين النص؛ false إذا كانت النافذة فارغة أو مغلقة، أو كانت 512 قيمة نصية مخزَّنة بالفعل، أو تعذّر تعيين الخاصية. النص الذي يزيد على 1024 حرفًا يوقف الإجراء بخطأ.

WindowSetTitle

WindowSetTitle(window: Window, title: Text) → Bool

يغيّر النص الموجود في شريط عنوان نافذة. قد يعيده البرنامج إلى ما كان عليه في أي وقت. البرنامج الذي لا يستجيب خلال ثانية واحدة يُترك دون تغيير.

المعلمات

• window: Window — النافذة المراد إعادة تسميتها.
• title: Text — نص العنوان الجديد.

القيمة المُرجَعة

true إذا تم تعيين العنوان؛ false إذا كانت النافذة فارغة أو مغلقة، أو لم تستجب خلال ثانية واحدة، أو رفض البرنامج ذلك.

١ مثال: إيماءة واحدة، عدة خيارات

WindowSetTopmost

WindowSetTopmost(window: Window, topmost: Bool) → Bool · بسيط

يُبقي نافذة فوق كل النوافذ العادية، أو يعيدها إلى الترتيب العادي، دون تنشيطها.

المعلمات

• window: Window — النافذة المراد تغييرها.
• topmost: Bool — true لإبقاء النافذة دائمًا في المقدمة؛ false لإعادتها إلى الترتيب العادي.

القيمة المُرجَعة

true إذا تم تطبيق التغيير؛ false إذا كانت النافذة فارغة أو مغلقة، أو كانت تنتمي إلى برنامج يعمل بصلاحيات أعلى.

١ مثال: تثبيت نافذة في المقدمة

WindowShow

WindowShow(window: Window) → Bool

يعرض نافذة مخفية مرة أخرى، مثل نافذة أُخفيت باستخدام WindowHide، بحجمها وموضعها الحاليين. يتوقف المحرك عن تتبعها كنافذة مخفية.

المعلمات

• window: Window — النافذة المراد عرضها.

القيمة المُرجَعة

true إذا تم تقديم طلب العرض؛ false إذا كانت النافذة فارغة أو مغلقة.

WindowToggleTopmost

WindowToggleTopmost(window: Window) → Bool · بسيط

يبدّل نافذة بين الظهور دائمًا في المقدمة والترتيب العادي، دون تنشيطها.

المعلمات

• window: Window — النافذة المراد تغييرها.

القيمة المُرجَعة

true إذا تم تطبيق التغيير؛ false إذا كانت النافذة فارغة أو مغلقة، أو رفضت التغيير. لا يبيّن الحالة التي أصبحت عليها النافذة الآن.

WindowWaitClose

WindowWaitClose(window: Window, timeoutMs: Integer) → Bool

ينتظر حتى تُغلق نافذة، مع الفحص كل 50 مللي ثانية. يحظر البرنامج النصي لمدة تصل إلى timeoutMs؛ ويؤدي إيقاف كل الإجراءات إلى إنهاء الانتظار مبكرًا.

المعلمات

• window: Window — النافذة المراد انتظارها.
• timeoutMs: Integer — أطول مدة للانتظار، بالمللي ثانية، من 0 إلى 60000. تُحتسب القيم الأكبر على أنها 60000؛ والقيمة 0 تفحص مرة واحدة دون انتظار.

القيمة المُرجَعة

true بمجرد إغلاق النافذة، وفورًا إذا كانت مغلقة بالفعل أو فارغة؛ false إذا ظلت مفتوحة عند انقضاء الوقت أو تم إيقاف الانتظار.

١ مثال: تشغيل برنامج وانتظار نافذته والعمل عليها

WindowWaitFor

WindowWaitFor(pattern: Text, timeoutMs: Integer) → Window

ينتظر حتى تظهر نافذة مرئية ذات مستوى أعلى يطابق عنوانها تعبيرًا عاديًا، مع الفحص كل 50 مللي ثانية. يحظر البرنامج النصي لمدة تصل إلى timeoutMs؛ مفيد مباشرةً بعد بدء تشغيل برنامج.

المعلمات

• pattern: Text — تعبير عادي تتم مطابقته مع عناوين النوافذ، مع تجاهل حالة الأحرف، مثل 'Notepad$'. يتطابق في أي موضع من العنوان ما لم يُثبَّت بـ ^ أو $.
• timeoutMs: Integer — أطول مدة للانتظار، بالمللي ثانية، من 0 إلى 60000. تُحتسب القيم الأكبر على أنها 60000؛ والقيمة 0 تفحص مرة واحدة دون انتظار.

القيمة المُرجَعة

النافذة المطابقة الأقرب إلى المقدمة، أو نافذة فارغة إذا لم تظهر أي نافذة في الوقت المحدد أو تم إيقاف الانتظار. النمط غير الصالح يوقف الإجراء بخطأ.

١ مثال: تشغيل برنامج وانتظار نافذته والعمل عليها