# 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 de l'exécutable
  * @param parameters une liste de chaînes de paramètres
  * @param callbackIdentifier un identifiant à utiliser dans la fonction onDetachedProcessCallback () (optionnel)
  * @param callbackParameter un paramètre supplémentaire pour les boucles ou autres (facultatif)
  * @param processData données écrites dans le processus si le rappel est utilisé (facultatif)
  * @return true en cas de succès, false sinon
  * /
bool startDetachedProcess (QString executablePath, paramètres QStringList,
                             QString callbackIdentifier, QVariant callbackParameter,
                             QByteArray processData);
1
2
3
4
5
6
7
8
9
10
11
12
13

# Exemple

Exemple simple:

script.startDetachedProcess("/path/to/my/program", ["my parameter"]);
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 à l'exemple custom-actions.qml (opens new window), callback.qml (opens new window) ou exécution-commande-après-note-update.qml (opens new window).

Vous pouvez également consulter le hook onDetachedProcessCallback.

TIP

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

# 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 de l'exécutable
  * @param parameters une liste de chaînes de paramètres
  * @param data les données qui seront écrites dans le processus (facultatif)
  * @return le texte qui a été renvoyé par le processus
QByteArray startSynchronousProcess(QString executablePath, QStringList parameters, QByteArray data);
1
2
3
4
5
6
7
8

# Exemple

var result = script.startSynchronousProcess("/path/to/my/program", ["my parameter"], "data");
1

Vous pouvez 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 actuelle
  *
  * @returns {NoteApi} l'objet de note actuel
  */
NoteApi currentNote ();
1
2
3
4
5
6

# Exemple

var note = script.currentNote();
1

Vous pouvez jeter un œ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("my text");
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 pouvez jeter un œ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 support
  * url ou le texte de l'image de démarque du média par rapport à la note actuelle
  *
  * @param {QString} url
  * @param {bool} returnUrlOnly si true, seule l'url du 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 pouvez jeter un œ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 multimédia et retourner
  * l'url du média ou le texte de l'image de démarque du média par rapport à 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("/path/to/your/image.png");
1

Vous pouvez jeter un œil à l'exemple scribble.qml (opens new window).

# Inserting an attachment file into the attachments folder

# Appel de méthode et paramètres

 * QML wrapper to insert an attachment file into the `attachments` folder and
 * returning the attachment url or the markdown text of the attachment
 * relative to the current note
 *
 * @param {QString} attachmentFilePath
 * @param {QString} fileName to use in the markdown
 * @param {bool} returnUrlOnly if true only the attachment url will be returned
 * (default false)
 * @return {QString} the attachment markdown or url
 */
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("/path/to/your/file.png");
1

# Regenerating the note preview

Actualise l'aperçu de la note.

# Appel de méthode et paramètres

/**
 * Regenerates the note preview
 */
QString ScriptingService::regenerateNotePreview();
1
2
3
4

# Exemple

script.regenerateNotePreview();
1

Vous pouvez jeter un œil à l'exemple scribble.qml (opens new window).

# Registering a custom action

# Appel de méthode et paramètres

