Public Types | Public Member Functions | Static Public Member Functions | Protected Member Functions | List of all members
ime::ui::Button Class Reference

A widget that performs an action when clicked with the mouse. More...

#include <Button.h>

Inheritance diagram for ime::ui::Button:
ime::ui::ClickableWidget ime::ui::Widget ime::ITransformable

Public Types

using Ptr = std::unique_ptr< Button >
 Unique widget pointer. More...
 
using ConstPtr = std::unique_ptr< const Button >
 Const unique widget pointer. More...
 

Public Member Functions

 Button (const Button &)
 Copy constructor. More...
 
Buttonoperator= (const Button &)
 Copy assignment operator. More...
 
 Button (Button &&) noexcept
 Move constructor. More...
 
Buttonoperator= (Button &&) noexcept
 Move assignment operator. More...
 
Button::Ptr copy () const
 Create a copy of this widget. More...
 
ButtonRenderergetRenderer ()
 Get the buttons renderer. More...
 
const ButtonRenderergetRenderer () const
 
void setText (const std::string &text)
 Set the text displayed on the button. More...
 
std::string getText () const
 Get the text displayed on the button. More...
 
Widget::Ptr clone () const override
 Make a copy of this widget. More...
 
std::string getWidgetType () const override
 Get the type of the button. More...
 
 ~Button () override
 Destructor. More...
 
void setName (const std::string &name)
 Set the name of the widget. More...
 
const std::string & getName () const
 Get the name of the widget. More...
 
void setRenderer (IWidgetRenderer::Ptr renderer)
 Set the widgets renderer. More...
 
void setPosition (float x, float y) override
 Set the position of the widget. More...
 
void setPosition (const Vector2f &position) override
 Set the position of the widget. More...
 
void setPosition (const std::string &x, const std::string &y)
 Set the position of the widget relative to the size of its parent. More...
 
Vector2f getPosition () const override
 Get the position of the widget. More...
 
Vector2f getAbsolutePosition () const
 Get the absolute position of the widget. More...
 
void setRotation (float angle) override
 Set the orientation of the widget. More...
 
void rotate (float angle) override
 Rotate the widget. More...
 
float getRotation () const override
 Get the orientation of the widget. More...
 
void setScale (float factorX, float factorY) override
 Set the scale factors of the widget. More...
 
void setScale (const Vector2f &scale) override
 Set the scale factor of the widget. More...
 
void scale (float factorX, float factorY) override
 Scale the widget by an offset. More...
 
void scale (const Vector2f &factor) override
 Scale the widget by an offset. More...
 
Vector2f getScale () const override
 Get the current scale of the widget. More...
 
void setOrigin (float x, float y) override
 Set the local origin of the widget. More...
 
void setOrigin (const Vector2f &origin) override
 Set the local origin of the widget. More...
 
Vector2f getOrigin () const override
 Get the local origin of the widget. More...
 
void move (float offsetX, float offsetY) override
 Move the widget by a given offset. More...
 
void move (const Vector2f &offset) override
 Move the widget by a given offset. More...
 
void setTextSize (unsigned int size)
 Set the character size of the text. More...
 
unsigned int getTextSize () const
 Get the character size of the text. More...
 
void setSize (float width, float height)
 Set the size of the widget. More...
 
void setSize (const std::string &width, const std::string &height)
 Set the size of the widget relative to the size of its parent. More...
 
Vector2f getSize () const
 Get the size of the widget. More...
 
Vector2f getAbsoluteSize ()
 Get the absolute size of the widget. More...
 
void setWidth (float width)
 Set the width of the widget. More...
 
void setWidth (const std::string &width)
 Set the width of the widget relative to its parent. More...
 
void setHeight (float height)
 Set the height of the widget. More...
 
void setHeight (const std::string &height)
 Set the height of the widget relative to its parent. More...
 
void setFocused (bool isFocused)
 Focus or unfocus widget. More...
 
bool isFocused () const
 Check if widget is focused or not. More...
 
void setEnabled (bool isEnable)
 Enable or disable the widget. More...
 
bool isEnabled () const
 Check if widget is enabled or disabled. More...
 
void toggleEnabled ()
 Disable the widget if its currently enabled and vice versa. More...
 
