openttd-ottdgrfs: comparison src/window

equal deleted inserted replaced

-:eec5a7dcbf61
+:fcf5fb2548eb
 enum {
 	WIDGET_LIST_END = -1, ///< indicate the end of widgets' list for vararg functions
 };
+/**
+* Window widget data structure
+*/
 struct Widget {
 	byte type;                        ///< Widget type, see WindowWidgetTypes
 	byte display_flags;               ///< Resize direction, alignment, etc. during resizing, see ResizeFlags
 	byte color;                       ///< Widget colour, see docs/ottd-colourtext-palette.png
 	int16 left, right, top, bottom;   ///< The position offsets inside the window
 	uint16 data;                      ///< The String/Image or special code (list-matrixes) of a widget
 	StringID tooltips;                ///< Tooltips that are shown when rightclicking on a widget
 };
+/**
+* Flags to describe the look of the frame
+*/
 enum FrameFlags {
 	FR_NONE         =  0,
 	FR_TRANSPARENT  =  1 << 0,  ///< Makes the background transparent if set
 	FR_BORDERONLY   =  1 << 4,  ///< Draw border only, no background
 	FR_LOWERED      =  1 << 5,  ///< If set the frame is lowered and the background color brighter (ie. buttons when pressed)
 	FR_DARKENED     =  1 << 6,  ///< If set the background is darker, allows for lowered frames with normal background color when used with FR_LOWERED (ie. dropdown boxes)
 };
 DECLARE_ENUM_AS_BIT_SET(FrameFlags);
+/* wiget.cpp */
 void DrawFrameRect(int left, int top, int right, int bottom, int color, FrameFlags flags);
+/**
+* Available window events
+*/
 enum WindowEventCodes {
-	WE_CREATE,
+	WE_CREATE,       ///< Initialize the Window
-	WE_DESTROY,
+	WE_DESTROY,      ///< Prepare for deletion of the window
-	WE_PAINT,
+	WE_PAINT,        ///< Repaint the window contents
-	WE_KEYPRESS,
+	WE_KEYPRESS,     ///< Key pressed
-	WE_CLICK,
+	WE_CLICK,        ///< Left mouse button click
-	WE_DOUBLE_CLICK,
+	WE_DOUBLE_CLICK, ///< Left mouse button double click
-	WE_RCLICK,
+	WE_RCLICK,       ///< Right mouse button click
 	WE_MOUSEOVER,
 	WE_MOUSELOOP,
 	WE_MOUSEWHEEL,
-	WE_TICK,
+	WE_TICK,         ///< Regularly occurring event (about once every 20 seconds orso, 10 days) for slowly changing content (typically list sorting)
-	WE_4,
+	WE_4,            ///< Regularly occurring event for updating continuously changing window content (other than view ports), or timer expiring
 	WE_TIMEOUT,
 	WE_PLACE_OBJ,
 	WE_ABORT_PLACE_OBJ,
 	WE_ON_EDIT_TEXT,
 	WE_ON_EDIT_TEXT_CANCEL,
 	WE_DRAGDROP,
 	WE_PLACE_DRAG,
 	WE_PLACE_MOUSEUP,
 	WE_PLACE_PRESIZE,
 	WE_DROPDOWN_SELECT,
-	WE_RESIZE,
+	WE_RESIZE,          ///< Request to resize the window, @see WindowEvent.we.resize
-	WE_MESSAGE,
+	WE_MESSAGE,         ///< Receipt of a message from another window. @see WindowEvent.we.message, SendWindowMessage(), SendWindowMessageClass()
 	WE_SCROLL,
-	WE_INVALIDATE_DATA,
+	WE_INVALIDATE_DATA, ///< Notification that data displayed by the window is obsolete
-	WE_CTRL_CHANGED,
+	WE_CTRL_CHANGED,    ///< CTRL key has changed state
 };
