OpenTTD GameScript API: GSStoryPage Class Reference

OpenTTD GameScript API 15.0-beta2

Public Types | Static Public Member Functions | Static Public Attributes
GSStoryPage Class Reference

Class that handles story page related functions. More...

`#include <script_story_page.hpp>`

Inheritance diagram for GSStoryPage:

## Public Types
enum | StoryPageElementType : int { SPET_TEXT , SPET_LOCATION , SPET_GOAL , SPET_BUTTON_PUSH , SPET_BUTTON_TILE , SPET_BUTTON_VEHICLE }
| Story page element types. More...
enum | StoryPageButtonFlags : int { SPBF_NONE , SPBF_FLOAT_LEFT , SPBF_FLOAT_RIGHT }
| Formatting and layout flags for story page buttons. More...
enum | StoryPageButtonCursor : int { SPBC_MOUSE , SPBC_ZZZ , SPBC_BUOY , SPBC_QUERY , SPBC_HQ , SPBC_SHIP_DEPOT , SPBC_SIGN , SPBC_TREE , SPBC_BUY_LAND , SPBC_LEVEL_LAND , SPBC_TOWN , SPBC_INDUSTRY , SPBC_ROCKY_AREA , SPBC_DESERT , SPBC_TRANSMITTER , SPBC_AIRPORT , SPBC_DOCK , SPBC_CANAL , SPBC_LOCK , SPBC_RIVER , SPBC_AQUEDUCT , SPBC_BRIDGE , SPBC_RAIL_STATION , SPBC_TUNNEL_RAIL , SPBC_TUNNEL_ELRAIL , SPBC_TUNNEL_MONO , SPBC_TUNNEL_MAGLEV , SPBC_AUTORAIL , SPBC_AUTOELRAIL , SPBC_AUTOMONO , SPBC_AUTOMAGLEV , SPBC_WAYPOINT , SPBC_RAIL_DEPOT , SPBC_ELRAIL_DEPOT , SPBC_MONO_DEPOT , SPBC_MAGLEV_DEPOT , SPBC_CONVERT_RAIL , SPBC_CONVERT_ELRAIL , SPBC_CONVERT_MONO , SPBC_CONVERT_MAGLEV , SPBC_AUTOROAD , SPBC_AUTOTRAM , SPBC_ROAD_DEPOT , SPBC_BUS_STATION , SPBC_TRUCK_STATION , SPBC_ROAD_TUNNEL , SPBC_CLONE_TRAIN , SPBC_CLONE_ROADVEH , SPBC_CLONE_SHIP , SPBC_CLONE_AIRPLANE , SPBC_DEMOLISH , SPBC_LOWERLAND , SPBC_RAISELAND , SPBC_PICKSTATION , SPBC_BUILDSIGNALS }
| Mouse cursors usable by story page buttons.
enum | StoryPageButtonColour : int { SPBC_DARK_BLUE , SPBC_PALE_GREEN , SPBC_PINK , SPBC_YELLOW , SPBC_RED , SPBC_LIGHT_BLUE , SPBC_GREEN , SPBC_DARK_GREEN , SPBC_BLUE , SPBC_CREAM , SPBC_MAUVE , SPBC_PURPLE , SPBC_ORANGE , SPBC_BROWN , SPBC_GREY , SPBC_WHITE }
| Colour codes usable for story page button elements. More...

