Methoden und Objekte, die QOwnNotes bereitstellt

/**
 * QML-Wrapper um einen unabhängigen Prozess zu starten
 *
 * @param executablePath der Pfad der Programmdatei
 * @param parameters eine Liste von Parameterstrings
 * @param callbackIdentifier ein Identifier, der in der Funktion onDetachedProcessCallback() verwendet werden soll (optional)
 * @param callbackParameter ein zusätzlicher Parameter für Schleifen oder ähnliches (optional)
 * @param processData in den Prozess geschriebene Daten, wenn der Callback verwendet wird (optional)
 * @param workingDirectory das Arbeitsverzeichnis, in dem der Prozess ausgeführt werden soll (optional, funktioniert nur ohne Callback)
 * @return true bei Erfolg, sonst false
 */
bool startDetachedProcess(QString executablePath, QStringList parameters,
                            QString callbackIdentifier, QVariant callbackParameter,
                            QByteArray processData, QString workingDirectory);

/**
 * QML-Wrapper, um einen gleichlaufenden Prozess zu starten
 *
 * @param executablePath der Pfad der Programmdatei
 * @param parameters eine Liste von Parameter-strings
 * @param data die Daten, die an den Prozess geschrieben werden (optional)
 * @param workingDirectory das Arbeitsverzeichnis, in dem der Prozess ausgeführt werden soll (optional)
 * @return der Text, der durch den Prozess zurückgegeben wurde
QByteArray startSynchronousProcess(QString executablePath, QStringList parameters, QByteArray data, QString workingDirectory);

/**
 * QML-Wrapper, um den aktuellen Pfad des Notizordners abzurufen
 *
 * @return der Pfad des aktuellen Notizordners
 */
QString currentNoteFolderPath();

/**
 * QML-Wrapper, um die aktuelle Notiz zu erhalten
 *
 * @returns {NoteApi} das aktuelle Notizobjekt
 */
NoteApi currentNote();

/**
 * QML-Wrapper, um auf das Protokoll-Widget zu protokollieren
 *
 * @param text
 */
void log(QString text);

/**
 * QML-Wrapper, um eine URL herunterzuladen und als Text zurückzugeben
 *
 * @param url
 * @return {QString} der Inhalt der heruntergeladenen URL
 */
QString downloadUrlToString(QUrl url);

/**
 * QML-Wrapper, um eine URL in den Medienordner herunterzuladen und die Medien-URL oder
 * den Markdown-Bildtext der Medien relativ zur aktuellen Notiz zurückzugeben
 *
 * @param {QString} url
 * @param {bool} returnUrlOnly falls true, wird nur die Medien-URL zurückgeben (standardmäßig false)
 * @return {QString} Medien-Markdown oder -URL
 */
QString downloadUrlToMedia(QUrl url, bool returnUrlOnly);

/**
 * QML-Wrapper, um eine Mediendatei in den Medienordner einzufügen und die Medien-URL
 * oder den Markdown-Bildtext der Medien relativ zur aktuellen Notiz zurückzugeben
 *
 * @param {QString} mediaFilePath
 * @param {bool} returnUrlOnly falls true, wird nur die Medien-URL zurückgegeben (standardmäßig false)
 * @return {QString} Medien-Markdown oder -URL
 */
QString ScriptingService::insertMediaFile(QString mediaFilePath,
                                        bool returnUrlOnly);

 * QML-Wrapper zum Einfügen einer Anhangsdatei in den Ordner `attachments` und
 * Rückgabe der Anhangs-URL oder des Markdown-Textes des Anhangs
 * bezogen auf die aktuelle Notiz
 *
 * @param {QString} attachmentFilePath
 * @param {QString} fileName für den Markdown
 * @param {bool} returnUrlOnly falss true, wird nur die Anhangs-URL zurückgegeben
 * (standardmäßig false)
 * @return {QString} das Markdown oder die URL des Anhangs
 */
QString ScriptingService::insertAttachmentFile(const QString &attachmentFilePath,
                                                const QString &fileName,
                                                bool returnUrlOnly);

/**
 * Erzeugt die Notizvorschau neu
 */
QString ScriptingService::regenerateNotePreview();

