# Metodi e oggetti forniti da QOwnNotes

# Avvio di un programma esterno in background

# Chiamata al metodo e parametri

/**
 * QML wrapper to start a detached process
 *
 * @param executablePath the path of the executable
 * @param parameters a list of parameter strings
 * @param callbackIdentifier an identifier to be used in the onDetachedProcessCallback() function (optional)
 * @param callbackParameter an additional parameter for loops or the like (optional)
 * @param processData data written to the process if the callback is used (optional)
 * @param workingDirectory the working directory to execute the process in (optional, only works without callback)
 * @return true on success, false otherwise
 */
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

# Esempio

Esempio semplice:

script.startDetachedProcess("/path/to/my/program", ["my parameter"]);
1

Esecuzione di molti processi:

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

Puoi dare un'occhiata all'esempio custom-actions.qml (opens new window), callback.qml (opens new window) o execute-command-after-note-update.qml (opens new window).

Potresti anche voler dare un'occhiata all'hook onDetachedProcessCallback.

# Avvio di un programma esterno e attesa dell'output

# Chiamata al metodo e parametri

/**
 * QML wrapper to start a synchronous process
 *
 * @param executablePath the path of the executable
 * @param parameters a list of parameter strings
 * @param data the data that will be written to the process (optional)
 * @param workingDirectory the working directory to execute the process in (optional)
 * @return the text that was returned by the process
QByteArray startSynchronousProcess(QString executablePath, QStringList parameters, QByteArray data, QString workingDirectory);
1
2
3
4
5
6
7
8
9

# Esempio

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

Puoi dare un'occhiata all'esempio encryption-keybase.qml (opens new window).

# Ottenere il percorso della cartella della nota corrente

# Chiamata al metodo e parametri

/**
 * Wrapper QML per ottenere il percorso della cartella della nota corrente
 *
 * @return il percorso della cartella della nota corrente
 */
QString currentNoteFolderPath();
1
2
3
4
5
6

# Esempio

var path = script.currentNoteFolderPath();
1

Puoi dare un'occhiata all'esempio absolute-media-links.qml (opens new window).

# Ottenere la nota corrente

# Chiamata al metodo e parametri

/**
 * QML wrapper to get the current note
 *
 * @returns {NoteApi} the current note object
 */
NoteApi currentNote();
1
2
3
4
5
6

# Esempio

var note = script.currentNote();
1

Puoi dare un'occhiata all'esempio custom-actions.qml (opens new window).

# Accesso al widget di registro

# Chiamata al metodo e parametri

/**
 * Wrapper QML per accedere al registro
 *
 * @param text
 */
void log(QString text);
1
2
3
4
5
6

# Esempio

script.log("my text");
1

# Download di un URL in una stringa

# Chiamata al metodo e parametri

/**
 * Wrapper QML per scaricare un url e ritornarlo come testo
 *
 * @param url
 * @return {QString} il contenuto del url  scaricato
 */
QString downloadUrlToString(QUrl url);
1
2
3
4
5
6
7

# Esempio

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

Puoi dare un'occhiata all'esempio insert-headline-with-link-from-github-url.qml (opens new window).

# Download di un URL nella cartella multimediale

# Chiamata al metodo e parametri

/**
  * Wrapper QML per scaricare un URL nella cartella multimediale e restituire il supporto
  * url o il testo dell'immagine di markdown del supporto relativo alla nota corrente
  *
  * URL @param {QString}
  * @param {bool} returnUrlOnly if true solo l'URL multimediale verrà restituito (valore predefinito false)
  * @return {QString} il markdown multimediale o l'URL
 */
QString downloadUrlToMedia(QUrl url, bool returnUrlOnly);
1
2
3
4
5
6
7
8
9

# Esempio

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

Puoi dare un'occhiata all'esempio paste-latex-image.qml (opens new window).

# Inserimento di un file multimediale nella cartella multimediale

# Chiamata al metodo e parametri