/**
 * Registers a custom action
 *
 * @param identifier the identifier of the action
 * @param menuText the text shown in the menu
 * @param buttonText the text shown in the button
 *                   (no button will be viewed if empty)
 * @param icon the icon file path or the name of a freedesktop theme icon
 *             you will find a list of icons here:
 *             https://specifications.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html
 * @param useInNoteEditContextMenu if true use the action in the note edit
 *                                 context menu (default: false)
 * @param hideButtonInToolbar if true the button will not be shown in the
 *                            custom action toolbar (default: false)
 * @param useInNoteListContextMenu if true use the action in the note list
 *                                 context menu (default: 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

# Exemple

// add a custom action without a button
script.registerCustomAction("mycustomaction1", "Menu text");

// add a custom action with a button
script.registerCustomAction("mycustomaction1", "Menu text", "Button text");

// add a custom action with a button and freedesktop theme icon
script.registerCustomAction("mycustomaction1", "Menu text", "Button text", "task-new");

// add a custom action with a button and an icon from a file
script.registerCustomAction("mycustomaction1", "Menu text", "Button text", "/usr/share/icons/breeze/actions/24/view-calendar-tasks.svg");
1
2
3
4
5
6
7
8
9
10
11

Vous pouvez ensuite utiliser l'identifiant avec la fonction customActionInvoked dans un script comme 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'informations, veuillez consulter Déclencher des actions de menu après le démarrage.

# Registering a label

# Appel de méthode et paramètres

/**
 * Registers a label to write to
 *
 * @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> HTML text<br />with three lines<br />and a <a href='https://www.qownnotes.org'>link to a website</a>.");

script.registerLabel("long-label", "another very long text, another very long text, another very long text, another very long text, another very long text, another very long text, another very long text, another very long text, another very long text, another very long text, another very long text that will wrap");

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

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

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 pouvez ensuite jeter un œil à l'exemple de script scripting-label-demo.qml (opens new window).

# Setting the text of a registered label

# Appel de méthode et paramètres

/**
 * Sets the text of a registered label
 *
 * @param identifier the identifier of the label
 * @param text the text shown in the label
 */
void ScriptingService::setLabelText(QString identifier, QString text);
1
2
3
4
5
6
7

# Exemple

script.setLabelText("counter-label", "counter text");
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 pouvez ensuite jeter un œil à l'exemple de script scripting-label-demo.qml (opens new window).

# Creating a new note

# Appel de méthode et paramètres

/**
 * Creates a new note
 *
 * @param text the note text
 */
void ScriptingService::createNote(QString text);
1
2
3
4
5
6

# Exemple

script.createNote("My note headline\n===\n\nMy text");
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 devez renommer votre fichier de note vous-même par la suite, comme ceci:

var note = script.currentNote();
note.renameNoteFile('your-filename');
1
2

# Accessing the clipboard

# Appel de méthode et paramètres

/**
 * Returns the content of the clipboard as text or html
 *
 * @param asHtml returns the clipboard content as html instead of text
 */
QString ScriptingService::clipboard(bool asHtml);
1
2
3
4
5
6

# Exemple

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

Vous pouvez jeter un œil à l'exemple custom-actions.qml (opens new window).

# Write text to the note text edit

# Appel de méthode et paramètres

/**
 * Writes text to the current cursor position in the note text edit
 *
 * @param text
 */
void ScriptingService::noteTextEditWrite(QString text);
1
2
3
4
5
6

# Exemple

// write text to the note text edit
script.noteTextEditWrite("My custom text");
1
2

Vous voudrez peut-être regarder l'action personnalisée transformTextRot13 dans le exemple custom-actions.qml (opens new window).

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

# Read the selected text in the note text edit

# Appel de méthode et paramètres

/**
 * Reads the selected text in the note text edit
 *
 * @return
 */
QString ScriptingService::noteTextEditSelectedText();
1
2
3
4
5
6

# Exemple

// read the selected text from the note text edit
var text = script.noteTextEditSelectedText();
1
2

Vous voudrez peut-être regarder l'action personnalisée transformTextRot13 dans le exemple custom-actions.qml (opens new window).

# Select all text in the note text edit

# Appel de méthode et paramètres

/**
 * Selects all text in the note text edit
 */
void ScriptingService::noteTextEditSelectAll();
1
2
3
4

# Exemple

script.noteTextEditSelectAll();
1

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

# Select the current line in the note text edit

# Appel de méthode et paramètres

/**
 * Selects the current line in the note text edit
 */
void ScriptingService::noteTextEditSelectCurrentLine();
1
2
3
4

# Exemple

script.noteTextEditSelectCurrentLine();
1

# Select the current word in the note text edit

# Appel de méthode et paramètres

/**
 * Selects the current line in the note text edit
 */