/**
 * Registriert eine benutzerdefinierte Aktion
 *
 * @param identifier Der Identifier der Aktion
 * @param menuText Der Text, der im Menü angezeigt wird
 * @param buttonText Der Text, der auf dem Button angezeigt wird
 *                   (falls leer, wird kein Button angezeigt)
 * @param icon Dateipfad des Icons, oder der Name eines freedesktop theme-Icons
 *             hier finden Sie eine Liste von Icons:
 *             https://specifications.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html
 * @param useInNoteEditContextMenu falls true, nutze die Aktion in der Notizbearbeitungs-
 *                                 Konextmenü (standard: false)
 * @param hideButtonInToolbar falls true, wird der Button nicht in der Toolbar für
 *                            benutzerdefinierte Aktionen angezeigt (standard: false)
 * @param useInNoteListContextMenu falls true, wird die Aktion im Notizlisten-
 *                                 Kontextmenü benutzt (standard: false)
 */
void ScriptingService::registerCustomAction(QString identifier,
                                            QString menuText,
                                            QString buttonText,
                                            QString icon,
                                            bool useInNoteEditContextMenu,
                                            bool hideButtonInToolbar,
                                            bool useInNoteListContextMenu);

/**
 * Registriert ein Label, um etwas darauf zu schreiben
 *
 * @param identifier Der Identifier des Labels
 * @param text Der Text, der auf dem Label angezeigt wird (optional)
 */
void ScriptingService::registerLabel(QString identifier, QString text);

/**
 * Legt den Text eines registrierten Labels fest
 *
 * @param identifier Der Identifier des Labels
 * @param text Der Text, der auf dem Label angezeigt wird
 */
void ScriptingService::setLabelText(QString identifier, QString text);

/**
 * Erstellt eine neue Notiz
 **
 * @param text Der Notiztext
 */
void ScriptingService::createNote(QString-Text);

/**
 * Gibt den Inhalt der Zwischenablage als Text oder HTML zurück
 *
 * @param asHtml gibt den Inhalt der Zwischenablage als HTML anstelle von Text zurück
 */
QString ScriptingService::clipboard (bool asHtml);

/**
 * Schreibt Text an die aktuelle Cursorposition in der Notiztextbearbeitung
 *
 * @param text
 */
void ScriptingService::noteTextEditWrite(QString text);

/**
 * Liest den ausgewählten Text in der Notiztextbearbeitung
 *
 * @return
 */
QString ScriptingService::noteTextEditSelectedText();

/**
 * Wählt den gesamten Text in der Notiztextbearbeitung aus
 */
void ScriptingService::noteTextEditSelectAll();

/**
 * Wählt die aktuelle Zeile in der Notiztextbearbeitung aus
 */
void ScriptingService::noteTextEditSelectCurrentLine();

/**
  * Wählt das aktuelle Wort in der Notiztextbearbeitung aus
  */
void ScriptingService::noteTextEditSelectCurrentWord();

/**
 * Legt den aktuell markierten Text in der Notiztextbearbeitung fest
 *
 * @param start
 * @param end
 */
void ScriptingService::noteTextEditSetSelection(int start, int end);

/**
 * Gibt die Startposition der aktuellen Auswahl in der Notiztextbearbeitung zurück
 */
int ScriptingService::noteTextEditSelectionStart();

/**
 * Gibt die Endposition der aktuellen Auswahl in der Notiztextbearbeitung zurück
 */
int ScriptingService::noteTextEditSelectionEnd();

/**
 * Setzt den Textcursor in der Notiztextbearbeitung auf eine bestimmte Position
 * 0 wäre der Anfang der Notiz
 * Spezialfall: -1 wäre das Ende der Notiz
 *
 * @param position
 */
void ScriptingService::noteTextEditSetCursorPosition(int position);

/**
 * Gibt die aktuelle Position des Textcursors in der Notiztextbearbeitung zurück
 * 0 wäre der Anfang der Notiz
 */
int ScriptingService::noteTextEditCursorPosition();

/**
 * Liest das aktuelle Wort in der Notiztextbearbeitung
 *
 * @param withPreviousCharacters erhält am Anfang auch mehrere Zeichen
 *                                    um Zeichen wie "@" zu erhalten, die nicht
 *                                    Wortzeichen sind
 * @return
 */
