# الخطاطيف

# onNoteStored (خطاف حفظ الملاحظة)

# نداء الدالة ومُعامِلاتها

/**
 * تُنادى هذه الدالة عندما تخزن ملاحظة على قرص التخزين
 * لا يمكنك تعديل الملاحظات المخزنة؛ سيسبب هذا فوضى
 * لأنك على الأرجح ستكون مُعدِّلا لها يدويا في الوقت نفسه
 *
 * @param {NoteApi} note
 *       كائن الملاحظة الخاص بالملاحظة المخزنة
 */
function onNoteStored(note);

1
2
3
4
5
6
7
8
9

ربما تحب أن تلقي نظرة على المثال on-note-opened.qml (opens new window).

# noteOpenedHook (خطاف فتح ملاحظة)

# نداء الدالة ومُعامِلاتها

/**
 * تُنادى هذه الدالة عند فتح ملاحظة
 *
 * @param {NoteApi} note
 *       كائن الملاحظة الخاص بالملاحظة المفتوحة
 */
function noteOpenedHook(note);

1
2
3
4
5
6
7

ربما تحب أن تلقي نظرة على المثال on-note-opened.qml (opens new window).

# noteDoubleClickedHook (خطاف النقر المزدوج على ملاحظة)

# نداء الدالة ومُعامِلاتها

/**
 * تُنادى هذه الدالة عند النقر المزدوج على ملاحظة
 *
 * @param {NoteApi} note
 *       كائن الملاحظة الخاص بالملاحظة التي نقر المستخدم عليها
 */
function noteDoubleClickedHook(note);

1
2
3
4
5
6
7

ربما تحب أن تلقي نظرة على المثال external-note-open.qml (opens new window).

# insertMediaHook (خطاف إضافة وسائط)

تُنادى هذه الدالة عندما يُضاف ملف وسائط إلى الملاحظة الحالية.

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

# نداء الدالة ومُعامِلاتها

/**
 * @param fileName
 *       سلسلة نصية: المسار الأصلي لملف الوسائط قبل نسخه إلى مجلد الوسائط
 * @param markdownText
 *       سلسلة نصية: نص ماركداون لملف الوسائط؛ مثال
 *       ![my-image](media/my-image-4101461585.jpg)
 * @return
 *        سلسلة نصية: نص ماركداون الجديد لملف الوسائط
 */
function insertMediaHook(fileName, markdownText);

1
2
3
4
5
6
7
8
9
10

ربما تحب أن تلقي نظرة على المثال example.qml (opens new window).

# insertAttachmentHook (خطاف إضافة مرفق)

تُنادى هذه الدالة عندما يُضاف ملف مرفق إلى الملاحظة الحالية.

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

# نداء الدالة ومُعامِلاتها

/**
 * @param fileName
 *       سلسلة نصية: المسار الأصلي للملف المرفق قبل نسخه إلى مجلد المرفقات
 * @param markdownText
 *       سلسلة نصية: نص ماركداون للملف المرفق؛ مثال
 *       [my-file.txt](attachments/my-file-4245650967.txt)
 * @return
 *        سلسلة نصية: نص ماركداون الجديد للملف المرفق
 */
function insertAttachmentHook(fileName, markdownText);

1
2
3
4
5
6
7
8
9
10

ربما تحب أن تلقي نظرة على المثال example.qml (opens new window).

# insertingFromMimeDataHook (خطاف إلصاق هتمل أو وسائط)

# نداء الدالة ومُعامِلاتها

/**
 * تُنادى هذه الدالة عندما يتم لصق هتمل أو ملف وسائط بضغط
 * `Ctrl + Shift + V`
 *
 * @param text
 *       نص كائن بيانات المايم (QMimeData)
 * @param html
 *       هتمل كائن بيانات المايم (QMimeData)
 * @return
 *        السلسلة النصية التي يجب إضافتها بدلا من نص كائن بيانات المايم
 */
function insertingFromMimeDataHook(text, html);

