source/modules/dgl/Application.hpp

   1 /*
   2  * DISTRHO Plugin Framework (DPF)
   3  * Copyright (C) 2012-2022 Filipe Coelho <falktx@falktx.com>
   4  *
   5  * Permission to use, copy, modify, and/or distribute this software for any purpose with
   6  * or without fee is hereby granted, provided that the above copyright notice and this
   7  * permission notice appear in all copies.
   8  *
   9  * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD
  10  * TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN
  11  * NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL
  12  * DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER
  13  * IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
  14  * CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  15  */
  16
  17 #ifndef DGL_APP_HPP_INCLUDED
  18 #define DGL_APP_HPP_INCLUDED
  19
  20 #include "Base.hpp"
  21
  22 #ifdef DISTRHO_NAMESPACE
  23 START_NAMESPACE_DISTRHO
  24 class PluginApplication;
  25 END_NAMESPACE_DISTRHO
  26 #endif
  27
  28 START_NAMESPACE_DGL
  29
  30 // --------------------------------------------------------------------------------------------------------------------
  31
  32 /**
  33    Base DGL Application class.
  34
  35    One application instance is required for creating a window.
  36    There's no single/global application instance in DGL, and multiple windows can share the same app instance.
  37
  38    In standalone mode an application will automatically quit its event-loop when all its windows are closed.
  39
  40    Unless stated otherwise, functions within this class are not thread-safe.
  41  */
  42 class DISTRHO_API Application
  43 {
  44 public:
  45    /**
  46       Constructor.
  47     */
  48     // NOTE: the default value is not yet passed, so we catch where we use this
  49     Application(bool isStandalone = true);
  50
  51    /**
  52       Destructor.
  53     */
  54     virtual ~Application();
  55
  56    /**
  57       Idle function.
  58       This runs the application event-loop once.
  59     */
  60     void idle();
  61
  62    /**
  63       Run the application event-loop until all Windows are closed.
  64       idle() is called at regular intervals.
  65       @note This function is meant for standalones only, *never* call this from plugins.
  66     */
  67     void exec(uint idleTimeInMs = 30);
  68
  69    /**
  70       Quit the application.
  71       This stops the event-loop and closes all Windows.
  72       This function is thread-safe.
  73     */
  74     void quit();
  75
  76    /**
  77       Check if the application is about to quit.
  78       Returning true means there's no event-loop running at the moment (or it's just about to stop).
  79       This function is thread-safe.
  80     */
  81     bool isQuitting() const noexcept;
  82
  83    /**
  84       Check if the application is standalone, otherwise running as a module or plugin.
  85       This function is thread-safe.
  86     */
  87     bool isStandalone() const noexcept;
  88
  89    /**
  90       Return the time in seconds.
  91
  92       This is a monotonically increasing clock with high resolution.@n
  93       The returned time is only useful to compare against other times returned by this function,
  94       its absolute value has no meaning.
  95    */
  96     double getTime() const;
  97
  98    /**
  99       Add a callback function to be triggered on every idle cycle.
 100       You can add more than one, and remove them at anytime with removeIdleCallback().
 101       Idle callbacks trigger right after OS event handling and Window idle events (within the same cycle).
 102       There are no guarantees in terms of timing, use Window::addIdleCallback for time-relative callbacks.
 103     */
 104     void addIdleCallback(IdleCallback* callback);
 105
 106    /**
 107       Remove an idle callback previously added via addIdleCallback().
 108     */
 109     void removeIdleCallback(IdleCallback* callback);
 110
 111    /**
 112       Get the class name of the application.
 113
 114       This is a stable identifier for the application, used as the window class/instance name on X11 and Windows.
 115       It is not displayed to the user, but can be used in scripts and by window managers,
 116       so it should be the same for every instance of the application, but different from other applications.
 117
 118       Plugins created with DPF have their class name automatically set based on DGL_NAMESPACE and plugin name.
 119     */
 120     const char* getClassName() const noexcept;
 121
 122    /**
 123       Set the class name of the application.
 124       @see getClassName
 125     */
 126     void setClassName(const char* name);
 127
 128 private:
 129     struct PrivateData;
 130     PrivateData* const pData;
 131     friend class Window;
 132    #ifdef DISTRHO_NAMESPACE
 133     friend class DISTRHO_NAMESPACE::PluginApplication;
 134    #endif
 135
 136     DISTRHO_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR(Application)
 137 };
 138
 139 // --------------------------------------------------------------------------------------------------------------------
 140
 141 END_NAMESPACE_DGL
 142
 143 #endif // DGL_APP_HPP_INCLUDED