مدخل إلى كتابة ماكرو Macro في ليبرأوفيس كالك LibreOffice Calc

يوفّر ليبرأوفيس LibreOffice طريقة لكتابة الماكرو Macro الذي تحتاجه لأتمتة المهام المتكررة في تطبيقك المكتبي، إذ يمكنك استخدام لغتي بايثون Python أو بيسك Basic لتطوير هذا الماكرو. سنتعلّم في هذا المقال كيفية كتابة ماكرو في ليبرأوفيس باستخدام ماكرو "Hello World" بلغة بيسك، حيث سننشئ ماكرو يضع السلسلة النصية "Hello World" في الخلية الأولى من برنامج ليبرأوفيس كالك Calc، أي خلية الصف 1 والعمود A وأيضًا سنتطرق إلى موضوع تنظيم الماكرو وكيفية تصديره واستيراده كمكتبة مستقلة.

هذا المقال جزء من سلسلة مقالات حول إنشاء ماكرو في ليبرأوفيس كالك، فهرس السلسلة:

إنشاء الماكرو

افتح برنامج ليبرأوفيس كالك من قائمة ابدأ ثم كافة البرامج ثم اختر ليبرأوفيس LibreOffice ثم ليبرأوفيس كالك LibreOffice Calc في نظام ويندوز أو من تطبيقات Applications ثم اختر Office ثم ليبرأوفيس كالك LibreOffice Calc في نظام لينكس.

انتقل إلى قائمة أدوات Tools ثم ماكرو Macros ثم نظّم وحدات الماكرو Organize Macros ثم LibreOffice Basic، حيث ستفتح نافذة "ماكروهات أساسية LibreOffice basic macros".

أدخِل الاسم الذي تريده في خانة اسم الماكرو وانقر على جديد. استخدمنا الاسم hello_world، ولكن يمكنك استخدام الاسم الذي تريده.

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

لنكتب الآن شيفرة الماكرو الأول من خلال التصريح عن متغيرين من النوع كائن object كما يلي:

dim document as object
dim dispatcher as object

ثم نسند قيمتين للمتغيرين السابقين كما يلي:

document = ThisComponent.CurrentController.Frame
dispatcher = createUnoService("com.sun.star.frame.DispatchHelper")

يشير ThisComponent إلى المستند الحالي. يكون كل شيء في ليبرأوفيس -مثل الكتابة والتلوين والإدراج- مراقبًا باستخدام متحكم controller، حيث يرسل هذا المتحكم التغييرات إلى إطار المستند، أي منطقة نافذة كالك الرئيسية. لذلك يشير المتغير document إلى منطقة كالك الرئيسية.

يُنشِئ التابع createUnoService نسخةً من خدمة DispatchHelper التي تساعد في إرسال المهام من الماكرو إلى الإطار، حيث يمكن تنفيذ جميع مهام ماكرو في ليبرأوفيس تقريبًا باستخدام المرسل dispatcher.

سنصرّح الآن عن مجموعة من الخاصيات التي تتكوّن من الزوج اسم/قيمة name/value، وبالتالي يحتوي الاسم name على اسم الخاصية وتحتوي القيمة value على قيمة تلك الخاصية.

dim args1(0) as new com.sun.star.beans.PropertyValue
dim args2(0) as new com.sun.star.beans.PropertyValue

هدفنا هو وضع النص "Hello World" في الخلية الأولى، حيث يمكن الإشارة إلى الخلية الأولى A1 ثم وضع نص فيها من خلال استخدام الخاصيتين ToPoint و StringName.

args1(0).Name = "ToPoint"
args1(0).Value = "$A$1"

args2(0).Name = "StringName"
args2(0).Value = "Hello World!"

يجب بعد ضبط الخاصيات استدعاء المرسل لإرسالها إلى المستند، لذلك استدعِ الحدث executeDispatch الخاص بالمرسل باستخدام أمرين هما: ‎.uno:GoToCell و ‎.uno:EnterString، حيث يخبر هذان الأمران الإطارَ بما يجب تنفيذه، ويمرّران مصفوفة الخاصيات بأكملها مع القيم. ضع الآن مربع رسالة message box لإعلامك باكتمال التنفيذ كما يلي:

تشغيل الماكرو

يمكن تشغيل الماكرو بالضغط على مفتاح F5 أو بالنقر على زر تشغيل الماكرو Run Macro من شريط الأدوات، ثم يظهر مربع الرسالة بعد التنفيذ. إذا تحققت من جدول بيانات كالك، فيجب أن ترى النص "Hello World!‎" مكتوبًا في الخلية الأولى.

