From c84fe27ca9ece2909a8b0f01d10f1e9704f9d8ae Mon Sep 17 00:00:00 2001 From: rubidium Date: Sat, 19 Apr 2008 13:05:05 +0000 Subject: (svn r12787) -Documentation: add/fix documentation of some functions. Patch by Alberth. --- src/engine_func.h | 2 +- src/smallmap_gui.cpp | 8 ++++---- src/sound.cpp | 9 ++++++++- src/station_gui.cpp | 25 +++++++++++++------------ src/viewport.cpp | 40 ++++++++++++++++++++++++++++++++++------ src/window.cpp | 16 ++++++++++------ src/zoom_func.h | 2 +- 7 files changed, 71 insertions(+), 31 deletions(-) diff --git a/src/engine_func.h b/src/engine_func.h index 7b5cac1d5..387cf5552 100644 --- a/src/engine_func.h +++ b/src/engine_func.h @@ -1,6 +1,6 @@ /* $Id$ */ -/** @file engine.h */ +/** @file engine_func.h */ #ifndef ENGINE_H #define ENGINE_H diff --git a/src/smallmap_gui.cpp b/src/smallmap_gui.cpp index e4caa9837..6430c7798 100644 --- a/src/smallmap_gui.cpp +++ b/src/smallmap_gui.cpp @@ -1108,7 +1108,7 @@ static const Widget _extra_view_port_widgets[] = { static void ExtraViewPortWndProc(Window *w, WindowEvent *e) { switch (e->event) { - case WE_CREATE: /* Disable zoom in button */ + case WE_CREATE: // Disable zoom in button /* New viewport start at (zero,zero) */ AssignWindowViewport(w, 3, 17, w->widget[4].right - w->widget[4].left - 1, w->widget[4].bottom - w->widget[4].top - 1, 0, ZOOM_LVL_VIEWPORT); @@ -1116,7 +1116,7 @@ static void ExtraViewPortWndProc(Window *w, WindowEvent *e) break; case WE_PAINT: - // set the number in the title bar + /* set the number in the title bar */ SetDParam(0, w->window_number + 1); DrawWindowWidgets(w); @@ -1128,7 +1128,7 @@ static void ExtraViewPortWndProc(Window *w, WindowEvent *e) case 5: DoZoomInOutWindow(ZOOM_IN, w); break; case 6: DoZoomInOutWindow(ZOOM_OUT, w); break; - case 7: { /* location button (move main view to same spot as this view) 'Paste Location' */ + case 7: { // location button (move main view to same spot as this view) 'Paste Location' Window *w2 = FindWindowById(WC_MAIN_WINDOW, 0); int x = WP(w, vp_d).scrollpos_x; // Where is the main looking at int y = WP(w, vp_d).scrollpos_y; @@ -1138,7 +1138,7 @@ static void ExtraViewPortWndProc(Window *w, WindowEvent *e) WP(w2, vp_d).dest_scrollpos_y = y - (w2->viewport->virtual_height - w->viewport->virtual_height) / 2; } break; - case 8: { /* inverse location button (move this view to same spot as main view) 'Copy Location' */ + case 8: { // inverse location button (move this view to same spot as main view) 'Copy Location' const Window *w2 = FindWindowById(WC_MAIN_WINDOW, 0); int x = WP(w2, const vp_d).scrollpos_x; int y = WP(w2, const vp_d).scrollpos_y; diff --git a/src/sound.cpp b/src/sound.cpp index c5daccae4..a9c0cb801 100644 --- a/src/sound.cpp +++ b/src/sound.cpp @@ -207,6 +207,14 @@ void SndCopyToPool() } } +/** + * Decide 'where' (between left and right speaker) to play the sound effect. + * @param sound Sound effect to play + * @param left Left edge of virtual coordinates where the sound is produced + * @param right Right edge of virtual coordinates where the sound is produced + * @param top Top edge of virtual coordinates where the sound is produced + * @param bottom Bottom edge of virtual coordinates where the sound is produced + */ static void SndPlayScreenCoordFx(SoundFx sound, int left, int right, int top, int bottom) { Window* const *wz; @@ -231,7 +239,6 @@ static void SndPlayScreenCoordFx(SoundFx sound, int left, int right, int top, in return; } } - } void SndPlayTileFx(SoundFx sound, TileIndex tile) diff --git a/src/station_gui.cpp b/src/station_gui.cpp index 033fad74a..64e993e30 100644 --- a/src/station_gui.cpp +++ b/src/station_gui.cpp @@ -184,35 +184,36 @@ struct plstations_d { assert_compile(WINDOW_CUSTOM_SIZE >= sizeof(plstations_d)); /** - * Set the 'SL_REBUILD' flag for all station lists + * Set the station sort flag for all station-list windows. + * @param sl_flag Sort list flag to set for all station-list windows */ -void RebuildStationLists() +static void SetStationListsFlag(StationListFlags sl_flag) { Window *const *wz; FOR_ALL_WINDOWS(wz) { Window *w = *wz; if (w->window_class == WC_STATION_LIST) { - WP(w, plstations_d).flags |= SL_REBUILD; + WP(w, plstations_d).flags |= sl_flag; SetWindowDirty(w); } } } +/** + * Set the 'SL_REBUILD' flag for all station lists + */ +void RebuildStationLists() +{ + SetStationListsFlag(SL_REBUILD); +} + /** * Set the 'SL_RESORT' flag for all station lists */ void ResortStationLists() { - Window *const *wz; - - FOR_ALL_WINDOWS(wz) { - Window *w = *wz; - if (w->window_class == WC_STATION_LIST) { - WP(w, plstations_d).flags |= SL_RESORT; - SetWindowDirty(w); - } - } + SetStationListsFlag(SL_RESORT); } /** diff --git a/src/viewport.cpp b/src/viewport.cpp index ad9e140d7..582943b64 100644 --- a/src/viewport.cpp +++ b/src/viewport.cpp @@ -158,6 +158,18 @@ void DeleteWindowViewport(Window *w) w->viewport = NULL; } +/** + * Initialize viewport of the window for use. + * @param w Window to use/display the viewport in + * @param x Offset of left edge of viewport with respect to left edge window \a w + * @param y Offset of top edge of viewport with respect to top edge window \a w + * @param width Width of the viewport + * @param height Height of the viewport + * @param follow_flags Flags controlling the viewport. + * - If bit 31 is set, the lower 16 bits are the vehicle that the viewport should follow. + * - If bit 31 is clear, it is a tile position. + * @param zoom Zoomlevel to display + */ void AssignWindowViewport(Window *w, int x, int y, int width, int height, uint32 follow_flags, ZoomLevel zoom) { @@ -324,7 +336,14 @@ static void SetViewportPosition(Window *w, int x, int y) } } - +/** + * Is a xy position inside the viewport of the window? + * @param w Window to examine its viewport + * @param x X coordinate of the xy position + * @param y Y coordinate of the xy position + * @return Pointer to the viewport if the xy position is in the viewport of the window, + * otherwise \c NULL is returned. + */ ViewPort *IsPtInWindowViewport(const Window *w, int x, int y) { ViewPort *vp = w->viewport; @@ -1591,11 +1610,12 @@ void UpdateViewportPosition(Window *w) } /** - * Marks a viewport as dirty for repaint. - * - * @param vp The viewport to mark as dirty - * @todo documents the missing parameters @c left, @c top, @c right and @c bottom - * @todo detailed description missing + * Marks a viewport as dirty for repaint if it displays (a part of) the area the needs to be repainted. + * @param vp The viewport to mark as dirty + * @param left Left edge of area to repaint + * @param top Top edge of area to repaint + * @param right Right edge of area to repaint + * @param bottom Bottom edge of area to repaint * @ingroup dirty */ static void MarkViewportDirty(const ViewPort *vp, int left, int top, int right, int bottom) @@ -1622,6 +1642,14 @@ static void MarkViewportDirty(const ViewPort *vp, int left, int top, int right, ); } +/** + * Mark all viewports that display an area as dirty (in need of repaint). + * @param left Left edge of area to repaint + * @param top Top edge of area to repaint + * @param right Right edge of area to repaint + * @param bottom Bottom edge of area to repaint + * @ingroup dirty + */ void MarkAllViewportsDirty(int left, int top, int right, int bottom) { Window **wz; diff --git a/src/window.cpp b/src/window.cpp index 46b0883e7..efb8cdadd 100644 --- a/src/window.cpp +++ b/src/window.cpp @@ -303,6 +303,7 @@ static void DrawOverlappedWindow(Window* const *wz, int left, int top, int right } } + /* Setup blitter, and dispatch a repaint event to window *wz */ DrawPixelInfo *dp = _cur_dpi; dp->width = right - left; dp->height = bottom - top; @@ -334,6 +335,7 @@ void DrawOverlappedWindowForAll(int left, int top, int right, int bottom) bottom > w->top && left < w->left + w->width && top < w->top + w->height) { + /* Window w intersects with the rectangle => needs repaint */ DrawOverlappedWindow(wz, left, top, right, bottom); } } @@ -398,7 +400,8 @@ Window **FindWindowZPosition(const Window *w) } /** - * Remove window and all its child windows from the window stack + * Remove window and all its child windows from the window stack. + * @param w Window to delete */ void DeleteWindow(Window *w) { @@ -2064,8 +2067,9 @@ int GetMenuItemIndex(const Window *w, int x, int y) } /** - * Mark window data as invalid (in need of re-computing) - * @param w Window with invalid data + * Mark window as dirty (in need of repainting) + * @param cls Window class + * @param number Window number in that class */ void InvalidateWindow(WindowClass cls, WindowNumber number) { @@ -2077,7 +2081,7 @@ 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 @@ -2095,7 +2099,7 @@ 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 */ @@ -2119,7 +2123,7 @@ void InvalidateThisWindowData(Window *w) } /** - * Mark window data the window of a given class and specific window number as invalid (in need of re-computing) + * Mark window data of 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 */ diff --git a/src/zoom_func.h b/src/zoom_func.h index 50dc4dfa3..c6cc51861 100644 --- a/src/zoom_func.h +++ b/src/zoom_func.h @@ -1,6 +1,6 @@ /* $Id$ */ -/** @file zoom_func.hpp */ +/** @file zoom_func.h */ #ifndef ZOOM_FUNC_H #define ZOOM_FUNC_H -- cgit v1.2.3-54-g00ecf