src/script/api/script_story_page.hpp

   1 /* $Id: script_story_page.hpp 26307 2014-02-06 19:50:34Z zuu $ */
   2
   3 /*
   4  * This file is part of OpenTTD.
   5  * 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.
   6  * 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.
   7  * 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/>.
   8  */
   9
  10 /** @file script_story_page.hpp Everything to manipulate a story page. */
  11
  12 #ifndef SCRIPT_STORY_HPP
  13 #define SCRIPT_STORY_HPP
  14
  15 #include "script_company.hpp"
  16 #include "script_date.hpp"
  17 #include "../../story_type.h"
  18 #include "../../story_base.h"
  19
  20 /**
  21  * Class that handles story page related functions.
  22  *
  23  * To create a page:
  24  * 1. Create the page
  25  * 2. Create page elements that will be appended to the page in the order which they are created.
  26  *
  27  * Pages can be either global or company specific. It is possible to mix, but the only mixed solution
  28  * that will work is to have all global pages first. Once you create the first company specific page,
  29  * it is not recommended to add additional global pages unless you clear up all pages first.
  30  *
  31  * Page elements are stacked vertically on a page. If goal elements are used, the element will
  32  * become empty if the goal is removed while the page still exist. Instead of removing the goal,
  33  * you can mark it as complete and the Story Book will show that the goal is completed.
  34  *
  35  * Mind that users might want to go back to old pages later on. Thus do not remove pages in
  36  * the story book unless you really need to.
  37  *
  38  * @api game
  39  */
  40 class ScriptStoryPage : public ScriptObject {
  41 public:
  42         /**
  43          * The story page IDs.
  44          */
  45         enum StoryPageID {
  46                 /* Note: these values represent part of the in-game StoryPageID enum */
  47                 STORY_PAGE_INVALID = ::INVALID_STORY_PAGE, ///< An invalid story page id.
  48         };
  49
  50         /**
  51          * The story page element IDs.
  52          */
  53         enum StoryPageElementID {
  54                 /* Note: these values represent part of the in-game StoryPageElementID enum */
  55                 STORY_PAGE_ELEMENT_INVALID = ::INVALID_STORY_PAGE_ELEMENT, ///< An invalid story page element id.
  56         };
  57
  58         /**
  59          * Story page element types.
  60          */
  61         enum StoryPageElementType {
  62                 SPET_TEXT = ::SPET_TEXT,         ///< An element that displays a block of text.
  63                 SPET_LOCATION = ::SPET_LOCATION, ///< An element that displays a single line of text along with a button to view the referenced location.
  64                 SPET_GOAL = ::SPET_GOAL,         ///< An element that displays a goal.
  65         };
  66
  67         /**
  68          * Check whether this is a valid story page ID.
  69          * @param story_page_id The StoryPageID to check.
  70          * @return True if and only if this story page is valid.
  71          */
  72         static bool IsValidStoryPage(StoryPageID story_page_id);
  73
  74         /**
  75          * Check whether this is a valid story page element ID.
  76          * @param story_page_element_id The StoryPageElementID to check.
  77          * @return True if and only if this story page element is valid.
  78          */
  79         static bool IsValidStoryPageElement(StoryPageElementID story_page_element_id);
  80
  81         /**
  82          * Create a new story page.
  83          * @param company The company to create the story page for, or ScriptCompany::COMPANY_INVALID for all.
  84          * @param title Page title (can be either a raw string, a ScriptText object, or null).
  85          * @return The new StoryPageID, or STORY_PAGE_INVALID if it failed.
  86          * @pre No ScriptCompanyMode may be in scope.
  87          * @pre company == COMPANY_INVALID || ResolveCompanyID(company) != COMPANY_INVALID.
  88          */
  89         static StoryPageID New(ScriptCompany::CompanyID company, Text *title);
  90
  91         /**
  92          * Create a new story page element.
  93          * @param story_page_id The page id of the story page which the page element should be appended to.
  94          * @param type Which page element type to create.
  95          * @param reference A reference value to the object that is refered 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.
  96          * @param text The body text of page elements that allow custom text. (SPET_TEXT and SPET_LOCATION)
  97          * @return The new StoryPageElementID, or STORY_PAGE_ELEMENT_INVALID if it failed.
  98          * @pre No ScriptCompanyMode may be in scope.
  99          * @pre IsValidStoryPage(story_page).
 100          * @pre (type != SPET_TEXT && type != SPET_LOCATION) || (text != NULL && len(text) != 0).
 101          * @pre type != SPET_LOCATION || ScriptMap::IsValidTile(reference).
 102          * @pre type != SPET_GOAL || ScriptGoal::IsValidGoal(reference).
 103          * @pre if type is SPET_GOAL and story_page is a global page, then referenced goal must be global.
 104          */
 105         static StoryPageElementID NewElement(StoryPageID story_page_id, StoryPageElementType type, uint32 reference, Text *text);
 106
 107         /**
 108          * Update the content of a page element
 109          * @param story_page_element_id The page id of the story page which the page element should be appended to.
 110          * @param reference A reference value to the object that is refered to by some page element types. See also NewElement.
 111          * @param text The body text of page elements that allow custom text. See also NewElement.
 112          * @return True if the action succeeded.
 113          * @pre No ScriptCompanyMode may be in scope.
 114          * @pre IsValidStoryPage(story_page).
 115          * @pre (type != SPET_TEXT && type != SPET_LOCATION) || (text != NULL && len(text) != 0).
 116          * @pre type != SPET_LOCATION || ScriptMap::IsValidTile(reference).
 117          * @pre type != SPET_GOAL || ScriptGoal::IsValidGoal(reference).
 118          * @pre if type is SPET_GOAL and story_page is a global page, then referenced goal must be global.
 119          */
 120         static bool UpdateElement(StoryPageElementID story_page_element_id, uint32 reference, Text *text);
 121
 122         /**
 123          * Get story page sort value. Each page has a sort value that is internally assigned and used
 124          * to sort the pages in the story book. OpenTTD maintains this number so that the sort order
 125          * is perceived. This API exist only so that you can sort ScriptStoryPageList the same order
 126          * as in GUI. You should not use this number for anything else.
 127          * @param story_page_id The story page to get the sort value of.
 128          * @return Page sort value.
 129          */
 130         static uint32 GetPageSortValue(StoryPageID story_page_id);
 131
 132         /**
 133          * Get story page element sort value. Each page element has a sort value that is internally
 134          * assigned and used to sort the page elements within a page of the story book. OpenTTD
 135          * maintains this number so that the sort order is perceived. This API exist only so that
 136          * you can sort ScriptStoryPageList the same order as in GUI. You should not use this number
 137          * for anything else.
 138          * @param story_page_element_id The story page element to get the sort value of.
 139          * @return Page element sort value.
 140          */
 141         static uint32 GetPageElementSortValue(StoryPageElementID story_page_element_id);
 142
 143         /**
 144          * Get the company which the page belongs to. If the page is global,
 145          * ScriptCompany::COMPANY_INVALID is returned.
 146          * @param story_page_id The story page to get the company for.
 147          * @return owner company or ScriptCompany::COMPANY_INVALID
 148          * @pre IsValidStoryPage(story_page_id).
 149          */
 150         static ScriptCompany::CompanyID GetCompany(StoryPageID story_page_id);
 151
 152         /**
 153          * Get the page date which is displayed at the top of each page.
 154          * @param story_page_id The story page to get the date of.
 155          * @return The date
 156          * @pre IsValidStoryPage(story_page_id).
 157          */
 158         static ScriptDate::Date GetDate(StoryPageID story_page_id);
 159
 160         /**
 161          * Update date of a story page. The date is shown in the top left of the page
 162          * @param story_page_id The story page to set the date for.
 163          * @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)
 164          * @return True if the action succeeded.
 165          * @pre No ScriptCompanyMode may be in scope.
 166          * @pre IsValidStoryPage(story_page_id).
 167          */
 168         static bool SetDate(StoryPageID story_page_id, ScriptDate::Date date);
 169
 170         /**
 171          * Update title of a story page. The title is shown in the page selector drop down.
 172          * @param story_page_id The story page to update.
 173          * @param title Page title (can be either a raw string, a ScriptText object, or null).
 174          * @return True if the action succeeded.
 175          * @pre No ScriptCompanyMode may be in scope.
 176          * @pre IsValidStoryPage(story_page_id).
 177          */
 178         static bool SetTitle(StoryPageID story_page_id, Text *title);
 179
 180         /**
 181          * Opens the Story Book if not yet open and selects the given page.
 182          * @param story_page_id The story page to update. If it is a global page, clients of all
 183          * companies are affecetd. Otherwise only the clients of the company which the page belongs
 184          * to are affected.
 185          * @return True if the action succeeded.
 186          * @pre No ScriptCompanyMode may be in scope.
 187          * @pre IsValidStoryPage(story_page_id).
 188          */
 189         static bool Show(StoryPageID story_page_id);
 190
 191         /**
 192          * Remove a story page and all the page elements
 193          * associated with it.
 194          * @param story_page_id The story page to remove.
 195          * @return True if the action succeeded.
 196          * @pre No ScriptCompanyMode may be in scope.
 197          * @pre IsValidStoryPage(story_page_id).
 198          */
 199         static bool Remove(StoryPageID story_page_id);
 200
 201         /**
 202          * Removes a story page element.
 203          * @param story_page_element_id The story page element to remove.
 204          * @return True if the action succeeded.
 205          * @pre No ScriptCompanyMode may be in scope.
 206          * @pre IsValidStoryPageElement(story_page_element_id).
 207          */
 208         static bool RemoveElement(StoryPageElementID story_page_element_id);
 209 };
 210
 211 #endif /* SCRIPT_STORY_HPP */
 212