void ScriptingService::noteTextEditSelectCurrentWord();
1
2
3
4

# Exemple

script.noteTextEditSelectCurrentWord();
1

# Set the currently selected text in the note text edit

# Appel de méthode et paramètres

/**
 * Sets the currently selected text in the note text edit
 *
 * @param start
 * @param end
 */
void ScriptingService::noteTextEditSetSelection(int start, int end);
1
2
3
4
5
6
7

# Exemple

// expands the current selection by one character
script.noteTextEditSetSelection(
    script.noteTextEditSelectionStart() - 1,
    script.noteTextEditSelectionEnd() + 1);
1
2
3
4

# Get the start position of the current selection in the note text edit

# Appel de méthode et paramètres

/**
 * Returns the start position of the current selection in the note text edit
 */
int ScriptingService::noteTextEditSelectionStart();
1
2
3
4

# Exemple

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

# Get the end position of the current selection in the note text edit

# Appel de méthode et paramètres

/**
 * Returns the end position of the current selection in the note text edit
 */
int ScriptingService::noteTextEditSelectionEnd();
1
2
3
4

# Exemple

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

# Set the text cursor in the note text edit to a certain position

# Appel de méthode et paramètres

/**
 * Sets the text cursor in the note text edit to a certain position
 * 0 would be the beginning of the note
 * special case: -1 would be the end of the note
 *
 * @param position
 */
void ScriptingService::noteTextEditSetCursorPosition(int position);
1
2
3
4
5
6
7
8

# Exemple

// jump to the 11th character in the note
script.noteTextEditSetCursorPosition(10);

// jump to the end of the note
script.noteTextEditSetCursorPosition(-1);
1
2
3
4
5

# Get the current position of the text cursor in the note text edit

# Appel de méthode et paramètres

/**
 * Returns the current position of the text cursor in the note text edit
 * 0 would be the beginning of the note
 */
int ScriptingService::noteTextEditCursorPosition();
1
2
3
4
5

# Exemple

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

# Read the current word from the note text edit

# Appel de méthode et paramètres

/**
 * Reads the current word in the note text edit
 *
 * @param withPreviousCharacters also get more characters at the beginning
 *                               to get characters like "@" that are not
 *                               word-characters
 * @return
 */
QString ScriptingService::noteTextEditCurrentWord(bool withPreviousCharacters);
1
2
3
4
5
6
7
8
9

# Exemple

// read the current word in the note text edit
var text = script.noteTextEditCurrentWord();
1
2

Vous pouvez jeter un œil à l'exemple autocompletion.qml (opens new window).

# Check whether platform is Linux, OS X or Windows

# Appel de méthode et paramètres

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

# Exemple

if (script.platformIsLinux()) {
    // only will be executed if under Linux
}
1
2
3

# Tag the current note

# Appel de méthode et paramètres

/**
 * Tags the current note with a tag named tagName
 *
 * @param tagName
 */
void ScriptingService::tagCurrentNote(QString tagName);
1
2
3
4
5
6

# Exemple

// add a "favorite" tag to the current note
script.tagCurrentNote("favorite");
1
2

Vous souhaiterez peut-être consulter l'action personnalisée favoriteNote dans l'exemple favorite-note.qml (opens new window).

# Create or fetch a tag by its name breadcrumb list

# Appel de méthode et paramètres

/**
 * Fetches or creates a tag by its "breadcrumb list" of tag names
 * Element nameList[0] would be highest in the tree (with parentId: 0)
 *
 * @param nameList
 * @param createMissing {bool} if true (default) all missing tags will be created
 * @return TagApi object of deepest tag of the name breadcrumb list
 */
TagApi *ScriptingService::getTagByNameBreadcrumbList(
    const QStringList &nameList, bool createMissing);
1
2
3
4
5
6
7
8
9
10

# Exemple

