added cmd line parsing support to wxApp and --theme option to wxUniv

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@10952 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

docs/latex/wx/app.tex

@@ -38,10 +38,6 @@ a reference to your application object) to be visible to other files.
 
 Constructor. Called implicitly with a definition of a wxApp object.
 
-% VZ: there is no such feature so far...
-% The argument is a language identifier; this is an experimental
-% feature and will be expanded and documented in future versions.
-
 \membersection{wxApp::\destruct{wxApp}}
 
 \func{void}{\destruct{wxApp}}{\void}
@@ -234,6 +230,53 @@ If you use this member, you can selectively consume keypress events by calling\r
 \helpref{wxKeyEvent}{wxkeyevent}, \helpref{wxWindow::OnChar}{wxwindowonchar},\rtfsp
 \helpref{wxWindow::OnCharHook}{wxwindowoncharhook}, \helpref{wxDialog::OnCharHook}{wxdialogoncharhook}
 
+\membersection{wxApp::OnCmdLineError}\label{wxapponcmdlineerror}
+
+\func{bool}{OnCmdLineError}{\param{wxCmdLineParser\& }{parser}}
+
+Called when command line parsing fails (i.e. an incorrect command line option
+was specified by the user). The default behaviour is to show the program usage
+text and abort the program.
+
+Return {\tt TRUE} to continue normal execution or {\tt FALSE} to return 
+{\tt FALSE} from \helpref{OnInit}{wxapponinit} thus terminating the program.
+
+\wxheading{See also}
+
+\helpref{OnInitCmdLine}{wxapponinitcmdline}
+
+\membersection{wxApp::OnCmdLineHelp}\label{wxapponcmdlinehelp}
+
+\func{bool}{OnCmdLineHelp}{\param{wxCmdLineParser\& }{parser}}
+
+Called when the help option ({\tt --help}) was specified on the command line.
+The default behaviour is to show the program usage text and abort the program.
+
+Return {\tt TRUE} to continue normal execution or {\tt FALSE} to return 
+{\tt FALSE} from \helpref{OnInit}{wxapponinit} thus terminating the program.
+
+\wxheading{See also}
+
+\helpref{OnInitCmdLine}{wxapponinitcmdline}
+
+\membersection{wxApp::OnCmdLineParsed}\label{wxapponcmdlineparsed}
+
+\func{bool}{OnCmdLineParsed}{\param{wxCmdLineParser\& }{parser}}
+
+Called after the command line had been successfully parsed. You may override
+this method to test for the values of the various parameters which could be
+set from the command line.
+
+Don't forget to call the base class version unless you want to suppress
+processing of the standard command line options.
+
+Return {\tt TRUE} to continue normal execution or {\tt FALSE} to return 
+{\tt FALSE} from \helpref{OnInit}{wxapponinit} thus terminating the program.
+
+\wxheading{See also}
+
+\helpref{OnInitCmdLine}{wxapponinitcmdline}
+
 \membersection{wxApp::OnFatalException}\label{wxapponfatalexception}
 
 \func{void}{OnFatalException}{\void}
@@ -251,64 +294,79 @@ work and, in fact, probably won't.
 
 \helpref{wxHandleFatalExcetions}{wxhandlefatalexceptions}
 
