[Scummvm-cvs-logs] SF.net SVN: scummvm:[41894] tools/branches/gsoc2009-gui/gui

Remere at users.sourceforge.net Remere at users.sourceforge.net
Fri Jun 26 02:06:56 CEST 2009


Revision: 41894
          http://scummvm.svn.sourceforge.net/scummvm/?rev=41894&view=rev
Author:   Remere
Date:     2009-06-26 00:06:56 +0000 (Fri, 26 Jun 2009)

Log Message:
-----------
*Added doxygen commentary to all files. Hope I got all the syntax right.

Modified Paths:
--------------
    tools/branches/gsoc2009-gui/gui/configuration.h
    tools/branches/gsoc2009-gui/gui/main.cpp
    tools/branches/gsoc2009-gui/gui/main.h
    tools/branches/gsoc2009-gui/gui/pages.h
    tools/branches/gsoc2009-gui/gui/tools.cpp
    tools/branches/gsoc2009-gui/gui/tools.h

Modified: tools/branches/gsoc2009-gui/gui/configuration.h
===================================================================
--- tools/branches/gsoc2009-gui/gui/configuration.h	2009-06-25 23:04:43 UTC (rev 41893)
+++ tools/branches/gsoc2009-gui/gui/configuration.h	2009-06-26 00:06:56 UTC (rev 41894)
@@ -27,8 +27,10 @@
 
 class Tool;
 
-// Different audio formats
-// They're used for bitwise operations
+/** 
+ * Different audio formats
+ * You can bitwise them to represent several formats
+ */
 enum AudioFormat {
 	AUDIO_VORBIS = 1,
 	AUDIO_FLAC = 2,
@@ -36,6 +38,9 @@
 	AUDIO_ALL = AUDIO_VORBIS | AUDIO_FLAC | AUDIO_MP3
 };
 
+/**
+ * Current state of the wizard
+ */
 struct Configuration {
 	Configuration();
 	
@@ -43,14 +48,25 @@
 	// this class is just a glorified map with different types, so it seems
 	// unnecessary.
 
+	/** If the user chose the advanced route from the start */
 	bool advanced;
+	/** true if the chose to compress, false if compress, undefined if advanced */
 	bool compressing;
-	bool advancedAudioSettings;
+
+	/** The name of the game we are extracting or compressing */
 	wxString selectedGame;
+	/** The tool the user chose to use, NULL if none has been chosen yet */
 	const Tool* selectedTool;
+
+	/** Input files selected */
 	wxArrayString inputFilePaths;
+	/** Path to output to */
 	wxString outputPath;
+
+	/** Audio format selected */
 	AudioFormat selectedAudioFormat;
+	/** true if the user wants to see the advanced audio options */
+	bool advancedAudioSettings;
 };
 
 inline Configuration::Configuration() {
@@ -58,11 +74,11 @@
 
 	advanced = false;
 	compressing = false;
-	advancedAudioSettings = false;
 
 	selectedTool = NULL;
 
 	selectedAudioFormat = AUDIO_VORBIS;
+	advancedAudioSettings = false;
 }
 
 #endif

Modified: tools/branches/gsoc2009-gui/gui/main.cpp
===================================================================
--- tools/branches/gsoc2009-gui/gui/main.cpp	2009-06-25 23:04:43 UTC (rev 41893)
+++ tools/branches/gsoc2009-gui/gui/main.cpp	2009-06-26 00:06:56 UTC (rev 41894)
@@ -150,10 +150,6 @@
 	_buttons->setPage(_pages.back(), newPanel);
 }
 
-void ScummToolsFrame::switchToPreviousPage() {
-	switchPage(NULL, true);
-}
-
 BEGIN_EVENT_TABLE(WizardButtons, wxPanel)
 	EVT_BUTTON(ID_NEXT, WizardButtons::onClickNext)
 	EVT_BUTTON(ID_PREV, WizardButtons::onClickPrevious)

Modified: tools/branches/gsoc2009-gui/gui/main.h
===================================================================
--- tools/branches/gsoc2009-gui/gui/main.h	2009-06-25 23:04:43 UTC (rev 41893)
+++ tools/branches/gsoc2009-gui/gui/main.h	2009-06-26 00:06:56 UTC (rev 41894)
@@ -39,23 +39,46 @@
 	ID_CANCEL,
 };
 
