(svn r12619) -Codechange: lots of documentation about window related stuff. Patch by Alberth.

1 files changed, 126 insertions, 87 deletions

diff --git a/src/window_gui.h b/src/window_gui.h
index 0787e9cb4..990bed27b 100644
--- a/src/window_gui.h
+++ b/src/window_gui.h
@@ -73,6 +73,9 @@ 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
@@ -82,6 +85,9 @@ struct 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
@@ -92,21 +98,25 @@ enum FrameFlags {
 
 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_DESTROY,
-	WE_PAINT,
-	WE_KEYPRESS,
-	WE_CLICK,
-	WE_DOUBLE_CLICK,
-	WE_RCLICK,
+	WE_CREATE,       ///< Initialize the Window
+	WE_DESTROY,      ///< Prepare for deletion of the window
+	WE_PAINT,        ///< Repaint the window contents
+	WE_KEYPRESS,     ///< Key pressed
+	WE_CLICK,        ///< Left mouse button click
+	WE_DOUBLE_CLICK, ///< Left mouse button double click
+	WE_RCLICK,       ///< Right mouse button click
 	WE_MOUSEOVER,
 	WE_MOUSELOOP,
 	WE_MOUSEWHEEL,
-	WE_TICK,
-	WE_4,
+	WE_TICK,         ///< Regularly occurring event (about once every 20 seconds orso, 10 days) for slowly changing content (typically list sorting)
+	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,
@@ -119,13 +129,17 @@ enum WindowEventCodes {
 	WE_PLACE_MOUSEUP,
 	WE_PLACE_PRESIZE,
 	WE_DROPDOWN_SELECT,
-	WE_RESIZE,
-	WE_MESSAGE,
+	WE_RESIZE,          ///< Request to resize the window, @see WindowEvent.we.resize
+	WE_MESSAGE,         ///< Receipt of a message from another window. @see WindowEvent.we.message, SendWindowMessage(), SendWindowMessageClass()
 	WE_SCROLL,
-	WE_INVALIDATE_DATA,
-	WE_CTRL_CHANGED,
+	WE_INVALIDATE_DATA, ///< Notification that data displayed by the window is obsolete
+	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 {
@@ -200,27 +214,40 @@ struct WindowEvent {
 	} we;
 };
 
+/**
+ * High level window description
+ */
 struct WindowDesc {
-	int16 left, top, minimum_width, minimum_height, default_width, default_height;
-	WindowClass cls;
-	WindowClass parent_cls;
-	uint32 flags;
-	const Widget *widgets;
-	WindowProc *proc;
+	int16 left;             ///< Prefered x position of left edge of the window, @see WindowDefaultPosition()
+	int16 top;              ///< Prefered y position of the top of the window, @see WindowDefaultPosition()
+	int16 minimum_width;    ///< Minimal width of the window
+	int16 minimum_height;   ///< Minimal height of the window
+	int16 default_width;    ///< Prefered initial width of the window
+	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_STD_BTN         =   1 << 2, ///< default handling for close and drag widgets (widget no 0 and 1)
+	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 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)
@@ -230,46 +257,65 @@ enum WindowDefaultPosition {
 
 #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 height;
-	uint step_width; ///< In how big steps the width and height go
-	uint step_height;
+	uint width;       ///< Minimum allowed width of the window
+	uint height;      ///< Minimum allowed height of the window
+	uint step_width;  ///< Step-size of width resize changes
+	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;
-	WindowClass window_class;
-	WindowNumber window_number;
+	uint16 flags4;              ///< Window flags, @see WindowFlags
+	WindowClass window_class;   ///< Window class
+	WindowNumber window_number; ///< Window number within the window class
 
-	int left, top;
-	int width, height;
+	int left;   ///< x position of left edge of the window
+	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)
+	int height; ///< Height of the window (number of pixels down in y direction)
 
-	Scrollbar hscroll, vscroll, vscroll2;
-	ResizeInfo resize;
+	Scrollbar hscroll;  ///< Horizontal scroll bar
+	Scrollbar vscroll;  ///< First vertical scroll bar
+	Scrollbar vscroll2; ///< Second vertical scroll bar
+	ResizeInfo resize;  ///< Resize information
 
-	byte caption_color;
+	byte caption_color; ///< Background color of the window caption, contains PlayerID
 
-	WindowProc *wndproc;
-	ViewPort *viewport;
-	const Widget *original_widget;
-	Widget *widget;
-	uint widget_count;
-	uint32 desc_flags;
+	WindowProc *wndproc;   ///< Event handler function for the window
+	ViewPort *viewport;    ///< Pointer to viewport, if present (structure is part of derived class)
+	const Widget *original_widget; ///< Original widget layout, copied from WindowDesc
+	Widget *widget;        ///< Widgets of the window
+	uint widget_count;     ///< Number of widgets of the window
+	uint32 desc_flags;     ///< Window/widgets default flags setting, @see WindowDefaultFlag
 
-	WindowMessage message;
-	Window *parent;
-	byte custom[WINDOW_CUSTOM_SIZE];
+	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);
 
@@ -429,28 +475,31 @@ enum WindowWidgetBehaviours {
 };
 
 
+/**
+ * Window widget types
+ */
 enum WindowWidgetTypes {
-	WWT_EMPTY,
-
-	WWT_PANEL,      ///< simple depressed panel
-	WWT_INSET,      ///< pressed (inset) panel, most commonly used as combo box _text_ area
-	WWT_IMGBTN,     ///< button with image
-	WWT_IMGBTN_2,   ///< button with diff image when clicked
-
-	WWT_TEXTBTN,    ///< button with text
-	WWT_TEXTBTN_2,  ///< button with diff text when clicked
-	WWT_LABEL,      ///< centered label
-	WWT_TEXT,       ///< pure simple text
-	WWT_MATRIX,
-	WWT_SCROLLBAR,
-	WWT_FRAME,      ///< frame
-	WWT_CAPTION,
-
-	WWT_HSCROLLBAR,
-	WWT_STICKYBOX,
+	WWT_EMPTY,      ///< Empty widget, place holder to reserve space in widget array
+
+	WWT_PANEL,      ///< Simple depressed panel
+	WWT_INSET,      ///< Pressed (inset) panel, most commonly used as combo box _text_ area
+	WWT_IMGBTN,     ///< Button with image
+	WWT_IMGBTN_2,   ///< Button with diff image when clicked
+
+	WWT_TEXTBTN,    ///< Button with text
+	WWT_TEXTBTN_2,  ///< Button with diff text when clicked
+	WWT_LABEL,      ///< Centered label
+	WWT_TEXT,       ///< Pure simple text
+	WWT_MATRIX,     ///< List of items underneath each other
+	WWT_SCROLLBAR,  ///< Vertical scrollbar
+	WWT_FRAME,      ///< Frame
+	WWT_CAPTION,    ///< Window caption (window title between closebox and stickybox)
+
+	WWT_HSCROLLBAR, ///< Horizontal scrollbar
+	WWT_STICKYBOX,  ///< Sticky box (normally at top-right of a window)
 	WWT_SCROLL2BAR, ///< 2nd vertical scrollbar
-	WWT_RESIZEBOX,
-	WWT_CLOSEBOX,
+	WWT_RESIZEBOX,  ///< Resize box (normally at bottom-right of a window)
+	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)
@@ -465,18 +514,21 @@ enum WindowWidgetTypes {
 
 #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_MASK      = 7,
-	WF_DRAGGING          = 1 <<  3,
-	WF_SCROLL_UP         = 1 <<  4,
-	WF_SCROLL_DOWN       = 1 <<  5,
-	WF_SCROLL_MIDDLE     = 1 <<  6,
+	WF_TIMEOUT_SHL       = 0,       ///< Window timeout counter shift
+	WF_TIMEOUT_MASK      = 7,       ///< Window timeout counter bit mask (3 bits), @see WF_TIMEOUT_SHL
+	WF_DRAGGING          = 1 <<  3, ///< Window is being dragged
+	WF_SCROLL_UP         = 1 <<  4, ///< Upper scroll button has been pressed, @see ScrollbarClickHandler()
+	WF_SCROLL_DOWN       = 1 <<  5, ///< Lower scroll button has been pressed, @see ScrollbarClickHandler()
+	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,
@@ -487,11 +539,6 @@ enum WindowFlags {
 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);
@@ -582,16 +629,8 @@ enum SpecialMouseMode {
 
 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);