# window_gui.h File Reference

Functions, definitions and such used only by the GUI. More...

`#include "core/math_func.hpp"`
`#include "vehicle_type.h"`
`#include "viewport_type.h"`
`#include "company_type.h"`
`#include "tile_type.h"`
`#include "widget_type.h"`

Go to the source code of this file.

## Data Structures

struct | WindowDesc
| High level window description. More...
class | Scrollbar
| Scrollbar data structure. More...
struct | ResizeInfo
| Data structure for resizing a window. More...
struct | ViewportData
| Data structure for a window viewport. More...
struct | Window
| Data structure for an opened window. More...
class | PickerWindowBase
| Base class for windows opened from a toolbar. More...

## Defines

#define | FOR_ALL_WINDOWS_FROM_BACK_FROM(w, start) for (w = start; w != NULL; w = w->z_front) if (w->window_class != WC_INVALID)
| Iterate over all windows.
#define | FOR_ALL_WINDOWS_FROM_FRONT_FROM(w, start) for (w = start; w != NULL; w = w->z_back) if (w->window_class != WC_INVALID)
#define | FOR_ALL_WINDOWS_FROM_BACK(w) FOR_ALL_WINDOWS_FROM_BACK_FROM(w, _z_back_window)
#define | FOR_ALL_WINDOWS_FROM_FRONT(w) FOR_ALL_WINDOWS_FROM_FRONT_FROM(w, _z_front_window)

## Enumerations

enum | FrameFlags { FR_NONE = 0, FR_TRANSPARENT = 1 << 0, FR_BORDERONLY = 1 << 4, FR_LOWERED = 1 << 5, FR_DARKENED = 1 << 6 }
| Flags to describe the look of the frame. More...

enum

WidgetDrawDistances {
WD_IMGBTN_LEFT = 1, WD_IMGBTN_RIGHT = 2, WD_IMGBTN_TOP = 1, WD_IMGBTN_BOTTOM = 2,
WD_INSET_LEFT = 2, WD_INSET_RIGHT = 2, WD_INSET_TOP = 1, WD_VSCROLLBAR_WIDTH = 12,
WD_HSCROLLBAR_HEIGHT = 12, WD_FRAMERECT_LEFT = 2, WD_FRAMERECT_RIGHT = 2, WD_FRAMERECT_TOP = 1,
WD_FRAMERECT_BOTTOM = 1, WD_TEXTPANEL_TOP = 6, WD_TEXTPANEL_BOTTOM = 6, WD_FRAMETEXT_LEFT = 6,
WD_FRAMETEXT_RIGHT = 6, WD_FRAMETEXT_TOP = 6, WD_FRAMETEXT_BOTTOM = 6, WD_MATRIX_LEFT = 2,
WD_MATRIX_RIGHT = 2, WD_MATRIX_TOP = 3, WD_MATRIX_BOTTOM = 1, WD_SHADEBOX_WIDTH = 12,
WD_SHADEBOX_LEFT = 2, WD_SHADEBOX_RIGHT = 2, WD_SHADEBOX_TOP = 3, WD_SHADEBOX_BOTTOM = 3,
WD_STICKYBOX_WIDTH = 12, WD_STICKYBOX_LEFT = 2, WD_STICKYBOX_RIGHT = 2, WD_STICKYBOX_TOP = 3,
WD_STICKYBOX_BOTTOM = 3, WD_RESIZEBOX_WIDTH = 12, WD_RESIZEBOX_LEFT = 3, WD_RESIZEBOX_RIGHT = 2,
WD_RESIZEBOX_TOP = 3, WD_RESIZEBOX_BOTTOM = 2, WD_CLOSEBOX_WIDTH = 11, WD_CLOSEBOX_LEFT = 2,
WD_CLOSEBOX_RIGHT = 1, WD_CLOSEBOX_TOP = 2, WD_CLOSEBOX_BOTTOM = 2, WD_CAPTION_HEIGHT = 14,
WD_CAPTIONTEXT_LEFT = 2, WD_CAPTIONTEXT_RIGHT = 2, WD_CAPTIONTEXT_TOP = 2, WD_CAPTIONTEXT_BOTTOM = 2,
WD_DROPDOWN_HEIGHT = 12, WD_DROPDOWNTEXT_LEFT = 2, WD_DROPDOWNTEXT_RIGHT = 14, WD_DROPDOWNTEXT_TOP = 1,
WD_DROPDOWNTEXT_BOTTOM = 1, WD_SORTBUTTON_ARROW_WIDTH = 11, WD_PAR_VSEP_NORMAL = 2, WD_PAR_VSEP_WIDE = 8
}

