src/script/api/script_story_page.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_story_page.hpp Everything to manipulate a story page. */
   9
  10 #ifndef SCRIPT_STORY_HPP
  11 #define SCRIPT_STORY_HPP
  12
  13 #include "script_company.hpp"
  14 #include "script_date.hpp"
  15 #include "script_vehicle.hpp"
  16 #include "../../story_type.h"
  17 #include "../../story_base.h"
  18
  19 /**
  20  * Class that handles story page related functions.
  21  *
  22  * To create a page:
  23  * 1. Create the page
  24  * 2. Create page elements that will be appended to the page in the order which they are created.
  25  *
  26  * Pages can be either global or company specific. It is possible to mix, but the only mixed solution
  27  * that will work is to have all global pages first. Once you create the first company specific page,
  28  * it is not recommended to add additional global pages unless you clear up all pages first.
  29  *
  30  * Page elements are stacked vertically on a page. If goal elements are used, the element will
  31  * become empty if the goal is removed while the page still exist. Instead of removing the goal,
  32  * you can mark it as complete and the Story Book will show that the goal is completed.
  33  *
  34  * Mind that users might want to go back to old pages later on. Thus do not remove pages in
  35  * the story book unless you really need to.
  36  *
  37  * @api game
  38  */
  39 class ScriptStoryPage : public ScriptObject {
  40 public:
  41         /**
  42          * The story page IDs.
  43          */
  44         enum StoryPageID {
  45                 /* Note: these values represent part of the in-game StoryPageID enum */
  46                 STORY_PAGE_INVALID = ::INVALID_STORY_PAGE, ///< An invalid story page id.
  47         };
  48
  49         /**
  50          * The story page element IDs.
  51          */
  52         enum StoryPageElementID {
  53                 /* Note: these values represent part of the in-game StoryPageElementID enum */
  54                 STORY_PAGE_ELEMENT_INVALID = ::INVALID_STORY_PAGE_ELEMENT, ///< An invalid story page element id.
  55         };
  56
  57         /**
  58          * Story page element types.
  59          */
  60         enum StoryPageElementType : uint8_t {
  61                 SPET_TEXT = ::SPET_TEXT,                     ///< An element that displays a block of text.
  62                 SPET_LOCATION = ::SPET_LOCATION,             ///< An element that displays a single line of text along with a button to view the referenced location.
  63                 SPET_GOAL = ::SPET_GOAL,                     ///< An element that displays a goal.
  64                 SPET_BUTTON_PUSH = ::SPET_BUTTON_PUSH,       ///< A push button that triggers an immediate event.
  65                 SPET_BUTTON_TILE = ::SPET_BUTTON_TILE,       ///< A button that allows the player to select a tile, and triggers an event with the tile.
  66                 SPET_BUTTON_VEHICLE = ::SPET_BUTTON_VEHICLE, ///< A button that allows the player to select a vehicle, and triggers an event wih the vehicle.
  67         };
  68
  69         /**
  70          * Formatting data for button page elements.
  71          */
  72         typedef uint32_t StoryPageButtonFormatting;
  73
  74         /**
  75          * Formatting and layout flags for story page buttons.
  76          * The SPBF_FLOAT_LEFT and SPBF_FLOAT_RIGHT flags can not be combined.
  77          */
  78         enum StoryPageButtonFlags : uint8_t {
  79                 SPBF_NONE        = ::SPBF_NONE,        ///< No special formatting for button.
  80                 SPBF_FLOAT_LEFT  = ::SPBF_FLOAT_LEFT,  ///< Button is placed to the left of the following paragraph.
  81                 SPBF_FLOAT_RIGHT = ::SPBF_FLOAT_RIGHT, ///< Button is placed to the right of the following paragraph.
  82         };
  83
  84         /**
  85          * Mouse cursors usable by story page buttons.
  86          */
  87         enum StoryPageButtonCursor : uint8_t {
  88                 SPBC_MOUSE          = ::SPBC_MOUSE,
  89                 SPBC_ZZZ            = ::SPBC_ZZZ,
  90                 SPBC_BUOY           = ::SPBC_BUOY,
  91                 SPBC_QUERY          = ::SPBC_QUERY,
  92                 SPBC_HQ             = ::SPBC_HQ,
  93                 SPBC_SHIP_DEPOT     = ::SPBC_SHIP_DEPOT,
  94                 SPBC_SIGN           = ::SPBC_SIGN,
  95                 SPBC_TREE           = ::SPBC_TREE,
  96                 SPBC_BUY_LAND       = ::SPBC_BUY_LAND,
  97                 SPBC_LEVEL_LAND     = ::SPBC_LEVEL_LAND,
  98                 SPBC_TOWN           = ::SPBC_TOWN,
  99                 SPBC_INDUSTRY       = ::SPBC_INDUSTRY,
 100                 SPBC_ROCKY_AREA     = ::SPBC_ROCKY_AREA,
 101                 SPBC_DESERT         = ::SPBC_DESERT,
 102                 SPBC_TRANSMITTER    = ::SPBC_TRANSMITTER,
 103                 SPBC_AIRPORT        = ::SPBC_AIRPORT,
 104                 SPBC_DOCK           = ::SPBC_DOCK,
 105                 SPBC_CANAL          = ::SPBC_CANAL,
 106                 SPBC_LOCK           = ::SPBC_LOCK,
 107                 SPBC_RIVER          = ::SPBC_RIVER,
 108                 SPBC_AQUEDUCT       = ::SPBC_AQUEDUCT,
 109                 SPBC_BRIDGE         = ::SPBC_BRIDGE,
 110                 SPBC_RAIL_STATION   = ::SPBC_RAIL_STATION,
 111                 SPBC_TUNNEL_RAIL    = ::SPBC_TUNNEL_RAIL,
 112                 SPBC_TUNNEL_ELRAIL  = ::SPBC_TUNNEL_ELRAIL,
 113                 SPBC_TUNNEL_MONO    = ::SPBC_TUNNEL_MONO,
 114                 SPBC_TUNNEL_MAGLEV  = ::SPBC_TUNNEL_MAGLEV,
 115                 SPBC_AUTORAIL       = ::SPBC_AUTORAIL,
 116                 SPBC_AUTOELRAIL     = ::SPBC_AUTOELRAIL,
 117                 SPBC_AUTOMONO       = ::SPBC_AUTOMONO,
 118                 SPBC_AUTOMAGLEV     = ::SPBC_AUTOMAGLEV,
 119                 SPBC_WAYPOINT       = ::SPBC_WAYPOINT,
 120                 SPBC_RAIL_DEPOT     = ::SPBC_RAIL_DEPOT,
 121                 SPBC_ELRAIL_DEPOT   = ::SPBC_ELRAIL_DEPOT,
 122                 SPBC_MONO_DEPOT     = ::SPBC_MONO_DEPOT,
 123                 SPBC_MAGLEV_DEPOT   = ::SPBC_MAGLEV_DEPOT,
 124                 SPBC_CONVERT_RAIL   = ::SPBC_CONVERT_RAIL,
 125                 SPBC_CONVERT_ELRAIL = ::SPBC_CONVERT_ELRAIL,
 126                 SPBC_CONVERT_MONO   = ::SPBC_CONVERT_MONO,
 127                 SPBC_CONVERT_MAGLEV = ::SPBC_CONVERT_MAGLEV,
 128                 SPBC_AUTOROAD       = ::SPBC_AUTOROAD,
 129                 SPBC_AUTOTRAM       = ::SPBC_AUTOTRAM,
 130                 SPBC_ROAD_DEPOT     = ::SPBC_ROAD_DEPOT,
 131                 SPBC_BUS_STATION    = ::SPBC_BUS_STATION,
 132                 SPBC_TRUCK_STATION  = ::SPBC_TRUCK_STATION,
 133                 SPBC_ROAD_TUNNEL    = ::SPBC_ROAD_TUNNEL,
 134                 SPBC_CLONE_TRAIN    = ::SPBC_CLONE_TRAIN,
 135                 SPBC_CLONE_ROADVEH  = ::SPBC_CLONE_ROADVEH,
 136                 SPBC_CLONE_SHIP     = ::SPBC_CLONE_SHIP,
 137                 SPBC_CLONE_AIRPLANE = ::SPBC_CLONE_AIRPLANE,
 138                 SPBC_DEMOLISH       = ::SPBC_DEMOLISH,
 139                 SPBC_LOWERLAND      = ::SPBC_LOWERLAND,
 140                 SPBC_RAISELAND      = ::SPBC_RAISELAND,
 141                 SPBC_PICKSTATION    = ::SPBC_PICKSTATION,
 142                 SPBC_BUILDSIGNALS   = ::SPBC_BUILDSIGNALS,
 143         };
 144
 145         /**
 146          * Colour codes usable for story page button elements.
 147          * Place a colour value in the lowest 8 bits of the \c reference parameter to the button.
 148          */
 149         enum StoryPageButtonColour : uint8_t {
 150                 SPBC_DARK_BLUE  = ::COLOUR_DARK_BLUE,
 151                 SPBC_PALE_GREEN = ::COLOUR_PALE_GREEN,
 152                 SPBC_PINK       = ::COLOUR_PINK,
 153                 SPBC_YELLOW     = ::COLOUR_YELLOW,
 154                 SPBC_RED        = ::COLOUR_RED,
 155                 SPBC_LIGHT_BLUE = ::COLOUR_LIGHT_BLUE,
 156                 SPBC_GREEN      = ::COLOUR_GREEN,
 157                 SPBC_DARK_GREEN = ::COLOUR_DARK_GREEN,
 158                 SPBC_BLUE       = ::COLOUR_BLUE,
 159                 SPBC_CREAM      = ::COLOUR_CREAM,
 160                 SPBC_MAUVE      = ::COLOUR_MAUVE,
 161                 SPBC_PURPLE     = ::COLOUR_PURPLE,
 162                 SPBC_ORANGE     = ::COLOUR_ORANGE,
 163                 SPBC_BROWN      = ::COLOUR_BROWN,
 164                 SPBC_GREY       = ::COLOUR_GREY,
 165                 SPBC_WHITE      = ::COLOUR_WHITE,
 166         };
 167
 168         /**
 169          * Check whether this is a valid story page ID.
 170          * @param story_page_id The StoryPageID to check.
 171          * @return True if and only if this story page is valid.
 172          */
 173         static bool IsValidStoryPage(StoryPageID story_page_id);
 174
 175         /**
 176          * Check whether this is a valid story page element ID.
 177          * @param story_page_element_id The StoryPageElementID to check.
 178          * @return True if and only if this story page element is valid.
 179          */
 180         static bool IsValidStoryPageElement(StoryPageElementID story_page_element_id);
 181
 182         /**
 183          * Check whether this is a valid story page element type.
 184          * @param type The StoryPageElementType to check.
 185          * @return True if and only if this story page element type is valid.
 186          */
 187         static bool IsValidStoryPageElementType(StoryPageElementType type);
 188
 189         /**
 190          * Create a new story page.
 191          * @param company The company to create the story page for, or ScriptCompany::COMPANY_INVALID for all.
 192          * @param title Page title (can be either a raw string, a ScriptText object, or null).
 193          * @return The new StoryPageID, or STORY_PAGE_INVALID if it failed.
 194          * @pre ScriptCompanyMode::IsDeity().
 195          * @pre company == COMPANY_INVALID || ResolveCompanyID(company) != COMPANY_INVALID.
 196          */
 197         static StoryPageID New(ScriptCompany::CompanyID company, Text *title);
 198
 199         /**
 200          * Create a new story page element.
 201          * @param story_page_id The page id of the story page which the page element should be appended to.
 202          * @param type Which page element type to create.
 203          * @param reference A reference value to the object that is referred to by some page element types.
 204          *                  When type is SPET_GOAL, this is the goal ID.
 205          *                  When type is SPET_LOCATION, this is the TileIndex.
 206          *                  When type is a button, this is the ID returned by
 207          *                  #MakePushButtonReference, #MakeTileButtonReference, or #MakeVehicleButtonReference.
 208          * @param text The body text of page elements that allow custom text. (SPET_TEXT and SPET_LOCATION)
 209          * @return The new StoryPageElementID, or STORY_PAGE_ELEMENT_INVALID if it failed.
 210          * @pre ScriptCompanyMode::IsDeity().
 211          * @pre IsValidStoryPage(story_page).
 212          * @pre IsValidStoryPageElementType(type).
 213          * @pre (type != SPET_TEXT && type != SPET_LOCATION) || (text != null && len(text) != 0).
 214          * @pre type != SPET_LOCATION || ScriptMap::IsValidTile(reference).
 215          * @pre type != SPET_GOAL || ScriptGoal::IsValidGoal(reference).
 216          * @pre if type is SPET_GOAL and story_page is a global page, then referenced goal must be global.
 217          */
 218         static StoryPageElementID NewElement(StoryPageID story_page_id, StoryPageElementType type, SQInteger reference, Text *text);
 219
 220         /**
 221          * Update the content of a page element
 222          * @param story_page_element_id The page id of the story page which the page element should be appended to.
 223          * @param reference A reference value to the object that is referred to by some page element types. See also NewElement.
 224          * @param text The body text of page elements that allow custom text. See also NewElement.
 225          * @return True if the action succeeded.
 226          * @pre ScriptCompanyMode::IsDeity().
 227          * @pre IsValidStoryPage(story_page).
 228          * @pre (type != SPET_TEXT && type != SPET_LOCATION) || (text != null && len(text) != 0).
 229          * @pre type != SPET_LOCATION || ScriptMap::IsValidTile(reference).
 230          * @pre type != SPET_GOAL || ScriptGoal::IsValidGoal(reference).
 231          * @pre if type is SPET_GOAL and story_page is a global page, then referenced goal must be global.
 232          */
 233         static bool UpdateElement(StoryPageElementID story_page_element_id, SQInteger reference, Text *text);
 234
 235         /**
 236          * Get story page sort value. Each page has a sort value that is internally assigned and used
 237          * to sort the pages in the story book. OpenTTD maintains this number so that the sort order
 238          * is perceived. This API exist only so that you can sort ScriptStoryPageList the same order
 239          * as in GUI. You should not use this number for anything else.
 240          * @param story_page_id The story page to get the sort value of.
 241          * @return Page sort value.
 242          */
 243         static SQInteger GetPageSortValue(StoryPageID story_page_id);
 244
 245         /**
 246          * Get story page element sort value. Each page element has a sort value that is internally
 247          * assigned and used to sort the page elements within a page of the story book. OpenTTD
 248          * maintains this number so that the sort order is perceived. This API exist only so that
 249          * you can sort ScriptStoryPageList the same order as in GUI. You should not use this number
 250          * for anything else.
 251          * @param story_page_element_id The story page element to get the sort value of.
 252          * @return Page element sort value.
 253          */
 254         static SQInteger GetPageElementSortValue(StoryPageElementID story_page_element_id);
 255
 256         /**
 257          * Get the company which the page belongs to. If the page is global,
 258          * ScriptCompany::COMPANY_INVALID is returned.
 259          * @param story_page_id The story page to get the company for.
 260          * @return owner company or ScriptCompany::COMPANY_INVALID
 261          * @pre IsValidStoryPage(story_page_id).
 262          */
 263         static ScriptCompany::CompanyID GetCompany(StoryPageID story_page_id);
 264
 265         /**
 266          * Get the page date which is displayed at the top of each page.
 267          * @param story_page_id The story page to get the date of.
 268          * @return The calendar-date
 269          * @pre IsValidStoryPage(story_page_id).
 270          * @see \ref ScriptCalendarTime
 271          */
 272         static ScriptDate::Date GetDate(StoryPageID story_page_id);
 273
 274         /**
 275          * Update date of a story page. The date is shown in the top left of the page
 276          * @param story_page_id The story page to set the date for.
 277          * @param date Calendar-date to display at the top of story page or ScriptDate::DATE_INVALID to disable showing date on this page. (also, @see ScriptDate)
 278          * @return True if the action succeeded.
 279          * @pre ScriptCompanyMode::IsDeity().
 280          * @pre IsValidStoryPage(story_page_id).
 281          * @see \ref ScriptCalendarTime
 282          */
 283         static bool SetDate(StoryPageID story_page_id, ScriptDate::Date date);
 284
 285         /**
 286          * Update title of a story page. The title is shown in the page selector drop down.
 287          * @param story_page_id The story page to update.
 288          * @param title Page title (can be either a raw string, a ScriptText object, or null).
 289          * @return True if the action succeeded.
 290          * @pre ScriptCompanyMode::IsDeity().
 291          * @pre IsValidStoryPage(story_page_id).
 292          */
 293         static bool SetTitle(StoryPageID story_page_id, Text *title);
 294
 295         /**
 296          * Opens the Story Book if not yet open and selects the given page.
 297          * @param story_page_id The story page to update. If it is a global page, clients of all
 298          * companies are affecetd. Otherwise only the clients of the company which the page belongs
 299          * to are affected.
 300          * @return True if the action succeeded.
 301          * @pre ScriptCompanyMode::IsDeity().
 302          * @pre IsValidStoryPage(story_page_id).
 303          */
 304         static bool Show(StoryPageID story_page_id);
 305
 306         /**
 307          * Remove a story page and all the page elements
 308          * associated with it.
 309          * @param story_page_id The story page to remove.
 310          * @return True if the action succeeded.
 311          * @pre ScriptCompanyMode::IsDeity().
 312          * @pre IsValidStoryPage(story_page_id).
 313          */
 314         static bool Remove(StoryPageID story_page_id);
 315
 316         /**
 317          * Removes a story page element.
 318          * @param story_page_element_id The story page element to remove.
 319          * @return True if the action succeeded.
 320          * @pre ScriptCompanyMode::IsDeity().
 321          * @pre IsValidStoryPageElement(story_page_element_id).
 322          */
 323         static bool RemoveElement(StoryPageElementID story_page_element_id);
 324
 325         /**
 326          * Check whether this is a valid story page button colour.
 327          * @param colour The StoryPageButtonColour to check.
 328          * @return True if and only if this story page button colour is valid.
 329          */
 330         static bool IsValidStoryPageButtonColour(StoryPageButtonColour colour);
 331
 332         /**
 333         * Check whether this is a valid story page button flag.
 334         * @param flags The StoryPageButtonFlags to check.
 335         * @return True if and only if this story page button flag is valid.
 336         */
 337         static bool IsValidStoryPageButtonFlags(StoryPageButtonFlags flags);
 338
 339         /**
 340          * Check whether this is a valid story page button cursor.
 341          * @param cursor The StoryPageButtonCursor to check.
 342          * @return True if and only if this story page button cursor is valid.
 343          */
 344         static bool IsValidStoryPageButtonCursor(StoryPageButtonCursor cursor);
 345
 346         /**
 347          * Create a reference value for SPET_BUTTON_PUSH element parameters.
 348          * @param colour The colour for the face of the button.
 349          * @param flags The formatting and layout flags for the button.
 350          * @return A reference value usable with the #NewElement and #UpdateElement functions.
 351          * @pre IsValidStoryPageButtonColour(colour).
 352          * @pre IsValidStoryPageButtonFlags(flags).
 353          */
 354         static StoryPageButtonFormatting MakePushButtonReference(StoryPageButtonColour colour, StoryPageButtonFlags flags);
 355
 356         /**
 357          * Create a reference value for SPET_BUTTON_TILE element parameters.
 358          * @param colour The colour for the face of the button.
 359          * @param flags The formatting and layout flags for the button.
 360          * @param cursor The mouse cursor to use when the player clicks the button and the game is ready for the player to select a tile.
 361          * @return A reference value usable with the #NewElement and #UpdateElement functions.
 362          * @pre IsValidStoryPageButtonColour(colour).
 363          * @pre IsValidStoryPageButtonFlags(flags).
 364          * @pre IsValidStoryPageButtonCursor(cursor).
 365          */
 366         static StoryPageButtonFormatting MakeTileButtonReference(StoryPageButtonColour colour, StoryPageButtonFlags flags, StoryPageButtonCursor cursor);
 367
 368         /**
 369          * Create a reference value for SPET_BUTTON_VEHICLE element parameters.
 370          * @param colour  The colour for the face of the button.
 371          * @param flags The formatting and layout flags for the button.
 372          * @param cursor  The mouse cursor to use when the player clicks the button and the game is ready for the player to select a vehicle.
 373          * @param vehtype The type of vehicle that will be selectable, or \c VT_INVALID to allow all types.
 374          * @return A reference value usable with the #NewElement and #UpdateElement functions.
 375          * @pre IsValidStoryPageButtonColour(colour).
 376          * @pre IsValidStoryPageButtonFlags(flags).
 377          * @pre IsValidStoryPageButtonCursor(cursor).
 378          * @pre vehtype == ScriptVehicle::VT_INVALID || vehtype == ScriptVehicle::VT_RAIL || vehtype == ScriptVehicle::VT_ROAD || vehtype == ScriptVehicle::VT_WATER || vehtype == ScriptVehicle::VT_AIR.
 379          */
 380         static StoryPageButtonFormatting MakeVehicleButtonReference(StoryPageButtonColour colour, StoryPageButtonFlags flags, StoryPageButtonCursor cursor, ScriptVehicle::VehicleType vehtype);
 381 };
 382
 383 #endif /* SCRIPT_STORY_HPP */
 384