## Static Public Member Functions
static bool | IsValidStoryPage (StoryPageID story_page_id)
| Check whether this is a valid story page ID.
static bool | IsValidStoryPageElement (StoryPageElementID story_page_element_id)
| Check whether this is a valid story page element ID.
static bool | IsValidStoryPageElementType (StoryPageElementType type)
| Check whether this is a valid story page element type.
static StoryPageID | New (GSCompany::CompanyID company, Text *title)
| Create a new story page.
static StoryPageElementID | NewElement (StoryPageID story_page_id, StoryPageElementType type, int reference, Text *text)
| Create a new story page element.
static bool | UpdateElement (StoryPageElementID story_page_element_id, int reference, Text *text)
| Update the content of a page element.
static int | GetPageSortValue (StoryPageID story_page_id)
| Get story page sort value.
static int | GetPageElementSortValue (StoryPageElementID story_page_element_id)
| Get story page element sort value.
static GSCompany::CompanyID | GetCompany (StoryPageID story_page_id)
| Get the company which the page belongs to.
static GSDate::Date | GetDate (StoryPageID story_page_id)
| Get the page date which is displayed at the top of each page.
static bool | SetDate (StoryPageID story_page_id, GSDate::Date date)
| Update date of a story page.
static bool | SetTitle (StoryPageID story_page_id, Text *title)
| Update title of a story page.
static bool | Show (StoryPageID story_page_id)
| Opens the Story Book if not yet open and selects the given page.
static bool | Remove (StoryPageID story_page_id)
| Remove a story page and all the page elements associated with it.
static bool | RemoveElement (StoryPageElementID story_page_element_id)
| Removes a story page element.
static bool | IsValidStoryPageButtonColour (StoryPageButtonColour colour)
| Check whether this is a valid story page button colour.
static bool | IsValidStoryPageButtonFlags (StoryPageButtonFlags flags)
| Check whether this is a valid story page button flag.
static bool | IsValidStoryPageButtonCursor (StoryPageButtonCursor cursor)
| Check whether this is a valid story page button cursor.
static StoryPageButtonFormatting | MakePushButtonReference (StoryPageButtonColour colour, StoryPageButtonFlags flags)
| Create a reference value for SPET_BUTTON_PUSH element parameters.
static StoryPageButtonFormatting | MakeTileButtonReference (StoryPageButtonColour colour, StoryPageButtonFlags flags, StoryPageButtonCursor cursor)
| Create a reference value for SPET_BUTTON_TILE element parameters.
static StoryPageButtonFormatting | MakeVehicleButtonReference (StoryPageButtonColour colour, StoryPageButtonFlags flags, StoryPageButtonCursor cursor, GSVehicle::VehicleType vehtype)
| Create a reference value for SPET_BUTTON_VEHICLE element parameters.

## Static Public Attributes
static constexpr StoryPageID | STORY_PAGE_INVALID = ::StoryPageID::Invalid()
| An invalid story page id.
static constexpr StoryPageElementID | STORY_PAGE_ELEMENT_INVALID = ::StoryPageElementID::Invalid()
| An invalid story page element id.

## Detailed Description

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.

## Member Enumeration Documentation

## ◆ StoryPageButtonColour

enum GSStoryPage::StoryPageButtonColour : int

Colour codes usable for story page button elements.

Place a colour value in the lowest 8 bits of the `reference` parameter to the button.

## ◆ StoryPageButtonFlags

enum GSStoryPage::StoryPageButtonFlags : int

Formatting and layout flags for story page buttons.

The SPBF_FLOAT_LEFT and SPBF_FLOAT_RIGHT flags can not be combined.

Enumerator
SPBF_NONE | No special formatting for button.
SPBF_FLOAT_LEFT | Button is placed to the left of the following paragraph.
SPBF_FLOAT_RIGHT | Button is placed to the right of the following paragraph.

## ◆ StoryPageElementType

enum GSStoryPage::StoryPageElementType : int

Story page element types.

Enumerator
SPET_TEXT | An element that displays a block of text.
SPET_LOCATION | An element that displays a single line of text along with a button to view the referenced location.
SPET_GOAL | An element that displays a goal.
SPET_BUTTON_PUSH | A push button that triggers an immediate event.
SPET_BUTTON_TILE | A button that allows the player to select a tile, and triggers an event with the tile.
SPET_BUTTON_VEHICLE | A button that allows the player to select a vehicle, and triggers an event with the vehicle.

## Member Function Documentation

## ◆ GetCompany()

static GSCompany::CompanyID GSStoryPage::GetCompany | ( | StoryPageID | story_page_id | ) |
| static

Get the company which the page belongs to.

If the page is global, GSCompany::COMPANY_INVALID is returned.

Parameters

  story_page_id | The story page to get the company for.

Returns
  owner company or GSCompany::COMPANY_INVALID

Precondition
  IsValidStoryPage(story_page_id).

## ◆ GetDate()

static GSDate::Date GSStoryPage::GetDate | ( | StoryPageID | story_page_id | ) |
| static

Get the page date which is displayed at the top of each page.

Parameters

  story_page_id | The story page to get the date of.

Returns
  The calendar-date

Precondition
  IsValidStoryPage(story_page_id).

See also
  GSCalendarTime

## ◆ GetPageElementSortValue()

static int GSStoryPage::GetPageElementSortValue | ( | StoryPageElementID | story_page_element_id | ) |
| static

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 GSStoryPageList the same order as in GUI. You should not use this number for anything else.

Parameters

  story_page_element_id | The story page element to get the sort value of.

Returns
  Page element sort value.

## ◆ GetPageSortValue()

static int GSStoryPage::GetPageSortValue | ( | StoryPageID | story_page_id | ) |
| static

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 GSStoryPageList the same order as in GUI. You should not use this number for anything else.

Parameters

  story_page_id | The story page to get the sort value of.

Returns
  Page sort value.