| Distances used in drawing widgets. More...
enum | WindowPosition { WDP_MANUAL, WDP_AUTO, WDP_CENTER, WDP_ALIGN_TOOLBAR }
| How do we the window to be placed? More...
enum | WindowDefaultFlag { WDF_CONSTRUCTION = 1 << 0, WDF_UNCLICK_BUTTONS = 1 << 1, WDF_MODAL = 1 << 2, WDF_NO_FOCUS = 1 << 3 }
| Window default widget/window handling flags. More...
enum | SortButtonState { SBS_OFF, SBS_DOWN, SBS_UP }
| State of a sort direction button. More...

enum

WindowFlags {
WF_TIMEOUT_TRIGGER = 1, WF_TIMEOUT_BEGIN = 7, WF_TIMEOUT_MASK = 7, WF_DRAGGING = 1 << 3,
WF_SCROLL_UP = 1 << 4, WF_SCROLL_DOWN = 1 << 5, WF_SCROLL_MIDDLE = 1 << 6, WF_SCROLL2 = 1 << 7,
WF_HSCROLL = 1 << 8, WF_SIZING_RIGHT = 1 << 9, WF_SIZING_LEFT = 1 << 10, WF_SIZING = WF_SIZING_RIGHT | WF_SIZING_LEFT,
WF_STICKY = 1 << 11, WF_DISABLE_VP_SCROLL = 1 << 12, WF_WHITE_BORDER_ONE = 1 << 13, WF_WHITE_BORDER_MASK = 1 << 14 | WF_WHITE_BORDER_ONE,
WF_CENTERED = 1 << 15
}

| Window flags. More...
enum | SpecialMouseMode { WSM_NONE = 0, WSM_DRAGDROP = 1, WSM_SIZING = 2, WSM_PRESIZE = 3 }

## Functions

| DECLARE_ENUM_AS_BIT_SET (FrameFlags)
void | DrawFrameRect (int left, int top, int right, int bottom, Colours colour, FrameFlags flags)
| Draw frame rectangle.
void | DrawCaption (const Rect &r, Colours colour, Owner owner, StringID str)
| Draw a caption bar.
Point | GetToolbarAlignedWindowPosition (int window_width)
| Computer the position of the top-left corner of a window to be opened right under the toolbar.
Window * | BringWindowToFrontById (WindowClass cls, WindowNumber number)
| Find a window and make it the top-window on the screen.
Window * | FindWindowFromPt (int x, int y)
| Do a search for a window at specific coordinates.
template<typename Wcls >
Wcls * | AllocateWindowDescFront (const WindowDesc *desc, int window_number)
| Open a new window.
void | RelocateAllWindows (int neww, int newh)
| Relocate all windows to fit the new size of the game application screen.
void | GuiShowTooltips (StringID str, uint paramcount=0, const uint64 params[]=NULL, bool use_left_mouse_button=false)
| Shows a tooltip.
int | GetWidgetFromPos (const Window *w, int x, int y)
| Returns the index for the widget located at the given position relative to the window.
Window * | GetCallbackWnd ()
void | SetFocusedWindow (Window *w)
| Set the window that has the focus.
bool | EditBoxInGlobalFocus ()
| Check if an edit box is in global focus.
void | ScrollbarClickHandler (Window *w, const NWidgetCore *nw, int x, int y)
| Special handling for the scrollbar widget type.

## Variables

Window * | _z_front_window
| List of windows opened at the screen sorted from the front.
Window * | _z_back_window
| List of windows opened at the screen sorted from the back.
Window * | _focused_window
Point | _cursorpos_drag_start
int | _scrollbar_start_pos
int | _scrollbar_size
byte | _scroller_click_timeout
bool | _scrolling_scrollbar
bool | _scrolling_viewport
byte | _special_mouse_mode

