Application.hpp

/*
 * DISTRHO Plugin Framework (DPF)
 * Copyright (C) 2012-2025 Filipe Coelho <falktx@falktx.com>
 *
 * Permission to use, copy, modify, and/or distribute this software for any purpose with
 * or without fee is hereby granted, provided that the above copyright notice and this
 * permission notice appear in all copies.
 *
 * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD
 * TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN
 * NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL
 * DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER
 * IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
 * CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 */
 
#ifndef DGL_APP_HPP_INCLUDED
#define DGL_APP_HPP_INCLUDED
 
#include "Base.hpp"
 
#ifdef DAF_NAMESPACE
START_NAMESPACE_DAF
class PluginApplication;
END_NAMESPACE_DAF
#endif
 
START_NAMESPACE_DGL
 
// --------------------------------------------------------------------------------------------------------------------
// build config sentinels
 
/**
   This set of static variables act as a build sentinel that detects a configuration error.
 
   Usually this means the way DGL was built and how it is being used and linked into your program is different,
   we want to avoid such combinations as memory layout would then also be different
   leading to all sort of subtle but very nasty memory corruption issues.
 
   Make sure the flags used to build DGL match the ones used by your program and the link errors should go away.
 */
#define BUILD_CONFIG_SENTINEL(NAME) \
   static struct DAF_JOIN_MACRO(_, NAME) { bool ok; DAF_JOIN_MACRO(_, NAME)() noexcept; } NAME;
 
#ifdef DAF_DEBUG
BUILD_CONFIG_SENTINEL(fail_to_link_is_mismatch_daf_debug_on)
#else
BUILD_CONFIG_SENTINEL(fail_to_link_is_mismatch_daf_debug_off)
#endif
 
#ifdef DGL_USE_FILE_BROWSER
BUILD_CONFIG_SENTINEL(fail_to_link_is_mismatch_dgl_use_file_browser_on)
#else
BUILD_CONFIG_SENTINEL(fail_to_link_is_mismatch_dgl_use_file_browser_off)
#endif
 
#ifdef DGL_USE_WEB_VIEW
BUILD_CONFIG_SENTINEL(fail_to_link_is_mismatch_dgl_use_web_view_on)
#else
BUILD_CONFIG_SENTINEL(fail_to_link_is_mismatch_dgl_use_web_view_off)
#endif
 
#ifdef DGL_NO_SHARED_RESOURCES
BUILD_CONFIG_SENTINEL(fail_to_link_is_mismatch_dgl_no_shared_resources_on)
#else
BUILD_CONFIG_SENTINEL(fail_to_link_is_mismatch_dgl_no_shared_resources_off)
#endif
 
#ifdef DGL_RUNTIME_BACKEND
BUILD_CONFIG_SENTINEL(fail_to_link_is_mismatch_dgl_runtime_backend_on)
#else
BUILD_CONFIG_SENTINEL(fail_to_link_is_mismatch_dgl_runtime_backend_off)
#endif
 
#undef BUILD_CONFIG_SENTINEL
 
// --------------------------------------------------------------------------------------------------------------------
 
/**
   Base DGL Application class.
 
   One application instance is required for creating a window.
   There's no single/global application instance in DGL, and multiple windows can share the same app instance.
 
   In standalone mode an application will automatically quit its event-loop when all its windows are closed.
 
   Unless stated otherwise, functions within this class are not thread-safe.
 */
class DAF_API Application
{
public:
   /**
      Type of application to setup, either "classic" or "modern".
 
      What this means depends on the OS.
    */
    enum Type {
        kTypeAuto,
        kTypeClassic,
        kTypeModern,
    };
 
