# Méthodes et objets fournis par QOwnNotes

# Lancer un programme externe en arrière-plan

# Appel de méthode et paramètres

/**
 * Wrapper QML pour démarrer un processus détaché
 *
 * @param executablePath le chemin d'accès de l'exécutable
 * @param parameters une liste de chaînes de paramètres
 * @param callbackIdentifier un indetifiant à utiliser dans la fonction onDetachedProcessCallback() (optionnel)
 * @param callbackParameter un paramètre additionel pour les boucles ou équivalents (optionnel)
 * @param processData données écrites vers le processus si la fonction de rappel est utilisée (optionnel)
 * @param workingDirectory le répertoire de travail dans lequel exécuter le processus (optionnel, fonctionne seulement avec une fonction de rappel)
 * @return true en cas de succès, false sinon
 */
bool startDetachedProcess(QString executablePath, QStringList parameters,
                            QString callbackIdentifier, QVariant callbackParameter,
                            QByteArray processData, QString workingDirectory);
1
2
3
4
5
6
7
8
9
10
11
12
13
14

# Exemple

Exemple simple :

script.startDetachedProcess("/chemin/vers/mon/programme", ["mon paramètre"]);
1

Exemple simple :

for (var i = 0; i < 100; i++) {
    var dur = Math.floor(Math.random() * 10) + 1;
    script.startDetachedProcess("sleep", [`${dur}s`], "my-callback", i);
}

function onDetachedProcessCallback(callbackIdentifier, resultSet, cmd, thread) {
    if (callbackIdentifier == "my-callback") {
        script.log(`#${thread[1]} i[${thread[0]}] t${cmd[1]}`);
    }
}
1
2
3
4
5
6
7
8
9
10

Vous voudrez peut-être jeter un coup d'œil aux exemples custom-actions.qml (opens new window), callback.qml (opens new window) ou exécution-commande-après-note-update.qml (opens new window).

Vous voudrez peut-être jeter un coup d'œil au hook onDetachedProcessCallback.

# Lancer un programme externe et attendre la sortie

# Appel de méthode et paramètres

/**
 * Wrapper QML pour démarrer un processus synchrone
 *
 * @param executablePath le chemin vers l'exécutable
 * @param parameters une liste de chaînes de paramètres
 * @param data les données qui seront écrites vers le processus (optionnel)
 * @param workingDirectory le répertoire de travail dans lequel exécuter le processus (optionnel)
 * @return le texte qui a été retourné par le processus
QByteArray startSynchronousProcess(QString executablePath, QStringList parameters, QByteArray data, QString workingDirectory);
1
2
3
4
5
6
7
8
9

# Exemple

var result = script.startSynchronousProcess("/chemin/vers/mon/programme", ["mon paramètre"], "données", "/chemin/d'accès/dans/lequel/exécuter");
1

Vous voudrez peut-être jeter un œil à l'exemple encryption-keybase.qml (opens new window).

# Obtenir le chemin du dossier de notes actuel

# Appel de méthode et paramètres

/**
  * Wrapper QML pour obtenir le chemin du dossier de notes actuel
  *
  * @return le chemin du dossier de notes actuel
  */
QString currentNoteFolderPath();
1
2
3
4
5
6

# Exemple

var path = script.currentNoteFolderPath();
1

Vous voudrez peut-être jeter un œil à l'exemple absolute-media-links.qml (opens new window).

# Obtenir la note actuelle

# Appel de méthode et paramètres

/**
 * Wrapper QML pour obtenir la note courante
 *
 * @returns {NoteApi} l'objet note courante
 */
NoteApi currentNote ();
1
2
3
4
5
6

# Exemple

var note = script.currentNote();
1

Vous voudrez peut-être jeter un coup d'œil à l'exemple custom-actions.qml (opens new window).

# Connexion au widget de journal

# Appel de méthode et paramètres

/**
 * Wrapper QML pour se connecter au widget de journal
 *
 * @param text
 */
void log(QString text);
1
2
3
4
5
6

# Exemple

script.log("mon texte");
1

# Téléchargement d'une URL dans une chaîne

# Appel de méthode et paramètres

/**
  * Wrapper QML pour télécharger une URL et la renvoyer sous forme de texte
  *
  * @param url
  * @return {QString} le contenu de l'url téléchargée
  */
QString downloadUrlToString(QUrl url);
1
2
3
4
5
6
7

# Exemple

var html = script.downloadUrlToString("https://www.qownnotes.org");
1

Vous voudrez peut-être jeter un coup d'œil à l'exemple insert-headline-with-link-from-github-url.qml (opens new window).

# Téléchargement d'une URL dans le dossier multimédia

# Appel de méthode et paramètres

/**
 * Wrapper QML pour télécharger une URL dans le dossier multimédia et renvoyer le média
 * url ou le texte Markdown de l'image du média relativement à la note actuelle
 *
 * @param {QString} url
 * @param {bool} returnUrlOnly si true, seule l'URLdu média sera renvoyée (par défaut false)
 * @return {QString} le Markdown ou l'URL du média
 */
QString downloadUrlToMedia (QUrl url, booléen returnUrlOnly);
1
2
3
4
5
6
7
8
9

# Exemple

var markdown = script.downloadUrlToMedia("http://latex.codecogs.com/gif.latex?\frac{1}{1+sin(x)}");
1

Vous voudrez peut-être jeter un coup d'œil à l'exemple paste-latex-image.qml (opens new window).

# Insertion d'un fichier multimédia dans le dossier multimédia

# Appel de méthode et paramètres

/**
  * Wrapper QML pour insérer un fichier multimédia dans le dossier des médias et retourner
  * l'URL du média ou le texte Markdown de l'image du média relativement à la note actuelle
  *
  * @param {QString} mediaFilePath
  * @param {bool} returnUrlOnly si true, seule l'URL du média sera retournée (par défaut false)
  * @return {QString} le Markdown ou l'URL du média
  */
QString ScriptingService::insertMediaFile (QString mediaFilePath,
                                         booléen returnUrlOnly);
1
2
3
4
5
6
7
8
9
10

# Exemple

var markdown = script.insertMediaFile("/chemin/vers/votre/image.png");
1

