src/script/api/script_sign.hpp

   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_sign.hpp Everything to query and build signs. */
   9
  10 #ifndef SCRIPT_SIGN_HPP
  11 #define SCRIPT_SIGN_HPP
  12
  13 #include "script_company.hpp"
  14 #include "script_error.hpp"
  15
  16 /**
  17  * Class that handles all sign related functions.
  18  * @api ai game
  19  */
  20 class ScriptSign : public ScriptObject {
  21 public:
  22         /**
  23          * All sign related error messages.
  24          */
  25         enum ErrorMessages {
  26
  27                 /** Base for sign building related errors */
  28                 ERR_SIGN_BASE = ScriptError::ERR_CAT_SIGN << ScriptError::ERR_CAT_BIT_SIZE,
  29
  30                 /** Too many signs have been placed */
  31                 ERR_SIGN_TOO_MANY_SIGNS,             // [STR_ERROR_TOO_MANY_SIGNS]
  32         };
  33
  34         /**
  35          * Checks whether the given sign index is valid.
  36          * @param sign_id The index to check.
  37          * @return True if and only if the sign is valid.
  38          */
  39         static bool IsValidSign(SignID sign_id);
  40
  41         /**
  42          * Set the name of a sign.
  43          * @param sign_id The sign to set the name for.
  44          * @param name The name for the sign (can be either a raw string, or a ScriptText object).
  45          * @pre IsValidSign(sign_id).
  46          * @pre name != null && len(name) != 0.
  47          * @exception ScriptError::ERR_NAME_IS_NOT_UNIQUE
  48          * @return True if and only if the name was changed.
  49          */
  50         static bool SetName(SignID sign_id, Text *name);
  51
  52         /**
  53          * Get the name of the sign.
  54          * @param sign_id The sign to get the name of.
  55          * @pre IsValidSign(sign_id).
  56          * @return The name of the sign.
  57          */
  58         static std::optional<std::string> GetName(SignID sign_id);
  59
  60         /**
  61          * Get the owner of a sign.
  62          * @param sign_id The sign to get the owner of.
  63          * @pre IsValidSign(sign_id).
  64          * @return The owner the sign has.
  65          * @api -ai
  66          */
  67         static ScriptCompany::CompanyID GetOwner(SignID sign_id);
  68
  69         /**
  70          * Gets the location of the sign.
  71          * @param sign_id The sign to get the location of.
  72          * @pre IsValidSign(sign_id).
  73          * @return The location of the sign.
  74          */
  75         static TileIndex GetLocation(SignID sign_id);
  76
  77         /**
  78          * Builds a sign on the map.
  79          * @param location The place to build the sign.
  80          * @param name The text to place on the sign (can be either a raw string, or a ScriptText object).
  81          * @pre ScriptMap::IsValidTile(location).
  82          * @pre name != null && len(name) != 0.
  83          * @exception ScriptSign::ERR_SIGN_TOO_MANY_SIGNS
  84          * @return The SignID of the build sign (use IsValidSign() to check for validity).
  85          *   In test-mode it returns 0 if successful, or any other value to indicate
  86          *   failure.
  87          */
  88         static SignID BuildSign(TileIndex location, Text *name);
  89
  90         /**
  91          * Removes a sign from the map.
  92          * @param sign_id The sign to remove.
  93          * @pre IsValidSign(sign_id).
  94          * @return True if and only if the sign has been removed.
  95          */
  96         static bool RemoveSign(SignID sign_id);
  97 };
  98
  99 #endif /* SCRIPT_SIGN_HPP */