MuditaOS/module-apps/Application.hpp

/*
 * @file Application.hpp
 * @author Robert Borzecki (robert.borzecki@mudita.com)
 * @date 1 cze 2019
 * @brief
 * @copyright Copyright (C) 2019 mudita.com
 * @details
 */
#ifndef MODULE_APPS_APPLICATION_HPP_
#define MODULE_APPS_APPLICATION_HPP_

#include <map>
//module-gui
#include "gui/Common.hpp"
//#include "gui/widgets/Window.hpp"
#include "gui/input/Translator.hpp"
//module-sys
#include "Service/Service.hpp"
#include "Service/Message.hpp"
#include "Service/Common.hpp"
#include "SystemManager/SystemManager.hpp"
//module-db
#include "Interface/SettingsRecord.hpp"

#include "SwitchData.hpp"
#include "service-cellular/api/CellularServiceAPI.hpp"
#include "windows/AppWindow.hpp"

namespace gui {
	class AppWindow;
};

namespace app {

class Application;

class AppTimer // this should inherit from ServiceTimer, but *bodge*
{
  private:
    uint32_t id = 0; // let's say 0 indicates not initalized timer
    std::function <void ()> callback = nullptr;
    Application *parent = nullptr;

    void registerCallback( std::function<void ()> );
    AppTimer();

  public:
    AppTimer(Application * parent, uint32_t id, std::function<void()> callback, const std::string &name);
    ~AppTimer();
    void runCallback();
    uint32_t getID();
    static uint32_t getNextUniqueID();
    // timer controls:
    void restart();
    void stop();
    bool operator==(const AppTimer &rhs) const;
    bool operator==(const uint32_t &rhs) const;
};

/// This is template for creating new applications. Main difference between Application and service is that:
/// 1. Application has access to GUI and Input
/// 2. Application lifetime is managed with sapm::ApplicationManager
class Application: public sys::Service {
  public:
    /// state in which application is right now
    /// @note do not mistake with application manager state
    enum class State
    {
        /// Application doesn't exist
        NONE,
        /// Application: Object has been created and underlying service is waiting to execute init handler method.
        /// Application Manager: Launcher for the application has been provided. Application can be started using provided launcher. The other possibility
        /// is that Appication Manager received CLOSING_FINISHED message.
        DEACTIVATED,
        /// Application: Set after entering the init handler of the application. In this state application will request
        /// in a blocking way the db configuration of the phone. Before exiting the init handler application must send APP_REGISTER message to
        /// Application Manager.
        /// Application Manager: Initialization is triggered by the switch message sent by other application to the application manager.
        /// Launcher for the application has been executed upon receiving switch command. Optional switch data has been
        /// saved and it will be provided when application manager receives registration message.
        INITIALIZING,
        /// Application manager sent variant of switch command to the selected application and it's now waiting for confirmation
        /// from the application
        ACTIVATING,
        /// Application is working and has focus and can render
        ACTIVE_FORGROUND,
        /// Applicatino lost focus but it is still working
        ACTIVE_BACKGROUND,
        /// Application: Close request message has been received. As a response application must send close request acknowledge message.
        /// Application must start closing all workers and releasing resources. After all workers are closed and resources released application
        /// sends to application manager CLOSING_FINISHED message
        /// Application Manager sent signal to application that it should be closed. Application must perform all necessary cleanup
        /// and request System Manager to close it.
        DEACTIVATING
    };
    /// c_str() function for Application::State
    static const char *stateStr(State st);

  private:
    State state = State::DEACTIVATED;

    bool signalStrengthUpdateHandler();

  public:
	std::list<uint32_t> timerIDs;
	std::list <AppTimer> appTimers; // @TODO decide on type
    AppTimer longPressTimer;
    Application(std::string name, std::string parent="", bool startBackground = false, uint32_t stackDepth=4096,
	        sys::ServicePriority priority=sys::ServicePriority::Idle);
	virtual ~Application();

    Application::State getState();
    void setState(State st);

