Struct UserEvent

Namespace

Sdl3Sharp.Events

Assembly

Sdl3Sharp.dll

Represents an user defined event

public struct UserEvent : ICommonEvent<UserEvent>, ICommonEvent, ISpanFormattable, IFormattable

Implements

ICommonEvent<UserEvent>

ICommonEvent

ISpanFormattable

IFormattable

Inherited Members

ValueType.Equals(object)

ValueType.GetHashCode()

object.Equals(object, object)

object.GetType()

object.ReferenceEquals(object, object)

Remarks

An UserEvent is unique; it is never created by SDL, but only by the application. The event can be pushed onto the event queue using TryPushEvent(in Event). The contents of the structure members are completely up to the programmer; the only requirement is that it's Type is a registered user defined event type obtained from TryRegister(out EventType) or TryRegister(Span<EventType>).

If you want to populate the managed user defined data slots, Data1 and Data2, you'll need to handle their lifetimes via an UserEventLifetime instance. You can then use it's GetEvent(EventType, ulong, uint, int) method to obtain an UserEvent where you'll be able to use it's managed user defined data slots, Data1 and Data2.

If you don't intend to use non-blittable or managed data, you can always use the raw user defined data slots, RawData1 and RawData2, freely.

Note: You shouldn't access the any of the raw user defined data slots when you use the corresponding managed user defined data slots. E.g., overwriting the value of RawData1 will lead to a loss of data in Data1 and Data1 won't be accessable anymore.

Associated EventTypes: User defined EventTypes registered using TryRegister(out EventType) or TryRegister(Span<EventType>).

Properties

Code

Gets or sets the user defined event code

public int Code { readonly get; set; }

Property Value

int

The user defined event code

Remarks

You can freely set this to any value of your liking. For example, you could use this property to further distinguish your user defined events.

Data1

Gets or sets the value of the first managed user defined data slot

public readonly object? Data1 { get; set; }

Property Value

object

The value of the first managed user defined data slot

Remarks

You should only access this property if the user defined event is backed by a UserEventLifetime. If it's not, or the UserEventLifetime is already disposed, accessing this property will lead to a InvalidOperationException been thrown.

You can freely set this to anything of your liking as long as the UserEvent is backed by a UserEventLifetime.

Note: If you intend to use this property, don't overwrite the value of it's associated raw user defined data slot, RawData1. If you do, that will lead to a loss of data in Data1 and Data1 won't be accessable anymore.

Exceptions

InvalidOperationException

The UserEvent might not be backed by an UserEventLifetime, the backening UserEventLifetime was already disposed, or the corresponding RawData property of the UserEvent was overridden at some point

InvalidOperationException

The UserEvent might not be backed by an UserEventLifetime, the backening UserEventLifetime was already disposed, or the corresponding RawData property of the UserEvent was overridden at some point

Data2

Gets or sets the value of the second managed user defined data slot

public readonly object? Data2 { get; set; }

Property Value

object

The value of the second managed user defined data slot

Remarks

You should only access this property if the user defined event is backed by a UserEventLifetime. If it's not, or the UserEventLifetime is already disposed, accessing this property will lead to a InvalidOperationException been thrown.

Note: If you intend to use this property, don't overwrite the value of it's associated raw user defined data slot, RawData2. If you do, that will lead to a loss of data in Data2 and Data2 won't be accessable anymore.

Exceptions

InvalidOperationException

The UserEvent might not be backed by an UserEventLifetime, the backening UserEventLifetime was already disposed, or the corresponding RawData property of the UserEvent was overridden at some point

InvalidOperationException

The UserEvent might not be backed by an UserEventLifetime, the backening UserEventLifetime was already disposed, or the corresponding RawData property of the UserEvent was overridden at some point

RawData1

Gets or sets the value of the first raw user defined data slot

public nint RawData1 { readonly get; set; }

Property Value

nint

The value of the first raw user defined data slot

Remarks

You should not overwrite the value of this property if the user defined event is backed by a UserEventLifetime. If you do, that will lead to a loss of data in Data1 and Data1 won't be accessable anymore.

You can freely set this to anything of your liking, as long as you don't intend to use Data1 as a managed user defined data slot.

RawData2

Gets or sets the value of the second raw user defined data slot

