From 1405ed0405c586e853adde2eae6d952bf7ca101f Mon Sep 17 00:00:00 2001 From: TJ Kotha Date: Wed, 8 Mar 2023 14:07:47 -0500 Subject: [PATCH 1/3] updated project manager source code map to include data classes and settings. Signed-off-by: TJ Kotha --- .../tools/project-manager/source-code-map.md | 78 +++++++++++++++++-- 1 file changed, 72 insertions(+), 6 deletions(-) diff --git a/content/docs/engine-dev/tools/project-manager/source-code-map.md b/content/docs/engine-dev/tools/project-manager/source-code-map.md index ac44cb30cdb..50c0cd621fa 100644 --- a/content/docs/engine-dev/tools/project-manager/source-code-map.md +++ b/content/docs/engine-dev/tools/project-manager/source-code-map.md @@ -12,9 +12,13 @@ This information is for developers of the **Project Manager** tool. If you're a This contains brief summaries of various class's functionality and role. If available, there are additional links in the table of contents, either with expanded information, or github links. All documentation reflects code as of commit [(b79bd3df1f)](https://github.com/o3de/o3de/tree/b79bd3df1fe5d4c2a639d3921a29bd0d95712f6c) {{< /note >}} -## Startup and Screen Management +## Overview +| Section | Description | +| - | - | +| [Startup and Screen Management](#startup-and-screen-management) | Describes the start up boot sequence and overall screen management of Project Manager.| +| [Data Classes](#data-classes) | Simple classes that house various data structures used by Project Manager.| -### Overview +### Startup and Screen Management | Class | Source Code | Description | | - | - | - | @@ -26,6 +30,22 @@ This contains brief summaries of various class's functionality and role. If avai |ScreenDefs | [header](https://github.com/o3de/o3de/blob/development/Code/Tools/ProjectManager/Source/ScreenDefs.h) | Contains definitions for `ProjectManagerScreen` enum, which describes all possible types of screens in Project Manager. It also defines a hash function, and a mapping to appropriate string equivalents for each enum.| |[ScreenWidget](#screenwidget) | [header](https://github.com/o3de/o3de/blob/development/Code/Tools/ProjectManager/Source/ScreenWidget.h) | The parent class to all screens in Project Manager. It contains all necessary stubs for screen management and transition. `ScreensCtrl` is defined in terms of `ScreenWidget`, so that all transition logic is polymorphic.| +[Back to Overview](#overview) + +### Data Classes + +| Class | Source Code | Description | +| - | - | - | +| TemplateInfo | [header](https://github.com/o3de/o3de/blob/development/Code/Tools/ProjectManager/Source/TemplateInfo.h) [cpp file](https://github.com/o3de/o3de/blob/development/Code/Tools/ProjectManager/Source/TemplateInfo.cpp) | Describes data fields to encapsulate a generic Template. | +| ProjectTemplateInfo | [header](https://github.com/o3de/o3de/blob/development/Code/Tools/ProjectManager/Source/ProjectTemplateInfo.h) | Subclass of Template specific to Projects. Only difference is that this one includes Gems. | +| SettingsInterface | [header](https://github.com/o3de/o3de/blob/development/Code/Tools/ProjectManager/Source/SettingsInterface.h) | Interface for interacting with the O3DE Settings Registry. | +| [Settings](#settings) | [header](https://github.com/o3de/o3de/blob/development/Code/Tools/ProjectManager/Source/Settings.h) [cpp file](https://github.com/o3de/o3de/blob/development/Code/Tools/ProjectManager/Source/Settings.cpp) | Implementation for `SettingsInterface` to interact with O3DE Settings Registry. | +| ProjectInfo | [header](https://github.com/o3de/o3de/blob/development/Code/Tools/ProjectManager/Source/ProjectInfo.h) [cpp file](https://github.com/o3de/o3de/blob/development/Code/Tools/ProjectManager/Source/ProjectInfo.cpp) | Contains data structure to describe a project, as recorded in project.json, inside `ProjectManager`. Also contains metadata for remote projects, or for checking if a project needs to be rebuilt. | +| EngineInfo | [header](https://github.com/o3de/o3de/blob/development/Code/Tools/ProjectManager/Source/EngineInfo.h) [cpp file](https://github.com/o3de/o3de/blob/development/Code/Tools/ProjectManager/Source/EngineInfo.cpp) | Contains data structure to describe the current engine, as recorded in engine.json, inside `ProjectManager`. Also contains metadata for engine registration. | +| ProjectManagerDefs | [header](https://github.com/o3de/o3de/blob/development/Code/Tools/ProjectManager/Source/ProjectManagerDefs.h) | Contains various constants and preset strings. | + +[Back to Overview](#overview) + ### Application Inherits from `AzFramework::Application`. @@ -50,7 +70,7 @@ The two primary functions to keep track of are `Init` and `Run`. [`TearDown`](ht * Shows the MainWindow. * Run the QApplication's main loop. -[Back to Top](#overview) +[Back to Startup and Screen Management](#startup-and-screen-management) @@ -67,7 +87,7 @@ All logic unique to the Project Manager occurs at the constructor, which is summ * If `startScreen` is set, first force load the main Projects screen, then transition to the desired screen. If not set, the Projects screen is the default. * If `projectPath` is set, notify the `ScreensCtrl` instance of the currently highlighted project path. -[Back to Top](#overview) +[Back to Startup and Screen Management](#startup-and-screen-management) @@ -120,7 +140,7 @@ All functions are summarized as follows: * Update `m_screenMap` with pointer to the new screen. * Connect slots for transition functions for new screen. -[Back to Top](#overview) +[Back to Startup and Screen Management](#startup-and-screen-management) ### ScreenWidget @@ -139,4 +159,50 @@ If you were to check the header file, it would only contain stub functions. In t `ScreenWidget` also defines various Qt [`signals`](https://github.com/o3de/o3de/blob/99f713702e5e0a8949e38c7b92bf00682c2633ca/Code/Tools/ProjectManager/Source/ScreenWidget.h#L65-L70) that are used to facilitate transitions by connecting to Qt [`slots`](https://github.com/o3de/o3de/blob/99f713702e5e0a8949e38c7b92bf00682c2633ca/Code/Tools/ProjectManager/Source/ScreensCtrl.cpp#L201-L205) as defined in `ScreensCtrl::ResetScreen`. -[Back to Top](#overview) \ No newline at end of file +[Back to Startup and Screen Management](#startup-and-screen-management) + + +### Settings + +We specify the `SettingsInterface` as a contract to ensure we implement the proper methods, and to enable global access to settings from a clean interface ([one example](https://github.com/o3de/o3de/blob/b79bd3df1fe5d4c2a639d3921a29bd0d95712f6c/Code/Tools/ProjectManager/Source/ExternalLinkDialog.cpp#L88)). It also acts as a singleton interface for accessing Project Manager settings. + +`SettingsInterface` specifies the following functions as the contract to interact with O3DE Settings Registry: +| Function | Description | Implementation | +| - | - | - | +| [`SettingsInterface::Get`](https://github.com/o3de/o3de/blob/69dbcd08a56539315bfb0472984daf0f46e7a966/Code/Tools/ProjectManager/Source/SettingsInterface.h#L31-L44) | Using a `QString` key, can either return the string or bool value. | [code](https://github.com/o3de/o3de/blob/7d716a4a21afd217444d91043ea810f6c8a38f21/Code/Tools/ProjectManager/Source/Settings.cpp#L65-L79) | +| [`SettingsInterface::Set`](https://github.com/o3de/o3de/blob/69dbcd08a56539315bfb0472984daf0f46e7a966/Code/Tools/ProjectManager/Source/SettingsInterface.h#L46-L59) | Using a `QString` key, can either set a string or bool value for an entry. | [code](https://github.com/o3de/o3de/blob/7d716a4a21afd217444d91043ea810f6c8a38f21/Code/Tools/ProjectManager/Source/Settings.cpp#L81-L99) | +| [`SettingsInterface::Remove`](https://github.com/o3de/o3de/blob/69dbcd08a56539315bfb0472984daf0f46e7a966/Code/Tools/ProjectManager/Source/SettingsInterface.h#L61-L66) | Removes a entry with `QString` key from the registry. | [code](https://github.com/o3de/o3de/blob/7d716a4a21afd217444d91043ea810f6c8a38f21/Code/Tools/ProjectManager/Source/Settings.cpp#L101-L109) | +| [`SettingsInterface::Copy`](https://github.com/o3de/o3de/blob/69dbcd08a56539315bfb0472984daf0f46e7a966/Code/Tools/ProjectManager/Source/SettingsInterface.h#L68-L75) | Copies the value from one key to another. Can also optionally remove the original entry, acting as a "Move" command. | [code](https://github.com/o3de/o3de/blob/7d716a4a21afd217444d91043ea810f6c8a38f21/Code/Tools/ProjectManager/Source/Settings.cpp#L111-L132) | +| [`SettingsInterface::GetProjectKey`](https://github.com/o3de/o3de/blob/69dbcd08a56539315bfb0472984daf0f46e7a966/Code/Tools/ProjectManager/Source/SettingsInterface.h#L77-L82) | Given a `ProjectInfo` instance, provides a key prefix for where that project should be in settings registry. | [code](https://github.com/o3de/o3de/blob/7d716a4a21afd217444d91043ea810f6c8a38f21/Code/Tools/ProjectManager/Source/Settings.cpp#L134-L137) | +| [`SettingsInterface::GetProjectBuiltSuccessfully`](https://github.com/o3de/o3de/blob/69dbcd08a56539315bfb0472984daf0f46e7a966/Code/Tools/ProjectManager/Source/SettingsInterface.h#L84-L90) | Queries the latest build status of a given project, if successful or not. | [code](https://github.com/o3de/o3de/blob/7d716a4a21afd217444d91043ea810f6c8a38f21/Code/Tools/ProjectManager/Source/Settings.cpp#L144-L163) | +| [`SettingsInterface::SetProjectBuiltSuccessfully`](https://github.com/o3de/o3de/blob/69dbcd08a56539315bfb0472984daf0f46e7a966/Code/Tools/ProjectManager/Source/SettingsInterface.h#L84-L90) | Sets the latest build status of a given project, if successful or not. | [code](https://github.com/o3de/o3de/blob/7d716a4a21afd217444d91043ea810f6c8a38f21/Code/Tools/ProjectManager/Source/Settings.cpp#L165-L187) | + +All of these functions are pure virtual functions, which require implementation in a base implementation class, otherwise it results in a compilation error, thereby enforcing the contract. + +The [`Settings`](https://github.com/o3de/o3de/blob/development/Code/Tools/ProjectManager/Source/Settings.h) class [inherits](https://github.com/o3de/o3de/blob/69dbcd08a56539315bfb0472984daf0f46e7a966/Code/Tools/ProjectManager/Source/Settings.h#L23-L24) `SettingsInterface` which uses [`AZ::SettingsRegistryInterface`](https://github.com/o3de/o3de/blob/b79bd3df1fe5d4c2a639d3921a29bd0d95712f6c/Code/Tools/ProjectManager/Source/Settings.h#L48) under the hood to interact with the O3DE Settings Registry. + +This mirrors JSON so that values can be retrieved by key paths. For example, take a .setreg like: +``` +{ + key:{ + subkey:{ + subsubkey:"value" + } + } +} +``` +Then the value can be retrieved using the string key `key/subkey/subsubkey`. + +The `ProjectManager::SettingsInterface` is similar to `AZ::SettingsRegistryInterface`, except it overrides some of the behavior to look for configuration specific to Project Manager, instead of O3DE as a whole. It's also modified to work with `QString`, which the `AZ` counterpart does not handle. + +The `Settings` class inherits from `SettingsInterface::Registrar`. The [`Registrar`](https://github.com/o3de/o3de/blob/b79bd3df1fe5d4c2a639d3921a29bd0d95712f6c/Code/Framework/AzCore/AzCore/Interface/Interface.h#L100-L106) is part of the `AZ::Interface` in `AzCore`. + +The [implementation](https://github.com/o3de/o3de/blob/b79bd3df1fe5d4c2a639d3921a29bd0d95712f6c/Code/Framework/AzCore/AzCore/Interface/Interface.h#L202-L212) of `Registrar` registers the interface globally, which indicates the singleton pattern. + +Here are the remaining functions that `Settings` also provides: +| Function | Description | +| - | - | +| [`Settings::Save`](https://github.com/o3de/o3de/blob/69dbcd08a56539315bfb0472984daf0f46e7a966/Code/Tools/ProjectManager/Source/Settings.cpp#L25-L55) | Dumps the settings registry into a string stream. Then tries to open the `ProjectManager.setreg` file in the O3DE user path, and write the stream data into that file. | +| [`Settings::GetBuiltSuccessfullyPaths`](https://github.com/o3de/o3de/blob/69dbcd08a56539315bfb0472984daf0f46e7a966/Code/Tools/ProjectManager/Source/Settings.cpp#L139-L142) | For each project path requested, fetches the build status. Returns the result as a set. | + +[Back to Data Classes](#data-classes) \ No newline at end of file From d26dd48d86cc03374650dbc7355b0abfe8f2725b Mon Sep 17 00:00:00 2001 From: TJ Kotha Date: Wed, 15 Mar 2023 23:38:14 -0400 Subject: [PATCH 2/3] added @willihay's suggestions for reorganizing the source code map into sub-pages Signed-off-by: TJ Kotha --- .../project-manager/source-code-map/_index.md | 21 +++++ .../source-code-map/data-classes.md | 78 ++++++++++++++++++ .../startup-and-screen-management.md} | 81 ++----------------- 3 files changed, 106 insertions(+), 74 deletions(-) create mode 100644 content/docs/engine-dev/tools/project-manager/source-code-map/_index.md create mode 100644 content/docs/engine-dev/tools/project-manager/source-code-map/data-classes.md rename content/docs/engine-dev/tools/project-manager/{source-code-map.md => source-code-map/startup-and-screen-management.md} (66%) diff --git a/content/docs/engine-dev/tools/project-manager/source-code-map/_index.md b/content/docs/engine-dev/tools/project-manager/source-code-map/_index.md new file mode 100644 index 00000000000..ad4e9bf885e --- /dev/null +++ b/content/docs/engine-dev/tools/project-manager/source-code-map/_index.md @@ -0,0 +1,21 @@ +--- +linkTitle: Source Code Map +title: Source Code Map +description: Summaries of classes and code files in Project Manager +--- + +{{< note >}} +This information is for developers of the **Project Manager** tool. If you're a user working with Project Manager, please refer to the [Project Manager User Guide](/docs/user-guide/project-config/project-manager). +{{< /note >}} + +{{< note >}} +This contains brief summaries of various class's functionality and role. If available, there are additional links in the table of contents, either with expanded information, or github links. All documentation reflects code as of commit [(b79bd3df1f)](https://github.com/o3de/o3de/tree/b79bd3df1fe5d4c2a639d3921a29bd0d95712f6c) +{{< /note >}} + +## Overview +| Section | Description | +| - | - | +| [Startup and Screen Management](./startup-and-screen-management) | Describes the start up boot sequence and overall screen management of Project Manager.| +| [Data Classes](./data-classes) | Simple classes that house various data structures used by Project Manager.| + + diff --git a/content/docs/engine-dev/tools/project-manager/source-code-map/data-classes.md b/content/docs/engine-dev/tools/project-manager/source-code-map/data-classes.md new file mode 100644 index 00000000000..ebb3bc59b30 --- /dev/null +++ b/content/docs/engine-dev/tools/project-manager/source-code-map/data-classes.md @@ -0,0 +1,78 @@ +--- +linkTitle: Data Classes +title: Data Classes +description: Classes that describe various data maintained in Project Manager +--- + +{{< note >}} +This information is for developers of the **Project Manager** tool. If you're a user working with Project Manager, please refer to the [Project Manager User Guide](/docs/user-guide/project-config/project-manager). +{{< /note >}} + +{{< note >}} +This contains brief summaries of various class's functionality and role. If available, there are additional links in the table of contents, either with expanded information, or github links. All documentation reflects code as of commit [(b79bd3df1f)](https://github.com/o3de/o3de/tree/b79bd3df1fe5d4c2a639d3921a29bd0d95712f6c) +{{< /note >}} + + + + +## Overview + +| Class | Source Code | Description | +| - | - | - | +| TemplateInfo | [header](https://github.com/o3de/o3de/blob/development/Code/Tools/ProjectManager/Source/TemplateInfo.h) [cpp file](https://github.com/o3de/o3de/blob/development/Code/Tools/ProjectManager/Source/TemplateInfo.cpp) | Describes data fields to encapsulate a generic Template. | +| ProjectTemplateInfo | [header](https://github.com/o3de/o3de/blob/development/Code/Tools/ProjectManager/Source/ProjectTemplateInfo.h) | Subclass of Template specific to Projects. Only difference is that this one includes Gems. | +| SettingsInterface | [header](https://github.com/o3de/o3de/blob/development/Code/Tools/ProjectManager/Source/SettingsInterface.h) | Interface for interacting with the O3DE Settings Registry. | +| [Settings](#settings) | [header](https://github.com/o3de/o3de/blob/development/Code/Tools/ProjectManager/Source/Settings.h) [cpp file](https://github.com/o3de/o3de/blob/development/Code/Tools/ProjectManager/Source/Settings.cpp) | Implementation for `SettingsInterface` to interact with O3DE Settings Registry. | +| ProjectInfo | [header](https://github.com/o3de/o3de/blob/development/Code/Tools/ProjectManager/Source/ProjectInfo.h) [cpp file](https://github.com/o3de/o3de/blob/development/Code/Tools/ProjectManager/Source/ProjectInfo.cpp) | Contains data structure to describe a project, as recorded in project.json, inside `ProjectManager`. Also contains metadata for remote projects, or for checking if a project needs to be rebuilt. | +| EngineInfo | [header](https://github.com/o3de/o3de/blob/development/Code/Tools/ProjectManager/Source/EngineInfo.h) [cpp file](https://github.com/o3de/o3de/blob/development/Code/Tools/ProjectManager/Source/EngineInfo.cpp) | Contains data structure to describe the current engine, as recorded in engine.json, inside `ProjectManager`. Also contains metadata for engine registration. | +| ProjectManagerDefs | [header](https://github.com/o3de/o3de/blob/development/Code/Tools/ProjectManager/Source/ProjectManagerDefs.h) | Contains various constants and preset strings. | + + + + + + +### Settings + +We specify the `SettingsInterface` as a contract to ensure we implement the proper methods, and to enable global access to settings from a clean interface ([one example](https://github.com/o3de/o3de/blob/b79bd3df1fe5d4c2a639d3921a29bd0d95712f6c/Code/Tools/ProjectManager/Source/ExternalLinkDialog.cpp#L88)). It also acts as a singleton interface for accessing Project Manager settings. + +`SettingsInterface` specifies the following functions as the contract to interact with O3DE Settings Registry: +| Function | Description | Implementation | +| - | - | - | +| [`SettingsInterface::Get`](https://github.com/o3de/o3de/blob/69dbcd08a56539315bfb0472984daf0f46e7a966/Code/Tools/ProjectManager/Source/SettingsInterface.h#L31-L44) | Using a `QString` key, can either return the string or bool value. | [code](https://github.com/o3de/o3de/blob/7d716a4a21afd217444d91043ea810f6c8a38f21/Code/Tools/ProjectManager/Source/Settings.cpp#L65-L79) | +| [`SettingsInterface::Set`](https://github.com/o3de/o3de/blob/69dbcd08a56539315bfb0472984daf0f46e7a966/Code/Tools/ProjectManager/Source/SettingsInterface.h#L46-L59) | Using a `QString` key, can either set a string or bool value for an entry. | [code](https://github.com/o3de/o3de/blob/7d716a4a21afd217444d91043ea810f6c8a38f21/Code/Tools/ProjectManager/Source/Settings.cpp#L81-L99) | +| [`SettingsInterface::Remove`](https://github.com/o3de/o3de/blob/69dbcd08a56539315bfb0472984daf0f46e7a966/Code/Tools/ProjectManager/Source/SettingsInterface.h#L61-L66) | Removes a entry with `QString` key from the registry. | [code](https://github.com/o3de/o3de/blob/7d716a4a21afd217444d91043ea810f6c8a38f21/Code/Tools/ProjectManager/Source/Settings.cpp#L101-L109) | +| [`SettingsInterface::Copy`](https://github.com/o3de/o3de/blob/69dbcd08a56539315bfb0472984daf0f46e7a966/Code/Tools/ProjectManager/Source/SettingsInterface.h#L68-L75) | Copies the value from one key to another. Can also optionally remove the original entry, acting as a "Move" command. | [code](https://github.com/o3de/o3de/blob/7d716a4a21afd217444d91043ea810f6c8a38f21/Code/Tools/ProjectManager/Source/Settings.cpp#L111-L132) | +| [`SettingsInterface::GetProjectKey`](https://github.com/o3de/o3de/blob/69dbcd08a56539315bfb0472984daf0f46e7a966/Code/Tools/ProjectManager/Source/SettingsInterface.h#L77-L82) | Given a `ProjectInfo` instance, provides a key prefix for where that project should be in settings registry. | [code](https://github.com/o3de/o3de/blob/7d716a4a21afd217444d91043ea810f6c8a38f21/Code/Tools/ProjectManager/Source/Settings.cpp#L134-L137) | +| [`SettingsInterface::GetProjectBuiltSuccessfully`](https://github.com/o3de/o3de/blob/69dbcd08a56539315bfb0472984daf0f46e7a966/Code/Tools/ProjectManager/Source/SettingsInterface.h#L84-L90) | Queries the latest build status of a given project, if successful or not. | [code](https://github.com/o3de/o3de/blob/7d716a4a21afd217444d91043ea810f6c8a38f21/Code/Tools/ProjectManager/Source/Settings.cpp#L144-L163) | +| [`SettingsInterface::SetProjectBuiltSuccessfully`](https://github.com/o3de/o3de/blob/69dbcd08a56539315bfb0472984daf0f46e7a966/Code/Tools/ProjectManager/Source/SettingsInterface.h#L91-L97) | Sets the latest build status of a given project, if successful or not. | [code](https://github.com/o3de/o3de/blob/7d716a4a21afd217444d91043ea810f6c8a38f21/Code/Tools/ProjectManager/Source/Settings.cpp#L165-L187) | + +All of these functions are pure virtual functions, which require implementation in a base implementation class, otherwise it results in a compilation error, thereby enforcing the contract. + +The [`Settings`](https://github.com/o3de/o3de/blob/development/Code/Tools/ProjectManager/Source/Settings.h) class [inherits](https://github.com/o3de/o3de/blob/69dbcd08a56539315bfb0472984daf0f46e7a966/Code/Tools/ProjectManager/Source/Settings.h#L23-L24) `SettingsInterface` which uses [`AZ::SettingsRegistryInterface`](https://github.com/o3de/o3de/blob/b79bd3df1fe5d4c2a639d3921a29bd0d95712f6c/Code/Tools/ProjectManager/Source/Settings.h#L48) under the hood to interact with the O3DE Settings Registry. + +This mirrors JSON so that values can be retrieved by key paths. For example, take a .setreg like: +``` +{ + key:{ + subkey:{ + subsubkey:"value" + } + } +} +``` +Then the value can be retrieved using the string key `key/subkey/subsubkey`. + +The `ProjectManager::SettingsInterface` is similar to `AZ::SettingsRegistryInterface`, except it overrides some of the behavior to look for configuration specific to Project Manager, instead of O3DE as a whole. It's also modified to work with `QString`, which the `AZ` counterpart does not handle. + +The `Settings` class inherits from `SettingsInterface::Registrar`. The [`Registrar`](https://github.com/o3de/o3de/blob/b79bd3df1fe5d4c2a639d3921a29bd0d95712f6c/Code/Framework/AzCore/AzCore/Interface/Interface.h#L100-L106) is part of the `AZ::Interface` in `AzCore`. + +The [implementation](https://github.com/o3de/o3de/blob/b79bd3df1fe5d4c2a639d3921a29bd0d95712f6c/Code/Framework/AzCore/AzCore/Interface/Interface.h#L202-L212) of `Registrar` registers the interface globally, which indicates the singleton pattern. + +Here are the remaining functions that `Settings` also provides: +| Function | Description | +| - | - | +| [`Settings::Save`](https://github.com/o3de/o3de/blob/69dbcd08a56539315bfb0472984daf0f46e7a966/Code/Tools/ProjectManager/Source/Settings.cpp#L25-L55) | Dumps the settings registry into a string stream. Then tries to open the `ProjectManager.setreg` file in the O3DE user path, and write the stream data into that file. | +| [`Settings::GetBuiltSuccessfullyPaths`](https://github.com/o3de/o3de/blob/69dbcd08a56539315bfb0472984daf0f46e7a966/Code/Tools/ProjectManager/Source/Settings.cpp#L139-L142) | For each project path requested, fetches the build status. Returns the result as a set. | + +[Back to Overview](#overview) \ No newline at end of file diff --git a/content/docs/engine-dev/tools/project-manager/source-code-map.md b/content/docs/engine-dev/tools/project-manager/source-code-map/startup-and-screen-management.md similarity index 66% rename from content/docs/engine-dev/tools/project-manager/source-code-map.md rename to content/docs/engine-dev/tools/project-manager/source-code-map/startup-and-screen-management.md index 50c0cd621fa..79b68dcd4d0 100644 --- a/content/docs/engine-dev/tools/project-manager/source-code-map.md +++ b/content/docs/engine-dev/tools/project-manager/source-code-map/startup-and-screen-management.md @@ -1,7 +1,7 @@ --- -linkTitle: Source Code Map -title: Source Code Map -description: Summaries of classes and code files in Project Manager +linkTitle: Startup and Screen Management Classes +title: Startup and Screen Management Classes +description: Classes that facilitate Project Manager startup, and screen transition logic --- {{< note >}} @@ -13,12 +13,6 @@ This contains brief summaries of various class's functionality and role. If avai {{< /note >}} ## Overview -| Section | Description | -| - | - | -| [Startup and Screen Management](#startup-and-screen-management) | Describes the start up boot sequence and overall screen management of Project Manager.| -| [Data Classes](#data-classes) | Simple classes that house various data structures used by Project Manager.| - -### Startup and Screen Management | Class | Source Code | Description | | - | - | - | @@ -30,21 +24,6 @@ This contains brief summaries of various class's functionality and role. If avai |ScreenDefs | [header](https://github.com/o3de/o3de/blob/development/Code/Tools/ProjectManager/Source/ScreenDefs.h) | Contains definitions for `ProjectManagerScreen` enum, which describes all possible types of screens in Project Manager. It also defines a hash function, and a mapping to appropriate string equivalents for each enum.| |[ScreenWidget](#screenwidget) | [header](https://github.com/o3de/o3de/blob/development/Code/Tools/ProjectManager/Source/ScreenWidget.h) | The parent class to all screens in Project Manager. It contains all necessary stubs for screen management and transition. `ScreensCtrl` is defined in terms of `ScreenWidget`, so that all transition logic is polymorphic.| -[Back to Overview](#overview) - -### Data Classes - -| Class | Source Code | Description | -| - | - | - | -| TemplateInfo | [header](https://github.com/o3de/o3de/blob/development/Code/Tools/ProjectManager/Source/TemplateInfo.h) [cpp file](https://github.com/o3de/o3de/blob/development/Code/Tools/ProjectManager/Source/TemplateInfo.cpp) | Describes data fields to encapsulate a generic Template. | -| ProjectTemplateInfo | [header](https://github.com/o3de/o3de/blob/development/Code/Tools/ProjectManager/Source/ProjectTemplateInfo.h) | Subclass of Template specific to Projects. Only difference is that this one includes Gems. | -| SettingsInterface | [header](https://github.com/o3de/o3de/blob/development/Code/Tools/ProjectManager/Source/SettingsInterface.h) | Interface for interacting with the O3DE Settings Registry. | -| [Settings](#settings) | [header](https://github.com/o3de/o3de/blob/development/Code/Tools/ProjectManager/Source/Settings.h) [cpp file](https://github.com/o3de/o3de/blob/development/Code/Tools/ProjectManager/Source/Settings.cpp) | Implementation for `SettingsInterface` to interact with O3DE Settings Registry. | -| ProjectInfo | [header](https://github.com/o3de/o3de/blob/development/Code/Tools/ProjectManager/Source/ProjectInfo.h) [cpp file](https://github.com/o3de/o3de/blob/development/Code/Tools/ProjectManager/Source/ProjectInfo.cpp) | Contains data structure to describe a project, as recorded in project.json, inside `ProjectManager`. Also contains metadata for remote projects, or for checking if a project needs to be rebuilt. | -| EngineInfo | [header](https://github.com/o3de/o3de/blob/development/Code/Tools/ProjectManager/Source/EngineInfo.h) [cpp file](https://github.com/o3de/o3de/blob/development/Code/Tools/ProjectManager/Source/EngineInfo.cpp) | Contains data structure to describe the current engine, as recorded in engine.json, inside `ProjectManager`. Also contains metadata for engine registration. | -| ProjectManagerDefs | [header](https://github.com/o3de/o3de/blob/development/Code/Tools/ProjectManager/Source/ProjectManagerDefs.h) | Contains various constants and preset strings. | - -[Back to Overview](#overview) ### Application @@ -70,7 +49,7 @@ The two primary functions to keep track of are `Init` and `Run`. [`TearDown`](ht * Shows the MainWindow. * Run the QApplication's main loop. -[Back to Startup and Screen Management](#startup-and-screen-management) +[Back to Overview](#overview) @@ -87,7 +66,7 @@ All logic unique to the Project Manager occurs at the constructor, which is summ * If `startScreen` is set, first force load the main Projects screen, then transition to the desired screen. If not set, the Projects screen is the default. * If `projectPath` is set, notify the `ScreensCtrl` instance of the currently highlighted project path. -[Back to Startup and Screen Management](#startup-and-screen-management) +[Back to Overview](#overview) @@ -140,7 +119,7 @@ All functions are summarized as follows: * Update `m_screenMap` with pointer to the new screen. * Connect slots for transition functions for new screen. -[Back to Startup and Screen Management](#startup-and-screen-management) +[Back to Overview](#overview) ### ScreenWidget @@ -159,50 +138,4 @@ If you were to check the header file, it would only contain stub functions. In t `ScreenWidget` also defines various Qt [`signals`](https://github.com/o3de/o3de/blob/99f713702e5e0a8949e38c7b92bf00682c2633ca/Code/Tools/ProjectManager/Source/ScreenWidget.h#L65-L70) that are used to facilitate transitions by connecting to Qt [`slots`](https://github.com/o3de/o3de/blob/99f713702e5e0a8949e38c7b92bf00682c2633ca/Code/Tools/ProjectManager/Source/ScreensCtrl.cpp#L201-L205) as defined in `ScreensCtrl::ResetScreen`. -[Back to Startup and Screen Management](#startup-and-screen-management) - - -### Settings - -We specify the `SettingsInterface` as a contract to ensure we implement the proper methods, and to enable global access to settings from a clean interface ([one example](https://github.com/o3de/o3de/blob/b79bd3df1fe5d4c2a639d3921a29bd0d95712f6c/Code/Tools/ProjectManager/Source/ExternalLinkDialog.cpp#L88)). It also acts as a singleton interface for accessing Project Manager settings. - -`SettingsInterface` specifies the following functions as the contract to interact with O3DE Settings Registry: -| Function | Description | Implementation | -| - | - | - | -| [`SettingsInterface::Get`](https://github.com/o3de/o3de/blob/69dbcd08a56539315bfb0472984daf0f46e7a966/Code/Tools/ProjectManager/Source/SettingsInterface.h#L31-L44) | Using a `QString` key, can either return the string or bool value. | [code](https://github.com/o3de/o3de/blob/7d716a4a21afd217444d91043ea810f6c8a38f21/Code/Tools/ProjectManager/Source/Settings.cpp#L65-L79) | -| [`SettingsInterface::Set`](https://github.com/o3de/o3de/blob/69dbcd08a56539315bfb0472984daf0f46e7a966/Code/Tools/ProjectManager/Source/SettingsInterface.h#L46-L59) | Using a `QString` key, can either set a string or bool value for an entry. | [code](https://github.com/o3de/o3de/blob/7d716a4a21afd217444d91043ea810f6c8a38f21/Code/Tools/ProjectManager/Source/Settings.cpp#L81-L99) | -| [`SettingsInterface::Remove`](https://github.com/o3de/o3de/blob/69dbcd08a56539315bfb0472984daf0f46e7a966/Code/Tools/ProjectManager/Source/SettingsInterface.h#L61-L66) | Removes a entry with `QString` key from the registry. | [code](https://github.com/o3de/o3de/blob/7d716a4a21afd217444d91043ea810f6c8a38f21/Code/Tools/ProjectManager/Source/Settings.cpp#L101-L109) | -| [`SettingsInterface::Copy`](https://github.com/o3de/o3de/blob/69dbcd08a56539315bfb0472984daf0f46e7a966/Code/Tools/ProjectManager/Source/SettingsInterface.h#L68-L75) | Copies the value from one key to another. Can also optionally remove the original entry, acting as a "Move" command. | [code](https://github.com/o3de/o3de/blob/7d716a4a21afd217444d91043ea810f6c8a38f21/Code/Tools/ProjectManager/Source/Settings.cpp#L111-L132) | -| [`SettingsInterface::GetProjectKey`](https://github.com/o3de/o3de/blob/69dbcd08a56539315bfb0472984daf0f46e7a966/Code/Tools/ProjectManager/Source/SettingsInterface.h#L77-L82) | Given a `ProjectInfo` instance, provides a key prefix for where that project should be in settings registry. | [code](https://github.com/o3de/o3de/blob/7d716a4a21afd217444d91043ea810f6c8a38f21/Code/Tools/ProjectManager/Source/Settings.cpp#L134-L137) | -| [`SettingsInterface::GetProjectBuiltSuccessfully`](https://github.com/o3de/o3de/blob/69dbcd08a56539315bfb0472984daf0f46e7a966/Code/Tools/ProjectManager/Source/SettingsInterface.h#L84-L90) | Queries the latest build status of a given project, if successful or not. | [code](https://github.com/o3de/o3de/blob/7d716a4a21afd217444d91043ea810f6c8a38f21/Code/Tools/ProjectManager/Source/Settings.cpp#L144-L163) | -| [`SettingsInterface::SetProjectBuiltSuccessfully`](https://github.com/o3de/o3de/blob/69dbcd08a56539315bfb0472984daf0f46e7a966/Code/Tools/ProjectManager/Source/SettingsInterface.h#L84-L90) | Sets the latest build status of a given project, if successful or not. | [code](https://github.com/o3de/o3de/blob/7d716a4a21afd217444d91043ea810f6c8a38f21/Code/Tools/ProjectManager/Source/Settings.cpp#L165-L187) | - -All of these functions are pure virtual functions, which require implementation in a base implementation class, otherwise it results in a compilation error, thereby enforcing the contract. - -The [`Settings`](https://github.com/o3de/o3de/blob/development/Code/Tools/ProjectManager/Source/Settings.h) class [inherits](https://github.com/o3de/o3de/blob/69dbcd08a56539315bfb0472984daf0f46e7a966/Code/Tools/ProjectManager/Source/Settings.h#L23-L24) `SettingsInterface` which uses [`AZ::SettingsRegistryInterface`](https://github.com/o3de/o3de/blob/b79bd3df1fe5d4c2a639d3921a29bd0d95712f6c/Code/Tools/ProjectManager/Source/Settings.h#L48) under the hood to interact with the O3DE Settings Registry. - -This mirrors JSON so that values can be retrieved by key paths. For example, take a .setreg like: -``` -{ - key:{ - subkey:{ - subsubkey:"value" - } - } -} -``` -Then the value can be retrieved using the string key `key/subkey/subsubkey`. - -The `ProjectManager::SettingsInterface` is similar to `AZ::SettingsRegistryInterface`, except it overrides some of the behavior to look for configuration specific to Project Manager, instead of O3DE as a whole. It's also modified to work with `QString`, which the `AZ` counterpart does not handle. - -The `Settings` class inherits from `SettingsInterface::Registrar`. The [`Registrar`](https://github.com/o3de/o3de/blob/b79bd3df1fe5d4c2a639d3921a29bd0d95712f6c/Code/Framework/AzCore/AzCore/Interface/Interface.h#L100-L106) is part of the `AZ::Interface` in `AzCore`. - -The [implementation](https://github.com/o3de/o3de/blob/b79bd3df1fe5d4c2a639d3921a29bd0d95712f6c/Code/Framework/AzCore/AzCore/Interface/Interface.h#L202-L212) of `Registrar` registers the interface globally, which indicates the singleton pattern. - -Here are the remaining functions that `Settings` also provides: -| Function | Description | -| - | - | -| [`Settings::Save`](https://github.com/o3de/o3de/blob/69dbcd08a56539315bfb0472984daf0f46e7a966/Code/Tools/ProjectManager/Source/Settings.cpp#L25-L55) | Dumps the settings registry into a string stream. Then tries to open the `ProjectManager.setreg` file in the O3DE user path, and write the stream data into that file. | -| [`Settings::GetBuiltSuccessfullyPaths`](https://github.com/o3de/o3de/blob/69dbcd08a56539315bfb0472984daf0f46e7a966/Code/Tools/ProjectManager/Source/Settings.cpp#L139-L142) | For each project path requested, fetches the build status. Returns the result as a set. | - -[Back to Data Classes](#data-classes) \ No newline at end of file +[Back to Overview](#overview) \ No newline at end of file From 4a3543a74a15eeb20d36379bf332aa96314e8e70 Mon Sep 17 00:00:00 2001 From: TJ Kotha Date: Thu, 16 Mar 2023 12:49:58 -0400 Subject: [PATCH 3/3] addressing minor feedback for source code map Signed-off-by: TJ Kotha --- .../project-manager/source-code-map/data-classes.md | 9 +++++---- .../source-code-map/startup-and-screen-management.md | 1 + 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/content/docs/engine-dev/tools/project-manager/source-code-map/data-classes.md b/content/docs/engine-dev/tools/project-manager/source-code-map/data-classes.md index ebb3bc59b30..10e194e0d16 100644 --- a/content/docs/engine-dev/tools/project-manager/source-code-map/data-classes.md +++ b/content/docs/engine-dev/tools/project-manager/source-code-map/data-classes.md @@ -2,6 +2,7 @@ linkTitle: Data Classes title: Data Classes description: Classes that describe various data maintained in Project Manager +weight: 200 --- {{< note >}} @@ -52,11 +53,11 @@ All of these functions are pure virtual functions, which require implementation The [`Settings`](https://github.com/o3de/o3de/blob/development/Code/Tools/ProjectManager/Source/Settings.h) class [inherits](https://github.com/o3de/o3de/blob/69dbcd08a56539315bfb0472984daf0f46e7a966/Code/Tools/ProjectManager/Source/Settings.h#L23-L24) `SettingsInterface` which uses [`AZ::SettingsRegistryInterface`](https://github.com/o3de/o3de/blob/b79bd3df1fe5d4c2a639d3921a29bd0d95712f6c/Code/Tools/ProjectManager/Source/Settings.h#L48) under the hood to interact with the O3DE Settings Registry. This mirrors JSON so that values can be retrieved by key paths. For example, take a .setreg like: -``` +```json { - key:{ - subkey:{ - subsubkey:"value" + "key":{ + "subkey":{ + "subsubkey":"value" } } } diff --git a/content/docs/engine-dev/tools/project-manager/source-code-map/startup-and-screen-management.md b/content/docs/engine-dev/tools/project-manager/source-code-map/startup-and-screen-management.md index 79b68dcd4d0..49272891d7a 100644 --- a/content/docs/engine-dev/tools/project-manager/source-code-map/startup-and-screen-management.md +++ b/content/docs/engine-dev/tools/project-manager/source-code-map/startup-and-screen-management.md @@ -2,6 +2,7 @@ linkTitle: Startup and Screen Management Classes title: Startup and Screen Management Classes description: Classes that facilitate Project Manager startup, and screen transition logic +weight: 100 --- {{< note >}}