إليك الشيفرة الكاملة:

REM  *****  BASIC  *****
sub hello_world

    dim document   as object
    dim dispatcher as object

    document   = ThisComponent.CurrentController.Frame
    dispatcher = createUnoService("com.sun.star.frame.DispatchHelper")

    dim args1(0) as new com.sun.star.beans.PropertyValue
    dim args2(0) as new com.sun.star.beans.PropertyValue

    args1(0).Name = "ToPoint"
    args1(0).Value = "$A$1"
    dispatcher.executeDispatch(document, ".uno:GoToCell", "", 0, args1())

    args2(0).Name = "StringName"
    args2(0).Value = "Hello World!"
    dispatcher.executeDispatch(document, ".uno:EnterString", "", 0, args2())

   msgbox "Completed!"
end sub

تنقيح أخطاء الماكرو باستخدام نقطة التوقف والمراقبة

سنتعلّم الآن تقنية تنقيح أخطاء debugging ماكرو بيسك في ليبرأوفيس باستخدام نقطة التوقف breakpoint والمراقبة watch، حيث بُنيَت هذه التقنية على نظام أبونتو Ubuntu 14.04LTS وبرنامج ليبرأوفيس الذي يستخدم لغة بيسك، وتُطبَّق على جميع لغات البرمجة تقريبًا مع ليبرأوفيس.

تعريف المتغيرات

لنعرّف 3 متغيرات سنستخدمها في مثالنا كما يلي:

dim i, j, cnt

عرّف حلقة for التي ستنفّذ من القيمة 1 إلى 10، ثم زِد متغيرين داخل هذه الحلقة على النحو التالي:

for cnt = 1 to 10
    i = i + 1
    j = i + 1   
next cnt

إضافة نقطة توقف Breakpoint

نريد وضع نقطتي توقف للعبارتين for cnt = 1 to 10 و j = i + 1، حيث تُشغَّل نقطة التوقف عند وضعها ضمن برنامجك في وضع تنقيح الأخطاء ويتوقف التنفيذ عند هذه النقطة.

يمكنك وضع نقطة توقف من خلال وضع المؤشر عند العبارة، ثم الضغط على مفتاح F9 أو الضغط على الزر التالي من شريط الأدوات:

سترى بعد ذلك دائرة حمراء بجانب العبارة مما يعني إضافة نقطة توقف كما يلي:

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

إضافة مراقبة Watch

سنضيف الآن مراقبة watch إلى المتغير cnt. تساعد هذه المراقبة عندما ينفّذ البرنامج في وضع تنقيح الأخطاء في مراقبة قيمة المتغير خلال خطوات البرنامج، حيث يمكنك إضافة مراقبة إلى المتغير cnt من خلال تحديد المتغير والضغط على مفتاح F7 أو النقر على أيقونة النظارات في شريط الأدوات.

ستلاحظ بعد ذلك إضافة المتغير إلى قائمة المراقبة أسفل المحرر.

تنفيذ خطوة تلو الأخرى

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

اضغط على مفتاح F5 مرة أخرى لمتابعة تنفيذ البرنامج، ولكنه سيتوقف مرةً أخرى في نقطة التوقف التالية.
اضغط على مفتاح F8 (تنفيذ خطوة) والذي سينفذ خطوةً تلو الخطوة، ويمكنك أن ترى تغيُّر قيمة المتغير cnt المُراقَبة.

لنضغط على مفتاح F8، حيث يمكنك أن ترى السهم البرتقالي ينتقل إلى العبارة التالية وينتظر. إذا ألقيت نظرة على نافذة المراقبة، فيمكنك رؤية قيمة المتغير cnt هي 1.

ويمكنك بهذه الطريقة تنقيح الأخطاء وإضافة نقطة توقف وإضافة مراقبة لأيّ ماكرو في ليبرأوفيس أو أوبن أوفيس OpenOffice باستخدام محرّره الخاص.

تنظيم الماكرو في ليبرأوفيس

إذا كنت معتادًا على استخدام البرمجة بلغة فيجوال بيسك Visual Basic for Applications -اختصارًا VBA- في مايكروسوفت إكسل Excel، فلا بدّ أنك تعرف أن شيفرات فيجوال بيسك VB الخاصة بالماكرو موجودة في مشروع VB، وإذا أردت تضمين الماكرو ضمن ملف إكسل Excel مثلًا، فيجب أن تحفظه بالتنسيق ‎.xlsm الذي يوضّح احتواء الملف على ماكرو.