// creates all tags until the 3rd level and returns the tag object for
// tag "level3", which would look like that in the tag tree:
// level1 > level2 > level3
var tag = script.getTagByNameBreadcrumbList(["level1", "level2", "level3"]);
1
2
3
4

# Search for tags by name

# Appel de méthode et paramètres

/**
 * Fetches all tags by doing a substring search on the name field
 *
 * @param name {QString} name to search for
 * @return {QStringList} list of tag names
 */
QStringList ScriptingService::searchTagsByName(QString name);
1
2
3
4
5
6
7

# Exemple

// searches for all tags with the word game in it
var tags = script.searchTagsByName("game");
1
2

Vous pouvez jeter un œil à l'exemple autocompletion.qml (opens new window).

# Search for notes by note text

# Appel de méthode et paramètres

/**
 * Returns a list of note ids of all notes with a certain text in the note text
 *
 * Unfortunately there is no easy way to use a QList<NoteApi*> in QML, so we
 * can only transfer the note ids
 *
 * @return {QList<int>} list of note ids
 */
QList<int> ScriptingService::fetchNoteIdsByNoteTextPart(QString text);
1
2
3
4
5
6
7
8
9

# Exemple

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

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

    // do something with the note
});
1
2
3
4
5
6
7

Vous pouvez jeter un œil à l'exemple unique-note-id.qml (opens new window).

# Add a custom stylesheet

# Appel de méthode et paramètres

/**
 * Adds a custom stylesheet to the application
 *
 * @param stylesheet
 */
void ScriptingService::addStyleSheet(QString stylesheet);
1
2
3
4
5
6

# Exemple

// make the text in the note list bigger
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).

You can get the widget names from the *.ui files, for example the main window is mainwindow.ui (opens new window).

The Qt documentation (for example QMainWindow (opens new window)) can help you to see how the widgets are related to each other (search for Inherits on the pages).

The base widget for almost everything is QWidget (opens new window). So just styling QWidget with for example QWidget {background-color: black; color: white;} would mean everything has a black background color and a white foreground color.

TIP

The style.qss (opens new window) of qdarkstyle (opens new window) might also be a good reference for styles you can change.

Take a look at Style Sheet Reference (opens new window) for a reference of what styles are available.

If you want to inject styles into html preview to alter the way notes are previewed please look at notetomarkdownhtmlhook.

TIP

If you actually want to see how the dialogs look and what the names are you could download Qt Creator (opens new window) and open the *.ui files in it.

# 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

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

// check if note exists, but ignore the id of "note"
script.noteExistsByFileName("my note.md", note.id);
1
2

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

# Copying text into the clipboard

# Appel de méthode et paramètres

/**
 * Copies text into the clipboard as plain text or html mime data
 *
 * @param text string text to put into the clipboard
 * @param asHtml bool if true the text will be set as html mime data
 */
void ScriptingService::setClipboardText(QString text, bool asHtml);
1
2
3
4
5
6
7

# Exemple

// copy text to the clipboard
script.setClipboardText("text to copy");
1
2

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

# Passer à une note

# Appel de méthode et paramètres

/**
 * Sets the current note if the note is visible in the note list
 *
 * @param note NoteApi note to jump to
 */
void ScriptingService::setCurrentNote(NoteApi *note);
1
2
3
4
5
6

# Exemple

// jump to the note
script.setCurrentNote(note);
1
2

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

# Jumping to a note subfolder

# Appel de méthode et paramètres

/**
 * Jumps to a note subfolder
 *
 * @param noteSubFolderPath {QString} path of the subfolder, relative to the note folder
 * @param separator {QString} separator between parts of the path, default "/"
 * @return true if jump was successful
 */
bool ScriptingService::jumpToNoteSubFolder(const QString &noteSubFolderPath,
                                            QString separator);
1
2
3
4
5
6
7
8
9

# Exemple

// jump to the note subfolder "a sub folder"
script.jumpToNoteSubFolder("a sub folder");

