include/SDL_messagebox.h
author David Ludwig <dludwig@pobox.com>
Sat, 29 Nov 2014 10:09:30 -0500
changeset 9247 eddb899239fe
parent 8149 681eb46b8ac4
child 9619 b94b6d0bff0f
permissions -rw-r--r--
WinRT: bug and data-integrity fixes for SDL_GetPrefPath()

This change does a few things, all with regards to the WinRT implementation of
SDL_GetPrefPath():

1. it fixes a bug whereby SDL_GetPrefPath() did not create the directory it
returned. On other SDL platforms, SDL_GetPrefPath() will create separate
directories for its 'org' and 'app' folders. Without this, attempts to create
files in the pref-path would fail, unless those directories were first created
by the app, or by some other library the app used. This change makes sure
that these directories get created, before SDL_GetPrefPath() returns to its
caller(s).


2. it defaults to having SDL_GetPrefPath() return a WinRT 'Local' folder
on all platforms. Previously, for Windows Store apps, it would have used a
different, 'Roaming' folder. Files in Roaming folders can be automatically,
and synchronized across multiple devices by Windows. This synchronization can
happen while the app runs, with new files being copied into a running app's
pref-path. Unless an app is specifically designed to handle this scenario,
there is a chance that save-data could be overwritten in unwanted or
unexpected ways.

The default is now to use a Local folder, which does not get synchronized, and
which is arguably a bit safer to use. Apps that wish to use Roaming folders
can do so by setting SDL_HINT_WINRT_PREF_PATH_ROOT to "roaming", however it
is recommended that one first read Microsoft's documentation for Roaming
files, a link to which is provided in README-winrt.md.

To preserve older pref-path selection behavior (found in SDL 2.0.3, as well as
many pre-2.0.4 versions of SDL from hg.libsdl.org), which uses a Roaming path
in Windows Store apps, and a Local path in Windows Phone, set
SDL_HINT_WINRT_PREF_PATH_ROOT to "old".

Please note that Roaming paths are not supported on Windows Phone 8.0, due to
limitations in the OS itself. Attempts to use this will fail.
(Windows Phone 8.1 does not have this limitation, however.)


3. It makes SDL_GetPrefPath(), when on Windows Phone 8.0, and when
SDL_HINT_WINRT_PREF_PATH_ROOT is set to "roaming", return NULL, rather than
silently defaulting to a Local path (then switching to a Roaming path if and
when the user upgraded to Windows Phone 8.1).
slouken@6602
     1
/*
slouken@6602
     2
  Simple DirectMedia Layer
slouken@8149
     3
  Copyright (C) 1997-2014 Sam Lantinga <slouken@libsdl.org>
slouken@6602
     4
slouken@6602
     5
  This software is provided 'as-is', without any express or implied
slouken@6602
     6
  warranty.  In no event will the authors be held liable for any damages
slouken@6602
     7
  arising from the use of this software.
slouken@6602
     8
slouken@6602
     9
  Permission is granted to anyone to use this software for any purpose,
slouken@6602
    10
  including commercial applications, and to alter it and redistribute it
slouken@6602
    11
  freely, subject to the following restrictions:
slouken@6602
    12
slouken@6602
    13
  1. The origin of this software must not be misrepresented; you must not
slouken@6602
    14
     claim that you wrote the original software. If you use this software
slouken@6602
    15
     in a product, an acknowledgment in the product documentation would be
slouken@6602
    16
     appreciated but is not required.
slouken@6602
    17
  2. Altered source versions must be plainly marked as such, and must not be
slouken@6602
    18
     misrepresented as being the original software.
slouken@6602
    19
  3. This notice may not be removed or altered from any source distribution.
slouken@6602
    20
*/
slouken@6602
    21
slouken@6602
    22
#ifndef _SDL_messagebox_h
slouken@6602
    23
#define _SDL_messagebox_h
slouken@6602
    24
slouken@6602
    25
#include "SDL_stdinc.h"
slouken@6602
    26
#include "SDL_video.h"      /* For SDL_Window */
slouken@6602
    27
slouken@6602
    28
#include "begin_code.h"
slouken@6602
    29
/* Set up for C function definitions, even when using C++ */
slouken@6602
    30
#ifdef __cplusplus
slouken@6602
    31
