[Scummvm-cvs-logs] SF.net SVN: scummvm: [29394] scummvm/trunk/gui

lordhoto at users.sourceforge.net lordhoto at users.sourceforge.net
Sun Nov 4 01:30:54 CET 2007


Revision: 29394
          http://scummvm.svn.sourceforge.net/scummvm/?rev=29394&view=rev
Author:   lordhoto
Date:     2007-11-03 17:30:53 -0700 (Sat, 03 Nov 2007)

Log Message:
-----------
- starting to document the theme renderer
- Theme::closeDialog -> Theme::closeAllDialogs, since it would remove every dialog currently

Modified Paths:
--------------
    scummvm/trunk/gui/ThemeClassic.cpp
    scummvm/trunk/gui/ThemeClassic.h
    scummvm/trunk/gui/ThemeModern.cpp
    scummvm/trunk/gui/ThemeModern.h
    scummvm/trunk/gui/newgui.cpp
    scummvm/trunk/gui/theme.h

Modified: scummvm/trunk/gui/ThemeClassic.cpp
===================================================================
--- scummvm/trunk/gui/ThemeClassic.cpp	2007-11-03 23:59:54 UTC (rev 29393)
+++ scummvm/trunk/gui/ThemeClassic.cpp	2007-11-04 00:30:53 UTC (rev 29394)
@@ -134,7 +134,7 @@
 #endif
 }
 