-// Application top window
-
+/**
+ * Top window of the application, the entire wizard, simply put
+ * Responsible for both the UI, and the management of pages
+ */
 class ScummToolsFrame : public wxFrame
 {
 public:
+	/**
+	 * Creates the top window
+	 *
+	 * @param title The title of the window
+	 * @param pos Position of the window onscreen
+	 * @param size The target size of the window
+	 */
 	ScummToolsFrame(const wxString &title, const wxPoint &pos, const wxSize &size);
 	~ScummToolsFrame();
 
-	// Switches to this page and resets the buttons
-	void switchPage(WizardPage *nextPage, bool moveback = false);
+	/**
+	 * Switches page, old page is stored on a stack for going backwards
+	 * Buttons are reset, and state is saved
+	 *
+	 * @param nextPage The page to switch too, the old page window will be destroyed 
+	 *                 and this page displayed in it's stead.
+	 */
+	void switchPage(WizardPage *nextPage) {
+		switchPage(nextPage, false);}
 
-	// Switches to the previous page
-	void switchToPreviousPage();
+	/**
+	 * Switches back page to the previous page
+	 * The current page is destroyed.
+	 */
+	void switchToPreviousPage() {
+		switchPage(NULL, true);}
 
+	/** The state of the wizard so far */
 	Configuration _configuration;
 
 private:
+	void switchPage(WizardPage *nextPage, bool moveback);
+
 	wxPanel *_wizardpane;
 	WizardButtons *_buttons;
 	
@@ -64,33 +87,59 @@
 	DECLARE_EVENT_TABLE()
 };
 
-// This panel contains the "Next", "Previous" and "Abort" buttons
-// Convenient interface as you don't need to create buttons
-// with long, awkward calls
+/**
+ * This panel contains the "Next", "Previous" and "Abort" buttons
+ * Convenient interface as you don't need to create buttons
+ * with long, awkward calls
+ */
 
 class WizardButtons : public wxPanel {
 public:
+	/**
+	 * Creates the button window.
+	 *
+	 * @param parent The parent window
+	 * @param linetext A static text that is used to display some extra information
+	 */
 	WizardButtons(wxWindow *parent, wxStaticText *linetext);
 
-	// Set the buttons to the standard configuration
-	// (prev, next shown and enabled, finish disabled)
+	/* Set the buttons to the standard configuration
+	 * (prev, next shown and enabled, finish disabled)
+	 */
 	void reset();
 
-	// Set the current wizard page, done from SwitchPage required
-	// for the buttons to know where to drop their events
+	/**
+	 * Set the current wizard page, this is called from SwitchPage to make us
+	 * know where to drop events generated by the buttons
+	 */
 	void setPage(WizardPage *current, wxWindow *panel);
 
-	// Set the label of the line above the buttons, can display some useful info here
+	/**
+	 * Set the label of the line above the buttons, can display some useful info here
+	 *
+	 * @param label The label to display
+	 */
 	void setLineLabel(wxString label);
 
-	// Enables (ie. makes clickable) the next button (or finish for the last page)
+	/**
+	 * Enables the next button (or finish for the last page)
+	 */
 	void enableNext(bool enable);
-	void enableFinish(bool enable) {enableNext(enable);}
-	// Enables the previous button, shows it if hidden
+
+	/**
+	 * Enables the previous button, shows it if it's disabled
+	 */
 	void enablePrevious(bool enable);
-	// Display the previous button, it is invisible by default
+
+
+	/**
+	 * Display the previous button.
+	 */ 
 	void showPrevious(bool show);
-	// Changes 'next' into 'finish'
+
+	/**
+	 * Changes name of the 'next' button to finish
+	 */
 	void showFinish(bool show);
 
 	// wx event handlers
@@ -100,19 +149,27 @@
 	void onClickCancel(wxCommandEvent &e);
 
 protected:
+	/** 'Next' (or finish) button */
 	wxButton *_next;
+	/** 'Previous' button */
 	wxButton *_prev;
+	/** 'Cancel' button */
 	wxButton *_cancel;
+	/** The static text on the line seperating the page area and the buttons */
 	wxStaticText *_linetext;
+	/** Current page, required for dumping events to it */
 	WizardPage *_currentPage;
+	/** Current panel, required so we can pass it as arguments to the handlers */
 	wxWindow *_currentPanel;
 
 	DECLARE_EVENT_TABLE()
 };
 
