Line data Source code
1 : /*
2 : * SPDX-License-Identifier: GPL-3.0-only
3 : * MuseScore-Studio-CLA-applies
4 : *
5 : * MuseScore Studio
6 : * Music Composition & Notation
7 : *
8 : * Copyright (C) 2021 MuseScore Limited and others
9 : *
10 : * This program is free software: you can redistribute it and/or modify
11 : * it under the terms of the GNU General Public License version 3 as
12 : * published by the Free Software Foundation.
13 : *
14 : * This program is distributed in the hope that it will be useful,
15 : * but WITHOUT ANY WARRANTY; without even the implied warranty of
16 : * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 : * GNU General Public License for more details.
18 : *
19 : * You should have received a copy of the GNU General Public License
20 : * along with this program. If not, see <https://www.gnu.org/licenses/>.
21 : */
22 :
23 : #pragma once
24 :
25 : #include <QDir>
26 : #include <QProcess>
27 :
28 : #include "global/modularity/ioc.h"
29 : #include "global/iglobalconfiguration.h"
30 : #include "extensions/iextensionsconfiguration.h"
31 : #include "project/iprojectconfiguration.h"
32 : #include "notation/inotationconfiguration.h"
33 : #include "audio/main/iaudioconfiguration.h"
34 : #include "engraving/infrastructure/mscio.h"
35 : #include "project/iprojectsession.h"
36 :
37 : namespace mu::engraving::apiv1 {
38 : //---------------------------------------------------------
39 : /// \class FileIO
40 : /// Provides a simple API to perform file reading and
41 : /// writing operations. To use this class in a plugin put
42 : /// \code import FileIO 3.0 \endcode
43 : /// to the top part of the .qml plugin file.
44 : /// After that FileIO object can be declared and used
45 : /// in QML code:
46 : /// \code
47 : /// import MuseScore 3.0
48 : /// import FileIO 3.0
49 : /// MuseScore {
50 : /// FileIO {
51 : /// id: exampleFile
52 : /// source: "/tmp/example.txt"
53 : /// }
54 : /// onRun: {
55 : /// var test = exampleFile.read();
56 : /// console.log(test); // will print the file content
57 : /// }
58 : /// }
59 : /// \endcode
60 : //---------------------------------------------------------
61 :
62 : class FileIO : public QObject, public muse::Contextable
63 : {
64 : Q_OBJECT
65 :
66 : /// Path to the file which is operated on
67 : Q_PROPERTY(QString source READ source WRITE setSource)
68 :
69 : muse::GlobalInject<muse::IGlobalConfiguration> globalConfiguration;
70 : muse::GlobalInject<muse::extensions::IExtensionsConfiguration> extensionsConfiguration;
71 : muse::GlobalInject<mu::project::IProjectConfiguration> projectConfiguration;
72 : muse::GlobalInject<mu::notation::INotationConfiguration> notationConfiguration;
73 : muse::GlobalInject<muse::audio::IAudioConfiguration> audioConfiguration;
74 : muse::ContextInject<mu::project::IProjectSession> projectSession = { this };
75 :
76 : public:
77 :
78 : /// \cond PLUGIN_API \private \endcond
79 : explicit FileIO(QObject* parent = 0);
80 : explicit FileIO(const muse::modularity::ContextPtr& ctx, QObject* parent = 0);
81 :
82 : /// Reads file contents and returns a string.
83 : /// In case error occurs, error() signal is emitted
84 : /// and an empty string is returned.
85 : Q_INVOKABLE QString read();
86 : /// muse::Returns true if the file exists
87 : Q_INVOKABLE bool exists();
88 : /// Writes a string to the file.
89 : /// \warning This function overwrites all the contents of
90 : /// the file pointed by FileIO::source so it becomes lost.
91 : /// \note For security reasons, files can only be written within
92 : /// the user's MuseScore data directories (userAppDataPath and userDataPath).
93 : /// Attempts to write outside these directories will be blocked.
94 : /// \returns `true` if an operation finished successfully.
95 : Q_INVOKABLE bool write(const QString& data);
96 : /**
97 : * Writes binary data to the file.
98 : * Each character code (0-255) in the string is written as a single byte.
99 : * Use this for binary files like images, soundfonts, etc.
100 : * \warning This function overwrites all the contents of
101 : * the file pointed by FileIO::source so it becomes lost.
102 : * \note For security reasons, files can only be written within
103 : * the user's MuseScore data directories (userAppDataPath and userDataPath).
104 : * Attempts to write outside these directories will be blocked.
105 : * \returns `true` if an operation finished successfully.
106 : */
107 : Q_INVOKABLE bool writeBinary(const QString& data);
108 : /// Removes the file
109 : Q_INVOKABLE bool remove();
110 : /// muse::Returns user's home directory
111 0 : Q_INVOKABLE QString homePath() { QDir dir; return dir.homePath(); }
112 : /// muse::Returns a path suitable for a temporary file
113 0 : Q_INVOKABLE QString tempPath() { QDir dir; return dir.tempPath(); }
114 : // Returns the user's MuseScore documents directory (default location for Scores, Plugins, SoundFonts, Styles, Templates)
115 : Q_INVOKABLE QString userDataPath();
116 : // Returns the user-configured Plugins directory (Preferences → Folders → Plugins)
117 : Q_INVOKABLE QString pluginsUserPath();
118 : // Returns the user-configured Scores directory (Preferences → Folders → Scores)
119 : Q_INVOKABLE QString userProjectsPath();
120 : // Returns the user-configured Templates directory (Preferences → Folders → Templates)
121 : Q_INVOKABLE QString userTemplatesPath();
122 : // Returns the user-configured Styles directory (Preferences → Folders → Styles)
123 : Q_INVOKABLE QString userStylesPath();
124 : // Returns the user-configured SoundFonts directories (Preferences → Folders → SoundFonts)
125 : Q_INVOKABLE QStringList userSoundFontDirectories();
126 : // Returns the plugin's folder's path
127 : Q_INVOKABLE QString pluginDirectoryPath();
128 : // Returns the project's path (ex: .../Desktop/project.mscz)
129 : Q_INVOKABLE QString projectPath();
130 : // Returns whether or not the project is stored as a folder (with a .mscx file)
131 : Q_INVOKABLE bool isProjectDirectory();
132 : // Returns the project's folder's path
133 : Q_INVOKABLE QString projectDirectoryPath();
134 : /// Returns true if the plugin is allowed to write to the path
135 : Q_INVOKABLE bool isPathWriteable(const QString& path);
136 :
137 : /// muse::Returns the file's last modification time
138 : Q_INVOKABLE int modifiedTime();
139 :
140 : /// \cond MS_INTERNAL
141 0 : QString source() { return m_source; }
142 :
143 : public slots:
144 8 : void setSource(const QString& source) { m_source = source; }
145 : /// \endcond
146 :
147 : signals:
148 : /// Emitted on file operations errors.
149 : /// Implement onError() in your FileIO object to handle this signal.
150 : /// \param msg A short textual description of the error occurred.
151 : void error(const QString& msg);
152 :
153 : private:
154 : QString m_source;
155 : };
156 :
157 : //---------------------------------------------------------
158 : // MsProcess
159 : // @@ QProcess
160 : /// \brief Start an external program.\ Available in QML
161 : /// as \p QProcess.
162 : /// \details Using this will most probably result in the
163 : /// plugin to be platform dependant. \since MuseScore 3.2
164 : //---------------------------------------------------------
165 :
166 : class MsProcess : public QProcess
167 : {
168 : Q_OBJECT
169 :
170 : public:
171 0 : MsProcess(QObject* parent = 0)
172 0 : : QProcess(parent) {}
173 :
174 : public slots:
175 : /// Execute an external command.
176 : /// \param command A command line to execute.
177 : /// \warning This function is deprecated. Use \ref startWithArgs instead.
178 : Q_INVOKABLE void start(const QString& command);
179 : /// Execute an external command.
180 : /// \param program A program to execute.
181 : /// \param args An array of arguments passed to the program.
182 : /// \since MuseScore 4.3
183 : Q_INVOKABLE void startWithArgs(const QString& program, const QStringList& args);
184 : /// --
185 0 : Q_INVOKABLE bool waitForFinished(int msecs = 30000) { return QProcess::waitForFinished(msecs); }
186 : /// --
187 0 : Q_INVOKABLE QByteArray readAllStandardOutput() { return QProcess::readAllStandardOutput(); }
188 : };
189 : }
|