+/**
+* Data structures for additional data associated with a window event
+* @see WindowEventCodes
+*/
 struct WindowEvent {
 	byte event;
 	union {
 		struct {
 			void *data;
 			bool cont;     ///< continue the search? (default true)
 		} ctrl;
 	} we;
 };
+/**
+* High level window description
+*/
 struct WindowDesc {
-	int16 left, top, minimum_width, minimum_height, default_width, default_height;
+	int16 left;             ///< Prefered x position of left edge of the window, @see WindowDefaultPosition()
-	WindowClass cls;
+	int16 top;              ///< Prefered y position of the top of the window, @see WindowDefaultPosition()
-	WindowClass parent_cls;
+	int16 minimum_width;    ///< Minimal width of the window
-	uint32 flags;
+	int16 minimum_height;   ///< Minimal height of the window
-	const Widget *widgets;
+	int16 default_width;    ///< Prefered initial width of the window
-	WindowProc *proc;
+	int16 default_height;   ///< Prefered initial height of the window
-};
+	WindowClass cls;        ///< Class of the window, @see WindowClass
+	WindowClass parent_cls; ///< Class of the parent window, @see WindowClass
+	uint32 flags;           ///< Flags, @see WindowDefaultFlags
+	const Widget *widgets;  ///< List of widgets with their position and size for the window
+	WindowProc *proc;       ///< Window event handler function for the window
+};
+/**
+* Window default widget/window handling flags
+*/
 enum WindowDefaultFlag {
 	WDF_STD_TOOLTIPS    =   1 << 0, ///< use standard routine when displaying tooltips
-	WDF_DEF_WIDGET      =   1 << 1, ///< default widget control for some widgets in the on click event
+	WDF_DEF_WIDGET      =   1 << 1, ///< Default widget control for some widgets in the on click event, @see DispatchLeftClickEvent()
-	WDF_STD_BTN         =   1 << 2, ///< default handling for close and drag widgets (widget no 0 and 1)
+	WDF_STD_BTN         =   1 << 2, ///< Default handling for close and titlebar widgets (widget no 0 and 1)
-	WDF_UNCLICK_BUTTONS =   1 << 4, ///< Unclick buttons when the window event times out */
+	WDF_UNCLICK_BUTTONS =   1 << 4, ///< Unclick buttons when the window event times out
 	WDF_STICKY_BUTTON   =   1 << 5, ///< Set window to sticky mode; they are not closed unless closed with 'X' (widget 2)
-	WDF_RESIZABLE       =   1 << 6, ///< A window can be resized
+	WDF_RESIZABLE       =   1 << 6, ///< Window can be resized
 	WDF_MODAL           =   1 << 7, ///< The window is a modal child of some other window, meaning the parent is 'inactive'
 };
-/* can be used as x or y coordinates to cause a specific placement */
+/**
+* Special values for 'left' and 'top' to cause a specific placement
+*/
 enum WindowDefaultPosition {
 	WDP_AUTO      = -1, ///< Find a place automatically
 	WDP_CENTER    = -2, ///< Center the window (left/right or top/bottom)
 	WDP_ALIGN_TBR = -3, ///< Align the right side of the window with the right side of the main toolbar
 	WDP_ALIGN_TBL = -4, ///< Align the left side of the window with the left side of the main toolbar
 };
 #define WP(ptr, str) (*(str*)(ptr)->custom)
+/**
+* Scrollbar data structure
+*/
 struct Scrollbar {
-	uint16 count, cap, pos;
+	uint16 count;  ///< Number of elements in the list
-};
+	uint16 cap;    ///< Number of visible elements of the scroll bar
+	uint16 pos;
+};
+/**
+* Data structure for resizing a window
+*/
 struct ResizeInfo {
-	uint width; ///< Minimum width and height
+	uint width;       ///< Minimum allowed width of the window
-	uint height;
+	uint height;      ///< Minimum allowed height of the window
-	uint step_width; ///< In how big steps the width and height go
+	uint step_width;  ///< Step-size of width resize changes
-	uint step_height;
+	uint step_height; ///< Step-size of height resize changes
 };
