comment/explain a lot

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

diff --git a/samples/mediaplayer/mediaplayer.cpp b/samples/mediaplayer/mediaplayer.cpp
index badca7d6ddd8b094a1c39e8f3dfa893ab4e389b1..4155a7d79fe0eb5c20010079e62ea954e8ce9e02 100644 (file)
--- a/samples/mediaplayer/mediaplayer.cpp
+++ b/samples/mediaplayer/mediaplayer.cpp
@@ -17,15 +17,12 @@
 // headers
 // ----------------------------------------------------------------------------
 
 // headers
 // ----------------------------------------------------------------------------
 

-// For compilers that support precompilation, includes "wx/wx.h".

 #include "wx/wxprec.h"
 
 #ifdef __BORLANDC__
     #pragma hdrstop
 #endif
 
 #include "wx/wxprec.h"
 
 #ifdef __BORLANDC__
     #pragma hdrstop
 #endif
 

-// for all others, include the necessary headers (this file is usually all you
-// need because it includes almost all "standard" wxWidgets headers)

 #ifndef WX_PRECOMP
     #include "wx/wx.h"
 #endif
 #ifndef WX_PRECOMP
     #include "wx/wx.h"
 #endif


@@ -34,18 +31,12 @@
 // resources
 // ----------------------------------------------------------------------------
 
 // resources
 // ----------------------------------------------------------------------------
 

-// the application icon (under Windows and OS/2 it is in resources and even
-// though we could still include the XPM here it would be unused)
-#if !defined(__WXMSW__) && !defined(__WXPM__)
-//    #include "../sample.xpm"
-#endif
-
-#include "wx/mediactrl.h"
-#include "wx/filedlg.h"
-#include "wx/slider.h"
-#include "wx/sizer.h"
-
-#include "wx/timer.h"
+#include "wx/mediactrl.h"   //for wxMediaCtrl
+#include "wx/filedlg.h"     //for opening files from OpenFile
+#include "wx/slider.h"      //for a slider for seeking within media
+#include "wx/sizer.h"       //for positioning controls/wxBoxSizer
+#include "wx/timer.h"       //timer for updating status bar
+#include "wx/textdlg.h"     //for getting user text from OpenURL

 
 
 #if !wxUSE_MEDIACTRL
 
 
 #if !wxUSE_MEDIACTRL


@@ -53,25 +44,15 @@
 #endif
 
 // ----------------------------------------------------------------------------
 #endif
 
 // ----------------------------------------------------------------------------

-// private classes
+// Declarations

 // ----------------------------------------------------------------------------
 
 // ----------------------------------------------------------------------------
 

-// Define a new application type, each program should derive a class from wxApp

 class MyApp : public wxApp
 {
 public:
 class MyApp : public wxApp
 {
 public:

-    // override base class virtuals
-    // ----------------------------
-
-    // this one is called on application startup and is a good place for the app
-    // initialization (doing it here and not in the ctor allows to have an error
-    // return: if OnInit() returns false, the application terminates)

     virtual bool OnInit();
 };
 
     virtual bool OnInit();
 };
 

-
-
-// Define a new frame type: this is going to be our main frame

 class MyFrame : public wxFrame
 {
 public:
 class MyFrame : public wxFrame
 {
 public:


@@ -96,19 +77,9 @@ public:
     void OnMediaFinished(wxMediaEvent& event);
 
 private:
     void OnMediaFinished(wxMediaEvent& event);
 
 private:

-    void ResetStatus()
-    {
-        m_basestatus = wxString::Format(_T("Size(x,y):%i,%i Length(Seconds):%u Speed:%1.1fx"), 
-        m_movie->GetBestSize().x, 
-        m_movie->GetBestSize().y, 
-        m_movie->GetDuration() / 1000,
-        m_movie->GetPlaybackRate()
-        );
-        
-        m_slider->SetRange(0, m_movie->GetDuration() / 1000);
-    }
-    
-    wxMediaCtrl* m_movie;
+    void ResetStatus();
+
+    wxMediaCtrl* m_mediactrl;

     wxSlider* m_slider;
     wxBoxSizer* m_sizer;
     class MyTimer* m_timer;
     wxSlider* m_slider;
     wxBoxSizer* m_sizer;
     class MyTimer* m_timer;


@@ -121,6 +92,32 @@ private:
     DECLARE_EVENT_TABLE()
 };
 
     DECLARE_EVENT_TABLE()
 };
 

