comment/explain a lot

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

samples/mediaplayer/mediaplayer.cpp

@@ -17,15 +17,12 @@
 // headers
 // ----------------------------------------------------------------------------
 
-// For compilers that support precompilation, includes "wx/wx.h".
 #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
@@ -34,18 +31,12 @@
 // resources
 // ----------------------------------------------------------------------------
 
-// the application icon (under Windows and OS/2 it is in resources and even
+#include "wx/mediactrl.h"   //for wxMediaCtrl
-// though we could still include the XPM here it would be unused)
+#include "wx/filedlg.h"     //for opening files from OpenFile
-#if !defined(__WXMSW__) && !defined(__WXPM__)
+#include "wx/slider.h"      //for a slider for seeking within media
-//    #include "../sample.xpm"
+#include "wx/sizer.h"       //for positioning controls/wxBoxSizer
-#endif
+#include "wx/timer.h"       //timer for updating status bar
-
+#include "wx/textdlg.h"     //for getting user text from OpenURL
-#include "wx/mediactrl.h"
-#include "wx/filedlg.h"
-#include "wx/slider.h"
-#include "wx/sizer.h"
-
-#include "wx/timer.h"
 
 
 #if !wxUSE_MEDIACTRL
@@ -53,25 +44,15 @@
 #endif
 
 // ----------------------------------------------------------------------------
-// private classes
+// Declarations
 // ----------------------------------------------------------------------------
 
-// Define a new application type, each program should derive a class from wxApp
 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();
 };
 
-
-
-// Define a new frame type: this is going to be our main frame
 class MyFrame : public wxFrame
 {
 public:
@@ -96,19 +77,9 @@ public:
     void OnMediaFinished(wxMediaEvent& event);
 
 private:
-    void ResetStatus()
+    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_mediactrl;
-    }
-    
-    wxMediaCtrl* m_movie;
     wxSlider* m_slider;
     wxBoxSizer* m_sizer;
     class MyTimer* m_timer;
@@ -121,6 +92,32 @@ private:
     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)
@@ -140,16 +137,22 @@ class MyTimer : public wxTimer
 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()
     {
-        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,
-                                    wxGetMediaStateText(m_frame->m_movie->GetState())
+                                    wxGetMediaStateText(m_frame->m_mediactrl->GetState())
                                                 )
                                );
     
@@ -168,30 +171,27 @@ enum
 {
     // 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_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
 // ----------------------------------------------------------------------------
 
-// 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)
+    //Menu events
     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)
+
+    //Slider events
     EVT_SLIDER(Minimal_Slider, MyFrame::OnSeek)
+
+    //wxMediaCtrl events
     EVT_MEDIA_FINISHED(Minimal_Media, MyFrame::OnMediaFinished)
 END_EVENT_TABLE()
 
-// Create a new application object: this macro will allow wxWidgets to create
+//main/WinMain()
-// 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)
 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()
 {
-    // create the main application window
     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);
 
-    // 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;
 }
 
@@ -239,18 +232,20 @@ bool MyApp::OnInit()
 // main frame
 // ----------------------------------------------------------------------------
 
-// frame constructor
+//
+//MyFrame
+//-------
+//Creates our menus and controls
+//
 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
-    // create a menu bar
     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"));
 
@@ -265,24 +260,31 @@ MyFrame::MyFrame(const wxString& title)
     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"));
 
-    // ... and attach this menu bar to the frame
     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->SetSizeHints(this);
+    //
-//    m_sizer->Fit(this);
+    //  Create our media control
+    //
 
-    m_movie = new wxMediaCtrl(this, Minimal_Media, wxT(""));
+    m_mediactrl = new wxMediaCtrl(this, Minimal_Media, wxT(""));
-    m_sizer->Add(m_movie, 0, wxALIGN_CENTER_HORIZONTAL|wxALL, 5);
+    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 
@@ -291,36 +293,72 @@ MyFrame::MyFrame(const wxString& title)
                             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);
 
+    //
+    //  We arn't looping initially
+    //
+
     m_bLoop = false;
 
-    m_timer = new MyTimer(this);
+    //
-    m_timer->Start(100);
+    //  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
+
+    //
+    //  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()
 {
-    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);
 }
 
+//
+//OnAbout
+//-------
+//Called from help->about.
+//Gets some info about this application.
+//
 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);
 }
 
+//
+//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;
 }
 
+//
+//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)
     {
-        if( !m_movie->Load(fd.GetPath()) )
+        if( !m_mediactrl->Load(fd.GetPath()) )
             wxMessageBox(wxT("Couldn't load file!"));
 
-        if( !m_movie->Play() )
+        if( !m_mediactrl->Play() )
             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"));
 
+#if defined(__WXMSW__) && wxUSE_DIRECTSHOW
     if(!theURL.empty())
     {
-        if( !m_movie->Load(wxURI(theURL)) )
+        if( !m_mediactrl->Load(wxURI(theURL)) )
             wxMessageBox(wxT("Couldn't load URL!"));
 
-        if( !m_movie->Play() )
+        if( !m_mediactrl->Play() )
             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))
 {
-    if( !m_movie->Play() )
+    if( !m_mediactrl->Play() )
         wxMessageBox(wxT("Couldn't play movie!"));
 }
 
+//
+//OnPause
+//-------
+//Called from file->pause.
+//Pauses the media in-place.
+//
 void MyFrame::OnPause(wxCommandEvent& WXUNUSED(event))
 {
-    if( !m_movie->Pause() )
+    if( !m_mediactrl->Pause() )
         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))
 {
-    if( !m_movie->Stop() )
+    if( !m_mediactrl->Stop() )
         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))
 {
-    if( !m_movie->SetPosition( m_slider->GetValue() * 1000 ) )
+    if( !m_mediactrl->SetPosition( m_slider->GetValue() * 1000 ) )
         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)
     {
-        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!"));
     }
 }