QString ScriptingService::noteTextEditCurrentWord(bool withPreviousCharacters);

/**
 * Reads the current block in the note text edit
 *
 * @return
 */
QString ScriptingService::noteTextEditCurrentBlock();

/**
 * QML wrapper to use the AI Completer
 *
 * @param prompt
 * @return {QString} the result of the completer
 */
QString ScriptingService::aiComplete(const QString& prompt);

bool ScriptingService::platformIsLinux();
bool ScriptingService::platformIsOSX();
bool ScriptingService::platformIsWindows();

/**
 * Markiert die aktuelle Notiz mit einem Schlagwort namens tagName
 *
 * @param tagName
 */
void ScriptingService::tagCurrentNote(QString tagName);

/**
 * Erstellt oder ruft ein Schlagwort anhand seiner "Breadcrumb-Liste" von Schlagwortnamen auf
 * Element nameList[0] wäre das höchste im Baum (mit parentId: 0)
 *
 * @param nameList
 * @param createMissing {bool} falls true (standard), werden alle fehlenden Schlagworte erstellt
 * @return TagApi Objekt des tiefsten Schlagworts in der Namen-Breadcrumb-Liste
 */
TagApi *ScriptingService::getTagByNameBreadcrumbList(
    const QStringList &nameList, bool createMissing);

/**
 * Ruft alle Schlagworte ab, indem eine Teilstringsuche im Namensfeld durchgeführt wird
 *
 * @param name {QString} Name, nach dem gesucht werden soll
 * @return {QStringList} Liste der Schlagwort-Namen
 */
QStringList ScriptingService::searchTagsByName(QString name);

/**
 * Gibt eine Liste der Notiz-IDs aller Notizen mit einem bestimmten Text im Notiztext zurück
 *
 * Leider gibt es keine einfache Möglichkeit, eine QList<NoteApi*> in QML zu verwenden,
 * weshalb wir nur die Notiz-IDs übertragen können
 *
 * @return {QList<int>} Liste der Notiz-IDs
 */
QList<int> ScriptingService::fetchNoteIdsByNoteTextPart(QString text);

/**
 * Fügt der Anwendung ein benutzerdefiniertes Stylesheet hinzu
 *
 * @param Stylesheet
 */
void ScriptingService::addStyleSheet(QString stylesheet);

/**
 * Lädt die Scripting-Engine neu
 */
void ScriptingService::reloadScriptingEngine();

/**
 * Ruft eine Notiz anhand ihres Dateinamens ab
 *
 * @param fileName string Der Dateinamen der Notiz (notwendig)
 * @param noteSubFolderId integer ID des Notizunterordners
 * @return NoteApi*
 */
NoteApi* ScriptingService::fetchNoteByFileName(QString fileName,
                                                int noteSubFolderId);

/**
 * Ruft eine Notiz anhand ihrer ID ab
 *
 * @param id int Die ID der Notiz
 * @return NoteApi*
 */
NoteApi* ScriptingService::fetchNoteById(int id);

/**
 * Überprüft anhand des Dateinamens, ob eine Notizdatei vorhanden ist
 *
 * @param fileName string Der Dateiname der Notiz (obligatorisch)
 * @param ignoreNoteId integer ID einer Notiz, die bei der Prüfung ignoriert werden soll
 * @param noteSubFolderId integer ID des Notiz-Unterordners
 * @return bool
 */
bool ScriptingService::noteExistsByFileName(QString fileName,
                                            int ignoreNoteId,
                                            int noteSubFolderId);

/**
 * Kopiert Text als Klartext- oder HTML-MIME-Daten in die Zwischenablage
 *
 * @param text string Text, der in die Zwischenablage eingefügt werden soll
 * @param asHtml bool Wenn true, wird der Text als HTML-MIME-Daten festgelegt
 */
void ScriptingService::setClipboardText(QString text, bool asHtml);

/**
 * Legt die aktuelle Notiz fest, wenn die Notiz in der Notizliste sichtbar ist
 *
 * @param note NoteApi Notiz, in die gesprungen werden soll
 * @param asTab bool falls true, wird die Notiz in einem neuen Tab geöffnet (falls nicht schon geöffnet)
 */
void ScriptingService::setCurrentNote(NoteApi *note, bool asTab = false);