void setMouseCursor (CursorType cursor)
 Set the mouse cursor that is displayed when the mouse is on top of the widget. More...
 
CursorType getMouseCursor () const
 Get the mouse cursor that is displayed when the mouse is on top of the widget. More...
 
void showWithEffect (AnimationType type, Time duration)
 Show the widget with an animation. More...
 
void hideWithEffect (AnimationType type, Time duration)
 Hide the widget with an animation. More...
 
bool isAnimationPlaying () const
 Check whether or not an animation is currently playing. More...
 
void setVisible (bool visible)
 Show or hide a widget. More...
 
bool isVisible () const
 Check if the widget is visible or not. More...
 
void toggleVisibility ()
 Toggle the visibility of the widget. More...
 
bool isContainer () const
 Check if the widget is a container or not. More...
 
bool contains (float x, float y) const
 Check if coordinates lie inside the widget. More...
 
template<typename... Args>
int on (const std::string &event, Callback< Args... > callback)
 Add an event listener to a widget event. More...
 
template<typename... Args>
int on (const std::string &event, Callback< Widget *, Args... > callback)
 Add an event listener to a widget event. More...
 
template<typename... Args>
void emit (const std::string &event, Args &&...args)
 Emit a widget event. More...
 
bool unsubscribe (const std::string &event, int id)
 Remove an event listener from a widget event. More...
 
const std::shared_ptr< void > getInternalPtr () const
 

Static Public Member Functions

static Button::Ptr create (const std::string &text="")
 Create a new button widget. More...
 

Protected Member Functions

void setAsContainer (bool container)
 Set whether or not the widget is a container. More...
 

Detailed Description

A widget that performs an action when clicked with the mouse.

Definition at line 39 of file Button.h.

Member Typedef Documentation

◆ ConstPtr

using ime::ui::Button::ConstPtr = std::unique_ptr<const Button>

Const unique widget pointer.

Definition at line 42 of file Button.h.

◆ Ptr

using ime::ui::Button::Ptr = std::unique_ptr<Button>

Unique widget pointer.

Definition at line 41 of file Button.h.

Constructor & Destructor Documentation

◆ Button() [1/2]

ime::ui::Button::Button ( const Button )

Copy constructor.

◆ Button() [2/2]

ime::ui::Button::Button ( Button &&  )
noexcept

Move constructor.

◆ ~Button()

ime::ui::Button::~Button ( )
override

Destructor.

Member Function Documentation

◆ clone()

Widget::Ptr ime::ui::Button::clone ( ) const
overridevirtual

Make a copy of this widget.

Returns
A copy of this widget

You should use this function if you don't care about the type of the widget, otherwise use the widgets copy function

See also
copy

Implements ime::ui::Widget.

◆ contains()

bool ime::ui::Widget::contains ( float  x,
float  y 
) const
inherited

Check if coordinates lie inside the widget.

Parameters
xX coordinate to be checked
yY coordinate to be checked
Returns
true if coordinates lie inside the widget, false if coordinates do not lie inside the widget

◆ copy()

Button::Ptr ime::ui::Button::copy ( ) const

Create a copy of this widget.

Returns
A copy of this widget
See also
clone

◆ create()

static Button::Ptr ime::ui::Button::create ( const std::string &  text = "")
static

Create a new button widget.

Parameters
textThe text to display on the button
Returns
The new button

◆ emit()

template<typename... Args>
void ime::ui::Widget::emit ( const std::string &  event,
Args &&...  args 
)
inlineinherited

Emit a widget event.

Parameters
eventName of the event to be emitted
argsArguments to pass to event listeners

This function will invoke all event listeners of the given event.

button.emit("click");
button.emit("click", ime::Vector2f{100, 200});

Definition at line 739 of file Widget.h.

◆ getAbsolutePosition()

Vector2f ime::ui::Widget::getAbsolutePosition ( ) const
inherited

Get the absolute position of the widget.

Returns
The absolute position of the widget

Unlike getPosition, this function returns the absolute position of the top-left point of the widget instead of the relative position to its parent

See also
setPosition

◆ getAbsoluteSize()

Vector2f ime::ui::Widget::getAbsoluteSize ( )
inherited

Get the absolute size of the widget.

