/src/gui/guidialog.h

https://bitbucket.org/thunderk/stormwar · C Header · 188 lines · 30 code · 16 blank · 142 comment · 0 complexity · 25134132df93ac12dcd1f86885dadbb2 MD5 · raw file

  1. /******************************************************************************
  2. * StormWar, a Real Time Strategy game *
  3. * Copyright (C) 2005 LEMAIRE Michael *
  4. *----------------------------------------------------------------------------*
  5. * This program is free software; you can redistribute it and/or modify *
  6. * it under the terms of the GNU General Public License as published by *
  7. * the Free Software Foundation; either version 2 of the License, or *
  8. * (at your option) any later version. *
  9. * *
  10. * This program is distributed in the hope that it will be useful, *
  11. * but WITHOUT ANY WARRANTY; without even the implied warranty of *
  12. * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the *
  13. * GNU General Public License for more details. *
  14. * *
  15. * You should have received a copy of the GNU General Public License *
  16. * along with this program; if not, write to the Free Software *
  17. * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA *
  18. * *
  19. * Read the full terms of this license in the "COPYING" file. *
  20. ****************************************************************************
  21. * *
  22. * Graphical dialog template *
  23. * *
  24. ***************************************************************************/
  25. /*!
  26. * \file
  27. * \brief This file defines a GUI dialog.
  28. *
  29. * A GuiDialog is a template to display a dialog for user interaction.
  30. *
  31. * Here is an example of how to use such a template:
  32. * \code
  33. * GuiDialog dialog;
  34. *
  35. * dialog = GuiDialog_new(GUIDIALOG_OKCANCEL, dialogcallback);
  36. * GuiDialog_addParagraph(dialog, "Hello World !");
  37. * GuiDialog_addTextInput(dialog, "answer", "How are you today ?", NULL, NULL);
  38. * GuiDialog_launch(dialog);
  39. * \endcode
  40. *
  41. * This example will create a message box with a simple text input and two buttons.
  42. *
  43. * The \a dialogcallback function will be called when the dialog closes, which
  44. * means the user clicked on a button. Here is an example of such a callback:
  45. * \code
  46. * static void dialogcallback(GuiDialogButton button, Var vinput)
  47. * {
  48. * if (button == GUIDIALOGBUTTON_OK)
  49. * {
  50. * Var v = Var_getArrayElemByCName(vinput, "answer");
  51. * printf("OK has been chosen and the anwser was %s.", String_get(Var_getValueString(v)));
  52. * }
  53. * else if (button == GUIDIALOGBUTTON_CANCEL)
  54. * {
  55. * printf("Cancel has been chosen.");
  56. * }
  57. * }
  58. * \endcode
  59. * You can see in this example that input fields of the dialog can be collected through
  60. * the variable returned by the callback.
  61. */
  62. #ifndef _SW_GUIDIALOG_H_
  63. #define _SW_GUIDIALOG_H_ 1
  64. /******************************************************************************
  65. * Includes *
  66. ******************************************************************************/
  67. #include "main.h"
  68. #include "core/types.h"
  69. /******************************************************************************
  70. * Typedefs *
  71. ******************************************************************************/
  72. /*!
  73. * \brief Private structure of a GuiDialog.
  74. */
  75. typedef struct pv_GuiDialog pv_GuiDialog;
  76. /*!
  77. * \brief Abstract type for a graphical dialog.
  78. */
  79. typedef pv_GuiDialog* GuiDialog;
  80. /*!
  81. * \brief Dialog type (will specify the dialog buttons).
  82. */
  83. typedef enum
  84. {
  85. GUIDIALOG_OK,
  86. GUIDIALOG_OKCANCEL,
  87. GUIDIALOG_YESNO,
  88. GUIDIALOG_YESNOCANCEL,
  89. GUIDIALOG_RETRYCANCEL
  90. } GuiDialogType;
  91. /*!
  92. * \brief Dialog buttons.
  93. */
  94. typedef enum
  95. {
  96. GUIDIALOGBUTTON_OK = 0,
  97. GUIDIALOGBUTTON_YES = 1,
  98. GUIDIALOGBUTTON_NO = 2,
  99. GUIDIALOGBUTTON_CANCEL = 3,
  100. GUIDIALOGBUTTON_RETRY = 4
  101. } GuiDialogButton;
  102. /*!
  103. * \brief Callback function that will be called on dialog closing.
  104. *
  105. * \param button - Button that caused the closing.
  106. * \param vinput - Named array containing dialog's input fields.
  107. */
  108. typedef void (*GuiDialogCallback) (GuiDialog dialog, GuiDialogButton button, Var vinput);
  109. /******************************************************************************
  110. *############################################################################*
  111. *# Shortcut functions #*
  112. *############################################################################*
  113. ******************************************************************************/
  114. /*!
  115. * \brief Show a popup with a simple text and an 'OK' button.
  116. *
  117. * This function is a shortcut and will not raise a callback.
  118. * It is provided for convenience.
  119. * \param text - The text that will be displayed.
  120. */
  121. void GuiDialog_popupMsg(const char* text);
  122. /******************************************************************************
  123. *############################################################################*
  124. *# Public functions #*
  125. *############################################################################*
  126. ******************************************************************************/
  127. /*!
  128. * \brief Create a dialog.
  129. *
  130. * A dialog can't be destroyed by calling a function. It only destroys itself.
  131. * The dialog won't be shown before GuiDialog_launch is called.
  132. * \param type - Type of dialog (specifies the buttons).
  133. * \param callback - Function that will be called when the user presses one of the buttons, can be NULL.
  134. * \return The newly allocated dialog.
  135. */
  136. GuiDialog GuiDialog_new(GuiDialogType type, GuiDialogCallback callback);
  137. /*!
  138. * \brief Destroy a dialog.
  139. *
  140. * This won't raise the dialog's callback.
  141. * \param dialog - The dialog to destroy.
  142. */
  143. void GuiDialog_del(GuiDialog dialog);
  144. /*!
  145. * \brief Effectively build a dialog.
  146. *
  147. * No GuiDialog_add... function can be called on this dialog after this.
  148. * This will show and center the dialog.
  149. * \param dialog - The dialog.
  150. */
  151. void GuiDialog_launch(GuiDialog dialog);
  152. /*!
  153. * \brief Add a text paragraph to the dialog.
  154. *
  155. * This must be called between GuiDialog_new and GuiDialog_launch.
  156. * \param dialog - The dialog.
  157. * \param text - Text paragraph, will be copied.
  158. */
  159. void GuiDialog_addParagraph(GuiDialog dialog, const char* text);
  160. /*!
  161. * \brief Add a text input field to the dialog.
  162. *
  163. * This must be called between GuiDialog_new and GuiDialog_launch.
  164. * This will fill a \ref VAR_STRING named '\a name' in the variable returned by the callback.
  165. * \param dialog - The dialog.
  166. * \param name - Identifier for the field (will be used in the \ref GuiDialogCallback variable).
  167. * \param label - Label that will be displayed before the input box.
  168. * \param tooltip - Tooltip to display, NULL if not.
  169. * \param defaulttext - Default text to fill in the box with, can be NULL.
  170. */
  171. void GuiDialog_addTextInput(GuiDialog dialog, const char* name, const char* label, const char* tooltip, const char* defaulttext);
  172. #endif