1
2
3
4
5
6
7
8
9
10
11
12

ربما تحب أن تلقي نظرة على الأمثلة example.qml (opens new window) أو insert-headline-with-link-from-github-url.qml (opens new window) أو note-text-from-5pm-mail.qml (opens new window).

# handleNoteTextFileNameHook (خطاف التعامل مع اسم ملف الملاحظة)

# نداء الدالة ومُعامِلاتها

/**
 * تُنادى هذه الدالة عندما تخزن ملاحظة على قرص التخزين إذا كان
 * الخيار «اسمح لاسم ملف الملاحظة أن يكون مختلفا عن العنوان» مفعلا
 * في الإعدادات
 *
 * تتيح لك هذه الدالة تعديل اسم ملف الملاحظة
 * تذكر أن عليك الاهتمام بتفادي تكرار أسماء الملفات بنفسك!‏
 *
 * أعد سلسلة نصية فارغة إذا كان اسم ملف الملاحظة لا يجب أن يتغيّر
 *
 * @param {NoteApi} note
 *       كائن الملاحظة الخاص بالملاحظة المخزنة
 * @return {string}
 *        سلسلة نصية: اسم ملف الملاحظة
 */
function handleNoteTextFileNameHook(note);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

ربما تحب أن تلقي نظرة على المثالين example.qml (opens new window) أو use-tag-names-in-filename.qml (opens new window).

# handleNoteNameHook (خطاف التعامل مع اسم الملاحظة)

# نداء الدالة ومُعامِلاتها

/**
 * تُنادى هذه الدالة عندما يتحدد اسم الملاحظة
 *
 * وتسمح لك بتعديل اسمها المعروض
 *
 * أعد سلسلة نصية فارغة إذا كان اسم الملاحظة لا يحتاج تغيير
 *
 * @param {NoteApi} note
 *       كائن الملاحظة الخاص بالملاحظة المخزنة
 * @return {string}
 *        سلسلة نصية: اسم الملاحظة
 */
function handleNoteNameHook(note);

1
2
3
4
5
6
7
8
9
10
11
12
13

ربما تحب أن تلقي نظرة على المثال example.qml (opens new window).

ليس مستحسنا استخدام هذا الخطاف إذا فعّل المستخدم خيار السماح لاسم الملف أن يختلف عن اسم الملاحظة.

# handleNewNoteHeadlineHook (خطاف التعامل مع عنوان الملاحظة الجديدة)

# نداء الدالة ومُعامِلاتها

/**
 * تُنادى هذه الدالة قبل إنشاء ملاحظة
 *
 * تتيح لك هذه الدالة تعديل عنوان الملاحظة الرئيسي قبل إنشائها
 * لاحظ أن عليك الاهتمام بإنشاء اسم ملاحظة فريد بنفسك
 * وإلا فلن يتم إنشاء ملاحظة جديدة، بل مجرد إيجادها في قائمة الملاحظات
 *
 * يمكنك استخدام هذه الدالة لإنشاء قوالب للملاحظات
 *
 * @param headline
 *       النص الذي سيستخدم لإنشاء العنوان الرئيسي
 * @return {string}
 *        سلسلة نصية: عنوان الملاحظة الرئيسي
 */
function handleNewNoteHeadlineHook(headline);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

ربما تحب أن تلقي نظرة على المثال custom-new-note-headline.qml (opens new window).

# preNoteToMarkdownHtmlHook (خطاف ما قبل تحويل الملاحظة من ماركداون إلى HTML)

# نداء الدالة ومُعامِلاتها

/**
 * This function is called before the markdown html of a note is generated
 *
 * It allows you to modify what is passed to the markdown to html converter
 *
 * The function can for example be used in multiple scripts to render code (like LaTeX math or mermaid)
 * to its graphical representation for the preview
 *
 * The note will not be changed in this process
 *
 * @param {NoteApi} note - the note object
 * @param {string} markdown - the markdown that is about to being converted to html
 * @param {bool} forExport - true if the html is used for an export, false for the preview
 * @return {string} the modified markdown or an empty string if nothing should be modified
 */