Returns
The absolute size of the widget

The absolute size includes the size of the widget, the padding, margin and outline thickness

See also
getSize

◆ getMouseCursor()

CursorType ime::ui::Widget::getMouseCursor ( ) const
inherited

Get the mouse cursor that is displayed when the mouse is on top of the widget.

Returns
The cursor shown when hovering above the widget

◆ getName()

const std::string & ime::ui::Widget::getName ( ) const
inherited

Get the name of the widget.

Returns
The name of the widget
See also
setName

◆ getOrigin()

Vector2f ime::ui::Widget::getOrigin ( ) const
overridevirtualinherited

Get the local origin of the widget.

Returns
Local origin of the widget

Implements ime::ITransformable.

◆ getPosition()

Vector2f ime::ui::Widget::getPosition ( ) const
overridevirtualinherited

Get the position of the widget.

Returns
Current position of the widget

Implements ime::ITransformable.

◆ getRenderer()

ButtonRenderer * ime::ui::Button::getRenderer ( )

Get the buttons renderer.

Returns
The buttons renderer

The renderer gives access to functions that determine how the button is displayed. It allows you to manipulate things such as the background colour, text colour, border colour etc...

See also
setRenderer

◆ getRotation()

float ime::ui::Widget::getRotation ( ) const
overridevirtualinherited

Get the orientation of the widget.

Returns
Current rotation, in degrees

The rotation is always in the range [0, 360]

Implements ime::ITransformable.

◆ getScale()

Vector2f ime::ui::Widget::getScale ( ) const
overridevirtualinherited

Get the current scale of the widget.

Returns
Current scale of the widget

Implements ime::ITransformable.

◆ getSize()

Vector2f ime::ui::Widget::getSize ( ) const
inherited

Get the size of the widget.

Returns
Current size of the widget

This function only returns the size of the widget (It does not accommodate margin, outline thickness etc ...)

See also
getAbsoluteSize

◆ getText()

std::string ime::ui::Button::getText ( ) const

Get the text displayed on the button.

Returns
The text displayed oon the button

◆ getTextSize()

unsigned int ime::ui::Widget::getTextSize ( ) const
inherited

Get the character size of the text.

Returns
The character size of the text

◆ getWidgetType()

std::string ime::ui::Button::getWidgetType ( ) const
overridevirtual

Get the type of the button.

Returns
The type of the button

Implements ime::ui::Widget.

◆ hideWithEffect()

void ime::ui::Widget::hideWithEffect ( AnimationType  type,
Time  duration 
)
inherited

Hide the widget with an animation.

Parameters
typeType of the animation
durationDuration of the animation

The animation will also be played if the widget currently hidden but it will not be seen

Note
During the animation the position, size and/or opacity opacity may change. Once the animation is done the widget will be back in the state in which it was when this function was called
See also
showWithEffect
isAnimationPlaying

◆ isAnimationPlaying()

bool ime::ui::Widget::isAnimationPlaying ( ) const
inherited

Check whether or not an animation is currently playing.

Returns
True if an animation is playing, otherwise false
See also
showWithEffect
hideWithEffect

◆ isContainer()

bool ime::ui::Widget::isContainer ( ) const
inherited

Check if the widget is a container or not.

Returns
True if the widget is a container, otherwise false

A container widget is a widget that can store other widgets inside it. Such widgets inherit from IWidget class

◆ isEnabled()

bool ime::ui::Widget::isEnabled ( ) const
inherited

Check if widget is enabled or disabled.

Returns
True if widget is enabled, false if widget is disabled
See also
setEnabled

◆ isFocused()

bool ime::ui::Widget::isFocused ( ) const
inherited

Check if widget is focused or not.

Returns
True if widget is focused. Otherwise, false
See also
setFocused

◆ isVisible()

bool ime::ui::Widget::isVisible ( ) const
inherited

Check if the widget is visible or not.

Returns
True if the widget is visible or false if hidden

◆ move() [1/2]

void ime::ui::Widget::move ( const Vector2f offset)
overridevirtualinherited

Move the widget by a given offset.

Parameters
offsetOffset to apply

This function adds to the current position of the widget, unlike setPosition which overwrites it

See also
setPosition