Vous voudrez peut-être jeter un coup d'œil à l'exemple scribble.qml (opens new window).

# Insérer un fichier joint dans le dossier des pièces jointes

# Appel de méthode et paramètres

 * Wrapper QML pour insérer un fichier joint dans le dossier `attachments` et
  * retourner l'URL de la pièce jointe ou le texte en Markdown de la pièce jointe
* relativement à la note actuelle
*
* @param {QString} attachmentFilePath
 * @param {QString} fileName à utiliser dans le Markdown
 * @param {bool} returnUrlOnly si true seule l'url de la pièce jointes era retournée
 * (false par défaut)
 * @return {QString} le Markdown ou l'url de la pièce jointe
 */
QString ScriptingService::insertAttachmentFile(const QString &attachmentFilePath,
                                               const QString &fileName,
                                               bool returnUrlOnly);
1
2
3
4
5
6
7
8
9
10
11
12
13

# Exemple

var markdown = script.insertAttachmentFile("/chemin/vers/votre/fichier.png");
1

# Régénérer l'aperçu de la note

Actualise l'aperçu de la note.

# Appel de méthode et paramètres

/**
 * Régénère l'aperçu de la note
 */
QString ScriptingService::regenerateNotePreview();
1
2
3
4

# Exemple

script.regenerateNotePreview();
1

Vous voudrez peut-être jeter un coup d'œil à l'exemple scribble.qml (opens new window).

# Déclarer une action personnalisée

# Appel de méthode et paramètres

/**
 * Enregistre une action personnalisée
 *
 * @param identifier l'identifiant de l'action
 * @param menuText le texte affiché dans le menu
 * @param buttonText le texte affiché dans le bouton
 *                   (aucun bouton vide ne sera affiché)
 * @param icon le chemin d'accès vers l'icône ou le nom d'un icône du thème freedesktop
 *             vous trouverez ici une liste des icônes :
 *             https://specifications.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html
 * @param useInNoteEditContextMenu si true utiilser l'action dans l'éditeur de notes
 *                                 context menu (default: false)
 * @param hideButtonInToolbar si true le bouton ne sera pas affiché dans
 *                            la barre d'outil des actions personnalisées (par défaut : false)
 * @param useInNoteListContextMenu si true utiliser l'action dans le menu contextuel de
 *                                 la liste de notes (par défaut : false)
 */
void ScriptingService::registerCustomAction(QString identifier,
                                            QString menuText,
                                            QString buttonText,
                                            QString icon,
                                            bool useInNoteEditContextMenu,
                                            bool hideButtonInToolbar,
                                            bool useInNoteListContextMenu);
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

TIP

Vous pouvez également attribuer des raccourcis locaux ou globaux à vos actions personnalisées dans les Paramètres des raccourcis.

WARNING

Soyez attentif au fait que les icones du thème freedesktop (opens new window) ne sont généralement disponibles que sous Linux. À cause de cela, si vous souhaitez vraiment utiliser un icone sous macOS ou Windows vous devrez le fournir avec votre script. Pour obtenir le chemin vers votre script afin de définir un chemin correct vers votre icone, utilisez scriptDirPath property.

# Exemple

import QtQml 2.0
import QOwnNotesTypes 1.0

