Class SdlBuilderExtensions

Namespace

Sdl3Sharp

Assembly

Sdl3Sharp.dll

Provides extensions for Sdl.Builder

public static class SdlBuilderExtensions

Inheritance

object

SdlBuilderExtensions

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Methods

SetAppCopyright(Builder, string?, bool)

Sets the human-readable copyright notice

public static Sdl.Builder SetAppCopyright(this Sdl.Builder builder, string? appCopyright, bool throwOnFailure = false)

Parameters

builder Sdl.Builder

The Sdl.Builder to use

appCopyright string

The copyright notice, like "Copyright (c) 2024 MojoWorkshop, LLC" or whatnot

throwOnFailure bool

A value indicating whether to fail silently (false), or to throw an exception on failure (true)

Returns

Sdl.Builder

The current Sdl.Builder so that additional calls can be chained

Remarks

You can optionally provide metadata about your app to SDL. This is not required, but strongly encouraged.

Keep the metadata to one line, don't paste a copy of a whole software license in here.

In contrast to most of the remaining API which uses the Try-method pattern, this method intentionally fails silently, if throwOnFailure is false, or fails by throwing an exception, if throwOnFailure is true. If you want to handle failures wrap the call to this method with throwOnFailure set to true in a try-block, and check TryGet(out string?) for more information when catching a SdlException.

Exceptions

SdlException

Couldn't set the metadata (check TryGet(out string?) for more information); only when throwOnFailure is true

InvalidOperationException

The Sdl.Builder is used outside of the initialization process of a Sdl instance

SetAppCreator(Builder, string?, bool)

Sets the human-readable name of the creator/developer/maker of this app

public static Sdl.Builder SetAppCreator(this Sdl.Builder builder, string? appCreator, bool throwOnFailure = false)

Parameters

builder Sdl.Builder

The Sdl.Builder to use

appCreator string

The name of the creator/developer/maker of this app like "MojoWorkshop, LLC"

throwOnFailure bool

A value indicating whether to fail silently (false), or to throw an exception on failure (true)

Returns

Sdl.Builder

The current Sdl.Builder so that additional calls can be chained

Remarks

You can optionally provide metadata about your app to SDL. This is not required, but strongly encouraged.

In contrast to most of the remaining API which uses the Try-method pattern, this method intentionally fails silently, if throwOnFailure is false, or fails by throwing an exception, if throwOnFailure is true. If you want to handle failures wrap the call to this method with throwOnFailure set to true in a try-block, and check TryGet(out string?) for more information when catching a SdlException.

Exceptions

SdlException

Couldn't set the metadata (check TryGet(out string?) for more information); only when throwOnFailure is true

InvalidOperationException

The Sdl.Builder is used outside of the initialization process of a Sdl instance

SetAppIdentifier(Builder, string?, bool)

Sets a unique string that identifies this app

public static Sdl.Builder SetAppIdentifier(this Sdl.Builder builder, string? appIdentifier, bool throwOnFailure = false)

Parameters

builder Sdl.Builder

The Sdl.Builder to use

appIdentifier string

The identifier of this app in reverse-domain format, like "com.example.mygame2"

throwOnFailure bool

A value indicating whether to fail silently (false), or to throw an exception on failure (true)

Returns

Sdl.Builder

The current Sdl.Builder so that additional calls can be chained

Remarks

You can optionally provide metadata about your app to SDL. This is not required, but strongly encouraged.

The metadata is used by desktop compositors to identify and group windows together, as well as match applications with associated desktop settings and icons. If you plan to package your application in a container such as Flatpak, the app ID should match the name of your Flatpak container as well.

In contrast to most of the remaining API which uses the Try-method pattern, this method intentionally fails silently, if throwOnFailure is false, or fails by throwing an exception, if throwOnFailure is true. If you want to handle failures wrap the call to this method with throwOnFailure set to true in a try-block, and check TryGet(out string?) for more information when catching a SdlException.

Exceptions

SdlException

Couldn't set the metadata (check TryGet(out string?) for more information); only when throwOnFailure is true

InvalidOperationException

The Sdl.Builder is used outside of the initialization process of a Sdl instance

