[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