path: root/src/script/api/script_story_page.hpp

/*
 * This file is part of OpenTTD.
 * 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.
 * 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.
 * 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/>.
 */

/** @file script_story_page.hpp Everything to manipulate a story page. */

#ifndef SCRIPT_STORY_HPP
#define SCRIPT_STORY_HPP

#include "script_company.hpp"
#include "script_date.hpp"
#include "script_vehicle.hpp"
#include "../../story_type.h"
#include "../../story_base.h"

/**
 * Class that handles story page related functions.
 *
 * To create a page:
 * 1. Create the page
 * 2. Create page elements that will be appended to the page in the order which they are created.
 *
 * Pages can be either global or company specific. It is possible to mix, but the only mixed solution
 * that will work is to have all global pages first. Once you create the first company specific page,
 * it is not recommended to add additional global pages unless you clear up all pages first.
 *
 * Page elements are stacked vertically on a page. If goal elements are used, the element will
 * become empty if the goal is removed while the page still exist. Instead of removing the goal,
 * you can mark it as complete and the Story Book will show that the goal is completed.
 *
 * Mind that users might want to go back to old pages later on. Thus do not remove pages in
 * the story book unless you really need to.
 *
 * @api game
 */
class ScriptStoryPage : public ScriptObject {
public:
	/**
	 * The story page IDs.
	 */
	enum StoryPageID {
		/* Note: these values represent part of the in-game StoryPageID enum */
		STORY_PAGE_INVALID = ::INVALID_STORY_PAGE, ///< An invalid story page id.
	};

	/**
	 * The story page element IDs.
	 */
	enum StoryPageElementID {
		/* Note: these values represent part of the in-game StoryPageElementID enum */
		STORY_PAGE_ELEMENT_INVALID = ::INVALID_STORY_PAGE_ELEMENT, ///< An invalid story page element id.
	};

	/**
	 * Story page element types.
	 */
	enum StoryPageElementType : byte {
		SPET_TEXT = ::SPET_TEXT,                     ///< An element that displays a block of text.
		SPET_LOCATION = ::SPET_LOCATION,             ///< An element that displays a single line of text along with a button to view the referenced location.
		SPET_GOAL = ::SPET_GOAL,                     ///< An element that displays a goal.
		SPET_BUTTON_PUSH = ::SPET_BUTTON_PUSH,       ///< A push button that triggers an immediate event.
		SPET_BUTTON_TILE = ::SPET_BUTTON_TILE,       ///< A button that allows the player to select a tile, and triggers an event with the tile.
		SPET_BUTTON_VEHICLE = ::SPET_BUTTON_VEHICLE, ///< A button that allows the player to select a vehicle, and triggers an event wih the vehicle.
	};

	/**
	 * Formatting data for button page elements.
	 */
	typedef uint32 StoryPageButtonFormatting;

	/**
	 * Formatting and layout flags for story page buttons.
	 * The SPBF_FLOAT_LEFT and SPBF_FLOAT_RIGHT flags can not be combined.
	 */
	enum StoryPageButtonFlags : byte {
		SPBF_NONE        = ::SPBF_NONE,        ///< No special formatting for button.
		SPBF_FLOAT_LEFT  = ::SPBF_FLOAT_LEFT,  ///< Button is placed to the left of the following paragraph.
		SPBF_FLOAT_RIGHT = ::SPBF_FLOAT_RIGHT, ///< Button is placed to the right of the following paragraph.
	};