-\membersection{wxApp::OnIdle}\label{wxapponidle}
+%% VZ: the wxApp event handler are private and should not be documented here!
-
+%%
-\func{void}{OnIdle}{\param{wxIdleEvent\& }{event}}
+%%\membersection{wxApp::OnIdle}\label{wxapponidle}
-
+%%
-Override this member function for any processing which needs to be done
+%%\func{void}{OnIdle}{\param{wxIdleEvent\& }{event}}
-when the application is idle. You should call wxApp::OnIdle from your own function,
+%%
-since this forwards OnIdle events to windows and also performs garbage collection for
+%%Override this member function for any processing which needs to be done
-windows whose destruction has been delayed.
+%%when the application is idle. You should call wxApp::OnIdle from your own function,
-
+%%since this forwards OnIdle events to windows and also performs garbage collection for
-wxWindows' strategy for OnIdle processing is as follows. After pending user interface events for an
+%%windows whose destruction has been delayed.
-application have all been processed, wxWindows sends an OnIdle event to the application object. wxApp::OnIdle itself
+%%
-sends an OnIdle event to each application window, allowing windows to do idle processing such as updating
+%%wxWindows' strategy for OnIdle processing is as follows. After pending user interface events for an
-their appearance. If either wxApp::OnIdle or a window OnIdle function requested more time, by
+%%application have all been processed, wxWindows sends an OnIdle event to the application object. wxApp::OnIdle itself
-caling \helpref{wxIdleEvent::RequestMore}{wxidleeventrequestmore}, wxWindows will send another OnIdle
+%%sends an OnIdle event to each application window, allowing windows to do idle processing such as updating
-event to the application object. This will occur in a loop until either a user event is found to be
+%%their appearance. If either wxApp::OnIdle or a window OnIdle function requested more time, by
-pending, or OnIdle requests no more time. Then all pending user events are processed until the system
+%%caling \helpref{wxIdleEvent::RequestMore}{wxidleeventrequestmore}, wxWindows will send another OnIdle
-goes idle again, when OnIdle is called, and so on.
+%%event to the application object. This will occur in a loop until either a user event is found to be
-
+%%pending, or OnIdle requests no more time. Then all pending user events are processed until the system
-\wxheading{See also}
+%%goes idle again, when OnIdle is called, and so on.
-
+%%
-\helpref{wxWindow::OnIdle}{wxwindowonidle}, \helpref{wxIdleEvent}{wxidleevent},\rtfsp
+%%\wxheading{See also}
-\helpref{wxWindow::SendIdleEvents}{wxappsendidleevents}
+%%
-
+%%\helpref{wxWindow::OnIdle}{wxwindowonidle}, \helpref{wxIdleEvent}{wxidleevent},\rtfsp
-\membersection{wxApp::OnEndSession}\label{wxapponendsession}
+%%\helpref{wxWindow::SendIdleEvents}{wxappsendidleevents}
-
+%%
-\func{void}{OnEndSession}{\param{wxCloseEvent\& }{event}}
+%%\membersection{wxApp::OnEndSession}\label{wxapponendsession}
-
+%%
-This is an event handler function called when the operating system or GUI session is
+%%\func{void}{OnEndSession}{\param{wxCloseEvent\& }{event}}
-about to close down. The application has a chance to silently save information,
+%%
-and can optionally close itself.
+%%This is an event handler function called when the operating system or GUI session is
-
+%%about to close down. The application has a chance to silently save information,
-Use the EVT\_END\_SESSION event table macro to handle query end session events.
+%%and can optionally close itself.
-
+%%
-The default handler calls \helpref{wxWindow::Close}{wxwindowclose} with a TRUE argument
+%%Use the EVT\_END\_SESSION event table macro to handle query end session events.
-(forcing the application to close itself silently).
+%%
-
+%%The default handler calls \helpref{wxWindow::Close}{wxwindowclose} with a TRUE argument
-\wxheading{Remarks}
+%%(forcing the application to close itself silently).
-
+%%
-Under X, OnEndSession is called in response to the `die' event.
+%%\wxheading{Remarks}
-
+%%
-Under Windows, OnEndSession is called in response to the WM\_ENDSESSION message.
+%%Under X, OnEndSession is called in response to the `die' event.
-
+%%
-\wxheading{See also}
+%%Under Windows, OnEndSession is called in response to the WM\_ENDSESSION message.
-
+%%
-\helpref{wxWindow::Close}{wxwindowclose},\rtfsp
+%%\wxheading{See also}
-\helpref{wxWindow::OnCloseWindow}{wxwindowonclosewindow},\rtfsp
+%%
-\helpref{wxCloseEvent}{wxcloseevent},\rtfsp
+%%\helpref{wxWindow::Close}{wxwindowclose},\rtfsp
-\helpref{wxApp::OnQueryEndSession}{wxapponqueryendsession}
+%%\helpref{wxWindow::OnCloseWindow}{wxwindowonclosewindow},\rtfsp
+%%\helpref{wxCloseEvent}{wxcloseevent},\rtfsp
+%%\helpref{wxApp::OnQueryEndSession}{wxapponqueryendsession}
 
 \membersection{wxApp::OnInit}\label{wxapponinit}
 
 \func{bool}{OnInit}{\void}
 
 This must be provided by the application, and will usually create the
