# هوک ها

# onNoteStored

# فراخوانی شگرد و پارامترها

/**
 * This function is called when a note gets stored to disk
 * You cannot modify stored notes, that would be a mess since
 * you are most likely editing them by hand at the same time
 *
 * @param {NoteApi} note - the note object of the stored note
 */
function onNoteStored(note);

1
2
3
4
5
6
7
8

You may want to take a look at the example on-note-opened.qml (opens new window).

# noteOpenedHook

# فراخوانی شگرد و پارامترها

/**
 * This function is called after a note was opened
 *
 * @param {NoteApi} note - the note object that was opened
 */
function noteOpenedHook(note);

1
2
3
4
5
6

You may want to take a look at the example on-note-opened.qml (opens new window).

# noteDoubleClickedHook

# فراخوانی شگرد و پارامترها

/**
 * This function is called after a note was double clicked
 *
 * @param {NoteApi} note - the note object that was clicked
 */
function noteDoubleClickedHook(note);

1
2
3
4
5
6

You may want to take a look at the example external-note-open.qml (opens new window).

# insertMediaHook

این تابع هنگامی فراخوانی می شود که یک پرونده رسانه در یادداشت کنونی درج شده باشد.

اگر این تابع در چندین اسکریپ تعریف شود، در این صورت اسکریپت نخست که یک رشته غیر خالی را بر می گرداند، برنده می شود.

# فراخوانی شگرد و پارامترها

/**
 * @param fileName string the file path of the source media file before it was copied to the media folder
 * @param markdownText string the markdown text of the media file, e.g. ![my-image](media/my-image-4101461585.jpg)
 * @return string the new markdown text of the media file
 */
function insertMediaHook(fileName, markdownText);

1
2
3
4
5
6

You may want to take a look at the example example.qml (opens new window).

# insertAttachmentHook

این تابع هنگامی فراخوانی می شود که یک پرونده پیوست در یادداشت کنونی درج شده باشد.

# فراخوانی شگرد و پارامترها

/**
 * @param fileName string the file path of the source attachment file before it was copied to the attachment folder
 * @param markdownText string the markdown text of the attachment file, e.g. [my-file.txt](attachments/my-file-4245650967.txt)
 * @return string the new markdown text of the attachment file
 */
function insertAttachmentHook(fileName, markdownText);

1
2
3
4
5
6

You may want to take a look at the example example.qml (opens new window).

# insertingFromMimeDataHook

# فراخوانی شگرد و پارامترها

/**
 * This function is called when html or a media file is pasted to a note with `Ctrl + Shift + V`
 *
 * @param text text of the QMimeData object
 * @param html html of the QMimeData object
 * @returns the string that should be inserted instead of the text from the QMimeData object
 */
function insertingFromMimeDataHook(text, html);

1
2
3
4
5
6
7
8

You may want to take a look at the example example.qml (opens new window), insert-headline-with-link-from-github-url.qml (opens new window) or note-text-from-5pm-mail.qml (opens new window).

# handleNoteTextFileNameHook

# فراخوانی شگرد و پارامترها

/**
 * This function is called when a note gets stored to disk if
 * "Allow note file name to be different from headline" is enabled
 * in the settings
 *
 * It allows you to modify the name of the note file
 * Keep in mind that you have to care about duplicate names yourself!
 *
 * Return an empty string if the file name of the note should
 * not be modified
 *
 * @param {NoteApi} note - the note object of the stored note
 * @return {string} the file name of the note
 */
function handleNoteTextFileNameHook(note);

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

You may want to take a look at the example example.qml (opens new window) or use-tag-names-in-filename.qml (opens new window).

# handleNoteNameHook

# فراخوانی شگرد و پارامترها

/**
 * This function is called when the note name is determined for a note
 *
 * It allows you to modify the name of the note that is viewed
 *
 * Return an empty string if the name of the note should not be modified
 *
 * @param {NoteApi} note - the note object of the stored note
 * @return {string} the name of the note
 */
function handleNoteNameHook(note);

1
2
3
4
5
6
7
8
9
10
11

You may want to take a look at the example example.qml (opens new window).

در صورتی که تنظیماتی که از نام پرونده به عنوان نام یادداشت استفاده می کند فعال باشد، استفاده از این هوک ایده خوبی به نظر نمی رسد.

# handleNewNoteHeadlineHook

# فراخوانی شگرد و پارامترها

/**
 * This function is called before a note is created
 *
 * It allows you to modify the headline of the note before it is created
 * Note that you have to take care about a unique note name, otherwise
 * the new note will not be created, it will just be found in the note list
 *
 * You can use this function for creating note templates
 *
 * @param headline text that would be used to create the headline
 * @return {string} the headline of the note
 */
function handleNewNoteHeadlineHook(headline);

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

You may want to take a look at the example custom-new-note-headline.qml (opens new window).

# preNoteToMarkdownHtmlHook

# فراخوانی شگرد و پارامترها

/**
 * 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

You may want to take a look at the example preview-styling.qml (opens new window).

# noteToMarkdownHtmlHook

# فراخوانی شگرد و پارامترها

/**
 * 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

You may want to take a look at the example example.qml (opens new window) or preview-styling.qml (opens new window).

لطفاً برای لیستی از همه سبک های پشتیبانی شده css به مستندات زیرمجموعه پشیبانی شده HTML (opens new window) مراجعه کنید.

# encryptionHook

# فراخوانی شگرد و پارامترها

/**
 * This function is called when text has to be encrypted or decrypted
 *
 * @param text string the text to encrypt or decrypt
 * @param password string the password
 * @param decrypt bool if false encryption is demanded, if true decryption is demanded
 * @return the encrypted decrypted text
 */