/**
 * Springt zu einem Notizunterordner
 *
 * @param noteSubFolderPath {QString} Pfad des Unterordners relativ zum Notizordner
 * @param separator {QString} Trennzeichen zwischen Teilen des Pfads, Standard "/"
 * @return true, wenn der Sprung erfolgreich war
 */
bool ScriptingService::jumpToNoteSubFolder(const QString &noteSubFolderPath,
                                            QString separator);

/ **
 * Zeigt ein Informationsmeldungsfeld an
 *
 * @param text
 * @param title (optional)
 */
void ScriptingService::informationMessageBox(QString text, QString title);

/ **
 * Zeigt ein Fragenmeldungsfeld an
 *
 * Informationen zu Schaltflächen finden Sie unter:
 * https://doc.qt.io/qt-5/qmessagebox.html#StandardButton-enum
 *
 * @param text
 * @param title (optional)
 * @param buttons Schaltflächen, die angezeigt werden sollen (optional)
 * @param defaultButton Standardschaltfläche, die ausgewählt wird (optional)
 * @return ID der gedrückten Schaltfläche
 */
int ScriptingService::questionMessageBox(
        QString text, QString title, int buttons, int defaultButton);

/**
 * Zeigt einen Dialog zum Öffnen von Dateien an
 *
 * @param caption (optional)
 * @param dir (optional)
 * @param filter (optional)
 * @return QString
 */
QString ScriptingService::getSaveFileName(QString caption, QString dir,
                                             QString filter);

/**
 * Zeigt einen Dialog zum Speichern von Dateien an
 *
 * @param caption (optional)
 * @param dir (optional)
 * @param filter (optional)
 * @return QString
 */
QString ScriptingService::getSaveFileName(QString caption, QString dir,
                                             QString filter);

/**
 * Stores a persistent variable
 * These variables are accessible globally over all scripts
 * Please use a meaningful prefix in your key like "PersistentVariablesTest/myVar"
 *
 * @param key {QString}
 * @param value {QVariant}
 */
void ScriptingService::setPersistentVariable(const QString &key,
                                             const QVariant &value);

/**
 * Loads a persistent variable
 * These variables are accessible globally over all scripts
 *
 * @param key {QString}
 * @param defaultValue {QVariant} return value if the setting doesn't exist (optional)
 * @return
 */
QVariant ScriptingService::getPersistentVariable(const QString &key,
                                                 const QVariant &defaultValue);

/**
 * Loads an application settings variable
 *
 * @param key {QString}
 * @param defaultValue {QVariant} return value if the setting doesn't exist (optional)
 * @return
 */
QVariant ScriptingService::getApplicationSettingsVariable(const QString &key,
                                                          const QVariant &defaultValue);

/**
 * Gibt ein Cache-Verzeichnis für ein Skript zurück
 *
 * @param {QString} subDir Der zu erstellende und zu verwendende Unterordner
 * @return {QString} Der Cache-Verzeichnispfad
 */
QString ScriptingService::cacheDir(const QString &subDir) const;

/**
 * Löscht das Cache-Verzeichnis für ein Skript
 *
 * @param {QString} subDir Der zu löschende Unterordner
 * @return {bool} true bei Erfolg
 */
bool ScriptingService::clearCacheDir(const QString &subDir) const;

/**
 * Gibt den Pfad zurück, und konvertiert die "/" Trennzeichen zu Trennzeichen,
 * die für das zugrundeliegende Betriebssystem angemessen sind.
 *
 * Unter Windows, toNativeDirSeparators("c:/winnt/system32") gibt
 * "c:\winnt\system32" zurück.
 *
 * @param path
 * @return
 */
QString ScriptingService::toNativeDirSeparators(QString path);

/**
 * Gibt den Pfad mit '/' als Dateitrennzeichen zurück.
 * Unter Windows gibt fromNativeDirSeparators("c:\\winnt\\system32")
 * beispielsweise "c:/winnt/system32" zurück.
 *
 * @param path
 * @return
 */
QString ScriptingService::toNativeDirSeparators(QString path);

/**
 * Gibt das native Verzeichnis-Trennzeichen "/" oder "\" unter Windows zurück
 *
 * @return
 */
QString ScriptingService::dirSeparator();