## Detailed Description

Functions, definitions and such used only by the GUI.

Definition in file window_gui.h.

## Enumeration Type Documentation

enum FrameFlags

Flags to describe the look of the frame.

Enumerator:

  FR_TRANSPARENT | Makes the background transparent if set.
  FR_BORDERONLY | Draw border only, no background.
  FR_LOWERED | If set the frame is lowered and the background colour brighter (ie. buttons when pressed).
  FR_DARKENED | If set the background is darker, allows for lowered frames with normal background colour when used with FR_LOWERED (ie. dropdown boxes).

Definition at line 25 of file window_gui.h.

enum SortButtonState

State of a sort direction button.

Enumerator:

  SBS_OFF | Do not sort (with this button).
  SBS_DOWN | Sort ascending.
  SBS_UP | Sort descending.

Definition at line 306 of file window_gui.h.

enum WidgetDrawDistances

Distances used in drawing widgets.

Enumerator:

  WD_IMGBTN_LEFT | Left offset of the image in the button.
  WD_IMGBTN_RIGHT | Right offset of the image in the button.
  WD_IMGBTN_TOP | Top offset of image in the button.
  WD_IMGBTN_BOTTOM | Bottom offset of image in the button.
  WD_INSET_LEFT | Left offset of string.
  WD_INSET_RIGHT | Right offset of string.
  WD_INSET_TOP | Top offset of string.
  WD_VSCROLLBAR_WIDTH | Width of a vertical scrollbar.
  WD_HSCROLLBAR_HEIGHT | Height of a horizontal scrollbar.
  WD_FRAMERECT_LEFT | Offset at left to draw the frame rectangular area.
  WD_FRAMERECT_RIGHT | Offset at right to draw the frame rectangular area.
  WD_FRAMERECT_TOP | Offset at top to draw the frame rectangular area.
  WD_FRAMERECT_BOTTOM | Offset at bottom to draw the frame rectangular area.
  WD_TEXTPANEL_TOP | Offset at top to draw above the text.
  WD_TEXTPANEL_BOTTOM | Offset at bottom to draw below the text.
  WD_FRAMETEXT_LEFT | Left offset of the text of the frame.
  WD_FRAMETEXT_RIGHT | Right offset of the text of the frame.
  WD_FRAMETEXT_TOP | Top offset of the text of the frame.
  WD_FRAMETEXT_BOTTOM | Bottom offset of the text of the frame.
  WD_MATRIX_LEFT | Offset at left of a matrix cell.
  WD_MATRIX_RIGHT | Offset at right of a matrix cell.
  WD_MATRIX_TOP | Offset at top of a matrix cell.
  WD_MATRIX_BOTTOM | Offset at bottom of a matrix cell.
  WD_SHADEBOX_WIDTH | Width of a standard shade box widget.
  WD_SHADEBOX_LEFT | Left offset of shade sprite.
  WD_SHADEBOX_RIGHT | Right offset of shade sprite.
  WD_SHADEBOX_TOP | Top offset of shade sprite.
  WD_SHADEBOX_BOTTOM | Bottom offset of shade sprite.
  WD_STICKYBOX_WIDTH | Width of a standard sticky box widget.
  WD_STICKYBOX_LEFT | Left offset of sticky sprite.
  WD_STICKYBOX_RIGHT | Right offset of sticky sprite.
  WD_STICKYBOX_TOP | Top offset of sticky sprite.
  WD_STICKYBOX_BOTTOM | Bottom offset of sticky sprite.
  WD_RESIZEBOX_WIDTH | Width of a resize box widget.
  WD_RESIZEBOX_LEFT | Left offset of resize sprite.
  WD_RESIZEBOX_RIGHT | Right offset of resize sprite.
  WD_RESIZEBOX_TOP | Top offset of resize sprite.
  WD_RESIZEBOX_BOTTOM | Bottom offset of resize sprite.
  WD_CLOSEBOX_WIDTH | Width of a close box widget.
  WD_CLOSEBOX_LEFT | Left offset of closebox string.
  WD_CLOSEBOX_RIGHT | Right offset of closebox string.
  WD_CLOSEBOX_TOP | Top offset of closebox string.
  WD_CLOSEBOX_BOTTOM | Bottom offset of closebox string.
  WD_CAPTION_HEIGHT | Height of a title bar.
  WD_CAPTIONTEXT_LEFT | Offset of the caption text at the left.
  WD_CAPTIONTEXT_RIGHT | Offset of the caption text at the right.
  WD_CAPTIONTEXT_TOP | Offset of the caption text at the top.
  WD_CAPTIONTEXT_BOTTOM | Offset of the caption text at the bottom.
  WD_DROPDOWN_HEIGHT | Height of a drop down widget.
  WD_DROPDOWNTEXT_LEFT | Left offset of the dropdown widget string.
  WD_DROPDOWNTEXT_RIGHT | Right offset of the dropdown widget string.
  WD_DROPDOWNTEXT_TOP | Top offset of the dropdown widget string.
  WD_DROPDOWNTEXT_BOTTOM | Bottom offset of the dropdown widget string.
  WD_SORTBUTTON_ARROW_WIDTH | Width of up/down arrow of sort button state.
  WD_PAR_VSEP_NORMAL | Normal amount of vertical space between two paragraphs of text.
  WD_PAR_VSEP_WIDE | Large amount of vertical space between two paragraphs of text.

