<commit_before>/*
 * Window.h
 * 
 * This file is part of the "LLGL" project (Copyright (c) 2015 by <NAME>)
 * See "LICENSE.txt" for license information.
 */

#ifndef LLGL_WINDOW_H
#define LLGL_WINDOW_H


#include <string>
#include <memory>
#include <vector>
#include <LLGL/Export.h>
#include <LLGL/Key.h>
#include <LLGL/Types.h>


namespace LLGL
{


//! Window descriptor structure.
struct WindowDescriptor
{
    std::wstring    title;
    Point           position;                       //!< Window position (relative to the client area).
    Size            size;                           //!< Client area size.

    bool            visible             = false;
    bool            borderless          = false;
    bool            resizable           = false;
    bool            acceptDropFiles     = false;
    bool            preventForPowerSafe = false;
    bool            centered            = false;

    /**
    \brief Window context handle.
    \remarks If used, this must be casted from a platform specific structure:
    \code
    #include <LLGL/Platform/NativeHandle.h>
    //...
    LLGL::NativeContextHandle handle;
    //handle.parentWindow = ...
    windowDesc.windowContext = reinterpret_cast<const void*>(&handle);
    \endcode
    */
    const void*     windowContext       = nullptr;
};


// Interface for a Window class (also named Canvas)
class LLGL_EXPORT Window
{

    public:

        // Interface for all window listeners
        class LLGL_EXPORT EventListener
        {

            public:

                virtual ~EventListener();

            protected:

                friend class Window;

                virtual void OnProcessEvents(Window& sender);

                virtual void OnKeyDown(Window& sender, Key keyCode);
                virtual void OnKeyUp(Window& sender, Key keyCode);

                virtual void OnDoubleClick(Window& sender, Key keyCode);
                
                virtual void OnChar(Window& sender, wchar_t chr);

                virtual void OnWheelMotion(Window& sender, int motion);

                virtual void OnLocalMotion(Window& sender, const Point& position);
                virtual void OnGlobalMotion(Window& sender, const Point& motion);

                virtual void OnResize(Window& sender, const Size& clientAreaSize);

                //! Returns true if the specified window can quit, i.e. "ProcessEvents" returns false from now on.
                virtual bool OnQuit(Window& sender);

        };

        /* --- Common --- */

        virtual ~Window();

        static std::unique_ptr<Window> Create(const WindowDescriptor& desc);

        virtual void SetPosition(const Point& position) = 0;
        virtual Point GetPosition() const = 0;

        virtual void SetSize(const Size& size, bool useClientArea = true) = 0;
        virtual Size GetSize(bool useClientArea = true) const = 0;

        virtual void SetTitle(const std::wstring& title) = 0;
        virtual std::wstring GetTitle() const = 0;

        virtual void Show(bool show = true) = 0;
        virtual bool IsShown() const = 0;

        //! Query a window descriptor, which describes the current state of this window.
        virtual WindowDescriptor QueryDesc() const = 0;

        //! Sets the new window descriptor.
        virtual void SetDesc(const WindowDescriptor& desc) = 0;

        /**
        \brief Recreates the internal window object. This may invalidate the native handle previously returned by "GetNativeHandle".
        \see GetNativeHandle
        */
        virtual void Recreate(const WindowDescriptor& desc) = 0;

        /**
        \brief Returns the native window handle.
        \remarks This must be casted to a platform specific structure:
        \code
        // Example for a custom Win32 window class
        #include <LLGL/Platform/NativeHandle.h>
        //...
        void YourWindowClass::GetNativeHandle(void* nativeHandle)
        {
            auto handle = reinterpret_cast<LLGL::NativeHandle*>(nativeHandle);
            //handle->window = 'some HWND window handle';
        }
        \endcode
        */
        virtual void GetNativeHandle(void* nativeHandle) const = 0;

        /**
        \brief Processes the events for this window (i.e. mouse movement, key presses etc.).
        \return Once the "PostQuit" function was called on this window object, this function returns false.
        This will happend, when the user clicks on the close button.
        */
        bool ProcessEvents();

        /* --- Event handling --- */

        void AddEventListener(const std::shared_ptr<EventListener>& eventListener);
        void RemoveEventListener(const EventListener* eventListener);

        void PostKeyDown(Key keyCode);
        void PostKeyUp(Key keyCode);

        void PostDoubleClick(Key keyCode);
        
        void PostChar(wchar_t chr);
        
        void PostWheelMotion(int motion);
        
        void PostLocalMotion(const Point& position);
        void PostGlobalMotion(const Point& motion);