/**
 * Gibt eine Liste der Pfade aller ausgewählten Notizen zurück
 *
 * @return {QStringList} Liste der ausgewählten Notizpfade
 */
QStringList ScriptingService::selectedNotesPaths();

/**
 * Gibt eine Liste der IDs aller ausgewählten Notizen zurück
 *
 * @return {QList<int>} Liste der ausgewählten Notiz-IDs
 */
QList<int> ScriptingService::selectedNotesIds();

/**
 * Löst eine Menüaktion aus
 *
 * @param objectName {QString} Objektname der auszulösenden Aktion
 * @param checked {QString} löst die Aktion nur aus, wenn der check-state anders
 *                          als dieser Parameter ist (optional, kann 0 oder 1 sein)
 */
void ScriptingService::triggerMenuAction(QString objectName, QString checked);

/ **
 * Öffnet einen Eingabedialog mit einem Auswahlfeld
 *
 * @param title {QString} Titel des Dialogfelds
 * @param label {QString} Beschriftungstext des Dialogfelds
 * @param items {QStringList} Liste der auszuwählenden Elemente
 * @param current {int} Index des Elements, das ausgewählt werden soll (standard: 0)
 * @param editable {bool} Wenn true, kann der Text im Dialogfeld bearbeitet werden (standard: false).
 * @return {QString} Text des ausgewählten Elements
 */
QString ScriptingService::inputDialogGetItem(
        const QString &title, const QString &label, const QStringList &items,
        int current, bool editable);

/**
 * Öffnet einen Eingabedialog mit einer Zeilenbearbeitung
 *
 * @param title {QString} Titel des Dialogfelds
 * @param label {QString} Beschriftungstext des Dialogfelds
 * @param text {QString} Text im Dialog (optional)
 * @return
 * /
QString ScriptingService::inputDialogGetText(
        const QString &title, const QString &label, const QString &text);

/**
 * Opens an input dialog with a multi-line text edit
 *
 * @param title {QString} title of the dialog
 * @param label {QString} label text of the dialog
 * @param text {QString} text in the dialog (optional)
 * @return
 */
QString ScriptingService::inputDialogGetMultiLineText(
        const QString &title, const QString &label, const QString &text);

/**
* Opens a dialog to show the differences between two texts and lets the user edit the result
*
* @param title {QString} title of the dialog
* @param label {QString} label text of the dialog
* @param text1 {QString} first text
* @param text2 {QString} second text
* @return
  */
  QString ScriptingService::textDiffDialog(const QString &title, const QString &label,
                                           const QString &text1, const QString &text2);

/**
 * Überprüft, ob eine Datei vorhanden ist
 * @param filePath
 * @return
 */
bool ScriptingService::fileExists(QString &filePath);

/**
 * Liest Text aus einer Datei
 *
 * @param filePath {QString} Pfad der zu ladenden Datei
 * @param codec {QString} Dateikodierung (Standard: UTF-8)
 * @return die Dateidaten oder null, wenn die Datei nicht existiert
 */
QString ScriptingService::readFromFile(const QString &filePath, const QString &codec)

/**
 * Schreibt einen Text in eine Datei
 *
 * @param filePath {QString}
 * @param data {QString}
 * @param createParentDirs {bool} optional (Standard: false)
 * @return
 */
bool ScriptingService::writeToFile(const QString &filePath, const QString &data, bool createParentDirs);

/**
 * Fügt dem Syntax-Highlighter des Editors eine Hervorhebungsregel hinzu
 *
 * @param pattern {QString} das hervorzuhebende reguläre Ausdrucksmuster
 * @param shouldContain {QString} eine Zeichenfolge, die im hervorgehobenen Text enthalten sein muss, damit das Muster analysiert werden kann
 * @param state {int} der Zustand des zu verwendenden Syntax-Highlighters
 * @param capturingGroup {int} die Erfassungsgruppe für das Muster, das zum Hervorheben verwendet werden soll (Standard: 0)
 * @param maskedGroup {int} die Erfassungsgruppe für das Muster, das zum Maskieren verwendet werden soll (Standard: 0)
 */
void ScriptingService::addHighlightingRule(const QString &pattern,
                                            const QString &shouldContain,
                                            int state,
                                            int capturingGroup,
                                            int maskedGroup);