function preNoteToMarkdownHtmlHook(note, markdown, forExport);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

ربما تحب أن تلقي نظرة على المثال preview-styling.qml (opens new window).

# noteToMarkdownHtmlHook (خطاف تحويل الملاحظة من ماركداون إلى HTML)

# نداء الدالة ومُعامِلاتها

/**
 * This function is called when the markdown html of a note is generated
 *
 * It allows you to modify this html
 * This is for example called before by the note preview
 *
 * The function can be used in multiple scripts to modify the html of the preview
 *
 * @param {NoteApi} note - the note object
 * @param {string} html - the html that is about to being rendered
 * @param {bool} forExport - true if the html is used for an export, false for the preview
 * @return {string} the modified html or an empty string if nothing should be modified
 */
function noteToMarkdownHtmlHook(note, html, forExport);

1
2
3
4
5
6
7
8
9
10
11
12
13
14

ربما تحب أن تلقي نظرة على المثالين example.qml (opens new window) أو preview-styling.qml (opens new window).

برجاء الاطلاع على توثيق الجزء المدعوم من HTML (opens new window) لقائمة بجميع خصائص CSS المدعومة.

# encryptionHook (خطاف التعمية)

# نداء الدالة ومُعامِلاتها

/**
 * تُنادى هذه الدالة عند الاحتياج إلى تعمية نص أو فك تعميته
 *
 * @param text
 *       سلسلة نصية: النص الذي سيُعمّى أو ستُفك تعميته
 * @param password
 *       سلسلة نصية: كلمة المرور
 * @param decrypt bool if false encryption is demanded, if true decryption is demanded
 *       قيمة منطقية: «صادق» إذا كان المطلوب فك التعمية، و«كاذب» إذا كان المطلوب التعمية
 * @return
 *       سلسلة نصية: النص المعّمى أو المفكوكة تعميته
 */
function encryptionHook(text, password, decrypt);

1
2
3
4
5
6
7
8
9
10
11
12
13

ربما تحب أن تلقي نظرة على الأمثلة encryption-keybase.qml (opens new window) أو encryption-pgp.qml (opens new window) أو encryption-rot13.qml (opens new window).

# noteTaggingHook (خطاف وسم الملاحظات)

يمكنك تنفيذ آلية وسم خاصة بك، مثلا باستخدام نص بصيغة خاصة في ملاحظاتك، مثل @tag1 و @tag2 و @tag3.

# نداء الدالة ومُعامِلاتها

/**
 * Handles note tagging for a note
 *
 * This function is called when tags are added to, removed from or renamed in
 * a note or the tags of a note should be listed
 *
 * @param note
 * @param action can be "add", "remove", "rename" or "list"
 * @param tagName tag name to be added, removed or renamed
 * @param newTagName tag name to be renamed to if action = "rename"
 * @return note text string or string-list of tag names (if action = "list")
 */
function noteTaggingHook(note, action, tagName, newTagName);

1
2
3
4
5
6
7
8
9
10
11
12
13

as soon as a script is activated that implements the new function noteTaggingHook note tagging will be handled by that function
ستعمل الخصائص التالية من خلال واجهة مستخدم QOwnNotes
- initially importing tags like @tag from your notes and overwriting your current tag assignment
  - you will not lose your tags tree, just the former assignment to notes
  - ستظل قادرًا على نقل الوسوم إلى وسوم أخرى
  - if more than one tag has the same name in your tag tree the first hit will be assigned
