OpenTTDDevBlackBook/Window/UseWindows

From OpenTTD
(Difference between revisions)
Jump to: navigation, search
(Windows flags are not exposed at the window API any more (for about 5 years))
 
(22 intermediate revisions by 13 users not shown)
Line 1: Line 1:
 +
{{DevDoc}}
  
 +
A window is drawn on the game screen at every <code>WE_PAINT</code> [[OpenTTDDevBlackBook/Window/WindowEvents|window event]].
 +
 +
==Opening a window==
 +
Creating a new struct of a window opens a new window. It should be provided with a doxygen comment explaining the function.
 +
 +
;<nowiki>Example:</nowiki>
 +
 +
<pre>
 +
/**
 +
* Opens a new instance of a MyNew window.
 +
* @param void Any parameters required by window
 +
*/
 +
void ShowMyNewWindow(void)
 +
{
 +
DeleteWindowByClass(window class);
 +
new MyNewWindow(void);
 +
}
 +
</pre>
 +
 +
==Describing a window==
 +
 +
Set up a <code>WindowDesc</code> with the name you gave <code>this->CreateNestedTree()</code> and <code>this->FinishInitNested()</code>.
 +
 +
;<nowiki>Syntax:</nowiki>
 +
 +
<pre>
 +
/** Window description for my new window. */
 +
static const WindowDesc _mywindow_desc(
 +
window positioning,
 +
        default width,
 +
        default height,
 +
        window class,
 +
        parent window class,
 +
        window flags
 +
        widget parts,
 +
        lengthof(widget parts)
 +
);
 +
</pre>
 +
 +
You will also need a struct describing
 +
You can find plenty of examples in the source code, look in a ''*_gui.cpp'' file.
 +
 +
===Window positioning===
 +
The window positioning is one of the values of the ''WindowPosition'' enum defined in src/window_gui.h.
 +
 +
===Window classes===
 +
A window class is a unique number that represents a (set of) windows, for example a window that displays a town has class ''WC_TOWN_VIEW''. To differentiate which town is displayed by an actual window, the latter has an additional window number.
 +
 +
The list of available window classes is defined by the ''WindowClass'' enum, in ''src/window_type.h''.
 +
 +
==Setting up widgets==
 +
 +
:;<nowiki>Syntax:</nowiki>
 +
 +
<pre>
 +
static const NWidgetPart _nested_mywindow_widgets[] = {
 +
        NWidget(nwid),
 +
                NWidget(wwt, colour, wid), SetDataTip(STR_NULL, STR_TOOLTIP_WINDOW_TITLE_DRAG_THIS),
 +
        EndContainer(),
 +
};
 +
</pre>
 +
 +
:;<nowiki>Example:</nowiki>
 +
 +
<pre>
 +
static const NWidgetPart _nested_mywindow_widgets[] = {
 +
NWidget(NWID_HORIZONTAL),
 +
NWidget(WWT_TEXT, COLOUR_MAUVE), SetDataTip(STR_NEWGRF_SETTINGS_SELECT_PRESET, STR_NULL),
 +
SetPadding(0, WD_FRAMETEXT_RIGHT, 0, 0),
 +
NWidget(WWT_DROPDOWN, COLOUR_YELLOW, WID_NS_PRESET_LIST), SetFill(1, 0), SetResize(1, 0),
 +
SetDataTip(STR_JUST_STRING, STR_NEWGRF_SETTINGS_PRESET_LIST_TOOLTIP),
 +
EndContainer(),
 +
};
 +
</pre>
 +
 +
===Widget types===
 +
 +
;<code>WWT_EMPTY</code>
 +
:
 +
{{todo|-Include an explanation.}}
 +
 +
;<code>WWT_PANEL</code>
 +
:A simple depressed panel.
 +
 +
;<code>WWT_INSET</code>
 +
:A depressed panel, most commonly used as a combo box text area.
 +
 +
;<code>WWT_IMGBTN</code>
 +
:Image button.
 +
 +
;<code>WWT_IMGBTN_2</code>
 +
:Image button. Image changes when button is pressed.
 +
 +
;<code>WWT_TEXTBTN</code>
 +
:Text button.
 +
 +
;<code>WWT_TEXTBTN_2</code>
 +
:Text button. Text changes when button is pressed.
 +
 +
;<code>WWT_LABEL</code>
 +
:A centered label.
 +
 +
;<code>WWT_MATRIX</code>
 +
:
 +
{{todo|-Include an explanation.}}
 +
 +
;<code>WWT_SCROLLBAR</code>
 +
:
 +
{{todo|-Include an explanation.}}
 +
 +
;<code>WWT_FRAME</code>
 +
:
 +
{{todo|-Include an explanation.}}
 +
 +
;<code>WWT_CAPTION</code>
 +
:
 +
{{todo|-Include an explanation.}}
 +
 +
;<code>WWT_HSCROLLBAR</code>
 +
:
 +
{{todo|-Include an explanation.}}
 +
 +
;<code>WWT_STICKYBOX</code>
 +
:The button for stickying a window.
 +
 +
;<code>WWT_SCROLL2BAR</code>
 +
:
 +
{{todo|-Include an explanation.}}
 +
 +
;<code>WWT_RESIZEBOX</code>
 +
:The button for resizing a window.
 +
 +
;<code>WWT_CLOSEBOX</code>
 +
:The button for closing a window.
 +
 +
;<code>WWT_PUSHBTN</code>
 +
:
 +
{{todo|-Include an explanation.}}
 +
 +
;<code>WWT_PUSHTXTBTN</code>
 +
:
 +
{{todo|-Include an explanation.}}
 +
 +
;<code>WWT_PUSHIMGBTN</code>
 +
