src/script/api/script_window.hpp.in

   1 /*
   2  * This file is part of OpenTTD.
   3  * OpenTTD is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 2.
   4  * OpenTTD is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
   5  * See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with OpenTTD. If not, see <http://www.gnu.org/licenses/>.
   6  */
   7
   8 /** @file script_window.hpp Everything to handle window interaction. */
   9
  10 #ifndef SCRIPT_WINDOW_HPP
  11 #define SCRIPT_WINDOW_HPP
  12
  13 #include "script_object.hpp"
  14
  15 ${INCLUDES}
  16
  17 /**
  18  * Class that handles window interaction. A Window in OpenTTD has two important
  19  *  values. The WindowClass, and a Window number. The first indicates roughly
  20  *  which window it is. WC_TOWN_VIEW for example, is the view of a town.
  21  * The Window number is a bit more complex, as it depends mostly on the
  22  *  WindowClass. For example for WC_TOWN_VIEW it is the TownID. In general a
  23  *  good rule of thumb is: either the number is always 0, or the ID of the
  24  *  object in question.
  25  * In the comment at the widget enum, it is mentioned how the number is used.
  26  *
  27  * Note, that the detailed window layout is very version specific.
  28  * Enum values might be added, changed or removed in future versions without notice
  29  * in the changelog, and there won't be any means of compatibility.
  30  *
  31  * @api game
  32  */
  33 class ScriptWindow : public ScriptObject {
  34 public:
  35         // @enum WindowNumberEnum ../../window_type.h@ENUM_WINDOWNUMBERENUM@
  36         // @endenum
  37
  38         // @enum WindowClass ../../window_type.h@ENUM_WINDOWCLASS@
  39         // @endenum
  40
  41         /**
  42          * The colours in the game which you can use for text and highlights.
  43          */
  44         enum TextColour {
  45                 /* Note: these values represent part of the in-game TextColour enum */
  46                 TC_BLUE        = ::TC_BLUE,        ///< Blue colour.
  47                 TC_SILVER      = ::TC_SILVER,      ///< Silver colour.
  48                 TC_GOLD        = ::TC_GOLD,        ///< Gold colour.
  49                 TC_RED         = ::TC_RED,         ///< Red colour.
  50                 TC_PURPLE      = ::TC_PURPLE,      ///< Purple colour.
  51                 TC_LIGHT_BROWN = ::TC_LIGHT_BROWN, ///< Light brown colour.
  52                 TC_ORANGE      = ::TC_ORANGE,      ///< Orange colour.
  53                 TC_GREEN       = ::TC_GREEN,       ///< Green colour.
  54                 TC_YELLOW      = ::TC_YELLOW,      ///< Yellow colour.
  55                 TC_DARK_GREEN  = ::TC_DARK_GREEN,  ///< Dark green colour.
  56                 TC_CREAM       = ::TC_CREAM,       ///< Cream colour.
  57                 TC_BROWN       = ::TC_BROWN,       ///< Brown colour.
  58                 TC_WHITE       = ::TC_WHITE,       ///< White colour.
  59                 TC_LIGHT_BLUE  = ::TC_LIGHT_BLUE,  ///< Light blue colour.
  60                 TC_GREY        = ::TC_GREY,        ///< Grey colour.
  61                 TC_DARK_BLUE   = ::TC_DARK_BLUE,   ///< Dark blue colour.
  62                 TC_BLACK       = ::TC_BLACK,       ///< Black colour.
  63                 TC_INVALID     = ::TC_INVALID,     ///< Invalid colour.
  64         };
  65
  66         /**
  67          * Special number values.
  68          */
  69         enum NumberType {
  70                 NUMBER_ALL = -1, ///< Value to select all windows of a class.
  71         };
  72
  73         /**
  74          * Special widget values.
  75          */
  76         enum WidgetType {
  77                 WIDGET_ALL = -1, ///< Value to select all widgets of a window.
  78         };
  79
  80         /**
  81          * Close a window.
  82          * @param window The class of the window to close.
  83          * @param number The number of the window to close, or NUMBER_ALL to close all of this class.
  84          *               The value will be clamped to 0 .. MAX(int32_t) when value is not NUMBER_ALL.
  85          * @pre !ScriptGame::IsMultiplayer().
  86          */
  87         static void Close(WindowClass window, SQInteger number);
  88
  89         /**
  90          * Check if a window is open.
  91          * @param window The class of the window to check for.
  92          * @param number The number of the window to check for, or NUMBER_ALL to check for any in the class.
  93          *               The value will be clamped to 0 .. MAX(int32_t) when value is not NUMBER_ALL.
  94          * @pre !ScriptGame::IsMultiplayer().
  95          * @return True if the window is open.
  96          */
  97         static bool IsOpen(WindowClass window, SQInteger number);
  98
  99         /**
 100          * Highlight a widget in a window.
 101          * @param window The class of the window to highlight a widget in.
 102          * @param number The number of the window to highlight a widget in.
 103          *               The value will be clamped to 0 .. MAX(int32_t) when value is not NUMBER_ALL.
 104          * @param widget The widget in the window to highlight, or WIDGET_ALL (in combination with TC_INVALID) to disable all widget highlighting on this window.
 105          *               The value will be clamped to 0 .. MAX(uint8_t) when value is not WIDGET_ALL.
 106          * @param colour The colour of the highlight, or TC_INVALID for disabling.
 107          * @pre !ScriptGame::IsMultiplayer().
 108          * @pre number != NUMBER_ALL.
 109          * @pre colour < TC_END || (widget == WIDGET_ALL && colour == TC_INVALID).
 110          * @pre IsOpen(window, number).
 111          */
 112         static void Highlight(WindowClass window, SQInteger number, SQInteger widget, TextColour colour);
 113
 114         // @enum .*Widgets ../../widgets/*_widget.h@ENUM_WIDGETS@
 115         // @endenum
 116 };
 117
 118 #endif /* SCRIPT_WINDOW_HPP */