1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
|
/* $Id$ */
/*
* 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 "../../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 {
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.
};
/**
* 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_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 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.
* @param text The body text of page elements that allow custom text. (SPET_TEXT and SPET_LOCATION)
* @return The new StoryPageID, or STORY_INVALID if it failed.
* @pre No ScriptCompanyMode may be in scope.
* @pre IsValidStoryPage(story_page).
* @pre (type != SPET_TEXT && type != SPET_LOCATION) || (text != NULL && 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 refered 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 The new StoryPageID, or STORY_INVALID if it failed.
* @pre No ScriptCompanyMode may be in scope.
* @pre IsValidStoryPage(story_page).
* @pre (type != SPET_TEXT && type != SPET_LOCATION) || (text != NULL && 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);
/**
* 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 from the list.
* @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);
};
#endif /* SCRIPT_STORY_HPP */
|