-// The header at the top of the window
-// Tries to load media/logo.gif and media/tiled.gif
-// If unavailable, it will simply be orange/brigt orange
+/**
+ * The header at the top of the window
+ * Tries to load media/logo.gif and media/tiled.gif
+ * If unavailable, it will simply be orange/brigt orange
+ */
 
 class Header : public wxPanel
 {

Modified: tools/branches/gsoc2009-gui/gui/pages.h
===================================================================
--- tools/branches/gsoc2009-gui/gui/pages.h	2009-06-25 23:04:43 UTC (rev 41893)
+++ tools/branches/gsoc2009-gui/gui/pages.h	2009-06-26 00:06:56 UTC (rev 41894)
@@ -24,8 +24,13 @@
 
 #include "configuration.h"
 
-// Wizard Page
-// A page in the extraction wizard
+/**
+ * A backend of a page in the wizard 
+ * This class is decoupled from the UI, and you can spawn as many pages as you like from this template
+ * 
+ * @todo Add the ability to not have to have a ScummToolsFrame as parent, to be able to put the pages
+ *       in a default config window, for example.
+ */
 
 class WizardPage : public wxEvtHandler
 {
@@ -35,34 +40,86 @@
 ;
 	}
 
-	// Creates a visual representation of this page as a child problem of the supplied parent
+	/**
+	 * Creates a visual representation of this page as a child problem of the supplied parent
+	 * Values will be loaded from the configuration object stored by the ScummToolsFrame
+	 * 
+	 * @param parent The parent window, the page will be a direct child window of this window.
+	 * @return       The created window.
+	 */
 	virtual wxWindow *CreatePanel(wxWindow *parent);
 
+	/**
+	 * Simply calls ScummToolsFrame::switchPage
+	 *
+	 * @param next The window to switch to.
+	 */
 	void switchPage(WizardPage *next);
 
-	// Load/Save configuration, reads data from the panel supplied
+	/**
+	 * Saves the state of the panel passed as the argument in the configuration object of
+	 * the ScummToolsFrame that was passed to the constructor
+	 *
+	 * @param panel Panel to read data from, should be a window created by CreatePanel
+	 */ 
 	virtual void save(wxWindow *panel);
 	
 	// Event handlers
-	// overload these to handle prev/next/cancel clicks
+	
+	/**
+	 * This handler is called when the user clicks the Next button, if you overload this
+	 * you should generally just call switchPage with the next page in the wizard
+	 *
+	 * @param panel The panel associated with this page, should have bene created by CreatePanel previously.
+	 */
 	virtual void onNext(wxWindow *panel);
+
+	/**
+	 * This handler is called when the user clicks the Previous button, you do not generally
+	 * need to overload this as the default handler returns to the privous page already.
+	 *
+	 * @param panel The panel associated with this page, should have bene created by CreatePanel previously.
+	 */
 	virtual void onPrevious(wxWindow *panel);
+
+	/**
+	 * This handler is called when the user clicks the Cancel button, overlaod this to destroy any
+	 * state this page might hold (the destructor will still be called though, so it's doubtful there
+	 * is a reason to overload this). The default handler queries the user if the really want to close
+	 * the wizard.
+	 *
+	 * @param panel The panel associated with this page, should have bene created by CreatePanel previously.
+	 */
 	virtual void onCancel(wxWindow *panel); // Default is to display 'Are you sure' and quit if you click 'Yes'
 
-	// Update button states
+	/**
+	 * Update state of the next/prev/cancel buttons, by default all buttons are shown, and the next button
+	 * is in "next" state (ie. finish is not displayed instead of next)
+	 *
+	 * @param panel The panel associated with this page, should have bene created by CreatePanel previously.
+	 * @param buttons The window that holds the concerned buttons
+	 */
 	virtual void updateButtons(wxWindow *panel, WizardButtons *buttons);
 
 protected:
-	// This adds an offset (about 100px) to the left of the sizer
-	// to center the text somewhat, before adding it to the panel
+	/** 
+	 * This adds an offset (about 100px) to the left of the sizer to center the text somewhat, before adding it 
+	 * to the panel using wxWindow::SetSizer.
+	 *
+	 * @param panel The panel associated with this page, should have bene created by CreatePanel previously.
+	 * @param sizer The topsizer of the window.
+	 */
 	void SetAlignedSizer(wxWindow *panel, wxSizer *sizer);
 
 	ScummToolsFrame* _topframe;
 	Configuration &_configuration;
 };
 
-// Introduction page, with options to extract/compress
-// Step 1
+/**
+ * Introduction page. Introduces the option to extract, compress or the advanced route (choose tool manually)
+ * 
+ * @todo Add the ability to drag & drop files onto this window, to automatically detect whether to compress or extract
+ */
 
 class IntroPage : public WizardPage
 {
@@ -78,7 +135,11 @@
 	void updateButtons(wxWindow *panel, WizardButtons *buttons);
 };
 