/**
  * QML wrapper per inserire un file multimediale nella cartella multimediale e tornare
  * l'URL del supporto o il testo dell'immagine di markdown del supporto relativo alla nota corrente
  *
  * @param {QString} mediaFilePath
  * @param {bool} returnUrlOnly se true solo l'URL multimediale verrà restituito (valore predefinito false)
  * @return {QString} il markdown multimediale o l'URL
1
2
3
4
5
6
7

# Esempio

var markdown = script.insertMediaFile("/percorso/del/tuo/file.png");
1

Puoi dare un'occhiata all'esempio scribble.qml (opens new window).

# Inserimento di un file allegato nella cartella allegati

# Chiamata al metodo e parametri

 * Wrapper QML per inserire un file allegato nella cartella
 * `attachments`e restituire l'URL dell'allegato o il testo markdown
 * dell'allegato relativi alla nota corrente
 *
 * @param {QString} attachmentFilePath
 * @param {QString} nome del file da usare nel markdown
 * @param {bool} returnUrlOnly se true sarà ritornato solo l'URL
 *                             dell'allegato (default false)
 * @return {QString} il markdown dell'allegato o l'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

# Esempio

var markdown = script.insertAttachmentFile("/percorso/del/tuo/file.png");
1

# Rigenerazione dell'anteprima della nota

Aggiorna l'anteprima della nota.

# Chiamata al metodo e parametri

/**
 * Rigenera l'anteprima della nota
 */
QString ScriptingService::regenerateNotePreview();
1
2
3
4

# Esempio

script.regenerateNotePreview();
1

Puoi dare un'occhiata all'esempio scribble.qml (opens new window).

# Registrazione di un'azione personalizzata

# Chiamata al metodo e parametri

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

TIP

Puoi anche assegnare scorciatoie locali e globali alle tue azioni personalizzate nelle Impostazioni dei collegamenti.

WARNING

Ricorda che le icone a tema freedesktop (opens new window) sono principalmente disponibili solo in Linux. Quindi se vuoi davvero usare un'icona in macOS o Windows, devi fornirne una col tuo script. Per fare in modo che il tuo script definisca un percorso corretto per la tua icona puoi usare la proprietà scriptDir.

# Esempio

import QtQml 2.0
import QOwnNotesTypes 1.0

