kindred/create
1
1
Fork 0
Code Issues 53 Pull Requests Actions Packages Projects 9 Releases 2 Wiki Activity

Merge pull request #25196 from pieterhijma/doc-application

Browse Source 
Doc: Improve the documentation of Application
This commit is contained in:
Chris Hennes
2026-01-29 13:31:09 +01:00
committed by GitHub
parent c74ac37488 393434026a
commit a00db89f57
3 changed files with 807 additions and 347 deletions
Download Patch File Download Diff File Expand all files Collapse all files

61
src/App/Application.cpp
View File

@@ -425,14 +425,6 @@ void Application::setupPythonException(PyObject* module)
//**************************************************************************
// Interface
/// get called by the document when the name is changing
void Application::renameDocument(const char *OldName, const char *NewName)
{
(void)OldName;
(void)NewName;
throw Base::RuntimeError("Renaming document internal name is no longer allowed!");
}
Document* Application::newDocument(const char * proposedName, const char * proposedLabel, DocumentInitFlags CreateFlags)
{
bool isUsingDefaultName = Base::Tools::isNullOrEmpty(proposedName);
@@ -1308,11 +1300,11 @@ Base::Reference<ParameterGrp> Application::GetParameterGroupByPath(const char*
return It->second->GetGroup(cName.c_str());
}
void Application::addImportType(const char* Type, const char* ModuleName)
void Application::addImportType(const char* filter, const char* moduleName)
{
FileTypeItem item;
item.filter = Type;
item.module = ModuleName;
item.filter = filter;
item.module = moduleName;
// Extract each filetype from 'Type' literal
std::string::size_type pos = item.filter.find("*.");
@@ -1325,7 +1317,7 @@ void Application::addImportType(const char* Type, const char* ModuleName)
}
// Due to branding stuff replace "FreeCAD" with the branded application name
if (strncmp(Type, "FreeCAD", 7) == 0) {
if (strncmp(filter, "FreeCAD", 7) == 0) {
std::string AppName = Config()["ExeName"];
AppName += item.filter.substr(7);
item.filter = std::move(AppName);
@@ -1337,26 +1329,26 @@ void Application::addImportType(const char* Type, const char* ModuleName)
}
}
void Application::changeImportModule(const char* Type, const char* OldModuleName, const char* NewModuleName)
void Application::changeImportModule(const char* filter, const char* oldModuleName, const char* newModuleName)
{
for (auto& it : _mImportTypes) {
if (it.filter == Type && it.module == OldModuleName) {
it.module = NewModuleName;
if (it.filter == filter && it.module == oldModuleName) {
it.module = newModuleName;
break;
}
}
}
std::vector<std::string> Application::getImportModules(const char* Type) const
std::vector<std::string> Application::getImportModules(const char* extension) const
{
std::vector<std::string> modules;
for (const auto & it : _mImportTypes) {
const std::vector<std::string>& types = it.types;
for (const auto & jt : types) {
#ifdef __GNUC__
if (strcasecmp(Type,jt.c_str()) == 0)
if (strcasecmp(extension, jt.c_str()) == 0)
#else
if (_stricmp(Type,jt.c_str()) == 0)
if (_stricmp(extension, jt.c_str()) == 0)
#endif
modules.push_back(it.module);
}
@@ -1405,16 +1397,16 @@ std::vector<std::string> Application::getImportTypes() const
return types;
}
std::map<std::string, std::string> Application::getImportFilters(const char* Type) const
std::map<std::string, std::string> Application::getImportFilters(const char* extension) const
{
std::map<std::string, std::string> moduleFilter;
for (const auto & it : _mImportTypes) {
const std::vector<std::string>& types = it.types;
for (const auto & jt : types) {
#ifdef __GNUC__
if (strcasecmp(Type,jt.c_str()) == 0)
if (strcasecmp(extension,jt.c_str()) == 0)
#else
if (_stricmp(Type,jt.c_str()) == 0)
if (_stricmp(extension,jt.c_str()) == 0)
#endif
moduleFilter[it.filter] = it.module;
}
@@ -1433,11 +1425,11 @@ std::map<std::string, std::string> Application::getImportFilters() const
return filter;
}
void Application::addExportType(const char* Type, const char* ModuleName)
void Application::addExportType(const char* filter, const char* moduleName)
{
FileTypeItem item;
item.filter = Type;
item.module = ModuleName;
item.filter = filter;
item.module = moduleName;
// Extract each filetype from 'Type' literal
std::string::size_type pos = item.filter.find("*.");
@@ -1450,7 +1442,7 @@ void Application::addExportType(const char* Type, const char* ModuleName)
}
// Due to branding stuff replace "FreeCAD" with the branded application name
if (strncmp(Type, "FreeCAD", 7) == 0) {
if (strncmp(filter, "FreeCAD", 7) == 0) {
std::string AppName = Config()["ExeName"];
AppName += item.filter.substr(7);
item.filter = std::move(AppName);
@@ -1462,26 +1454,26 @@ void Application::addExportType(const char* Type, const char* ModuleName)
}
}
void Application::changeExportModule(const char* Type, const char* OldModuleName, const char* NewModuleName)
void Application::changeExportModule(const char* filter, const char* oldModuleName, const char* newModuleName)
{
for (auto& it : _mExportTypes) {
if (it.filter == Type && it.module == OldModuleName) {
it.module = NewModuleName;
if (it.filter == filter && it.module == oldModuleName) {
it.module = newModuleName;
break;
}
}
}
std::vector<std::string> Application::getExportModules(const char* Type) const
std::vector<std::string> Application::getExportModules(const char* extension) const
{
std::vector<std::string> modules;
for (const auto & it : _mExportTypes) {
const std::vector<std::string>& types = it.types;
for (const auto & jt : types) {
#ifdef __GNUC__
if (strcasecmp(Type,jt.c_str()) == 0)
if (strcasecmp(extension,jt.c_str()) == 0)
#else
if (_stricmp(Type,jt.c_str()) == 0)
if (_stricmp(extension,jt.c_str()) == 0)
#endif
modules.push_back(it.module);
}
@@ -1530,16 +1522,16 @@ std::vector<std::string> Application::getExportTypes() const
return types;
}
std::map<std::string, std::string> Application::getExportFilters(const char* Type) const
std::map<std::string, std::string> Application::getExportFilters(const char* extension) const
{
std::map<std::string, std::string> moduleFilter;
for (const auto & it : _mExportTypes) {
const std::vector<std::string>& types = it.types;
for (const auto & jt : types) {
#ifdef __GNUC__
if (strcasecmp(Type,jt.c_str()) == 0)
if (strcasecmp(extension,jt.c_str()) == 0)
#else
if (_stricmp(Type,jt.c_str()) == 0)
if (_stricmp(extension,jt.c_str()) == 0)
#endif
moduleFilter[it.filter] = it.module;
}
@@ -2889,7 +2881,6 @@ std::list<std::string> Application::processFiles(const std::list<std::string>& f
void Application::processCmdLineFiles()
{
// process files passed to command line
const std::list<std::string> files = getCmdLineFiles();
const std::list<std::string> processed = processFiles(files);

1007
src/App/Application.h
View File

File diff suppressed because it is too large Load Diff

86
src/App/core-app.dox
View File

@@ -4,10 +4,10 @@
* @brief The part of FreeCAD that works without GUI (console or server mode)
*
* @details It contains the App namespace and defines core concepts such as
* @ref DocumentGroup "Document", @ref DocumentObjectGroup "Document Object",
* @ref PropertyFramework "Property Framework", @ref ExpressionFramework
* "Expression Framework", and the @ref ExtensionFramework "Extension
* Framework".
* @ref ApplicationGroup "Application", @ref DocumentGroup "Document", @ref
* DocumentObjectGroup "DocumentObject", @ref PropertyFramework "Property
* Framework", @ref ExpressionFramework "Expression Framework", and the @ref
* ExtensionFramework "Extension Framework".
*
* The largest difference between the functionality in @ref BASE "Base"
* compared to %App is that %App introduces the notion of properties, both used
@@ -16,6 +16,80 @@
* @ref App::Application "Application".
*/
/**
* @defgroup ApplicationGroup Application
* @ingroup APP
* @brief The class that represents the running FreeCAD application.
*
* The App::Application class is a singleton class that represents the running
* FreeCAD application. It can be obtained by App::GetApplication(). It
* manages the opened documents and provides various forms of functionality
* that are briefly discussed below.
*
* @section SecApplicationInitialization Initialization and Configuration
*
* On application start, the FreeCAD type system is initialized and the command
* line arguments are processed, possible opening FreeCAD files or executing
* FreeCAD macros. The internal configuration that contains various paths is
* set up and after that the `user.cfg` and `system.cfg` file are parsed and
* made available by @ref App::Application::GetUserParameter()
* "GetUserParameter()" and @ref App::Application::GetSystemParameter()
* "GetSystemParameter()".
*
* FreeCAD obtains various resources from different paths that can be accessed
* by means of functions such as @ref App::Application::GetHomePath()
* "GetHomePath" or the more generic function @ref
* App::Application::directories "directories()" that provides an @ref
* App::ApplicationDirectories "ApplicationDirectories" class.
*
* @section SecApplicationDocuments Document management
*
* An important role is managing FreeCAD documents. The application class
* allows opening and closing documents, creating unique and valid names and
* labels for the files, and setting or opening a file as the active file.
*
* Moreover, there is support for special files such as temporary files that
* may or may not be hidden in the tree or partially loaded files where not all
* objects are loaded.
*
* FreeCAD has a wide range of file formats that it can import and export. It
* is possible to install a file type filter together with a module name that
* then becomes responsible for importing or exporting the file types of the
* filter. An example of a filter is @c "STEP with colors (*.step *.STEP *.stp
* *.STP)" and the file types that will be associated with this filter are
* represented by the extensions and will be @c "step" and @c "stp" (matching
* is case-insensitive).
*
* @section SecApplicationTransactions Application-wide transactions
*
* In @ref SecUndoRedo "Documents" we explain more about the transaction
* system. Although transactions are mainly a feature of documents and
* document objects, there is also applicaton-wide functionality that allows
* creating transactions in multiple documents sharing the same transaction ID.
*
* @section SecApplicationLinks Links between document objects
*
* Although links occur between document objects and are as such more a topic
* of @ref GroupDocumentObject "DocumentObjects", App::Application provides
* functions to check for cyclic dependencies and obtaining links to a document
* object.
*
* @section SecApplicationSignals Signals
*
* The application class has various signals that can be connected to. There
* are various categories of signals:
* - on the level of the application, such as with new or deleted documents or
* transactions,
* - on the level of documents, such as with changed properties of documents or
* document objects, or with newly added objects,
* - on the level of objects, such as newly added properties,
* - on the level of extensions, such as newly added extensions.
*
* Many of the signals are also available on the document level and typically
* the application class has slots that connect to these document signals when
* a document is opened.
*/
/**
* @defgroup DocumentGroup Document
* @ingroup APP
@@ -127,7 +201,7 @@
*/
/**
* @defgroup DocumentObjectGroup Document Object
* @defgroup DocumentObjectGroup DocumentObject
* @ingroup APP
* @brief %Base class of all objects handled in the @ref App::Document "Document".
*
@@ -398,7 +472,7 @@
/**
* @defgroup ExtensionFramework Extension framework
* @ingroup APP
* @brief The extension system provides a way to extend the functionality of Document Objects.
* @brief The extension system provides a way to extend the functionality of @ref DocumentObjectGroup "DocumentObjects".
*
* The concept of extensions provides a way to extend the functionality of
* objects in FreeCAD despite Python's limitations with multiple inheritance