// jump to the note subfolder "sub" inside of "a sub folder"
script.jumpToNoteSubFolder("a sub folder/sub");
1
2
3
4
5

TIP

You can create a new note subfolder in the current subfolder by calling 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

// show a information message box
script.informationMessageBox("The text I want to show", "Some optional title");
1
2

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

# Appel de méthode et paramètres

/**
 * Shows a question message box
 *
 * For information about buttons see:
 * https://doc.qt.io/qt-5/qmessagebox.html#StandardButton-enum
 *
 * @param text
 * @param title (optional)
 * @param buttons buttons that should be shown (optional)
 * @param defaultButton default button that will be selected (optional)
 * @return id of pressed button
 */
int ScriptingService::questionMessageBox(
        QString text, QString title, int buttons, int defaultButton);
1
2
3
4
5
6
7
8
9
10
11
12
13
14

# Exemple

// show a question message box with an apply and a help button
// see: https://doc.qt.io/qt-5/qmessagebox.html#StandardButton-enum
var result = script.questionMessageBox(
    "The text I want to show", "Some optional title", 0x01000000|0x02000000, 0x02000000);
script.log(result);
1
2
3
4
5

For information about buttons see StandardButton (opens new window).

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

# Showing an open file dialog

# Appel de méthode et paramètres

/**
 * Shows an open file dialog
 *
 * @param caption (optional)
 * @param dir (optional)
 * @param filter (optional)
 * @return QString
 */
QString ScriptingService::getOpenFileName(QString caption, QString dir,
                                            QString filter);
1
2
3
4
5
6
7
8
9
10

# Exemple

// show an open file dialog
var fileName = script.getOpenFileName("Please select an image", "/home/user/images", "Images (*.png *.xpm *.jpg)");
1
2

# Showing a save file dialog

# Method call and parameters

/**
 * Shows a save file dialog
 *
 * @param caption (optional)
 * @param dir (optional)
 * @param filter (optional)
 * @return QString
 */
QString ScriptingService::getSaveFileName(QString caption, QString dir,
                                            QString filter);
1
2
3
4
5
6
7
8
9
10

# Exemple

// show a save file dialog
var fileName = script.getSaveFileName("Please select HTML file to save", "output.html", "HTML (*.html)");
1
2

You may want to take a look at the example export-notes-as-one-html.qml (opens new window).

# Registering script settings variables

You need to define your settings variables as properties in your script and register them in a property named settingsVariables.

The user can then set these properties in the script settings.

# Example

// you have to define your registered variables so you can access them later
property string myString;
property bool myBoolean;
property string myText;
property int myInt;
property string myFile;
property string mySelection;

