IN THIS ARTICLE

Startup and Screen Management Classes

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.

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)

Overview

Class	Source Code	Description
main.cpp	cpp file	Entry point for the Project Manager. Initiates the Application main loop .
Application	header cpp file	Houses core startup code and configuration loading for Qt framework, Logging, Python Bindngs and O3DE Engine Registration. Facilitates prior housework to starting up the application main loop, and clean up when tearing down.
ProjectManagerWindow	header cpp file	Constructs the application’s `QMainWindow` and `DownloadController`, and prepares all relevant transition screens for the Project Manager.
ScreensCtrl	header cpp file	Container structure for all Project Manager Screens and GUI Widgets. Also houses primary transition code for facilitating Project Manager’s business logic.
ScreenFactory	header cpp file	Helper class for `ScreensCtrl` that routes `ProjectManagerScreen` enums to appropriate `ScreenWidget` constructor, invokes that constructor, and returns an instance of a given screen for the Project Manager’s business logic.
ScreenDefs	header	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	header	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.

Application

Inherits from AzFramework::Application.

The functions of the Application class are exclusively run by main.cpp.

The two primary functions to keep track of are Init and Run. TearDown is invoked at Application’s deconstruction.

`Application::Init`

Sets various QApplication and QCoreApplication attributes and parameters.
Registers components for system logging, and invokes InitLog .
Creates new instance of QApplication, feeding in command line arguments.
Sets up PythonBindings.
Calls RegisterEngine to setup the O3DE engine that Project Manager ships with.
Gets connection to CommandLine, and parses for screen and projectPath parameters.
Creates ProjectManagerWindow.

`Application::Run`

Sets up Qt GUI stylesheets.
Sets up Window decoration and MainWindow Geometry.
Shows the MainWindow.
Run the QApplication’s main loop.

Back to Overview

ProjectManagerWindow

This inherits all primary functionality from QMainWindow.

All logic unique to the Project Manager occurs at the constructor, which is summarized as follows:

Fetch Engine Info to set Window Title with correct engine version information.
Instantiate the DownloadController.
Instantiate the ScreensCtrl for screen management.
Construct a list of relevant ProjectManagerScreen enums, and use ScreensCtrl to construct each screen widget for Project Manager’s GUI.
Set instance of ScreensCtrl as central widget of the window.
Retrieve passed in arguments for startScreen and projectPath.
- 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 Overview

ScreensCtrl

ScreensCtrl is the central widget which stores all GUI information for Project Manager. It is comprised of these data structures:

m_screenMap - used to access all available Screens in Project Manager.
m_screenStack - stores all screens in a QStackedWidget.
m_tabWidget - The three primary tabs of Project Manager (Project, Gem, and Engine), are stored here. This tab widget, in turn, is stored as the first element of m_screenStack.
m_screenVisitOrder - Traversal history through the screens of ProjectManager can be tracked using this.

All functions are summarized as follows:

Function	Description
`ScreensCtrl::ScreensCtrl`	Sets up primary screen layout. `m_tabWidget` is the first widget pushed to `m_screenStack`.
`ScreensCtrl::BuildScreens`	For each requested screen, calls `ResetScreen`. Because this is called at the beginning of Application life cycle, this will trigger initialization logic in `ResetScreen`.
`ScreensCtrl::FindScreen`	Searches for the pointer to the `ScreenWidget` of the requested `ProjectManagerScreen` enum and returns it if found. Otherwise returns a `nullptr`.
`ScreensCtrl::GetCurrentScreen`	First checks if the current widget in `m_screenStack` is `m_tabWidget`. If so, it returns the current tab of `m_tabWidget`. Otherwise it returns whatever the current widget of `m_screenStack` is.
`ScreensCtrl::ChangeToScreen`	If able, we transition to the desired screen using `ForceChangeToScreen`.
`ScreensCtrl::ForceChangeToScreen`	Driver code to change screen GUIs in Project Manager. More info can be found below
`ScreensCtrl::GoToPreviousScreen`	If `m_screenVisitOrder` is not empty, we call `ForceChangeToScreen` by popping `m_screenVisitOrder`.
`ScreensCtrl::ResetScreen`	Deletes the old screen, and recreates it. More info can be found below
`ScreensCtrl::ResetAllScreens`	Call `ResetScreen` for every screen.
`ScreensCtrl::DeleteScreen`	If screen can be found in `m_screenMap`, we proceed to delete the screen either from `m_tabWidget` if it is a tab, or from `m_screenStack` otherwise. Afterwards we erase the entry from `m_screenMap`.
`ScreensCtrl::DeleteAllScreens`	Call `DeleteScreen` for all screens.
`ScreensCtrl::TabChanged`	A Slot function , which is invoked anytime `m_tabWidget` changes tabs. This just causes the current tab to refresh itself via `NotifyCurrentScreen`.
`ScreensCtrl::GetScreenTabIndex`	Retrieves the index position of the screen in `m_tabWidget` if it is a tab screen, otherwise returns -1.