	/**
	 * Mouse cursors usable by story page buttons.
	 */
	enum StoryPageButtonCursor : byte {
		SPBC_MOUSE          = ::SPBC_MOUSE,
		SPBC_ZZZ            = ::SPBC_ZZZ,
		SPBC_BUOY           = ::SPBC_BUOY,
		SPBC_QUERY          = ::SPBC_QUERY,
		SPBC_HQ             = ::SPBC_HQ,
		SPBC_SHIP_DEPOT     = ::SPBC_SHIP_DEPOT,
		SPBC_SIGN           = ::SPBC_SIGN,
		SPBC_TREE           = ::SPBC_TREE,
		SPBC_BUY_LAND       = ::SPBC_BUY_LAND,
		SPBC_LEVEL_LAND     = ::SPBC_LEVEL_LAND,
		SPBC_TOWN           = ::SPBC_TOWN,
		SPBC_INDUSTRY       = ::SPBC_INDUSTRY,
		SPBC_ROCKY_AREA     = ::SPBC_ROCKY_AREA,
		SPBC_DESERT         = ::SPBC_DESERT,
		SPBC_TRANSMITTER    = ::SPBC_TRANSMITTER,
		SPBC_AIRPORT        = ::SPBC_AIRPORT,
		SPBC_DOCK           = ::SPBC_DOCK,
		SPBC_CANAL          = ::SPBC_CANAL,
		SPBC_LOCK           = ::SPBC_LOCK,
		SPBC_RIVER          = ::SPBC_RIVER,
		SPBC_AQUEDUCT       = ::SPBC_AQUEDUCT,
		SPBC_BRIDGE         = ::SPBC_BRIDGE,
		SPBC_RAIL_STATION   = ::SPBC_RAIL_STATION,
		SPBC_TUNNEL_RAIL    = ::SPBC_TUNNEL_RAIL,
		SPBC_TUNNEL_ELRAIL  = ::SPBC_TUNNEL_ELRAIL,
		SPBC_TUNNEL_MONO    = ::SPBC_TUNNEL_MONO,
		SPBC_TUNNEL_MAGLEV  = ::SPBC_TUNNEL_MAGLEV,
		SPBC_AUTORAIL       = ::SPBC_AUTORAIL,
		SPBC_AUTOELRAIL     = ::SPBC_AUTOELRAIL,
		SPBC_AUTOMONO       = ::SPBC_AUTOMONO,
		SPBC_AUTOMAGLEV     = ::SPBC_AUTOMAGLEV,
		SPBC_WAYPOINT       = ::SPBC_WAYPOINT,
		SPBC_RAIL_DEPOT     = ::SPBC_RAIL_DEPOT,
		SPBC_ELRAIL_DEPOT   = ::SPBC_ELRAIL_DEPOT,
		SPBC_MONO_DEPOT     = ::SPBC_MONO_DEPOT,
		SPBC_MAGLEV_DEPOT   = ::SPBC_MAGLEV_DEPOT,
		SPBC_CONVERT_RAIL   = ::SPBC_CONVERT_RAIL,
		SPBC_CONVERT_ELRAIL = ::SPBC_CONVERT_ELRAIL,
		SPBC_CONVERT_MONO   = ::SPBC_CONVERT_MONO,
		SPBC_CONVERT_MAGLEV = ::SPBC_CONVERT_MAGLEV,
		SPBC_AUTOROAD       = ::SPBC_AUTOROAD,
		SPBC_AUTOTRAM       = ::SPBC_AUTOTRAM,
		SPBC_ROAD_DEPOT     = ::SPBC_ROAD_DEPOT,
		SPBC_BUS_STATION    = ::SPBC_BUS_STATION,
		SPBC_TRUCK_STATION  = ::SPBC_TRUCK_STATION,
		SPBC_ROAD_TUNNEL    = ::SPBC_ROAD_TUNNEL,
		SPBC_CLONE_TRAIN    = ::SPBC_CLONE_TRAIN,
		SPBC_CLONE_ROADVEH  = ::SPBC_CLONE_ROADVEH,
		SPBC_CLONE_SHIP     = ::SPBC_CLONE_SHIP,
		SPBC_CLONE_AIRPLANE = ::SPBC_CLONE_AIRPLANE,
		SPBC_DEMOLISH       = ::SPBC_DEMOLISH,
		SPBC_LOWERLAND      = ::SPBC_LOWERLAND,
		SPBC_RAISELAND      = ::SPBC_RAISELAND,
		SPBC_PICKSTATION    = ::SPBC_PICKSTATION,
		SPBC_BUILDSIGNALS   = ::SPBC_BUILDSIGNALS,
	};

	/**
	 * Colour codes usable for story page button elements.
	 * Place a colour value in the lowest 8 bits of the \c reference parameter to the button.
	 */
	enum StoryPageButtonColour {
		SPBC_DARK_BLUE  = ::COLOUR_DARK_BLUE,
		SPBC_PALE_GREEN = ::COLOUR_PALE_GREEN,
		SPBC_PINK       = ::COLOUR_PINK,
		SPBC_YELLOW     = ::COLOUR_YELLOW,
		SPBC_RED        = ::COLOUR_RED,
		SPBC_LIGHT_BLUE = ::COLOUR_LIGHT_BLUE,
		SPBC_GREEN      = ::COLOUR_GREEN,
		SPBC_DARK_GREEN = ::COLOUR_DARK_GREEN,
		SPBC_BLUE       = ::COLOUR_BLUE,
		SPBC_CREAM      = ::COLOUR_CREAM,
		SPBC_MAUVE      = ::COLOUR_MAUVE,
		SPBC_PURPLE     = ::COLOUR_PURPLE,
		SPBC_ORANGE     = ::COLOUR_ORANGE,
		SPBC_BROWN      = ::COLOUR_BROWN,
		SPBC_GREY       = ::COLOUR_GREY,
		SPBC_WHITE      = ::COLOUR_WHITE,
	};