Definition at line 36 of file window_gui.h.

enum WindowDefaultFlag

Window default widget/window handling flags.

Enumerator:

  WDF_CONSTRUCTION | This window is used for construction; close it whenever changing company.
  WDF_UNCLICK_BUTTONS | Unclick buttons when the window event times out.
  WDF_MODAL | The window is a modal child of some other window, meaning the parent is 'inactive'.
  WDF_NO_FOCUS | This window won't get focus/make any other window lose focus when click.

Definition at line 166 of file window_gui.h.

enum WindowFlags

Window flags.

Enumerator:

  WF_TIMEOUT_TRIGGER | When the timeout should start triggering.
  WF_TIMEOUT_BEGIN | The initial value for the timeout.
  WF_TIMEOUT_MASK | Window timeout counter bit mask (3 bits).
  WF_DRAGGING | Window is being dragged.

  WF_SCROLL_UP

  Upper scroll button has been pressed,.
  See also:
    ScrollbarClickHandler()

  WF_SCROLL_DOWN

  Lower scroll button has been pressed,.
  See also:
    ScrollbarClickHandler()

  WF_SCROLL_MIDDLE

  Scrollbar scrolling,.
  See also:
    ScrollbarClickHandler()

  WF_SIZING_RIGHT | Window is being resized towards the right.
  WF_SIZING_LEFT | Window is being resized towards the left.
  WF_SIZING | Window is being resized.
  WF_STICKY | Window is made sticky by user.

  WF_DISABLE_VP_SCROLL

  Window does not do autoscroll,.
  See also:
    HandleAutoscroll()

  WF_CENTERED | Window is centered and shall stay centered after ReInit.

Definition at line 827 of file window_gui.h.

enum WindowPosition

How do we the window to be placed?

Enumerator:

  WDP_MANUAL | Manually align the window (so no automatic location finding).
  WDP_AUTO | Find a place automatically.
  WDP_CENTER | Center the window.
  WDP_ALIGN_TOOLBAR | Align toward the toolbar.

Definition at line 133 of file window_gui.h.

## Function Documentation

template<typename Wcls >

Wcls* AllocateWindowDescFront | ( | const WindowDesc * | desc,
|  | int | window_number |
| ) |  |  | `[inline]`

Open a new window.

Parameters:

  | desc | The pointer to the WindowDesc to be created
  | window_number | the window number of the new window

Returns:
  see Window pointer of the newly created window

Definition at line 860 of file window_gui.h.

References BringWindowToFrontById(), and WindowDesc::cls.

Window* BringWindowToFrontById | ( | WindowClass | cls,
|  | WindowNumber | number |
| ) |  |  |

Find a window and make it the top-window on the screen.

The window gets unshaded if it was shaded, and a white border is drawn at its edges for a brief period of time to visualize its "activation".

