Mercurial > hg > openttd
changeset 8992:c0e03990caf0 draft
(svn r12787) -Documentation: add/fix documentation of some functions. Patch by Alberth.
author | rubidium <rubidium@openttd.org> |
---|---|
date | Sat, 19 Apr 2008 13:05:05 +0000 |
parents | 4a6bf04ea450 |
children | 1b2c82dc4d69 |
files | src/engine_func.h src/smallmap_gui.cpp src/sound.cpp src/station_gui.cpp src/viewport.cpp src/window.cpp src/zoom_func.h |
diffstat | 7 files changed, 71 insertions(+), 31 deletions(-) [+] |
line wrap: on
line diff
--- 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
--- a/src/smallmap_gui.cpp +++ b/src/smallmap_gui.cpp @@ -1108,7 +1108,7 @@ 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 @@ 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 @@ 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 @@ 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;
--- a/src/sound.cpp +++ b/src/sound.cpp @@ -207,6 +207,14 @@ } } +/** + * 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 @@ return; } } - } void SndPlayTileFx(SoundFx sound, TileIndex tile)
--- a/src/station_gui.cpp +++ b/src/station_gui.cpp @@ -184,35 +184,36 @@ 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); } /**
--- a/src/viewport.cpp +++ b/src/viewport.cpp @@ -158,6 +158,18 @@ 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 @@ } } - +/** + * 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 @@ } /** - * 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 @@ ); } +/** + * 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;
--- a/src/window.cpp +++ b/src/window.cpp @@ -303,6 +303,7 @@ } } + /* 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 @@ 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 @@ } /** - * 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 @@ } /** - * 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 @@ } } -/* +/** * 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 @@ } } -/* +/** * Mark all windows of a particular class as dirty (in need of repainting) * @param cls Window class */ @@ -2119,7 +2123,7 @@ } /** - * 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 */