Program Structure - dylondark/cob-taylor-games GitHub Wiki

This section explains the different components of the code, what they are and how they relate to each other.

Menu

Files:

  • main.cpp
    • Class/Namespace: N/A
    • Purpose: To provide the starting point of the program. Sets up the environment for the program and then opens the main window.
    • Uses:
      • mainwindow.h/.cpp - For creating the main window with the menu
  • mainwindow.h/.cpp
    • Class/Namespace: MainWindow
    • Purpose: The main class of the program, provides the "glue" that holds the program together. It contains the code for displaying the menu and leaderboard. Serves as the launching point for all the games.
    • Uses:
      • leaderboardhandler.h/.cpp - For managing the leaderboard scores
      • TriviaGame.qml, GuessTheLogoGame.qml, TetroosGame.qml, HopperGame.qml, PongGame.qml, MazeGame.qml - For launching the games
      • cliparser.h/.cpp - For getting the filepath and determining if the games should be opened in separate windows
      • clickdetector.h/.cpp - For detecting if the leaderboard has been clicked
      • utilities.h/.cpp - For choosing which QML file to open when a game is clicked
      • bgwidget.h/.cpp - For the scrolling background on the menu
      • debuglabel.h/.cpp - For the secret debug label
  • leaderboardhandler.h/.cpp
    • Class/Namespace: LeaderboardHandler
    • Purpose: This class handles adding the user's score and username to the leaderboard shown on the main screen.
    • Uses:
      • mainwindow.h/.cpp - Is used by main window to display the leaderboard
      • utilities.h/.cpp - Uses Utilities::game to allow leaderboard handler to organize the scores per game as well as update the corresponding game score on the leaderboard.
  • debuglabel.h/.cpp
    • Class/Namespace: DebugLabel class
    • Purpose: Custom implementation of a QLabel, meant to be used as a label on the main menu with a secret activation method, that displays some important system and program information. This could just be an ordinary label controlled with a function in mainwindow, but putting it in its own class provides a little bit of organization.
    • Uses: This #includes QLabel, QObject, and QString.
  • clickdetector.h/.cpp
    • Class/Namespace: ClickDetectorClass
    • Purpose: This class provides a way to detect if a widget has been clicked. It gets installed onto a widget with installEventFilter() and the clickDetected() signal can be connected to a slot to monitor clicks on that widget.
    • Uses: This #includes QObject.
  • bgwidget.h/.cpp
    • Class/Namespace: bgWidget
    • Purpose: This is a custom implementation of the QOpenGLWidget. QOpenGLWidget is a generic widget (so, doesn't come with any specialized features like a label, button etc would) that provides GPU acceleration through openGL for everything drawn on it. This is naturally useful for drawing a fancy scrolling background animation on, because it offloads some of that animation work from the CPU to the GPU, making it more efficient. This custom widget specifically includes the code to draw said background animation onto itself. It just needs to be added to the window and a QTimer object needs to be connected to the animate() slot in order to run the animation. This is done in mainwindow class (see initbg() in mainwindow.cpp).
    • Uses: This uses #include QWidget, QOpenGLWidget, QTimer, QPixmap, vector, and imgqueue.h.

Controllers

Files:

  • triviacontroller.h/.cpp

    • Class/Namespace: Part of the trivia game.
    • Purpose: The .h file is a class which loads the trivia question data from the filesystem. The CPP file loads those questions into a question struct, which is then stored in questionVec. This displays them in a UI to the user.
    • Uses: -rapidcsv.h - Used for getting the questions from the question bank file. -utilities.h - General file used for error messages, can be used across any game.
  • guessthelogocontroller.h/.cpp

    • Class/Namespace: Part of the Guess the Logo Game.
    • Purpose: This .h file is a class which receives a random logo trivia question from the database. The CPP file then loads those questions into the question struct, along with the corresponding image.
    • Uses:
  • tetrooscontroller.h/.cpp

    • Class/Namespace: Part of the Tetroos game.
    • Purpose: This class is the controller class for the Tetroos game. It is instantiated as an object in the QML file for the game and used in the QML. This class contains all of the logic for the Tetroos game. The QML file calls this class's input methods and functions when buttons are pressed in the game, and this class sends signals to the QML file to update its view of the game state.
    • Uses: "threadworker.h" "tetroosdata.h" in the h file, Then in the CPP File it includes "tetrooscontroller.h" "cliparser.h"
  • pongcontroller.h/.cpp

    • Class/Namespace: Part of the Pong game.
    • Purpose: To define the logic on which the game and AI runs, and to define the functions which are used in the QML file, also to store data such as scores and timers. The file which handles the logic for how the game is played (through AI, controlling the paddles via keyboard input, etc.)
    • Uses: The CPP file uses "cliparser.h" and the Hpp file uses "threadworker.h"
  • mazecontroller.h/.cpp

    • Class/Namespace: Part of the maze game.
    • Purpose: The purpose of the maze controller is to initialize the maze and all the cells in it. It also takes input from the keyboard to move the character, it updates / calculates the game state, and generally handles all game logic required to run the maze game.
    • Uses: The .h file uses "flippedarray.h" "threadworker.h" and the .cpp file uses "qpainter.h"
  • feedbackcontroller.h/.cpp

    • Class/Namespace: Feedback Controller
    • Purpose: This is for the end of the games when a user would leave feedback this puts it into a text file. This is a vestigial class, as it is not used anymore.
    • Uses: <QtQml/qmlregistration.h>

Utilities

Files:

  • utilities.h/.cpp
    • Class/Namespace: Utilities
    • Purpose: General utilities files which house functions that can be used in any game. Arrays like errorMessages, game array which has a game number for each game, and throwError which gives the errorMessages out.
    • Uses: QUrl, QMessageBox
  • rapidcsv.h
    • Class/Namespace: Utilities
    • Purpose: Rapidcsv is a C++ parser library that is used for many things, including reading and writing data. In our program, it is used to retrieve questions for our trivia based games.
    • Uses:
      • guessthelogocontroller.cpp - Retrieves a random question from rapidcsv::Document file; to display on screen
      • triviacontroller.cpp - Retrieves a random question from rapidcsv::Document file; to display on screen
  • profanitychecker.h/.cpp
    • Class/Namespace: Utilities
    • Purpose: Profanity checker is used to detect if any blacklisted words are present in the user's username. If there are, it denies them from entering the name, and thus, putting it on the leaderboard.
    • Uses: -mainwindow.cpp - Used as a controller when the user attempts to input their username.
  • cliparser.h/.cpp
    • Class/Namespace: Utilities
    • Purpose: Handles CMD arguments that are passed to a Qt application. It is largely used to detect the presence of the -w flag, which would launch the game in a pop-out window or not. This prevents the game from launching in the incorrect display options, ensuring the game looks (and runs) properly. It also uses -p to check for specific directory paths.
    • Uses: -bgwidget.cpp - Used to get a specific directory path -mainwindow.cpp - Used to get a specific directory path and launch in the proper windowed mode -tetrooscontroller.cpp - Used to get a specific directory path and launch in the proper windowed mode
  • threadworker.h
    • Class/Namespace: Threadworker
    • Purpose: This is the object used to run actions in a separate thread. It gets moved to another thread, and you can give it jobs to run on that thread using QMetaObject::invokeMethod(). See tetrooscontroller.cpp for examples.
    • Uses: This uses #include QObject.
  • flippedarray.h
    • Class/Namespace: FlippedArray
    • Purpose: This is a class that subclasses std::array but flips the access operator so that it always returns the opposite element specified. For instance, in a hypothetical array of 10 elements, trying to access the element at position 0 will return the element at position 9. This is useful for changing the origin point of 2D arrays from the top left to the bottom left by using a FlippedArray for the Y array.
    • Uses: This includes algorithm, array, stdexcept
  • leaderboardtools.h
    • Class/Namespace: LeaderboardTools
    • Purpose: Provides the tools and code for the leaderboard, including generating random strings of characters, generating and manipulating leaderboard data, generating leaderboard entries, and generating scores for all the games.
    • Uses:
      • leaderboardhandler.h
      • utilities.h
  • imgqueue.h/.cpp
    • Class/Namespace: imqQueue class
    • Purpose: This class provides the data structure used for the images in the background animation. At its base it is a linked list, but it is set up sort of as a queue. It is constructed with a vector of QPixmaps (IMGLIST) as the images for use in the queue (can be any size). It then populates the list with random images from the IMGLIST vector. The list can be looped through with next() and specific elements can be accessed with brackets []. Calling shift() takes an image off the front of the queue and inserts a random new one at the end. In the background animation, the contents of the queue are visible in each diagonal "line" of images down the screen, and shift() is called when the last image goes offscreen. This is done seamlessly so that it appears that there is an infinite "line" of random images.
    • Uses: This includes QPixmap vector

QML

  • MazeGame.qml

    • Purpose: Main game file for Maze.
    • Uses:
      • mazecontroller.h/.cpp - For controlling the game from C++
      • HomeBarBase.qml - For the home bar
      • GameOverBase.qml - For the game over screen
  • Feedback.qml

    • Purpose: Currently not in use, used for the player to give feedback for the developers on what they think about the game.
    • Uses:
      • feedbackcontroller.h/.cpp - Used to receive the input text from the user and save it as feedback.
  • GameOverBase.qml

    • Purpose: GameOverBase provides the "Game Over" screen for every game. It also displays the user's score and uploads it to the local leader-board.
    • Uses:
      • gameBase.qml - Uses both "questionscorrect" and "maxquestions" from gamebase.
  • GuessTheLogoGame.qml

    • Purpose: This qml file contains all of the code for the game "Guess The Logo", a trivia game based on Akron logos.
    • Uses:
      • guessthelogocontroller - Randomizes questions and retrieves the proper corresponding answers + images.
      • MenuBase.qml - For allowing the user to input their username.
      • HomeBarBase.qml - For the home bar
      • GameOverBase.qml - For the Game Over screen
  • HomeBarBase.qml

    • Purpose: The black bar at the bottom of the screen. Displays the Username as well as an option for the user to return to the homescreen. Typically, it displays points as well.
    • Uses:
      • N/A
  • HopperGame.qml

    • Purpose: Contains all of the code, files, and resources for the game codenamed "Zippy Hopper", officially known as "Zippy's Class Run".
    • Uses:
      • MenuBase.qml - For allowing the user to input their username
      • HomeBarBase.qml - For the home bar
      • GameOverBase.qml - For the Game Over screen
  • MenuBase.qml

    • Purpose: Contains the code for the main menu and all of its components, including Username Input, Profanity Checker (prevents users from putting in banned words as their username) and code for the animated background.
    • Uses:
      • profanitychecker.cpp - For filtering out blacklisted words when the user inputs their username
  • PongGame.qml

    • Purpose: Contains all of the code and necessary files for the game "Pong".
    • Uses:
      • MenuBase.qml - For allowing the user to input their username
      • HomeBarBase.qml - For the home bar
      • GameOverBase.qml - For the Game Over screen
  • PreviewBase.qml

    • Purpose: Contains the code for the game previews on the main menu.
    • Uses:
      • N/A
  • TetroosBackgroundPiece.qml

    • Purpose: Contains all of the code used for the falling Tetris pieces on the Tetroos Game Over screen.
    • Uses:
      • N/A
  • TetroosGame.qml

    • Purpose: Contains all of the code and necessary files for the Tetris game "Tetroos".
    • Uses:
      • TetroosPieceView.qml - Uses TetroosPieceView.qml for displaying the pieces ingame.
      • MenuBase.qml - For allowing the user to input their username
      • HomeBarBase.qml - For the home bar
      • GameOverBase.qml - For the Game Over screen
  • TetroosPieceView.qml

    • Purpose: Used to show the current and "next" piece for the Game "Tetroos".
    • Uses:
      • TetroosGame.qml - is USED in TetroosGame.qml.
  • TriviaGame.qml

    • Purpose: Contains all of the code and necessary files for the Trivia Game.
    • Uses:
      • TriviaController -
      • MenuBase.qml - For allowing the user to input their username
      • HomeBarBase.qml - For the home bar at the bottom of the screen
      • GameOverBase.qml - For the Game Over screen
⚠️ **GitHub.com Fallback** ⚠️