- إضافة وسم إلى ملاحظة سيضيف الوسم إلى نص الملاحظة
- إزالة وسم من ملاحظة سيزيل الوسم من نص الملاحظة
- إزالة وسوم من قائمة الوسوم سيزيل هذه الوسوم من ملاحظاتك
- إعادة تسمية وسوم في قائمة الوسوم سيعيد تسمية هذه الوسوم في ملاحظاتك
- وسم كمية من الملاحظات في قائمة الملاحظات سيضيف هذه الوسوم إلى ملاحظاتك
- إزالة كمية من الوسوم من الملاحظات في قائمة الملاحظات سيزيل هذه الوسوم من ملاحظاتك
- إذا تم نقل وسوم في لوحة الوسوم، فسينفذ التطبيق سلسلة من إجراءات الإضافة (add) والإزالة (remove) لجميع الوسوم المحددة ووسومها الفرعية في جميع الملاحظات

ربما تحب أن تلقي نظرة على المثال note-tagging.qml (opens new window) لتنفيذ آلية وسم خاصة بك.

WARNING

اجعل إجراء السرد، list، الخاص بك سريعا جدا، لأنه سينفذ لكل ملاحظة كل مرة يُعاد فيها تحميل مجلدها!

# noteTaggingByObjectHook (خطاف وسم الملاحظات الكائني)

مثل خطاف وسم الملاحظات (noteTaggingHook)، يمكنك تنفيذ آلية وسم خاصة بك، لكنك لست مربوطًا بأسماء وسوم في جذر شجرة الوسوم. يمكنك بهذه الطريقة استخدام شجرة الوسوم كلها بدلا من قائمة وسوم فقط.

تحصل باستخدامك خطاف وسم الملاحظات الكائني (noteTaggingByObjectHook) على كائن TagApi كمُعامِل، بدلا من اسم وسم. وعليك توفير قائمة مُعرِّفات الوسوم من أجل نتيجة إجراء السرد (list).

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

# نداء الدالة ومُعامِلاتها

/**
 * Handles note tagging for a note
 *
 * This function is called when tags are added to, removed from or renamed in
 * a note or the tags of a note should be listed
 *
 * @param note
 * @param action can be "add", "remove", "rename" or "list"
 * @param tag to be added, removed or renamed
 * @param newTagName tag name to be renamed to if action = "rename"
 * @return note text string or string-list of tag ids (if action = "list")
 */
function noteTaggingByObjectHook(note, action, tag, newTagName);

1
2
3
4
5
6
7
8
9
10
11
12
13

ربما تحب أن تلقي نظرة على المثال note-tagging-by-object.qml (opens new window) لتنفيذ آلية وسم خاصة بك.

# autocompletionHook (خطاف الإكمال التلقائي)

يمكنك إرجاع قائمة سلاسل نصية لإضافتها إلى قائمة الإكمال التلقائي عندما يُستدعى الإكمال التلقائي (مثلا بضغط Ctrl + Space).

# نداء الدالة ومُعامِلاتها

/**
 * Calls the autocompletionHook function for all script components
 * This function is called when autocompletion is invoked in a note
 *
 * @return QStringList of text for the autocomplete list
 */
function callAutocompletionHook();

1
2
3
4
5
6
7

ربما تحب أن تلقي نظرة على المثال autocompletion.qml (opens new window).

# websocketRawDataHook (خطاف البيانات الخام من مقبس الويب)

يُنادى هذا الخطاف عندما تُرسل بيانات من إضافة متصفح رفيقة ويب QOwnNotes من خلال قائمة سياق المتصفح.

# نداء الدالة ومُعامِلاتها

/**
 * @param requestType can be "page" or "selection"
 * @param pageUrl the url of the webpage where the request was made
 * @param pageTitle the page title of the webpage where the request was made
 * @param rawData the data that was transmitted, html for requestType "page" or plain text for requestType "selection"
 * @param screenshotDataUrl the data url of the screenshot of the webpage where the request was made
 * @return true if data was handled by a hook
 */
function callHandleWebsocketRawDataHook(requestType, pageUrl, pageTitle, rawData, screenshotDataUrl);

1
2
3
4
5
6
7
8
9

ربما تحب أن تلقي نظرة على المثالين websocket-raw-data-new-note.qml (opens new window) و websocket-raw-data-selection-in-note.qml (opens new window).