SetAppName(Builder, string?, bool)

Sets the human-readable name of the application

public static Sdl.Builder SetAppName(this Sdl.Builder builder, string? appName, bool throwOnFailure = false)

Parameters

builder Sdl.Builder

The Sdl.Builder to use

appName string

The name of the app, like "My Game 2: Bad Guy's Revenge!"

throwOnFailure bool

A value indicating whether to fail silently (false), or to throw an exception on failure (true)

Returns

Sdl.Builder

The current Sdl.Builder so that additional calls can be chained

Remarks

You can optionally provide metadata about your app to SDL. This is not required, but strongly encouraged.

The metadata will show up anywhere the OS shows the name of the application separately from window titles, such as volume control applets, etc.

In contrast to most of the remaining API which uses the Try-method pattern, this method intentionally fails silently, if throwOnFailure is false, or fails by throwing an exception, if throwOnFailure is true. If you want to handle failures wrap the call to this method with throwOnFailure set to true in a try-block, and check TryGet(out string?) for more information when catching a SdlException.

Exceptions

SdlException

Couldn't set the metadata (check TryGet(out string?) for more information); only when throwOnFailure is true

InvalidOperationException

The Sdl.Builder is used outside of the initialization process of a Sdl instance

SetAppType(Builder, string?, bool)

Sets the type of application

public static Sdl.Builder SetAppType(this Sdl.Builder builder, string? appType, bool throwOnFailure = false)

Parameters

builder Sdl.Builder

The Sdl.Builder to use

appType string

The type of application

throwOnFailure bool

A value indicating whether to fail silently (false), or to throw an exception on failure (true)

Returns

Sdl.Builder

The current Sdl.Builder so that additional calls can be chained

Remarks

You can optionally provide metadata about your app to SDL. This is not required, but strongly encouraged.

Currently the metadata can be "game" for a video game, "mediaplayer" for a media player, or generically "application" if nothing else applies. Future versions of SDL might add new types.

In contrast to most of the remaining API which uses the Try-method pattern, this method intentionally fails silently, if throwOnFailure is false, or fails by throwing an exception, if throwOnFailure is true. If you want to handle failures wrap the call to this method with throwOnFailure set to true in a try-block, and check TryGet(out string?) for more information when catching a SdlException.

Exceptions

SdlException

Couldn't set the metadata (check TryGet(out string?) for more information); only when throwOnFailure is true

InvalidOperationException

The Sdl.Builder is used outside of the initialization process of a Sdl instance

SetAppUrl(Builder, string?, bool)

Sets a URL to the app on the web

public static Sdl.Builder SetAppUrl(this Sdl.Builder builder, string? appUrl, bool throwOnFailure = false)

Parameters

builder Sdl.Builder

The Sdl.Builder to use

appUrl string

The URL of this app

throwOnFailure bool

A value indicating whether to fail silently (false), or to throw an exception on failure (true)

Returns

Sdl.Builder

The current Sdl.Builder so that additional calls can be chained

Remarks

You can optionally provide metadata about your app to SDL. This is not required, but strongly encouraged.

The URL maybe a product page, or a storefront, or even a GitHub repository, for user's further information.

In contrast to most of the remaining API which uses the Try-method pattern, this method intentionally fails silently, if throwOnFailure is false, or fails by throwing an exception, if throwOnFailure is true. If you want to handle failures wrap the call to this method with throwOnFailure set to true in a try-block, and check TryGet(out string?) for more information when catching a SdlException.

Exceptions

SdlException

Couldn't set the metadata (check TryGet(out string?) for more information); only when throwOnFailure is true

InvalidOperationException

The Sdl.Builder is used outside of the initialization process of a Sdl instance

SetAppVersion(Builder, string?, bool)

Sets the version of the app

public static Sdl.Builder SetAppVersion(this Sdl.Builder builder, string? appVersion, bool throwOnFailure = false)

Parameters

builder Sdl.Builder

The Sdl.Builder to use

appVersion string

The version of the app

throwOnFailure bool

A value indicating whether to fail silently (false), or to throw an exception on failure (true)

Returns

Sdl.Builder

The current Sdl.Builder so that additional calls can be chained

