OpenTTDDevBlackBook/Window/UseWindows

From OpenTTD
(Difference between revisions)
Jump to: navigation, search
(Re-wrote window class text)
(Cleaning up the window description part)
Line 18: Line 18:
 
==Describing a window==
 
==Describing a window==
  
Set up a <code>WindowDesc</code> with the name you gave <code>AllocateWindowDesc</code>.
+
Set up a <code>WindowDesc</code> with the name you gave <code>this->InitNested()</code>.
  
 
;<nowiki>Syntax:</nowiki>
 
;<nowiki>Syntax:</nowiki>
  
 
<pre>
 
<pre>
static const WindowDesc _mywindow_desc = {
+
/** Window description for my new window. */
X-coordinate of window top-left corner,  
+
static const WindowDesc _mywindow_desc(
Y-coordinate of window top-left corner,  
+
window positioning,
window width, window height,
+
        default width,
window class,
+
        default height,
window parent class,  
+
        window class,
window flags,
+
        parent window class,
widget definition,  
+
        window flags
window procedure name
+
        widget parts,
};
+
        length of widget parts
 +
);
 
</pre>
 
</pre>
 +
You can find plenty of examples in the source code, look in a ''*_gui.cpp'' file.
  
;<nowiki>Example:</nowiki>
+
===Window positioning===
 
+
The window positioning is one of the values of the ''WindowPosition'' enum defined in src/window_gui.h.
<pre>
+
static const WindowDesc _mywindow_desc = {
+
100, 100, 150, 200,
+
WC_ERRMSG,
+
0,
+
WDF_STD_TOOLTIPS | WDF_STD_BTN | WDF_DEF_WIDGET,
+
_mywindow_widgets,
+
MyWindowProc
+
};
+
</pre>
+
 
+
===Coordinate variables===
+
 
+
These variables can be used to replace static coordinate numbers.
+
 
+
;<code>WDP_AUTO</code>
+
:Finds a location automatically
+
 
+
;<code>WDP_CENTER</code>
+
:Centers the window (left/right or top/bottom)
+
 
+
;<code>WDP_ALIGN_TBR</code>
+
:Aligns the right side of the window with the right side of the main toolbar
+
 
+
;<code>WDP_ALIGN_TBL</code>
+
:Aligns the left side of the window with the left side of the main toolbar
+
  
 
===Window classes===
 
===Window classes===
Line 70: Line 46:
  
 
===Flags===
 
===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.
;<code>WDF_STD_TOOLTIPS</code>
+
:Use standard routine when displaying tooltips
+
 
+
;<code>WDF_DEF_WIDGET</code>
+
:Default widget control for some widgets in the onClick event
+
 
+
;<code>WDF_STD_BTN</code>
+
:Default handling for close and drag widgets (widget n:o 0 and 1)
+
 
+
;<code>WDF_UNCLICK_BUTTONS</code>
+
:Unclick buttons when the window event times out
+
 
+
;<code>WDF_STICKY_BUTTON</code>
+
:Set window to sticky mode; they are not closed unless closed with 'X' (widget 2)
+
 
+
;<code>WDF_RESIZABLE</code>
+
:A window can be resized
+
 
+
;<code>WDF_MODAL</code>
+
:The window is a modal child of some other window, meaning the parent is 'inactive'
+
  
 
==Setting up widgets==
 
==Setting up widgets==

Revision as of 17:40, 29 July 2010

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

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

Opening a window

The function AllocateWindowDesc opens a window. It should be provided with a description (AllocateWindowDesc(&_mywindow_desc);). It returns the window pointer of the newly created window.

Example:
void ShowMyNewWindow(void)
{
	AllocateWindowDesc(&_mywindow_desc);
}

Describing a window

Set up a WindowDesc with the name you gave this->InitNested().

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,
        length of widget parts
);

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.

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

Content.png

Warning
This section is outdated and doesn't reflect the nested widget scheme