# onDetachedProcessCallback (عند رد عملية منفصلة)

يُنادى هذا الخطاف عندما ينتهي تنفيذ عملية منفصلة بدأها بُريمج في خيط تنفيذ بالدالة startDetachedProcess.

# نداء الدالة ومُعامِلاتها

/**
 * This function is called when a script thread is done executing.
 * Hint: thread[1]==0 helps to determine if a bulk of started processes for a certain identifier is done.
 *
 * @param {QString} callbackIdentifier - the provided id when calling startDetachedProcess()
 * @param {QString} resultSet - the result of the process
 * @param {QVariantList} cmd - the entire command array [0-executablePath, 1-parameters, 2-exitCode]
 * @param {QVariantList} thread - the thread information array [0-passed callbackParameter, 1-remaining threads for this identifier]
 */
function onDetachedProcessCallback(callbackIdentifier, resultSet, cmd, thread);

1
2
3
4
5
6
7
8
9
10

ربما تحب أن تلقي نظرة على المثال callback-example.qml (opens new window).

# windowStateChangedHook (خطاف تغيّر حالة النافذة)

# نداء الدالة ومُعامِلاتها

/**
 * تُنادى هذه الدالة عند حدث تغيير حالة النافذة
 *
 * @param {QString} windowState
 *       الحالة الجديدة للنافذة؛ القيم المحتملة هي
 *       "minimized", "maximized", "fullscreen", "active", "nostate"
 */
function windowStateChangedHook(windowState);

1
2
3
4
5
6
7
8

ربما تحب أن تلقي نظرة على المثال window-state-changed.qml (opens new window).

# workspaceSwitchedHook (خطاف تبديل مساحة العمل)

يُنادى هذا الخطاف عند تبديل مساحة العمل.

# نداء الدالة ومُعامِلاتها

/**
 * تُنادى هذه الدالة عند تبديل مساحات العمل
 *
 * @param oldUuid
 *       المعرف العالمي الفريد لمساحة العمل القديمة
 * @param newUuid
 *       المعرف العالمي الفريد لمساحة العمل الجديدة
 */
function workspaceSwitchedHook(oldUuid, newUuid);

1
2
3
4
5
6
7
8
9

ربما تحب أن تلقي نظرة على المثال websocket-raw-data-new-note.qml (opens new window).

# openAiBackendsHook (خطاف خدمات الذكاء المصطنع)

يُنادى هذا الخطاف عند إعادة تحميل تهيئة خدمات OpenAI. يحدث هذا مثلا عند إعادة تحميل محرك البرمجة.

يمكنك استعماله لتهيئة خدمات OpenAI مخصصة، مثل نماذج LLM خاصة بك (على أن تكون متوافقة مع OpenAI API).

# نداء الدالة ومُعامِلاتها

/**
 * This function is called when the OpenAI service config is reloaded
 * It returns a list of objects with config parameters for new OpenAI backends
 */
function openAiBackendsHook() {
    return [
        {
            "id": "my-custom-ai",
            "name": "My Custom AI",
            "baseUrl": "http://localhost:5000",
            "apiKey": "kDFJkjk3asdm",
            "models": ["gpt-3.5-turbo", "gpt-4.0-turbo"],
        },
        {
            "id": "my-custom-ai2",
            "name": "My Custom AI 2",
            "baseUrl": "http://localhost:5001",
            "apiKey": "lOikf7eNdb9",
            "models": ["gpt-3.5-turbo2", "gpt-4.0-turbo2"],
        },
    ];
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

TIP

يمكنك الاستفادة من تسجيل متغيرات إعدادات البُريمج لحفظ إعدادات خدمات الذكاء المصطنع ضمن إعدادات البريمج.

ربما تحب أن تلقي نظرة على المثال custom-openai-backends.qml (opens new window).

← الدوال والكائنات التي يوفرها QOwnNotes الفصائل (الكلاسات) المكشوفة →

Crafted by Patrizio Bekerle with ❤️