# class hiro::Gadget

## Overview

Visual part of module. Provides options for visualization, that do not interfere with data stored in Resource. More…

    #include <Gadget.h>

    class Gadget {
    public:
        // fields

        const hiro::ResourceId RESOURCE_ID;

        // construction

        Gadget(const hiro::Resource* res);
        virtual ~Gadget();

        // methods

        virtual void Initialize();
        virtual void Terminate();
        virtual void GenerateGui(hiro::GuiGenerator& gui);
        virtual void Update(const float time_delta);
        virtual bool FocusCamera(glm::vec3& focus_point, glm::vec3& cam_position) const;
        virtual hiro::EventStatus KeyPressed(hiro::Key key, const hiro::ModKeys& mods, hiro::EventStatus status);
        virtual hiro::EventStatus KeyReleased(hiro::Key key, const hiro::ModKeys& mods, hiro::EventStatus status);
        virtual hiro::EventStatus MouseButtonPressed(hiro::MouseButton button, const hiro::ModKeys& mods, hiro::EventStatus status);
        virtual hiro::EventStatus MouseButtonReleased(hiro::MouseButton button, const hiro::ModKeys& mods, hiro::EventStatus status);
        virtual hiro::EventStatus MouseWheel(float offset, hiro::EventStatus status);
        virtual hiro::EventStatus MouseMoved(float x, float y, hiro::EventStatus status);
        virtual hiro::EventStatus ViewResized(uint32_t width, uint32_t height, hiro::EventStatus status);
        virtual void RenderTexts(hiro::draw::TextRenderer& t_renderer);
        hiro::Camera* GetCamera() const;
        virtual int32_t AddRenderer(const hiro::draw::PRenderer& renderer, const hiro::draw::PStyle& style, uint8_t layer = 0u) const;
        virtual void RemoveRenderer(int32_t renderer_id) const;
        hiro::draw::ProjectionParams GetProjectionParams() const;

        template <typename UnitType = Resource>
        const UnitType* GetResource() const;

        void SetViewarea(hiro::Viewarea* viewarea);
        bool SaveState() const;
        void SetNearFar(float near, float far) const;

    protected:
        // methods

        void LoadState();
        virtual bool ReadFromStream(std::istream& str);
        virtual void WriteToStream(std::ostream& str) const;
        void DrawOnNextUpdate() const;
        static bool ReadStateVersion(std::istream& str, uint32_t expected_version);
        static void WriteStateVersion(std::ostream& str, uint32_t version);
    };

## Detailed Documentation

Visual part of module. Provides options for visualization, that do not interfere with data stored in Resource.

To unlock its powers, derive your custom Gadget and override functionality that you require.

### Methods

    virtual void Initialize()

Function invoked right after object creation to set up all properties.

    virtual void Terminate()

Function invoked right before object destruction.

    virtual void GenerateGui(hiro::GuiGenerator& gui)

Function invoked right after object initialization to define gui.

    virtual void Update(const float time_delta)

Function invoked each time HIRO context is updated.

    virtual bool FocusCamera(glm::vec3& focus_point, glm::vec3& cam_position) const

Function invoked when user requests to focus camera at this gadget.

Parameters:

focus_point | Point at which the camera should look at.
cam_position | Position of the camera.

Returns:

When the camera can be set correctly, the method should return true.

    virtual hiro::EventStatus KeyPressed(hiro::Key key, const hiro::ModKeys& mods, hiro::EventStatus status)

The function invoked after the key press event, triggered by a user.

Parameters:

key | Identifier of key that was pressed.
mods | Set of modifier keys being held at the time of key press.
status | Whether the event was already processed by other object.

Returns:

When the event was handled, the function should return EventStatus::processed.

    virtual hiro::EventStatus KeyReleased(hiro::Key key, const hiro::ModKeys& mods, hiro::EventStatus status)

The function invoked after the key release event, triggered by a user.

Parameters:

key | Identifier of key that was released.
mods | Set of modifier keys being held at the time of key release.
status | Whether the event was already processed by other object.

Returns:

When the event was handled, the function should return EventStatus::processed.

    virtual hiro::EventStatus MouseButtonPressed(hiro::MouseButton button, const hiro::ModKeys& mods, hiro::EventStatus status)