-application's main window, optionally calling \helpref{wxApp::SetTopWindow}{wxappsettopwindow}.
+application's main window, optionally calling 
+\helpref{wxApp::SetTopWindow}{wxappsettopwindow}.
+
+Notice that if you want to to use the command line processing provided by
+wxWindows you have to call the base class version in the derived class
+OnInit().
 
 Return TRUE to continue processing, FALSE to exit the application.
 
+\membersection{wxApp::OnInitCmdLine}\label{wxapponinitcmdline}
+
+\func{void}{OnInitCmdLine}{\param{wxCmdLineParser\& }{parser}}
+
+Called from \helpref{OnInit}{wxapponinit} and may be used to initialize the
+parser with the command line options for this application. The base class
+versions adds support for a few standard options only.
+
 \membersection{wxApp::OnQueryEndSession}\label{wxapponqueryendsession}
 
 \func{void}{OnQueryEndSession}{\param{wxCloseEvent\& }{event}}

include/wx/app.h

@@ -31,6 +31,8 @@
     typedef wxObject* (*wxAppInitializerFunction)();
 #endif
 
+class WXDLLEXPORT wxCmdLineParser;
+
 // ----------------------------------------------------------------------------
 // headers we have to include here
 // ----------------------------------------------------------------------------
@@ -38,7 +40,7 @@
 #include "wx/event.h"       // for the base class
 
 #if wxUSE_GUI
-    #include "wx/window.h"      // for wxTopLevelWindows
+    #include "wx/window.h"  // for wxTopLevelWindows
 #endif // wxUSE_GUI
 
 #if wxUSE_LOG
@@ -63,19 +65,13 @@ public:
 
     // the virtual functions which may/must be overridden in the derived class
     // -----------------------------------------------------------------------
-#ifdef __WXMAC_X__
+
-    virtual ~wxAppBase() {}  // Added min for Mac X
-#endif
         // called during the program initialization, returning FALSE from here
         // prevents the program from continuing - it's a good place to create
         // the top level program window and return TRUE.
         //
         // Override: always in GUI application, rarely in console ones.
-#if wxUSE_GUI
+    virtual bool OnInit();
-    virtual bool OnInit() { return FALSE; };
-#else // !GUI
-    virtual bool OnInit() { return TRUE; };
-#endif // wxUSE_GUI
 
 #if wxUSE_GUI
         // a platform-dependent version of OnInit(): the code here is likely to
@@ -196,6 +192,34 @@ public:
 
 #endif // wxUSE_GUI
 
+    // cmd line parsing stuff
+    // ----------------------
+
+    // all of these methods may be overridden in the derived class to
+    // customize the command line parsing (by default only a few standard
+    // options are handled)
+    //
+    // you also need to call wxApp::OnInit() from YourApp::OnInit() for all
+    // this to work
+
+#if wxUSE_CMDLINE_PARSER
+    // this one is called from OnInit() to add all supported options
+    // to the given parser
+    virtual void OnInitCmdLine(wxCmdLineParser& parser);
+
+    // called after successfully parsing the command line, return TRUE
+    // to continue and FALSE to exit
+    virtual bool OnCmdLineParsed(wxCmdLineParser& parser);
+
+    // called if "--help" option was specified, return TRUE to continue
+    // and FALSE to exit
+    virtual bool OnCmdLineHelp(wxCmdLineParser& parser);
+
+    // called if incorrect command line options were given, return
+    // FALSE to abort and TRUE to continue
+    virtual bool OnCmdLineError(wxCmdLineParser& parser);
+#endif // wxUSE_CMDLINE_PARSER
+
     // miscellaneous customization functions
     // -------------------------------------
 
@@ -281,6 +305,11 @@ protected:
     // does any of our windows has focus?
     bool m_isActive;
 #endif // wxUSE_GUI
+
+#ifdef __WXMAC_X__
+public:
+    virtual ~wxAppBase() {}  // Added min for Mac X
+#endif
 };
 
 // ----------------------------------------------------------------------------
@@ -412,7 +441,7 @@ public:
         extern int wxEntry( int argc, char *argv[] ); \
         int main(int argc, char *argv[]) { return wxEntry(argc, argv); }
 #elif defined(__WXMAC__) && defined(__UNIX__)