## ◆ IsValidStoryPage()

static bool GSStoryPage::IsValidStoryPage | ( | StoryPageID | story_page_id | ) |
| static

Check whether this is a valid story page ID.

Parameters

  story_page_id | The StoryPageID to check.

Returns
  True if and only if this story page is valid.

## ◆ IsValidStoryPageButtonColour()

static bool GSStoryPage::IsValidStoryPageButtonColour | ( | StoryPageButtonColour | colour | ) |
| static

Check whether this is a valid story page button colour.

Parameters

  colour | The StoryPageButtonColour to check.

Returns
  True if and only if this story page button colour is valid.

## ◆ IsValidStoryPageButtonCursor()

static bool GSStoryPage::IsValidStoryPageButtonCursor | ( | StoryPageButtonCursor | cursor | ) |
| static

Check whether this is a valid story page button cursor.

Parameters

  cursor | The StoryPageButtonCursor to check.

Returns
  True if and only if this story page button cursor is valid.

## ◆ IsValidStoryPageButtonFlags()

static bool GSStoryPage::IsValidStoryPageButtonFlags | ( | StoryPageButtonFlags | flags | ) |
| static

Check whether this is a valid story page button flag.

Parameters

  flags | The StoryPageButtonFlags to check.

Returns
  True if and only if this story page button flag is valid.

## ◆ IsValidStoryPageElement()

static bool GSStoryPage::IsValidStoryPageElement | ( | StoryPageElementID | story_page_element_id | ) |
| static

Check whether this is a valid story page element ID.

Parameters

  story_page_element_id | The StoryPageElementID to check.

Returns
  True if and only if this story page element is valid.

## ◆ IsValidStoryPageElementType()

static bool GSStoryPage::IsValidStoryPageElementType | ( | StoryPageElementType | type | ) |
| static

Check whether this is a valid story page element type.

Parameters

  type | The StoryPageElementType to check.

Returns
  True if and only if this story page element type is valid.

## ◆ MakePushButtonReference()

static StoryPageButtonFormatting GSStoryPage::MakePushButtonReference | ( | StoryPageButtonColour | colour,
|  | StoryPageButtonFlags | flags
| ) |  |
| static

Create a reference value for SPET_BUTTON_PUSH element parameters.

Parameters

  colour | The colour for the face of the button.
  flags | The formatting and layout flags for the button.

Returns
  A reference value usable with the NewElement and UpdateElement functions.

Precondition
  IsValidStoryPageButtonColour(colour).
  IsValidStoryPageButtonFlags(flags).

## ◆ MakeTileButtonReference()

static StoryPageButtonFormatting GSStoryPage::MakeTileButtonReference | ( | StoryPageButtonColour | colour,
|  | StoryPageButtonFlags | flags,
|  | StoryPageButtonCursor | cursor
| ) |  |
| static

Create a reference value for SPET_BUTTON_TILE element parameters.

Parameters

  colour | The colour for the face of the button.
  flags | The formatting and layout flags for the button.
  cursor | The mouse cursor to use when the player clicks the button and the game is ready for the player to select a tile.

Returns
  A reference value usable with the NewElement and UpdateElement functions.

Precondition
  IsValidStoryPageButtonColour(colour).
  IsValidStoryPageButtonFlags(flags).
  IsValidStoryPageButtonCursor(cursor).

## ◆ MakeVehicleButtonReference()

static StoryPageButtonFormatting GSStoryPage::MakeVehicleButtonReference | ( | StoryPageButtonColour | colour,
|  | StoryPageButtonFlags | flags,
|  | StoryPageButtonCursor | cursor,
|  | GSVehicle::VehicleType | vehtype
| ) |  |
| static

Create a reference value for SPET_BUTTON_VEHICLE element parameters.

Parameters

  colour | The colour for the face of the button.
  flags | The formatting and layout flags for the button.
  cursor | The mouse cursor to use when the player clicks the button and the game is ready for the player to select a vehicle.
  vehtype | The type of vehicle that will be selectable, or `VT_INVALID` to allow all types.

Returns
  A reference value usable with the NewElement and UpdateElement functions.

Precondition
  IsValidStoryPageButtonColour(colour).
  IsValidStoryPageButtonFlags(flags).
  IsValidStoryPageButtonCursor(cursor).
  vehtype == GSVehicle::VT_INVALID || vehtype == GSVehicle::VT_RAIL || vehtype == GSVehicle::VT_ROAD || vehtype == GSVehicle::VT_WATER || vehtype == GSVehicle::VT_AIR.

## ◆ New()

static StoryPageID GSStoryPage::New | ( | GSCompany::CompanyID | company,
|  | Text * | title
| ) |  |
| static