The function invoked after the mouse button press event, triggered by a user.

Parameters:

button | Identifier of button that was pressed.
mods | Set of modifier keys being held at the time of button press.
status | Whether the event was already processed by other object.

Returns:

When the event was handled, the function should return EventStatus::processed.

    virtual hiro::EventStatus MouseButtonReleased(hiro::MouseButton button, const hiro::ModKeys& mods, hiro::EventStatus status)

The function invoked after the mouse button release event, triggered by a user.

Parameters:

button | Identifier of button that was released.
mods | Set of modifier keys being held at the time of button release.
status | Whether the event was already processed by other object.

Returns:

When the event was handled, the function should return EventStatus::processed.

    virtual hiro::EventStatus MouseWheel(float offset, hiro::EventStatus status)

The function invoked after the mouse wheel was interacted with, triggered by a user.

Parameters:

offset | Orientation and intensity of a wheel change.
status | Whether the event was already processed by other object.

Returns:

When the event was handled, the function should return EventStatus::processed.

    virtual hiro::EventStatus MouseMoved(float x, float y, hiro::EventStatus status)

The function invoked after the mouse is moved, triggered by a user.

Parameters:

x | Horizontal position of a mouse cursor.
y | Vertical position of a mouse cursor.
status | Whether the event was already processed by other object.

Returns:

When the event was handled, the function should return EventStatus::processed.

    virtual hiro::EventStatus ViewResized(uint32_t width, uint32_t height, hiro::EventStatus status)

The function invoked after the view resolution changes.

Parameters:

width | Horizontal pixel resolution of a view.
height | Vertical pixel resolution of a view.
status | Whether the event was already processed by other object.

Returns:

When the event was handled, the function should return EventStatus::processed.

    virtual void RenderTexts(hiro::draw::TextRenderer& t_renderer)

Function called before rendering, to define what texts should be printed on screen.

Parameters:

t_renderer | Text printer used to define texts to be printed.

    hiro::Camera* GetCamera() const

Return handle to the camera used to render this.

    virtual int32_t AddRenderer(const hiro::draw::PRenderer& renderer, const hiro::draw::PStyle& style, uint8_t layer = 0u) const

Insert specified renderer to the list of currently used renderers.

Parameters:

renderer | Renderer to add to the rendering system.
style | Style used for rendering.
layer | Rendering layer used for rendering.

Returns:

Identifier of currently added renderer.

    virtual void RemoveRenderer(int32_t renderer_id) const

Remove specified renderer from the list of currently used renderers.

Parameters:

renderer_id | Identifier of renderer to be removed.

    hiro::draw::ProjectionParams GetProjectionParams() const

Returns projection parameters for view where object exists.

    template <typename UnitType = Resource>
    const UnitType* GetResource() const

Returns pointer to Resource object that was used to create this object.

    void SetViewarea(hiro::Viewarea* viewarea)

Assign Viewarea to this. Not to be called by a user.

    bool SaveState() const

Forces this to save its state.

State is saved automatically when changes are made to gui. May negatively affect performance when used a lot.

Returns:

Whether saving was successful.

    void SetNearFar(float near, float far) const

Set near and far values of the viewarea.

    void LoadState()

Loads file stored from previous session. This method calls also ReadFromStream.

    virtual bool ReadFromStream(std::istream& str)

Override this method to read custom state from auto save stream.

This method is not designed to be called by user directly, it is called automatically by the system. Must be consistent with WriteToStream counterpart method.

    virtual void WriteToStream(std::ostream& str) const

Override this method to write custom state to auto save stream.

This method is not designed to be called by user directly, it is called automatically by the system. Must be consistent with ReadFromStream counterpart method.

    void DrawOnNextUpdate() const

Forces system to render on next update frame. Has effect when “optimized rendering” is enabled.

    static bool ReadStateVersion(std::istream& str, uint32_t expected_version)

Helper function for reading version number from input stream.

Parameters:

str | Stream to read version number from.
expected_version | Version number to compare stream version number to.

Returns:

Whether the number red is equal to the expected_version.

    static void WriteStateVersion(std::ostream& str, uint32_t version)

Helper function for writing version number to output stream.

Parameters:

str | Stream to write version number to.
version | Version number to write to stream.