-	// wxMac seems to have a specific wxEntry prototype
+    // wxMac seems to have a specific wxEntry prototype
     #define IMPLEMENT_WXWIN_MAIN \
         extern int wxEntry( int argc, char *argv[], bool enterLoop = 1 ); \
         int main(int argc, char *argv[]) { return wxEntry(argc, argv); }

samples/widgets/widgets.cpp

@@ -192,6 +192,9 @@ END_EVENT_TABLE()
 
 bool WidgetsApp::OnInit()
 {
+    if ( !wxApp::OnInit() )
+        return FALSE;
+
     // the reason for having these ifdef's is that I often run two copies of
     // this sample side by side and it is useful to see which one is which
     wxString title;

src/common/appcmn.cpp

@@ -30,20 +30,22 @@
 
 #ifndef WX_PRECOMP
     #include "wx/app.h"
+    #include "wx/intl.h"
     #include "wx/list.h"
 #endif
 
+#include "wx/cmdline.h"
 #include "wx/thread.h"
 #include "wx/confbase.h"
 
-#ifdef __WXUNIVERSAL__
-    #include "wx/univ/theme.h"
-#endif // __WXUNIVERSAL__
-
 // ===========================================================================
 // implementation
 // ===========================================================================
 
+// ----------------------------------------------------------------------------
+// initialization and termination
+// ----------------------------------------------------------------------------
+
 wxAppBase::wxAppBase()
 {
     wxTheApp = (wxApp *)this;
@@ -59,15 +61,11 @@ wxAppBase::wxAppBase()
 #endif // wxUSE_GUI
 }
 
-// ----------------------------------------------------------------------------
-// initialization and termination
-// ----------------------------------------------------------------------------
-
 #if wxUSE_GUI
 bool wxAppBase::OnInitGui()
 {
 #ifdef __WXUNIVERSAL__
-    if ( !wxTheme::CreateDefault() )
+    if ( !wxTheme::Get() && !wxTheme::CreateDefault() )
         return FALSE;
 #endif // __WXUNIVERSAL__
 
@@ -136,3 +134,127 @@ void wxAppBase::SetActive(bool active, wxWindow * WXUNUSED(lastFocus))
 }
 
 #endif // wxUSE_GUI
+
+// ----------------------------------------------------------------------------
+// cmd line parsing
+// ----------------------------------------------------------------------------
+
+bool wxAppBase::OnInit()
+{
+#if wxUSE_CMDLINE_PARSER
+    wxCmdLineParser parser(argc, argv);
+
+    OnInitCmdLine(parser);
+
+    bool cont;
+    switch ( parser.Parse() )
+    {
+        case -1:
+            cont = OnCmdLineHelp(parser);
+            break;
+
+        case 0:
+            cont = OnCmdLineParsed(parser);
+            break;
+
+        default:
+            cont = OnCmdLineError(parser);
+            break;
+    }
+
+    if ( !cont )
+        return FALSE;
+#endif // wxUSE_CMDLINE_PARSER
+
+    return TRUE;
+}
+
+#if wxUSE_CMDLINE_PARSER
+
+#define OPTION_VERBOSE _T("verbose")
+#define OPTION_THEME   _T("theme")
+
+void wxAppBase::OnInitCmdLine(wxCmdLineParser& parser)
+{
+    // the standard command line options
+    static const wxCmdLineEntryDesc cmdLineDesc[] =
+    {
+        {
+            wxCMD_LINE_SWITCH,
+            _T("h"),
+            _T("help"),
+            gettext_noop("show this help message"),
+            wxCMD_LINE_VAL_NONE,
+            wxCMD_LINE_OPTION_HELP
+        },
+
+#if wxUSE_LOG
+        {
+            wxCMD_LINE_SWITCH,
+            _T(""),
+            OPTION_VERBOSE,
+            gettext_noop("generate verbose log messages")
+        },
+#endif wxUSE_LOG
+
+#ifdef __WXUNIVERSAL__
+        {
+            wxCMD_LINE_OPTION,
+            _T(""),
+            OPTION_THEME,
+            gettext_noop("specify the theme to use"),
+            wxCMD_LINE_VAL_STRING
+        },
+#endif // __WXUNIVERSAL__
+
+        // terminator
+        { wxCMD_LINE_NONE }
+    };
+
+    parser.SetDesc(cmdLineDesc);
+}
+
+bool wxAppBase::OnCmdLineParsed(wxCmdLineParser& parser)
+{
+#if wxUSE_LOG
+    if ( parser.Found(OPTION_VERBOSE) )
+    {
+        wxLog::SetVerbose(TRUE);
+    }
+#endif // wxUSE_LOG
+
+#ifdef __WXUNIVERSAL__
+    wxString themeName;
+    if ( parser.Found(OPTION_THEME, &themeName) )
+    {
+        wxTheme *theme = wxTheme::Create(themeName);
+        if ( !theme )
+        {
+            wxLogError(_("Unsupported theme '%s'."), themeName.c_str());
+
+            return FALSE;
+        }
+
+        wxTheme::Set(theme);
+    }
+#endif // __WXUNIVERSAL__
+
+    return TRUE;
+}
+
+bool wxAppBase::OnCmdLineHelp(wxCmdLineParser& parser)
+{
+    parser.Usage();
+
+    return FALSE;
+}
+
+bool wxAppBase::OnCmdLineError(wxCmdLineParser& parser)
+{
+    parser.Usage();
+
+    return FALSE;
+}
+
+#endif // wxUSE_CMDLINE_PARSER
+

src/common/cmdline.cpp

@@ -64,6 +64,9 @@ struct wxCmdLineOption
                     wxCmdLineParamType typ,
                     int fl)
     {
+        wxASSERT_MSG( !shrt.empty() || !lng.empty(),
+                      _T("option should have at least one name") );
+
         kind = k;
 
         shortName = shrt;
@@ -240,13 +243,16 @@ void wxCmdLineParserData::SetArguments(const wxString& cmdLine)
 
 int wxCmdLineParserData::FindOption(const wxString& name)
 {
-    size_t count = m_options.GetCount();
+    if ( !name.empty() )
-    for ( size_t n = 0; n < count; n++ )
     {
-        if ( m_options[n].shortName == name )
+        size_t count = m_options.GetCount();
+        for ( size_t n = 0; n < count; n++ )
         {
-            // found
+            if ( m_options[n].shortName == name )
-            return n;
+            {
+                // found
+                return n;
+            }
         }
     }
 
@@ -410,6 +416,9 @@ void wxCmdLineParser::AddParam(const wxString& desc,
 bool wxCmdLineParser::Found(const wxString& name) const
 {
     int i = m_data->FindOption(name);
+    if ( i == wxNOT_FOUND )
+        i = m_data->FindOptionByLongName(name);
+
     wxCHECK_MSG( i != wxNOT_FOUND, FALSE, _T("unknown switch") );
 
     wxCmdLineOption& opt = m_data->m_options[(size_t)i];
@@ -422,6 +431,9 @@ bool wxCmdLineParser::Found(const wxString& name) const
 bool wxCmdLineParser::Found(const wxString& name, wxString *value) const
 {
     int i = m_data->FindOption(name);
+    if ( i == wxNOT_FOUND )
+        i = m_data->FindOptionByLongName(name);
+
     wxCHECK_MSG( i != wxNOT_FOUND, FALSE, _T("unknown option") );
 
     wxCmdLineOption& opt = m_data->m_options[(size_t)i];
@@ -438,6 +450,9 @@ bool wxCmdLineParser::Found(const wxString& name, wxString *value) const
 bool wxCmdLineParser::Found(const wxString& name, long *value) const
 {
     int i = m_data->FindOption(name);
+    if ( i == wxNOT_FOUND )
+        i = m_data->FindOptionByLongName(name);
+
     wxCHECK_MSG( i != wxNOT_FOUND, FALSE, _T("unknown option") );
 
     wxCmdLineOption& opt = m_data->m_options[(size_t)i];
@@ -454,6 +469,9 @@ bool wxCmdLineParser::Found(const wxString& name, long *value) const
 bool wxCmdLineParser::Found(const wxString& name, wxDateTime *value) const
 {
     int i = m_data->FindOption(name);
+    if ( i == wxNOT_FOUND )
+        i = m_data->FindOptionByLongName(name);
+
     wxCHECK_MSG( i != wxNOT_FOUND, FALSE, _T("unknown option") );
 
     wxCmdLineOption& opt = m_data->m_options[(size_t)i];