Parameters:

  | cls | WindowClass of the window to activate
  | number | WindowNumber of the window to activate

Returns:
  a pointer to the window thus activated

Definition at line 762 of file window.cpp.

References BringWindowToFront(), FindWindowById(), Window::flags4, Window::IsShaded(), Window::SetDirty(), and Window::SetShaded().

Referenced by AllocateWindowDescFront(), DoSelectCompanyManagerFace(), NetworkContentListWindow::OnClick(), CompanyWindow::OnClick(), ShowCompanyFinances(), ShowDepotWindow(), ShowGenerateWorldProgress(), and ShowSelectBaseStationIfNeeded().

void DrawCaption | ( | const Rect & | r,
|  | Colours | colour,
|  | Owner | owner,
|  | StringID | str |
| ) |  |  |

Draw a caption bar.

Parameters:

  | r | Rectangle of the bar.
  | colour | Colour of the window.
  | owner | 'Owner' of the window.
  | str | Text to draw in the bar.

Definition at line 516 of file widget.cpp.

References _colour_gradient, _company_colours, DrawFrameRect(), DrawString(), FR_BORDERONLY, FR_DARKENED, FR_LOWERED, GfxFillRect(), INVALID_OWNER, SA_CENTER, WD_CAPTIONTEXT_LEFT, WD_CAPTIONTEXT_RIGHT, and WD_CAPTIONTEXT_TOP.

Referenced by NWidgetLeaf::Draw(), and NewsWindow::DrawWidget().

void DrawFrameRect | ( | int | left,
|  | int | top,
|  | int | right,
|  | int | bottom,
|  | Colours | colour,
|  | FrameFlags | flags |
| ) |  |  |

Draw frame rectangle.

Parameters:

  | left | Left edge of the frame
  | top | Top edge of the frame
  | right | Right edge of the frame
  | bottom | Bottom edge of the frame
  | colour | Colour table to use.

See also:
  _colour_gradient

Parameters:

  | flags | Flags controlling how to draw the frame.

See also:
  FrameFlags

Definition at line 200 of file widget.cpp.

References _colour_gradient, FILLRECT_RECOLOUR, FR_BORDERONLY, FR_DARKENED, FR_LOWERED, FR_TRANSPARENT, and GfxFillRect().

Referenced by NWidgetLeaf::Draw(), NWidgetBackground::Draw(), DrawAircraftImage(), DrawArrowButtons(), DrawButtonDropdown(), DrawCaption(), DrawCloseBox(), DrawHorizontalScrollbar(), DrawImageButtons(), DrawInset(), DrawMatrix(), DrawResizeBox(), DrawRoadVehImage(), SettingEntry::DrawSetting(), DrawShadeBox(), DrawShipImage(), DrawStickyBox(), DrawTrainImage(), DrawVerticalScrollbar(), TransparenciesWindow::DrawWidget(), NetworkJoinStatusWindow::DrawWidget(), NetworkContentDownloadStatusWindow::DrawWidget(), MusicWindow::DrawWidget(), GenerateProgressWindow::DrawWidget(), CheatWindow::DrawWidget(), AISettingsWindow::DrawWidget(), and Window::DrawWidgets().

bool EditBoxInGlobalFocus | ( |  | ) |

Check if an edit box is in global focus.

That is if focused window has a edit box as focused widget, or if a console is focused.

Returns:
  returns true if an edit box is in global focus or if the focused window is a console, else false

Definition at line 126 of file window.cpp.

References Window::nested_focus, NWidgetBase::type, Window::window_class, and WWT_EDITBOX.

Referenced by HandleKeypress(), and Window::InitializeData().

Window* FindWindowFromPt | ( | int | x,
|  | int | y |
| ) |  |  |

Do a search for a window at specific coordinates.

For this we start at the topmost window, obviously and work our way down to the bottom

Parameters:

  | x | position x to query
  | y | position y to query

Returns:
  a pointer to the found window if any, NULL otherwise

Definition at line 1260 of file window.cpp.

References Window::height, IsInsideBS(), Window::left, Window::top, and Window::width.

Referenced by HandleAutoscroll().