-void ThemeClassic::closeDialog() {
+void ThemeClassic::closeAllDialogs() {
 #ifndef CT_NO_TRANSPARENCY
 	if (_dialog) {
 		_dialog->screen.free();
@@ -153,7 +153,7 @@
 	_system->grabOverlay((OverlayColor*)_screen.pixels, _screen.w);
 }
 
-void ThemeClassic::drawAll() {
+void ThemeClassic::updateScreen() {
 	_forceRedraw = false;
 }
 

Modified: scummvm/trunk/gui/ThemeClassic.h
===================================================================
--- scummvm/trunk/gui/ThemeClassic.h	2007-11-03 23:59:54 UTC (rev 29393)
+++ scummvm/trunk/gui/ThemeClassic.h	2007-11-04 00:30:53 UTC (rev 29394)
@@ -46,10 +46,10 @@
 	void disable();
 
 	void openDialog(bool topDialog);
-	void closeDialog();
+	void closeAllDialogs();
 
 	void clearAll();
-	void drawAll();
+	void updateScreen();
 	
 	void resetDrawArea();
 

Modified: scummvm/trunk/gui/ThemeModern.cpp
===================================================================
--- scummvm/trunk/gui/ThemeModern.cpp	2007-11-03 23:59:54 UTC (rev 29393)
+++ scummvm/trunk/gui/ThemeModern.cpp	2007-11-04 00:30:53 UTC (rev 29394)
@@ -211,7 +211,7 @@
 		addDirtyRect(Common::Rect(0, 0, _screen.w, _screen.h), false, false);
 }
 
-void ThemeModern::closeDialog() {
+void ThemeModern::closeAllDialogs() {
 	if (_dialog) {
 		_dialog->screen.free();
 		delete _dialog;
@@ -228,7 +228,7 @@
 	_system->grabOverlay((OverlayColor*)_screen.pixels, _screen.w);
 }
 
-void ThemeModern::drawAll() {
+void ThemeModern::updateScreen() {
 	// TODO: see ThemeModern::addDirtyRect
 	_forceRedraw = false;
 }

Modified: scummvm/trunk/gui/ThemeModern.h
===================================================================
--- scummvm/trunk/gui/ThemeModern.h	2007-11-03 23:59:54 UTC (rev 29393)
+++ scummvm/trunk/gui/ThemeModern.h	2007-11-04 00:30:53 UTC (rev 29394)
@@ -41,16 +41,16 @@
 
 	void refresh();
 
-	bool ownCursor() { return _useCursor; }
+	bool ownCursor() const { return _useCursor; }
 
 	void enable();
 	void disable();
 	
 	void openDialog(bool topDialog);
-	void closeDialog();
+	void closeAllDialogs();
 
 	void clearAll();
-	void drawAll();
+	void updateScreen();
 	
 	void setDrawArea(const Common::Rect &r);
 	void resetDrawArea();

Modified: scummvm/trunk/gui/newgui.cpp
===================================================================
--- scummvm/trunk/gui/newgui.cpp	2007-11-03 23:59:54 UTC (rev 29393)
+++ scummvm/trunk/gui/newgui.cpp	2007-11-04 00:30:53 UTC (rev 29394)
@@ -184,9 +184,10 @@
 	// This is necessary to get the blending right.
 	_theme->clearAll();
 
-	for (i = 0; i < _dialogStack.size(); ++i) {
-		_theme->closeDialog();
-	}
+	_theme->closeAllDialogs();
+	//for (i = 0; i < _dialogStack.size(); ++i)
+	//	_theme->closeDialog();
+
 	for (i = 0; i < _dialogStack.size(); i++) {
 		// Special treatment when topmost dialog has dimsInactive() set to false
 		// This is the case for PopUpWidget which should not dim a dialog
@@ -201,7 +202,7 @@
 		_dialogStack[i]->drawDialog();
 	}
 
-	_theme->drawAll();
+	_theme->updateScreen();
 }
 
 Dialog *NewGui::getTopDialog() const {
@@ -243,7 +244,7 @@
 
 		if (_useStdCursor)
 			animateCursor();
-		_theme->drawAll();
+		_theme->updateScreen();
 		_system->updateScreen();
 
 		Common::Event event;
@@ -321,7 +322,10 @@
 		_system->delayMillis(10);
 	}
 
-	_theme->closeDialog();
+	// HACK: since we reopen all dialogs anyway on redraw
+	// we for now use Theme::closeAllDialogs here, until
+	// we properly add (and implement) Theme::closeDialog
+	_theme->closeAllDialogs();
 
 	if (didSaveState) {
 		_theme->disable();

Modified: scummvm/trunk/gui/theme.h
===================================================================
--- scummvm/trunk/gui/theme.h	2007-11-03 23:59:54 UTC (rev 29393)
+++ scummvm/trunk/gui/theme.h	2007-11-04 00:30:53 UTC (rev 29394)
@@ -40,62 +40,74 @@
 
 class Eval;
 
-// Hints to the theme engine that the widget is used in a non-standard way.
-
-enum {
-	// Indicates that this is the first time the widget is drawn.
+//! Hint to the theme engine that the widget is used in a non-standard way.
+enum ThemeHint {
+	//! Indicates that this is the first time the widget is drawn.
 	THEME_HINT_FIRST_DRAW = 1 << 0,
 
-	// Indicates that the widget will be redrawn often, e.g. list widgets.
-	// It may therefore be a good idea to save the background so that it
-	// can be redrawn quickly.
+	/**
+	 * Indicates that the widget will be redrawn often, e.g. list widgets.
+	 * It may therefore be a good idea to save the background so that it
+	 * can be redrawn quickly.
+	 */
 	THEME_HINT_SAVE_BACKGROUND = 1 << 1,
 
-	// Indicates that this is the launcher dialog (maybe delete this in the future)
+	//! Indicates that this is the launcher dialog (maybe delete this in the future)
 	THEME_HINT_MAIN_DIALOG = 1 << 2,
 
-	// Indicates special colorfade
+	//! Indicates special colorfade
 	THEME_HINT_SPECIAL_COLOR = 1 << 3,
 
-	// Indicates no colorfade
+	//! Indicates no colorfade
 	THEME_HINT_PLAIN_COLOR = 1 << 4,
 
-	// Indictaes that a shadows should be drawn around the background
+	//! Indictaes that a shadows should be drawn around the background
 	THEME_HINT_USE_SHADOW = 1 << 5,
 
-	// Indicates that no background should be restored when drawing the widget
-	// (note that this can be silently ignored if for example the theme does
-	// alpha blending and would blend over a allready drawn widget)
-	// TODO: currently only ThemeModern::drawButton supports this
+	/**
+	 * Indicates that no background should be restored when drawing the widget
+	 * (note that this can be silently ignored if for example the theme does
+	 * alpha blending and would blend over a allready drawn widget)
+	 * TODO: currently only ThemeModern::drawButton supports this
+	 */
 	THEME_HINT_NO_BACKGROUND_RESTORE = 1 << 6
 };
 
-
+/**
+ * Our theme renderer class.
+ *
+ * It is used to draw the different widgets and
+ * getting the layout of the widgets for different
+ * resolutions.
+ */
 class Theme {
 public:
 	Theme();
 
 	virtual ~Theme();
 
+	//! Defined the align of the text
 	enum TextAlign {
-		kTextAlignLeft,
-		kTextAlignCenter,
-		kTextAlignRight
+		kTextAlignLeft,		//! Text should be aligned to the left
+		kTextAlignCenter,	//! Text should be centered
+		kTextAlignRight		//! Text should be aligned to the right
 	};
 
+	//! Widget background type
 	enum WidgetBackground {
-		kWidgetBackgroundNo,
-		kWidgetBackgroundPlain,
-		kWidgetBackgroundBorder,
-		kWidgetBackgroundBorderSmall,
-		kWidgetBackgroundEditText,
-		kWidgetBackgroundSlider
+		kWidgetBackgroundNo,			//! No background at all
+		kWidgetBackgroundPlain,			//! Simple background, this may not include borders
+		kWidgetBackgroundBorder,		//! Same as kWidgetBackgroundPlain just with a border
+		kWidgetBackgroundBorderSmall,	//! Same as kWidgetBackgroundPlain just with a small border
+		kWidgetBackgroundEditText,		//! Background used for edit text fields
+		kWidgetBackgroundSlider			//! Background used for sliders
 	};
 
+	//! State of the widget to be drawn
 	enum State {
-		kStateDisabled,
-		kStateEnabled,
-		kStateHighlight
+		kStateDisabled,	//! Indicates that the widget is disabled, that does NOT include that it is invisible
+		kStateEnabled,	//! Indicates that the widget is enabled
+		kStateHighlight	//! Indicates that the widget is highlighted by the user
 	};
 
 	enum ScrollbarState {
@@ -106,43 +118,159 @@
 		kScrollbarStateSinglePage
 	};
 
+	//! Font style selector
 	enum FontStyle {
-		kFontStyleBold = 0,	// standard font
-		kFontStyleNormal = 1,
-		kFontStyleItalic = 2,
-		kFontStyleFixedNormal = 3,
-		kFontStyleFixedBold = 4,
-		kFontStyleFixedItalic = 5,
+		kFontStyleBold = 0,			//! A bold font. This is also the default font.
+		kFontStyleNormal = 1,		//! A normal font.
+		kFontStyleItalic = 2,		//! Italic styled font.
+		kFontStyleFixedNormal = 3,	//! Fixed size font.
+		kFontStyleFixedBold = 4,	//! Fixed size bold font.
+		kFontStyleFixedItalic = 5,	//! Fixed size italic font.
 		kFontStyleMax
 	};
 
+	//! Function used to process areas other than the current dialog
 	enum ShadingStyle {
-		kShadingNone,
-		kShadingDim,
-		kShadingLuminance
+		kShadingNone,		//! No special post processing
+		kShadingDim,		//! Dimming unsued areas
+		kShadingLuminance	//! Converting colors to luminance for unsued areas
 	};
 
+	/**
+	 * This initalizes all the data needed by the theme renderer.
+	 * It should just be called *once*, when first using the renderer.
+	 *
+	 * Other functions of the renderer should just be used after
+	 * calling this function, else the result is undefined.
+	 *
+	 * If used again it should just be used after deinit,
+	 * if there is need to use the renderer again.
+	 *
+	 * @see deinit
+	 */
 	virtual bool init() = 0;
+
+	/**
+	 * Unloads all data used by the theme renderer.
+	 */
 	virtual void deinit() = 0;
 
+	/**
+	 * Updates the renderer to changes to resolution,
+	 * bit depth and other video related configuration.
+	 */
 	virtual void refresh() = 0;
 
-	virtual bool ownCursor() { return false; }
+	/**
+	 * Checks if the theme supplies its own cursor.
+	 *
+	 * @return true if using an own cursor
+	 */
+	virtual bool ownCursor() const { return false; }
 
+	/**
+	 * Enables the theme renderer for use.
+	 *
+	 * This for examples shows up the overlay, clears the
+	 * renderers temporary screen buffers and does other
+	 * things to make the renderer for use. 
+	 *
+	 * This may NOT back up the data on the overlay.
+	 * So if you got data in the overlay save it before
+	 * calling this.
+	 *
+	 * As a difference to init, this makes the renderer
+	 * ready to draw something to the screen. And of course
+	 * it relies on the data loaded by init.
+	 *
+	 * @see disable
+	 * @see init
+	 */
 	virtual void enable() = 0;
+
+	/**
+	 * Disables the theme renderer.
+	 *
+	 * This for example hides the overlay and undoes
+	 * other things done by enable.
+	 *
+	 * As a difference to uninit, this just makes the
+	 * renderer unable to do any screen drawing, but
+	 * still keeps all data loaded into memory.
+	 *
+	 * @see enable
+	 * @see uninit
+	 */
 	virtual void disable() = 0;
 
+	/**
+	 * Tells the theme renderer that a new dialog is opened.
+	 *
+	 * This can be used for internal caching and marking
+	 * area of all but the not top dialog in a special way.
+	 *
+	 * TODO: This needs serious reworking, since at least for
+	 * normal usage, a dialog opened with openDialog should always
+	 * be the top dialog. Currently our themes have no good enough
+	 * implementation to handle a single open dialog though, so we
+	 * have to stay this way until we implement proper dialog
+	 * 'caching'/handling.
+	 *
+	 * @param topDialog	if true it indicates that this is the top dialog
+	 *
+	 * @see closeAllDialogs
+	 */
 	virtual void openDialog(bool topDialog) = 0;
-	virtual void closeDialog() = 0;
 
+	/**
+	 * This indicates that all dialogs have been closed.
+	 *
+	 * @see openDialog
+	 */
+	virtual void closeAllDialogs() = 0;
+
+	/**
+	 * Clear the complete GUI screen.
+	 */
 	virtual void clearAll() = 0;
-	virtual void drawAll() = 0;
 
+	/**
+	 * Update the GUI screen aka overlay.
+	 *
+	 * This does NOT call OSystem::updateScreen,
+	 * it just copies all (changed) data to the overlay.
+	 */
+	virtual void updateScreen() = 0;
+
+	/**
+	 * Set the active screen area, in which the renderer is able to
+	 * draw.
+	 *
+	 * This does not affect the coordinates for the draw* functions,
+	 * it just markes the screen rect given in param r as writeable.
+	 *
+	 * This is for example used in the credits dialog, which, if not
+	 * just a part of the screen would be marked as writebale, would
+	 * draw parts of the scrolling text outside the dialog box and
+	 * thus would look strange.
+	 *
+	 * The active area defaults to the whole screen, so there is just
+	 * need to use this function if you want to limit it.
+	 *
+	 * @param r	rect of the screen, which should be writeable
+	 *
+	 * @see resetDrawArea
+	 */
 	virtual void setDrawArea(const Common::Rect &r) { _drawArea = r; }
-	// resets the draw area to the screen size
+
+	/**
+	 * Resets the draw area to the whole screen.
+	 *
+	 * @see setDrawArea
+	 */
 	virtual void resetDrawArea() = 0;
 
-	virtual const Common::ConfigFile &getConfigFile() { return _configFile; }
+	virtual const Common::ConfigFile &getConfigFile() const { return _configFile; }
 
 	virtual const Graphics::Font *getFont(FontStyle font = kFontStyleBold) const = 0;
 	virtual int getFontHeight(FontStyle font = kFontStyleBold) const = 0;
@@ -218,12 +346,26 @@
 	const Common::String &getStylefileName() const { return _stylefile; }
 	const Common::String &getThemeName() const { return _stylename; }
 
+	/**
+	 * Checks if the theme renderer suppots drawing of images.
+	 *
+	 * @return true on support, else false
+	 */
 	virtual bool supportsImages() const { return false; }
 
+	//! Special image ids for images used in the GUI
 	enum kThemeImages {
-		kImageLogo = 0
+		kImageLogo = 0		//! ScummVM Logo used in the launcher
 	};
 
+	/**
+	 * Returns the given image.
+	 *
+	 * @param n	id of the image, see kThemeImages
+	 * @return 0 if no such image exists for the theme, else pointer to the image
+	 *
+	 * @see kThemeImages
+	 */
 	virtual const Graphics::Surface *getImageSurface(const kThemeImages n) const { return 0; }
 protected:
 	bool loadConfigFile(const Common::String &file);


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.




More information about the Scummvm-git-logs mailing list