Script {
    /**
     * Initialise les actions personnalisées
     */
    function init() {
        // ajouter une action personnalisée sans bouton
        script.registerCustomAction("mycustomaction1", "Texte du menu");

        // ajouter une action personnalisée avec un bouton
        script.registerCustomAction("mycustomaction2", "Texte du menu", "Texte du bouton");

        // ajouter une action personnalisée avec un bouton et un icône du thème freedesktop
        script.registerCustomAction("mycustomaction3", "Texte du menu", "Texte du bouton", "nouvelle-tâche");

        // ajouter une action personnalisée avec un bouton et un icône provenant d'un fichier
        script.registerCustomAction("mycustomaction4", "Texte du menu", "Texte du bouton", "/usr/share/icons/breeze/actions/24/view-calendar-tasks.svg");
    }

    /**
     * Cette fonction est appelée quand une action personnalisée est déclenchée
     * dans le menu ou via un bouton
     * 
     * @param identifier string l'identifiant défini dans registerCustomAction
     */
    function customActionInvoked(identifier) {
        switch (identifier) {
            case "mycustomaction1":
                script.log("Action 1");
            break;
            case "mycustomaction2":
                script.log("Action 2");
            break;
            case "mycustomaction3":
                script.log("Action 3");
            break;
            case "mycustomaction4":
                script.log("Action 4");
            break;
        }
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44

Pour d'autres exemples allez voir custom-actions.qml (opens new window).

TIP

Vous pouvez également déclencher une action personnalisée après le démarrage de l'application avec le paramètre --action customAction_<identifier>. Pour plus d'information, veuillez consulter Déclencher des actions de menu après le démarrage.

# Enregistrer une étiquette

# Appel de méthode et paramètres

/**
 * Enregistre une étiquette sur laquelle écrire
 *
 * @param identifier the identifier of the label
 * @param text the text shown in the label (optional)
 */
void ScriptingService::registerLabel(QString identifier, QString text);
1
2
3
4
5
6
7

# Exemple

script.registerLabel("html-label", "<strong>Strong</strong> Texte HTML <br />avec trois lignes<br />et un <a href='https://www.qownnotes.org'>lien vers un site web</a>.");

script.registerLabel("long-label", "encore un très long texte, encore un très long texte, encore un très long texte, encore un très long texte, encore un très long texte, encore un très long texte, encore un très long texte, encore un très long texte, encore un très long texte, encore un très long texte, encore un très long texte qui sera renvoyé à la ligne");

script.registerLabel("counter-label");
1
2
3
4
5

Les étiquettes seront visibles dans le widget de scripting du dock.

Vous pouvez utiliser à la fois du texte brut ou du HTML dans les étiquettes. Le texte sera sélectionnable et les liens pourront être cliqués.

Vous aurez peut-être envie de jeter un œil à l'exemple de script scripting-label-demo.qml (opens new window).

# Définition du texte d'une étiquette enregistrée

# Appel de méthode et paramètres

/**
 * Définit le texte d'une étiquette enregistrée
 *
 * @param identifier l'identifiant du label
 * @param text le texte affiché dans l'étiquette
 */
void ScriptingService::setLabelText(QString identifier, QString text);
1
2
3
4
5
6
7

# Exemple

script.setLabelText("étiquette-compteur", "texte compteur");
1

Vous pouvez utiliser à la fois du texte brut ou du HTML dans les étiquettes. Le texte sera sélectionnable et les liens pourront être cliqués.

Vous aurez peut-être envie de jeter un œil à l'exemple de script scripting-label-demo.qml (opens new window).

# Créer une nouvelle note

# Appel de méthode et paramètres

/**
 * Créé une nouvelle note
 *
 * @param text le texte de la note
 */
void ScriptingService::createNote(QString text);
1
2
3
4
5
6

# Exemple

script.createNote("Le titre de ma note\n===\n\nMon texte");
1

Vous voudrez peut-être jeter un coup d'œil à l'exemple custom-actions.qml (opens new window).

TIP

Si vous avez désactivé que le titre de votre note détermine le nom de fichier de la note, vous devrez par la suite renommer vous-même votre fichier de note comme ceci :

var note = script.currentNote();
note.renameNoteFile('votre-nom-de-fichier');
1
2

# Accéder au presse-papiers

# Appel de méthode et paramètres

/**
 * Retourne le contenu du presse-papier sous forme de texte ou de HTML
 *
 * @param asHtml retourne le contenu du presse-papier sous forme de HTML au lieu de texte
 */
QString ScriptingService::clipboard(bool asHtml);
1
2
3
4
5
6

# Exemple

var clipboardText = script.clipboard();
var clipboardHtml = script.clipboard(true);
1
2

Vous voudrez peut-être jeter un coup d'œil à l'exemple custom-actions.qml (opens new window).

# Écrire du texte dans le corps de la note

# Appel de méthode et paramètres

/**
 * Écrit du texte à la position courante du curseur dans le corps de la note
 *
 * @param text
 */
void ScriptingService::noteTextEditWrite(QString text);
1
2
3
4
5
6

# Exemple

// écrire texte dans le corps de la note
script.noteTextEditWrite("Mon texte à moi");
1
2

Vous voudrez peut-être jeter un œil à l'action personnalisée transformTextRot13 dans l'exemple custom-actions.qml (opens new window).

Vous pouvez l'utiliser en conjonction avec noteTextEditSelectAll pour écraser tout le texte de la note actuelle.

# Lire le texte sélectionné dans le corps de la note

# Appel de méthode et paramètres

/**
 * Lit le texte sélectionné dans le corps de la note
 *
 * @return
 */
QString ScriptingService::noteTextEditSelectedText();
1
2
3
4
5
6

# Exemple

// lit le texte sélectionné dans le corps de la note
var text = script.noteTextEditSelectedText();
1
2

Vous voudrez peut-être jeter un œil à l'action personnalisée transformTextRot13 dans l'exemple custom-actions.qml (opens new window).

# Sélectionner l'intégralité du texte de la note

# Appel de méthode et paramètres

/**
 * Sélectionne l'intégralité du texte de la note
 */
void ScriptingService::noteTextEditSelectAll();
1
2
3
4

# Exemple

script.noteTextEditSelectAll();
1

Vous pouvez utiliser ceci en conjonction avec noteTextEditWrite pour écraser tout le texte de la note actuelle.

# Sélectionner la ligne actuelle dans le texte de la note

# Appel de méthode et paramètres

/**
 * Sélectionne la ligne actuelle dans le texte de la note
 */
void ScriptingService::noteTextEditSelectCurrentLine();
1
2
3
4

# Exemple

script.noteTextEditSelectCurrentLine();
1

# Sélectionner le mot actuel dans le texte de la note

# Appel de méthode et paramètres

/**
 * Sélectionne la ligne actuelle dans l'édition du texte de la note
 */
void ScriptingService::noteTextEditSelectCurrentWord();
1
2
3
4

# Exemple

script.noteTextEditSelectCurrentWord();
1

# Définir le texte actuellement sélectionné dans le corps de la note

# Appel de méthode et paramètres

/**
 *Définit le texte actuellement sélectionné dans le corps de la note
 *
 * @param start
 * @param end
 */
void ScriptingService::noteTextEditSetSelection(int start, int end);
1
2
3
4
5
6
7

# Exemple

// étendre la sélection actuelle d'un caractère
script.noteTextEditSetSelection(
    script.noteTextEditSelectionStart() - 1,
    script.noteTextEditSelectionEnd() + 1);
1
2
3
4

# Obtenir la position de départ de la sélection courante dans le texte de la note

# Appel de méthode et paramètres

/**
 * Renvoie la position de départ de la sélection actuelle dans l'éditeur de texte de la note
 */
int ScriptingService::noteTextEditSelectionStart();
1
2
3
4

# Exemple

script.log(script.noteTextEditSelectionStart());
1

# Obtenir la position de fin de la sélection courante dans le texte de la note

# Appel de méthode et paramètres

/**
 * Renvoie la position de fin de la sélection actuelle dans l'éditeur de texte de la note
 */
int ScriptingService :: noteTextEditSelectionEnd ();
1
2
3
4

# Exemple

script.log(script.noteTextEditSelectionEnd());
1

# Placer le curseur à un endroit donné du texte de la note

# Appel de méthode et paramètres

/**
 * Place le curseur à un endroit donné dans le texte de la note
 * 0 serait le début de la note
 * cas particulier: -1 serait la fin de la note
 *
 * @param position
 */
void ScriptingService::noteTextEditSetCursorPosition(int position);
1
2
3
4
5
6
7
8

# Exemple

// sauter au 11ème caractère dans la note
script.noteTextEditSetCursorPosition(10);

// sauter à la fin de la note
script.noteTextEditSetCursorPosition(-1);
1
2
3
4
5

# Obtenir la position actuelle du curseur dans le texte de la note

# Appel de méthode et paramètres

/**
 * Retourne la position actuelle du curseur dans le texte de la note
 * 0 serait le début de la note
 */
int ScriptingService::noteTextEditCursorPosition();
1
2
3
4
5

# Exemple

script.log(script.noteTextEditCursorPosition());
1

# Lire le mot actuel dans le texte de la note

# Appel de méthode et paramètres

/**
 * Lit le mot actuel dans le texte de la note
 *
 * @param withPreviousCharacters pour récupérer plus de caractères au début
 *                               pour récupérer des caractères tels que "@" qui ne sont pas
 *                              des caractères de mots
 * @return
 */
QString ScriptingService::noteTextEditCurrentWord(bool withPreviousCharacters);
1
2
3
4
5
6
7
8
9

# Exemple

// Lit le mot actuel dans le texte de la note
var text = script.noteTextEditCurrentWord();
1
2

Vous voudrez peut-être jeter un coup d'œil à l'exemple autocompletion.qml (opens new window).

# Déterminer si la plate-forme est Linux, OS X ou Windows

# Appel de méthode et paramètres

bool ScriptingService::platformIsLinux();
bool ScriptingService::platformIsOSX();
bool ScriptingService::platformIsWindows();
1
2
3

# Exemple

if (script.platformIsLinux()) {
   // ne sera exécuté que sous Linux
}
1
2
3

# Étiquetter la note actuelle

# Appel de méthode et paramètres

/**
 * Étiquette la note courante avec une étiquette nommée tagName
 *
 * @param tagName
 */
void ScriptingService::tagCurrentNote(QString tagName);
1
2
3
4
5
6

# Exemple

// ajouter une étiquette "favorite" à la note courante
script.tagCurrentNote("favorite");
1
2

Vous voudrez peut-être jeter un coup d'œil à l'action personnalisée favoriteNote dans l'exemple favorite-note.qml (opens new window).

# Créer ou récupérer une étiquette par son nom liste de fil d'Ariane

# Appel de méthode et paramètres

/**
 * Créé ou récupère une étiquette par son nom liste de fil d'Ariane
 * Element nameList[0] serait le plus élevé dans l'arborescence (with parentId: 0)
 *
 * @param nameList
 * @param createMissing {bool} si true (default) toutes les étiquettes manquantes seront créées
 * @return TagApi object de l'étiquette la plus profonde du nom liste de fil d'Ariane
 */
TagApi *ScriptingService::getTagByNameBreadcrumbList(
    const QStringList &nameList, bool createMissing);
1
2
3
4
5
6
7
8
9
10

# Exemple

// crée toutes les étiquettes jusqu'au 3ème niveau et renvoie l'objet étiquette pour la
// balise "level3", qui ressemblerait à ceci dans l'arborescence des balises:
// level1 > level2 > level3
var tag = script.getTagByNameBreadcrumbList(["level1", "level2", "level3"]);
1
2
3
4

# Rechercher des étiquettes par nom

# Appel de méthode et paramètres

/**
 * Récupère toutes les étiquettes par le biais d'une recherche de sous-chaîne sur le champ « nom ».
 *
 * @param name {QString} nom à rechercher
 * @return {QStringList} liste des noms des étiquettes
 */
QStringList ScriptingService::searchTagsByName(QString name);
1
2
3
4
5
6
7

# Exemple

// recherche toutes les étiquettes contenant le mot "jeu"
var tags = script.searchTagsByName("jeu");
1
2

Vous voudrez peut-être jeter un coup d'œil à l'exemple autocompletion.qml (opens new window).

# Rechercher des notes à partir de texte contenu dans le corps d'une note

# Appel de méthode et paramètres

/**
 * Retourne une liste des identifiants de toutes les notes contenant un certain texte dans leur corps.
 *
 * Malheureusement il n'y a pas de moyen facile pour utiliser un QList<NoteApi*> en QML, c'est pourquoi on
 * ne peut transférer que les identifiants de notes
 *
 * @return {QList<int>} liste des identifiants de notes
 */
QList<int> ScriptingService::fetchNoteIdsByNoteTextPart(QString text);
1
2
3
4
5
6
7
8
9

# Exemple

var noteIds = script.fetchNoteIdsByNoteTextPart("montexte");

noteIds.forEach(function (noteId){
    var note = script.fetchNoteById(noteId);

    // faire quelque chose avec la note
});
1
2
3
4
5
6
7

Vous voudrez peut-être jeter un coup d'œil à l'exemple unique-note-id.qml (opens new window).

# Ajouter une feuille de style personnalisée

# Appel de méthode et paramètres

/**
 * Ajoute une feuille de style personnalisée à l'application
 *
 * @param stylesheet
 */
void ScriptingService::addStyleSheet(QString stylesheet);
1
2
3
4
5
6

# Exemple

// augmenter la taille du texte de la liste des notes
script.addStyleSheet("QTreeWidget#noteTreeWidget {font-size: 30px;}");
1
2

Vous voudrez peut-être jeter un coup d'œil à l'exemple custom-stylesheet.qml (opens new window).

Vous pouvez obtenir les noms des widgets à partir des fichiers *.ui. Par exemple, la fenêtre principale est mainwindow.ui (opens new window).

La documentation Qt (par exemple QMainWindow (opens new window)) peut vous aider à voir comment les widgets sont liés les uns aux autres (recherchez Inherits).

Le widget de base pour presque tout est QWidget (opens new window). De ce fait, le seul ajustement de style de QWidget avec par exemple QWidget {background-color: black; color: white;} signifierait que tout a une couleur d'arrière-plan noire et une couleur de premier plan blanche.

TIP

Le style.qss (opens new window) de qdarkstyle (opens new window) peut également constituer une bonne référence des styles que vous pouvez changer.

Jetez un œil à Style Sheet Reference (opens new window) en tant que référence des styles disponibles.

Si vous souhaitez injecter des styles dans l'aperçu HTML pour modifier la façon dont les notes sont prévisualisées, veuillez consulter notetomarkdownhtmlhook.

TIP

Si vous souhaitez voir l'aspect des dialogues et quels sont leurs noms, téléchargezQt Creator (opens new window) et ouvrez les fichiers *.ui qu'il contient.

# Recharger le moteur de script

# Appel de méthode et paramètres

/**
 * Recharge le moteur de script
 */
void ScriptingService :: reloadScriptingEngine ();
1
2
3
4

# Exemple

// recharger le moteur de script
script.reloadScriptingEngine ();
1
2

# Récupérer une note par son nom de fichier

# Appel de méthode et paramètres

/**
 * Récupère une note par son nom de fichier
 *
 * @param fileName string le nom de fichier de la note (obligatoire)
 * @param noteSubFolderId ID entier du sous-dossier de notes
 * @return NoteApi *
 */
NoteApi * ScriptingService :: fetchNoteByFileName (QString fileName,
                                                 int noteSubFolderId);
1
2
3
4
5
6
7
8
9

# Exemple

// récupère la note par nom de fichier
script.fetchNoteByFileName ("ma note.md");
1
2

# Récupérer une note par son identifiant

# Appel de méthode et paramètres

/**
 * Récupère une note par son identifiant
 *
 * @param id int l'identifiant de la note
 * @return NoteApi *
 */
NoteApi* ScriptingService::fetchNoteById(int id);
1
2
3
4
5
6
7

# Exemple

// récupère la note par identifiant
script.fetchNoteById (243);
1
2

Vous voudrez peut-être jeter un coup d'œil à l'exemple export-notes-as-one-html.qml (opens new window).

# Vérifier si une note existe par son nom de fichier

# Appel de méthode et paramètres

/**
 * Vérifie si un fichier de note existe par son nom de fichier
 *
 * @param fileName string le nom de fichier de la note (obligatoire)
 * @param ignoreNoteId identifiant entier d'une note à ignorer lors de la vérification
 * @param noteSubFolderId ID entier du sous-dossier de notes
 * @return booléen
 */
booléen ScriptingService :: noteExistsByFileName (QString fileName,
                                             int ignoreNoteId,
                                             int noteSubFolderId);
1
2
3
4
5
6
7
8
9
10
11

# Exemple

// vérifie si la note existe, mais ignore l'id de "note"
script.noteExistsByFileName ("ma note.md", note.id);
1
2

Vous voudrez peut-être jeter un coup d'œil à l'exemple use-tag-names-in-filename.qml (opens new window).

# Copier du texte dans le presse-papiers

# Appel de méthode et paramètres

/**
 * Copie du texte dans le presse-papiers sous forme de texte brut ou de données MIME HTML
 *
 * @param text string texte à mettre dans le presse-papiers
 * @param asHtml bool si true, le texte sera défini en tant que données MIME HTML
 */
void ScriptingService::setClipboardText(QString text, bool asHtml);
1
2
3
4
5
6
7

# Exemple

// copie du texte dans le presse-papiers
script.setClipboardText ("texte à copier");
1
2

Vous voudrez peut-être jeter un coup d'œil à l'exemple selected-markdown-to-bbcode.qml (opens new window).

# Sauter vers une note

# Appel de méthode et paramètres

/**
 * Définit la note actuelle si la note est visible dans la liste des notes
 *
 * @param note NoteApi note pour passer à
 */
void ScriptingService::setCurrentNote(NoteApi *note);
1
2
3
4
5
6

# Exemple

// sauter vers la note
script.setCurrentNote (note);
1
2

Vous voudrez peut-être jeter un coup d'œil à l'exemple journal-entry.qml (opens new window).

# Sauter vers un sous-dossier de notes

# Appel de méthode et paramètres

/**
  * Saute vers un sous-dossier de notes
  *
  * @param noteSubFolderPath {QString} chemin du sous-dossier, relativement au dossier de notes
  * @param separator {QString} séparateur entre les parties du chemin, par défaut "/"
  * @return true si le saut a réussi
  */
bool ScriptingService::jumpToNoteSubFolder(const QString &noteSubFolderPath,
                                            QString separator);
1
2
3
4
5
6
7
8
9

# Exemple

// saute vers le sous-dossier de notes "un sous-dossier"
script.jumpToNoteSubFolder("un sous-dossier");

// saute vers le sous-dossier de notes "sub" à l'intérieur de "un sous-dossier"
script.jumpToNoteSubFolder("un sous-dossier/sub");
1
2
3
4
5

TIP

Vous pouvez créer un nouveau sous-dossier de notes dans le sous-dossier courant en appelant mainWindow.createNewNoteSubFolder.

# Affichage d'une boîte de message d'information

# Appel de méthode et paramètres

/**
  * Affiche une boîte de message d'information
  *
  * @param text
  * @param title (optional)
  */
void ScriptingService::informationMessageBox(QString text, QString title);
1
2
3
4
5
6
7

# Exemple

// affiche une boîte de message d'information
script.informationMessageBox ("Le texte que je veux afficher", "Un titre facultatif");
1
2

# Affichage d'une boîte de message de question

# Appel de méthode et paramètres

/**
  * Affiche une boîte de message de question
  *
  * Pour plus d'informations sur les boutons, voir :
  * https://doc.qt.io/qt-5/qmessagebox.html#StandardButton-enum
  *
  * @param text
  * @param title (facultatif)
  * Boutons @param boutons qui doivent être affichés (facultatif)
  * @param defaultButton bouton qui sera sélectionné par défaut (facultatif)
  * @return id du bouton enfoncé
  */
int ScriptingService :: questionMessageBox (
         Texte QString, titre QString, boutons int, int defaultButton);
1
2
3
4
5
6
7
8
9
10
11
12
13
14

# Exemple

// affiche une boîte de message de question avec un bouton "Appliquer" et un bouton "Aide"
// voir : https://doc.qt.io/qt-5/qmessagebox.html#StandardButton-enum
var result = script.questionMessageBox (
     "Le texte que je veux afficher", "Un titre facultatif", 0x01000000 | 0x02000000, 0x02000000);
script.log (résultat);
1
2
3
4
5

Pour plus d'informations sur les boutons voir StandardButton (opens new window).

Vous voudrez peut-être jeter un coup d'œil à l'exemple input-dialogs.qml (opens new window).

# Affichage d'une boîte de dialogue d'ouverture de fichier

# Appel de méthode et paramètres

/**
  * Affiche une boîte de dialogue d'ouverture de fichier
  *
  * @param caption (facultatif)
  * @param dir (facultatif)
  * @param filter (facultatif)
  * @return QString
  */
QString ScriptingService :: getOpenFileName (légende QString, répertoire QString,
                                             Filtre QString);
1
2
3
4
5
6
7
8
9
10

# Exemple

// affiche une boîte de dialogue d'ouverture de fichier
var fileName = script.getOpenFileName("Veuillez choisir une image", "/home/user/images", "Images (*.png *.xpm *.jpg)");
1
2

# Affichage d'une boîte de dialogue d'enregistrement de fichier

# Appel de méthode et paramètres

/**
  * Affiche une boîte de dialogue d'enregistrement de fichier
  *
  * @param caption (facultatif)
  * @param dir (facultatif)
  * @param filter (facultatif)
  * @return QString
  */
QString ScriptingService::getSaveFileName (légende QString, répertoire QString,
                                             Filtre QString);
1
2
3
4
5
6
7
8
9
10

# Exemple

// affiche une boîte de dialogue d'enregistrement de fichier
var fileName = script.getSaveFileName ("Veuillez sélectionner le fichier HTML à enregistrer", "output.html", "HTML (*.html)");
1
2

Vous voudrez peut-être jeter un coup d'œil à l'exemple export-notes-as-one-html.qml (opens new window).

# Enregistrement des variables de paramètres de script

Vous devez définir vos variables de paramètres en tant que propriétés dans votre script et les enregistrer dans une propriété nommée settingsVariables.

L'utilisateur peut ensuite définir ces propriétés dans les paramètres du script.

# Exemple

// vous devez définir les variables enregistrées pour pouvoir y accéder plus tard
property string myString;
property bool myBoolean;
property string myText;
property int myInt;
property string myFile;
property string mySelection;

// enregistrez vos variables de paramètres pour que l'utilisateur puisse les définir dans les paramètres du script
//
// il n'y a malheureusement pas de QVariantHash dans Qt, nous pouvons seulement utiliser
// QVariantMap (qui n'a pas de classement arbitraire) or QVariantList (qui
// peut être ordonné arbitrairement)
property variant settingsVariables: [
    {
        "identifier": "myString",
        "name": "Je suis une édition de ligne",
        "description": "Veuillez entrer une chaîne valide :",
        "type": "string",
        "default": "Ma valeur par défaut",
    },
    {
        "identifier": "myBoolean",
        "name": "Je suis une case à cocher",
        "description": "Une description",
        "text": "Cochez cette case",
        "type": "boolean",
        "default": true,
    },
    {
        "identifier": "myText",
        "name": "Je suis une boîte de texte",
        "description": "Veuillez entrer votre texte :",
        "type": "text",
        "default": "Ceci peut être un très long texte \navec plusieurs lignes.",
    },
    {
        "identifier": "myInt",
        "name": "Je suis un sélecteur de chiffres",
        "description": "Veuillez entrer un chiffre :",
        "type": "integer",
        "default": 42,
    },
    {
        "identifier": "myFile",
        "name": "Je suis un sélecteur de fichiers",
        "description": "Veuillez sélectionner un fichier :",
        "type": "file",
        "default": "pandoc",
    },
    {
        "identifier": "mySelection",
        "name": "Je suis un sélecteur d'éléments",
        "description": "Veuillez sélectionner un élément:",
        "type": "selection",
        "default": "option2",
        "items": {"option1": "Texte pour option 1", "option2": "Texte pour option 2", "option3": "Texte pour option 3"},
    }
];
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59

De plus, vous pouvez outrepasser les settingsVariables avec une fonction spéciale registerSettingsVariables () comme ceci :

# Exemple

/**
 *Enregistre à nouveau les variables de paramètres
 *
 *Utilisez cette méthode si vous souhaitez utiliser du code pour outrepasser vos variables, telles que le réglage
 *des valeurs par défaut dépendant du système d'exploitation.
 */
function registerSettingsVariables() {
    if (script.platformIsWindows()) {
        // outrepasser la valeur par défaut de monFichier
        settingsVariables[3].default = "pandoc.exe"
    }
}
1
2
3
4
5
6
7
8
9
10
11
12

Vous voudrez peut-être jeter un coup d'œil à l'exemple variables.qml (opens new window).

# Stockage et chargement de variables persistantes

# Appel de méthode et paramètres

/**
 * Stocke une variable persistante
 * Ces variables sont accessibles globalement par l'ensemble des scripts
 * Veuillez utiliser des préfixes explicites dans votre clé comme "PersistentVariablesTest/myVar"
 *
 * @param key {QString}
 * @param value {QVariant}
 */
void ScriptingService::setPersistentVariable(const QString &key,
                                                const QVariant &value);

/**
 * Charge une variable persistante
 * Ces variables sont accessibles globalement par l'ensemble des scripts
 *
 * @param key {QString}
 * @param defaultValue {QVariant} retourner valeur si le paramètre n'existe pas (optionnel)
 * @return
 */
QVariant ScriptingService::getPersistentVariable(const QString &key,
                                                    const QVariant &defaultValue);
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

# Exemple

// stocker une variable persistante
script.setPersistentVariable("PersistentVariablesTest/myVar", result);

// charger et consigner une variable persistante
script.log(script.getPersistentVariable("PersistentVariablesTest/myVar", "rien ici pour le moment"));
1
2
3
4
5

Veuillez vous assurer d'utiliser un préfixe explicite dans votre clé, tel que PersistentVariablesTest / myVar car les variables sont accessibles depuis tous les scripts.

Vous voudrez peut-être également jeter un coup d'œil à l'exemple persistent-variables.qml (opens new window).

# Chargement des variables de paramètres d'application

# Appel de méthode et paramètres

/**
 * Charger une variable de paramètres d'application
 *
 * @param key {QString}
 * @param defaultValue {QVariant} retourne valeur si le paramètre n'existe pas (optionnel)
 * @return
 */
QVariant ScriptingService::getApplicationSettingsVariable(const QString &key,
                                                            const QVariant &defaultValue);
1
2
3
4
5
6
7
8
9

# Exemple

// charger et enregistrer une variable de paramètres d'application
script.log (script.getApplicationSettingsVariable ("gitExecutablePath"));
1
2

Gardez à l'esprit que les paramètres peuvent être vides, vous devez vous en occuper vous-même. defaultValue n'est utilisé que si le paramètre n'existe nulle part.

# Créer un répertoire cache

Vous pouvez mettre en cache des fichiers à l'emplacement de cache par défaut de votre système.

# Appel de méthode et paramètres

/**
 * Renvoie un répertoire de cache pour un script
 *
 * @param {QString} subDir le sous-dossier à créer et à utiliser
 * @return {QString} le chemin du répertoire cache
 */
QString ScriptingService :: cacheDir (const QString & subDir) const;
1
2
3
4
5
6
7

# Exemple

// crée le répertoire cache pour mon-id-de-script
var cacheDirForScript = script.cacheDir ("mon-id-de-script");
1
2

# Vider un répertoire cache

Vous pouvez vider le répertoire cache de votre script en passant son nom à clearCacheDir().

# Appel de méthode et paramètres

/**
 * Vide le répertoire cache pour un script
 *
 * @param {QString} subDir le sous-dossier à vider
 * @return {bool} true en cas de succès
 */
bool ScriptingService :: clearCacheDir (const QString & subDir) const;
1
2
3
4
5
6
7

# Exemple

// vider le répertoire cache de mon-id-de-script 
script.clearCacheDir("mon-id-de-script ");
1
2

# Lire le chemin d'accès au répertoire de votre script

Si vous avez besoin d'obtenir le chemin d'accès au répertoire où votre script est placé pour, par exemple, charger d'autres fichiers, vous devez enregistrer une chaîne de propriété scriptDirPath;. Cette propriété sera définie avec le chemin d'accès au répertoire du script.

# Exemple

import QtQml 2.0
import QOwnNotesTypes 1.0

Script {
    // le chemin d'accès au répertoire du script est défini ici
    property string scriptDirPath;

    function init() {
        script.log(scriptDirPath);
    }
}
1
2
3
4
5
6
7
8
9
10
11

# Conversion des séparateurs de chemin en séparateurs natifs

# Appel de méthode et paramètres

/**
 * Renvoie le chemin avec les séparateurs '/' convertis en séparateurs
 * appropriés au système d'exploitation sous-jacent.
 *
 * Sous Windows, toNativeDirSeparators("c:/winnt/system32") retourne
 * "c:\winnt\system32".
 *
 * @param path
 * @return
 */
QString ScriptingService::toNativeDirSeparators(QString path);
1
2
3
4
5
6
7
8
9
10
11

# Exemple

// retournera "c:\winnt\system32" sous Windows
script.log(script.toNativeDirSeparators("c:/winnt/system32"));
1
2

# Conversion des séparateurs de chemin depuis des séparateurs natifs

# Appel de méthode et paramètres

/**
 * Renvoie le chemin en utilisant '/' comme séparateur de fichier.
 * Sous Windows par exemple, fromNativeDirSeparators("c:\\winnt\\system32")
 * renverra "c:/winnt/system32".
 *
 * @param path
 * @return
 */
QString ScriptingService::fromNativeDirSeparators(QString path);
1
2
3
4
5
6
7
8
9

# Exemple

// retournera "c:/winnt/system32" sous Windows
script.log(script.toNativeDirSeparators("c:\\winnt\\system32"));
1
2

# Obtenir le séparateur de répertoire natif

# Appel de méthode et paramètres

/**
 * Renvoie le séparateur de répertoire natif "/" ou "\" sous Windows
 *
 * @return
 */
QString ScriptingService::dirSeparator();
1
2
3
4
5
6

# Exemple

// renverra "\" sous Windows
script.log(script.dirSeparator());
1
2

# Obtenir une liste des chemins d'accès de toutes les notes sélectionnées

# Appel de méthode et paramètres

/**
 * Renvoie une liste des chemins d'accès de toutes les notes sélectionnées
 *
 * @return {QStringList} liste des chemins d'accès de toutes les notes sélectionnées
 */
QStringList ScriptingService::selectedNotesPaths();
1
2
3
4
5
6

# Exemple

// renvoie une liste des chemins d'accès de toutes les notes sélectionnées
script.log(script.selectedNotesPaths());
1
2

Vous voudrez peut-être jeter un coup d'œil à l'exemple external-note-diff.qml (opens new window).

# Obtenir une liste des identifiants de toutes les notes sélectionnées

# Appel de méthode et paramètres

/**
 * Renvoie une liste des identifiants de toutes les notes sélectionnées
 *
 * @return {QList <int>} liste des identifiants de note sélectionnés
 */
QList<int> ScriptingService::selectedNotesIds();
1
2
3
4
5
6

# Exemple

// renvoie une liste des identifiants de toutes les notes sélectionnées
script.log(script.selectedNotesIds());
1
2

Vous voudrez peut-être jeter un coup d'œil à l'exemple export-notes-as-one-html.qml (opens new window).

# Déclencher une action de menu

# Appel de méthode et paramètres

/**
  * Déclenche une action de menu
  *
  * @param objectName {QString} nom d'objet de l'action à déclencher
  * @param vérifié {QString} ne déclenche l'action que si l'état vérifié est
  * différent de ce paramètre (facultatif, peut être 0 ou 1)
  */
void ScriptingService::triggerMenuAction(QString objectName, QString checked);
1
2
3
4
5
6
7
8

# Exemple

// basculer en mode lecture seule
script.triggerMenuAction ("actionAllow_note_editing");

// désactiver le mode lecture seule
script.triggerMenuAction ("actionAllow_note_editing", 1);
1
2
3
4
5

Vous voudrez peut-être jeter un coup d'œil à l'exemple disable-readonly-mode.qml (opens new window).

TIP

Vous pouvez obtenir les noms d'objet de l'action de menu à partir de mainwindow.ui (opens new window). Recherchez simplement le titre du menu en anglais. Notez que ces textes peuvent changer avec le temps.

# Ouverture d'une boîte de dialogue de saisie avec une boîte de sélection

# Appel de méthode et paramètres

/**
  * Ouvre une boîte de dialogue de saisie avec une boîte de sélection
  *
  * @param title {QString} titre de la boîte de dialogue
  * @param label {QString} texte de l'étiquette de la boîte de dialogue
  * @param items {QStringList} liste des éléments à sélectionner
  * @param current {int} index de l'élément à sélectionner (par défaut : 0)
  * @param editable {bool} si true, le texte de la boîte de dialogue peut être édité (par défaut : false)
  * @return {QString} texte de l'élément sélectionné
  */
QString ScriptingService :: inputDialogGetItem (
         const QString & title, const QString & label, const QStringList & items,
         int courant, booléen modifiable);
1
2
3
4
5
6
7
8
9
10
11
12
13

# Exemple

var result = script.inputDialogGetItem(
    "combo box", "Veuillez sélectionner un élément", ["Élément 1", "Élément 2", "Élément 3"]);
script.log(result);
1
2
3

Vous voudrez peut-être jeter un coup d'œil à l'exemple input-dialogs.qml (opens new window).

# Ouverture d'une boîte de dialogue de saisie avec une modification de ligne

# Appel de méthode et paramètres

/ **
  * Ouvre une boîte de dialogue de saisie avec une modification de ligne
  *
  * @param title {QString} titre de la boîte de dialogue
  * @param label {QString} texte de l'étiquette de la boîte de dialogue
  * @param text {QString} texte dans la boîte de dialogue (facultatif)
  * @ return
 */
QString ScriptingService::inputDialogGetText(
        const QString &title, const QString &label, const QString &text);
1
2
3
4
5
6
7
8
9
10

# Exemple

var result = script.inputDialogGetText(
    "édition de ligne", "Veuillez entrer un nom", "texte actuel");
script.log(result);
1
2
3

# Vérifier si un fichier existe

# Appel de méthode et paramètres

/**
 * Vérifier si un fichier existe
 * @param filePath
 * @return
 */
bool ScriptingService::fileExists(QString &filePath);
1
2
3
4
5
6

# Exemple

var result = script.fileExists(filePath);
script.log(result);
1
2

# Lire du texte à partir d'un fichier

# Appel de méthode et paramètres

/**
 * Lire du texte à partir d'un fichier
 *
 * @param filePath {QString} chemin d'accès du fichier à charger
 * @param codec {QString} encodage du fichier (par défaut : UTF-8)
 * @return les données contenues dans le fichier ou 'null' si le fichier n'existe pas
 */
QString ScriptingService::readFromFile(const QString &filePath, const QString &codec)
1
2
3
4
5
6
7
8

# Exemple

if(script.fileExists(filePath)){
    var data = script.readFromFile(filePath);
    script.log(data);
}
1
2
3
4

# Écrire du texte dans un fichier

# Appel de méthode et paramètres

/**
 * Écrire du texte dans un fichier
 *
 * @param filePath {QString}
 * @param data {QString}
 * @param createParentDirs {bool} otionnel (par défaut : false)
 * @return
 */
bool ScriptingService::writeToFile(const QString &filePath, const QString &data, bool createParentDirs);
1
2
3
4
5
6
7
8
9

# Exemple

var result = script.writeToFile(filePath, html);
script.log(result);
1
2

Vous voudrez peut-être jeter un coup d'œil à l'exemple export-notes-as-one-html.qml (opens new window).

# Travailler avec des Websockets

Vous pouvez contrôler QOwnNotes à distance en utilisant WebSocketServer.

Veuillez jeter un œil à l'exemple websocket-server.qml (opens new window). Vous pouvez tester le serveur de sockets en vous y connectant sur Websocket test (opens new window).

Vous pouvez également écouter les sockets avec WebSocket. Veuillez jeter un œil à l'exemple websocket-client.qml (opens new window).

Gardez à l'esprit que vous devez avoir la bibliothèque QML websocket de Qt installée pour utiliser cette fonction. Par exemple, sous Ubuntu Linux vous pouvez installer module-qml-qtwebsockets.

# Ajout d'une règle de mise en évidence pour l'éditeur

Il est possible d'injecter des règles de mise en évidence directement dans l'éditeur en définissant et assignant des expressions régulières à un état de mise en évidence.

# Appel de méthode et paramètres

/**
 * Ajout d'une règle de mise en évidence au surligneur de syntaxe de l'éditeur
 *
 * @param pattern {QString} le motif d'expression régulière à mettre en évidence
 * @param shouldContain {QString} une chaîne qui doit être contenue dans le texte mis en évidence pour que le motif soit analysé syntaxiquement
 * @param state {int} l'état du surligneur de syntaxe à utiliser
 * @param capturingGroup {int} le groupe de capture du motif à utiliser pour la mise en évidence (par défaut : 0)
 * @param maskedGroup {int} le groupe de capture du motif à utiliser pour la mise en évidence (par défault : 0)
 */
void ScriptingService::addHighlightingRule(const QString &pattern,
                                           const QString &shouldContain,
                                           int state,
                                           int capturingGroup,
                                           int maskedGroup);
1
2
3
4
5
6
7
8
9
10
11
12
13
14

# États de mise en évidence

Nom Numéro
NoState -1
Lien 0
Image 3
CodeBlock 4
CodeBlockComment 5
Italic 7
Gras 8
List 9
Commentaire 11
H1 12
H2 13
H3 14
H4 15
H5 16
H6 17
BlockQuote 18
HorizontalRuler 21
Table 22
InlineCodeBlock 23
MaskedSyntax 24
CurrentLineBackgroundColor 25
BrokenLink 26
FrontmatterBlock 27
TrailingSpace 28
CheckBoxUnChecked 29
CheckBoxChecked 30
StUnderline 31

# Exemple

// Highlight a text line like "BLOCK: some text" as blockquote (state 18)
script.addHighlightingRule("^BLOCK: (.+)", "BLOCK:", 18);

// Mask out (state 24) all characters after 32 characters in a line
// capturingGroup 1 means the expression from the first bracketed part of the pattern will be highlighted
// maskedGroup -1 means that no masking should be done
script.addHighlightingRule("^.{32}(.+)", "", 24, 1, -1);
1
2
3
4
5
6
7

You can also take a look at the examples in highlighting.qml (opens new window).