Point GetToolbarAlignedWindowPosition | ( | int | window_width | ) |

Computer the position of the top-left corner of a window to be opened right under the toolbar.

Parameters:

  | window_width | the width of the window to get the position for

Returns:
  Coordinate of the top-left corner of the new window.

Definition at line 1132 of file window.cpp.

References _dynlang, FindWindowById(), Window::height, Window::left, TD_RTL, DynamicLanguages::text_dir, Window::top, and Window::width.

Referenced by LocalGetWindowPlacement(), TransparenciesWindow::OnInitialPosition(), and TerraformToolbarWindow::OnInitialPosition().

int GetWidgetFromPos | ( | const Window * | w,
|  | int | x,
|  | int | y |
| ) |  |  |

Returns the index for the widget located at the given position relative to the window.

It includes all widget-corner pixels as well.

Parameters:

  | *w | Window to look inside
  | x | The Window client X coordinate
  | y | The Window client y coordinate

Returns:
  A widget index, or -1 if no widget was found.

Definition at line 185 of file widget.cpp.

References NWidgetBase::GetWidgetFromPos(), NWidgetCore::index, and Window::nested_root.

Referenced by DropdownWindow::GetDropDownItem(), and DropdownWindow::OnMouseLoop().

void GuiShowTooltips | ( | StringID | str,
|  | uint | paramcount,
|  | const uint64 | params[],
|  | bool | use_left_mouse_button |
| ) |  |  |

Shows a tooltip.

Parameters:

  | str | String to be displayed
  | paramcount | number of params to deal with
  | params | (optional) up to 5 pieces of additional information that may be added to a tooltip
  | use_left_mouse_button | close the tooltip when the left (true) or right (false) mousebutton is released

Definition at line 878 of file misc_gui.cpp.

References DeleteWindowById().

Referenced by DispatchRightClickEvent(), DepotWindow::OnRightClick(), and ShowMeasurementTooltips().

void RelocateAllWindows | ( | int | neww,
|  | int | newh |
| ) |  |  |

Relocate all windows to fit the new size of the game application screen.

Parameters:

  | neww | New width of the game application screen
  | newh | New height of the game appliction screen

Definition at line 2551 of file window.cpp.

References Clamp(), FindWindowById(), Window::flags4, Window::height, ViewPort::height, ViewPort::left, Window::left, min(), PositionMainToolbar(), ResizeWindow(), ScaleByZoom(), ViewPort::top, Window::top, Window::viewport, ViewPort::virtual_height, ViewPort::virtual_width, WF_CENTERED, Window::width, ViewPort::width, and Window::window_class.

Referenced by GameSizeChanged(), and ReInitAllWindows().

void ScrollbarClickHandler | ( | Window * | w,
|  | const NWidgetCore * | nw,
|  | int | x,
|  | int | y |
| ) |  |  |

Special handling for the scrollbar widget type.

Handles the special scrolling buttons and other scrolling.

Parameters:

  | w | Window on which a scroll was performed.
  | nw | Pointer to the scrollbar widget.
  | x | The X coordinate of the mouse click.
  | y | The Y coordinate of the mouse click.

Definition at line 150 of file widget.cpp.

References NWidgetBase::current_x, NWidgetBase::current_y, NWidgetBase::pos_x, NWidgetBase::pos_y, ScrollbarClickPositioning(), NWidgetBase::type, WWT_HSCROLLBAR, WWT_SCROLL2BAR, and WWT_SCROLLBAR.

Referenced by DispatchLeftClickEvent().

void SetFocusedWindow | ( | Window * | w | ) |

Set the window that has the focus.

Parameters:

  | w | The window to set the focus on

Definition at line 103 of file window.cpp.

References Window::nested_focus, Window::OnFocus(), Window::OnFocusLost(), and NWidgetBase::SetDirty().

Referenced by DispatchLeftClickEvent(), Window::InitializeData(), and OskWindow::OnClick().

## Variable Documentation

Window* _z_back_window

List of windows opened at the screen sorted from the back.

Definition at line 43 of file window.cpp.

Window* _z_front_window

List of windows opened at the screen sorted from the front.

Definition at line 41 of file window.cpp.