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))
 
(5 intermediate revisions by 2 users not shown)
Line 4: Line 4:
  
 
==Opening a window==
 
==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.
The function <nowiki>AllocateWindowDesc</nowiki> opens a window. It should be provided with a description (<code>AllocateWindowDesc(&_mywindow_desc);</code>). It returns the window pointer of the newly created window.
+
  
 
;<nowiki>Example:</nowiki>
 
;<nowiki>Example:</nowiki>
  
 
<pre>
 
<pre>
 +
/**
 +
* Opens a new instance of a MyNew window.
 +
* @param void Any parameters required by window
 +
*/
 
void ShowMyNewWindow(void)
 
void ShowMyNewWindow(void)
 
{
 
{
AllocateWindowDesc(&_mywindow_desc);
+
DeleteWindowByClass(window class);
 +
new MyNewWindow(void);
 
}
 
}
 
</pre>
 
</pre>
Line 18: Line 22:
 
==Describing a window==
 
==Describing a window==
  
Set up a <code>WindowDesc</code> with the name you gave <code>this->InitNested()</code>.
+
Set up a <code>WindowDesc</code> with the name you gave <code>this->CreateNestedTree()</code> and <code>this->FinishInitNested()</code>.
  
 
;<nowiki>Syntax:</nowiki>
 
;<nowiki>Syntax:</nowiki>
Line 32: Line 36:
 
         window flags
 
         window flags
 
         widget parts,
 
         widget parts,
         length of widget parts
+
         lengthof(widget parts)
 
);
 
);
 
</pre>
 
</pre>
 +
 +
You will also need a struct describing
 
You can find plenty of examples in the source code, look in a ''*_gui.cpp'' file.
 
You can find plenty of examples in the source code, look in a ''*_gui.cpp'' file.
  
Line 44: Line 50:
  
 
The list of available window classes is defined by the ''WindowClass'' enum, in ''src/window_type.h''.
 
The list of available window classes is defined by the ''WindowClass'' enum, in ''src/window_type.h''.
 
===Flags===
 
The window flags are a composition of bit values from the ''WindowDefaultFlag'' enum also defined in ''src/window_gui.h''. Use 0 if none of the flags apply.
 
  
 
==Setting up widgets==
 
==Setting up widgets==
 