	/**
	 * Check whether this is a valid story page ID.
	 * @param story_page_id The StoryPageID to check.
	 * @return True if and only if this story page is valid.
	 */
	static bool IsValidStoryPage(StoryPageID story_page_id);

	/**
	 * Check whether this is a valid story page element ID.
	 * @param story_page_element_id The StoryPageElementID to check.
	 * @return True if and only if this story page element is valid.
	 */
	static bool IsValidStoryPageElement(StoryPageElementID story_page_element_id);

	/**
	 * Create a new story page.
	 * @param company The company to create the story page for, or ScriptCompany::COMPANY_INVALID for all.
	 * @param title Page title (can be either a raw string, a ScriptText object, or null).
	 * @return The new StoryPageID, or STORY_PAGE_INVALID if it failed.
	 * @pre No ScriptCompanyMode may be in scope.
	 * @pre company == COMPANY_INVALID || ResolveCompanyID(company) != COMPANY_INVALID.
	 */
	static StoryPageID New(ScriptCompany::CompanyID company, Text *title);

	/**
	 * Create a new story page element.
	 * @param story_page_id The page id of the story page which the page element should be appended to.
	 * @param type Which page element type to create.
	 * @param reference A reference value to the object that is referred to by some page element types.
	 *                  When type is SPET_GOAL, this is the goal ID.
	 *                  When type is SPET_LOCATION, this is the TileIndex.
	 *                  When type is a button, this is additional parameters for the button,
	 *                  use the #BuildPushButtonReference, #BuildTileButtonReference, or #BuildVehicleButtonReference functions to make the values.
	 * @param text The body text of page elements that allow custom text. (SPET_TEXT and SPET_LOCATION)
	 * @return The new StoryPageElementID, or STORY_PAGE_ELEMENT_INVALID if it failed.
	 * @pre No ScriptCompanyMode may be in scope.
	 * @pre IsValidStoryPage(story_page).
	 * @pre (type != SPET_TEXT && type != SPET_LOCATION) || (text != nullptr && len(text) != 0).
	 * @pre type != SPET_LOCATION || ScriptMap::IsValidTile(reference).
	 * @pre type != SPET_GOAL || ScriptGoal::IsValidGoal(reference).
	 * @pre if type is SPET_GOAL and story_page is a global page, then referenced goal must be global.
	 */
	static StoryPageElementID NewElement(StoryPageID story_page_id, StoryPageElementType type, uint32 reference, Text *text);

	/**
	 * Update the content of a page element
	 * @param story_page_element_id The page id of the story page which the page element should be appended to.
	 * @param reference A reference value to the object that is referred to by some page element types. See also NewElement.
	 * @param text The body text of page elements that allow custom text. See also NewElement.
	 * @return True if the action succeeded.
	 * @pre No ScriptCompanyMode may be in scope.
	 * @pre IsValidStoryPage(story_page).
	 * @pre (type != SPET_TEXT && type != SPET_LOCATION) || (text != nullptr && len(text) != 0).
	 * @pre type != SPET_LOCATION || ScriptMap::IsValidTile(reference).
	 * @pre type != SPET_GOAL || ScriptGoal::IsValidGoal(reference).
	 * @pre if type is SPET_GOAL and story_page is a global page, then referenced goal must be global.
	 */
	static bool UpdateElement(StoryPageElementID story_page_element_id, uint32 reference, Text *text);

	/**
	 * Get story page sort value. Each page has a sort value that is internally assigned and used
	 * to sort the pages in the story book. OpenTTD maintains this number so that the sort order
	 * is perceived. This API exist only so that you can sort ScriptStoryPageList the same order
	 * as in GUI. You should not use this number for anything else.
	 * @param story_page_id The story page to get the sort value of.
	 * @return Page sort value.
	 */
	static uint32 GetPageSortValue(StoryPageID story_page_id);