// register your settings variables so the user can set them in the script settings
// use this property if you don't need
//
// unfortunately there is no QVariantHash in Qt, we only can use
// QVariantMap (that has no arbitrary ordering) or QVariantList (which at
// least can be ordered arbitrarily)
property variant settingsVariables: [
    {
        "identifier": "myString",
        "name": "I am a line edit",
        "description": "Please enter a valid string:",
        "type": "string",
        "default": "My default value",
    },
    {
        "identifier": "myBoolean",
        "name": "I am a checkbox",
        "description": "Some description",
        "text": "Check this checkbox",
        "type": "boolean",
        "default": true,
    },
    {
        "identifier": "myText",
        "name": "I am textbox",
        "description": "Please enter your text:",
        "type": "text",
        "default": "This can be a really long text\nwith multiple lines.",
    },
    {
        "identifier": "myInt",
        "name": "I am a number selector",
        "description": "Please enter a number:",
        "type": "integer",
        "default": 42,
    },
    {
        "identifier": "myFile",
        "name": "I am a file selector",
        "description": "Please select the file:",
        "type": "file",
        "default": "pandoc",
    },
    {
        "identifier": "mySelection",
        "name": "I am an item selector",
        "description": "Please select an item:",
        "type": "selection",
        "default": "option2",
        "items": {"option1": "Text for option 1", "option2": "Text for option 2", "option3": "Text for 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
60

In addition you can override the settingsVariables with a special function registerSettingsVariables() like this:

# Exemple

/**
 * Registers the settings variables again
 *
 * Use this method if you want to use code to override your variables, like setting
 * default values depended on the operating system.
 */
function registerSettingsVariables() {
    if (script.platformIsWindows()) {
        // override the myFile default value
        settingsVariables[3].default = "pandoc.exe"
    }
}
1
2
3
4
5
6
7
8
9
10
11
12

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

# Storing and loading persistent variables

# Appel de méthode et paramètres

/**
 * 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);
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

# Exemple

// store persistent variable
script.setPersistentVariable("PersistentVariablesTest/myVar", result);

// load and log persistent variable
script.log(script.getPersistentVariable("PersistentVariablesTest/myVar", "nothing here yet"));
1
2
3
4
5

Please make sure to use a meaningful prefix in your key like PersistentVariablesTest/myVar because the variables are accessible from all scripts.

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

# Loading application settings variables

# Appel de méthode et paramètres

/**
 * 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);
1
2
3
4
5
6
7
8
9

# Exemple

// load and log an application settings variable
script.log(script.getApplicationSettingsVariable("gitExecutablePath"));
1
2

Keep in mind that settings actually can be empty, you have to take care about that yourself. defaultValue is only used if the setting doesn't exist at all.

# Creating a cache directory

You can cache files at the default cache location of your system.

# Appel de méthode et paramètres

/**
 * Returns a cache directory for a script
 *
 * @param {QString} subDir the subfolder to create and use
 * @return {QString} the cache dir path
 */
QString ScriptingService::cacheDir(const QString &subDir) const;
1
2
3
4
5
6
7

# Exemple

// create the cache directory for my-script-id
var cacheDirForScript = script.cacheDir("my-script-id");
1
2

# Clearing a cache directory

You can clear the cache files of your script by passing its name to clearCacheDir().

# Method call and parameters

/**
 * Clears the cache directory for a script
 *
 * @param {QString} subDir the subfolder to clear
 * @return {bool} true on success
 */
bool ScriptingService::clearCacheDir(const QString &subDir) const;
1
2
3
4
5
6
7

# Example

// clear cache directory of my-script-id 
script.clearCacheDir("my-script-id");
1
2

# Reading the path to the directory of your script

If you need to get the path to the directory where your script is placed to for example load other files you have to register a property string scriptDirPath;. This property will be set with the path to the script's directory.

# Exemple

import QtQml 2.0
import QOwnNotesTypes 1.0

Script {
    // the path to the script's directory will be set here
    property string scriptDirPath;

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

# Converting path separators to native ones

# Appel de méthode et paramètres

/**
 * Returns path with the '/' separators converted to separators that are
 * appropriate for the underlying operating system.
 *
 * On Windows, toNativeDirSeparators("c:/winnt/system32") returns
 * "c:\winnt\system32".
 *
 * @param path
 * @return
 */
QString ScriptingService::toNativeDirSeparators(QString path);
1
2
3
4
5
6
7
8
9
10
11

# Exemple

// will return "c:\winnt\system32" on Windows
script.log(script.toNativeDirSeparators("c:/winnt/system32"));
1
2

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

# Appel de méthode et paramètres

/**
 * Returns path using '/' as file separator.
 * On Windows, for instance, fromNativeDirSeparators("c:\\winnt\\system32")
 * returns "c:/winnt/system32".
 *
 * @param path
 * @return
 */
QString ScriptingService::fromNativeDirSeparators(QString path);
1
2
3
4
5
6
7
8
9

# Exemple

// will return "c:/winnt/system32" on Windows
script.log(script.fromNativeDirSeparators("c:\\winnt\\system32"));
1
2

# Getting the native directory separator

# Appel de méthode et paramètres

/**
 * Returns the native directory separator "/" or "\" on Windows
 *
 * @return
 */
QString ScriptingService::dirSeparator();
1
2
3
4
5
6

# Exemple

// will return "\" on Windows
script.log(script.dirSeparator());
1
2

# Getting a list of the paths of all selected notes

# Appel de méthode et paramètres

/**
 * Returns a list of the paths of all selected notes
 *
 * @return {QStringList} list of selected note paths
 */
QStringList ScriptingService::selectedNotesPaths();
1
2
3
4
5
6

# Exemple

// returns a list of the paths of all selected notes
script.log(script.selectedNotesPaths());
1
2

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

/**
 * Returns a list of the ids of all selected notes
 *
 * @return {QList<int>} list of selected note ids
 */
QList<int> ScriptingService::selectedNotesIds();
1
2
3
4
5
6

# Exemple

// returns a list of the ids of all selected notes
script.log(script.selectedNotesIds());
1
2

You may want to take a look at the example export-notes-as-one-html.qml (opens new window).

# Triggering a menu action

# Appel de méthode et paramètres

/**
 * Triggers a menu action
 *
 * @param objectName {QString} object name of the action to trigger
 * @param checked {QString} only trigger the action if checked-state is
 *                          different than this parameter (optional, can be 0 or 1)
 */
void ScriptingService::triggerMenuAction(QString objectName, QString checked);
1
2
3
4
5
6
7
8

# Exemple

// toggle the read-only mode
script.triggerMenuAction("actionAllow_note_editing");

// disable the read-only mode
script.triggerMenuAction("actionAllow_note_editing", 1);
1
2
3
4
5

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

TIP

You can get the object names of the menu action from mainwindow.ui (opens new window). Just search for the English menu title. Note that these texts can change over time.

# Opening an input dialog with a select box

# Appel de méthode et paramètres

/**
 * Opens an input dialog with a select box
 *
 * @param title {QString} title of the dialog
 * @param label {QString} label text of the dialog
 * @param items {QStringList} list of items to select
 * @param current {int} index of the item that should be selected (default: 0)
 * @param editable {bool} if true the text in the dialog can be edited (default: false)
 * @return {QString} text of the selected item
 */
QString ScriptingService::inputDialogGetItem(
        const QString &title, const QString &label, const QStringList &items,
        int current, bool editable);
1
2
3
4
5
6
7
8
9
10
11
12
13

# Exemple

var result = script.inputDialogGetItem(
    "combo box", "Please select an item", ["Item 1", "Item 2", "Item 3"]);
script.log(result);
1
2
3

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

# Opening an input dialog with a line edit

# Appel de méthode et paramètres

/**
 * Opens an input dialog with a line 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::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(
    "line edit", "Please enter a name", "current text");
script.log(result);
1
2
3

# Checking if a file exists

# Appel de méthode et paramètres

/**
 * Check if a file exists
 * @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

# Reading text from a file

# Appel de méthode et paramètres

/**
 * Read text from a file
 *
 * @param filePath {QString} path of the file to load
 * @param codec {QString} file encoding (default: UTF-8)
 * @return the file data or null if the file does not exist
 */
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

# Writing text to a file

# Method call and parameters

/**
 * Writes a text to a file
 *
 * @param filePath {QString}
 * @param data {QString}
 * @param createParentDirs {bool} optional (default: false)
 * @return
 */
bool ScriptingService::writeToFile(const QString &filePath, const QString &data, bool createParentDirs);
1
2
3
4
5
6
7
8
9

# Example

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

You may want to take a look at the example export-notes-as-one-html.qml (opens new window).

# Working with websockets

You can remote control QOwnNotes by using WebSocketServer.

Please take a look at the example websocket-server.qml (opens new window). You can test the socket server by connecting to it on Websocket test (opens new window).

You can also listen to sockets with WebSocket. Please take look at the example websocket-client.qml (opens new window).

Keep in mind that you need to have Qt's QML websocket library installed to use this. For example under Ubuntu Linux you can install qml-module-qtwebsockets.