:
 +
{{todo|-Include an explanation.}}
 +
 +
===Colours===
 +
 +
''For a list of available colors, see [[OpenTTDDevBlackBook/Window/Colours]].''
 +
 +
==Maintaining the window==
 +
 +
Define what to do with the window in a struct, with a constructor
 +
 +
:;<nowiki>Example:</nowiki>
 +
 +
<pre>
 +
struct MyNewWindow {
 +
        MyNewWindow()
 +
        {
 +
        }
 +
        ....
 +
}
 +
</pre>
 +
 +
[[Category:Development]]
 +
[[Category:OpenTTDDevBlackBook|W]]

Latest revision as of 13:13, 28 December 2014

External Links

OpenTTD GitHub
Contributing to OpenTTD - guidelines
OpenTTD Doxygen

General Reference

Coding style
Compiling OpenTTD
Debugging
Add a setting
Add a squirrel function
Understanding the SaveGame handler
Bumping the savegame version
Doing an OpenTTD release

Language and Strings

Manual of style
Format of langfiles
Using OpenTTD strings
List of special strings

Window System

Using the window system
Colour codes that exist in OpenTTD
Adding a text box
Understanding the widget focus system
GUI style guide

Multiplayer

The OpenTTD TCP protocol
The OpenTTD UDP protocol
Debugging desyncs
Server Admin Port development

Ingame Console

The console window
Console commands
Console variables
Using console scripting
Adding functions/commands to the console
Adding variables to the console
Console development history

Content APIs (modding frameworks)

Graphics and similar (NewGRF)
AI framework (NoAI)
GameScript framework (NoGO)

Other Reference

Map array (landscape grid)
Vehicles
Pathfinding
Train acceleration


A window is drawn on the game screen at every WE_PAINT window event.

Contents

[edit] Opening a window

Creating a new struct of a window opens a new window. It should be provided with a doxygen comment explaining the function.

Example:
/**
 * Opens a new instance of a MyNew window.
 * @param void Any parameters required by window
 */
void ShowMyNewWindow(void)
{
	DeleteWindowByClass(window class);
	new MyNewWindow(void);
}

[edit] Describing a window

Set up a WindowDesc with the name you gave this->CreateNestedTree() and this->FinishInitNested().

Syntax:
/** Window description for my new window. */
static const WindowDesc _mywindow_desc(
	window positioning,
        default width,
        default height,
        window class,
        parent window class,
        window flags
        widget parts,
        lengthof(widget parts)
);

You will also need a struct describing You can find plenty of examples in the source code, look in a *_gui.cpp file.

[edit] Window positioning

The window positioning is one of the values of the WindowPosition enum defined in src/window_gui.h.

[edit] Window classes

A window class is a unique number that represents a (set of) windows, for example a window that displays a town has class WC_TOWN_VIEW. To differentiate which town is displayed by an actual window, the latter has an additional window number.

The list of available window classes is defined by the WindowClass enum, in src/window_type.h.

[edit] Setting up widgets

Syntax:
static const NWidgetPart _nested_mywindow_widgets[] = {
        NWidget(nwid),
                 NWidget(wwt, colour, wid), SetDataTip(STR_NULL, STR_TOOLTIP_WINDOW_TITLE_DRAG_THIS),
        EndContainer(),
};
Example:
static const NWidgetPart _nested_mywindow_widgets[] = {
	NWidget(NWID_HORIZONTAL),
		NWidget(WWT_TEXT, COLOUR_MAUVE), SetDataTip(STR_NEWGRF_SETTINGS_SELECT_PRESET, STR_NULL),
				SetPadding(0, WD_FRAMETEXT_RIGHT, 0, 0),
		NWidget(WWT_DROPDOWN, COLOUR_YELLOW, WID_NS_PRESET_LIST), SetFill(1, 0), SetResize(1, 0),
				SetDataTip(STR_JUST_STRING, STR_NEWGRF_SETTINGS_PRESET_LIST_TOOLTIP),
	EndContainer(),
};

[edit] Widget types

WWT_EMPTY
Klipper.png

To Do
-Include an explanation.

WWT_PANEL
A simple depressed panel.
WWT_INSET
A depressed panel, most commonly used as a combo box text area.
WWT_IMGBTN
Image button.
WWT_IMGBTN_2
Image button. Image changes when button is pressed.
WWT_TEXTBTN
Text button.
WWT_TEXTBTN_2
Text button. Text changes when button is pressed.
WWT_LABEL
A centered label.
WWT_MATRIX
Klipper.png

To Do
-Include an explanation.

WWT_SCROLLBAR
Klipper.png

To Do
-Include an explanation.

WWT_FRAME
Klipper.png

To Do
-Include an explanation.

WWT_CAPTION
Klipper.png

To Do
-Include an explanation.

WWT_HSCROLLBAR
Klipper.png

To Do
-Include an explanation.

WWT_STICKYBOX
The button for stickying a window.
WWT_SCROLL2BAR
Klipper.png

To Do
-Include an explanation.

WWT_RESIZEBOX
The button for resizing a window.
WWT_CLOSEBOX
The button for closing a window.
WWT_PUSHBTN
Klipper.png

To Do
-Include an explanation.

WWT_PUSHTXTBTN
Klipper.png

To Do
-Include an explanation.

WWT_PUSHIMGBTN
Klipper.png

To Do
-Include an explanation.

[edit] Colours

For a list of available colors, see OpenTTDDevBlackBook/Window/Colours.

[edit] Maintaining the window

Define what to do with the window in a struct, with a constructor

Example:
struct MyNewWindow {
        MyNewWindow()
        {
        }
        ....
}
Personal tools