SFML 3.1.0
Loading...
Searching...
No Matches
Public Types | Public Member Functions | Static Public Member Functions | Friends | List of all members
sf::Cursor Class Reference
Window module

Cursor defines the appearance of a system cursor. More...

`#include <SFML/Window/Cursor.hpp>`

## Public Types
enum class | Type { Arrow , ArrowWait , Wait , Text , Hand , SizeHorizontal , SizeVertical , SizeTopLeftBottomRight , SizeBottomLeftTopRight , SizeLeft , SizeRight , SizeTop , SizeBottom , SizeTopLeft , SizeBottomRight , SizeBottomLeft , SizeTopRight , SizeAll , Cross , Help , NotAllowed }
| Enumeration of the native system cursor types. More...

## Public Member Functions
| ~Cursor ()
| Destructor.
| Cursor (const Cursor &)=delete
| Deleted copy constructor.
Cursor & | operator= (const Cursor &)=delete
| Deleted copy assignment.
| Cursor (Cursor &&) noexcept
| Move constructor.
Cursor & | operator= (Cursor &&) noexcept
| Move assignment.
| Cursor (const std::uint8_t *pixels, Vector2u size, Vector2u hotspot)
| Construct a cursor with the provided image.
| Cursor (Type type)
| Create a native system cursor.

## Static Public Member Functions
static std::optional< Cursor > | createFromPixels (const std::uint8_t *pixels, Vector2u size, Vector2u hotspot)
| Create a cursor with the provided image.
static std::optional< Cursor > | createFromSystem (Type type)
| Create a native system cursor.

## Friends
class | WindowBase

## Detailed Description

Cursor defines the appearance of a system cursor.

Warning
  Features related to Cursor are not supported on iOS and Android.

This class abstracts the operating system resources associated with either a native system cursor or a custom cursor.

After loading the cursor graphical appearance with either createFromPixels() or createFromSystem(), the cursor can be changed with sf::WindowBase::setMouseCursor().

The behavior is undefined if the cursor is destroyed while in use by the window.

Usage example:

sf::Window window;
// ... create window as usual ...
const auto cursor = sf::Cursor::createFromSystem(sf::Cursor::Type::Hand).value();
window.setMouseCursor(cursor);
sf::Cursor::createFromSystem
static std::optional< Cursor > createFromSystem(Type type)
Create a native system cursor.
sf::Cursor::Type::Hand
@ Hand
Pointing hand cursor.
Definition Cursor.hpp:95
sf::WindowBase::setMouseCursor
void setMouseCursor(const Cursor &cursor)
Set the displayed cursor to a native system cursor.
sf::Window
Window that serves as a target for OpenGL rendering.
Definition Window/Window.hpp:56

See also
  sf::WindowBase::setMouseCursor

Definition at line 50 of file Cursor.hpp.

## Member Enumeration Documentation

## ◆ Type

enum class sf::Cursor::Type
| strong

Enumeration of the native system cursor types.

Refer to the following table to determine which cursor is available on which platform.

Type | Linux | macOS | Windows
--- | --- | --- | ---
sf::Cursor::Type::Arrow | yes | yes | yes
sf::Cursor::Type::ArrowWait | no | no | yes
sf::Cursor::Type::Wait | yes | no | yes
sf::Cursor::Type::Text | yes | yes | yes
sf::Cursor::Type::Hand | yes | yes | yes
sf::Cursor::Type::SizeHorizontal | yes | yes | yes
sf::Cursor::Type::SizeVertical | yes | yes | yes
sf::Cursor::Type::SizeTopLeftBottomRight | no | yes* | yes
sf::Cursor::Type::SizeBottomLeftTopRight | no | yes* | yes
sf::Cursor::Type::SizeLeft | yes | yes** | yes**
sf::Cursor::Type::SizeRight | yes | yes** | yes**
sf::Cursor::Type::SizeTop | yes | yes** | yes**
sf::Cursor::Type::SizeBottom | yes | yes** | yes**
sf::Cursor::Type::SizeTopLeft | yes | yes** | yes**
sf::Cursor::Type::SizeTopRight | yes | yes** | yes**
sf::Cursor::Type::SizeBottomLeft | yes | yes** | yes**
sf::Cursor::Type::SizeBottomRight | yes | yes** | yes**
sf::Cursor::Type::SizeAll | yes | no | yes
sf::Cursor::Type::Cross | yes | yes | yes
sf::Cursor::Type::Help | yes | yes* | yes
sf::Cursor::Type::NotAllowed | yes | yes | yes

- These cursor types are undocumented so may not be available on all versions, but have been tested on 10.13

** On Windows and macOS, double-headed arrows are used

