wxWidgets/interface/wx/power.h

/////////////////////////////////////////////////////////////////////////////
// Name:        power.h
// Purpose:     interface of wxPowerEvent
// Author:      wxWidgets team
// Licence:     wxWindows licence
/////////////////////////////////////////////////////////////////////////////

enum wxPowerType
{
    wxPOWER_SOCKET,
    wxPOWER_BATTERY,
    wxPOWER_UNKNOWN
};

enum wxBatteryState
{
    wxBATTERY_NORMAL_STATE,    // system is fully usable
    wxBATTERY_LOW_STATE,       // start to worry
    wxBATTERY_CRITICAL_STATE,  // save quickly
    wxBATTERY_SHUTDOWN_STATE,  // too late
    wxBATTERY_UNKNOWN_STATE
};

/**
    Possible power resources that can be locked by wxPowerResourceBlocker.

    @since 3.1.0
 */
enum wxPowerResourceKind
{
    /// Use to prevent automatic display power off.
    wxPOWER_RESOURCE_SCREEN,

    /// Use to prevent automatic system suspend.
    wxPOWER_RESOURCE_SYSTEM
};

/**
    Possible blocking behaviours for power resources.

    @since 3.3.0
 */
enum wxPowerBlockKind
{
    /**
        Prevent the resource from disappearing.

        When combined with ::wxPOWER_RESOURCE_SCREEN, this prevents the screen
        from turning off automatically. When combined with
        ::wxPOWER_RESOURCE_SYSTEM, this prevents the system from suspending.
     */
    wxPOWER_PREVENT,

    /**
        Delay suspend until the application handles the corresponding event.

        This block kind can only be used with ::wxPOWER_RESOURCE_SYSTEM.
     */
    wxPOWER_DELAY
};


/**
    @class wxPowerEvent

    The power events are generated when the system power state changes, e.g. the
    system is suspended, hibernated, plugged into or unplugged from the wall socket
    and so on. wxPowerEvents are emitted by wxWindows.

    Notice that currently these events are generated only under MSW, Linux and
    MacOS (cocoa). Under Linux and MacOS you @e must use wxPowerResource::Acquire()
    to receive them, e.g. typically an application interested in these events should
    initialize wxPowerResourceBlocker for ::wxPOWER_RESOURCE_SYSTEM resource
    using ::wxPOWER_DELAY block kind when initializing either the application
    itself or its main window. E.g. for an application that wants to handle
    suspend to gracefully close the open network connections and then reopen
    them on resume you could do

    @code
    class MyMainFrame : public wxFrame
    {
        ...

    private:
        wxPowerResourceBlocker m_powerDelaySleep;
    };

    MyMainFrame::MyMainFrame()
        : wxFrame(...),
          m_powerDelaySleep(wxPOWER_RESOURCE_SYSTEM,
                            "MyApp needs to close network connections",
                            wxPOWER_DELAY)
    {
        Bind(wxEVT_POWER_SUSPENDED, [](wxPowerEvent&) {
            // Close network connections here.
        });

        Bind(wxEVT_POWER_RESUME, [](wxPowerEvent&) {
            // Restore previously closed network connections here.
        });
    }
    @endcode

    To avoid the need to change the code using this event later when these
    events are implemented on the other platforms please use the test <tt>ifdef
    wxHAS_POWER_EVENTS</tt> instead of directly testing for the platform in
    your code: this symbol will be defined for all platforms supporting the
    power events.

    @beginEventTable{wxPowerEvent}
    @event{EVT_POWER_SUSPENDING(func)}
           @warning This event and the possibility to veto suspend was removed
           from MSW systems starting from Windows Vista. wxPowerResourceBlocker
           can be used to prevent the system from suspending under both XP and
           later systems, use it instead of handling this event.

           System is about to be suspended, this event can be vetoed to prevent
           suspend from taking place.
    @event{EVT_POWER_SUSPENDED(func)}
           System is about to suspend: normally the application should quickly
           (i.e. without user intervention) close all the open files and network
           connections here, possibly remembering them to reopen them later when
           the system is resumed.
    @event{EVT_POWER_SUSPEND_CANCEL(func)}
           @warning This event is currently never generated.

           System suspension was cancelled because some application vetoed it.
    @event{EVT_POWER_RESUME(func)}
           System resumed from suspend: normally the application should restore
           the state in which it had been before the suspension.
    @endEventTable

    @library{wxcore}
    @category{events}

    @see ::wxGetPowerType(), ::wxGetBatteryState()
*/
class wxPowerEvent : public wxEvent
{
public:
    wxPowerEvent();
    wxPowerEvent(wxEventType evtType);