        void PostResize(const Size& clientAreaSize);

        /**
        \brief Posts the 'OnQuit' event to all event listeners.
        \remarks If at least one event listener returns false within the "OnQuit" callback, the window will not quit.
        If all event listener return true within the "OnQuit" callback, "ProcessEvents" will returns false from now on.
        */
        void PostQuit();

    protected:

        /**
        \briefs Called inside the "ProcessEvents" function after all event listeners received the same event.
        \see ProcessEvents
        \see EventListener::OnProcessEvents
        */
        virtual void OnProcessEvents() = 0;

    private:

        std::vector<std::shared_ptr<EventListener>> eventListeners_;

        bool quit_ = false;

};


} // /namespace LLGL


#endif



// ================================================================================<commit_msg>Completed docu of "Window" interface.<commit_after>/*
 * Window.h
 * 
 * This file is part of the "LLGL" project (Copyright (c) 2015 by <NAME>)
 * See "LICENSE.txt" for license information.
 */

#ifndef LLGL_WINDOW_H
#define LLGL_WINDOW_H


#include <string>
#include <memory>
#include <vector>
#include <LLGL/Export.h>
#include <LLGL/Key.h>
#include <LLGL/Types.h>


namespace LLGL
{


//! Window descriptor structure.
struct WindowDescriptor
{
    //! Window title as UTF16 string.
    std::wstring    title;

    //! Window position (relative to the client area).
    Point           position;

    //! Window size (this should be the client area size).
    Size            size;

    //! Specifies whether the window is visible at creation time.
    bool            visible             = false;

    //! Specifies whether the window is borderless. This is required for a fullscreen render context.
    bool            borderless          = false;

    //! Specifies whether the window can be resized.
    bool            resizable           = false;

    //! Specifies whether the window allows that files can be draged-and-droped onto the window.
    bool            acceptDropFiles     = false;

    /**
    \brief Specifies whether the 
    \note Only supported on: MS/Windows.
    */
    bool            preventForPowerSafe = false;

    //! Specifies whether the window is centered within the desktop screen.
    bool            centered            = false;

    /**
    \brief Window context handle.
    \remarks If used, this must be casted from a platform specific structure:
    \code
    #include <LLGL/Platform/NativeHandle.h>
    //...
    LLGL::NativeContextHandle handle;
    //handle.parentWindow = ...
    windowDesc.windowContext = reinterpret_cast<const void*>(&handle);
    \endcode
    */
    const void*     windowContext       = nullptr;
};


/**
\brief Interface for a Window class.
\remarks This is the main interface for the windowing system in LLGL.
To implement a custom window (and use GLFW for instance) you have to
derive from this class and implement all pure virtual functions.
*/
class LLGL_EXPORT Window
{

    public:

        // Interface for all window listeners
        class LLGL_EXPORT EventListener
        {

            public:

                virtual ~EventListener();

            protected:

                friend class Window;

                /**
                \brief Send when the window events are about to be polled. The event listeners receive this event before the window itself.
                \see Window::OnProcessEvents
                */
                virtual void OnProcessEvents(Window& sender);

                //! Send when a key (from keyboard or mouse) has been pushed.
                virtual void OnKeyDown(Window& sender, Key keyCode);

                //! Send when a key (from keyboard or mouse) has been released.
                virtual void OnKeyUp(Window& sender, Key keyCode);

                //! Send when a mouse button has been double clicked.
                virtual void OnDoubleClick(Window& sender, Key keyCode);
                
                //! Send when a character specific key has been typed on the sender window. This will repeat depending on the OS keyboard settings.
                virtual void OnChar(Window& sender, wchar_t chr);

                //! Send when the mouse wheel has been moved on the sender window.
                virtual void OnWheelMotion(Window& sender, int motion);

                //! Send when the mouse has been moved on the sender window.
                virtual void OnLocalMotion(Window& sender, const Point& position);

                //! Send when the global mouse position has changed. This is a raw input and independent of the screen resolution.
                virtual void OnGlobalMotion(Window& sender, const Point& motion);

                //! Send when the window has been resized.
                virtual void OnResize(Window& sender, const Size& clientAreaSize);

                /**
                \brief Send when the window is about to be quit.
                \return True if the sender window can quit. In this case "ProcessEvents" returns false from now on.
                Otherwise the quit can be prevented. Returns true by default.
                \see Window::ProcessEvents
                */
                virtual bool OnQuit(Window& sender);

        };

        /* --- Common --- */

        virtual ~Window();

        //! Creates a platform specific instance of the Window interface.
        static std::unique_ptr<Window> Create(const WindowDescriptor& desc);