Create a new story page.

Parameters

  company | The company to create the story page for, or GSCompany::COMPANY_INVALID for all.
  title | Page title (can be either a raw string, a GSText object, or null).

Returns
  The new StoryPageID, or STORY_PAGE_INVALID if it failed.

Precondition
  GSCompanyMode::IsDeity().
  company == COMPANY_INVALID || ResolveCompanyID(company) != COMPANY_INVALID.

## ◆ NewElement()

static StoryPageElementID GSStoryPage::NewElement | ( | StoryPageID | story_page_id,
|  | StoryPageElementType | type,
|  | int | reference,
|  | Text * | text
| ) |  |
| static

Create a new story page element.

Parameters

  story_page_id | The page id of the story page which the page element should be appended to.
  type | Which page element type to create.
  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 the ID returned by MakePushButtonReference, MakeTileButtonReference, or MakeVehicleButtonReference.
  text | The body text of page elements that allow custom text. (SPET_TEXT and SPET_LOCATION)

Returns
  The new StoryPageElementID, or STORY_PAGE_ELEMENT_INVALID if it failed.

Precondition
  GSCompanyMode::IsDeity().
  IsValidStoryPage(story_page).
  IsValidStoryPageElementType(type).
  (type != SPET_TEXT && type != SPET_LOCATION) || (text != null && len(text) != 0).
  type != SPET_LOCATION || GSMap::IsValidTile(reference).
  type != SPET_GOAL || GSGoal::IsValidGoal(reference).
  if type is SPET_GOAL and story_page is a global page, then referenced goal must be global.

## ◆ Remove()

static bool GSStoryPage::Remove | ( | StoryPageID | story_page_id | ) |
| static

Remove a story page and all the page elements associated with it.

Parameters

  story_page_id | The story page to remove.

Returns
  True if the action succeeded.

Precondition
  GSCompanyMode::IsDeity().
  IsValidStoryPage(story_page_id).

## ◆ RemoveElement()

static bool GSStoryPage::RemoveElement | ( | StoryPageElementID | story_page_element_id | ) |
| static

Removes a story page element.

Parameters

  story_page_element_id | The story page element to remove.

Returns
  True if the action succeeded.

Precondition
  GSCompanyMode::IsDeity().
  IsValidStoryPageElement(story_page_element_id).

## ◆ SetDate()

static bool GSStoryPage::SetDate | ( | StoryPageID | story_page_id,
|  | GSDate::Date | date
| ) |  |
| static

Update date of a story page.

The date is shown in the top left of the page

Parameters

  story_page_id | The story page to set the date for.
  date | Calendar-date to display at the top of story page or GSDate::DATE_INVALID to disable showing date on this page. (also,

See also
  GSDate)

Returns
  True if the action succeeded.

Precondition
  GSCompanyMode::IsDeity().
  IsValidStoryPage(story_page_id).

See also
  GSCalendarTime

## ◆ SetTitle()

static bool GSStoryPage::SetTitle | ( | StoryPageID | story_page_id,
|  | Text * | title
| ) |  |
| static

Update title of a story page.

The title is shown in the page selector drop down.

Parameters

  story_page_id | The story page to update.
  title | Page title (can be either a raw string, a GSText object, or null).

Returns
  True if the action succeeded.

Precondition
  GSCompanyMode::IsDeity().
  IsValidStoryPage(story_page_id).

## ◆ Show()

static bool GSStoryPage::Show | ( | StoryPageID | story_page_id | ) |
| static

Opens the Story Book if not yet open and selects the given page.

Parameters

  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.

Returns
  True if the action succeeded.

Precondition
  GSCompanyMode::IsDeity().
  IsValidStoryPage(story_page_id).

## ◆ UpdateElement()

static bool GSStoryPage::UpdateElement | ( | StoryPageElementID | story_page_element_id,
|  | int | reference,
|  | Text * | text
| ) |  |
| static

Update the content of a page element.

Parameters

  story_page_element_id | The page id of the story page which the page element should be appended to.
  reference | A reference value to the object that is referred to by some page element types. See also NewElement.
  text | The body text of page elements that allow custom text. See also NewElement.

Returns
  True if the action succeeded.

Precondition
  GSCompanyMode::IsDeity().
  IsValidStoryPage(story_page).
  (type != SPET_TEXT && type != SPET_LOCATION) || (text != null && len(text) != 0).
  type != SPET_LOCATION || GSMap::IsValidTile(reference).
  type != SPET_GOAL || GSGoal::IsValidGoal(reference).
  if type is SPET_GOAL and story_page is a global page, then referenced goal must be global.