	/**
	 * Get story page element sort value. Each page element has a sort value that is internally
	 * assigned and used to sort the page elements within a page of the story book. OpenTTD
	 * maintains this number so that the sort order is perceived. This API exist only so that
	 * you can sort ScriptStoryPageList the same order as in GUI. You should not use this number
	 * for anything else.
	 * @param story_page_element_id The story page element to get the sort value of.
	 * @return Page element sort value.
	 */
	static uint32 GetPageElementSortValue(StoryPageElementID story_page_element_id);

	/**
	 * Get the company which the page belongs to. If the page is global,
	 * ScriptCompany::COMPANY_INVALID is returned.
	 * @param story_page_id The story page to get the company for.
	 * @return owner company or ScriptCompany::COMPANY_INVALID
	 * @pre IsValidStoryPage(story_page_id).
	 */
	static ScriptCompany::CompanyID GetCompany(StoryPageID story_page_id);

	/**
	 * Get the page date which is displayed at the top of each page.
	 * @param story_page_id The story page to get the date of.
	 * @return The date
	 * @pre IsValidStoryPage(story_page_id).
	 */
	static ScriptDate::Date GetDate(StoryPageID story_page_id);

	/**
	 * Update date of a story page. The date is shown in the top left of the page
	 * @param story_page_id The story page to set the date for.
	 * @param date Date to display at the top of story page or ScriptDate::DATE_INVALID to disable showing date on this page. (also, @see ScriptDate)
	 * @return True if the action succeeded.
	 * @pre No ScriptCompanyMode may be in scope.
	 * @pre IsValidStoryPage(story_page_id).
	 */
	static bool SetDate(StoryPageID story_page_id, ScriptDate::Date date);

	/**
	 * Update title of a story page. The title is shown in the page selector drop down.
	 * @param story_page_id The story page to update.
	 * @param title Page title (can be either a raw string, a ScriptText object, or null).
	 * @return True if the action succeeded.
	 * @pre No ScriptCompanyMode may be in scope.
	 * @pre IsValidStoryPage(story_page_id).
	 */
	static bool SetTitle(StoryPageID story_page_id, Text *title);

	/**
	 * Opens the Story Book if not yet open and selects the given page.
	 * @param story_page_id The story page to update. If it is a global page, clients of all
	 * companies are affecetd. Otherwise only the clients of the company which the page belongs
	 * to are affected.
	 * @return True if the action succeeded.
	 * @pre No ScriptCompanyMode may be in scope.
	 * @pre IsValidStoryPage(story_page_id).
	 */
	static bool Show(StoryPageID story_page_id);

	/**
	 * Remove a story page and all the page elements
	 * associated with it.
	 * @param story_page_id The story page to remove.
	 * @return True if the action succeeded.
	 * @pre No ScriptCompanyMode may be in scope.
	 * @pre IsValidStoryPage(story_page_id).
	 */
	static bool Remove(StoryPageID story_page_id);

	/**
	 * Removes a story page element.
	 * @param story_page_element_id The story page element to remove.
	 * @return True if the action succeeded.
	 * @pre No ScriptCompanyMode may be in scope.
	 * @pre IsValidStoryPageElement(story_page_element_id).
	 */
	static bool RemoveElement(StoryPageElementID story_page_element_id);

	/**
	 * Create a reference value for SPET_BUTTON_PUSH element parameters.
	 * @param colour The colour for the face of the button.
	 * @return A reference value usable with the #NewElement and #UpdateElement functions.
	 */
	static StoryPageButtonFormatting MakePushButtonReference(StoryPageButtonColour colour, StoryPageButtonFlags flags);

	/**
	 * Create a reference value for SPET_BUTTON_TILE element parameters.
	 * @param colour The colour for the face of the button.
	 * @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.
	 * @return A reference value usable with the #NewElement and #UpdateElement functions.
	 */
	static StoryPageButtonFormatting MakeTileButtonReference(StoryPageButtonColour colour, StoryPageButtonFlags flags, StoryPageButtonCursor cursor);

	/**
	 * Create a reference value for SPET_BUTTON_VEHICLE element parameters.
	 * @param colour  The colour for the face of the button.
	 * @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.
	 * @param vehtype The type of vehicle that will be selectable, or \c VT_INVALID to allow all types.
	 * @return A reference value usable with the #NewElement and #UpdateElement functions.
	 */
	static StoryPageButtonFormatting MakeVehicleButtonReference(StoryPageButtonColour colour, StoryPageButtonFlags flags, StoryPageButtonCursor cursor, ScriptVehicle::VehicleType vehtype);
};

#endif /* SCRIPT_STORY_HPP */