Implements ime::ITransformable.

◆ move() [2/2]

void ime::ui::Widget::move ( float  offsetX,
float  offsetY 
)
overridevirtualinherited

Move the widget by a given offset.

Parameters
offsetXHorizontal offset
offsetYVertical offset

This function adds to the current position of the widget, unlike setPosition which overwrites it

See also
setPosition

Implements ime::ITransformable.

◆ on() [1/2]

template<typename... Args>
int ime::ui::Widget::on ( const std::string &  event,
Callback< Args... >  callback 
)
inlineinherited

Add an event listener to a widget event.

Parameters
eventEvent to add an event listener to
callbackFunction to execute when the event is fired
Returns
The event listeners identification number

The callback is passed event arguments (if any) on invocation. Here is an example demonstrating an event listener listening to an event with and arguments

// Event without arguments
widget.on("mouseEnter", ime::Callback<>([] {
std::cout << "Mouse entered widget" << "\n";
}));
// Event with arguments
widget.on("positionChange", ime::Callback<ime::Vector2f>([](ime::Vector2f pos) {
std::cout << "Widget moved to {" << pos.x << ", " << pos.y << "}" << "\n";
})):
T x
X coordinate of the vector.
Definition: Vector2.h:109
T y
Y coordinate of the vector.
Definition: Vector2.h:110
std::function< void(Args...)> Callback
Event listener.
Definition: EventEmitter.h:38
See also
unsubscribe

Definition at line 689 of file Widget.h.

◆ on() [2/2]

template<typename... Args>
int ime::ui::Widget::on ( const std::string &  event,
Callback< Widget *, Args... >  callback 
)
inlineinherited

Add an event listener to a widget event.

Parameters
eventEvent to add an event listener to
callbackFunction to execute when the event is fired
Returns
The event listeners identification number

The callback is passed a pointer to the widget as the first argument followed by the event arguments (if any) on invocation

// Event without arguments
widget.on("mouseEnter", ime::Callback<ime::ui::Widget*>([](ime::ui::Widget* widget) {
std::cout << "Mouse entered " << widget->getName() << "\n";
}));
// Event with arguments
std::cout << "Widget " << widget->getName() << " moved to {" << pos.x << ", " << pos.y << "}" << "\n";
})):
An Abstract Base Class for Graphical User Interface (GUI) elements.
Definition: Widget.h:86
const std::string & getName() const
Get the name of the widget.
int on(const std::string &event, Callback< Args... > callback)
Add an event listener to a widget event.
Definition: Widget.h:689
Note
Event listeners without the context/widget pointer are invoked first
See also
unsubscribe

Definition at line 721 of file Widget.h.

◆ operator=() [1/2]

Button & ime::ui::Button::operator= ( Button &&  )
noexcept

Move assignment operator.

◆ operator=() [2/2]

Button & ime::ui::Button::operator= ( const Button )

Copy assignment operator.

◆ rotate()

void ime::ui::Widget::rotate ( float  angle)
overridevirtualinherited

Rotate the widget.

Parameters
angleAngle of rotation, in degrees

This function adds to the current rotation of the widget, unlike setRotation which overwrites it

See also
setRotation

Implements ime::ITransformable.

◆ scale() [1/2]

void ime::ui::Widget::scale ( const Vector2f factor)
overridevirtualinherited

Scale the widget by an offset.

Parameters
factorOffset to apply

This function multiplies the current scale of the widget, unlike setScale which overwrites it

See also
setScale

Implements ime::ITransformable.

◆ scale() [2/2]

void ime::ui::Widget::scale ( float  factorX,
float  factorY 
)
overridevirtualinherited

Scale the widget by an offset.

Parameters
factorXHorizontal scale factor
factorYVertical scale factor

This function multiplies the current scale of the widget, unlike setScale which overwrites it

See also
setScale

Implements ime::ITransformable.

◆ setAsContainer()

void ime::ui::Widget::setAsContainer ( bool  container)
protectedinherited

Set whether or not the widget is a container.

Parameters
containerTrue to flag as container, otherwise false

A container widget is a widget that can store other widgets inside it. Such widgets inherit from IWidget class

All widgets are not containers by default

◆ setEnabled()