Enumerator
Arrow | Arrow cursor (default).
ArrowWait | Busy arrow cursor.
Wait | Busy cursor.
Text | I-beam, cursor when hovering over a field allowing text entry.
Hand | Pointing hand cursor.
SizeHorizontal | Horizontal double arrow cursor.
SizeVertical | Vertical double arrow cursor.
SizeTopLeftBottomRight | Double arrow cursor going from top-left to bottom-right.
SizeBottomLeftTopRight | Double arrow cursor going from bottom-left to top-right.
SizeLeft | Left arrow cursor on Linux, same as SizeHorizontal on other platforms.
SizeRight | Right arrow cursor on Linux, same as SizeHorizontal on other platforms.
SizeTop | Up arrow cursor on Linux, same as SizeVertical on other platforms.
SizeBottom | Down arrow cursor on Linux, same as SizeVertical on other platforms.
SizeTopLeft | Top-left arrow cursor on Linux, same as SizeTopLeftBottomRight on other platforms.
SizeBottomRight | Bottom-right arrow cursor on Linux, same as SizeTopLeftBottomRight on other platforms.
SizeBottomLeft | Bottom-left arrow cursor on Linux, same as SizeBottomLeftTopRight on other platforms.
SizeTopRight | Top-right arrow cursor on Linux, same as SizeBottomLeftTopRight on other platforms.
SizeAll | Combination of SizeHorizontal and SizeVertical.
Cross | Crosshair cursor.
Help | Help cursor.
NotAllowed | Action not allowed cursor.

Definition at line 89 of file Cursor.hpp.

## Constructor & Destructor Documentation

## ◆ ~Cursor()

sf::Cursor::~Cursor | ( |  | ) |

Destructor.

This destructor releases the system resources associated with this cursor, if any.

## ◆ Cursor() [1/4]

sf::Cursor::Cursor | ( | const Cursor & |  | ) |
| delete

Deleted copy constructor.

## ◆ Cursor() [2/4]

sf::Cursor::Cursor | ( | Cursor && |  | ) |
| noexcept

Move constructor.

## ◆ Cursor() [3/4]

sf::Cursor::Cursor | ( | const std::uint8_t * | pixels,
|  | Vector2u | size,
|  | Vector2u | hotspot )

Construct a cursor with the provided image.

pixels must be an array of size pixels in 32-bit RGBA format. If not, this will cause undefined behavior.

If pixels is nullptr or either of size's properties are 0, the current cursor is left unchanged and the function will return false.

In addition to specifying the pixel data, you can also specify the location of the hotspot of the cursor. The hotspot is the pixel coordinate within the cursor image which will be located exactly where the mouse pointer position is. Any mouse actions that are performed will return the window/screen location of the hotspot.

Warning
  On Unix platforms which do not support colored cursors, the pixels are mapped into a monochrome bitmap: pixels with an alpha channel to 0 are transparent, black if the RGB channel are close to zero, and white otherwise.

Parameters

  pixels | Array of pixels of the image
  size | Width and height of the image
  hotspot | (x,y) location of the hotspot

Exceptions

  sf::Exception | if the cursor could not be constructed

## ◆ Cursor() [4/4]

sf::Cursor::Cursor | ( | Type | type | ) |
| explicit

Create a native system cursor.

Refer to the list of cursor available on each system (see sf::Cursor::Type) to know whether a given cursor is expected to load successfully or is not supported by the operating system.

Parameters

  type | Native system cursor type

Exceptions

  sf::Exception | if the corresponding cursor is not natively supported by the operating system

## Member Function Documentation

## ◆ createFromPixels()

std::optional< Cursor > sf::Cursor::createFromPixels | ( | const std::uint8_t * | pixels,
|  | Vector2u | size,
|  | Vector2u | hotspot )
| static nodiscard

Create a cursor with the provided image.

pixels must be an array of size pixels in 32-bit RGBA format. If not, this will cause undefined behavior.

If pixels is nullptr or either of size's properties are 0, the current cursor is left unchanged and the function will return false.

In addition to specifying the pixel data, you can also specify the location of the hotspot of the cursor. The hotspot is the pixel coordinate within the cursor image which will be located exactly where the mouse pointer position is. Any mouse actions that are performed will return the window/screen location of the hotspot.

Warning
  On Unix platforms which do not support colored cursors, the pixels are mapped into a monochrome bitmap: pixels with an alpha channel to 0 are transparent, black if the RGB channel are close to zero, and white otherwise.

Parameters

  pixels | Array of pixels of the image
  size | Width and height of the image
  hotspot | (x,y) location of the hotspot

Returns
  Cursor if the cursor was successfully loaded; std::nullopt otherwise

## ◆ createFromSystem()

std::optional< Cursor > sf::Cursor::createFromSystem | ( | Type | type | ) |
| static nodiscard

Create a native system cursor.

Refer to the list of cursor available on each system (see sf::Cursor::Type) to know whether a given cursor is expected to load successfully or is not supported by the operating system.

Parameters

  type | Native system cursor type

Returns
  Cursor if and only if the corresponding cursor is natively supported by the operating system; std::nullopt otherwise

## ◆ operator=() [1/2]

Cursor & sf::Cursor::operator= | ( | const Cursor & |  | ) |
| delete

Deleted copy assignment.

## ◆ operator=() [2/2]

Cursor & sf::Cursor::operator= | ( | Cursor && |  | ) |
| noexcept

Move assignment.

## Friends And Related Symbol Documentation

## ◆ WindowBase

friend class WindowBase
| friend

Definition at line 245 of file Cursor.hpp.

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

- Cursor.hpp