+/**
+* Message data structure for messages sent between winodows
+* @see SendWindowMessageW()
+*/
 struct WindowMessage {
 	int msg;
 	int wparam;
 	int lparam;
 };
+/**
+* Data structure for an opened window
+*/
 struct Window {
-	uint16 flags4;
+	uint16 flags4;              ///< Window flags, @see WindowFlags
-	WindowClass window_class;
+	WindowClass window_class;   ///< Window class
-	WindowNumber window_number;
+	WindowNumber window_number; ///< Window number within the window class
-	int left, top;
+	int left;   ///< x position of left edge of the window
-	int width, height;
+	int top;    ///< y position of top edge of the window
+	int width;  ///< width of the window (number of pixels to the right in x direction)
-	Scrollbar hscroll, vscroll, vscroll2;
+	int height; ///< Height of the window (number of pixels down in y direction)
-	ResizeInfo resize;
+	Scrollbar hscroll;  ///< Horizontal scroll bar
-	byte caption_color;
+	Scrollbar vscroll;  ///< First vertical scroll bar
+	Scrollbar vscroll2; ///< Second vertical scroll bar
-	WindowProc *wndproc;
+	ResizeInfo resize;  ///< Resize information
-	ViewPort *viewport;
-	const Widget *original_widget;
+	byte caption_color; ///< Background color of the window caption, contains PlayerID
-	Widget *widget;
-	uint widget_count;
+	WindowProc *wndproc;   ///< Event handler function for the window
-	uint32 desc_flags;
+	ViewPort *viewport;    ///< Pointer to viewport, if present (structure is part of derived class)
+	const Widget *original_widget; ///< Original widget layout, copied from WindowDesc
-	WindowMessage message;
+	Widget *widget;        ///< Widgets of the window
-	Window *parent;
+	uint widget_count;     ///< Number of widgets of the window
-	byte custom[WINDOW_CUSTOM_SIZE];
+	uint32 desc_flags;     ///< Window/widgets default flags setting, @see WindowDefaultFlag
+	WindowMessage message; ///< Buffer for storing received messages (for communication between different window events)
+	Window *parent;        ///< Parent window
+	byte custom[WINDOW_CUSTOM_SIZE]; ///< Additional data depending on window type
 	void HandleButtonClick(byte widget);
 	void SetWidgetDisabledState(byte widget_index, bool disab_stat);
 	void DisableWidget(byte widget_index);
 	byte paramcount;
 	uint64 params[5];
 };
 assert_compile(WINDOW_CUSTOM_SIZE >= sizeof(tooltips_d));
-struct replaceveh_d {
-	byte sel_index[2];
-	EngineID sel_engine[2];
-	uint16 count[2];
-	bool wagon_btnstate; ///< true means engine is selected
-	EngineList list[2];
-	bool update_left;
-	bool update_right;
-	bool init_lists;
-	GroupID sel_group;
-};
-assert_compile(WINDOW_CUSTOM_SIZE >= sizeof(replaceveh_d));
 struct depot_d {
 	VehicleID sel;
 	VehicleType type;
 	bool generate_list;
 	uint16 engine_list_length;
 	int32 scroll_y;
 	int32 subscroll;
 };
 assert_compile(WINDOW_CUSTOM_SIZE >= sizeof(smallmap_d));
-struct refit_d {
-	int sel;
-	struct RefitOption *cargo;
-	struct RefitList *list;
-	uint length;
-	VehicleOrderID order;
-};
-assert_compile(WINDOW_CUSTOM_SIZE >= sizeof(refit_d));
 struct vp_d {
 	VehicleID follow_vehicle;
 	int32 scrollpos_x;
 	int32 scrollpos_y;
 	int32 dest_scrollpos_x;
 	int32 dest_scrollpos_y;
 };
 assert_compile(WINDOW_CUSTOM_SIZE >= sizeof(vp_d));
