diff options
| -rw-r--r-- | src/gfx.cpp | 8 | ||||
| -rw-r--r-- | src/main_gui.cpp | 4 | ||||
| -rw-r--r-- | src/sound.cpp | 4 | ||||
| -rw-r--r-- | src/station_gui.cpp | 2 | ||||
| -rw-r--r-- | src/viewport_type.h | 17 | ||||
| -rw-r--r-- | src/widget.cpp | 5 | ||||
| -rw-r--r-- | src/widgets/dropdown.cpp | 4 | ||||
| -rw-r--r-- | src/window.cpp | 204 | ||||
| -rw-r--r-- | src/window_func.h | 5 | ||||
| -rw-r--r-- | src/window_gui.h | 213 |
10 files changed, 332 insertions, 134 deletions
diff --git a/src/gfx.cpp b/src/gfx.cpp index 734ae590c..5f3faeea0 100644 --- a/src/gfx.cpp +++ b/src/gfx.cpp @@ -28,10 +28,10 @@ CursorVars _cursor; bool _ctrl_pressed; ///< Is Ctrl pressed? bool _shift_pressed; ///< Is Shift pressed? byte _fast_forward; -bool _left_button_down; -bool _left_button_clicked; -bool _right_button_down; -bool _right_button_clicked; +bool _left_button_down; ///< Is left mouse button pressed? +bool _left_button_clicked; ///< Is left mouse button clicked? +bool _right_button_down; ///< Is right mouse button pressed? +bool _right_button_clicked; ///< Is right mouse button clicked? DrawPixelInfo _screen; bool _screen_disable_anim = false; ///< Disable palette animation (important for 32bpp-anim blitter during giant screenshot) bool _exit_game; diff --git a/src/main_gui.cpp b/src/main_gui.cpp index 027f29130..4e5be4d98 100644 --- a/src/main_gui.cpp +++ b/src/main_gui.cpp @@ -1214,6 +1214,10 @@ void ShowVitalWindows() WP(w, def_d).data_1 = -1280; } +/** + * Size of the application screen changed. + * Adapt the game screen-size, re-allocate the open windows, and repaint everything + */ void GameSizeChanged() { _cur_resolution[0] = _screen.width; diff --git a/src/sound.cpp b/src/sound.cpp index 9fed4a689..c5daccae4 100644 --- a/src/sound.cpp +++ b/src/sound.cpp @@ -197,9 +197,7 @@ static const byte _sound_idx[] = { void SndCopyToPool() { - uint i; - - for (i = 0; i < _file_count; i++) { + for (uint i = 0; i < _file_count; i++) { FileEntry *orig = &_files[_sound_idx[i]]; FileEntry *fe = AllocateFileEntry(); diff --git a/src/station_gui.cpp b/src/station_gui.cpp index b28f96211..b949476ea 100644 --- a/src/station_gui.cpp +++ b/src/station_gui.cpp @@ -388,7 +388,7 @@ static void PlayerStationsWndProc(Window *w, WindowEvent *e) assert(st->xy != 0); - /* Do not do the complex check HasStationInUse here, it may be even false + /* Do not do the complex check HasStationInUse here, it may be even false * when the order had been removed and the station list hasn't been removed yet */ assert(st->owner == owner || (st->owner == OWNER_NONE && !st->IsBuoy())); diff --git a/src/viewport_type.h b/src/viewport_type.h index 55504ebb6..f43566fbb 100644 --- a/src/viewport_type.h +++ b/src/viewport_type.h @@ -10,12 +10,19 @@ #include "window_type.h" #include "tile_type.h" +/** + * Data structure for viewport, display of a part of the world + */ struct ViewPort { - int left,top; // screen coordinates for the viewport - int width, height; // screen width/height for the viewport + int left; ///< Screen coordinate left egde of the viewport + int top; ///< Screen coordinate top edge of the viewport + int width; ///< Screen width of the viewport + int height; ///< Screen height of the viewport - int virtual_left, virtual_top; // virtual coordinates - int virtual_width, virtual_height; // these are just width << zoom, height << zoom + int virtual_left; ///< Virtual left coordinate + int virtual_top; ///< Virtual top coordinate + int virtual_width; ///< width << zoom + int virtual_height; ///< height << zoom ZoomLevel zoom; }; @@ -58,7 +65,7 @@ enum ViewportHighlightMode { VHM_RAIL = 5, ///< rail pieces }; -/* highlighting draw styles */ +/** Highlighting draw styles */ enum HighLightStyle { HT_NONE = 0x00, HT_RECT = 0x80, diff --git a/src/widget.cpp b/src/widget.cpp index bca66bdc5..38bfe98d3 100644 --- a/src/widget.cpp +++ b/src/widget.cpp @@ -186,6 +186,10 @@ void DrawFrameRect(int left, int top, int right, int bottom, int ctab, FrameFlag } +/** + * Paint all widgets of a window. + * @param w Window + */ void DrawWindowWidgets(const Window *w) { const DrawPixelInfo* dpi = _cur_dpi; @@ -569,6 +573,7 @@ void ResizeButtons(Window *w, byte left, byte right) } } +/** Resize a widget and shuffle other widgets around to fit. */ void ResizeWindowForWidget(Window *w, int widget, int delta_x, int delta_y) { int right = w->widget[widget].right; diff --git a/src/widgets/dropdown.cpp b/src/widgets/dropdown.cpp index 225140e9e..89e336a58 100644 --- a/src/widgets/dropdown.cpp +++ b/src/widgets/dropdown.cpp @@ -313,6 +313,10 @@ void ShowDropDownMenu(Window *w, const StringID *strings, int selected, int butt ShowDropDownList(w, list, selected, button); } +/** + * Delete the drop-down menu from window \a pw + * @param pw Parent window of the drop-down menu window + */ void HideDropDownMenu(Window *pw) { Window **wz; diff --git a/src/window.cpp b/src/window.cpp index 035d2bf92..28c2c1a36 100644 --- a/src/window.cpp +++ b/src/window.cpp @@ -22,10 +22,16 @@ #include "table/sprites.h" -/* delta between mouse cursor and upper left corner of dragged window */ +/** delta between mouse cursor and upper left corner of dragged window */ static Point _drag_delta; static Window _windows[MAX_NUMBER_OF_WINDOWS]; + +/** + * List of windows opened at the screen. + * Uppermost window is at _z_windows[_last_z_window - 1], + * bottom window is at _z_windows[0] + */ Window *_z_windows[lengthof(_windows)]; Window **_last_z_window; ///< always points to the next free space in the z-array @@ -116,6 +122,13 @@ void Window::HandleButtonClick(byte widget) static void StartWindowDrag(Window *w); static void StartWindowSizing(Window *w); +/** + * Dispatch left mouse-button (possibly double) click in window. + * @param w Window to dispatch event in + * @param x X coordinate of the click + * @param y Y coordinate of the click + * @param double_click Was it a double click? + */ static void DispatchLeftClickEvent(Window *w, int x, int y, bool double_click) { WindowEvent e; @@ -175,6 +188,12 @@ static void DispatchLeftClickEvent(Window *w, int x, int y, bool double_click) w->wndproc(w, &e); } +/** + * Dispatch right mouse-button click in window. + * @param w Window to dispatch event in + * @param x X coordinate of the click + * @param y Y coordinate of the click + */ static void DispatchRightClickEvent(Window *w, int x, int y) { WindowEvent e; @@ -197,9 +216,10 @@ static void DispatchRightClickEvent(Window *w, int x, int y) w->wndproc(w, &e); } -/** Dispatch the mousewheel-action to the window which will scroll any - * compatible scrollbars if the mouse is pointed over the bar or its contents - * @param *w Window +/** + * Dispatch the mousewheel-action to the window. + * The window will scroll any compatible scrollbars if the mouse is pointed over the bar or its contents + * @param w Window * @param widget the widget where the scrollwheel was used * @param wheel scroll up or down */ @@ -232,6 +252,14 @@ static void DispatchMouseWheelEvent(Window *w, int widget, int wheel) static void DrawOverlappedWindow(Window* const *wz, int left, int top, int right, int bottom); +/** + * From a rectangle that needs redrawing, find the windows that intersect with the rectangle. + * These windows should be re-painted. + * @param left Left edge of the rectangle that should be repainted + * @param top Top edge of the rectangle that should be repainted + * @param right Right edge of the rectangle that should be repainted + * @param bottom Bottom edge of the rectangle that should be repainted + */ void DrawOverlappedWindowForAll(int left, int top, int right, int bottom) { Window* const *wz; @@ -249,10 +277,23 @@ void DrawOverlappedWindowForAll(int left, int top, int right, int bottom) } } +/** + * Generate repaint events for the visible part of window *wz within the rectangle. + * + * The function goes recursively upwards in the window stack, and splits the rectangle + * into multiple pieces at the window edges, so obscured parts are not redrawn. + * + * @param wz Pointer into window stack, pointing at the window that needs to be repainted + * @param left Left edge of the rectangle that should be repainted + * @param top Top edge of the rectangle that should be repainted + * @param right Right edge of the rectangle that should be repainted + * @param bottom Bottom edge of the rectangle that should be repainted + * + * @todo Swap this function to above DrawOverlappedWindowForAll() to eliminate the forward declaration + */ static void DrawOverlappedWindow(Window* const *wz, int left, int top, int right, int bottom) { Window* const *vz = wz; - int x; while (++vz != _last_z_window) { const Window *v = *vz; @@ -261,6 +302,9 @@ static void DrawOverlappedWindow(Window* const *wz, int left, int top, int right bottom > v->top && left < v->left + v->width && top < v->top + v->height) { + /* v and rectangle intersect with eeach other */ + int x; + if (left < (x = v->left)) { DrawOverlappedWindow(wz, left, top, x, bottom); DrawOverlappedWindow(wz, x, top, right, bottom); @@ -302,6 +346,12 @@ static void DrawOverlappedWindow(Window* const *wz, int left, int top, int right } } +/** + * Dispatch an event to a possibly non-existing window. + * If the window pointer w is \c NULL, the event is not dispatched + * @param w Window to dispatch the event to, may be \c NULL + * @param event Event to dispatch + */ void CallWindowEventNP(Window *w, int event) { WindowEvent e; @@ -310,6 +360,11 @@ void CallWindowEventNP(Window *w, int event) w->wndproc(w, &e); } +/** + * Mark entire window as dirty (in need of re-paint) + * @param w Window to redraw + * @ingroup dirty + */ void SetWindowDirty(const Window *w) { if (w == NULL) return; @@ -334,12 +389,13 @@ static Window *FindChildWindow(const Window *w) /** Find the z-value of a window. A window must already be open * or the behaviour is undefined but function should never fail * @param w window to query Z Position - * @return the window that matches it */ + * @return Pointer into the window-list at the position of \a w + */ Window **FindWindowZPosition(const Window *w) { Window **wz; - for (wz = _z_windows; wz != _last_z_window; wz++) { + FOR_ALL_WINDOWS(wz) { if (*wz == w) return wz; } @@ -348,14 +404,15 @@ Window **FindWindowZPosition(const Window *w) return NULL; } +/** + * Remove window and all its child windows from the window stack + */ void DeleteWindow(Window *w) { - Window *v; - Window **wz; if (w == NULL) return; /* Delete any children a window might have in a head-recursive manner */ - v = FindChildWindow(w); + Window *v = FindChildWindow(w); if (v != NULL) DeleteWindow(v); if (_thd.place_mode != VHM_NONE && @@ -375,12 +432,18 @@ void DeleteWindow(Window *w) /* Find the window in the z-array, and effectively remove it * by moving all windows after it one to the left */ - wz = FindWindowZPosition(w); + Window **wz = FindWindowZPosition(w); if (wz == NULL) return; memmove(wz, wz + 1, (byte*)_last_z_window - (byte*)wz); _last_z_window--; } +/** + * Find a window by its class and window number + * @param cls Window class + * @param number Number of the window within the window class + * @return Pointer to the found window, or \c NULL if not available + */ Window *FindWindowById(WindowClass cls, WindowNumber number) { Window* const *wz; @@ -393,11 +456,20 @@ Window *FindWindowById(WindowClass cls, WindowNumber number) return NULL; } +/** + * Delete a window by its class and window number (if it is open). + * @param cls Window class + * @param number Number of the window within the window class + */ void DeleteWindowById(WindowClass cls, WindowNumber number) { DeleteWindow(FindWindowById(cls, number)); } +/** + * Delete all windows of a given class + * @param cls Window class of windows to delete + */ void DeleteWindowByClass(WindowClass cls) { Window* const *wz; @@ -625,9 +697,8 @@ static Window *FindFreeWindow() * @param window_number number being assigned to the new window * @param data the data to be given during the WE_CREATE message * @return Window pointer of the newly created window */ -static Window *LocalAllocateWindow( - int x, int y, int min_width, int min_height, int def_width, int def_height, - WindowProc *proc, WindowClass cls, const Widget *widget, int window_number, void *data) +static Window *LocalAllocateWindow(int x, int y, int min_width, int min_height, int def_width, int def_height, + WindowProc *proc, WindowClass cls, const Widget *widget, int window_number, void *data) { Window *w = FindFreeWindow(); @@ -751,18 +822,14 @@ static Window *LocalAllocateWindow( * @param *proc see WindowProc function to call when any messages/updates happen to the window * @param cls see WindowClass class of the window, used for identification and grouping * @param *widget see Widget pointer to the window layout and various elements - * @return Window pointer of the newly created window */ -Window *AllocateWindow( - int x, int y, int width, int height, - WindowProc *proc, WindowClass cls, const Widget *widget, void *data) + * @return Window pointer of the newly created window + */ +Window *AllocateWindow(int x, int y, int width, int height, + WindowProc *proc, WindowClass cls, const Widget *widget, void *data) { return LocalAllocateWindow(x, y, width, height, width, height, proc, cls, widget, 0, data); } -struct SizeRect { - int left,top,width,height; -}; - static bool IsGoodAutoPlace1(int left, int top, int width, int height, Point &pos) { @@ -1002,7 +1069,7 @@ void UnInitWindowSystem() restart_search: /* Delete all windows, reset z-array. - *When we find the window to delete, we need to restart the search + * When we find the window to delete, we need to restart the search * as deleting this window could cascade in deleting (many) others * anywhere in the z-array. We call DeleteWindow() so that it can properly * release own alloc'd memory, which otherwise could result in memleaks */ @@ -1158,12 +1225,15 @@ static bool HandleMouseOver() return true; } -/** Update all the widgets of a window based on their resize flags +/** + * Resize the window. + * Update all the widgets of a window based on their resize flags * Both the areas of the old window and the new sized window are set dirty * ensuring proper redrawal. * @param w Window to resize * @param x delta x-size of changed window (positive if larger, etc.) - * @param y delta y-size of changed window */ + * @param y delta y-size of changed window + */ void ResizeWindow(Window *w, int x, int y) { Widget *wi; @@ -1409,6 +1479,10 @@ static bool HandleWindowDragging() return false; } +/** + * Start window dragging + * @param w Window to start dragging + */ static void StartWindowDrag(Window *w) { w->flags4 |= WF_DRAGGING; @@ -1421,6 +1495,10 @@ static void StartWindowDrag(Window *w) DeleteWindowById(WC_DROPDOWN_MENU, 0); } +/** + * Start resizing a window + * @param w Window to start resizing + */ static void StartWindowSizing(Window *w) { w->flags4 |= WF_SIZING; @@ -1632,11 +1710,10 @@ void SendWindowMessageClass(WindowClass wnd_class, int msg, int wparam, int lpar } /** Handle keyboard input. - * @param key Lower 8 bits contain the ASCII character, the higher - * 16 bits the keycode */ + * @param key Lower 8 bits contain the ASCII character, the higher 16 bits the keycode + */ void HandleKeypress(uint32 key) { - Window* const *wz; WindowEvent e; /* Stores if a window with a textfield for typing is open * If this is the case, keypress events are only passed to windows with text fields and @@ -1685,7 +1762,7 @@ void HandleKeypress(uint32 key) } /* Call the event, start with the uppermost window. */ - for (wz = _last_z_window; wz != _z_windows;) { + for (Window* const *wz = _last_z_window; wz != _z_windows;) { Window *w = *--wz; /* if a query window is open, only call the event for certain window types */ @@ -1709,6 +1786,9 @@ void HandleKeypress(uint32 key) } } +/** + * State of CONTROL key has changed + */ void HandleCtrlChanged() { WindowEvent e; @@ -1727,8 +1807,18 @@ void HandleCtrlChanged() extern void UpdateTileSelection(); extern bool VpHandlePlaceSizingDrag(); +/** + * Local counter that is incremented each time an mouse input event is detected. + * The counter is used to stop auto-scrolling. + * @see HandleAutoscroll() + * @see HandleMouseEvents() + */ static int _input_events_this_tick = 0; +/** + * If needed and switched on, perform auto scrolling (automatically + * moving window contents when mouse is near edge of the window). + */ static void HandleAutoscroll() { Window *w; @@ -1870,6 +1960,9 @@ void MouseLoop(MouseClick click, int mousewheel) } } +/** + * Handle a mouse event from the video driver + */ void HandleMouseEvents() { static int double_click_time = 0; @@ -1919,12 +2012,18 @@ void HandleMouseEvents() MouseLoop(click, mousewheel); } +/** + * Regular call from the global game loop + */ void InputLoop() { HandleMouseEvents(); HandleAutoscroll(); } +/** + * Update the continuously changing contents of the windows, such as the viewports + */ void UpdateWindows() { Window* const *wz; @@ -1959,6 +2058,13 @@ void UpdateWindows() } +/** + * In a window with menu_d custom extension, retrieve the menu item number from a position + * @param w Window holding the menu items + * @param x X coordinate of the position + * @param y Y coordinate of the position + * @return Index number of the menu item, or \c -1 if no valid selection under position + */ int GetMenuItemIndex(const Window *w, int x, int y) { if ((x -= w->left) >= 0 && x < w->width && (y -= w->top + 1) >= 0) { @@ -1972,6 +2078,10 @@ int GetMenuItemIndex(const Window *w, int x, int y) return -1; } +/** + * Mark window data as invalid (in need of re-computing) + * @param w Window with invalid data + */ void InvalidateWindow(WindowClass cls, WindowNumber number) { Window* const *wz; @@ -1982,6 +2092,12 @@ void InvalidateWindow(WindowClass cls, WindowNumber number) } } +/* + * Mark a particular widget in a particular window as dirty (in need of repainting) + * @param cls Window class + * @param number Window number in that class + * @param widget_index Index number of the widget that needs repainting + */ void InvalidateWindowWidget(WindowClass cls, WindowNumber number, byte widget_index) { Window* const *wz; @@ -1994,6 +2110,10 @@ void InvalidateWindowWidget(WindowClass cls, WindowNumber number, byte widget_in } } +/* + * Mark all windows of a particular class as dirty (in need of repainting) + * @param cls Window class + */ void InvalidateWindowClasses(WindowClass cls) { Window* const *wz; @@ -2003,12 +2123,21 @@ void InvalidateWindowClasses(WindowClass cls) } } +/** + * Mark window data as invalid (in need of re-computing) + * @param w Window with invalid data + */ void InvalidateThisWindowData(Window *w) { CallWindowEventNP(w, WE_INVALIDATE_DATA); SetWindowDirty(w); } +/** + * Mark window data the window of a given class and specific window number as invalid (in need of re-computing) + * @param cls Window class + * @param number Window number within the class + */ void InvalidateWindowData(WindowClass cls, WindowNumber number) { Window* const *wz; @@ -2019,6 +2148,10 @@ void InvalidateWindowData(WindowClass cls, WindowNumber number) } } +/** + * Mark window data of all windows of a given class as invalid (in need of re-computing) + * @param cls Window class + */ void InvalidateWindowClassesData(WindowClass cls) { Window* const *wz; @@ -2028,6 +2161,9 @@ void InvalidateWindowClassesData(WindowClass cls) } } +/** + * Dispatch WE_TICK event over all windows + */ void CallWindowTickEvent() { Window* const *wz; @@ -2093,6 +2229,11 @@ void HideVitalWindows() DeleteWindowById(WC_STATUS_BAR, 0); } +/** + * (Re)position main toolbar window at the screen + * @param w Window structure of the main toolbar window, may also be \c NULL + * @return X coordinate of left edge of the repositioned toolbar window + */ int PositionMainToolbar(Window *w) { DEBUG(misc, 5, "Repositioning Main Toolbar..."); @@ -2110,6 +2251,11 @@ int PositionMainToolbar(Window *w) return w->left; } +/** + * Relocate all windows to fit the new size of the game application screen + * @param neww New width of the game application screen + * @param newh New height of the game appliction screen + */ void RelocateAllWindows(int neww, int newh) { Window* const *wz; diff --git a/src/window_func.h b/src/window_func.h index 4bdcad3cd..9b6b6f66c 100644 --- a/src/window_func.h +++ b/src/window_func.h @@ -8,11 +8,6 @@ #include "window_type.h" #include "player_type.h" -/** - * 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); 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); |