Syntax:
static const Widget _mywindow_widgets[] = {
{   Widget type, flags, color, position-left, position-right, position-top, position-bottom, string/image identifier, tooltip string identifier},
};
Example:
static const Widget _mywindow_widgets[] = {
{   WWT_CLOSEBOX,   RESIZE_NONE,    14,     0,    10,     0,    13, STR_00C5,         STR_018B_CLOSE_WINDOW},
{    WWT_CAPTION,   RESIZE_NONE,    14,    11,   419,     0,    13, STR_015B_OPENTTD, STR_NULL},
{      WWT_PANEL,   RESIZE_NONE,    14,     0,   419,    14,   271, 0x0,              STR_NULL},
{      WWT_FRAME,   RESIZE_NONE,    14,     5,   414,    40,   245, STR_NULL,         STR_NULL},
{    WIDGETS_END},
};

Widget types

WWT_EMPTY
Klipper.png

To Do
Whoever added this template didn't specify what was to be done, so it should be removed or updated with the correct action.

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
Whoever added this template didn't specify what was to be done, so it should be removed or updated with the correct action.

WWT_SCROLLBAR
Klipper.png

To Do
Whoever added this template didn't specify what was to be done, so it should be removed or updated with the correct action.

WWT_FRAME
Klipper.png

To Do
Whoever added this template didn't specify what was to be done, so it should be removed or updated with the correct action.

WWT_CAPTION
Klipper.png

To Do
Whoever added this template didn't specify what was to be done, so it should be removed or updated with the correct action.

WWT_HSCROLLBAR
Klipper.png

To Do
Whoever added this template didn't specify what was to be done, so it should be removed or updated with the correct action.

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

To Do
Whoever added this template didn't specify what was to be done, so it should be removed or updated with the correct action.

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

To Do
Whoever added this template didn't specify what was to be done, so it should be removed or updated with the correct action.

WWT_MASK
0x1F
Klipper.png

To Do
Whoever added this template didn't specify what was to be done, so it should be removed or updated with the correct action.

WWT_PUSHBTN
Klipper.png

To Do
Whoever added this template didn't specify what was to be done, so it should be removed or updated with the correct action.

WWT_PUSHTXTBTN
Klipper.png

To Do
Whoever added this template didn't specify what was to be done, so it should be removed or updated with the correct action.

WWT_PUSHIMGBTN
Klipper.png

To Do
Whoever added this template didn't specify what was to be done, so it should be removed or updated with the correct action.

Flags

Quote from window.h lines 16 onwards:

/* 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 */
RESIZE_NONE
Klipper.png

To Do
Whoever added this template didn't specify what was to be done, so it should be removed or updated with the correct action.

RESIZE_LEFT
Klipper.png

To Do
Whoever added this template didn't specify what was to be done, so it should be removed or updated with the correct action.

RESIZE_RIGHT
Klipper.png

To Do
Whoever added this template didn't specify what was to be done, so it should be removed or updated with the correct action.

RESIZE_TOP
Klipper.png

To Do
Whoever added this template didn't specify what was to be done, so it should be removed or updated with the correct action.

RESIZE_BOTTOM
Klipper.png

To Do
Whoever added this template didn't specify what was to be done, so it should be removed or updated with the correct action.

RESIZE_LR
Klipper.png

To Do
Whoever added this template didn't specify what was to be done, so it should be removed or updated with the correct action.

RESIZE_RB
Klipper.png

To Do
Whoever added this template didn't specify what was to be done, so it should be removed or updated with the correct action.

RESIZE_TB
Klipper.png

To Do
Whoever added this template didn't specify what was to be done, so it should be removed or updated with the correct action.

RESIZE_LRB
Klipper.png

To Do
Whoever added this template didn't specify what was to be done, so it should be removed or updated with the correct action.

RESIZE_LRTB
Klipper.png

To Do
Whoever added this template didn't specify what was to be done, so it should be removed or updated with the correct action.

RESIZE_RTB
Klipper.png

To Do
Whoever added this template didn't specify what was to be done, so it should be removed or updated with the correct action.

WIDG_DISABLED
Widget is disabled (greyed out)
WIDG_HIDDEN
Widget is invisible
WIDG_LOWERED
Widget pressed

Colors

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

Maintaining the window

Set up a window procedure to be run each time WE_PAINT is called.

Example:
static void MyWindowProc(Window *w, WindowEvent *e)
{
	switch (e->event) {
		case WE_PAINT: {
			DrawWindowWidgets(w);
		}	break;
	}
}
Retrieved from "http://wiki.openttd.org/?title=OpenTTDDevBlackBook/Window/UseWindows&oldid=40640"
Views
Personal tools
Navigation
Toolbox