-struct news_d {
-	uint16 follow_vehicle;
-	int32 scrollpos_x;
-	int32 scrollpos_y;
-	int32 dest_scrollpos_x;
-	int32 dest_scrollpos_y;
-	NewsItem *ni;
-};
-assert_compile(WINDOW_CUSTOM_SIZE >= sizeof(news_d));
 struct highscore_d {
 	uint32 background_img;
 	int8 rank;
 };
 assert_compile(WINDOW_CUSTOM_SIZE >= sizeof(highscore_d));
 	VehicleType vehicle_type;   // The vehicle type that is sorted
 	list_d l;                   // General list struct
 };
 assert_compile(WINDOW_CUSTOM_SIZE >= sizeof(vehiclelist_d));
-struct grouplist_d {
-	const Group **sort_list;
-	list_d l;                   // General list struct
-};
-assert_compile(WINDOW_CUSTOM_SIZE >= sizeof(grouplist_d));
-struct groupveh_d : vehiclelist_d {
-	GroupID group_sel;
-	VehicleID vehicle_sel;
-	grouplist_d gl;
-};
-assert_compile(WINDOW_CUSTOM_SIZE >= sizeof(groupveh_d));
 /****************** THESE ARE NOT WIDGET TYPES!!!!! *******************/
 enum WindowWidgetBehaviours {
 	WWB_PUSHBUTTON  = 1 << 5,
 	WWB_MASK        = 0xE0,
 };
+/**
+* Window widget types
+*/
 enum WindowWidgetTypes {
-	WWT_EMPTY,
+	WWT_EMPTY,      ///< Empty widget, place holder to reserve space in widget array
-	WWT_PANEL,      ///< simple depressed panel
+	WWT_PANEL,      ///< Simple depressed panel
-	WWT_INSET,      ///< pressed (inset) panel, most commonly used as combo box _text_ area
+	WWT_INSET,      ///< Pressed (inset) panel, most commonly used as combo box _text_ area
-	WWT_IMGBTN,     ///< button with image
+	WWT_IMGBTN,     ///< Button with image
-	WWT_IMGBTN_2,   ///< button with diff image when clicked
+	WWT_IMGBTN_2,   ///< Button with diff image when clicked
-	WWT_TEXTBTN,    ///< button with text
+	WWT_TEXTBTN,    ///< Button with text
-	WWT_TEXTBTN_2,  ///< button with diff text when clicked
+	WWT_TEXTBTN_2,  ///< Button with diff text when clicked
-	WWT_LABEL,      ///< centered label
+	WWT_LABEL,      ///< Centered label
-	WWT_TEXT,       ///< pure simple text
+	WWT_TEXT,       ///< Pure simple text
-	WWT_MATRIX,
+	WWT_MATRIX,     ///< List of items underneath each other
-	WWT_SCROLLBAR,
+	WWT_SCROLLBAR,  ///< Vertical scrollbar
-	WWT_FRAME,      ///< frame
+	WWT_FRAME,      ///< Frame
-	WWT_CAPTION,
+	WWT_CAPTION,    ///< Window caption (window title between closebox and stickybox)
-	WWT_HSCROLLBAR,
+	WWT_HSCROLLBAR, ///< Horizontal scrollbar
-	WWT_STICKYBOX,
+	WWT_STICKYBOX,  ///< Sticky box (normally at top-right of a window)
 	WWT_SCROLL2BAR, ///< 2nd vertical scrollbar
-	WWT_RESIZEBOX,
+	WWT_RESIZEBOX,  ///< Resize box (normally at bottom-right of a window)
-	WWT_CLOSEBOX,
+	WWT_CLOSEBOX,   ///< Close box (at top-left of a window)
 	WWT_DROPDOWN,   ///< Raised drop down list (regular)
 	WWT_DROPDOWNIN, ///< Inset drop down list (used on game options only)
+	WWT_EDITBOX,    ///< a textbox for typing (don't forget to call ShowOnScreenKeyboard() when clicked)
 	WWT_LAST,       ///< Last Item. use WIDGETS_END to fill up padding!!
 	WWT_MASK = 0x1F,
 	WWT_PUSHBTN     = WWT_PANEL   | WWB_PUSHBUTTON,
 	WWT_PUSHIMGBTN  = WWT_IMGBTN  | WWB_PUSHBUTTON,
 };
 #define WIDGETS_END WWT_LAST,   RESIZE_NONE,     0,     0,     0,     0,     0, 0, STR_NULL