        //! Sets the window position relative to its parent.
        virtual void SetPosition(const Point& position) = 0;

        //! Returns the window position relative to its parent.
        virtual Point GetPosition() const = 0;

        //! Sets the either the overall window size or the client area size. By default the client area size is set.
        virtual void SetSize(const Size& size, bool useClientArea = true) = 0;

        //! Returns either the overall window size or the client area size. By default the client area size is returned.
        virtual Size GetSize(bool useClientArea = true) const = 0;

        //! Sets the window title as UTF16 string. If the OS does not support UTF16 window title, it will be converted to UTF8.
        virtual void SetTitle(const std::wstring& title) = 0;

        //! Returns the window title as UTF16 string.
        virtual std::wstring GetTitle() const = 0;

        //! Shows or hides the window.
        virtual void Show(bool show = true) = 0;

        //! Returns true if this window is visible.
        virtual bool IsShown() const = 0;

        //! Queries a window descriptor, which describes the current state of this window.
        virtual WindowDescriptor QueryDesc() const = 0;

        //! Sets the window attributes according to the specified window descriptor.
        virtual void SetDesc(const WindowDescriptor& desc) = 0;

        /**
        \brief Recreates the internal window object. This may invalidate the native handle previously returned by "GetNativeHandle".
        \remarks This function is mainly used by the OpenGL renderer on Win32 when a multi-sampled swap-chain is created.
        \see GetNativeHandle
        */
        virtual void Recreate(const WindowDescriptor& desc) = 0;

        /**
        \brief Returns the native window handle.
        \remarks This must be casted to a platform specific structure:
        \code
        // Example for a custom Win32 window class
        #include <LLGL/Platform/NativeHandle.h>
        //...
        void YourWindowClass::GetNativeHandle(void* nativeHandle)
        {
            auto handle = reinterpret_cast<LLGL::NativeHandle*>(nativeHandle);
            //handle->window = 'some HWND window handle';
        }
        \endcode
        */
        virtual void GetNativeHandle(void* nativeHandle) const = 0;

        /**
        \brief Processes the events for this window (i.e. mouse movement, key presses etc.).
        \return Once the "PostQuit" function was called on this window object, this function returns false.
        This will happend, when the user clicks on the close button.
        */
        bool ProcessEvents();

        /* --- Event handling --- */

        //! Adds a new event listener to this window.
        void AddEventListener(const std::shared_ptr<EventListener>& eventListener);

        //! Removes the specified event listener from this window.
        void RemoveEventListener(const EventListener* eventListener);

        /**
        \brief Posts a 'KeyDown' event to all event listeners.
        \remarks For a window created with "Window::Create", and events will be posted automatically by the "ProcessEvents" function.
        \see EventListener::OnKeyDown
        \see ProcessEvents
        */
        void PostKeyDown(Key keyCode);

        //! \see PostKeyDown
        void PostKeyUp(Key keyCode);

        //! \see PostKeyDown
        void PostDoubleClick(Key keyCode);
        
        //! \see PostKeyDown
        void PostChar(wchar_t chr);
        
        //! \see PostKeyDown
        void PostWheelMotion(int motion);
        
        //! \see PostKeyDown
        void PostLocalMotion(const Point& position);

        //! \see PostKeyDown
        void PostGlobalMotion(const Point& motion);

        //! \see PostKeyDown
        void PostResize(const Size& clientAreaSize);

        /**
        \brief Posts a 'Quit' event to all event listeners.
        \remarks If at least one event listener returns false within the "OnQuit" callback, the window will not quit.
        If all event listener return true within the "OnQuit" callback, "ProcessEvents" will returns false from now on.
        \see EventListener::OnQuit
        \see ProcessEvents
        */
        void PostQuit();

    protected:

        /**
        \briefs Called inside the "ProcessEvents" function after all event listeners received the same event.
        \see ProcessEvents
        \see EventListener::OnProcessEvents
        */
        virtual void OnProcessEvents() = 0;

    private:

        std::vector<std::shared_ptr<EventListener>> eventListeners_;

        bool                                        quit_           = false;

};


} // /namespace LLGL


#endif



// ================================================================================
{'fraction_non_alphanumeric': 0.08856400259909032, 'fraction_numerical': 0.003183885640025991, 'mean_word_length': 2.0653256323441544, 'pattern_counts': {'":': 0, '<': 35, '<?xml version=': 0, '>': 35, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5792408', 'n_tokens_mistral': 3861, 'n_tokens_neox': 3629, 'n_words': 1485}