Script {
    /**
     * Initializes the custom actions
     */
    function init() {
        // add a custom action without a button
        script.registerCustomAction("mycustomaction1", "Menu text");

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

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

        // add a custom action with a button and an icon from a file
        script.registerCustomAction("mycustomaction4", "Menu text", "Button text", "/usr/share/icons/breeze/actions/24/view-calendar-tasks.svg");
    }

    /**
     * This function is invoked when a custom action is triggered
     * in the menu or via button
     * 
     * @param identifier string the identifier defined in 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

Per altri esempi guarda custom-actions.qml (opens new window).

TIP

Puoi anche attivare un'azione personalizzata dopo che l'applicazione è stata avviata con il parametro --action customAction_<identifier>. Per maggiori informazioni dai un'occhiata a Attiva le azioni del menu dopo l'avvio.

# Registrazione di un'etichetta

# Chiamata al metodo e parametri

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

# Esempio

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

The labels will be visible in the scripting dock widget.

You can use both plain text or html in the labels. The text will be selectable and links can be clicked.

You may then want to take a look at the example script scripting-label-demo.qml (opens new window).

# Impostazione del testo di un'etichetta registrata

# Chiamata al metodo e parametri

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

# Esempio

script.setLabelText("counter-label", "counter text");
1

È possibile utilizzare sia testo normale che html nelle etichette. Il testo sarà selezionabile e sarà possibile fare clic sui collegamenti.

Potresti quindi voler dare un'occhiata allo script di esempio scripting-label-demo.qml (opens new window).

# Creazione di una nuova nota

# Chiamata al metodo e parametri

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

# Esempio

script.createNote("My note headline\n===\n\nMy text");
1

Puoi dare un'occhiata all'esempio custom-actions.qml (opens new window).

TIP

Se hai disattivato che il titolo della nota determina il nome del file della nota, devi rinominare il file della nota da solo in seguito, in questo modo:

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

# Accesso agli appunti

# Chiamata al metodo e parametri

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

# Esempio

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

Puoi dare un'occhiata all'esempio custom-actions.qml (opens new window).

# Scrivi il testo nella finestra di modifica del testo della nota

# Chiamata al metodo e parametri

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

# Esempio

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

Potresti voler esaminare l'azione personalizzata transformTextRot13 nel file esempio custom-actions.qml (opens new window).

Puoi usarlo insieme a noteTextEditSelectAll per sovrascrivere l'intero testo della nota corrente.

# Leggi il testo selezionato nella finestra di modifica del testo della nota

# Chiamata al metodo e parametri

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

# Esempio

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

Potresti voler esaminare l'azione personalizzata transformTextRot13 nel file esempio custom-actions.qml (opens new window).

# Seleziona tutto il testo nella finestra di modifica del testo della nota

# Chiamata al metodo e parametri

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

# Esempio

script.noteTextEditSelectAll();
1

Puoi usarlo insieme a noteTextEditWrite per sovrascrivere l'intero testo della nota corrente.

# Seleziona la riga corrente nella finestra di modifica del testo della nota

# Chiamata al metodo e parametri

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

# Esempio

script.noteTextEditSelectCurrentLine();
1

# Seleziona la parola corrente nella finestra di modifica del testo della nota

# Chiamata al metodo e parametri

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

# Esempio

script.noteTextEditSelectCurrentWord();
1

# Imposta il testo attualmente selezionato nella finestra di modifica del testo della nota

# Chiamata al metodo e parametri

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

# Esempio

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

# Ottieni la posizione iniziale della selezione corrente nella finestra di modifica del testo della nota

# Chiamata al metodo e parametri

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

# Esempio

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

# Ottieni la posizione finale della selezione corrente nella finestra di modifica del testo della nota

# Chiamata al metodo e parametri

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

# Esempio

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

# Impostare il cursore del testo nella finestra di modifica del testo della nota su una determinata posizione

# Chiamata al metodo e parametri

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

# Esempio

// salta all'undicesimo carattere nella nota
script.noteTextEditSetCursorPosition(10);

// salta alla fine della nota
script.noteTextEditSetCursorPosition(-1);
1
2
3
4
5

# Ottieni la posizione corrente del cursore del testo nella finestra di modifica del testo della nota

# Chiamata al metodo e parametri

/**
  * Restituisce la posizione corrente del cursore del testo nella finestra di modifica del testo della nota
  * 0 sarebbe l'inizio della nota
  */
int ScriptingService::noteTextEditCursorPosition();
1
2
3
4
5

# Esempio

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

# Leggi la parola corrente dalla finestra di modifica del testo della nota

# Chiamata al metodo e parametri

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

# Esempio

// legge la parola corrente dalla finestra di modifica del testo della nota
var text = script.noteTextEditCurrentWord();
1
2

Puoi dare un'occhiata all'esempio autocompletion.qml (opens new window).

# Controlla se la piattaforma è Linux, OS X o Windows

# Chiamata al metodo e parametri

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

# Esempio

if (script.platformIsLinux()) {
    // Verrà eseguito solo se sotto Linux
}
1
2
3

# Etichetta la nota corrente

# Chiamata al metodo e parametri

/**
  * Contrassegna la nota corrente con un'entichetta denominata tagName
  *
  * @param tagName
  */
void ScriptingService::tagCurrentNote(QString tagName);
1
2
3
4
5
6

# Esempio

// aggiungi un'etichetta "preferito" alla nota corrente
script.tagCurrentNote("preferito");
1
2

Potresti voler dare un'occhiata all'azione personalizzata favoriteNote nell'esempio favorite-note.qml (opens new window).

# Crea o recupera un'etichetta dal una lista di elementi

# Chiamata al metodo e parametri

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

# Esempio

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

# Cerca le etichette per nome

# Chiamata al metodo e parametri

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

# Esempio

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

Puoi dare un'occhiata all'esempio autocompletion.qml (opens new window).

# Cerca note in base al testo della nota

# Chiamata al metodo e parametri

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

# Esempio

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

Puoi dare un'occhiata all'esempio unique-note-id.qml (opens new window).

# Aggiungi un foglio di stile personalizzato

# Chiamata al metodo e parametri

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

# Esempio

// make the text in the note list bigger
script.addStyleSheet("QTreeWidget#noteTreeWidget {font-size: 30px;}");
1
2

Puoi dare un'occhiata all'esempio custom-stylesheet.qml (opens new window).

Puoi ottenere i nomi dei widget dai file *.ui, ad esempio la finestra principale è mainwindow.ui (opens new window).

La documentazione Qt (ad esempio QMainWindow (opens new window)) può aiutarti a vedere come sono correlati tra loro i widget (cerca Eredita nelle pagine).

Il widget di base per quasi tutto è 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.

Se vuoi inserire stili nell'anteprima HTML per modificare il modo in cui le note vengono visualizzate in anteprima, guarda notetomarkdownhtmlhook.

TIP

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

# Ricaricamento del motore di scripting

# Chiamata al metodo e parametri

/**
 * Reloads the scripting engine
 */
void ScriptingService::reloadScriptingEngine();
1
2
3
4

# Esempio

// reload the scripting engine
script.reloadScriptingEngine();
1
2

# Recupero di una nota in base al nome del file

# Chiamata al metodo e parametri

/**
 * Fetches a note by its file name
 *
 * @param fileName string the file name of the note (mandatory)
 * @param noteSubFolderId integer id of the note subfolder
 * @return NoteApi*
 */
NoteApi* ScriptingService::fetchNoteByFileName(QString fileName,
                                                int noteSubFolderId);
1
2
3
4
5
6
7
8
9

# Esempio

// fetch note by file name
script.fetchNoteByFileName("my note.md");
1
2

# Recupero di una nota dal suo ID

# Chiamata al metodo e parametri

/**
 * Fetches a note by its id
 *
 * @param id int the id of the note
 * @return NoteApi*
 */
NoteApi* ScriptingService::fetchNoteById(int id);
1
2
3
4
5
6
7

# Esempio

// fetch note by id
script.fetchNoteById(243);
1
2

Puoi dare un'occhiata all'esempio export-notes-as-one-html.qml (opens new window).

# Controllo dell'esistenza di una nota tramite il nome del file

# Chiamata al metodo e parametri

/**
 * Checks if a note file exists by its file name
 *
 * @param fileName string the file name of the note (mandatory)
 * @param ignoreNoteId integer id of a note to ignore in the check
 * @param noteSubFolderId integer id of the note subfolder
 * @return bool
 */
bool ScriptingService::noteExistsByFileName(QString fileName,
                                            int ignoreNoteId,
                                            int noteSubFolderId);
1
2
3
4
5
6
7
8
9
10
11

# Esempio

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

Puoi dare un'occhiata all'esempio paste-latex-image.qml (opens new window).

# Copia del testo negli appunti

# Chiamata al metodo e parametri

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

# Esempio

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

Puoi dare un'occhiata all'esempio disable-readonly-mode.qml (opens new window).

# Andare a una nota

# Chiamata al metodo e parametri

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

# Esempio

// 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).

# Passaggio a una sottocartella di note

# Chiamata al metodo e parametri

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

# Esempio

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

# Visualizzazione di una finestra di messaggio informativo

# Chiamata al metodo e parametri

/**
 * Shows an information message box
 *
 * @param text
 * @param title (optional)
 */
void ScriptingService::informationMessageBox(QString text, QString title);
1
2
3
4
5
6
7

# Esempio

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

# Visualizzazione di una finestra di messaggio interrogativo

# Chiamata al metodo e parametri

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

# Esempio

// 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).

# Visualizzazione di una finestra di dialogo Apri file

# Chiamata al metodo e parametri

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

# Esempio

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

# Visualizzazione di una finestra di dialogo Salva file

# Chiamata al metodo e parametri

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

# Esempio

// 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).

# Registrazione delle variabili delle impostazioni dello script

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.

# Esempio

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

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

# Esempio

/**
 * Registers the settings variables again
 *
 * Use this method if you want to use code to override your variables, like setting
 * default values depending 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).

# Memorizzazione e caricamento di variabili persistenti

# Chiamata al metodo e parametri

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

# Esempio

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

Assicurati di utilizzare un prefisso significativo nella tua chiave come PersistentVariablesTest/myVar perché le variabili sono accessibili da tutti gli script.

Potresti anche dare un'occhiata all'esempio variabili-persistenti.qml (opens new window).

# Caricamento delle variabili delle impostazioni dell'applicazione

# Chiamata al metodo e parametri

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

# Esempio

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

Tieni presente che le impostazioni in realtà possono essere vuote, devi occupartene tu stesso. defaultValue is only used if the setting doesn't exist at all.

# Creazione di una directory della cache

È possibile memorizzare nella cache i file nella posizione cache predefinita del sistema.

# Chiamata al metodo e parametri

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

# Esempio

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

# Cancellazione di una directory della cache

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

# Chiamata al metodo e parametri

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

# Esempio

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

# Leggere il percorso della directory del tuo script

Se è necessario ottenere il percorso della directory in cui è posizionato lo script, ad esempio per caricare altri file, è necessario registrare un file property string scriptDirPath;. Questa proprietà verrà impostata con il percorso della directory dello script.

# Esempio

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

# Conversione dei separatori di percorso in quelli nativi

# Chiamata al metodo e parametri

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

# Esempio

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

# Conversione dei separatori di percorso da quelli nativi

# Chiamata al metodo e parametri

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

# Esempio

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

# Recupero del separatore di directory nativo

# Chiamata al metodo e parametri

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

# Esempio

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

# Ottenere un elenco dei percorsi di tutte le note selezionate

# Chiamata al metodo e parametri

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

# Esempio

// 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).

# Ottenere un elenco degli ID di tutte le note selezionate

# Chiamata al metodo e parametri

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

# Esempio

// 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).

# Attivazione di un'azione di menu

# Chiamata al metodo e parametri

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

# Esempio

// 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). Basta cercare il titolo del menu in inglese. Nota che questi testi possono cambiare nel tempo.

# Apertura di una finestra di dialogo di input con una casella di selezione

# Chiamata al metodo e parametri

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

# Esempio

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).

# Apertura di una finestra di dialogo di input con una riga di modifica

# Chiamata al metodo e parametri

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

# Esempio

var result = script.inputDialogGetText(
    "line edit", "Please enter a name", "current text");
script.log(result);
1
2
3

# Verificare se esiste un file

# Chiamata al metodo e parametri

/**
 * Check if a file exists
 * @param filePath
 * @return
 */
bool ScriptingService::fileExists(QString &filePath);
1
2
3
4
5
6

# Esempio

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

# Leggere il testo da un file

# Chiamata al metodo e parametri

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

# Esempio

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

# Scrittura di testo in un file

# Chiamata al metodo e parametri

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

# Esempio

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

Puoi dare un'occhiata all'esempio export-notes-as-one-html.qml (opens new window).

# Lavorare con websocket

You can remotely 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.

# Adding a highlighting rule for the editor

You can directly inject highlighting rules into the editor by defining regular expressions and assigning them to a highlighting state.

# Method call and parameters

/**
 * Adds a highlighting rule to the syntax highlighter of the editor
 *
 * @param pattern {QString} the regular expression pattern to highlight
 * @param shouldContain {QString} a string that must be contained in the highlighted text for the pattern to be parsed
 * @param state {int} the state of the syntax highlighter to use
 * @param capturingGroup {int} the capturing group for the pattern to use for highlighting (default: 0)
 * @param maskedGroup {int} the capturing group for the pattern to use for masking (default: 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

# Highlighting states

Name Nr.
NoState -1
Link 0
Image 3
CodeBlock 4
CodeBlockComment 5
Italic 7
Bold 8
List 9
Comment 11
H1 12
H2 13
H3 14
H4 15
H5 16
H6 17
BlockQuote 18
HorizontalRuler 21
Tabella 22
InlineCodeBlock 23
MaskedSyntax 24
CurrentLineBackgroundColor 25
BrokenLink 26
FrontmatterBlock 27
TrailingSpace 28
CheckBoxUnChecked 29
CheckBoxChecked 30
StUnderline 31

# Esempio

// 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).