    /**
        Call this to prevent suspend from taking place in @c wxEVT_POWER_SUSPENDING
        handler (it is ignored for all the others).
    */
    void Veto();

    /**
       Returns whether Veto has been called.
    */
    bool IsVetoed() const;
};

wxEventType wxEVT_POWER_SUSPENDING;
wxEventType wxEVT_POWER_SUSPENDED;
wxEventType wxEVT_POWER_SUSPEND_CANCEL;
wxEventType wxEVT_POWER_RESUME;

/**
    Helper functions for acquiring and releasing the given power resource.

    If an application performs a long running task without user interaction it
    is often necessary to prevent the system from automatically suspending or
    powering off the screen and Acquire() method can be used to do this.

    Notice that currently this functionality is only implemented for MSW and
    macOS for ::wxPOWER_RESOURCE_SCREEN and these platforms and Linux for
    ::wxPOWER_RESOURCE_SYSTEM, however the system must be using systemd 183 or
    later for this to work there.

    If possible, use wxPowerResourceBlocker class to ensure that Release() is
    called instead of calling it manually.

    @since 3.1.0
    @library{wxcore}
    @category{misc}

    @see wxPowerResourceBlocker
*/
class wxPowerResource
{
public:
    /**
       Acquire a power resource for the application.

       The default behaviour, chosen by setting @a blockKind to
       ::wxPOWER_PREVENT, is to ensure that the resource of the corresponding
       @a kind remains accessible, i.e. prevent the system from turning off the
       screen or suspending.

       Specifying ::wxPOWER_DELAY for @a blockKind doesn't actually prevent the
       system from suspending but does delay it to allow the application to
       handle the corresponding notifications. Note that under Linux systems
       will *not* receive ::wxEVT_POWER_SUSPENDED without acquiring the system
       resource using ::wxPOWER_DELAY.

       Every call to Acquire @b must be matched by a corresponding call to
       Release() or the system will not suspend until the application ends, use
       wxPowerResourceBlocker to ensure that this happens.

       @param kind Power resource required, either ::wxPOWER_RESOURCE_SCREEN
        or ::wxPOWER_RESOURCE_SYSTEM.
       @param reason Optional reason may be specified which might be used on
           some platforms to inform the user what is preventing power saving.
           It should usually describe the operation requiring the resource and
           specifying it is strongly recommended.
       @param blockKind The default value corresponds to the blocking
           behaviour, the ::wxPOWER_DELAY value can be used to avoid blocking
           the resource but just delay it to allow the application to handle
           the corresponding notifications. This parameter is available in
           wxWidgets 3.3.0 and later.
       @return Returns true if the acquisition was successful.

       @see Release()
    */
    static bool Acquire(wxPowerResourceKind kind,
                        const wxString& reason = wxString(),
                        wxPowerBlockKind blockKind = wxPOWER_PREVENT);

    /**
        Release a previously acquired power resource.

        Release @b must be called for every Acquire() call made to restore
        normal power saving behaviour

        @param kind Power resource to be released.

        @see Acquire()
    */
    static void Release(wxPowerResourceKind kind);
};

/**
    Helper RAII class ensuring that power resources are released.

    A wxPowerResourceBlocker object acquires a power resource in the
    constructor and releases it in the destructor making it impossible to
    forget to release the power resource (which would prevent suspending or
    screen power off until the application ends).

    Example:
    @code
    void MyWindow::DoSomething()
    {
        wxPowerResourceBlocker
            blocker(wxPOWER_RESOURCE_SYSTEM, "Downloading something important");

        if ( !blocker.IsInEffect() )
        {
            // If the resource could not be acquired, tell the user that he has
            // to keep the system alive
            wxLogMessage("Warning: system may suspend while downloading.");
        }

        // Run an important download and the system will not suspend while downloading
        for ( int i = 0; i < download.size(); ++i )
            download.readByte();

        // wxPOWER_RESOURCE_SYSTEM automatically released here.
    }
    @endcode

    @since 3.1.0
    @library{wxcore}
    @category{misc}

    @see wxPowerResource
*/
class wxPowerResourceBlocker
{
public:
    /**
       Acquires the power resource.

       Uses the same parameters as wxPowerResource::Acquire().
    */
    explicit wxPowerResourceBlocker(wxPowerResourceKind kind,
                                    const wxString& reason = wxString(),
                                    wxPowerBlockKind blockKind = wxPOWER_PREVENT);

    /**
        Returns whether the power resource could be acquired.

        This can be used to inform the user that the application will not
        prevent automatic suspending.

        @see wxPowerResource::Acquire()
    */
    bool IsInEffect() const;

    /**
       Releases the power resource.

       @see wxPowerResource::Release()
    */
    ~wxPowerResourceBlocker();
};