-// Step 2, choose tool / game
+/**
+ * Presents a list of games that are supported for compression.
+ * 
+ * @todo Possibly merge with ChooseExtractionPage
+ */
 
 class ChooseCompressionPage : public WizardPage
 {
@@ -92,6 +153,12 @@
 	void save(wxWindow *panel);
 };
 
+/**
+ * Presents a list of games that are supported for extraction.
+ * 
+ * @todo Possibly merge with ChooseCompressionPage
+ */
+
 class ChooseExtractionPage : public WizardPage
 {
 public:
@@ -104,6 +171,10 @@
 	void save(wxWindow *panel);
 };
 
+/**
+ * Presents a list of all supported tools, the "advanced route"
+ */
+
 class ChooseToolPage : public WizardPage
 {
 public:
@@ -116,7 +187,12 @@
 	void save(wxWindow *panel);
 };
 
-// Step 3, choose input & output directory/file
+/**
+ * Presents a list of all input and outputs supported by the selected tool
+ * expects the configuration to already contain the selected tool
+ *
+ * @todo Make it look better and save state
+ */
 
 class ChooseInOutPage : public WizardPage
 {
@@ -130,7 +206,13 @@
 	void save(wxWindow *panel);
 };
 
-// Step 4, choose audio format
+/**
+ * Presents a dropdown list of the three different audio compression methods
+ * or possibly fewer, if the selected tool does not support all methods.
+ *
+ * @todo Make it look better and save state, and possibly skip it if the tool
+ *       only support one method of compression.
+ */
 
 class ChooseAudioFormatPage : public WizardPage
 {

Modified: tools/branches/gsoc2009-gui/gui/tools.cpp
===================================================================
--- tools/branches/gsoc2009-gui/gui/tools.cpp	2009-06-25 23:04:43 UTC (rev 41893)
+++ tools/branches/gsoc2009-gui/gui/tools.cpp	2009-06-26 00:06:56 UTC (rev 41894)
@@ -205,11 +205,12 @@
 	return &iter->second;
 }
 
-const Tool *Tools::getByGame(const wxString &gamename) const {
+const Tool *Tools::getByGame(const wxString &gamename, ToolType type) const {
 	for(std::map<wxString, Tool>::const_iterator iter = tools.begin(); iter != tools.end(); ++iter)
-		for(wxArrayString::const_iterator citer = iter->second._games.begin(); citer != iter->second._games.end(); ++citer)
-			if(*citer == gamename)
-				return &iter->second;
+		if(type == TOOLTYPE_ALL || iter->second._type == type)
+			for(wxArrayString::const_iterator citer = iter->second._games.begin(); citer != iter->second._games.end(); ++citer)
+				if(*citer == gamename)
+					return &iter->second;
 	return NULL;
 }
 
@@ -252,17 +253,6 @@
 	return (_supportedFormats & format) == format;
 }
 