Remarks

You can optionally provide metadata about your app to SDL. This is not required, but strongly encouraged.

There are no rules on format, so "1.0.3beta2" and "April 22nd, 2024" and a git hash are all valid options.

In contrast to most of the remaining API which uses the Try-method pattern, this method intentionally fails silently, if throwOnFailure is false, or fails by throwing an exception, if throwOnFailure is true. If you want to handle failures wrap the call to this method with throwOnFailure set to true in a try-block, and check TryGet(out string?) for more information when catching a SdlException.

Exceptions

SdlException

Couldn't set the metadata (check TryGet(out string?) for more information); only when throwOnFailure is true

InvalidOperationException

The Sdl.Builder is used outside of the initialization process of a Sdl instance

SetMetadata(Builder, string, string?, bool)

Sets metadata about your app

public static Sdl.Builder SetMetadata(this Sdl.Builder builder, string name, string? value, bool throwOnFailure = false)

Parameters

builder Sdl.Builder

The Sdl.Builder to use

name string

The name of the metadata

value string

The value of the metadata, or null to remove that metadata

throwOnFailure bool

A value indicating whether to fail silently (false), or to throw an exception on failure (true)

Returns

Sdl.Builder

The current Sdl.Builder so that additional calls can be chained

Remarks

You can optionally provide metadata about your app to SDL. This is not required, but strongly encouraged.

There are several locations where SDL can make use of metadata (an "About" box in the macOS menu bar, the name of the app can be shown on some audio mixers, etc). Any piece of metadata can be left out, if a specific detail doesn't make sense for the app.

See Sdl.Metadata for a overview over the available metadata properties and their meanings.

Multiple calls to this method with the same name value are allowed, but various state might not change once it has been already set up.

In contrast to most of the remaining API which uses the Try-method pattern, this method intentionally fails silently, if throwOnFailure is false, or fails by throwing an exception, if throwOnFailure is true. If you want to handle failures wrap the call to this method with throwOnFailure set to true in a try-block, and check TryGet(out string?) for more information when catching a SdlException.

Exceptions

SdlException

Couldn't set the metadata (check TryGet(out string?) for more information); only when throwOnFailure is true

InvalidOperationException

The Sdl.Builder is used outside of the initialization process of a Sdl instance

SetMetadata(Builder, string?, string?, string?, bool)

Sets basic metadata about your app

public static Sdl.Builder SetMetadata(this Sdl.Builder builder, string? appName, string? appVersion, string? appIdentifier, bool throwOnFailure = false)

Parameters

builder Sdl.Builder

The Sdl.Builder to use

appName string

The name of the application ("My Game 2: Bad Guy's Revenge!")

appVersion string

The version of the application ("1.0.0beta5" or a git hash, or whatever makes sense)

appIdentifier string

A unique string in reverse-domain format that identifies this app ("com.example.mygame2")

throwOnFailure bool

A value indicating whether to fail silently (false), or to throw an exception on failure (true)

Returns

Sdl.Builder

The current Sdl.Builder so that additional calls can be chained

Remarks

You can optionally provide metadata about your app to SDL. This is not required, but strongly encouraged.

There are several locations where SDL can make use of metadata (an "About" box in the macOS menu bar, the name of the app can be shown on some audio mixers, etc). Any piece of metadata can be left out as a null value, if a specific detail doesn't make sense for the app.

Passing a null value removes any previous metadata.

Multiple calls to this method are allowed, but various state might not change once it has been already set up.

This is a simplified interface for the most important information. You can supply significantly more detailed metadata with SetMetadata(Builder, string, string?, bool).

In contrast to most of the remaining API which uses the Try-method pattern, this method intentionally fails silently, if throwOnFailure is false, or fails by throwing an exception, if throwOnFailure is true. If you want to handle failures wrap the call to this method with throwOnFailure set to true in a try-block, and check TryGet(out string?) for more information when catching a SdlException.

Exceptions

SdlException

Couldn't set the metadata (check TryGet(out string?) for more information); only when throwOnFailure is true

InvalidOperationException

The Sdl.Builder is used outside of the initialization process of a Sdl instance