SDL_hints.c File Reference

#include "./SDL_internal.h"
#include "SDL_hints.h"
#include "SDL_error.h"

Include dependency graph for SDL_hints.c:

Go to the source code of this file.

Data Structures
struct	SDL_HintWatch
struct	SDL_Hint

Functions
SDL_bool	SDL_SetHintWithPriority (const char *name, const char *value, SDL_HintPriority priority)
	Set a hint with a specific priority.
SDL_bool	SDL_SetHint (const char *name, const char *value)
	Set a hint with normal priority.
const char *	SDL_GetHint (const char *name)
	Get a hint.
SDL_bool	SDL_GetHintBoolean (const char *name, SDL_bool default_value)
	Get a hint.
void	SDL_AddHintCallback (const char *name, SDL_HintCallback callback, void *userdata)
	Add a function to watch a particular hint.
void	SDL_DelHintCallback (const char *name, SDL_HintCallback callback, void *userdata)
	Remove a function watching a particular hint.
void	SDL_ClearHints (void)
	Clear all hints.

Variables
static SDL_Hint *	SDL_hints

Function Documentation

void SDL_AddHintCallback	(	const char *	name,
		SDL_HintCallback	callback,
		void *	userdata
	)

Add a function to watch a particular hint.

Parameters

name	The hint to watch
callback	The function to call when the hint value changes
userdata	A pointer to pass to the callback function

Definition at line 135 of file SDL_hints.c.

References SDL_HintWatch::callback, callback(), SDL_Hint::callbacks, SDL_Hint::name, SDL_HintWatch::next, SDL_Hint::next, NULL, SDL_Hint::priority, SDL_DelHintCallback, SDL_free, SDL_GetHint, SDL_HINT_DEFAULT, SDL_hints, SDL_InvalidParamError, SDL_malloc, SDL_OutOfMemory, SDL_strcmp, SDL_strdup, SDL_HintWatch::userdata, and SDL_Hint::value.

{
    SDL_Hint *hint;
    SDL_HintWatch *entry;
    const char *value;

    if (!name || !*name) {
        SDL_InvalidParamError("name");
        return;
    }
    if (!callback) {
        SDL_InvalidParamError("callback");
        return;
    }

    SDL_DelHintCallback(name, callback, userdata);

    entry = (SDL_HintWatch *)SDL_malloc(sizeof(*entry));
    if (!entry) {
        SDL_OutOfMemory();
        return;
    }
    entry->callback = callback;
    entry->userdata = userdata;

    for (hint = SDL_hints; hint; hint = hint->next) {
        if (SDL_strcmp(name, hint->name) == 0) {
            break;
        }
    }
    if (!hint) {
        /* Need to add a hint entry for this watcher */
        hint = (SDL_Hint *)SDL_malloc(sizeof(*hint));
        if (!hint) {
            SDL_OutOfMemory();
            SDL_free(entry);
            return;
        }
        hint->name = SDL_strdup(name);
        hint->value = NULL;
        hint->priority = SDL_HINT_DEFAULT;
        hint->callbacks = NULL;
        hint->next = SDL_hints;
        SDL_hints = hint;
    }

    /* Add it to the callbacks for this hint */
    entry->next = hint->callbacks;
    hint->callbacks = entry;

    /* Now call it with the current value */
    value = SDL_GetHint(name);
    callback(userdata, name, value, value);
}

void SDL_ClearHints

(

void

)

Clear all hints.

This function is called during SDL_Quit() to free stored hints.

Definition at line 216 of file SDL_hints.c.

References SDL_Hint::callbacks, SDL_Hint::name, SDL_HintWatch::next, SDL_Hint::next, SDL_free, SDL_hints, and SDL_Hint::value.

{
    SDL_Hint *hint;
    SDL_HintWatch *entry;

    while (SDL_hints) {
        hint = SDL_hints;
        SDL_hints = hint->next;

        SDL_free(hint->name);
        SDL_free(hint->value);
        for (entry = hint->callbacks; entry; ) {
            SDL_HintWatch *freeable = entry;
            entry = entry->next;
            SDL_free(freeable);
        }
        SDL_free(hint);
    }
}

void SDL_DelHintCallback	(	const char *	name,
		SDL_HintCallback	callback,
		void *	userdata
	)

Remove a function watching a particular hint.

Parameters

name	The hint being watched
callback	The function being called when the hint value changes
userdata	A pointer being passed to the callback function

Definition at line 191 of file SDL_hints.c.

References SDL_HintWatch::callback, SDL_Hint::callbacks, SDL_Hint::name, SDL_HintWatch::next, SDL_Hint::next, NULL, SDL_free, SDL_strcmp, and SDL_HintWatch::userdata.

