Startup and Screen Management Classes

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.
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)


ClassSource CodeDescription
main.cppcpp file Entry point for the Project Manager. Initiates the Application main loop .
Applicationheader 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.
ProjectManagerWindowheader cpp file Constructs the application’s QMainWindow and DownloadController, and prepares all relevant transition screens for the Project Manager.
ScreensCtrlheader cpp file Container structure for all Project Manager Screens and GUI Widgets. Also houses primary transition code for facilitating Project Manager’s business logic.
ScreenFactoryheader 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.
ScreenDefsheader 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.
ScreenWidgetheader 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.


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.

  • 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.
  • Sets up Qt GUI stylesheets.
  • Sets up Window decoration and MainWindow Geometry.
  • Shows the MainWindow.
  • Run the QApplication’s main loop.

Back to Overview


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 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:

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

  • 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.
  • 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


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.

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