extern "C" {
slouken@6602
    32
#endif
slouken@6602
    33
slouken@6602
    34
/**
slouken@6602
    35
 * \brief SDL_MessageBox flags. If supported will display warning icon, etc.
slouken@6602
    36
 */
slouken@6602
    37
typedef enum
slouken@6602
    38
{
slouken@6602
    39
    SDL_MESSAGEBOX_ERROR        = 0x00000010,   /**< error dialog */
slouken@6602
    40
    SDL_MESSAGEBOX_WARNING      = 0x00000020,   /**< warning dialog */
icculus@6679
    41
    SDL_MESSAGEBOX_INFORMATION  = 0x00000040    /**< informational dialog */
slouken@6602
    42
} SDL_MessageBoxFlags;
slouken@6602
    43
slouken@6602
    44
/**
slouken@6602
    45
 * \brief Flags for SDL_MessageBoxButtonData.
slouken@6602
    46
 */
slouken@6602
    47
typedef enum
slouken@6602
    48
{
slouken@6602
    49
    SDL_MESSAGEBOX_BUTTON_RETURNKEY_DEFAULT = 0x00000001,  /**< Marks the default button when return is hit */
icculus@6679
    50
    SDL_MESSAGEBOX_BUTTON_ESCAPEKEY_DEFAULT = 0x00000002   /**< Marks the default button when escape is hit */
slouken@6602
    51
} SDL_MessageBoxButtonFlags;
slouken@6602
    52
slouken@6602
    53
/**
slouken@6602
    54
 *  \brief Individual button data.
slouken@6602
    55
 */
slouken@6602
    56
typedef struct
slouken@6602
    57
{
slouken@6602
    58
    Uint32 flags;       /**< ::SDL_MessageBoxButtonFlags */
philipp@7175
    59
    int buttonid;       /**< User defined button id (value returned via SDL_ShowMessageBox) */
slouken@6602
    60
    const char * text;  /**< The UTF-8 button text */
slouken@6602
    61
} SDL_MessageBoxButtonData;
slouken@6602
    62
slouken@6602
    63
/**
slouken@6602
    64
 * \brief RGB value used in a message box color scheme
slouken@6602
    65
 */
slouken@6602
    66
typedef struct
slouken@6602
    67
{
slouken@6602
    68
    Uint8 r, g, b;
slouken@6602
    69
} SDL_MessageBoxColor;
slouken@6602
    70
slouken@6602
    71
typedef enum
slouken@6602
    72
{
icculus@6680
    73
    SDL_MESSAGEBOX_COLOR_BACKGROUND,
icculus@6680
    74
    SDL_MESSAGEBOX_COLOR_TEXT,
icculus@6680
    75
    SDL_MESSAGEBOX_COLOR_BUTTON_BORDER,
icculus@6680
    76
    SDL_MESSAGEBOX_COLOR_BUTTON_BACKGROUND,
icculus@6680
    77
    SDL_MESSAGEBOX_COLOR_BUTTON_SELECTED,
icculus@6680
    78
    SDL_MESSAGEBOX_COLOR_MAX
slouken@6602
    79
} SDL_MessageBoxColorType;
slouken@6602
    80
slouken@6602
    81
/**
slouken@6602
    82
 * \brief A set of colors to use for message box dialogs
slouken@6602
    83
 */
slouken@6602
    84
typedef struct
slouken@6602
    85
{
slouken@6602
    86
    SDL_MessageBoxColor colors[SDL_MESSAGEBOX_COLOR_MAX];
slouken@6602
    87
} SDL_MessageBoxColorScheme;
slouken@6602
    88
slouken@6602
    89
/**
slouken@6602
    90
 *  \brief MessageBox structure containing title, text, window, etc.
slouken@6602
    91
 */
slouken@6602
    92
typedef struct
slouken@6602
    93
{
slouken@6602
    94
    Uint32 flags;                       /**< ::SDL_MessageBoxFlags */
slouken@6602
    95
    SDL_Window *window;                 /**< Parent window, can be NULL */
slouken@6602
    96
    const char *title;                  /**< UTF-8 title */
slouken@6602
    97
    const char *message;                /**< UTF-8 message text */
slouken@6602
    98
slouken@6602
    99
    int numbuttons;
slouken@6602
   100
    const SDL_MessageBoxButtonData *buttons;
slouken@6602
   101
slouken@6602
   102
    const SDL_MessageBoxColorScheme *colorScheme;   /**< ::SDL_MessageBoxColorScheme, can be NULL to use system settings */
slouken@6602
   103
} SDL_MessageBoxData;
slouken@6602
   104
slouken@6602
   105
/**
slouken@6602
   106
 *  \brief Create a modal message box.
slouken@6602
   107
 *
philipp@7175
   108
 *  \param messageboxdata The SDL_MessageBoxData structure with title, text, etc.
philipp@7188
   109
 *  \param buttonid The pointer to which user id of hit button should be copied.
slouken@6602
   110
 *
slouken@6602
   111
 *  \return -1 on error, otherwise 0 and buttonid contains user id of button
slouken@6602
   112
 *          hit or -1 if dialog was closed.
slouken@6613
   113
 *
slouken@6613
   114
 *  \note This function should be called on the thread that created the parent
slouken@6613
   115
 *        window, or on the main thread if the messagebox has no parent.  It will
slouken@6613
   116
 *        block execution of that thread until the user clicks a button or
slouken@6613
   117
 *        closes the messagebox.
slouken@6602
   118
 */
slouken@6602
   119
extern DECLSPEC int SDLCALL SDL_ShowMessageBox(const SDL_MessageBoxData *messageboxdata, int *buttonid);
slouken@6602
   120
slouken@6602
   121
/**
slouken@6602
   122
 *  \brief Create a simple modal message box
slouken@6602
   123
 *
slouken@6602
   124
 *  \param flags    ::SDL_MessageBoxFlags
slouken@6602
   125
 *  \param title    UTF-8 title text
slouken@6602
   126
 *  \param message  UTF-8 message text
slouken@6602
   127
 *  \param window   The parent window, or NULL for no parent
slouken@6602
   128
 *
slouken@6602
   129
 *  \return 0 on success, -1 on error
slouken@6613
   130
 *
slouken@6613
   131
 *  \sa SDL_ShowMessageBox
slouken@6602
   132
 */
slouken@6602
   133
extern DECLSPEC int SDLCALL SDL_ShowSimpleMessageBox(Uint32 flags, const char *title, const char *message, SDL_Window *window);
slouken@6602
   134
slouken@6602
   135
slouken@6602
   136
/* Ends C function definitions when using C++ */
slouken@6602
   137
#ifdef __cplusplus
slouken@6602
   138
}
slouken@6602
   139
#endif
slouken@6602
   140
#include "close_code.h"
slouken@6602
   141
slouken@6602
   142
#endif /* _SDL_messagebox_h */
slouken@6602
   143
slouken@6602
   144
/* vi: set ts=4 sw=4 expandtab: */