DPF

DISTRHO Plugin Framework
Log | Files | Refs | Submodules | README | LICENSE

Application.hpp (4681B)

      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