From ba1d7a6cec8d9569ce2e380d4a39ddcd4450c9b5 Mon Sep 17 00:00:00 2001 From: Francesco Montorsi Date: Sat, 11 Oct 2008 13:10:48 +0000 Subject: [PATCH] revised m*h headers git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@56227 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775 --- interface/wx/mdi.h | 39 ++++-- interface/wx/mediactrl.h | 204 ++++++++++++++++++------------- interface/wx/memory.h | 132 ++++++++++---------- interface/wx/menu.h | 237 ++++++++++++++++++++++++------------ interface/wx/menuitem.h | 75 ++++++++---- interface/wx/metafile.h | 56 ++++++--- interface/wx/mimetype.h | 249 +++++++++++++++++++++++++------------- interface/wx/minifram.h | 60 ++++----- interface/wx/module.h | 52 ++++---- interface/wx/mousestate.h | 7 ++ interface/wx/msgdlg.h | 13 +- interface/wx/msgqueue.h | 35 +++--- interface/wx/mstream.h | 34 ++++-- 13 files changed, 736 insertions(+), 457 deletions(-) diff --git a/interface/wx/mdi.h b/interface/wx/mdi.h index 60e93cba19..29231640c7 100644 --- a/interface/wx/mdi.h +++ b/interface/wx/mdi.h @@ -8,14 +8,10 @@ /** @class wxMDIClientWindow - @wxheader{mdi.h} An MDI client window is a child of wxMDIParentFrame, and manages zero or more wxMDIChildFrame objects. - @library{wxcore} - @category{managedwnd} - @remarks The client window is the area where MDI child windows exist. It doesn't have to @@ -32,6 +28,9 @@ Under Windows 95, the client window will automatically have a sunken border style when the active child is not maximized, and no border style when a child is maximized. + @library{wxcore} + @category{managedwnd} + @see wxMDIChildFrame, wxMDIParentFrame, wxFrame */ class wxMDIClientWindow : public wxWindow @@ -73,7 +72,6 @@ public: /** @class wxMDIParentFrame - @wxheader{mdi.h} An MDI (Multiple Document Interface) parent frame is a window which can contain MDI child frames in its own 'desktop'. It is a convenient way to avoid window @@ -176,6 +174,9 @@ public: @remarks During the construction of the frame, the client window will be created. To use a different class from wxMDIClientWindow, override OnCreateClient(). + Under Windows 95, the client window will automatically have a + sunken border style when the active child is not maximized, + and no border style when a child is maximized. @see Create(), OnCreateClient() */ @@ -220,8 +221,8 @@ public: virtual void Cascade(); /** - Used in two-step frame construction. See wxMDIParentFrame() - for further details. + Used in two-step frame construction. + See wxMDIParentFrame() for further details. */ bool Create(wxWindow* parent, wxWindowID id, const wxString& title, @@ -316,7 +317,7 @@ public: Note that it is probably impossible to have a client window that scrolls as well as painting a bitmap or pattern, since in @b OnScroll, the scrollbar - positions always return zero. (Solutions to: julian.smart@btopenworld.com). + positions always return zero. @see GetClientWindow(), wxMDIClientWindow */ @@ -353,8 +354,8 @@ public: virtual void SetToolBar(wxWindow* toolbar); /** - Call this to change the current Window menu. Ownership of the menu object - passes to the frame when you call this function. + Call this to change the current Window menu. + Ownership of the menu object passes to the frame when you call this function. This call is available under Windows only. @@ -375,7 +376,6 @@ public: /** @class wxMDIChildFrame - @wxheader{mdi.h} An MDI child frame is a frame that can only exist on a wxMDIClientWindow, which is itself a child of wxMDIParentFrame. @@ -407,6 +407,19 @@ public: Displays a thick frame around the window (Windows and Motif only). @endStyleTable + @remarks + Although internally an MDI child frame is a child of the MDI client window, + in wxWidgets you create it as a child of wxMDIParentFrame. + You can usually forget that the client window exists. + MDI child frames are clipped to the area of the MDI client window, and may + be iconized on the client window. + You can associate a menubar with a child frame as usual, although an MDI + child doesn't display its menubar under its own title bar. + The MDI parent frame's menubar will be changed to reflect the currently + active child frame. + If there are currently no children, the parent frame's own menubar will + be displayed. + @library{wxcore} @category{managedwnd} @@ -466,8 +479,8 @@ public: virtual void Activate(); /** - Used in two-step frame construction. See wxMDIChildFrame() - for further details. + Used in two-step frame construction. + See wxMDIChildFrame() for further details. */ bool Create(wxWindow* parent, wxWindowID id, const wxString& title, diff --git a/interface/wx/mediactrl.h b/interface/wx/mediactrl.h index 95b4be94c1..e572a1361e 100644 --- a/interface/wx/mediactrl.h +++ b/interface/wx/mediactrl.h @@ -65,19 +65,15 @@ public: /** @class wxMediaCtrl - wxMediaCtrl is a class for displaying types of - media, such as videos, audio files, natively through native codecs. + wxMediaCtrl is a class for displaying types of media, such as videos, audio + files, natively through native codecs. wxMediaCtrl uses native backends to render media, for example on Windows there is a ActiveMovie/DirectShow backend, and on Macintosh there is a QuickTime backend. - @library{wxmedia} - @category{media} - @see wxMediaEvent - - @section class_mediactrl_rendering_media Rendering media + @section mediactrl_rendering_media Rendering media Depending upon the backend, wxMediaCtrl can render and display pretty much any kind of media that the native system can - such as an image, mpeg video, or mp3 @@ -93,7 +89,7 @@ public: of the backend. For example, QuickTime cannot set the playback rate of certain streaming media - while DirectShow is slightly more flexible in that regard. - @section class_mediactrl_operation Operation + @section mediactrl_operation Operation When wxMediaCtrl plays a file, it plays until the stop position is reached (currently the end of the file/stream). Right before it hits the end of the stream, @@ -120,85 +116,120 @@ public: } @endcode - When wxMediaCtrl stops, either by the @c EVT_MEDIA_STOP not being vetoed, or by manually - calling Stop(), where it actually stops is not at the beginning, rather, but at the beginning - of the stream. That is, when it stops and play is called, playback is gauranteed to start at - the beginning of the media. This is because some streams are not seekable, and when stop is - called on them they return to the beginning, thus wxMediaCtrl tries to keep consistant for all types - of media. - - Note that when changing the state of the media through Play() and other methods, the media may not - actually be in the @c wxMEDIASTATE_PLAYING, for example. If you are relying on the media being in - certain state catch the event relevant to the state. See wxMediaEvent for the kinds of events that - you can catch. - - @section class_mediactrl_video_size Video size - - By default, wxMediaCtrl will scale the size of the video to the requested amount passed to either - its constructor or Create(). After calling Load or performing an equivilant operation, you can - subsequently obtain the "real" size of the video (if there is any) by calling GetBestSize(). - Note that the actual result on the display will be slightly different when ShowPlayerControls is - activated and the actual video size will be less then specified due to the extra controls provided - by the native toolkit. In addition, the backend may modify GetBestSize() to include the size of - the extra controls - so if you want the real size of the video just disable ShowPlayerControls(). - - The idea with setting GetBestSize() to the size of the video is that GetBestSize() is a wxWindow-derived - function that is called when sizers on a window recalculate. What this means is that if you use sizers - by default the video will show in its original size without any extra assistance needed from the user. - - @section class_mediactrl_player_controls Player controls - - Normally, when you use wxMediaCtrl it is just a window for the video to play in. However, some toolkits - have their own media player interface. For example, QuickTime generally has a bar below the video with - a slider. A special feature available to wxMediaCtrl, you can use the toolkits interface instead of making - your own by using the ShowPlayerControls() function. There are several options for the flags parameter, - with the two general flags being @c wxMEDIACTRLPLAYERCONTROLS_NONE which turns off the native interface, - and @c wxMEDIACTRLPLAYERCONTROLS_DEFAULT which lets wxMediaCtrl decide what native controls on the interface. - Be sure to review the caveats outlined in Video size before doing so. - - @section class_mediactrl_choosing_backend Choosing a backend - - Generally, you should almost certainly leave this part up to wxMediaCtrl - but if you need a certain backend - for a particular reason, such as QuickTime for playing .mov files, all you need to do to choose a specific - backend is to pass the name of the backend class to Create(). + When wxMediaCtrl stops, either by the @c EVT_MEDIA_STOP not being vetoed, or + by manually calling Stop(), where it actually stops is not at the beginning, + rather, but at the beginning of the stream. That is, when it stops and play + is called, playback is gauranteed to start at the beginning of the media. + This is because some streams are not seekable, and when stop is called on + them they return to the beginning, thus wxMediaCtrl tries to keep consistant + for all types of media. + + Note that when changing the state of the media through Play() and other methods, + the media may not actually be in the @c wxMEDIASTATE_PLAYING, for example. + If you are relying on the media being in certain state catch the event relevant + to the state. See wxMediaEvent for the kinds of events that you can catch. + + + @section mediactrl_video_size Video size + + By default, wxMediaCtrl will scale the size of the video to the requested + amount passed to either its constructor or Create(). + After calling wxMediaCtrl::Load or performing an equivilant operation, + you can subsequently obtain the "real" size of the video (if there is any) + by calling wxMediaCtrl::GetBestSize(). Note that the actual result on the + display will be slightly different when wxMediaCtrl::ShowPlayerControls is + activated and the actual video size will be less then specified due to the + extra controls provided by the native toolkit. + In addition, the backend may modify wxMediaCtrl::GetBestSize() to include + the size of the extra controls - so if you want the real size of the video + just disable wxMediaCtrl::ShowPlayerControls(). + + The idea with setting wxMediaCtrl::GetBestSize() to the size of the video is + that GetBestSize() is a wxWindow-derived function that is called when sizers + on a window recalculate. + What this means is that if you use sizers by default the video will show in + its original size without any extra assistance needed from the user. + + + @section mediactrl_player_controls Player controls + + Normally, when you use wxMediaCtrl it is just a window for the video to play in. + However, some toolkits have their own media player interface. + For example, QuickTime generally has a bar below the video with a slider. + A special feature available to wxMediaCtrl, you can use the toolkits interface + instead of making your own by using the ShowPlayerControls() function. + There are several options for the flags parameter, with the two general flags + being @c wxMEDIACTRLPLAYERCONTROLS_NONE which turns off the native interface, + and @c wxMEDIACTRLPLAYERCONTROLS_DEFAULT which lets wxMediaCtrl decide what + native controls on the interface. + Be sure to review the caveats outlined in @ref mediactrl_video_size before doing so. + + + @section mediactrl_choosing_backend Choosing a backend + + Generally, you should almost certainly leave this part up to wxMediaCtrl - + but if you need a certain backend for a particular reason, such as QuickTime + for playing .mov files, all you need to do to choose a specific backend is + to pass the name of the backend class to wxMediaCtrl::Create(). The following are valid backend identifiers: - @beginTable - @row2col{@b wxMEDIABACKEND_DIRECTSHOW, Use ActiveMovie/DirectShow. Uses the native ActiveMovie (I.E. DirectShow) control. Default backend on Windows and supported by nearly all Windows versions, even some Windows CE versions. May display a windows media player logo while inactive.} - @row2col{@b wxMEDIABACKEND_QUICKTIME, Use QuickTime. Mac Only. WARNING: May not working correctly embedded in a wxNotebook.} - @row2col{@b wxMEDIABACKEND_GSTREAMER, Use GStreamer. Unix Only. Requires GStreamer 0.8 along with at the very least the xvimagesink, xoverlay, and gst-play modules of gstreamer to function. You need the correct modules to play the relavant files, for example the mad module to play mp3s, etc.} - @row2col{@b wxMEDIABACKEND_WMP10, Uses Windows Media Player 10 (Windows only) - works on mobile machines with Windows Media Player 10 and desktop machines with either Windows Media Player 9 or 10} - @endTable + - @b wxMEDIABACKEND_DIRECTSHOW: Use ActiveMovie/DirectShow. + Uses the native ActiveMovie (I.E. DirectShow) control. + Default backend on Windows and supported by nearly all Windows versions, + even some Windows CE versions. + May display a windows media player logo while inactive. + - @b wxMEDIABACKEND_QUICKTIME: Use QuickTime. Mac Only. + WARNING: May not working correctly embedded in a wxNotebook. + - @b wxMEDIABACKEND_GSTREAMER, Use GStreamer. Unix Only. + Requires GStreamer 0.8 along with at the very least the xvimagesink, xoverlay, + and gst-play modules of gstreamer to function. + You need the correct modules to play the relavant files, for example the + mad module to play mp3s, etc. + - @b wxMEDIABACKEND_WMP10, Uses Windows Media Player 10 (Windows only) - + works on mobile machines with Windows Media Player 10 and desktop machines + with either Windows Media Player 9 or 10. + + Note that other backends such as wxMEDIABACKEND_MCI can now be found at + wxCode (http://wxcode.sourceforge.net/). + + + @section mediactrl_creating_backend Creating a backend + + Creating a backend for wxMediaCtrl is a rather simple process. + Simply derive from wxMediaBackendCommonBase and implement the methods you want. + The methods in wxMediaBackend correspond to those in wxMediaCtrl except for + wxMediaCtrl::CreateControl which does the actual creation of the control, + in cases where a custom control is not needed you may simply call wxControl::Create(). - Note that other backends such as wxMEDIABACKEND_MCI can now be found at wxCode(http://wxcode.sourceforge.net/). + You need to make sure to use the @c DECLARE_CLASS and @c IMPLEMENT_CLASS macros. - @section class_mediactrl_creating_backend Creating a backend + The only real tricky part is that you need to make sure the file in compiled in, + which if there are just backends in there will not happen and you may need to + use a force link hack (see http://www.wxwidgets.org/wiki/index.php/RTTI). - Creating a backend for wxMediaCtrl is a rather simple process. Simply derive from wxMediaBackendCommonBase - and implement the methods you want. The methods in wxMediaBackend correspond to those in wxMediaCtrl except - for CreateControl which does the actual creation of the control, in cases where a custom control is not - needed you may simply call wxControl::Create(). + This is a rather simple example of how to create a backend in the + wxActiveXContainer documentation. - You need to make sure to use the @c DECLARE_CLASS and @c IMPLEMENT_CLASS macros. - The only real tricky part is that you need to make sure the file in compiled in, which if there are - just backends in there will not happen and you may need to use a force link hack - (see http://www.wxwidgets.org/wiki/index.php/RTTI). + @library{wxmedia} + @category{media} - This is a rather simple example of how to create a backend in the wxActiveXContainer documentation. + @see wxMediaEvent */ class wxMediaCtrl : public wxControl { public: /** - Default constructor - you MUST call Create before calling any other methods of wxMediaCtrl. + Default constructor - you MUST call Create() before calling any + other methods of wxMediaCtrl. */ wxMediaCtrl(); /** - Constructor that calls Create(). You may prefer to call Create() directly to check - to see if wxMediaCtrl is available on the system. + Constructor that calls Create(). + You may prefer to call Create() directly to check to see if + wxMediaCtrl is available on the system. @param parent parent of this control. Must not be @NULL. @@ -213,8 +244,7 @@ public: @param style Optional styles. @param szBackend - Name of backend you want to use, leave blank to make - wxMediaCtrl figure it out. + Name of backend you want to use, leave blank to make wxMediaCtrl figure it out. @param validator validator to use. @param name @@ -226,14 +256,14 @@ public: const wxValidator& validator = wxDefaultValidator, const wxString& name = wxPanelNameStr); - /** - Creates this control. Returns @false if it can't load the movie located at @a fileName + Creates this control. + Returns @false if it can't load the movie located at @a fileName or it cannot load one of its native backends. - If you specify a file to open via @a fileName and you don't specify a backend to - use, wxMediaCtrl tries each of its backends until one that can render the path referred to - by @a fileName can be found. + If you specify a file to open via @a fileName and you don't specify a + backend to use, wxMediaCtrl tries each of its backends until one that + can render the path referred to by @a fileName can be found. @param parent parent of this control. Must not be @NULL. @@ -248,8 +278,7 @@ public: @param style Optional styles. @param szBackend - Name of backend you want to use, leave blank to make - wxMediaCtrl figure it out. + Name of backend you want to use, leave blank to make wxMediaCtrl figure it out. @param validator validator to use. @param name @@ -263,7 +292,8 @@ public: /** Obtains the best size relative to the original/natural size of the - video, if there is any. See @ref class_mediactrl_video_size for more information. + video, if there is any. + See @ref mediactrl_video_size for more information. */ wxSize GetBestSize(); @@ -290,8 +320,8 @@ public: /** Gets the volume of the media from a 0.0 to 1.0 range. - @note Due to rounding and other errors the value returned may not be the exact value - sent to SetVolume(). + @note Due to rounding and other errors the value returned may not be the + exact value sent to SetVolume(). */ double GetVolume(); @@ -306,8 +336,9 @@ public: bool Load(const wxString& fileName); /** - Loads the location that uri refers to. Note that this is very implementation-dependant, - although HTTP URI/URLs are generally supported, for example. Returns @false if loading fails. + Loads the location that uri refers to. Note that this is very + implementation-dependant, although HTTP URI/URLs are generally + supported, for example. Returns @false if loading fails. */ bool Load(const wxURI& uri); @@ -324,7 +355,8 @@ public: bool LoadURI(const wxURI& uri); /** - Same as Load(const wxURI& uri, const wxURI& proxy). Kept for wxPython compatibility. + Same as Load(const wxURI& uri, const wxURI& proxy). + Kept for wxPython compatibility. */ bool LoadURIWithProxy(const wxURI& uri, const wxURI& proxy); @@ -375,7 +407,7 @@ public: default controls provided by the toolkit. The function takes a wxMediaCtrlPlayerControls enumeration, please see available show modes there. - For more see @ref class_mediactrl_player_controls. + For more see @ref mediactrl_player_controls. Currently only implemented on the QuickTime and DirectShow backends. The function returns @true on success. @@ -385,7 +417,7 @@ public: /** Stops the media. - See @ref class_mediactrl_operation for an overview of how stopping works. + See @ref mediactrl_operation for an overview of how stopping works. */ bool Stop(); diff --git a/interface/wx/memory.h b/interface/wx/memory.h index 45e91ac460..d4d27991ca 100644 --- a/interface/wx/memory.h +++ b/interface/wx/memory.h @@ -1,49 +1,26 @@ ///////////////////////////////////////////////////////////////////////////// // Name: memory.h -// Purpose: interface of wxDebugStreamBuf +// Purpose: interface of wxDebugContext // Author: wxWidgets team // RCS-ID: $Id$ // Licence: wxWindows license ///////////////////////////////////////////////////////////////////////////// -/** - @class wxDebugStreamBuf - - This class allows you to treat debugging output in a similar - (stream-based) fashion on different platforms. Under - Windows, an ostream constructed with this buffer outputs - to the debugger, or other program that intercepts debugging - output. On other platforms, the output goes to standard error (cerr). - - This is soon to be obsolete, replaced by wxLog functionality. - - @library{wxbase} - @category{FIXME} - - @see Overview() -*/ -class wxDebugStreamBuf -{ -public: - -}; - - /** @class wxDebugContext - A class for performing various debugging and memory tracing - operations. Full functionality (such as printing out objects - currently allocated) is only present in a debugging build of wxWidgets, - i.e. if the __WXDEBUG__ symbol is defined. wxDebugContext - and related functions and macros can be compiled out by setting - wxUSE_DEBUG_CONTEXT to 0 is setup.h + A class for performing various debugging and memory tracing operations. + + Full functionality (such as printing out objects currently allocated) is + only present in a debugging build of wxWidgets, i.e. if the __WXDEBUG__ + symbol is defined. wxDebugContext and related functions and macros can be + compiled out by setting wxUSE_DEBUG_CONTEXT to 0 is setup.h @library{wxbase} @category{debugging} - @see Overview() + @see @ref overview_debugging */ class wxDebugContext { @@ -53,8 +30,8 @@ public: checkpoint. @return Returns the number of errors, so a value of zero represents - success. Returns -1 if an error was detected that - prevents further checking. + success. Returns -1 if an error was detected that prevents + further checking. */ int Check(); @@ -70,6 +47,7 @@ public: /** Returns @true if the memory allocator checks all previous memory blocks for errors. + By default, this is @false since it slows down execution considerably. @see SetCheckPrevious() @@ -77,22 +55,25 @@ public: bool GetCheckPrevious(); /** - Returns @true if debug mode is on. If debug mode is on, the wxObject new and - delete - operators store or use information about memory allocation. Otherwise, - a straight malloc and free will be performed by these operators. + Returns @true if debug mode is on. + + If debug mode is on, the wxObject new and delete operators store or use + information about memory allocation. Otherwise, a straight malloc and + free will be performed by these operators. @see SetDebugMode() */ bool GetDebugMode(); /** - Gets the debug level (default 1). The debug level is used by the wxTraceLevel - function and - the WXTRACELEVEL macro to specify how detailed the trace information is; setting - a different level will only have an effect if trace statements in the - application - specify a value other than one. + Gets the debug level (default 1). + + The debug level is used by the wxTraceLevel function and the WXTRACELEVEL + macro to specify how detailed the trace information is; setting a + different level will only have an effect if trace statements in the + application specify a value other than one. + + @deprecated This is obsolete, replaced by wxLog functionality. @see SetLevel() @@ -101,6 +82,8 @@ public: /** Returns the output stream associated with the debug context. + + @deprecated This is obsolete, replaced by wxLog functionality. @see SetStream() @@ -111,6 +94,8 @@ public: Returns a pointer to the output stream buffer associated with the debug context. There may not necessarily be a stream buffer if the stream has been set by the user. + + @deprecated This is obsolete, replaced by wxLog functionality. */ streambuf* GetStreamBuf(); @@ -118,6 +103,8 @@ public: /** Returns @true if there is a stream currently associated with the debug context. + + @deprecated This is obsolete, replaced by wxLog functionality. @see SetStream(), GetStream() @@ -138,9 +125,8 @@ public: allocations is printed, together with the total size. @param detailed - If @true, the function will also print how many - objects of each class have been allocated, and the space taken by - these class instances. + If @true, the function will also print how many objects of each class + have been allocated, and the space taken by these class instances. @see PrintStatistics() */ @@ -160,39 +146,45 @@ public: that have been performed up to this point. @param all - If @true, the checkpoint is reset to include all - memory allocations since the program started. + If @true, the checkpoint is reset to include all memory allocations + since the program started. */ void SetCheckpoint(bool all = false); /** - Sets the debug mode on or off. If debug mode is on, the wxObject new and delete - operators store or use information about memory allocation. Otherwise, - a straight malloc and free will be performed by these operators. + Sets the debug mode on or off. + + If debug mode is on, the wxObject new and delete operators store or use + information about memory allocation. Otherwise, a straight malloc and free + will be performed by these operators. + By default, debug mode is on if __WXDEBUG__ is defined. If the application uses this function, it should make sure that all object memory allocated - is deallocated with the same value of debug mode. Otherwise, the - delete operator might try to look for memory information that does not - exist. + is deallocated with the same value of debug mode. Otherwise, the delete + operator might try to look for memory information that does not exist. @see GetDebugMode() */ void SetDebugMode(bool debug); /** - Sets the current debug file and creates a stream. This will delete any existing - stream and stream buffer. By default, the debug context stream - outputs to the debugger (Windows) or standard error (other platforms). + Sets the current debug file and creates a stream. + This will delete any existing stream and stream buffer. + + By default, the debug context stream outputs to the debugger (Windows) + or standard error (other platforms). */ bool SetFile(const wxString& filename); /** - Sets the debug level (default 1). The debug level is used by the wxTraceLevel - function and - the WXTRACELEVEL macro to specify how detailed the trace information is; setting + Sets the debug level (default 1). + + The debug level is used by the wxTraceLevel function and the WXTRACELEVEL + macro to specify how detailed the trace information is; setting a different level will only have an effect if trace statements in the - application - specify a value other than one. + application specify a value other than one. + + @deprecated This is obsolete, replaced by wxLog functionality. @see GetLevel() @@ -200,10 +192,10 @@ public: void SetLevel(int level); /** - Installs a function to be called at the end of wxWidgets shutdown. It will be - called after - all files with global instances of wxDebugContextDumpDelayCounter have run - their destructors. + Installs a function to be called at the end of wxWidgets shutdown. + It will be called after all files with global instances of + wxDebugContextDumpDelayCounter have run their destructors. + The shutdown function must be take no parameters and return nothing. */ void SetShutdownNotifyFunction(wxShutdownNotifyFunction func); @@ -211,15 +203,19 @@ public: /** Sets the debugging stream to be the debugger (Windows) or standard error (other platforms). + This is the default setting. The existing stream will be flushed and deleted. + + @deprecated This is obsolete, replaced by wxLog functionality. */ bool SetStandardError(); /** Sets the stream and optionally, stream buffer associated with the debug context. - This operation flushes and deletes the existing stream (and stream buffer if - any). + This operation flushes and deletes the existing stream (and stream buffer if any). + + @deprecated This is obsolete, replaced by wxLog functionality. @param stream diff --git a/interface/wx/menu.h b/interface/wx/menu.h index b232d89f4c..efefdb4821 100644 --- a/interface/wx/menu.h +++ b/interface/wx/menu.h @@ -11,22 +11,36 @@ A menu bar is a series of menus accessible from the top of a frame. + @remarks + To respond to a menu selection, provide a handler for EVT_MENU, in the frame + that contains the menu bar. + + If you have a toolbar which uses the same identifiers as your EVT_MENU entries, + events from the toolbar will also be processed by your EVT_MENU event handlers. + + Tip: under Windows, if you discover that menu shortcuts (for example, Alt-F + to show the file menu) are not working, check any EVT_CHAR events you are + handling in child windows. + If you are not calling event.Skip() for events that you don't process in + these event handlers, menu shortcuts may cease to work. + + @library{wxcore} @category{menus} - @see wxMenu, @ref overview_eventhandling "Event Handling Overview" + @see wxMenu, @ref overview_eventhandling */ class wxMenuBar : public wxWindow { public: /** - Construct an empty menu barM + Construct an empty menu bar. @param style If wxMB_DOCKABLE the menu bar can be detached (wxGTK only). */ wxMenuBar(long style = 0); - + /** Construct a menu bar from arrays of menus and titles. @@ -45,8 +59,8 @@ public: long style = 0); /** - Destructor, destroying the menu bar and removing it from the parent frame (if - any). + Destructor, destroying the menu bar and removing it from the parent + frame (if any). */ virtual ~wxMenuBar(); @@ -54,7 +68,7 @@ public: Adds the item to the end of the menu bar. @param menu - The menu to add. Do not deallocate this menu after calling Append. + The menu to add. Do not deallocate this menu after calling Append(). @param title The title of the menu. @@ -116,8 +130,10 @@ public: /** Returns the index of the menu with the given @a title or @c wxNOT_FOUND if no - such menu exists in this menubar. The @a title parameter may specify either - the menu title (with accelerator characters, i.e. @c "File") or just the + such menu exists in this menubar. + + The @a title parameter may specify either the menu title + (with accelerator characters, i.e. @c "&File") or just the menu label (@c "File") indifferently. */ int FindMenu(const wxString& title) const; @@ -176,6 +192,9 @@ public: @remarks Use only after the menubar has been associated with a frame. + @deprecated + This function is deprecated in favour of GetMenuLabel() and GetMenuLabelText(). + @see SetLabelTop() */ wxString GetLabelTop(int pos) const; @@ -225,8 +244,7 @@ public: /** Inserts the menu at the given position into the menu bar. Inserting menu at position 0 will insert it in the very beginning of it, inserting at position - GetMenuCount() is the same as calling - Append(). + GetMenuCount() is the same as calling Append(). @param pos The position of the new menu in the menu bar @@ -267,10 +285,9 @@ public: void Refresh(); /** - Removes the menu from the menu bar and returns the menu object - the caller is - responsible for deleting it. This function may be used together with - Insert() to change the menubar - dynamically. + Removes the menu from the menu bar and returns the menu object - the caller + is responsible for deleting it. This function may be used together with + Insert() to change the menubar dynamically. @see Replace() */ @@ -286,8 +303,8 @@ public: @param title The title of the menu. - @return The menu which was previously at position pos. The caller is - responsible for deleting it. + @return The menu which was previously at position pos. + The caller is responsible for deleting it. @see Insert(), Remove() */ @@ -329,6 +346,9 @@ public: @remarks Use only after the menubar has been associated with a frame. + @deprecated + This function has been deprecated in favour of SetMenuLabel(). + @see GetLabelTop() */ void SetLabelTop(int pos, const wxString& label); @@ -360,20 +380,20 @@ public: with a special identifier -1 is a separator item and doesn't have an associated command but just makes a separator line appear in the menu. - @note Please note that @e wxID_ABOUT and @e wxID_EXIT are - predefined by wxWidgets and have a special meaning since entries - using these IDs will be taken out of the normal menus under MacOS X - and will be inserted into the system menu (following the appropriate - MacOS X interface guideline). On PalmOS @e wxID_EXIT is disabled according - to Palm OS Companion guidelines. - - Menu items may be either normal items, check items or radio items. Normal items - don't have any special properties while the check items have a boolean flag - associated to them and they show a checkmark in the menu when the flag is set. + @note + Please note that @e wxID_ABOUT and @e wxID_EXIT are predefined by wxWidgets + and have a special meaning since entries using these IDs will be taken out + of the normal menus under MacOS X and will be inserted into the system menu + (following the appropriate MacOS X interface guideline). + On PalmOS @e wxID_EXIT is disabled according to Palm OS Companion guidelines. + + Menu items may be either normal items, check items or radio items. + Normal items don't have any special properties while the check items have a + boolean flag associated to them and they show a checkmark in the menu when + the flag is set. wxWidgets automatically toggles the flag value when the item is clicked and its - value may be retrieved using either wxMenu::IsChecked method - of wxMenu or wxMenuBar itself or by using - wxEvent::IsChecked when you get the menu + value may be retrieved using either wxMenu::IsChecked method of wxMenu or + wxMenuBar itself or by using wxEvent::IsChecked when you get the menu notification for the item in question. The radio items are similar to the check items except that all the other items @@ -385,12 +405,32 @@ public: the radio items risks to not work correctly. Finally note that radio items are not supported under Motif. + + @section menu_allocation Allocation strategy + + All menus except the popup ones must be created on the heap. + All menus attached to a menubar or to another menu will be deleted by their + parent when it is deleted. + As the frame menubar is deleted by the frame itself, it means that normally + all menus used are deleted automatically. + + + @section menu_eventhandling Event handling + + If the menu is part of a menubar, then wxMenuBar event processing is used. + With a popup menu, there is a variety of ways to handle a menu selection event + (wxEVT_COMMAND_MENU_SELECTED). + Derive a new class from wxMenu and define event table entries using the EVT_MENU macro. + Set a new event handler for wxMenu, using an object whose class has EVT_MENU entries. + Provide EVT_MENU handlers in the window which pops up the menu, or in an + ancestor of this window. + + @library{wxcore} @category{menus} - @see wxMenuBar, wxWindow::PopupMenu, - @ref overview_eventhandling "Event Handling Overview", - @ref wxFileHistory "wxFileHistory (most recently used files menu)" + @see wxMenuBar, wxWindow::PopupMenu, @ref overview_eventhandling, + @ref wxFileHistory "wxFileHistory (most recently used files menu)" */ class wxMenu : public wxEvtHandler { @@ -404,7 +444,7 @@ public: wxMenu(long style); /** - Constructs a wxMenu object with a title + Constructs a wxMenu object with a title. @param title Title at the top of the menu (not always supported). @@ -412,20 +452,22 @@ public: If set to wxMENU_TEAROFF, the menu will be detachable (wxGTK only). */ wxMenu(const wxString& title = "", long style = 0); - + /** Destructor, destroying the menu. - Note: under Motif, a popup menu must have a valid parent (the window - it was last popped up on) when being destroyed. Therefore, make sure - you delete or re-use the popup menu @e before destroying the - parent window. Re-use in this context means popping up the menu on - a different window from last time, which causes an implicit destruction - and recreation of internal data structures. + + @note + Under Motif, a popup menu must have a valid parent (the window + it was last popped up on) when being destroyed. Therefore, make sure + you delete or re-use the popup menu @e before destroying the parent + window. Re-use in this context means popping up the menu on a different + window from last time, which causes an implicit destruction and + recreation of internal data structures. */ virtual ~wxMenu(); /** - Adds a menu item. + Adds a menu item. @param id The menu command identifier. @@ -436,17 +478,48 @@ public: By default, the handler for the wxEVT_MENU_HIGHLIGHT event displays this string in the status line. @param kind - May be wxITEM_SEPARATOR, wxITEM_NORMAL, - wxITEM_CHECK or wxITEM_RADIO + May be wxITEM_SEPARATOR, wxITEM_NORMAL, wxITEM_CHECK or wxITEM_RADIO + + @remarks + This command can be used after the menu has been shown, as well as on + initial creation of a menu or menubar. + + The item string for the normal menu items (not submenus or separators) + may include the accelerator which can be used to activate the menu item + from keyboard. + The accelerator string follows the item label and is separated from it + by a TAB character ('\\t'). + + Its general syntax is any combination of "CTRL", "ALT" and "SHIFT" strings + (case doesn't matter) separated by either '-' or '+' characters and followed + by the accelerator itself. + The accelerator may be any alphanumeric character, any function key + (from F1 to F12) or one of the special characters listed in the table + below (again, case doesn't matter): + + - DEL or DELETE: Delete key + - INS or INSERT: Insert key + - ENTER or RETURN: Enter key + - PGUP: PageUp key + - PGDN: PageDown key + - LEFT: Left cursor arrow key + - RIGHT: Right cursor arrow key + - UP: Up cursor arrow key + - DOWN: Down cursor arrow key + - HOME: Home key + - END: End key + - SPACE: Space + - TAB: Tab key + - ESC: or ESCAPE Escape key (Windows only) @see AppendSeparator(), AppendCheckItem(), AppendRadioItem(), - AppendSubMenu(), Insert(), SetLabel(), - GetHelpString(), SetHelpString(), wxMenuItem + AppendSubMenu(), Insert(), SetLabel(), GetHelpString(), + SetHelpString(), wxMenuItem */ wxMenuItem* Append(int id, const wxString& item = wxEmptyString, const wxString& helpString = wxEmptyString, wxItemKind kind = wxITEM_NORMAL); - + /** Adds a submenu. @@ -464,25 +537,30 @@ public: this string in the status line. @see AppendSeparator(), AppendCheckItem(), AppendRadioItem(), - AppendSubMenu(), Insert(), SetLabel(), - GetHelpString(), SetHelpString(), wxMenuItem + AppendSubMenu(), Insert(), SetLabel(), GetHelpString(), + SetHelpString(), wxMenuItem */ wxMenuItem* Append(int id, const wxString& item, wxMenu* subMenu, const wxString& helpString = wxEmptyString); - + /** - Adds a menu item object. This is the most generic variant of Append() method - because it may be used for both items (including separators) and submenus and - because you can also specify various extra properties of a menu item this way, + Adds a menu item object. + + This is the most generic variant of Append() method because it may be + used for both items (including separators) and submenus and because + you can also specify various extra properties of a menu item this way, such as bitmaps and fonts. @param menuItem - A menuitem object. It will be owned by the wxMenu object after this function - is called, so do not delete it yourself. + A menuitem object. It will be owned by the wxMenu object after this + function is called, so do not delete it yourself. + + @remarks + See the remarks for the other Append() overloads. @see AppendSeparator(), AppendCheckItem(), AppendRadioItem(), - AppendSubMenu(), Insert(), SetLabel(), - GetHelpString(), SetHelpString(), wxMenuItem + AppendSubMenu(), Insert(), SetLabel(), GetHelpString(), + SetHelpString(), wxMenuItem */ wxMenuItem* Append(wxMenuItem* menuItem); @@ -495,9 +573,9 @@ public: const wxString& helpString = ""); /** - Adds a radio item to the end of the menu. All consequent radio items form a - group and when an item in the group is checked, all the others are - automatically unchecked. + Adds a radio item to the end of the menu. + All consequent radio items form a group and when an item in the group is + checked, all the others are automatically unchecked. @see Append(), InsertRadioItem() */ @@ -520,8 +598,8 @@ public: const wxString& help = wxEmptyString); /** - Inserts a break in a menu, causing the next appended item to appear in a new - column. + Inserts a break in a menu, causing the next appended item to appear in + a new column. */ virtual void Break(); @@ -620,7 +698,7 @@ public: @return Menu item object or NULL if none is found. */ - const wxMenuItem * FindItem(int id, wxMenu** menu = NULL) const; + const wxMenuItem* FindItem(int id, wxMenu** menu = NULL) const; /** Returns the wxMenuItem given a position in the menu. @@ -671,8 +749,10 @@ public: size_t GetMenuItemCount() const; /** - Returns the list of items in the menu. wxMenuItemList is a pseudo-template - list class containing wxMenuItem pointers, see wxList. + Returns the list of items in the menu. + + wxMenuItemList is a pseudo-template list class containing wxMenuItem + pointers, see wxList. */ wxMenuItemList GetMenuItems() const; @@ -687,17 +767,19 @@ public: wxString GetTitle() const; /** - Inserts the given @a item before the position @e pos. Inserting the item - at position GetMenuItemCount() is the same + Inserts the given @a item before the position @a pos. + + Inserting the item at position GetMenuItemCount() is the same as appending it. @see Append(), Prepend() */ wxMenuItem* Insert(size_t pos, wxMenuItem* item); - + /** - Inserts the given @a item before the position @e pos. Inserting the item - at position GetMenuItemCount() is the same + Inserts the given @a item before the position @a pos. + + Inserting the item at position GetMenuItemCount() is the same as appending it. @see Append(), Prepend() @@ -799,8 +881,8 @@ public: /** Removes the menu item from the menu but doesn't delete the associated C++ - object. This allows you to reuse the same item later by adding it back to the menu - (especially useful with submenus). + object. This allows you to reuse the same item later by adding it back to + the menu (especially useful with submenus). @param id The identifier of the menu item to remove. @@ -808,11 +890,11 @@ public: @return A pointer to the item which was detached from the menu. */ wxMenuItem* Remove(int id); - + /** Removes the menu item from the menu but doesn't delete the associated C++ - object. This allows you to reuse the same item later by adding it back to the menu - (especially useful with submenus). + object. This allows you to reuse the same item later by adding it back to + the menu (especially useful with submenus). @param item The menu item to remove. @@ -860,9 +942,10 @@ public: /** Sends events to @a source (or owning window if @NULL) to update the - menu UI. This is called just before the menu is popped up with - wxWindow::PopupMenu, but - the application may call it at other times if required. + menu UI. + + This is called just before the menu is popped up with wxWindow::PopupMenu, + but the application may call it at other times if required. */ void UpdateUI(wxEvtHandler* source = NULL); }; diff --git a/interface/wx/menuitem.h b/interface/wx/menuitem.h index 4b8b36e42a..eb25e171da 100644 --- a/interface/wx/menuitem.h +++ b/interface/wx/menuitem.h @@ -1,6 +1,6 @@ ///////////////////////////////////////////////////////////////////////////// // Name: menuitem.h -// Purpose: interface of wxMenuItem +// Purpose: interface of wxMenu, wxMenuItem // Author: wxWidgets team // RCS-ID: $Id$ // Licence: wxWindows license @@ -9,9 +9,10 @@ /** @class wxMenuItem - A menu item represents an item in a menu. Note that you usually don't have to - deal with it directly as wxMenu methods usually construct an - object of this class for you. + A menu item represents an item in a menu. + + Note that you usually don't have to deal with it directly as wxMenu methods + usually construct an object of this class for you. Also please note that the methods related to fonts and bitmaps are currently only implemented for Windows and GTK+. @@ -26,19 +27,38 @@ class wxMenuItem : public wxObject public: /** Constructs a wxMenuItem object. - Menu items can be standard, or "stock menu items", or custom. For the - standard menu items (such as commands to open a file, exit the program and so - on, see @ref page_stockitems "Stock Items" for the full list) it is enough - to specify just the stock ID and leave @a text and @a helpString empty. In - fact, leaving at least @a text empty for the stock menu items is strongly + + Menu items can be standard, or "stock menu items", or custom. + For the standard menu items (such as commands to open a file, exit the + program and so on, see @ref page_stockitems for the full list) it is enough + to specify just the stock ID and leave @a text and @a helpString empty. + + In fact, leaving at least @a text empty for the stock menu items is strongly recommended as they will have appearance and keyboard interface (including standard accelerators) familiar to the user. + For the custom (non-stock) menu items, @a text must be specified and while @a helpString may be left empty, it's recommended to pass the item - description (which is automatically shown by the library in the status bar when - the menu item is selected) in this parameter. + description (which is automatically shown by the library in the status bar + when the menu item is selected) in this parameter. + Finally note that you can e.g. use a stock menu label without using its stock - help string; that is, stock properties are set independently one from the other. + help string: + + @code + // use all stock properties: + helpMenu->Append(wxID_ABOUT); + + // use the stock label and the stock accelerator but not the stock help string: + helpMenu->Append(wxID_ABOUT, wxEmptyString, wxT("My custom help string")); + + // use all stock properties except for the bitmap: + wxMenuItem *mymenu = new wxMenuItem(helpMenu, wxID_ABOUT); + mymenu->SetBitmap(wxArtProvider::GetBitmap(wxART_WARNING)); + helpMenu->Append(mymenu); + @endcode + + that is, stock properties are set independently one from the other. @param parentMenu Menu that the menu item belongs to. Can be @NULL if the item is @@ -48,14 +68,14 @@ public: case the given kind is ignored and taken to be @c wxITEM_SEPARATOR instead. @param text - Text for the menu item, as shown on the menu. An accelerator - key can be specified using the ampersand " character. In order to embed an + Text for the menu item, as shown on the menu. An accelerator key can + be specified using the ampersand " character. In order to embed an ampersand character in the menu item text, the ampersand must be doubled. @param helpString Optional help string that will be shown on the status bar. @param kind - May be @c wxITEM_SEPARATOR, @c wxITEM_NORMAL, @c wxITEM_CHECK or @c - wxITEM_RADIO + May be @c wxITEM_SEPARATOR, @c wxITEM_NORMAL, @c wxITEM_CHECK or + @c wxITEM_RADIO @param subMenu If non-@NULL, indicates that the menu item is a submenu. */ @@ -108,7 +128,7 @@ public: /** Returns the text associated with the menu item including any accelerator - characters that were passed to the constructor or SetItemLabel. + characters that were passed to the constructor or SetItemLabel(). @see GetItemLabelText(), GetLabelText() */ @@ -131,23 +151,26 @@ public: /** Returns the text associated with the menu item without any accelerator characters it might contain. + @deprecated This function is deprecated in favour of GetItemLabelText(). + @see GetText(), GetLabelFromText() */ wxString GetLabel() const; /** @deprecated This function is deprecated; please use GetLabelText() instead. + @see GetText(), GetLabel() */ static wxString GetLabelFromText(const wxString& text); /** - Strips all accelerator characters and mnemonics from the given @e text. + Strips all accelerator characters and mnemonics from the given @a text. For example: @code - wxMenuItem::GetLabelfromText( "&Hello\tCtrl-h"); + wxMenuItem::GetLabelfromText("&Hello\tCtrl-h"); @endcode will return just @c "Hello". @@ -169,7 +192,9 @@ public: /** Returns the text associated with the menu item. + @deprecated This function is deprecated. Please use + GetItemLabel() or GetItemLabelText() instead. */ wxString GetName() const; @@ -182,7 +207,9 @@ public: /** Returns the text associated with the menu item, such as it was passed to the wxMenuItem constructor, i.e. with any accelerator characters it may contain. + @deprecated This function is deprecated in favour of GetItemLabel(). + @see GetLabel(), GetLabelFromText() */ wxString GetText() const; @@ -223,15 +250,14 @@ public: void SetBackgroundColour(const wxColour& colour) const; /** - Sets the bitmap for the menu item (Windows and GTK+ only). It is - equivalent to wxMenuItem::SetBitmaps(bmp, wxNullBitmap). + Sets the bitmap for the menu item (Windows and GTK+ only). + It is equivalent to wxMenuItem::SetBitmaps(bmp, wxNullBitmap). */ virtual void SetBitmap(const wxBitmap& bmp); /** - Sets the checked/unchecked bitmaps for the menu item (Windows only). The first - bitmap - is also used as the single bitmap for uncheckable menu items. + Sets the checked/unchecked bitmaps for the menu item (Windows only). + The first bitmap is also used as the single bitmap for uncheckable menu items. */ void SetBitmaps(const wxBitmap& checked, const wxBitmap& unchecked = wxNullBitmap); @@ -268,6 +294,7 @@ public: /** Sets the text associated with the menu item. + @deprecated This function is deprecated in favour of SetItemLabel(). */ virtual void SetText(const wxString& text); diff --git a/interface/wx/metafile.h b/interface/wx/metafile.h index a04ec22f49..cb446bface 100644 --- a/interface/wx/metafile.h +++ b/interface/wx/metafile.h @@ -11,20 +11,21 @@ This is a type of device context that allows a metafile object to be created (Windows only), and has most of the characteristics of a normal - @b wxDC. The wxMetafileDC::Close member must be called after drawing into the + @b wxDC. + The wxMetafileDC::Close member must be called after drawing into the device context, to return a metafile. The only purpose for this at - present is to allow the metafile to be copied to the clipboard (see wxMetafile). + present is to allow the metafile to be copied to the clipboard + (see wxMetafile). Adding metafile capability to an application should be easy if you already write to a wxDC; simply pass the wxMetafileDC to your drawing function instead. You may wish to conditionally compile this code so it - is not compiled under X (although no harm will result if you leave it - in). + is not compiled under X (although no harm will result if you leave it in). Note that a metafile saved to disk is in standard Windows metafile format, and cannot be imported into most applications. To make it importable, - call the function ::wxMakeMetafilePlaceable after - closing your disk-based metafile device context. + call the function ::wxMakeMetafilePlaceable after closing your disk-based + metafile device context. @library{wxcore} @category{dc} @@ -35,8 +36,8 @@ class wxMetafileDC : public wxDC { public: /** - Constructor. If no filename is passed, the metafile is created - in memory. + Constructor. + If no filename is passed, the metafile is created in memory. */ wxMetafileDC(const wxString& filename = ""); @@ -46,8 +47,8 @@ public: ~wxMetafileDC(); /** - This must be called after the device context is finished with. A - metafile is returned, and ownership of it passes to the calling + This must be called after the device context is finished with. + A metafile is returned, and ownership of it passes to the calling application (so it should be destroyed explicitly). */ wxMetafile* Close(); @@ -61,11 +62,14 @@ public: A @b wxMetafile represents the MS Windows metafile object, so metafile operations have no effect in X. In wxWidgets, only sufficient functionality has been provided for copying a graphic to the clipboard; this may be extended - in a future version. Presently, the only way of creating a metafile - is to use a wxMetafileDC. + in a future version. + + Presently, the only way of creating a metafile is to use a wxMetafileDC. + + @onlyfor{wxmsw} @library{wxcore} - @category{FIXME} + @category{gdi,misc} @see wxMetafileDC */ @@ -73,16 +77,17 @@ class wxMetafile : public wxObject { public: /** - Constructor. If a filename is given, the Windows disk metafile is - read in. Check whether this was performed successfully by - using the @ref isok() wxMetafile:IsOk member. + Constructor. + + If a filename is given, the Windows disk metafile is read in. + Check whether this was performed successfully by using the IsOk() member. */ wxMetafile(const wxString& filename = ""); /** Destructor. - See @ref overview_refcountdestruct "reference-counted object destruction" for - more info. + + See @ref overview_refcount_destruct for more info. */ ~wxMetafile(); @@ -101,10 +106,25 @@ public: Passes the metafile data to the clipboard. The metafile can no longer be used for anything, but the wxMetafile object must still be destroyed by the application. + Below is a example of metafile, metafile device context and clipboard use from the @c hello.cpp example. Note the way the metafile dimensions are passed to the clipboard, making use of the device context's ability to keep track of the maximum extent of drawing commands. + + @code + wxMetafileDC dc; + if (dc.Ok()) + { + Draw(dc, false); + wxMetafile *mf = dc.Close(); + if (mf) + { + bool success = mf->SetClipboard((int)(dc.MaxX() + 10), (int)(dc.MaxY() + 10)); + delete mf; + } + } + @endcode */ bool SetClipboard(int width = 0, int height = 0); }; diff --git a/interface/wx/mimetype.h b/interface/wx/mimetype.h index 8fbcba7573..ae5abb790e 100644 --- a/interface/wx/mimetype.h +++ b/interface/wx/mimetype.h @@ -13,17 +13,60 @@ MIME types from a system-specific location and the filename extensions to the MIME types and vice versa. After initialization the functions GetFileTypeFromMimeType() and GetFileTypeFromExtension() - may be called: they will return a wxFileType object which - may be further queried for file description, icon and other attributes. + may be called: they will return a wxFileType object which may be further + queried for file description, icon and other attributes. + + Under Windows, the MIME type information is queried from registry. + Under Linux and Unix, it is queried from the XDG data directories. - Under Windows, the MIME type information is queried from registry. Under - Linux and Unix, it is queried from the XDG data directories. - Currently, wxMimeTypesManager is limited to reading MIME type information. - The application should not construct its own manaer: it should use the + The application should not construct its own manager: it should use the object pointer ::wxTheMimeTypesManger. + + @section mimetypemanager_helpers Helper functions + + All of these functions are static (i.e. don't need a wxMimeTypesManager object + to call them) and provide some useful operations for string representations of + MIME types. Their usage is recommended instead of directly working with MIME + types using wxString functions. + + - wxMimeTypesManager::IsOfType() + + + @section mimetypemanager_ctor Constructor and destructor + + NB: You won't normally need to use more than one wxMimeTypesManager object + in a program. + + - wxMimeTypesManager::wxMimeTypesManager() + - wxMimeTypesManager::~wxMimeTypesManager() + + + @section mimetypemanager_query Query database + + These functions are the heart of this class: they allow to find a file type + object from either file extension or MIME type. + If the function is successful, it returns a pointer to the wxFileType object + which must be deleted by the caller, otherwise NULL will be returned. + + - wxMimeTypesManager::GetFileTypeFromMimeType() + - wxMimeTypesManager::GetFileTypeFromExtension() + + + @section mimetypemanager_init Initialization functions + + Unix: These functions may be used to load additional files (except for the + default ones which are loaded automatically) containing MIME information in + either mailcap(5) or mime.types(5) format. + + - wxMimeTypesManager::ReadMailcap() + - wxMimeTypesManager::ReadMimeTypes() + - wxMimeTypesManager::AddFallbacks() + + + @library{wxbase} @category{misc} @@ -52,7 +95,7 @@ public: /** Gather information about the files with given extension and return the corresponding wxFileType object or @NULL if the extension is unknown. - + The @a extension parameter may have, or not, the leading dot, if it has it, it is stripped automatically. It must not however be empty. */ @@ -66,15 +109,15 @@ public: /** - This function returns @true if either the given @a mimeType is exactly the - same as @a wildcard or if it has the same category and the subtype of + This function returns @true if either the given @a mimeType is exactly + the same as @a wildcard or if it has the same category and the subtype of @a wildcard is '*'. Note that the '*' wildcard is not allowed in @a mimeType itself. + The comparison don by this function is case insensitive so it is not necessary to convert the strings to the same case before calling it. */ static bool IsOfType(const wxString& mimeType, const wxString& wildcard); - }; @@ -87,12 +130,14 @@ wxMimeTypesManager* wxTheMimeTypesManager; /** @class wxFileType - This class holds information about a given @e file type. File type is the same - as - MIME type under Unix, but under Windows it corresponds more to an extension than - to MIME type (in fact, several extensions may correspond to a file type). This - object may be created in several different ways: the program might know the file - extension and wish to find out the corresponding MIME type or, conversely, it + This class holds information about a given @e file type. + + File type is the same as MIME type under Unix, but under Windows it corresponds + more to an extension than to MIME type (in fact, several extensions may + correspond to a file type). + + This object may be created in several different ways: the program might know the + file extension and wish to find out the corresponding MIME type or, conversely, it might want to find the right extension for the file to which it writes the contents of given MIME type. Depending on how it was created some fields may be unknown so the return value of all the accessors @b must be checked: @false @@ -116,8 +161,74 @@ wxMimeTypesManager* wxTheMimeTypesManager; typically correspond to the extension ".txt", but may as well be associated with ".ini" or ".conf". + + @section filetype_example MessageParameters class + + One of the most common usages of MIME is to encode an e-mail message. + The MIME type of the encoded message is an example of a message parameter. + These parameters are found in the message headers ("Content-XXX"). + + At the very least, they must specify the MIME type and the version of MIME + used, but almost always they provide additional information about the message + such as the original file name or the charset (for the text documents). + These parameters may be useful to the program used to open, edit, view or + print the message, so, for example, an e-mail client program will have to + pass them to this program. Because wxFileType itself can not know about + these parameters, it uses MessageParameters class to query them. + + The default implementation only requires the caller to provide the file name + (always used by the program to be called - it must know which file to open) + and the MIME type and supposes that there are no other parameters. + + If you wish to supply additional parameters, you must derive your own class + from MessageParameters and override GetParamValue() function, for example: + + @code + // provide the message parameters for the MIME type manager + class MailMessageParameters : public wxFileType::MessageParameters + { + public: + MailMessageParameters(const wxString& filename, + const wxString& mimetype) + : wxFileType::MessageParameters(filename, mimetype) + { + } + + virtual wxString GetParamValue(const wxString& name) const + { + // parameter names are not case-sensitive + if ( name.CmpNoCase("charset") == 0 ) + return "US-ASCII"; + else + return wxFileType::MessageParameters::GetParamValue(name); + } + }; + @endcode + + Now you only need to create an object of this class and pass it to, for example, + GetOpenCommand like this: + + @code + wxString command; + if ( filetype->GetOpenCommand(&command, + MailMessageParameters("foo.txt", "text/plain")) ) + { + // the full command for opening the text documents is in 'command' + // (it might be "notepad foo.txt" under Windows or "cat foo.txt" under Unix) + } + else + { + // we don't know how to handle such files... + } + @endcode + + Windows: As only the file name is used by the program associated with the + given extension anyhow (but no other message parameters), there is no need + to ever derive from MessageParameters class for a Windows-only program. + + @library{wxbase} - @category{FIXME} + @category{misc} @see wxMimeTypesManager */ @@ -137,30 +248,19 @@ public: /** This function is primarily intended for GetOpenCommand and GetPrintCommand - usage but may be also used by the application directly if, for example, you want - to use some non-default command to open the file. - The function replaces all occurrences of - - format specification - - with - - %s - - the full file name - - %t - - the MIME type - - %{param} - - the value of the parameter @e param + usage but may be also used by the application directly if, for example, you + want to use some non-default command to open the file. + The function replaces all occurrences of: + - %s with the full file name + - %t with the MIME type + - %{param} with the value of the parameter @e param using the MessageParameters object you pass to it. + If there is no '%s' in the command string (and the string is not empty), it is assumed that the command reads the data on stdin and so the effect is the same as " %s" were appended to the string. + Unlike all other functions of this class, there is no error return for this function. */ @@ -177,24 +277,27 @@ public: /** If the function returns @true, the array @a extensions is filled with all extensions associated with this file type: for example, it may - contain the following two elements for the MIME type "text/html" (notice the - absence of the leading dot): "html" and "htm". + contain the following two elements for the MIME type "text/html" + (notice the absence of the leading dot): "html" and "htm". + @b Windows: This function is currently not implemented: there is no - (efficient) way to retrieve associated extensions from the given MIME type on - this platform, so it will only return @true if the wxFileType object was - created - by wxMimeTypesManager::GetFileTypeFromExtension - function in the first place. + (efficient) way to retrieve associated extensions from the given MIME type + on this platform, so it will only return @true if the wxFileType object was + created by wxMimeTypesManager::GetFileTypeFromExtension function in the + first place. */ bool GetExtensions(wxArrayString& extensions); /** If the function returns @true, the @c iconLoc is filled with the - location of the icon for this MIME type. A wxIcon may be - created from @a iconLoc later. + location of the icon for this MIME type. + A wxIcon may be created from @a iconLoc later. + @b Windows: The function returns the icon shown by Explorer for the files of the specified type. + @b Mac: This function is not implemented and always returns @false. + @b Unix: MIME manager gathers information about icons from GNOME and KDE settings and thus GetIcon's success depends on availability of these desktop environments. @@ -208,11 +311,12 @@ public: bool GetMimeType(wxString* mimeType) const; /** - Same as GetMimeType() but returns array of MIME - types. This array will contain only one item in most cases but sometimes, - notably under Unix with KDE, may contain more MIME types. This happens when - one file extension is mapped to different MIME types by KDE, mailcap and - mime.types. + Same as GetMimeType() but returns array of MIME types. + + This array will contain only one item in most cases but sometimes, + notably under Unix with KDE, may contain more MIME types. + This happens when one file extension is mapped to different MIME types + by KDE, mailcap and mime.types. */ bool GetMimeType(wxArrayString& mimeTypes); @@ -220,52 +324,27 @@ public: /** With the first version of this method, if the @true is returned, the string pointed to by @a command is filled with the command which must be - executed (see wxExecute()) in order to open the file of the - given type. In this case, the name of the file as well as any other parameters - is retrieved from MessageParameters() - class. + executed (see wxExecute()) in order to open the file of the given type. + + In this case, the name of the file as well as any other parameters + is retrieved from MessageParameters() class. + In the second case, only the filename is specified and the command to be used to open this kind of file is returned directly. An empty string is returned to indicate that an error occurred (typically meaning that there is no standard way to open this kind of files). */ - bool GetOpenCommand(wxString* command, - MessageParameters& params); + bool GetOpenCommand(wxString* command, MessageParameters& params); wxString GetOpenCommand(const wxString& filename); //@} /** If the function returns @true, the string pointed to by @a command is filled - with the command which must be executed (see wxExecute()) in - order to print the file of the given type. The name of the file is - retrieved from MessageParameters() class. - */ - bool GetPrintCommand(wxString* command, - MessageParameters& params); + with the command which must be executed (see wxExecute()) in order to + print the file of the given type. - /** - One of the most common usages of MIME is to encode an e-mail message. The MIME - type of the encoded message is an example of a @e message parameter. These - parameters are found in the message headers ("Content-XXX"). At the very least, - they must specify the MIME type and the version of MIME used, but almost always - they provide additional information about the message such as the original file - name or the charset (for the text documents). - These parameters may be useful to the program used to open, edit, view or print - the message, so, for example, an e-mail client program will have to pass them to - this program. Because wxFileType itself can not know about these parameters, - it uses MessageParameters class to query them. The default implementation only - requires the caller to provide the file name (always used by the program to be - called - it must know which file to open) and the MIME type and supposes that - there are no other parameters. If you wish to supply additional parameters, you - must derive your own class from MessageParameters and override GetParamValue() - function, for example: - - Now you only need to create an object of this class and pass it to, for example, - GetOpenCommand() like this: - - @b Windows: As only the file name is used by the program associated with the - given extension anyhow (but no other message parameters), there is no need to - ever derive from MessageParameters class for a Windows-only program. + The name of the file is retrieved from the MessageParameters class. */ + bool GetPrintCommand(wxString* command, MessageParameters& params); }; diff --git a/interface/wx/minifram.h b/interface/wx/minifram.h index ef4363a8d9..0d2d310d0d 100644 --- a/interface/wx/minifram.h +++ b/interface/wx/minifram.h @@ -9,41 +9,44 @@ /** @class wxMiniFrame - A miniframe is a frame with a small title bar. It is suitable for floating - toolbars that must not - take up too much screen area. + A miniframe is a frame with a small title bar. + It is suitable for floating toolbars that must not take up too much screen area. - An example of mini frame can be seen in the @ref overview_sampledialogs - "dialogs sample" + An example of mini frame can be seen in the @ref page_samples_dialogs using the "Mini frame" command of the "Generic dialogs" submenu. @beginStyleTable @style{wxICONIZE} - Display the frame iconized (minimized) (Windows only). + Display the frame iconized (minimized) (Windows only). @style{wxCAPTION} - Puts a caption on the frame. + Puts a caption on the frame. @style{wxMINIMIZE} - Identical to wxICONIZE. + Identical to wxICONIZE. @style{wxMINIMIZE_BOX} - Displays a minimize box on the frame (Windows and Motif only). + Displays a minimize box on the frame (Windows and Motif only). @style{wxMAXIMIZE} - Displays the frame maximized (Windows only). + Displays the frame maximized (Windows only). @style{wxMAXIMIZE_BOX} - Displays a maximize box on the frame (Windows and Motif only). + Displays a maximize box on the frame (Windows and Motif only). @style{wxCLOSE_BOX} - Displays a close box on the frame. + Displays a close box on the frame. @style{wxSTAY_ON_TOP} - Stay on top of other windows (Windows only). + Stay on top of other windows (Windows only). @style{wxSYSTEM_MENU} - Displays a system menu (Windows and Motif only). + Displays a system menu (Windows and Motif only). @style{wxTINY_CAPTION_HORIZ} - This style is obsolete and not used any longer. + This style is obsolete and not used any longer. @style{wxTINY_CAPTION_VERT} - This style is obsolete and not used any longer. + This style is obsolete and not used any longer. @style{wxRESIZE_BORDER} - Displays a resizeable border around the window. + Displays a resizeable border around the window. @endStyleTable + @remarks + This class has miniframe functionality under Windows and GTK, i.e. the presence + of mini frame will not be noted in the task bar and focus behaviour is different. + On other platforms, it behaves like a normal frame. + @library{wxcore} @category{managedwnd} @@ -52,7 +55,11 @@ class wxMiniFrame : public wxFrame { public: - //@{ + /** + Default ctor. + */ + wxMiniFrame(); + /** Constructor, creating the window. @@ -60,37 +67,32 @@ public: The window parent. This may be @NULL. If it is non-@NULL, the frame will always be displayed on top of the parent window on Windows. @param id - The window identifier. It may take a value of -1 to indicate a default - value. + The window identifier. It may take a value of -1 to indicate a default value. @param title The caption to be displayed on the frame's title bar. @param pos The window position. The value wxDefaultPosition indicates a default position, - chosen by - either the windowing system or wxWidgets, depending on platform. + chosen by either the windowing system or wxWidgets, depending on platform. @param size The window size. The value wxDefaultSize indicates a default size, chosen by either the windowing system or wxWidgets, depending on platform. @param style The window style. See wxMiniFrame. @param name - The name of the window. This parameter is used to associate a name with the - item, - allowing the application user to set Motif resource values for + The name of the window. This parameter is used to associate a name with + the item, allowing the application user to set Motif resource values for individual windows. @remarks The frame behaves like a normal frame on non-Windows platforms. @see Create() */ - wxMiniFrame(); wxMiniFrame(wxWindow* parent, wxWindowID id, const wxString& title, const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, long style = wxCAPTION | wxRESIZE_BORDER, const wxString& name = "frame"); - //@} /** Destructor. Destroys all child windows and menu bar if present. @@ -98,8 +100,8 @@ public: virtual ~wxMiniFrame(); /** - Used in two-step frame construction. See wxMiniFrame() - for further details. + Used in two-step frame construction. + See wxMiniFrame() for further details. */ bool Create(wxWindow* parent, wxWindowID id, const wxString& title, diff --git a/interface/wx/module.h b/interface/wx/module.h index 1cd5717e16..4e72b4ec6f 100644 --- a/interface/wx/module.h +++ b/interface/wx/module.h @@ -14,19 +14,19 @@ automatically called on wxWidgets startup and exit. To define a new kind of module, derive a class from wxModule, override the - wxModule::OnInit and wxModule::OnExit - functions, and add the DECLARE_DYNAMIC_CLASS and IMPLEMENT_DYNAMIC_CLASS to - header and implementation files (which can be the same file). On - initialization, wxWidgets will find all classes derived from wxModule, create - an instance of each, and call each OnInit function. On exit, wxWidgets will - call the OnExit function for each module instance. + wxModule::OnInit and wxModule::OnExit functions, and add the + DECLARE_DYNAMIC_CLASS and IMPLEMENT_DYNAMIC_CLASS to header and implementation + files (which can be the same file). + On initialization, wxWidgets will find all classes derived from wxModule, create + an instance of each, and call each wxModule::OnInit function. On exit, wxWidgets + will call the wxModule::OnExit function for each module instance. Note that your module class does not have to be in a header file. For example: @code - // A module to allow DDE initialization/cleanup + // A module to allow DDE initialization/cleanup // without calling these functions from app.cpp or from // the user's application. class wxDDEModule: public wxModule @@ -73,7 +73,7 @@ @endcode @library{wxbase} - @category{FIXME} + @category{misc} */ class wxModule : public wxObject { @@ -88,27 +88,32 @@ public: */ virtual ~wxModule(); - //@{ /** - Call this function from the constructor of the derived class. @a dep must be - the CLASSINFO() of a wxModule-derived class and the - corresponding module will be loaded before and unloaded after - this module. - The second version of this function allows a dependency to be added by - name without access to the class info. This is useful when a module is - declared entirely in a source file and there is no header for the declaration - of the module needed by CLASSINFO(), however errors are - not detected until run-time, instead of compile-time, then. - Note that circular dependencies are detected and result in a fatal error. + Call this function from the constructor of the derived class. + + @a dep must be the CLASSINFO() of a wxModule-derived class and the + corresponding module will be loaded before and unloaded after this module. @param dep The class information object for the dependent module. + */ + void AddDependency(wxClassInfo* dep); + + /** + Call this function from the constructor of the derived class. + + This overload allows a dependency to be added by name without access to + the class info. + + This is useful when a module is declared entirely in a source file and + there is no header for the declaration of the module needed by CLASSINFO(), + however errors are not detected until run-time, instead of compile-time, then. + Note that circular dependencies are detected and result in a fatal error. + @param classname The class name of the dependent module. */ - void AddDependency(wxClassInfo* dep); void AddDependency(const char* classname); - //@} /** Provide this function with appropriate cleanup for your module. @@ -116,9 +121,8 @@ public: virtual void OnExit(); /** - Provide this function with appropriate initialization for your module. If the - function - returns @false, wxWidgets will exit immediately. + Provide this function with appropriate initialization for your module. + If the function returns @false, wxWidgets will exit immediately. */ virtual bool OnInit(); }; diff --git a/interface/wx/mousestate.h b/interface/wx/mousestate.h index 0632791564..a5d21a9593 100644 --- a/interface/wx/mousestate.h +++ b/interface/wx/mousestate.h @@ -21,6 +21,7 @@ This class is implemented entirely inline in @ and thus has no linking requirements. + @nolibrary @category{misc} @see wxGetMouseState(), wxMouseEvent @@ -37,10 +38,12 @@ public: Returns X coordinate of the physical mouse event position. */ wxCoord GetX() const; + /** Returns Y coordinate of the physical mouse event position. */ wxCoord GetY() const; + /** Returns the physical mouse position. */ @@ -50,18 +53,22 @@ public: Returns @true if the left mouse button changed to down. */ bool LeftDown() const; + /** Returns @true if the middle mouse button changed to down. */ bool MiddleDown() const; + /** Returns @true if the right mouse button changed to down. */ bool RightDown() const; + /** Returns @true if the first extra button mouse button changed to down. */ bool Aux1Down() const; + /** Returns @true if the second extra button mouse button changed to down. */ diff --git a/interface/wx/msgdlg.h b/interface/wx/msgdlg.h index e2693fe911..a868777134 100644 --- a/interface/wx/msgdlg.h +++ b/interface/wx/msgdlg.h @@ -15,14 +15,13 @@ @library{wxcore} @category{cmndlg} - @see @ref overview_wxmessagedialogoverview "wxMessageDialog overview" + @see @ref overview_cmndlg_msg */ class wxMessageDialog : public wxDialog { public: /** Constructor specifying the message box properties. - Use ShowModal() to show the dialog. @a style may be a bit list of the following identifiers: @@ -56,8 +55,7 @@ public: wxICON_ERROR. @style{wxICON_QUESTION} Displays a question mark symbol. This icon is automatically used - with @c wxYES_NO so it's usually unnecessary to specify it - explicitly. + with @c wxYES_NO so it's usually unnecessary to specify it explicitly. @style{wxICON_INFORMATION} Displays an information symbol. This icon is used by default if @c wxYES_NO is not given so it is usually unnecessary to specify it @@ -67,8 +65,8 @@ public: implemented only under MSW). @endStyleTable - Notice that not all styles are compatible: only one of @c wxOK and @c - wxYES_NO may be specified (and one of them must be specified) and at + Notice that not all styles are compatible: only one of @c wxOK and + @c wxYES_NO may be specified (and one of them must be specified) and at most one default button style can be used and it is only valid if the corresponding button is shown in the message box. @@ -161,8 +159,7 @@ public: virtual bool SetYesNoLabels(const ButtonLabel& yes, const ButtonLabel& no); /** - Shows the dialog, returning one of wxID_OK, wxID_CANCEL, wxID_YES, - wxID_NO. + Shows the dialog, returning one of wxID_OK, wxID_CANCEL, wxID_YES, wxID_NO. Notice that this method returns the identifier of the button which was clicked unlike wxMessageBox() function. diff --git a/interface/wx/msgqueue.h b/interface/wx/msgqueue.h index 35af235e01..5a6347f794 100644 --- a/interface/wx/msgqueue.h +++ b/interface/wx/msgqueue.h @@ -11,22 +11,28 @@ wxMessageQueue allows passing messages between threads. This class should be typically used to communicate between the main and worker - threads. The main thread calls wxMessageQueue::Post and - the worker thread calls wxMessageQueue::Receive. + threads. The main thread calls wxMessageQueue::Post and the worker thread + calls wxMessageQueue::Receive. - For this class a message is an object of arbitrary type T. Notice that - often there is a some special message indicating that the thread + For this class a message is an object of arbitrary type T. + Notice that often there is a some special message indicating that the thread should terminate as there is no other way to gracefully shutdown a thread waiting on the message queue. @nolibrary - @category{FIXME} + @category{misc} @see wxThread */ class wxMessageQueue { public: + /** + Default and only constructor. + Use wxMessageQueue::IsOk to check if the object was successfully initialized. + */ + wxMessageQueue(); + /** Returns @true if the object had been initialized successfully, @false if an error occurred. @@ -37,32 +43,31 @@ public: Add a message to this queue and signal the threads waiting for messages (i.e. the threads which called wxMessageQueue::Receive or wxMessageQueue::ReceiveTimeout). + This method is safe to call from multiple threads in parallel. */ wxMessageQueueError Post(T const& msg); /** - Block until a message becomes available in the queue. Waits indefinitely long - or until an error occurs. - The message is returned in @e msg. + Block until a message becomes available in the queue. + Waits indefinitely long or until an error occurs. + + The message is returned in @a msg. */ wxMessageQueueError Receive(T& msg); /** Block until a message becomes available in the queue, but no more than @a timeout milliseconds has elapsed. + If no message is available after @a timeout milliseconds then returns @b wxMSGQUEUE_TIMEOUT. + If @a timeout is 0 then checks for any messages present in the queue and returns immediately without waiting. - The message is returned in @e msg. - */ - wxMessageQueueError ReceiveTimeout(long timeout, T& msg); - /** - Default and only constructor. Use wxMessageQueue::IsOk to check - if the object was successfully initialized. + The message is returned in @a msg. */ - wxMessageQueue(); + wxMessageQueueError ReceiveTimeout(long timeout, T& msg); }; diff --git a/interface/wx/mstream.h b/interface/wx/mstream.h index 641e5fecaf..a606dbdb38 100644 --- a/interface/wx/mstream.h +++ b/interface/wx/mstream.h @@ -9,6 +9,7 @@ /** @class wxMemoryOutputStream + @todo describe me. @library{wxbase} @category{streams} @@ -21,6 +22,9 @@ public: /** If @a data is @NULL, then it will initialize a new empty buffer which will grow if required. + + @warning + If the buffer is created, it will be destroyed at the destruction of the stream. */ wxMemoryOutputStream(char* data = NULL, size_t length = 0); @@ -30,9 +34,8 @@ public: virtual ~wxMemoryOutputStream(); /** - CopyTo allowed you to transfer data from the internal buffer of - wxMemoryOutputStream to an external buffer. @a len specifies the size of - the buffer. + Allows you to transfer data from the internal buffer of wxMemoryOutputStream + to an external buffer. @a len specifies the size of the buffer. */ size_t CopyTo(char* buffer, size_t len) const; @@ -48,6 +51,7 @@ public: /** @class wxMemoryInputStream + @todo describe me. @library{wxbase} @category{streams} @@ -57,19 +61,29 @@ public: class wxMemoryInputStream : public wxInputStream { public: - //@{ /** - Creates a new read-only memory stream, initializing it with the - data from the given input stream @e stream. - The @a len argument specifies the amount of data to read from - the @e stream. Setting it to @e wxInvalidOffset means that - the @a stream is to be read entirely (i.e. till the EOF is reached). + Initializes a new read-only memory stream which will use the specified + buffer data of length len. The stream does not take ownership of the buffer, + i.e. the buffer will not be deleted in its destructor. */ wxMemoryInputStream(const char* data, size_t len); + + /** + Creates a new read-only memory stream, initializing it with the data from + the given output stream @a stream. + */ wxMemoryInputStream(const wxMemoryOutputStream& stream); + + /** + Creates a new read-only memory stream, initializing it with the + data from the given input stream @a stream. + + The @a len argument specifies the amount of data to read from the + @a stream. Setting it to @e wxInvalidOffset means that the @a stream + is to be read entirely (i.e. till the EOF is reached). + */ wxMemoryInputStream(wxInputStream& stream, wxFileOffset len = wxInvalidOffset); - //@} /** Destructor. -- 2.45.2