GSStoryPage Class Reference

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

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 {   SPET_TEXT,   SPET_LOCATION,   SPET_GOAL }
	Story page element types. 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 StoryPageID	New (GSCompany::CompanyID company, Text *title)
	Create a new story page.
static StoryPageElementID	NewElement (StoryPageID story_page_id, StoryPageElementType type, uint32 reference, Text *text)
	Create a new story page element.
static bool	UpdateElement (StoryPageElementID story_page_element_id, uint32 reference, Text *text)
	Update the content of a page element.
static uint32	GetPageSortValue (StoryPageID story_page_id)
	Get story page sort value.
static uint32	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.

---

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

enum GSStoryPage::StoryPageID

The story page IDs.

Enumerator:

STORY_PAGE_INVALID

An invalid story page id.

enum GSStoryPage::StoryPageElementID

The story page element IDs.

Enumerator:

STORY_PAGE_ELEMENT_INVALID

An invalid story page element id.

enum GSStoryPage::StoryPageElementType

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.

---

Member Function Documentation

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.

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.

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:

No GSCompanyMode may be in scope.

company == COMPANY_INVALID || ResolveCompanyID(company) != COMPANY_INVALID.

static StoryPageElementID GSStoryPage::NewElement	(	StoryPageID	story_page_id,
		StoryPageElementType	type,
		uint32	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 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.
	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:

No GSCompanyMode may be in scope.

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.

static bool GSStoryPage::UpdateElement	(	StoryPageElementID	story_page_element_id,
		uint32	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 refered 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:

No GSCompanyMode may be in scope.

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.

static uint32 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.

static uint32 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.

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).

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).

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:

No GSCompanyMode may be in scope.

IsValidStoryPage(story_page_id).

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:

No GSCompanyMode may be in scope.

IsValidStoryPage(story_page_id).

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:

No GSCompanyMode may be in scope.

IsValidStoryPage(story_page_id).

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:

No GSCompanyMode may be in scope.

IsValidStoryPage(story_page_id).

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:

No GSCompanyMode may be in scope.

IsValidStoryPageElement(story_page_element_id).