YSSCore::Editor::FileEditWidget Class
class YSSCore::Editor::FileEditWidget此类为Yayin Story Studio 提供文件编辑的基类. 详情...
| 头文件： | #include <FileEditWidget> |
| 自以下版本： | YSS 0.13.0 |
| 被继承： |
公开成员函数
(自 YSS 0.13.0 引入) | FileEditWidget(QWidget *parent = nullptr) |
(自 YSS 0.13.0 引入) virtual | ~FileEditWidget() |
(自 YSS 0.13.0 引入) void | cancelFileChanged() |
(自 YSS 0.13.0 引入) virtual void | closeEvent(QCloseEvent *event) override |
(自 YSS 0.13.0 引入) void | closeFile(bool autoAbandon = false) |
(自 YSS 0.13.0 引入) bool | copy() |
(自 YSS 0.13.0 引入) bool | cursorToPosition(qint32 lineNumber, qint32 column) |
(自 YSS 0.13.0 引入) bool | cut() |
(自 YSS 0.15.0 引入) QString | getFileExt() const |
(自 YSS 0.13.0 引入) QString | getFileName() const |
(自 YSS 0.13.0 引入) QString | getFilePath() const |
(自 YSS 0.15.0 引入) QString | getVirtualFileParam() const |
(自 YSS 0.15.0 引入) bool | isAutoAbandon() const |
(自 YSS 0.13.0 引入) bool | isFileChanged() const |
(自 YSS 0.15.0 引入) bool | isVirtualFile() const |
(自 YSS 0.13.0 引入) bool | openFile(const QString &path) |
(自 YSS 0.13.0 引入) bool | paste() |
(自 YSS 0.13.0 引入) bool | redo() |
(自 YSS 0.13.0 引入) bool | reloadFile() |
(自 YSS 0.15.0 引入) bool | saveFile(const QString &path = "", bool deleteWhenSaveAs = false) |
(自 YSS 0.13.0 引入) bool | selectAll() |
(自 YSS 0.15.0 引入) void | setAutoAbandon(bool autoAbandon) |
(自 YSS 0.13.0 引入) void | setFileChanged() |
(自 YSS 0.13.0 引入) bool | undo() |
信号
(自 YSS 0.14.0 引入) void | fileChangeCanceled(const QString &filePath) |
(自 YSS 0.13.0 引入) void | fileChanged(const QString &filePath) |
(自 YSS 0.15.0 引入) void | fileClosed(const QString &filePath) |
(自 YSS 0.15.0 引入) void | fileRenamed(const QString &rawPath, const QString &changedPath) |
(自 YSS 0.13.0 引入) void | fileSaved(const QString &filePath) |
受保护成员函数
(自 YSS 0.13.0 引入) virtual bool | onClose() |
(自 YSS 0.13.0 引入) virtual bool | onCopy() |
(自 YSS 0.13.0 引入) virtual bool | onCursorToPosition(qint32 lineNumber, qint32 column) |
(自 YSS 0.13.0 引入) virtual bool | onCut() |
(自 YSS 0.13.0 引入) virtual bool | onOpen(const QString &path) |
(自 YSS 0.13.0 引入) virtual bool | onPaste() |
(自 YSS 0.13.0 引入) virtual bool | onRedo() |
(自 YSS 0.13.0 引入) virtual bool | onReload() |
(自 YSS 0.13.0 引入) virtual bool | onSave(const QString &path) |
(自 YSS 0.13.0 引入) virtual bool | onSelectAll() |
(自 YSS 0.13.0 引入) virtual bool | onUndo() |
(自 YSS 0.15.0 引入) virtual bool | onVirtualClose() |
(自 YSS 0.15.0 引入) virtual bool | onVirtualOpen(const QString &ext, const QString &fileName, const QString ¶m) |
(自 YSS 0.15.0 引入) virtual bool | onVirtualReload() |
(自 YSS 0.15.0 引入) virtual bool | onVirtualSave() |
详细说明
FileEditWidget是所有文件编辑器的基类，所有文件编辑器都需要继承此类。
Note: 这类在0.15.0因引入虚拟文件概念而变更了虚函数顺序和声明，因此ABI与此前不同。
文件编辑器的职责
文件编辑器的职责是提供一个界面来编辑文件内容，并提供一些基本的文件操作功能， 如保存、撤销、重做等。具体来说，文件编辑器需要实现以下功能：
- 1. 打开文件：能够打开一个指定路径的文件，并将其内容显示在编辑器中。
- 2. 编辑文件：能够修改文件内容，并能够检测到文件内容的修改状态。
- 3. 保存文件：能够将修改后的文件内容保存到指定路径的文件中。
- 4. 其他操作：能够提供一些常用的编辑操作，如复制、剪切、粘贴、全选等。
上述未提及的功能，如重载、光标定位等都是可选功能。重载默认按照打开文件的方式重新加载文件内容，光标定位默认不实现。
文件编辑器的使用接口和实现接口
文件编辑器提供了一套使用接口和实现接口。使用接口是指外部代码调用该 文件编辑器时使用的接口，比如openFile、saveFile等； 实现接口是指文件编辑器的子类需要重载的接口，如onOpen、onSave等。
目前，所有实现接口都以on开头，且设为protected，理应不被外部调用， 实际上也不应被继承类调用，除非你明确要复用基类的实现逻辑。
虚拟文件
YSSCore提供了一套被称之为虚拟文件的概念。有关该概念的详细阐述， 以及虚拟文件的虚拟文件路径的格式，请参考YSSCore::Editor::FileServer的相关文档。 这里我们只说明一下FileEditWidget在虚拟文件模式下的一些特殊行为。
当openFile函数被调用时，如果传入的路径符合虚拟文件路径的格式（即以@开头，且包含!和?）， 则FileEditWidget会自动将其识别为虚拟文件，并将isVirtualFile属性设为true。 此时，文件路径、文件名、扩展名等相关信息会按照虚拟文件路径的格式进行解析和返回。
在虚拟文件模式下，有关文件读写操作的四函数从onOpen、onClose、onSave、onReload 变更为onVirtualOpen、onVirtualClose、onVirtualSave、onVirtualReload，且默认实现为返回false。 但对应的外部使用接口不变，仍然为openFile、close、saveFile、reloadFile等。
也就是说，外部调用者无需关心当前文件是否为虚拟文件，仍然按照正常的方式调用这些接口即可， FileEditWidget会根据当前文件的类型自动调用相应的实现接口。不过值得一提的是， 在虚拟文件模式下，saveFile传入的两个参数均会被忽略。
文件关闭的行为
在四大读写操作函数中，只有closeFile()是void类型，这意味着无法通过返回值来判断文件是否成功关闭了。 因为文件的关闭可能并非是从手动调用触发的，也可能是从用户点击关闭按钮触发的，而且也可能因 用户的要求中途取消了关闭操作。因此FileEditWidget通过重载closeEvent函数来统一处理所有 来源的关闭，且不可能从closeFile知道是否成功关闭。要获得文件的关闭状态，应该监听fileClosed信号。
此外，根据目前FileServerManager的实现，fileClosed信号发出之后，在下一个事件循环该 FileEditWidget对象就会被销毁，因此任何连接到fileClosed信号的槽函数都只应做一些立即操作， 并且不得缓存该对象的指针以备后用，因为该对象可能已经被销毁了。
成员函数文档
[since YSS 0.13.0] FileEditWidget::FileEditWidget(QWidget *parent = nullptr)
parent 为父对象。
构造FileEditWidget对象。
这个function 从 YSS 0.13.0 开始支持。
[virtual noexcept, since YSS 0.13.0] FileEditWidget::~FileEditWidget()
析构FileEditWidget对象。
这个function 从 YSS 0.13.0 开始支持。
[since YSS 0.13.0] void FileEditWidget::cancelFileChanged()
将当前文件内容标记为未修改状态。 此函数通常在派生类中被调用，当文件内容被保存或重新加载后，应调用此函数以更新文件状态。 之后，它会自动触发fileChangeCanceled信号，通知外部文件内容修改已被取消，并传递当前文件路径作为参数。
这个function 从 YSS 0.13.0 开始支持。
[override virtual, since YSS 0.13.0] void FileEditWidget::closeEvent(QCloseEvent *event)
event 关闭事件对象。
处理文件编辑器关闭事件。
此函数在文件编辑器尝试关闭时被调用，调用派生类实现的onClose()函数以决定是否允许关闭。 如果onClose()返回true，则接受关闭事件；否则忽略关闭事件，文件编辑器保持打开状态。
Warning: 派生类若重载了closeEvent()，应确保调用基类的实现以保持正确的关闭行为。
这个function 从 YSS 0.13.0 开始支持。
[since YSS 0.13.0] void FileEditWidget::closeFile(bool autoAbandon = false)
关闭当前文件编辑器。autoAbandon 是否自动放弃未保存的修改。默认为false，即不自动放弃。
这个函数直接调用QWidget的close()函数，触发关闭事件。
关闭事件会调用派生类实现的onClose()函数以决定是否允许关闭。
这个function 从 YSS 0.13.0 开始支持。
[since YSS 0.13.0] bool FileEditWidget::copy()
复制当前选中的内容到剪贴板。
return 如果复制操作成功，返回true；否则返回false。
此类调用派生类实现的onCopy()函数以实际处理复制逻辑。
这个function 从 YSS 0.13.0 开始支持。
[since YSS 0.13.0] bool FileEditWidget::cursorToPosition(qint32 lineNumber, qint32 column)
lineNumber 行号，从1开始。 column 列号，从1开始。
将光标移动到指定的行号和列号位置。
return 如果光标成功移动到指定位置，返回true；否则返回false。
这个function 从 YSS 0.13.0 开始支持。
[since YSS 0.13.0] bool FileEditWidget::cut()
剪切当前选中的内容到剪贴板。
return 如果剪切操作成功，返回true；否则返回false。
此类调用派生类实现的onCut()函数以实际处理剪切逻辑。
这个function 从 YSS 0.13.0 开始支持。
[signal, since YSS 0.14.0] void FileEditWidget::fileChangeCanceled(const QString &filePath)
filePath 当前文件路径。
当文件内容修改被取消时，自动触发此信号。
这个function 从 YSS 0.14.0 开始支持。
[signal, since YSS 0.13.0] void FileEditWidget::fileChanged(const QString &filePath)
filePath 当前文件路径。
当文件内容被修改时，自动触发此信号。
这个function 从 YSS 0.13.0 开始支持。
另请参阅 setFileChanged().
[signal, since YSS 0.15.0] void FileEditWidget::fileClosed(const QString &filePath)
filePath 当前文件路径。
当文件最终被关闭时，自动触发此信号。
请注意，这函数发出之后，该FileEditWidget很快就会被销毁，且无法阻止。 请勿再保存该对象的指针以备后用。
这个function 从 YSS 0.15.0 开始支持。
[signal, since YSS 0.15.0] void FileEditWidget::fileRenamed(const QString &rawPath, const QString &changedPath)
rawPath 原文件路径。 changedPath 现文件路径。
当文件被成功保存，且路径与此前不一致时，自动触发此信号。
这个function 从 YSS 0.15.0 开始支持。
[signal, since YSS 0.13.0] void FileEditWidget::fileSaved(const QString &filePath)
filePath 当前文件路径。
当文件被成功保存时，自动触发此信号。
这个function 从 YSS 0.13.0 开始支持。
[since YSS 0.15.0] QString FileEditWidget::getFileExt() const
return 当前文件的扩展名。
返回当前文件的扩展名（不带点）。如果当前没有打开任何文件，则返回空字符串。
对于虚拟文件路径，扩展名是路径中@和!之间的部分。
这个function 从 YSS 0.15.0 开始支持。
[since YSS 0.13.0] QString FileEditWidget::getFileName() const
return 当前文件编辑器的文件名。
返回当前文件编辑器的文件名。如果当前没有打开任何文件，则返回空字符串。
这个function 从 YSS 0.13.0 开始支持。
[since YSS 0.13.0] QString FileEditWidget::getFilePath() const
return 当前文件编辑器的文件路径。
返回当前文件编辑器的文件路径。如果当前没有打开任何文件，则返回空字符串。
注意，这可能是个虚拟文件路径，如果当前文件是通过FileServer打开的虚拟文件， 则返回的路径格式为@ext!fileName?param，其中ext是文件扩展名，fileName是文件名，param是额外参数。 对于虚拟文件路径，getFileName()函数会正确解析并返回文件名部分。
这个function 从 YSS 0.13.0 开始支持。
[since YSS 0.15.0] QString FileEditWidget::getVirtualFileParam() const
return 当前虚拟文件的参数部分。
返回当前虚拟文件的参数部分。如果当前文件不是虚拟文件或没有参数，则返回空字符串。
对于虚拟文件路径，参数部分是路径中?之后的部分。
这个function 从 YSS 0.15.0 开始支持。
[since YSS 0.15.0] bool FileEditWidget::isAutoAbandon() const
return 当前文件编辑器的自动放弃状态。
如果在关闭文件时会自动放弃未保存的修改，返回true；否则返回false。
这个function 从 YSS 0.15.0 开始支持。
[since YSS 0.13.0] bool FileEditWidget::isFileChanged() const
return 当前文件内容是否被修改。
如果文件内容被修改，返回true；否则返回false。
这个function 从 YSS 0.13.0 开始支持。
[since YSS 0.15.0] bool FileEditWidget::isVirtualFile() const
return 当前文件是否为虚拟文件。
如果当前文件为虚拟文件，返回true；否则返回false。
虚拟文件是指不对应实际磁盘文件的文件，通常由程序动态生成或从其他来源加载。对于虚拟文件，某些操作可能会有所不同，例如保存时可能需要特殊处理。
这个function 从 YSS 0.15.0 开始支持。
[virtual protected, since YSS 0.13.0] bool FileEditWidget::onClose()
派生类可以实现此虚函数以处理文件关闭逻辑。
return 如果文件编辑器可以关闭，返回true；否则返回false。
这个函数默认会根据isFileChanged()的返回值来判断文件是否被修改过， 如果被修改过则弹出一个警告对话框询问用户是否保存修改。这应该可以 满足绝大部分情况下的关闭需求，因此如果没有特殊需求，派生类无需重载此函数。
如果isAutoAbandon()返回true，则无论文件是否被修改过，都会直接放弃修改并允许关闭。
Warning: 不要在这个函数里调用close或deleteLater等任何实质上真的 会关闭这个Widget的函数，会造成递归爆栈。这个函数的唯一作用是通过 return 告知YSS是否真的应该关闭它。因此你可以在里面做一些保存、警告等操作
这个function 从 YSS 0.13.0 开始支持。
[virtual protected, since YSS 0.13.0] bool FileEditWidget::onCopy()
派生类实现此纯虚函数以处理复制逻辑。
return 如果复制操作成功，返回true；否则返回false。
这个function 从 YSS 0.13.0 开始支持。
[virtual protected, since YSS 0.13.0] bool FileEditWidget::onCursorToPosition(qint32 lineNumber, qint32 column)
lineNumber 行号，从1开始。 column 列号，从1开始。
由派生类实现的函数，用于将光标移动到指定的行号和列号位置。
由于FileEditWidget最早是面向文本文件设计，因此 lineNumber 和 column 的语义是基于文本文件的行列号的。但如有需要， 也可以将其按照其他方式进行解释和使用，例如对于图片，可用理解为像素坐标等。
return 如果光标成功移动到指定位置，返回true；否则返回false。
这个function 从 YSS 0.13.0 开始支持。
[virtual protected, since YSS 0.13.0] bool FileEditWidget::onCut()
派生类实现此纯虚函数以处理剪切逻辑。
return 如果剪切操作成功，返回true；否则返回false。
这个function 从 YSS 0.13.0 开始支持。
[virtual protected, since YSS 0.13.0] bool FileEditWidget::onOpen(const QString &path)
派生类必须实现此纯虚函数以处理文件打开逻辑。 path 要打开的文件路径。
return 如果文件成功打开并加载，返回true；否则返回false。
Warning: 从0.15开始，这个函数可能因为onReload而重复调用，不保证 在整个生命周期内只调用一次。因此如果你在这个函数内尝试懒加载你的 FileEditWidget，应当首先检查资源是否已经初始化，避免出现内存泄漏。
这个function 从 YSS 0.13.0 开始支持。
[virtual protected, since YSS 0.13.0] bool FileEditWidget::onPaste()
派生类实现此纯虚函数以处理粘贴逻辑。
return 如果粘贴操作成功，返回true；否则返回false。
这个function 从 YSS 0.13.0 开始支持。
[virtual protected, since YSS 0.13.0] bool FileEditWidget::onRedo()
派生类实现此纯虚函数以处理重做逻辑。
return 如果重做操作成功，返回true；否则返回false。
这个function 从 YSS 0.13.0 开始支持。
[virtual protected, since YSS 0.13.0] bool FileEditWidget::onReload()
派生类实现此纯虚函数以处理文件重新加载逻辑。
return 如果文件成功重新加载，返回true；否则返回false。
在0.15之前的版本，这个函数默认返回false 从0.15开始，这个函数默认使用现在的文件路径重新调用onOpen()
这个function 从 YSS 0.13.0 开始支持。
[virtual protected, since YSS 0.13.0] bool FileEditWidget::onSave(const QString &path)
派生类必须实现此纯虚函数以处理文件保存逻辑。
path 要保存的文件路径。如果为空字符串，则使用当前文件路径。非空字符串在保存成功后会更新当前文件路径。
return 如果文件成功保存，返回true；否则返回false。
这个function 从 YSS 0.13.0 开始支持。
[virtual protected, since YSS 0.13.0] bool FileEditWidget::onSelectAll()
派生类实现此纯虚函数以处理全选逻辑。
return 如果全选操作成功，返回true；否则返回false。
这个function 从 YSS 0.13.0 开始支持。
[virtual protected, since YSS 0.13.0] bool FileEditWidget::onUndo()
派生类实现此纯虚函数以处理撤销逻辑。
return 如果撤销操作成功，返回true；否则返回false。
这个function 从 YSS 0.13.0 开始支持。
[virtual protected, since YSS 0.15.0] bool FileEditWidget::onVirtualClose()
处理虚拟文件的关闭逻辑。
return 如果虚拟文件编辑器可以关闭，返回true；否则返回false。
默认返回true。
这个function 从 YSS 0.15.0 开始支持。
[virtual protected, since YSS 0.15.0] bool FileEditWidget::onVirtualOpen(const QString &ext, const QString &fileName, const QString ¶m)
ext 虚拟文件的扩展名。 fileName 虚拟文件的文件名。 param 其他参数字符串，可以包含任意内容，由调用者和实现者自行约定格式和含义。
处理虚拟文件的打开逻辑。
return 如果虚拟文件成功打开，返回true；否则返回false。
默认返回false。
这个function 从 YSS 0.15.0 开始支持。
[virtual protected, since YSS 0.15.0] bool FileEditWidget::onVirtualReload()
处理虚拟文件的重新加载逻辑。
return 如果虚拟文件成功重新加载，返回true；否则返回false。
这个实现默认重新调用onVirtualOpen。
这个function 从 YSS 0.15.0 开始支持。
[virtual protected, since YSS 0.15.0] bool FileEditWidget::onVirtualSave()
处理虚拟文件的保存逻辑。
return 如果虚拟文件成功保存，返回true；否则返回false。
默认实现为返回false，表示虚拟文件不支持保存操作。派生类可以根据需要重载此函数以提供虚拟文件的保存功能。
这个function 从 YSS 0.15.0 开始支持。
[since YSS 0.13.0] bool FileEditWidget::openFile(const QString &path)
打开指定路径的文件，并加载其内容。 path 要打开的文件路径。
return 如果文件成功打开并加载，返回true；否则返回false。
此类在判定文件路径是否为空后，调用派生类实现的onOpen()函数以实际打开文件。
从0.15.0开始，这个函数会事先判定文件路径是否满足虚拟文件路径，如果是的话，则调用 onVirtualOpen()函数打开。有关虚拟文件路径的概念，请参考FileServer类的说明。
这个function 从 YSS 0.13.0 开始支持。
[since YSS 0.13.0] bool FileEditWidget::paste()
从剪贴板粘贴内容到当前光标位置。
return 如果粘贴操作成功，返回true；否则返回false。
此类调用派生类实现的onPaste()函数以实际处理粘贴逻辑。
这个function 从 YSS 0.13.0 开始支持。
[since YSS 0.13.0] bool FileEditWidget::redo()
重做上一次被撤销的编辑操作。
return 如果重做操作成功，返回true；否则返回false。
此类调用派生类实现的onRedo()函数以实际处理重做逻辑。
这个function 从 YSS 0.13.0 开始支持。
[since YSS 0.13.0] bool FileEditWidget::reloadFile()
重新加载当前文件编辑器的内容。
return 如果文件成功重新加载，返回true；否则返回false。
此类在判定当前文件路径是否为空后，调用派生类实现的onReload()函数以实际重新加载文件。
这个function 从 YSS 0.13.0 开始支持。
[since YSS 0.15.0] bool FileEditWidget::saveFile(const QString &path = "", bool deleteWhenSaveAs = false)
保存当前文件编辑器的内容到指定路径。 path 要保存的文件路径。如果为空字符串，则使用当前文件路径。非空字符串在保存成功后会更新当前文件路径。 deleteWhenSaveAs 当执行另存为操作时，是否删除原文件。默认为false，即不删除原文件。如果设置为true， 可以视作重命名文件，保存成功后原文件将被删除。请谨慎使用此选项，以免误删重要文件。
return 如果文件成功保存，返回true；否则返回false。
此类在判定文件路径是否为空后，调用派生类实现的onSave()函数以实际保存文件。 一旦文件成功保存，fileChanged状态会被重置为false，并触发fileSaved信号。
Note: 这个函数最初从0.13.0引入，在0.15.0中增加了deleteWhenSaveAs参数以支持在另存为操作时删除原文件的功能。 此外，从0.15.0开始，这个函数会在调用虚函数onSave之后，额外检查文件是否确实存在，以确保保存操作的成功性。 这是因为某些派生类的onSave实现可能会在保存失败时没有正确返回false，因此增加了文件存在性的检查以提高函数的可靠性。
在虚拟文件模式下，它会直接调用onVirtualSave()函数进行保存。虚拟保存时，path 和 deleteWhenSaveAs 均无效。
这个function 从 YSS 0.15.0 开始支持。
[since YSS 0.13.0] bool FileEditWidget::selectAll()
选中当前文件编辑器中的所有内容。
return 如果全选操作成功，返回true；否则返回false。
此类调用派生类实现的onSelectAll()函数以实际处理全选逻辑。
这个function 从 YSS 0.13.0 开始支持。
[since YSS 0.15.0] void FileEditWidget::setAutoAbandon(bool autoAbandon)
设置当前文件编辑器的自动放弃状态。 autoAbandon 是否在关闭文件时自动放弃未保存的修改。默认为false，即不自动放弃。
这个function 从 YSS 0.15.0 开始支持。
另请参阅 isAutoAbandon().
[since YSS 0.13.0] void FileEditWidget::setFileChanged()
将当前文件内容标记为已修改状态。 此函数通常在派生类中被调用，当用户修改了文件内容时，应调用此函数以更新文件状态。 之后，它会自动触发fileChanged信号，通知外部文件内容已被修改，并传递当前文件路径作为参数。
这个function 从 YSS 0.13.0 开始支持。
另请参阅 fileChanged().
[since YSS 0.13.0] bool FileEditWidget::undo()
撤销上一次编辑操作。
return 如果撤销操作成功，返回true；否则返回false。
此类调用派生类实现的onUndo()函数以实际处理撤销逻辑。
这个function 从 YSS 0.13.0 开始支持。