+//
+//ResetStatus
+//-----------
+//Here we just make a simple status string
+//with some useful info about the media
+//We display info here in seconds (wxMediaCtrl
+//uses milliseconds - that's why we divide by 1000)
+//
+void MyFrame::ResetStatus()
+{
+    m_basestatus = wxString::Format(_T("Size(x,y):%i,%i Length(Seconds):%u Speed:%1.1fx"), 
+    m_mediactrl->GetBestSize().x, 
+    m_mediactrl->GetBestSize().y, 
+    m_mediactrl->GetDuration() / 1000,
+    m_mediactrl->GetPlaybackRate()
+    );
+    
+    m_slider->SetRange(0, m_mediactrl->GetDuration() / 1000);
+}
+
+//
+//wxGetMediaStateText
+//-------------------
+//Converts a wxMediaCtrl state into something
+//useful that we can display
+//

 const wxChar* wxGetMediaStateText(int nState)
 {
     switch(nState)
 const wxChar* wxGetMediaStateText(int nState)
 {
     switch(nState)


@@ -140,16 +137,22 @@ class MyTimer : public wxTimer
 public:
     MyTimer(MyFrame* frame) {m_frame = frame;}
 
 public:
     MyTimer(MyFrame* frame) {m_frame = frame;}
 

+    //
+    //Notify
+    //-----------
+    //Updates the main frame's status bar with the current
+    //position within the media and state the media is in
+    //

     void Notify()
     {
     void Notify()
     {

-        long lPosition = m_frame->m_movie->GetPosition() / 1000;
+        long lPosition = m_frame->m_mediactrl->GetPosition() / 1000;

         m_frame->m_slider->SetValue(lPosition);
             
 
         m_frame->SetStatusText(wxString::Format(_T("%s Pos:%u State:%s"),
                                     m_frame->m_basestatus.c_str(), 
                                     lPosition,
         m_frame->m_slider->SetValue(lPosition);
             
 
         m_frame->SetStatusText(wxString::Format(_T("%s Pos:%u State:%s"),
                                     m_frame->m_basestatus.c_str(), 
                                     lPosition,

-                                    wxGetMediaStateText(m_frame->m_movie->GetState())
+                                    wxGetMediaStateText(m_frame->m_mediactrl->GetState())

                                                 )
                                );
     
                                                 )
                                );
     


@@ -168,30 +171,27 @@ enum
 {
     // menu items
     Minimal_Quit = wxID_EXIT,
 {
     // menu items
     Minimal_Quit = wxID_EXIT,

-
-    // it is important for the id corresponding to the "About" command to have
-    // this standard value as otherwise it won't be handled properly under Mac
-    // (where it is special and put into the "Apple" menu)
-    Minimal_About = wxID_ABOUT,
-
-    Minimal_Slider = 1,
-    Minimal_Media,

     Minimal_Loop,
     Minimal_OpenFile,
     Minimal_OpenURL,
     Minimal_Play,
     Minimal_Pause,
     Minimal_Loop,
     Minimal_OpenFile,
     Minimal_OpenURL,
     Minimal_Play,
     Minimal_Pause,

-    Minimal_Stop
+    Minimal_Stop,
+    Minimal_About = wxID_ABOUT,
+
+    // id for our slider
+    Minimal_Slider = 1,
+
+    // id for our wxMediaCtrl
+    Minimal_Media

 };
 
 // ----------------------------------------------------------------------------
 // event tables and other macros for wxWidgets
 // ----------------------------------------------------------------------------
 
 };
 
 // ----------------------------------------------------------------------------
 // event tables and other macros for wxWidgets
 // ----------------------------------------------------------------------------
 

-// the event tables connect the wxWidgets events with the functions (event
-// handlers) which process them. It can be also done at run-time, but for the
-// simple menu events like this the static method is much simpler.

 BEGIN_EVENT_TABLE(MyFrame, wxFrame)
 BEGIN_EVENT_TABLE(MyFrame, wxFrame)

+    //Menu events

     EVT_MENU(Minimal_Quit,  MyFrame::OnQuit)
     EVT_MENU(Minimal_About, MyFrame::OnAbout)
     EVT_MENU(Minimal_Loop, MyFrame::OnLoop)
     EVT_MENU(Minimal_Quit,  MyFrame::OnQuit)
     EVT_MENU(Minimal_About, MyFrame::OnAbout)
     EVT_MENU(Minimal_Loop, MyFrame::OnLoop)


@@ -200,15 +200,15 @@ BEGIN_EVENT_TABLE(MyFrame, wxFrame)
     EVT_MENU(Minimal_Play, MyFrame::OnPlay)
     EVT_MENU(Minimal_Pause, MyFrame::OnPause)
     EVT_MENU(Minimal_Stop, MyFrame::OnStop)
     EVT_MENU(Minimal_Play, MyFrame::OnPlay)
     EVT_MENU(Minimal_Pause, MyFrame::OnPause)
     EVT_MENU(Minimal_Stop, MyFrame::OnStop)

+
+    //Slider events

     EVT_SLIDER(Minimal_Slider, MyFrame::OnSeek)
     EVT_SLIDER(Minimal_Slider, MyFrame::OnSeek)

+
+    //wxMediaCtrl events

     EVT_MEDIA_FINISHED(Minimal_Media, MyFrame::OnMediaFinished)
 END_EVENT_TABLE()
 
     EVT_MEDIA_FINISHED(Minimal_Media, MyFrame::OnMediaFinished)
 END_EVENT_TABLE()
 

-// Create a new application object: this macro will allow wxWidgets to create
-// the application object during program execution (it's better than using a
-// static object for many reasons) and also implements the accessor function
-// wxGetApp() which will return the reference of the right type (i.e. MyApp and
-// not wxApp)
+//main/WinMain()

 IMPLEMENT_APP(MyApp)
 
 // ============================================================================
 IMPLEMENT_APP(MyApp)
 
 // ============================================================================


@@ -216,22 +216,15 @@ IMPLEMENT_APP(MyApp)
 // ============================================================================
 
 // ----------------------------------------------------------------------------
 // ============================================================================
 
 // ----------------------------------------------------------------------------

-// the application class
+// MyApp

 // ----------------------------------------------------------------------------
 
 // 'Main program' equivalent: the program execution "starts" here
 bool MyApp::OnInit()
 {
 // ----------------------------------------------------------------------------
 
 // 'Main program' equivalent: the program execution "starts" here
 bool MyApp::OnInit()
 {

-    // create the main application window

     MyFrame *frame = new MyFrame(_T("Minimal wxWidgets App"));
     MyFrame *frame = new MyFrame(_T("Minimal wxWidgets App"));

-
-    // and show it (the frames, unlike simple controls, are not shown when
-    // created initially)

     frame->Show(true);
 
     frame->Show(true);
 

-    // success: wxApp::OnRun() will be called which will enter the main message
-    // loop and the application will run. If we returned false here, the
-    // application would exit immediately.

     return true;
 }
 
     return true;
 }
 


@@ -239,18 +232,20 @@ bool MyApp::OnInit()
 // main frame
 // ----------------------------------------------------------------------------
 
 // main frame
 // ----------------------------------------------------------------------------
 

-// frame constructor
+//
+//MyFrame
+//-------
+//Creates our menus and controls
+//

 MyFrame::MyFrame(const wxString& title)
        : wxFrame(NULL, wxID_ANY, title), m_timer(NULL)
 {
 MyFrame::MyFrame(const wxString& title)
        : wxFrame(NULL, wxID_ANY, title), m_timer(NULL)
 {

-    // set the frame icon
-//    SetIcon(wxICON(sample));
-
+    //
+    //  Create Menus
+    //

 #if wxUSE_MENUS
 #if wxUSE_MENUS

-    // create a menu bar

     wxMenu *menuFile = new wxMenu;
 
     wxMenu *menuFile = new wxMenu;
 

-    // the "About" item should be in the help menu

     wxMenu *helpMenu = new wxMenu;
     helpMenu->Append(Minimal_About, _T("&About...\tF1"), _T("Show about dialog"));
 
     wxMenu *helpMenu = new wxMenu;
     helpMenu->Append(Minimal_About, _T("&About...\tF1"), _T("Show about dialog"));
 


@@ -265,24 +260,31 @@ MyFrame::MyFrame(const wxString& title)
     menuFile->AppendSeparator();
     menuFile->Append(Minimal_Quit, _T("E&xit\tAlt-X"), _T("Quit this program"));
 
     menuFile->AppendSeparator();
     menuFile->Append(Minimal_Quit, _T("E&xit\tAlt-X"), _T("Quit this program"));
 

-    // now append the freshly created menu to the menu bar...

     wxMenuBar *menuBar = new wxMenuBar();
     menuBar->Append(menuFile, _T("&File"));
     menuBar->Append(helpMenu, _T("&Help"));
 
     wxMenuBar *menuBar = new wxMenuBar();
     menuBar->Append(menuFile, _T("&File"));
     menuBar->Append(helpMenu, _T("&Help"));
 

-    // ... and attach this menu bar to the frame

     SetMenuBar(menuBar);
 #endif // wxUSE_MENUS
 
     SetMenuBar(menuBar);
 #endif // wxUSE_MENUS
 

+    //
+    //  Create and attach the first/main sizer
+    //
+

     m_sizer = new wxBoxSizer(wxVERTICAL); 
     this->SetSizer(m_sizer);
     this->SetAutoLayout(true);
 
     m_sizer = new wxBoxSizer(wxVERTICAL); 
     this->SetSizer(m_sizer);
     this->SetAutoLayout(true);
 

-//    m_sizer->SetSizeHints(this);
-//    m_sizer->Fit(this);
-    
-    m_movie = new wxMediaCtrl(this, Minimal_Media, wxT(""));
-    m_sizer->Add(m_movie, 0, wxALIGN_CENTER_HORIZONTAL|wxALL, 5);
+    //
+    //  Create our media control
+    //
+
+    m_mediactrl = new wxMediaCtrl(this, Minimal_Media, wxT(""));
+    m_sizer->Add(m_mediactrl, 0, wxALIGN_CENTER_HORIZONTAL|wxALL, 5);
+
+    //
+    //  Create our slider
+    //

 
     m_slider = new wxSlider(this, Minimal_Slider, 0, //init
                             0, //start 
 
     m_slider = new wxSlider(this, Minimal_Slider, 0, //init
                             0, //start 


@@ -291,36 +293,72 @@ MyFrame::MyFrame(const wxString& title)
                             wxSL_HORIZONTAL );
     m_sizer->Add(m_slider, 0, wxALIGN_CENTER_HORIZONTAL|wxALL|wxEXPAND , 5);
 
                             wxSL_HORIZONTAL );
     m_sizer->Add(m_slider, 0, wxALIGN_CENTER_HORIZONTAL|wxALL|wxEXPAND , 5);
 

+
+    //
+    //  Create the second sizer which will position things
+    //  vertically - 
+    //
+    //  -------Menu----------
+    //  [m_mediactrl]
+    //
+    //  [m_slider]
+    //
+

     wxBoxSizer* horzsizer = new wxBoxSizer(wxHORIZONTAL);
     m_sizer->Add(horzsizer, 0, wxALIGN_CENTER_HORIZONTAL|wxALL, 5);
 
     wxBoxSizer* horzsizer = new wxBoxSizer(wxHORIZONTAL);
     m_sizer->Add(horzsizer, 0, wxALIGN_CENTER_HORIZONTAL|wxALL, 5);
 

-    m_bLoop = false;
+    //
+    //  We arn't looping initially
+    //

 
 

-    m_timer = new MyTimer(this);
-    m_timer->Start(100);
+    m_bLoop = false;

 
 

+    //
+    //  Create our status bar
+    //

 #if wxUSE_STATUSBAR
     // create a status bar just for fun (by default with 1 pane only)
     CreateStatusBar(1);
     ResetStatus();
     SetStatusText(m_basestatus);
 #endif // wxUSE_STATUSBAR
 #if wxUSE_STATUSBAR
     // create a status bar just for fun (by default with 1 pane only)
     CreateStatusBar(1);
     ResetStatus();
     SetStatusText(m_basestatus);
 #endif // wxUSE_STATUSBAR

+
+    //
+    //  Create a timer to update our status bar
+    //
+
+    m_timer = new MyTimer(this);
+    m_timer->Start(100);

 }
 
 }
 

+//
+//~MyFrame
+//-------
+//Deletes child objects implicitly and our timer explicitly
+//

 MyFrame::~MyFrame()
 {
 MyFrame::~MyFrame()
 {

-    if (m_timer)
-        delete m_timer;
+    delete m_timer;

 }
 
 }
 

-// event handlers
-
+//
+//OnQuit
+//-------
+//Called from file->quit.
+//Closes this application.
+//

 void MyFrame::OnQuit(wxCommandEvent& WXUNUSED(event))
 {
     // true is to force the frame to close
     Close(true);
 }
 
 void MyFrame::OnQuit(wxCommandEvent& WXUNUSED(event))
 {
     // true is to force the frame to close
     Close(true);
 }
 

+//
+//OnAbout
+//-------
+//Called from help->about.
+//Gets some info about this application.
+//

 void MyFrame::OnAbout(wxCommandEvent& WXUNUSED(event))
 {
     wxString msg;
 void MyFrame::OnAbout(wxCommandEvent& WXUNUSED(event))
 {
     wxString msg;


@@ -330,74 +368,128 @@ void MyFrame::OnAbout(wxCommandEvent& WXUNUSED(event))
     wxMessageBox(msg, _T("About wxMediaCtrl test"), wxOK | wxICON_INFORMATION, this);
 }
 
     wxMessageBox(msg, _T("About wxMediaCtrl test"), wxOK | wxICON_INFORMATION, this);
 }
 

+//
+//OnLoop
+//-------
+//Called from file->loop.
+//Changes the state of whether we want to loop or not.
+//

 void MyFrame::OnLoop(wxCommandEvent& WXUNUSED(event))
 {
     m_bLoop = !m_bLoop;
 }
 
 void MyFrame::OnLoop(wxCommandEvent& WXUNUSED(event))
 {
     m_bLoop = !m_bLoop;
 }
 

+//
+//OnOpenFile
+//-------
+//Called from file->openfile.
+//Opens and plays a media file
+//

 void MyFrame::OnOpenFile(wxCommandEvent& WXUNUSED(event))
 {
     wxFileDialog fd(this);
 
     if(fd.ShowModal() == wxID_OK)
     {
 void MyFrame::OnOpenFile(wxCommandEvent& WXUNUSED(event))
 {
     wxFileDialog fd(this);
 
     if(fd.ShowModal() == wxID_OK)
     {

-        if( !m_movie->Load(fd.GetPath()) )
+        if( !m_mediactrl->Load(fd.GetPath()) )

             wxMessageBox(wxT("Couldn't load file!"));
 
             wxMessageBox(wxT("Couldn't load file!"));
 

-        if( !m_movie->Play() )
+        if( !m_mediactrl->Play() )

             wxMessageBox(wxT("Couldn't play movie!"));            
             
         ResetStatus();
     }
 }
 
             wxMessageBox(wxT("Couldn't play movie!"));            
             
         ResetStatus();
     }
 }
 

-#include "wx/textdlg.h"

 
 

+//
+//OnOpenURL
+//-------
+//Called from file->openurl.
+//Opens a URL.
+//Windows DirectShow only.
+//

 void MyFrame::OnOpenURL(wxCommandEvent& WXUNUSED(event))
 {
     wxString theURL = wxGetTextFromUser(wxT("Enter the URL that has the movie to play"));
 
 void MyFrame::OnOpenURL(wxCommandEvent& WXUNUSED(event))
 {
     wxString theURL = wxGetTextFromUser(wxT("Enter the URL that has the movie to play"));
 

+#if defined(__WXMSW__) && wxUSE_DIRECTSHOW

     if(!theURL.empty())
     {
     if(!theURL.empty())
     {

-        if( !m_movie->Load(wxURI(theURL)) )
+        if( !m_mediactrl->Load(wxURI(theURL)) )

             wxMessageBox(wxT("Couldn't load URL!"));
 
             wxMessageBox(wxT("Couldn't load URL!"));
 

-        if( !m_movie->Play() )
+        if( !m_mediactrl->Play() )

             wxMessageBox(wxT("Couldn't play movie!"));            
             
         ResetStatus();
     }
             wxMessageBox(wxT("Couldn't play movie!"));            
             
         ResetStatus();
     }

+#else
+    wxMessageBox(wxT("Not supported!"));     
+#endif

 }
 
 }
 

+//
+//OnPlay
+//-------
+//Called from file->play.
+//Resumes the media if it is paused or stopped.
+//

 void MyFrame::OnPlay(wxCommandEvent& WXUNUSED(event))
 {
 void MyFrame::OnPlay(wxCommandEvent& WXUNUSED(event))
 {

-    if( !m_movie->Play() )
+    if( !m_mediactrl->Play() )

         wxMessageBox(wxT("Couldn't play movie!"));
 }
 
         wxMessageBox(wxT("Couldn't play movie!"));
 }
 

+//
+//OnPause
+//-------
+//Called from file->pause.
+//Pauses the media in-place.
+//

 void MyFrame::OnPause(wxCommandEvent& WXUNUSED(event))
 {
 void MyFrame::OnPause(wxCommandEvent& WXUNUSED(event))
 {

-    if( !m_movie->Pause() )
+    if( !m_mediactrl->Pause() )

         wxMessageBox(wxT("Couldn't pause movie!"));
 }
 
         wxMessageBox(wxT("Couldn't pause movie!"));
 }
 

+//
+//OnStop
+//-------
+//Called from file->stop.
+//Note that where the media stops is undefined - 
+//it could stop at the end or beginning.
+//

 void MyFrame::OnStop(wxCommandEvent& WXUNUSED(event))
 {
 void MyFrame::OnStop(wxCommandEvent& WXUNUSED(event))
 {

-    if( !m_movie->Stop() )
+    if( !m_mediactrl->Stop() )

         wxMessageBox(wxT("Couldn't stop movie!"));
 }
 
         wxMessageBox(wxT("Couldn't stop movie!"));
 }
 

+//
+//OnSeek
+//-------
+//Called from file->seek.
+//Called when the user moves the slider -
+//seeks to a position within the media
+//

 void MyFrame::OnSeek(wxCommandEvent& WXUNUSED(event))
 {
 void MyFrame::OnSeek(wxCommandEvent& WXUNUSED(event))
 {

-    if( !m_movie->SetPosition( m_slider->GetValue() * 1000 ) )
+    if( !m_mediactrl->SetPosition( m_slider->GetValue() * 1000 ) )

         wxMessageBox(wxT("Couldn't seek in movie!"));
 }
 
         wxMessageBox(wxT("Couldn't seek in movie!"));
 }
 

+//
+//OnMediaFinished
+//-------
+//Called when the media stops playing.
+//Here we loop it if the user wants to (has been selected from file menu)
+//

 void MyFrame::OnMediaFinished(wxMediaEvent& WXUNUSED(event))
 {
     if(m_bLoop)
     {
 void MyFrame::OnMediaFinished(wxMediaEvent& WXUNUSED(event))
 {
     if(m_bLoop)
     {

-        if ( !m_movie->SetPosition(0) || !m_movie->Play() )
+        if ( !m_mediactrl->SetPosition(0) || !m_mediactrl->Play() )

             wxMessageBox(wxT("Couldn't seek or play to loop movie!"));
     }
 }
\ No newline at end of file
             wxMessageBox(wxT("Couldn't seek or play to loop movie!"));
     }
 }
\ No newline at end of file