البنى الافتراضية لملف الماكرو في ليبرأوفيس

ينشئ ليبرأوفيس افتراضيًا الماكرو ضمن المسار ماكروهاتي My Macros ثم Standard ثم Module1 عند إنشائه لأول مرة، إذ توجد جميع دوال الماكرو الخاصة بك ضمن الوحدة Module1، حيث أنشأنا في مثالنا الدالة my_macro ضمن الوحدة Module1.

يحتفظ ليبرأوفيس بجميع شيفرات الماكرو التي أُنشئت ضمن الوحدة Module1 الافتراضية في المسار الآتي:

 ‎/home/[user name]/.config/libreoffice/4/user/basic/Standard

يجب أن يوجد ضمن المسار ملف يسمى Module1.xba يحتوي على دوال الماكرو الافتراضية، حيث يجب أن تكون دالة الاختبار my_macro ومحتوياتها داخل هذا الملف.

كيفية إنشاء الماكرو بوصفه جزءا من ملف مكتبي

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

إذا أردت توزيع أو إرسال ملف ليبرأوفيس مثل كالك Calc أو إمبرس Impress أو غيرها مع دوال الماكرو، فيجب عليك إنشاء وحدات الماكرو بطريقة مختلفة، إذ يجب إنشاء الماكرو داخل الملف أثناء إنشاء وحدات الماكرو ومربع الحوار الذي تريد توزيعه بوصفه جزءًا من ملف ليبرأوفيس. افتح مربع الحوار من قائمة أدوات Tools ثم ماكرو Macros ثم تنظيم الماكرو Organize Macros ثم بيسك LibreOffice Basic. حدّد اسم الملف من قائمة "الماكرو من Macro From" داخل مربع الحوار، ثم اضغط "جديد New"، حيث سيطلب ليبرأوفيس كتابة اسم الوحدة Module.

يستخدم ليبرأوفيس الوحدة "Module1" افتراضيًا، لذلك اكتب أي اسم تريده واضغط على "موافق" (استخدمنا اسم الوحدةdebugpoint_demo_module).

سيفتح بعد ذلك محرّر الماكرو الذي يحتوي الوحدة الجديدة والماكرو ضمن ملف عملك. يمكنك الآن كتابة العديد من وحدات الماكرو التي تريدها ضمن الوحدة الحالية وحفظ ملف ليبرأوفيس الحالي، ثم ستُحفَظ جميع وحدات الماكرو ومحتوياتها مع الملف ويمكنك بسهولة مشاركة الملف أو توزيعه على المستخدمين.

تُخزَّن وحدات الماكرو Macros ضمن الوحدات Modules في ليبرأوفيس، والوحدات هي جزء من المكتبات Libraries والمكتبات هي جزء من الحاويات Containers كما هو موضح أدناه:

تحميل الوحدة التي يعرفها المستخدم

يفترض ليبرأوفيس أن جميع مربعات الحوار والمتغيرات موجودة في الوحدة "Module1" وفقًا للتنظيم الافتراضي، لكننا أنشأنا وحدة جديدة بالاسم "debugpointdemomodule" التي تبقى مع الملف، حيث يجب تحميل الوحدة قبل البدء في كتابة شيفرات الماكرو. يمكنك تحميل الوحدات التي يعرّفها المستخدم باستخدام التابع التالي:

ThisComponent.BasicLibraries.LoadLibrary("debugpoint_demo_module")

إذا أنشأتَ مربع حوار -"my_dialog" مثلًا- أسفل ملف العمل نفسه، فيمكنك إنشاء كائن الحوار Dialog باستخدام ما يلي:

Dim oDialog1 As Object
oDialog1 = CreateUnoDialog(DialogLibraries.Standard.my_dialog)

تفعيل الماكرو في ملفات ليبرأوفيس

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

انتقل إلى قائمة أدوات Tools ثم خيارات Options ثم ليبرأوفيس LibreOffice ثم الأمن Security ثم أمان الماكرو Macro Security، حيث يُضبَط أمان الماكرو على الخيار "عالٍ high"، ولكن يمكنك تغييره إلى الخيار "منخفض low" إذا كنت واثقًا من مصدر الماكرو، ثم يمكنك إعادة محاولة تنفيذ الماكرو.