diff -r eec5a7dcbf61 -r fcf5fb2548eb src/window_gui.h --- a/src/window_gui.h Mon Apr 14 20:32:36 2008 +0000 +++ b/src/window_gui.h Tue Apr 15 00:47:19 2008 +0000 @@ -73,6 +73,9 @@ 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 @@ 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 @@ 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 @@ 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 @@ } 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 @@ #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; - - int left, top; - int width, height; - - Scrollbar hscroll, vscroll, vscroll2; - ResizeInfo resize; + uint16 flags4; ///< Window flags, @see WindowFlags + WindowClass window_class; ///< Window class + WindowNumber window_number; ///< Window number within the window class - byte caption_color; + 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) - WindowProc *wndproc; - ViewPort *viewport; - const Widget *original_widget; - Widget *widget; - uint widget_count; - uint32 desc_flags; + Scrollbar hscroll; ///< Horizontal scroll bar + Scrollbar vscroll; ///< First vertical scroll bar + Scrollbar vscroll2; ///< Second vertical scroll bar + ResizeInfo resize; ///< Resize information - WindowMessage message; - Window *parent; - byte custom[WINDOW_CUSTOM_SIZE]; + byte caption_color; ///< Background color of the window caption, contains PlayerID + + 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; ///< 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); @@ -331,19 +377,6 @@ }; 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; @@ -374,15 +407,6 @@ }; 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; @@ -392,16 +416,6 @@ }; 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; @@ -453,20 +467,6 @@ }; 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, @@ -475,30 +475,34 @@ }; +/** + * 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_EMPTY, ///< Empty widget, place holder to reserve space in widget array - 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_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_HSCROLLBAR, - WWT_STICKYBOX, + 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) WWT_LAST, ///< Last Item. use WIDGETS_END to fill up padding!! WWT_MASK = 0x1F, @@ -510,18 +514,21 @@ #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, @@ -532,11 +539,6 @@ 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); @@ -627,16 +629,8 @@ 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);