{
    SDL_Hint *hint;
    SDL_HintWatch *entry, *prev;

    for (hint = SDL_hints; hint; hint = hint->next) {
        if (SDL_strcmp(name, hint->name) == 0) {
            prev = NULL;
            for (entry = hint->callbacks; entry; entry = entry->next) {
                if (callback == entry->callback && userdata == entry->userdata) {
                    if (prev) {
                        prev->next = entry->next;
                    } else {
                        hint->callbacks = entry->next;
                    }
                    SDL_free(entry);
                    break;
                }
                prev = entry;
            }
            return;
        }
    }
}

const char* SDL_GetHint

(

const char *

name

)

Get a hint.

Returns

The string value of a hint variable.

Definition at line 104 of file SDL_hints.c.

References SDL_Hint::name, SDL_Hint::next, SDL_Hint::priority, SDL_getenv, SDL_HINT_OVERRIDE, SDL_strcmp, and SDL_Hint::value.

{
    const char *env;
    SDL_Hint *hint;

    env = SDL_getenv(name);
    for (hint = SDL_hints; hint; hint = hint->next) {
        if (SDL_strcmp(name, hint->name) == 0) {
            if (!env || hint->priority == SDL_HINT_OVERRIDE) {
                return hint->value;
            }
            break;
        }
    }
    return env;
}

SDL_bool SDL_GetHintBoolean	(	const char *	name,
		SDL_bool	default_value
	)

Get a hint.

Returns

The boolean value of a hint variable.

Definition at line 122 of file SDL_hints.c.

References SDL_FALSE, SDL_GetHint, SDL_strcasecmp, and SDL_TRUE.

{
    const char *hint = SDL_GetHint(name);
    if (!hint || !*hint) {
        return default_value;
    }
    if (*hint == '0' || SDL_strcasecmp(hint, "false") == 0) {
        return SDL_FALSE;
    }
    return SDL_TRUE;
}

SDL_bool SDL_SetHint	(	const char *	name,
		const char *	value
	)

Set a hint with normal priority.

Returns

SDL_TRUE if the hint was set, SDL_FALSE otherwise

Definition at line 98 of file SDL_hints.c.

References SDL_HINT_NORMAL, and SDL_SetHintWithPriority.

{
    return SDL_SetHintWithPriority(name, value, SDL_HINT_NORMAL);
}

SDL_bool SDL_SetHintWithPriority	(	const char *	name,
		const char *	value,
		SDL_HintPriority	priority
	)

Set a hint with a specific priority.

The priority controls the behavior when setting a hint that already has a value. Hints will replace existing hints of their priority and lower. Environment variables are considered to have override priority.

Returns

SDL_TRUE if the hint was set, SDL_FALSE otherwise

Definition at line 47 of file SDL_hints.c.

References SDL_HintWatch::callback, SDL_Hint::callbacks, SDL_Hint::name, SDL_HintWatch::next, SDL_Hint::next, NULL, SDL_Hint::priority, SDL_FALSE, SDL_free, SDL_getenv, SDL_HINT_OVERRIDE, SDL_hints, SDL_malloc, SDL_strcmp, SDL_strdup, SDL_TRUE, SDL_HintWatch::userdata, and SDL_Hint::value.

{
    const char *env;
    SDL_Hint *hint;
    SDL_HintWatch *entry;

    if (!name || !value) {
        return SDL_FALSE;
    }

    env = SDL_getenv(name);
    if (env && priority < SDL_HINT_OVERRIDE) {
        return SDL_FALSE;
    }

    for (hint = SDL_hints; hint; hint = hint->next) {
        if (SDL_strcmp(name, hint->name) == 0) {
            if (priority < hint->priority) {
                return SDL_FALSE;
            }
            if (!hint->value || !value || SDL_strcmp(hint->value, value) != 0) {
                for (entry = hint->callbacks; entry; ) {
                    /* Save the next entry in case this one is deleted */
                    SDL_HintWatch *next = entry->next;
                    entry->callback(entry->userdata, name, hint->value, value);
                    entry = next;
                }
                SDL_free(hint->value);
                hint->value = value ? SDL_strdup(value) : NULL;
            }
            hint->priority = priority;
            return SDL_TRUE;
        }
    }

    /* Couldn't find the hint, add a new one */
    hint = (SDL_Hint *)SDL_malloc(sizeof(*hint));
    if (!hint) {
        return SDL_FALSE;
    }
    hint->name = SDL_strdup(name);
    hint->value = value ? SDL_strdup(value) : NULL;
    hint->priority = priority;
    hint->callbacks = NULL;
    hint->next = SDL_hints;
    SDL_hints = hint;
    return SDL_TRUE;
}

Variable Documentation

SDL_Hint* SDL_hints

static

Definition at line 44 of file SDL_hints.c.

Referenced by SDL_AddHintCallback(), SDL_ClearHints(), and SDL_SetHintWithPriority().