In-Depth Explanations

`ScreensCtrl::ForceChangeToScreen`

First we search for the desired screen in m_screenMap.
If we can find it, then if it is already the current screen, we run NotifyCurrentScreen to refresh it.
Otherwise we set the current widget of m_screenStack (and m_tabWidget if the desired screen is one of the main tabs).
- If we are tracking previous visits, we make sure to update m_screenVisitOrder as well.
Finally we run NotifyCurrentScreen and GoToScreen to prepare for our arrival.

`ScreensCtrl::ResetScreen`

Delete the old screen using DeleteScreen.
Rebuild screen using ScreenFactory::BuildScreen .
If the screen is supposed to be a Tab.
- Update m_tabWidget with screen.
- Update current widget for m_tabWidget and m_screenStack.
- If we should restore the screen, call NotifyCurrentScreen.
Otherwise add the screen to m_screenStack and set the current widget.
- NotifyCurrentScreen for newly created screen.
Update m_screenMap with pointer to the new screen.
Connect slots for transition functions for new screen.

Back to Overview

ScreenWidget

If you were to check the header file, it would only contain stub functions. In this section we will explain the high level purpose of each function, so that it’s easier to recognize what the subclasses are doing when they override a given function.

Function	Description
`ScreenWidget::GetScreenEnum`	Each subclass of `ScreenWidget` will use this function to define what type of screen is currently active.
`ScreenWidget::IsReadyForNextScreen`	Meant to validate if a given screen is ready for a transition , or if it must pause for some reason (for example, an uninterruptable task is taking place). Currently it is unused.
`ScreenWidget::IsTab`	This function declares if a given screen is a tab in the `m_tabWidget` data structure. This is used to process tabs as an edgecase in `ScreensCtrl::ForceChangeToScreen` and `ScreensCtrl::DeleteScreen` . The classes which override this function are `GemCatalogScreen` , `ProjectsScreen` , `ProjectGemCatalogScreen` , and `EngineScreenCtrl` .
`ScreenWidget::GetTabText`	Gets the corresponding string value of a tab screen, if defined by the subclass.
`ScreenWidget::ContainsScreen`	There exist some screens in Project Manager, like `EngineScreenCtrl` , that contain other smaller screens inside of them. This can be used to check if a given screen exists inside of a parent screen.
`ScreenWidget::GoToScreen`	Defines a transition function where the subclass decides whether or not to move onto a certain screen.
`ScreenWidget::Init`	This function occurs shortly after a screen’s constructor runs in `ScreenFactory::BuildScreen` . This is meant to setup any hooks into the system that cannot be done at construction time. Two examples of this can be found in `CreateAGemScreen` and `EditAGemScreen` , the reasoning of which can be found here .
`ScreenWidget::NotifyCurrentScreen`	A function that is called anytime the screen needs to refresh itself. All necessary refresh logic should be expressed here.

ScreenWidget also defines various Qt signals that are used to facilitate transitions by connecting to Qt slots as defined in ScreensCtrl::ResetScreen.

Back to Overview