:{{warning|This section is outdated and doesn't reflect the nested widget scheme}}
 
  
 
:;<nowiki>Syntax:</nowiki>
 
:;<nowiki>Syntax:</nowiki>
  
 
<pre>
 
<pre>
static const Widget _mywindow_widgets[] = {
+
static const NWidgetPart _nested_mywindow_widgets[] = {
{  Widget type, flags, color, position-left, position-right, position-top, position-bottom, string/image identifier, tooltip string identifier},
+
        NWidget(nwid),
 +
                NWidget(wwt, colour, wid), SetDataTip(STR_NULL, STR_TOOLTIP_WINDOW_TITLE_DRAG_THIS),
 +
        EndContainer(),
 
};
 
};
 
</pre>
 
</pre>
Line 63: Line 66:
  
 
<pre>
 
<pre>
static const Widget _mywindow_widgets[] = {
+
static const NWidgetPart _nested_mywindow_widgets[] = {
{  WWT_CLOSEBOX,   RESIZE_NONE,   14,     0,   10,     0,   13, STR_00C5,         STR_018B_CLOSE_WINDOW},
+
NWidget(NWID_HORIZONTAL),
{    WWT_CAPTION,   RESIZE_NONE,   14,   11,   419,    0,   13, STR_015B_OPENTTD, STR_NULL},
+
NWidget(WWT_TEXT, COLOUR_MAUVE), SetDataTip(STR_NEWGRF_SETTINGS_SELECT_PRESET, STR_NULL),
{      WWT_PANEL,  RESIZE_NONE,    14,    0,  419,    14,  271, 0x0,              STR_NULL},
+
SetPadding(0, WD_FRAMETEXT_RIGHT, 0, 0),
{      WWT_FRAME,   RESIZE_NONE,    14,    5,  414,    40,  245, STR_NULL,        STR_NULL},
+
NWidget(WWT_DROPDOWN, COLOUR_YELLOW, WID_NS_PRESET_LIST), SetFill(1, 0), SetResize(1, 0),
{    WIDGETS_END},
+
SetDataTip(STR_JUST_STRING, STR_NEWGRF_SETTINGS_PRESET_LIST_TOOLTIP),
 +
EndContainer(),
 
};
 
};
 
</pre>
 
</pre>
Line 75: Line 79:
  
 
;<code>WWT_EMPTY</code>
 
;<code>WWT_EMPTY</code>
:{{todo|-Include an explanation.}}
+
:
 +
{{todo|-Include an explanation.}}
  
 
;<code>WWT_PANEL</code>
 
;<code>WWT_PANEL</code>
Line 99: Line 104:
  
 
;<code>WWT_MATRIX</code>
 
;<code>WWT_MATRIX</code>
:{{todo|-Include an explanation.}}
+
:
 +
{{todo|-Include an explanation.}}
  
 
;<code>WWT_SCROLLBAR</code>
 
;<code>WWT_SCROLLBAR</code>
:{{todo|-Include an explanation.}}
+
:
 +
{{todo|-Include an explanation.}}
  
 
;<code>WWT_FRAME</code>
 
;<code>WWT_FRAME</code>
:{{todo|-Include an explanation.}}
+
:
 +
{{todo|-Include an explanation.}}
  
 
;<code>WWT_CAPTION</code>
 
;<code>WWT_CAPTION</code>
:{{todo|-Include an explanation.}}
+
:
 +
{{todo|-Include an explanation.}}
  
 
;<code>WWT_HSCROLLBAR</code>
 
;<code>WWT_HSCROLLBAR</code>
:{{todo|-Include an explanation.}}
+
:
 +
{{todo|-Include an explanation.}}
  
 
;<code>WWT_STICKYBOX</code>
 
;<code>WWT_STICKYBOX</code>
Line 117: Line 127:
  
 
;<code>WWT_SCROLL2BAR</code>
 
;<code>WWT_SCROLL2BAR</code>
:{{todo|-Include an explanation.}}
+
:
 +
{{todo|-Include an explanation.}}
  
 
;<code>WWT_RESIZEBOX</code>
 
;<code>WWT_RESIZEBOX</code>
Line 124: Line 135:
 
;<code>WWT_CLOSEBOX</code>
 
;<code>WWT_CLOSEBOX</code>
 
:The button for closing a window.
 
:The button for closing a window.
 
;<code>WWT_LAST</code>
 
:{{todo|-Include an explanation.}}
 
 
;<code>WWT_MASK</code>
 
:0x1F {{todo}}
 
  
 
;<code>WWT_PUSHBTN</code>
 
;<code>WWT_PUSHBTN</code>
:{{todo|-Include an explanation.}}
+
:
 +
{{todo|-Include an explanation.}}
  
 
;<code>WWT_PUSHTXTBTN</code>
 
;<code>WWT_PUSHTXTBTN</code>
:{{todo|-Include an explanation.}}
+
:
 +
{{todo|-Include an explanation.}}
  
 
;<code>WWT_PUSHIMGBTN</code>
 
;<code>WWT_PUSHIMGBTN</code>
:{{todo|-Include an explanation.}}
+
:
 +
{{todo|-Include an explanation.}}
  
===Flags===
+
===Colours===
 
+
Quote from <code>window.h</code> lines 16 onwards:
+
 
+
<pre>
+
/* How the resize system works:
+
    First, you need to add a WWT_RESIZEBOX to the widgets, and you need
+
    to add the flag WDF_RESIZABLE to the window. Now the window is ready
+
    to resize itself.
+
    As you may have noticed, all widgets have a RESIZE_XXX in their line.
+
    This lines controls how the widgets behave on resize. RESIZE_NONE means
+
    it doesn't do anything. Any other option let's one of the borders
+
    move with the changed width/height. So if a widget has
+
    RESIZE_RIGHT, and the window is made 5 pixels wider by the user,
+
    the right of the window will also be made 5 pixels wider.
+
    Now, what if you want to clamp a widget to the bottom? Give it the flag
+
    RESIZE_TB. This is RESIZE_TOP + RESIZE_BOTTOM. Now if the window gets
+
    5 pixels bigger, both the top and bottom gets 5 bigger, so the whole
+
    widgets moves downwards without resizing, and appears to be clamped
+
    to the bottom. Nice aint it?
+
  You should know one more thing about this system. Most windows can't
+
    handle an increase of 1 pixel. So there is a step function, which
+
    let the windowsize only be changed by X pixels. You configure this
+
    after making the window, like this:
+
      w->resize.step_height = 10;
+
    Now the window will only change in height in steps of 10.
+
  You can also give a minimum width and height. The default value is
+
    the default height/width of the window itself. You can change this
+
    AFTER window-creation, with:
+
    w->resize.width or w->resize.height.
+
  That was all.. good luck, and enjoy :) -- TrueLight */
+
</pre>
+
 
+
:;<code>RESIZE_NONE</code>
+
:{{todo|-Include an explanation.}}
+
 
+
:;<code>RESIZE_LEFT</code>
+
:{{todo|-Include an explanation.}}
+
 
+
:;<code>RESIZE_RIGHT</code>
+
:{{todo|-Include an explanation.}}
+
 
+
:;<code>RESIZE_TOP</code>
+
:{{todo|-Include an explanation.}}
+
 
+
:;<code>RESIZE_BOTTOM</code>
+
:{{todo|-Include an explanation.}}
+
 
+
:;<code>RESIZE_LR</code>
+
:{{todo|-Include an explanation.}}
+
 
+
:;<code>RESIZE_RB</code>
+
:{{todo|-Include an explanation.}}
+
 
+
:;<code>RESIZE_TB</code>
+
:{{todo|-Include an explanation.}}
+
 
+
:;<code>RESIZE_LRB</code>
+
:{{todo|-Include an explanation.}}
+
 
+
:;<code>RESIZE_LRTB</code>
+
:{{todo|-Include an explanation.}}
+
 
+
:;<code>RESIZE_RTB</code>
+
:{{todo|-Include an explanation.}}
+
 
+
:;<code>WIDG_DISABLED</code>
+
:Widget is disabled (greyed out)
+
 
+
:;<code>WIDG_HIDDEN</code>
+
:Widget is invisible
+
 
+
:;<code>WIDG_LOWERED</code>
+
:Widget pressed
+
 
+
===Colors===
+
  
 
''For a list of available colors, see [[OpenTTDDevBlackBook/Window/Colours]].''
 
''For a list of available colors, see [[OpenTTDDevBlackBook/Window/Colours]].''
Line 221: Line 154:
 
==Maintaining the window==
 
==Maintaining the window==
  
Set up a window procedure to be run each time <code>WE_PAINT</code> is called.
+
Define what to do with the window in a struct, with a constructor
  
 
:;<nowiki>Example:</nowiki>
 
:;<nowiki>Example:</nowiki>
  
 
<pre>
 
<pre>
static void MyWindowProc(Window *w, WindowEvent *e)
+
struct MyNewWindow {
{
+
        MyNewWindow()
switch (e->event) {
+
        {
case WE_PAINT: {
+
        }
DrawWindowWidgets(w);
+
        ....
} break;
+
}
+
 
}
 
}
 
</pre>
 
</pre>

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