    /// @defgroup AppTimers Application timers
    /// @note Please mind that timers are from Service and implementation in service should be revritten to send notify instead of calling callback
    ///       Right now timers can create races.
    /// @{
    /// Method to register callback function to be run on timer.
    AppTimer CreateAppTimer(TickType_t interval, bool isPeriodic, std::function<void()> callback, const std::string &name = "");
    /// Remove previousy registered AppTimer by object
    void DeleteTimer(AppTimer &timer);
    /// Remove previousy registered AppTimer by id
    void DeleteTimer(uint32_t id);
    /// @}

    /// Method responsible for rendering currently active window.
    /// 1. queries for static data for all windows form Store (i.e. battery level, sim card level)
    /// 2. loads rendering commands and send them to GUI renderer (sgui::ServiceGUI)
    void render(gui::RefreshModes mode);

    /// Method responsible for setting application to the state where incoming user input is blocked
    void blockEvents(bool isBlocked);

    /// Method sending switch command for another window. It will switch window within active application.
    /// to switch windows between applications use sapm::ApplicationManager::messageSwitchApplication
    /// it will effectivelly trigger setActiveWindow and change on windows stack
    int switchWindow(const std::string &windowName, gui::ShowMode cmd = gui::ShowMode::GUI_SHOW_INIT, std::unique_ptr<gui::SwitchData> data = nullptr);

    /// Same as switchWindow above
    inline auto switchWindow(const std::string &windowName, std::unique_ptr<gui::SwitchData> data)
    {
        return switchWindow( windowName, gui::ShowMode::GUI_SHOW_INIT, std::move(data));
    };

    /// Metod sendind switch command for previous window on windows stack.
    int switchBackWindow(const std::string &windowName, uint32_t cmd, std::unique_ptr<gui::SwitchData> data);

    /// Method refreshing active window
    int refreshWindow(gui::RefreshModes mode);

    /// Mehtod to handle bus messages, all message types are defined in Message.hpp
    /// Message types are in MessageType
    sys::Message_t DataReceivedHandler(sys::DataMessage *msgl);

    /// initialization function
    /// 1. it has to be called for each and every application instance, it registeres application in ApplicationManager
    ///    and notify ApplicationManager that it's in Initialization state
    /// 2. It gets settings from database
    sys::ReturnCodes InitHandler() override;

    /// function to set active window for application
    /// if none window is selected main window is used
    /// if window name is "LastWindow" then previous window is selected
    /// it modifies windows stack
    void setActiveWindow(const std::string &windowName);

    /// getter for settings record
    SettingsRecord &getSettings()
    {
        return settings;
    }

    /// see suspendInProgress documentation
    virtual void setSuspendFlag(bool val)
    {
        suspendInProgress = val;
    };
    /// see shutdownInProgress documentation
    virtual void setShutdownFlag()
    {
        shutdownInProgress = true;
    };

    /// @defgroup Application Application static functions
    /// All this functions are meant to be used in ApplicationManager only
    /// @note consider moving these as private elements of ApplicationManager i.e. under names message::switchApplication etc.
    /// @{
    static bool messageSwitchApplication(sys::Service *sender, std::string application, std::string window, std::unique_ptr<gui::SwitchData> data);
    static bool messageRefreshApplication( sys::Service* sender, std::string application, std::string window, gui::SwitchData* data=nullptr );
	static bool messageCloseApplication( sys::Service* sender, std::string application );
	static bool messageRebuildApplication( sys::Service* sender, std::string application );
    /// @}

  protected:
    /// application's settings taken from database
    SettingsRecord settings;

    void longPressTimerCallback();
    /// function executing functions registered by CreateAppTimer
    /// @param id - timer identification number
    virtual void TickHandler(uint32_t id) override final;
    /// Method used to register all windows and widgets in application
    virtual void createUserInterface() = 0;
    /// Method closing application's windows.
    virtual void destroyUserInterface() = 0;
    /// Map containing application's windows
    /// Right now all application windows are being created on application start in createUserInterface
    /// then all windows are removed at the end of application
    /// @note right now there is no mechanism to postphone window creation
    std::map<std::string, gui::AppWindow *> windows;

    /// stack of visited windows in application
    /// @ingrup AppWindowStack
    std::vector<std::string> windowStack;