+/**
+* Window flags
+*/
 enum WindowFlags {
-	WF_TIMEOUT_SHL       = 0,
+	WF_TIMEOUT_SHL       = 0,       ///< Window timeout counter shift
-	WF_TIMEOUT_MASK      = 7,
+	WF_TIMEOUT_MASK      = 7,       ///< Window timeout counter bit mask (3 bits), @see WF_TIMEOUT_SHL
-	WF_DRAGGING          = 1 <<  3,
+	WF_DRAGGING          = 1 <<  3, ///< Window is being dragged
-	WF_SCROLL_UP         = 1 <<  4,
+	WF_SCROLL_UP         = 1 <<  4, ///< Upper scroll button has been pressed, @see ScrollbarClickHandler()
-	WF_SCROLL_DOWN       = 1 <<  5,
+	WF_SCROLL_DOWN       = 1 <<  5, ///< Lower scroll button has been pressed, @see ScrollbarClickHandler()
-	WF_SCROLL_MIDDLE     = 1 <<  6,
+	WF_SCROLL_MIDDLE     = 1 <<  6, ///< Scrollbar scrolling, @see ScrollbarClickHandler()
 	WF_HSCROLL           = 1 <<  7,
 	WF_SIZING            = 1 <<  8,
-	WF_STICKY            = 1 <<  9,
+	WF_STICKY            = 1 <<  9, ///< Window is made sticky by user
-	WF_DISABLE_VP_SCROLL = 1 << 10,
+	WF_DISABLE_VP_SCROLL = 1 << 10, ///< Window does not do autoscroll, @see HandleAutoscroll()
 	WF_WHITE_BORDER_ONE  = 1 << 11,
 	WF_WHITE_BORDER_MASK = 1 << 12 | WF_WHITE_BORDER_ONE,
 	WF_SCROLL2           = 1 << 13,
 };
 /* window.cpp */
 void CallWindowEventNP(Window *w, int event);
 void CallWindowTickEvent();
-/**
-* Marks the window as dirty for repaint.
-*
-* @ingroup dirty
-*/
 void SetWindowDirty(const Window *w);
 void SendWindowMessage(WindowClass wnd_class, WindowNumber wnd_num, int msg, int wparam, int lparam);
 void SendWindowMessageClass(WindowClass wnd_class, int msg, int wparam, int lparam);
 Window *FindWindowById(WindowClass cls, WindowNumber number);
 	WSM_PRESIZE  = 3,
 };
 void ScrollbarClickHandler(Window *w, const Widget *wi, int x, int y);
-/** Evenly distribute some widgets when resizing horizontally (often a button row)
-*  The widgets are presumed to be in a line and numberef from left to right (without gaps)
-* @param w widow to modify
-* @param left The leftmost widget to resize
-* @param right The rightmost widget to resize. Since right side of it is used, remember to set it to RESIZE_RIGHT
-*/
 void ResizeButtons(Window *w, byte left, byte right);
-/** Resize a widget an shuffle other widgets around to fit.
-*/
 void ResizeWindowForWidget(Window *w, int widget, int delta_x, int delta_y);
 /**
 * Sets the enabled/disabled status of a widget.

branch	NewGRF_ports
changeset 10184	fcf5fb2548eb
parent 6878	7d1ff2f621c7
child 10200	aba3af04cdbd