function encryptionHook(text, password, decrypt);

1
2
3
4
5
6
7
8
9

You may want to take a look at the example encryption-keybase.qml (opens new window), encryption-pgp.qml (opens new window) or 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

به محض اینکه اسکریپتی فعال می شود که تابع جدید noteTaggingHook را پیاده سازی می کند، برچسب گذاری یادداشت با آن تابع انجام می شود.
قابلیت های پیش رو بایستی از طریق رابط کاربری QOwnNotes فعالیت کند
- ورود اولیه برچسب هایی نظیر @tag از یادداشت شما و بازنویسی برچسب زنی کنونی شما
  - شما ساختار درختی برچسب هایتان را از دست نخواهید داد (تنها تخصیص قبلی به یادداشت ها)
  - همچنان می توانید برچسب ها را به سایر برچسب ها جابجا کنید
  - اگر بیش از یک برچسب در ساختار درختی برچسب شما نام یکسانی داشته باشد، مورد نخست در نظر گرفته خواهد شد
- افزودن یک برچسب به یک یادداشت، برچسب را به متن یادداشت اضافه خواهد کرد
- حذف یک برچسب از یک یادداشت، برچسب را از متن یادداشت حذف خواهد کرد
- حذف برچسب ها در لیست برچسب، آن برچسب ها را از یادداشت های شما حذف خواهد کرد
- تغییر نام برچسب ها در لیست برچسب، آن برچسب ها را در یادداشت های شما تغییر نام خواهد داد
- برچسب گذاری انبوه یادداشت ها در لیست یادداشت آن برچسب ها را به یادداشت های شما اضافه خواهد کرد
- حذف انبوه برچسب ها از یادداشت ها در لیست یادداشت، آن برچسب ها را از یادداشت های شما حذف خواهد کرد
- در صورتی که برچسب ها در پنل برچسب جابجا ‌شوند، برنامه یکسری اقدامات افزایش و حذف برای همه برچسب های منتخب و فرزندان آن ها در تمام یادداشت ها انجام خواهد داد.

You may want to take a look at the example note-tagging.qml (opens new window) to implement your own tagging mechanism.

WARNING

مطمئن شوید که فعالیت لیست شما به واقع سریع است زیرا برای هر یادداشت و در هر زمانی که پوشه یادداشت مجدداً بارگذاری می شود، اجرا خواهد شد!

# noteTaggingByObjectHook

به همین ترتیب برای noteTaggingHook، شما می توانید مکانیسم برچسب گذاری یادداشت خود را پیاده سازی کنید اما به اسامی برچسب در ریشه ساختار درختی برچسب متصل نیستید. از این رو می ‌توانید از کل ساختار درختی برچسب به جای تنها یک لیست برچسب استفاده کنید.

با noteTaggingByObjectHook به جای یک نام برچسب یک مقصد TagApi به عنوان پارامتر دریافت می کنید. علاوه بر این به عنوان نتیجه ای برای فعالیت لیست، باید لیستی از شناسه های برچسب تهیه کنید.

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

# فراخوانی شگرد و پارامترها

/**
 * 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

You may want to take a look at the example note-tagging-by-object.qml (opens new window) to implement your own tagging mechanism.

# autocompletionHook

هنگامی که تکمیل خودکار (برای مثال با فشردن Ctrl + فاصله) فراخوانی می شود، شما می توانید لیستی از رشته ها را برای افزودن به لیست تکمیل خودکار برگردانید.

# فراخوانی شگرد و پارامترها

/**
 * 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

You may want to take a look at the example 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

You may want to take a look at the examples websocket-raw-data-new-note.qml (opens new window) and 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

You may want to take a look at the example callback-example.qml (opens new window).

# windowStateChangedHook

# فراخوانی شگرد و پارامترها

/**
 * This function is called after a WindowStateChange event was triggered
 *
 * @param {QString} windowState - the new window state, parameter value can be "minimized", "maximized", "fullscreen", "active" or "nostate"
 */
function windowStateChangedHook(windowState);

1
2
3
4
5
6

You may want to take a look at the example window-state-changed.qml (opens new window).

# workspaceSwitchedHook

این هوک زمانی فراخوانده می شود که وضعیت محیط های کار تغییر کند.

# فراخوانی شگرد و پارامترها

/**
 * This function is called when workspaces are switched
 *
 * @param oldUuid old uuid of workspace
 * @param newUuid new uuid of workspace
 */
function workspaceSwitchedHook(oldUuid, newUuid);

1
2
3
4
5
6
7

You may want to take a look at the example websocket-raw-data-new-note.qml (opens new window).

# openAiBackendsHook

This hook is called, when the OpenAI service config is reloaded. For example, this is also done when the script engine is reloaded.

You can use it to provide config for custom OpenAI backends, like your own OpenAI API compatible LLMs.

# Method call and parameters

/**
 * 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

You can use Registering script settings variables to store the OpenAI backend settings in the script settings.

You may want to take a look at the example custom-openai-backends.qml (opens new window).

← روش ها و اهدافی که QOwnNotes فراهم می کند کلاس های آشکار →

Crafted by Patrizio Bekerle with ❤️