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

Inheritance diagram for GSStoryPage:

Public Types
enum	StoryPageID { STORY_PAGE_INVALID }
	The story page IDs. More...

enum	StoryPageElementID { STORY_PAGE_ELEMENT_INVALID }
	The story page element IDs. More...

enum	StoryPageElementType : uint8_t { SPET_TEXT, SPET_LOCATION, SPET_GOAL, SPET_BUTTON_PUSH, SPET_BUTTON_TILE, SPET_BUTTON_VEHICLE }
	Story page element types. More...

enum	StoryPageButtonFlags : uint8_t { SPBF_NONE, SPBF_FLOAT_LEFT, SPBF_FLOAT_RIGHT }
	Formatting and layout flags for story page buttons. More...

enum	StoryPageButtonCursor : uint8_t { 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 : uint8_t { 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. More...

static bool	IsValidStoryPageElement (StoryPageElementID story_page_element_id)
	Check whether this is a valid story page element ID. More...

static bool	IsValidStoryPageElementType (StoryPageElementType type)
	Check whether this is a valid story page element type. More...

static StoryPageID	New (GSCompany::CompanyID company, Text *title)
	Create a new story page. More...

static StoryPageElementID	NewElement (StoryPageID story_page_id, StoryPageElementType type, SQInteger reference, Text *text)
	Create a new story page element. More...

static bool	UpdateElement (StoryPageElementID story_page_element_id, SQInteger reference, Text *text)
	Update the content of a page element. More...

static SQInteger	GetPageSortValue (StoryPageID story_page_id)
	Get story page sort value. More...

static SQInteger	GetPageElementSortValue (StoryPageElementID story_page_element_id)
	Get story page element sort value. More...

static GSCompany::CompanyID	GetCompany (StoryPageID story_page_id)
	Get the company which the page belongs to. More...

static GSDate::Date	GetDate (StoryPageID story_page_id)
	Get the page date which is displayed at the top of each page. More...

static bool	SetDate (StoryPageID story_page_id, GSDate::Date date)
	Update date of a story page. More...

static bool	SetTitle (StoryPageID story_page_id, Text *title)
	Update title of a story page. More...

static bool	Show (StoryPageID story_page_id)
	Opens the Story Book if not yet open and selects the given page. More...

static bool	Remove (StoryPageID story_page_id)
	Remove a story page and all the page elements associated with it. More...

static bool	RemoveElement (StoryPageElementID story_page_element_id)
	Removes a story page element. More...

static bool	IsValidStoryPageButtonColour (StoryPageButtonColour colour)
	Check whether this is a valid story page button colour. More...

static bool	IsValidStoryPageButtonFlags (StoryPageButtonFlags flags)
	Check whether this is a valid story page button flag. More...

static bool	IsValidStoryPageButtonCursor (StoryPageButtonCursor cursor)
	Check whether this is a valid story page button cursor. More...

static StoryPageButtonFormatting	MakePushButtonReference (StoryPageButtonColour colour, StoryPageButtonFlags flags)
	Create a reference value for SPET_BUTTON_PUSH element parameters. More...

static StoryPageButtonFormatting	MakeTileButtonReference (StoryPageButtonColour colour, StoryPageButtonFlags flags, StoryPageButtonCursor cursor)
	Create a reference value for SPET_BUTTON_TILE element parameters. More...

static StoryPageButtonFormatting	MakeVehicleButtonReference (StoryPageButtonColour colour, StoryPageButtonFlags flags, StoryPageButtonCursor cursor, GSVehicle::VehicleType vehtype)
	Create a reference value for SPET_BUTTON_VEHICLE element parameters. More...

Detailed Description

Class that handles story page related functions.

To create a page:

Create the page
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 : uint8_t

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 : uint8_t

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.

◆ StoryPageElementID

enum GSStoryPage::StoryPageElementID

The story page element IDs.

Enumerator
STORY_PAGE_ELEMENT_INVALID	An invalid story page element id.

◆ StoryPageElementType

enum GSStoryPage::StoryPageElementType : uint8_t

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 wih the vehicle.

◆ StoryPageID

enum GSStoryPage::StoryPageID

The story page IDs.

Enumerator
STORY_PAGE_INVALID	An invalid story page id.

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 date

Precondition: IsValidStoryPage(story_page_id).

◆ GetPageElementSortValue()

static SQInteger 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 SQInteger 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

colour 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

colour 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,
		SQInteger	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 additional parameters for the button, use the #BuildPushButtonReference, #BuildTileButtonReference, or #BuildVehicleButtonReference functions to make the values.
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	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).

◆ 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,
		SQInteger	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.

Public Types

Static Public Member Functions

Detailed Description

Member Enumeration Documentation

◆ StoryPageButtonColour

◆ StoryPageButtonFlags

◆ StoryPageElementID

◆ StoryPageElementType

◆ StoryPageID

Member Function Documentation

◆ GetCompany()

◆ GetDate()

◆ GetPageElementSortValue()

◆ GetPageSortValue()

◆ IsValidStoryPage()

◆ IsValidStoryPageButtonColour()

◆ IsValidStoryPageButtonCursor()

◆ IsValidStoryPageButtonFlags()

◆ IsValidStoryPageElement()

◆ IsValidStoryPageElementType()

◆ MakePushButtonReference()

◆ MakeTileButtonReference()

◆ MakeVehicleButtonReference()

◆ New()

◆ NewElement()

◆ Remove()

◆ RemoveElement()

◆ SetDate()

◆ SetTitle()

◆ Show()

◆ UpdateElement()