public nint RawData2 { readonly get; set; }

Property Value

nint

The value of the second raw user defined data slot

Remarks

You should not overwrite the value of this property if the user defined event is backed by a UserEventLifetime. If you do, that will lead to a loss of data in Data2 and Data2 won't be accessable anymore.

You can freely set this to anything of your liking, as long as you don't intend to use Data2 as a managed user defined data slot.

Timestamp

Gets or sets the timestamp of the current event

public ulong Timestamp { readonly get; set; }

Property Value

ulong

The timestamp of the current event, in nanoseconds in nanoseconds since the initialization of SDL

Remarks

The value of this property usually describes the time passed, in nanoseconds since the initialization of SDL. It can be properly populated by using NanosecondTicks.

Type

Gets or sets the type of the current event

public EventType Type { readonly get; set; }

Property Value

EventType

The type of the current event

Remarks

When setting this property, the value must be a valid value for UserEvents. Otherwise, it will lead the property to throw an ArgumentException! Try registering user defined event type using TryRegister(out EventType) or TryRegister(Span<EventType>).

Exceptions

ArgumentException

When setting this property, the value was not valid for UserEvents

WindowId

Gets or sets the window Id of the Window associated with this event, if any

public uint WindowId { readonly get; set; }

Property Value

uint

The window Id of the Window associated with this event, if any, or 0

Methods

ToString()

Returns the fully qualified type name of this instance.

public override readonly string ToString()

Returns

string

The fully qualified type name.

ToString(IFormatProvider?)

Formats the value of the current instance using the specified format.

public readonly string ToString(IFormatProvider? formatProvider)

Parameters

formatProvider IFormatProvider

The provider to use to format the value.

-or-

A null reference (Nothing in Visual Basic) to obtain the numeric format information from the current locale setting of the operating system.

Returns

string

The value of the current instance in the specified format.

ToString(string?)

Formats the value of the current instance using the specified format.

public readonly string ToString(string? format)

Parameters

format string

The format to use.

-or-

A null reference (Nothing in Visual Basic) to use the default format defined for the type of the IFormattable implementation.

Returns

string

The value of the current instance in the specified format.

ToString(string?, IFormatProvider?)

Formats the value of the current instance using the specified format.

public readonly string ToString(string? format, IFormatProvider? formatProvider)

Parameters

format string

The format to use.

-or-

A null reference (Nothing in Visual Basic) to use the default format defined for the type of the IFormattable implementation.

formatProvider IFormatProvider

The provider to use to format the value.

-or-

A null reference (Nothing in Visual Basic) to obtain the numeric format information from the current locale setting of the operating system.

Returns

string

The value of the current instance in the specified format.

TryFormat(Span<char>, out int, ReadOnlySpan<char>, IFormatProvider?)

Tries to format the value of the current instance into the provided span of characters.

public readonly bool TryFormat(Span<char> destination, out int charsWritten, ReadOnlySpan<char> format = default, IFormatProvider? provider = null)

Parameters

destination Span<char>

The span in which to write this instance's value formatted as a span of characters.

charsWritten int

When this method returns, contains the number of characters that were written in destination.

format ReadOnlySpan<char>

A span containing the characters that represent a standard or custom format string that defines the acceptable format for destination.

provider IFormatProvider

An optional object that supplies culture-specific formatting information for destination.

Returns

bool

true if the formatting was successful; otherwise, false.

Operators

explicit operator UserEvent(in Event)

Converts a general Event to an event of type UserEvent

public static explicit operator UserEvent(in Event @event)

Parameters

event Event

The general Event to convert to an event of type UserEvent

Returns

UserEvent

Remarks

The Type of the given event must be a valid value for UserEvents. Otherwise, it will lead the method to throw an ArgumentException! Try registering user defined event type using TryRegister(out EventType) or TryRegister(Span<EventType>).

Exceptions

ArgumentException

The Type of the given event was not valid for UserEvents

implicit operator Event(in UserEvent)

Converts an event of type UserEvent to a general Event

public static implicit operator Event(in UserEvent @event)

Parameters

event UserEvent

The event of type UserEvent to convert to a general Event

Returns

Event

Remarks

This conversion usually requires the event to be copied into a new general Event structure. Note: This can impact performance!