src/script/api/script_league.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_league.hpp Everything to manipulate league tables. */
   9
  10 #ifndef SCRIPT_LEAGUE_HPP
  11 #define SCRIPT_LEAGUE_HPP
  12
  13 #include "script_company.hpp"
  14 #include "script_text.hpp"
  15 #include "../../league_type.h"
  16
  17 /**
  18  * Class that handles league table related functions.
  19  *
  20  * To create a league table:
  21  * 1. Create the league table
  22  * 2. Create league table elements that will be shown in the table in the order of their rating (higher=better).
  23  *
  24  * @api game
  25  */
  26 class ScriptLeagueTable : public ScriptObject {
  27 public:
  28         /**
  29          * The league table IDs.
  30          */
  31         enum LeagueTableID {
  32                 LEAGUE_TABLE_INVALID = ::INVALID_LEAGUE_TABLE, ///< An invalid league table id.
  33         };
  34
  35         /**
  36          * The league table element IDs.
  37          */
  38         enum LeagueTableElementID {
  39                 LEAGUE_TABLE_ELEMENT_INVALID = ::INVALID_LEAGUE_TABLE_ELEMENT, ///< An invalid league table element id.
  40         };
  41
  42         /**
  43          * The type of a link.
  44          */
  45         enum LinkType : uint8_t {
  46                 LINK_NONE = ::LT_NONE,             ///< No link
  47                 LINK_TILE = ::LT_TILE,             ///< Link a tile
  48                 LINK_INDUSTRY = ::LT_INDUSTRY,     ///< Link an industry
  49                 LINK_TOWN = ::LT_TOWN,             ///< Link a town
  50                 LINK_COMPANY = ::LT_COMPANY,       ///< Link a company
  51                 LINK_STORY_PAGE = ::LT_STORY_PAGE, ///< Link a story page
  52         };
  53
  54         /**
  55          * Check whether this is a valid league table ID.
  56          * @param table_id The LeagueTableID to check.
  57          * @return true iff this league table is valid.
  58          */
  59         static bool IsValidLeagueTable(LeagueTableID table_id);
  60
  61         /**
  62          * Check whether this is a valid league table element ID.
  63          * @param element_id The LeagueTableElementID to check.
  64          * @return true iff this league table element is valid.
  65          */
  66         static bool IsValidLeagueTableElement(LeagueTableElementID element_id);
  67
  68         /**
  69          * Create a new league table.
  70          * @param title League table title (can be either a raw string, or ScriptText object).
  71          * @param header The optional header text for the table (null is allowed).
  72          * @param footer The optional footer text for the table (null is allowed).
  73          * @return The new LeagueTableID, or LEAGUE_TABLE_INVALID if it failed.
  74          * @pre ScriptCompanyMode::IsDeity.
  75          * @pre title != null && len(title) != 0.
  76          */
  77         static LeagueTableID New(Text *title, Text *header, Text *footer);
  78
  79         /**
  80          * Create a new league table element.
  81          * @param table Id of the league table this element belongs to.
  82          * @param rating Value that elements are ordered by.
  83          * @param company Company to show the color blob for or INVALID_COMPANY.
  84          * @param text Text of the element (can be either a raw string, or ScriptText object).
  85          * @param score String representation of the score associated with the element (can be either a raw string, or ScriptText object).
  86          * @param link_type Type of the referenced object.
  87          * @param link_target Id of the referenced object.
  88          * @return The new LeagueTableElementID, or LEAGUE_TABLE_ELEMENT_INVALID if it failed.
  89          * @pre ScriptCompanyMode::IsDeity.
  90          * @pre IsValidLeagueTable(table).
  91          * @pre text != null && len(text) != 0.
  92          * @pre score != null && len(score) != 0.
  93          * @pre IsValidLink(Link(link_type, link_target)).
  94          */
  95         static LeagueTableElementID NewElement(LeagueTableID table, SQInteger rating, ScriptCompany::CompanyID company, Text *text, Text *score, LinkType link_type, SQInteger link_target);
  96
  97         /**
  98          * Update the attributes of a league table element.
  99          * @param element Id of the element to update
 100          * @param company Company to show the color blob for or INVALID_COMPANY.
 101          * @param text Text of the element (can be either a raw string, or ScriptText object).
 102          * @param link_type Type of the referenced object.
 103          * @param link_target Id of the referenced object.
 104          * @return True if the action succeeded.
 105          * @pre ScriptCompanyMode::IsDeity.
 106          * @pre IsValidLeagueTableElement(element).
 107          * @pre text != null && len(text) != 0.
 108          * @pre IsValidLink(Link(link_type, link_target)).
 109          */
 110         static bool UpdateElementData(LeagueTableElementID element, ScriptCompany::CompanyID company, Text *text, LinkType link_type, SQInteger link_target);
 111
 112         /**
 113          * Create a new league table element.
 114          * @param element Id of the element to update
 115          * @param rating Value that elements are ordered by.
 116          * @param score String representation of the score associated with the element (can be either a raw string, or ScriptText object).
 117          * @return True if the action succeeded.
 118          * @pre ScriptCompanyMode::IsDeity.
 119          * @pre IsValidLeagueTableElement(element).
 120          * @pre score != null && len(score) != 0.
 121          */
 122         static bool UpdateElementScore(LeagueTableElementID element, SQInteger rating, Text *score);
 123
 124
 125         /**
 126          * Remove a league table element.
 127          * @param element Id of the element to update
 128          * @return True if the action succeeded.
 129          * @pre ScriptCompanyMode::IsDeity.
 130          * @pre IsValidLeagueTableElement(element).
 131          */
 132         static bool RemoveElement(LeagueTableElementID element);
 133 };
 134
 135
 136 #endif /* SCRIPT_LEAGUE_HPP */