void ime::ui::Widget::setEnabled ( bool  isEnable)
inherited

Enable or disable the widget.

Parameters
isEnableSet true to enable the widget or false to disable the widget

If the widget is disabled, it wont not receive events and hence does won't dispatch callbacks

By default, the widget is enabled

See also
isEnabled

◆ setFocused()

void ime::ui::Widget::setFocused ( bool  isFocused)
inherited

Focus or unfocus widget.

Parameters
isFocusedTrue to focus or false to unfocus widget

When the widget is focused, a previously focused widget will be unfocused

Note
This function only works properly if the widget has already been added to the gui (see ime::ui::GuiContainer)

By default, the widget is not focused

See also
isFocused

◆ setHeight() [1/2]

void ime::ui::Widget::setHeight ( const std::string &  height)
inherited

Set the height of the widget relative to its parent.

Parameters
heightNew height

The relative height is given in percentages as shown:

widget->setHeight("10%");

This function sets the height of the widget while keeping the width the same

See also
setSize

◆ setHeight() [2/2]

void ime::ui::Widget::setHeight ( float  height)
inherited

Set the height of the widget.

Parameters
heightNew height of the widget

This function sets the height while keeping the width the same

See also
setSize

◆ setMouseCursor()

void ime::ui::Widget::setMouseCursor ( CursorType  cursor)
inherited

Set the mouse cursor that is displayed when the mouse is on top of the widget.

Parameters
cursorThe cursor to be shown

By default, the arrow cursor is shown

◆ setName()

void ime::ui::Widget::setName ( const std::string &  name)
inherited

Set the name of the widget.

Parameters
nameThe name of the widget

By default the widget is assigned a unique name. The naming convention is as follows:

widgetType + instantiation number

For example:

ime::Button::Ptr myBtn = ime::Button::create("Click me");
std::cout << myBtn->getName(); // Button1
ime::Label::Ptr lblGreet = ime::Label::create("Hello");
std::cout << lblGreet->getName(); // Label1
std::cout << lblGreet->copy()->getName(); // Label2
Warning
The name must not contain white spaces
See also
getName

◆ setOrigin() [1/2]

void ime::ui::Widget::setOrigin ( const Vector2f origin)
overridevirtualinherited

Set the local origin of the widget.

Parameters
originNew origin

The origin of the widget defines the center point for all transformations (position, scale, rotation). The coordinates of this point must be relative to the top-left corner of the widget, and ignore all transformations (position, scale, rotation).

The default origin of the widget is (0, 0)

Implements ime::ITransformable.

◆ setOrigin() [2/2]

void ime::ui::Widget::setOrigin ( float  x,
float  y 
)
overridevirtualinherited

Set the local origin of the widget.

Parameters
xX coordinate of the new origin
yY coordinate of the new origin

The origin of the widget defines the center point for all transformations (position, scale, rotation). The coordinates of this point must be relative to the top-left corner of the widget, and ignore all transformations (position, scale, rotation).

The default origin of the widget is (0, 0)

Implements ime::ITransformable.

◆ setPosition() [1/3]

void ime::ui::Widget::setPosition ( const std::string &  x,
const std::string &  y 
)
inherited

Set the position of the widget relative to the size of its parent.

Parameters
xNew x coordinate of the widget
yNew y coordinate of the widget

The position is specified in percentages as shown below:

widget->setPosition("5%", "10%");

This function completely overwrites the previous position. Use the move function to apply an offset based on the previous position instead.

The default position of the widget is (0, 0)

See also
move

◆ setPosition() [2/3]

void ime::ui::Widget::setPosition ( const Vector2f position)
overridevirtualinherited

Set the position of the widget.

Parameters
positionNew position

This function completely overwrites the previous position. Use the move function to apply an offset based on the previous position instead.

The default position of the widget is (0, 0)

See also
move

Implements ime::ITransformable.

◆ setPosition() [3/3]

void ime::ui::Widget::setPosition ( float  x,
float  y 
)
overridevirtualinherited

Set the position of the widget.

Parameters
xX coordinate of the new position
yY coordinate of the new position

This function completely overwrites the previous position. use move function to apply an offset based on the previous position instead

The default position of a the widget is (0, 0)

See also
move

Implements ime::ITransformable.

