Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

updated project manager source code map to include data classes and settings #2304

Merged
merged 3 commits into from
Mar 16, 2023
Merged

updated project manager source code map to include data classes and settings #2304

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
1405ed0
updated project manager source code map to include data classes and s…
Mar 8, 2023
d26dd48
added @willihay's suggestions for reorganizing the source code map in…
Mar 16, 2023
4a3543a
addressing minor feedback for source code map
Mar 16, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
78 changes: 72 additions & 6 deletions content/docs/engine-dev/tools/project-manager/source-code-map.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
| - | - | - |
Expand All @@ -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
tkothadev marked this conversation as resolved.
Show resolved Hide resolved

| 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`.
Expand All @@ -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)



Expand All @@ -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)



Expand Down Expand Up @@ -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
Expand All @@ -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)
[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) |
tkothadev marked this conversation as resolved.
Show resolved Hide resolved

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)