   /**
      Windowing system to open the application's windows on.
 
      Only Linux and the other X11/Wayland systems have one to choose. A DGL_BACKEND=both build picks X11 or
      Wayland at runtime, by the rule in dgl/src/runtime-backend.md, unless the application asks for one.
      The request is final: if that system cannot be used, or the build does not have it, no window opens
      and a message says why, rather than the application ending up on the other one.
      It takes the place of the DAF_WINDOW_BACKEND environment variable.
 
      On macOS, Windows and the other platforms with a single windowing system the request is ignored.
    */
    enum WindowSystem {
        kWindowSystemAuto,
        kWindowSystemX11,
        kWindowSystemWayland,
    };
 
   /**
      Constructor for standalone or plugin application.
    */
    Application(bool isStandalone = true, Type type = kTypeAuto, WindowSystem windowSystem = kWindowSystemAuto);
 
   /**
      Constructor for a standalone application.
      This specific constructor is required if using web views in standalone applications.
      On Linux a web view needs X11, see WindowSystem.
    */
    Application(int argc, char* argv[], WindowSystem windowSystem = kWindowSystemAuto);
 
   /**
      Destructor.
    */
    virtual ~Application();
 
   /**
      Idle function.
      This runs the application event-loop once.
    */
    void idle();
 
   /**
      Run the application event-loop until all Windows are closed.
      idle() is called at regular intervals.
      @note This function is meant for standalones only, *never* call this from plugins.
    */
    void exec(uint idleTimeInMs = 30);
 
   /**
      Quit the application.
      This stops the event-loop and closes all Windows.
      This function is thread-safe.
    */
    void quit();
 
   /**
      Check if the application is about to quit.
      Returning true means there's no event-loop running at the moment (or it's just about to stop).
      This function is thread-safe.
    */
    bool isQuitting() const noexcept;
 
   /**
      Check if the application is standalone, otherwise running as a module or plugin.
      This function is thread-safe.
    */
    bool isStandalone() const noexcept;
 
   /**
      Return the time in seconds.
 
      This is a monotonically increasing clock with high resolution.@n
      The returned time is only useful to compare against other times returned by this function,
      its absolute value has no meaning.
   */
    double getTime() const;
 
   /**
      Return the application type, either kTypeClassic or kTypeModern.
      This function never return kTypeAuto.
   */
    Type getType() const noexcept;
 
   /**
      Return the windowing system the application's windows open on, kWindowSystemX11 or kWindowSystemWayland.
      Returns kWindowSystemAuto where the platform has no choice of one, and when none could be opened.
   */
    WindowSystem getWindowSystem() const noexcept;
 
   /**
      Add a callback function to be triggered on every idle cycle.
      You can add more than one, and remove them at anytime with removeIdleCallback().
      Idle callbacks trigger right after OS event handling and Window idle events (within the same cycle).
      There are no guarantees in terms of timing, use Window::addIdleCallback for time-relative callbacks.
      Registrations added during dispatch start on the next idle call. Removing a registration
      cancels its pending call immediately; nested idle calls do not re-enter an active registration.
    */
    void addIdleCallback(IdleCallback* callback);
 
   /**
      Remove an idle callback previously added via addIdleCallback().
    */
    void removeIdleCallback(IdleCallback* callback);
 
   /**
      Get the class name of the application.
 
      This is a stable identifier for the application, used as the window class/instance name on X11 and Windows.
      It is not displayed to the user, but can be used in scripts and by window managers,
      so it should be the same for every instance of the application, but different from other applications.
 
      Plugins created with DAF have their class name automatically set based on DGL_NAMESPACE and plugin name.
    */
    const char* getClassName() const noexcept;
 
   /**
      Set the class name of the application.
      @see getClassName
    */
    void setClassName(const char* name);
 
private:
    struct PrivateData;
    PrivateData* const pData;
    friend class Window;
   #ifdef DAF_NAMESPACE
    friend class DAF_NAMESPACE::PluginApplication;
   #endif
 
    DAF_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR(Application)
};
 
// --------------------------------------------------------------------------------------------------------------------
 
END_NAMESPACE_DGL
 
#endif // DGL_APP_HPP_INCLUDED