  public:
    /// @ingrup AppWindowStack
    /// get to the first time we entered this &window
    bool popToWindow(const std::string &window);
    /// push window to the top of windows stack
    /// @ingrup AppWindowStack
    void pushWindow(const std::string &newWindow);
    /// getter for previous window name
    /// @ingrup AppWindowStack
    const std::string getPrevWindow() const;
    /// clears windows stack
    /// @ingrup AppWindowStack
    void cleanPrevWindw();
    /// getter to get window by name
    /// @note could be possibly used to implement building window on request
    /// @ingrup AppWindowStack
    gui::AppWindow *getWindow(const std::string &window);
    /// getter for current wisible window in application
    /// @ingrup AppWindowStack
    gui::AppWindow *getCurrentWindow();

  protected:
    /// Flag defines whether keyboard input should be processed
    bool acceptInput = false;

    /// key translator to handle
    /// 1. long press transformation (right now we support long press only via top application keyTralator handling)
    /// 2. simple translation of keys 1 to 1 with keyboard
    std::unique_ptr<gui::KeyInputSimpleTranslation> keyTranslator;
    /// Flag defines how application will behave after registration. It can go forground or background
    bool startBackground = false;
    /// Flag which defines whether application initialized suspend mode, this will influence how render message will sent to gui service.
    /// If suspend is true, application manager will receive information from both eink and gui services if last rendering mesage will
    /// be processed.
    bool suspendInProgress = false;
    /// Flag defines case when display needs to be refreshed before closing the system. If flag is set to true next set of rendering commands will
    /// carry information to GUI service that system needs to be closed. After displaying the screen GUI will notify application manager to request system
    /// shutdown.
    bool shutdownInProgress = false;

    /// informs self that there was key press
    /// used to provide a way for long press/multipress handling in application
    static bool messageInputEventApplication(sys::Service *sender, std::string application, const gui::InputEvent &event);
};

/// used in ApplicationManager to start applications
class ApplicationLauncher {
protected:
  /// name of the application to run
  std::string name = "";
  /// name of the application's owner
  std::string parent = "";
  /// defines whether application can be closed when it looses focus
  bool closeable = true;
  /// defines whether application should be run without gaining focus, it will remian in the BACKGROUND state
  bool startBackground = false;
  /// flag defines whether this application can prevent power manager from changing
  bool preventBlocking = false;

public:
	ApplicationLauncher( std::string name, bool isCloseable, bool preventBlocking = false ) :
		name{name},
		closeable{isCloseable},
		preventBlocking{preventBlocking} {};
	virtual ~ApplicationLauncher() {};
	std::string getName() { return name;};
	bool isCloseable() { return closeable; };
	bool isBlocking() { return preventBlocking; };

	//virtual method to run the application
	virtual bool run(sys::Service* caller = nullptr ) {return true;};
	virtual bool runBackground(sys::Service* caller = nullptr ) {return true;};
    std::shared_ptr<Application> handle = nullptr;
};

/// application launcher boilerplate
template <class T>
class ApplicationLauncherT : public ApplicationLauncher
{
    public:
    ApplicationLauncherT(std::string name, bool isCloseable=true) : ApplicationLauncher(name, isCloseable) {}
    virtual bool run(sys::Service* caller) override {
        parent = (caller == nullptr ? "" : caller->GetName());
        handle = std::make_shared<T>(name, parent);
        return sys::SystemManager::CreateService(handle, caller);
    };
    bool runBackground(sys::Service *caller) override {
        parent = (caller == nullptr ? "" : caller->GetName());
        handle = std::make_shared<T>(name, parent, true);
        return sys::SystemManager::CreateService(handle, caller);
    };
};

/// creates application launcher per class provided
template <class T>
std::unique_ptr<ApplicationLauncherT<T>> CreateLauncher(std::string name, bool isCloseable=true) {
    return std::move(std::unique_ptr<ApplicationLauncherT<T>>(new ApplicationLauncherT<T>(name, isCloseable)));
}

} /* namespace app */

#endif /* MODULE_APPS_APPLICATION_HPP_ */