-bool Tool::pickFiles() {
-	for(ToolInputs::const_iterator iter = _inputs.begin(); iter != _inputs.end(); ++iter)
-		if(iter->_file)
-			return true;
-	return false;
-}
-
-bool Tool::pickDirs() {
-	return !pickFiles();
-}
-
 wxString Tool::getExecutable() {
 #ifdef WIN32
 	return _name + wxT(".exe");

Modified: tools/branches/gsoc2009-gui/gui/tools.h
===================================================================
--- tools/branches/gsoc2009-gui/gui/tools.h	2009-06-25 23:04:43 UTC (rev 41893)
+++ tools/branches/gsoc2009-gui/gui/tools.h	2009-06-26 00:06:56 UTC (rev 41894)
@@ -30,8 +30,10 @@
 
 #include "configuration.h"
 
-// Different types of tools, used to differentiate them when 
-// fetching lists of games & tools
+
+/** Different types of tools, used to differentiate them when 
+ * fetching lists of games & tools
+ */
 enum ToolType {
 	TOOLTYPE_COMPRESSION,
 	TOOLTYPE_EXTRACTION,
@@ -40,37 +42,76 @@
 };
 
 
-// Describes a possible input to the tool (since some take two seperate files, 
-// some a dir and some a single file
+/**
+ * Describes a possible input to the tool (since some take two seperate files, 
+ * some a dir and some a single file
+ */
 struct ToolInput {
+	/** The extension of this input file, ignored for directories */
 	wxString _extension;
+	/** A short description of what file is expected, displayed in the UI */
 	wxString _description;
-	bool _file; // dir otherwise
+	/** If false, this input is a directory */
+	bool _file;
 };
 
 typedef std::vector<ToolInput> ToolInputs;
 
-// A tool, contains all info necessary to run it
+/**
+ * A tool supported by the Wizard, holds all information about what format it supports
+ * what input it requires etc.
+ *
+ * @todo Add some way to represent extra arguments to the tool
+ */
 class Tool {
 public:
 	Tool();
-	Tool(wxString name, wxString input_extensions = wxT("*.*"));
+	/**
+	 * Creates a new tool, can be stack allocated and copied without problems
+	 * The type of tool is deduced from the name, if it contains 'extract', it's an extraction tool
+	 * and if it contains 'compress' it's a compression tool. If the tool does not contain either,
+	 * you must set the type manually.
+	 *
+	 * @param name The name of the tool, should match the executable name (without the extension)
+	 * @param input_extenion Filename filter of the input  to expect.
+	 */
+	Tool(wxString name, wxString input_extension = wxT("*.*"));
 
+	/**
+	 * Adds a supported game to this tool
+	 *
+	 * @param game_name The name of the game this tool supports
+	 */
 	void addGame(const wxString &game_name);
 
-	// Helpfer functions to get info about the tool
+	// Helper functions to get info about the tool
+	
+	/**
+	 * Returns true if the audio format(s) is supported by this tool
+	 * 
+	 * @param format The audio format(s) to test for
+	 */
 	bool supportsAudioFormat(AudioFormat format);
-	bool pickFiles();
-	bool pickDirs();
+	/**
+	 * Returns the name of the executable of this tool.
+	 * This simple returns the name under *nix, and name.exe under Windows
+	 */
 	wxString getExecutable();
 
 
+	/** Name of the tool */
 	wxString _name;
+	/** Type of tool, either extract, compress or unknown */
 	ToolType _type;
+	/* Formats supported by the tool, bitwise ORed */
 	AudioFormat _supportedFormats;
+	/** List of all inputs this tool expects */
 	ToolInputs _inputs;
+	/** Try if this tool does not output a single file, but rather an entire directory */
 	bool _outputToDirectory;
+	/** The help text displayed on the input/output page */
 	wxString _inoutHelpText;
+	/** A list of all games supported by this tool */
 	wxArrayString _games;
 };
 
@@ -78,18 +119,55 @@
 class Tools {
 public:
 	Tools();
+	
+	/**
+	 * Returns a tool by name
+	 * asserts if the tool is not found
+	 *
+	 * @param name Name of the tool to fetch
+	 * @return A reference to the tool, tools cannot be modified.
+	 */
 
 	const Tool &operator[](const wxString &name) const;
+	/**
+	 * Returns a tool by name
+	 *
+	 * @param name Name of the tool to fetch
+	 * @return A pointer to the tool, NULL if there is no tool by that name.
+	 */
 	const Tool *get(const wxString &name) const;
-	const Tool *getByGame(const wxString &game) const;
 
-	// Returns all tool/game names in a list
-	// conveinent for creating the choose tool page
-	// List will be sorted and unique
-	wxArrayString getToolList(ToolType tt) const;
-	wxArrayString getGameList(ToolType tt) const;
+	/**
+	 * Returns a tool that supports the selected game
+	 * 
+	 * @param game Name of the game
+	 * @param type The type of tool we're looking for
+	 * @return The tool that supports this game, and NULL if no tool does
+	 */
+	const Tool *getByGame(const wxString &game, ToolType type = TOOLTYPE_ALL) const;
 
+	/**
+	 * Returns a list of all tools
+	 *
+	 * @param tt Filter by this type of tool
+	 * @return Returns all tools of this type, list is sorted and contains no duplicates
+	 */
+	wxArrayString getToolList(ToolType tt = TOOLTYPE_ALL) const;
+
+	/**
+	 * Returns a list of all games supported by all tools (of the specified type)
+	 *
+	 * @param tt Filter by this type of tool
+	 * @return Returns all games supported, list is sorted and contains no duplicates
+	 */
+	wxArrayString getGameList(ToolType tt = TOOLTYPE_ALL) const;
+
 protected:
+	/**
+	 * Adds a supported tool. Should not be done after construction, since it might break pointers
+	 *
+	 * @param tool the tool to add.
+	 */
 	void addTool(const Tool &tool);
 
 	std::map<wxString, Tool> tools;


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