◆ setRenderer()

void ime::ui::Widget::setRenderer ( IWidgetRenderer::Ptr  renderer)
inherited

Set the widgets renderer.

Parameters
rendererThe new renderer

The renderer determines how the widget is displayed.

See also
getRenderer

◆ setRotation()

void ime::ui::Widget::setRotation ( float  angle)
overridevirtualinherited

Set the orientation of the widget.

Parameters
angleNew rotation, in degrees

This function completely overwrites the previous rotation. See the rotate function to add an angle based on the previous rotation instead.

The default rotation of the widget is 0

See also
rotate

Implements ime::ITransformable.

◆ setScale() [1/2]

void ime::ui::Widget::setScale ( const Vector2f scale)
overridevirtualinherited

Set the scale factor of the widget.

Parameters
scaleNew scale

This function completely overwrites the previous scale

See also
scale

Implements ime::ITransformable.

◆ setScale() [2/2]

void ime::ui::Widget::setScale ( float  factorX,
float  factorY 
)
overridevirtualinherited

Set the scale factors of the widget.

Parameters
factorXNew horizontal scale factor
factorYNew vertical scale factor

This function completely overwrites the previous scale

See also
scale

Implements ime::ITransformable.

◆ setSize() [1/2]

void ime::ui::Widget::setSize ( const std::string &  width,
const std::string &  height 
)
inherited

Set the size of the widget relative to the size of its parent.

Parameters
widthThe new width of the widget
heightThe new height of the widget

The size is specified in percentages as shown below:

widget->setSize("20%", "5%");

◆ setSize() [2/2]

void ime::ui::Widget::setSize ( float  width,
float  height 
)
inherited

Set the size of the widget.

Parameters
widthThe width of the widget
heightThe height of the widget

◆ setText()

void ime::ui::Button::setText ( const std::string &  text)

Set the text displayed on the button.

Parameters
textText to display

This function will overwrite any text that was previously set

◆ setTextSize()

void ime::ui::Widget::setTextSize ( unsigned int  size)
inherited

Set the character size of the text.

Parameters
sizeNew character size

◆ setVisible()

void ime::ui::Widget::setVisible ( bool  visible)
inherited

Show or hide a widget.

Parameters
visibleTrue to show or false to hide

If the widget is hidden, it won't receive events (and thus won't send callbacks) nor will it be drawn

The widget is visible by default.

◆ setWidth() [1/2]

void ime::ui::Widget::setWidth ( const std::string &  width)
inherited

Set the width of the widget relative to its parent.

Parameters
widthNew width

The relative width is given in percentages as shown:

widget->setWidth("10%");

This function sets the width of the widget while keeping the height the same

See also
setSize

◆ setWidth() [2/2]

void ime::ui::Widget::setWidth ( float  width)
inherited

Set the width of the widget.

Parameters
widthNew width of the widget

This function sets the width while keeping the height the same

See also
setSize

◆ showWithEffect()

void ime::ui::Widget::showWithEffect ( AnimationType  type,
Time  duration 
)
inherited

Show the widget with an animation.

Parameters
typeType of the animation
durationDuration of the animation

The animation will be played if the widget currently visible

Note
During the animation the position, size and/or opacity opacity may change. Once the animation is done the widget will be back in the state in which it was when this function was called
See also
hideWithEffect
isAnimationPlaying

◆ toggleEnabled()

void ime::ui::Widget::toggleEnabled ( )
inherited

Disable the widget if its currently enabled and vice versa.

If the widget is disabled, it wont not receive events and hence does won't dispatch callbacks

See also
setEnabled

◆ toggleVisibility()

void ime::ui::Widget::toggleVisibility ( )
inherited

Toggle the visibility of the widget.

This function will hide the widget if its currently visible and vice versa

See also
setVisible

◆ unsubscribe()

bool ime::ui::Widget::unsubscribe ( const std::string &  event,
int  id 
)
inherited

Remove an event listener from a widget event.

Parameters
eventEvent to remove event listener from
idId number of the event listener
Returns
True if the event listener was removed or false if the given event does not exist or the event does not have an event listener with the given id

The id is the number given when the event listener was registered

See also
on

The documentation for this class was generated from the following file: