Amebis/wxWidgets
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

revised m*h headers

Browse Source 
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@56227 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
This commit is contained in:
Francesco Montorsi
2008-10-11 13:10:48 +00:00
parent bd412bc6b6
commit ba1d7a6cec
13 changed files with 727 additions and 448 deletions
Download Patch File Download Diff File Expand all files Collapse all files

39
interface/wx/mdi.h
View File

@@ -8,14 +8,10 @@
/** /**
@class wxMDIClientWindow @class wxMDIClientWindow
@wxheader{mdi.h}
An MDI client window is a child of wxMDIParentFrame, and manages zero or An MDI client window is a child of wxMDIParentFrame, and manages zero or
more wxMDIChildFrame objects. more wxMDIChildFrame objects.
@library{wxcore}
@category{managedwnd}
@remarks @remarks
The client window is the area where MDI child windows exist. It doesn't have to 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 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. when the active child is not maximized, and no border style when a child is maximized.
@library{wxcore}
@category{managedwnd}
@see wxMDIChildFrame, wxMDIParentFrame, wxFrame @see wxMDIChildFrame, wxMDIParentFrame, wxFrame
*/ */
class wxMDIClientWindow : public wxWindow class wxMDIClientWindow : public wxWindow
@@ -73,7 +72,6 @@ public:
/** /**
@class wxMDIParentFrame @class wxMDIParentFrame
@wxheader{mdi.h}
An MDI (Multiple Document Interface) parent frame is a window which can contain 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 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 @remarks During the construction of the frame, the client window will be
created. To use a different class from wxMDIClientWindow, override created. To use a different class from wxMDIClientWindow, override
OnCreateClient(). 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() @see Create(), OnCreateClient()
*/ */
@@ -220,8 +221,8 @@ public:
virtual void Cascade(); virtual void Cascade();
/** /**
Used in two-step frame construction. See wxMDIParentFrame() Used in two-step frame construction.
for further details. See wxMDIParentFrame() for further details.
*/ */
bool Create(wxWindow* parent, wxWindowID id, bool Create(wxWindow* parent, wxWindowID id,
const wxString& title, const wxString& title,
@@ -316,7 +317,7 @@ public:
Note that it is probably impossible to have a client window that scrolls 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 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 @see GetClientWindow(), wxMDIClientWindow
*/ */
@@ -353,8 +354,8 @@ public:
virtual void SetToolBar(wxWindow* toolbar); virtual void SetToolBar(wxWindow* toolbar);
/** /**
Call this to change the current Window menu. Ownership of the menu object Call this to change the current Window menu.
passes to the frame when you call this function. Ownership of the menu object passes to the frame when you call this function.
This call is available under Windows only. This call is available under Windows only.
@@ -375,7 +376,6 @@ public:
/** /**
@class wxMDIChildFrame @class wxMDIChildFrame
@wxheader{mdi.h}
An MDI child frame is a frame that can only exist on a wxMDIClientWindow, An MDI child frame is a frame that can only exist on a wxMDIClientWindow,
which is itself a child of wxMDIParentFrame. which is itself a child of wxMDIParentFrame.
@@ -407,6 +407,19 @@ public:
Displays a thick frame around the window (Windows and Motif only). Displays a thick frame around the window (Windows and Motif only).
@endStyleTable @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} @library{wxcore}
@category{managedwnd} @category{managedwnd}
@@ -466,8 +479,8 @@ public:
virtual void Activate(); virtual void Activate();
/** /**
Used in two-step frame construction. See wxMDIChildFrame() Used in two-step frame construction.
for further details. See wxMDIChildFrame() for further details.
*/ */
bool Create(wxWindow* parent, wxWindowID id, bool Create(wxWindow* parent, wxWindowID id,
const wxString& title, const wxString& title,

186
interface/wx/mediactrl.h
View File

@@ -65,19 +65,15 @@ public:
/** /**
@class wxMediaCtrl @class wxMediaCtrl
wxMediaCtrl is a class for displaying types of wxMediaCtrl is a class for displaying types of media, such as videos, audio
media, such as videos, audio files, natively through native codecs. files, natively through native codecs.
wxMediaCtrl uses native backends to render media, for example on Windows wxMediaCtrl uses native backends to render media, for example on Windows
there is a ActiveMovie/DirectShow backend, and on Macintosh there is a there is a ActiveMovie/DirectShow backend, and on Macintosh there is a
QuickTime backend. QuickTime backend.
@library{wxmedia}
@category{media}
@see wxMediaEvent @section mediactrl_rendering_media Rendering media
@section class_mediactrl_rendering_media Rendering media
Depending upon the backend, wxMediaCtrl can render and display pretty much any 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 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 of the backend. For example, QuickTime cannot set the playback rate of certain
streaming media - while DirectShow is slightly more flexible in that regard. 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 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, (currently the end of the file/stream). Right before it hits the end of the stream,
@@ -120,85 +116,120 @@ public:
} }
@endcode @endcode
When wxMediaCtrl stops, either by the @c EVT_MEDIA_STOP not being vetoed, or by manually When wxMediaCtrl stops, either by the @c EVT_MEDIA_STOP not being vetoed, or
calling Stop(), where it actually stops is not at the beginning, rather, but at the beginning by manually calling Stop(), where it actually stops is not at the beginning,
of the stream. That is, when it stops and play is called, playback is gauranteed to start at rather, but at the beginning of the stream. That is, when it stops and play
the beginning of the media. This is because some streams are not seekable, and when stop is is called, playback is gauranteed to start at the beginning of the media.
called on them they return to the beginning, thus wxMediaCtrl tries to keep consistant for all types This is because some streams are not seekable, and when stop is called on
of media. 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 Note that when changing the state of the media through Play() and other methods,
actually be in the @c wxMEDIASTATE_PLAYING, for example. If you are relying on the media being in the media may not actually be in the @c wxMEDIASTATE_PLAYING, for example.
certain state catch the event relevant to the state. See wxMediaEvent for the kinds of events that If you are relying on the media being in certain state catch the event relevant
you can catch. 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 @section mediactrl_video_size Video size
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 By default, wxMediaCtrl will scale the size of the video to the requested
function that is called when sizers on a window recalculate. What this means is that if you use sizers amount passed to either its constructor or Create().
by default the video will show in its original size without any extra assistance needed from the user. 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().
@section class_mediactrl_player_controls Player controls 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.
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 @section mediactrl_player_controls Player controls
Generally, you should almost certainly leave this part up to wxMediaCtrl - but if you need a certain backend Normally, when you use wxMediaCtrl it is just a window for the video to play in.
for a particular reason, such as QuickTime for playing .mov files, all you need to do to choose a specific However, some toolkits have their own media player interface.
backend is to pass the name of the backend class to Create(). 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: The following are valid backend identifiers:
@beginTable - @b wxMEDIABACKEND_DIRECTSHOW: Use ActiveMovie/DirectShow.
@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.} Uses the native ActiveMovie (I.E. DirectShow) control.
@row2col{@b wxMEDIABACKEND_QUICKTIME, Use QuickTime. Mac Only. WARNING: May not working correctly embedded in a wxNotebook.} Default backend on Windows and supported by nearly all Windows versions,
@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.} even some Windows CE versions.
@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} May display a windows media player logo while inactive.
@endTable - @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/). Note that other backends such as wxMEDIABACKEND_MCI can now be found at
wxCode (http://wxcode.sourceforge.net/).
@section class_mediactrl_creating_backend Creating a backend
Creating a backend for wxMediaCtrl is a rather simple process. Simply derive from wxMediaBackendCommonBase @section mediactrl_creating_backend Creating a backend
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 Creating a backend for wxMediaCtrl is a rather simple process.
needed you may simply call wxControl::Create(). 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().
You need to make sure to use the @c DECLARE_CLASS and @c IMPLEMENT_CLASS macros. 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 The only real tricky part is that you need to make sure the file in compiled in,
just backends in there will not happen and you may need to use a force link hack which if there are just backends in there will not happen and you may need to
(see http://www.wxwidgets.org/wiki/index.php/RTTI). use a force link hack (see http://www.wxwidgets.org/wiki/index.php/RTTI).
This is a rather simple example of how to create a backend in the wxActiveXContainer documentation. This is a rather simple example of how to create a backend in the
wxActiveXContainer documentation.
@library{wxmedia}
@category{media}
@see wxMediaEvent
*/ */
class wxMediaCtrl : public wxControl class wxMediaCtrl : public wxControl
{ {
public: 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(); wxMediaCtrl();
/** /**
Constructor that calls Create(). You may prefer to call Create() directly to check Constructor that calls Create().
to see if wxMediaCtrl is available on the system. You may prefer to call Create() directly to check to see if
wxMediaCtrl is available on the system.
@param parent @param parent
parent of this control. Must not be @NULL. parent of this control. Must not be @NULL.
@@ -213,8 +244,7 @@ public:
@param style @param style
Optional styles. Optional styles.
@param szBackend @param szBackend
Name of backend you want to use, leave blank to make Name of backend you want to use, leave blank to make wxMediaCtrl figure it out.
wxMediaCtrl figure it out.
@param validator @param validator
validator to use. validator to use.
@param name @param name
@@ -226,14 +256,14 @@ public:
const wxValidator& validator = wxDefaultValidator, const wxValidator& validator = wxDefaultValidator,
const wxString& name = wxPanelNameStr); 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. 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 If you specify a file to open via @a fileName and you don't specify a
use, wxMediaCtrl tries each of its backends until one that can render the path referred to backend to use, wxMediaCtrl tries each of its backends until one that
by @a fileName can be found. can render the path referred to by @a fileName can be found.
@param parent @param parent
parent of this control. Must not be @NULL. parent of this control. Must not be @NULL.
@@ -248,8 +278,7 @@ public:
@param style @param style
Optional styles. Optional styles.
@param szBackend @param szBackend
Name of backend you want to use, leave blank to make Name of backend you want to use, leave blank to make wxMediaCtrl figure it out.
wxMediaCtrl figure it out.
@param validator @param validator
validator to use. validator to use.
@param name @param name
@@ -263,7 +292,8 @@ public:
/** /**
Obtains the best size relative to the original/natural size of the 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(); wxSize GetBestSize();
@@ -290,8 +320,8 @@ public:
/** /**
Gets the volume of the media from a 0.0 to 1.0 range. 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 @note Due to rounding and other errors the value returned may not be the
sent to SetVolume(). exact value sent to SetVolume().
*/ */
double GetVolume(); double GetVolume();
@@ -306,8 +336,9 @@ public:
bool Load(const wxString& fileName); bool Load(const wxString& fileName);
/** /**
Loads the location that uri refers to. Note that this is very implementation-dependant, Loads the location that uri refers to. Note that this is very
although HTTP URI/URLs are generally supported, for example. Returns @false if loading fails. implementation-dependant, although HTTP URI/URLs are generally
supported, for example. Returns @false if loading fails.
*/ */
bool Load(const wxURI& uri); bool Load(const wxURI& uri);
@@ -324,7 +355,8 @@ public:
bool LoadURI(const wxURI& uri); 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); bool LoadURIWithProxy(const wxURI& uri, const wxURI& proxy);
@@ -375,7 +407,7 @@ public:
default controls provided by the toolkit. The function takes a default controls provided by the toolkit. The function takes a
wxMediaCtrlPlayerControls enumeration, please see available show modes there. 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. Currently only implemented on the QuickTime and DirectShow backends.
The function returns @true on success. The function returns @true on success.
@@ -385,7 +417,7 @@ public:
/** /**
Stops the media. 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(); bool Stop();

132
interface/wx/memory.h
View File

@@ -1,49 +1,26 @@
///////////////////////////////////////////////////////////////////////////// /////////////////////////////////////////////////////////////////////////////
// Name: memory.h // Name: memory.h
// Purpose: interface of wxDebugStreamBuf // Purpose: interface of wxDebugContext
// Author: wxWidgets team // Author: wxWidgets team
// RCS-ID: $Id$ // RCS-ID: $Id$
// Licence: wxWindows license // 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 @class wxDebugContext
A class for performing various debugging and memory tracing A class for performing various debugging and memory tracing operations.
operations. Full functionality (such as printing out objects
currently allocated) is only present in a debugging build of wxWidgets, Full functionality (such as printing out objects currently allocated) is
i.e. if the __WXDEBUG__ symbol is defined. wxDebugContext only present in a debugging build of wxWidgets, i.e. if the __WXDEBUG__
and related functions and macros can be compiled out by setting symbol is defined. wxDebugContext and related functions and macros can be
wxUSE_DEBUG_CONTEXT to 0 is setup.h compiled out by setting wxUSE_DEBUG_CONTEXT to 0 is setup.h
@library{wxbase} @library{wxbase}
@category{debugging} @category{debugging}
@see Overview() @see @ref overview_debugging
*/ */
class wxDebugContext class wxDebugContext
{ {
@@ -53,8 +30,8 @@ public:
checkpoint. checkpoint.
@return Returns the number of errors, so a value of zero represents @return Returns the number of errors, so a value of zero represents
success. Returns -1 if an error was detected that success. Returns -1 if an error was detected that prevents
prevents further checking. further checking.
*/ */
int Check(); int Check();
@@ -70,6 +47,7 @@ public:
/** /**
Returns @true if the memory allocator checks all previous memory blocks for Returns @true if the memory allocator checks all previous memory blocks for
errors. errors.
By default, this is @false since it slows down execution considerably. By default, this is @false since it slows down execution considerably.
@see SetCheckPrevious() @see SetCheckPrevious()
@@ -77,22 +55,25 @@ public:
bool GetCheckPrevious(); bool GetCheckPrevious();
/** /**
Returns @true if debug mode is on. If debug mode is on, the wxObject new and Returns @true if debug mode is on.
delete
operators store or use information about memory allocation. Otherwise, If debug mode is on, the wxObject new and delete operators store or use
a straight malloc and free will be performed by these operators. information about memory allocation. Otherwise, a straight malloc and
free will be performed by these operators.
@see SetDebugMode() @see SetDebugMode()
*/ */
bool GetDebugMode(); bool GetDebugMode();
/** /**
Gets the debug level (default 1). The debug level is used by the wxTraceLevel Gets the debug level (default 1).
function and
the WXTRACELEVEL macro to specify how detailed the trace information is; setting The debug level is used by the wxTraceLevel function and the WXTRACELEVEL
a different level will only have an effect if trace statements in the macro to specify how detailed the trace information is; setting a
application different level will only have an effect if trace statements in the
specify a value other than one. application specify a value other than one.
@deprecated
This is obsolete, replaced by wxLog functionality. This is obsolete, replaced by wxLog functionality.
@see SetLevel() @see SetLevel()
@@ -101,6 +82,8 @@ public:
/** /**
Returns the output stream associated with the debug context. Returns the output stream associated with the debug context.
@deprecated
This is obsolete, replaced by wxLog functionality. This is obsolete, replaced by wxLog functionality.
@see SetStream() @see SetStream()
@@ -111,6 +94,8 @@ public:
Returns a pointer to the output stream buffer associated with the debug context. 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 There may not necessarily be a stream buffer if the stream has been set
by the user. by the user.
@deprecated
This is obsolete, replaced by wxLog functionality. This is obsolete, replaced by wxLog functionality.
*/ */
streambuf* GetStreamBuf(); streambuf* GetStreamBuf();
@@ -118,6 +103,8 @@ public:
/** /**
Returns @true if there is a stream currently associated Returns @true if there is a stream currently associated
with the debug context. with the debug context.
@deprecated
This is obsolete, replaced by wxLog functionality. This is obsolete, replaced by wxLog functionality.
@see SetStream(), GetStream() @see SetStream(), GetStream()
@@ -138,9 +125,8 @@ public:
allocations is printed, together with the total size. allocations is printed, together with the total size.
@param detailed @param detailed
If @true, the function will also print how many If @true, the function will also print how many objects of each class
objects of each class have been allocated, and the space taken by have been allocated, and the space taken by these class instances.
these class instances.
@see PrintStatistics() @see PrintStatistics()
*/ */
@@ -160,39 +146,45 @@ public:
that have been performed up to this point. that have been performed up to this point.
@param all @param all
If @true, the checkpoint is reset to include all If @true, the checkpoint is reset to include all memory allocations
memory allocations since the program started. since the program started.
*/ */
void SetCheckpoint(bool all = false); void SetCheckpoint(bool all = false);
/** /**
Sets the debug mode on or off. If debug mode is on, the wxObject new and delete Sets the debug mode on or off.
operators store or use information about memory allocation. Otherwise,
a straight malloc and free will be performed by these operators. 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 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 uses this function, it should make sure that all object memory allocated
is deallocated with the same value of debug mode. Otherwise, the is deallocated with the same value of debug mode. Otherwise, the delete
delete operator might try to look for memory information that does not operator might try to look for memory information that does not exist.
exist.
@see GetDebugMode() @see GetDebugMode()
*/ */
void SetDebugMode(bool debug); void SetDebugMode(bool debug);
/** /**
Sets the current debug file and creates a stream. This will delete any existing Sets the current debug file and creates a stream.
stream and stream buffer. By default, the debug context stream This will delete any existing stream and stream buffer.
outputs to the debugger (Windows) or standard error (other platforms).
By default, the debug context stream outputs to the debugger (Windows)
or standard error (other platforms).
*/ */
bool SetFile(const wxString& filename); bool SetFile(const wxString& filename);
/** /**
Sets the debug level (default 1). The debug level is used by the wxTraceLevel Sets the debug level (default 1).
function and
the WXTRACELEVEL macro to specify how detailed the trace information is; setting 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 a different level will only have an effect if trace statements in the
application application specify a value other than one.
specify a value other than one.
@deprecated
This is obsolete, replaced by wxLog functionality. This is obsolete, replaced by wxLog functionality.
@see GetLevel() @see GetLevel()
@@ -200,10 +192,10 @@ public:
void SetLevel(int level); void SetLevel(int level);
/** /**
Installs a function to be called at the end of wxWidgets shutdown. It will be Installs a function to be called at the end of wxWidgets shutdown.
called after It will be called after all files with global instances of
all files with global instances of wxDebugContextDumpDelayCounter have run wxDebugContextDumpDelayCounter have run their destructors.
their destructors.
The shutdown function must be take no parameters and return nothing. The shutdown function must be take no parameters and return nothing.
*/ */
void SetShutdownNotifyFunction(wxShutdownNotifyFunction func); void SetShutdownNotifyFunction(wxShutdownNotifyFunction func);
@@ -211,15 +203,19 @@ public:
/** /**
Sets the debugging stream to be the debugger (Windows) or standard error (other Sets the debugging stream to be the debugger (Windows) or standard error (other
platforms). platforms).
This is the default setting. The existing stream will be flushed and deleted. This is the default setting. The existing stream will be flushed and deleted.
@deprecated
This is obsolete, replaced by wxLog functionality. This is obsolete, replaced by wxLog functionality.
*/ */
bool SetStandardError(); bool SetStandardError();
/** /**
Sets the stream and optionally, stream buffer associated with the debug context. Sets the stream and optionally, stream buffer associated with the debug context.
This operation flushes and deletes the existing stream (and stream buffer if This operation flushes and deletes the existing stream (and stream buffer if any).
any).
@deprecated
This is obsolete, replaced by wxLog functionality. This is obsolete, replaced by wxLog functionality.
@param stream @param stream

235
interface/wx/menu.h
View File

@@ -11,22 +11,36 @@
A menu bar is a series of menus accessible from the top of a frame. 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} @library{wxcore}
@category{menus} @category{menus}
@see wxMenu, @ref overview_eventhandling "Event Handling Overview" @see wxMenu, @ref overview_eventhandling
*/ */
class wxMenuBar : public wxWindow class wxMenuBar : public wxWindow
{ {
public: public:
/** /**
Construct an empty menu barM Construct an empty menu bar.
@param style @param style
If wxMB_DOCKABLE the menu bar can be detached (wxGTK only). If wxMB_DOCKABLE the menu bar can be detached (wxGTK only).
*/ */
wxMenuBar(long style = 0); wxMenuBar(long style = 0);
/** /**
Construct a menu bar from arrays of menus and titles. Construct a menu bar from arrays of menus and titles.
@@ -45,8 +59,8 @@ public:
long style = 0); long style = 0);
/** /**
Destructor, destroying the menu bar and removing it from the parent frame (if Destructor, destroying the menu bar and removing it from the parent
any). frame (if any).
*/ */
virtual ~wxMenuBar(); virtual ~wxMenuBar();
@@ -54,7 +68,7 @@ public:
Adds the item to the end of the menu bar. Adds the item to the end of the menu bar.
@param menu @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 @param title
The title of the menu. 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 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 such menu exists in this menubar.
the menu title (with accelerator characters, i.e. @c "File") or just the
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. menu label (@c "File") indifferently.
*/ */
int FindMenu(const wxString& title) const; int FindMenu(const wxString& title) const;
@@ -176,6 +192,9 @@ public:
@remarks Use only after the menubar has been associated with a frame. @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() @see SetLabelTop()
*/ */
wxString GetLabelTop(int pos) const; wxString GetLabelTop(int pos) const;
@@ -225,8 +244,7 @@ public:
/** /**
Inserts the menu at the given position into the menu bar. Inserting menu at 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 position 0 will insert it in the very beginning of it, inserting at position
GetMenuCount() is the same as calling GetMenuCount() is the same as calling Append().
Append().
@param pos @param pos
The position of the new menu in the menu bar The position of the new menu in the menu bar
@@ -267,10 +285,9 @@ public:
void Refresh(); void Refresh();
/** /**
Removes the menu from the menu bar and returns the menu object - the caller is Removes the menu from the menu bar and returns the menu object - the caller
responsible for deleting it. This function may be used together with is responsible for deleting it. This function may be used together with
Insert() to change the menubar Insert() to change the menubar dynamically.
dynamically.
@see Replace() @see Replace()
*/ */
@@ -286,8 +303,8 @@ public:
@param title @param title
The title of the menu. The title of the menu.
@return The menu which was previously at position pos. The caller is @return The menu which was previously at position pos.
responsible for deleting it. The caller is responsible for deleting it.
@see Insert(), Remove() @see Insert(), Remove()
*/ */
@@ -329,6 +346,9 @@ public:
@remarks Use only after the menubar has been associated with a frame. @remarks Use only after the menubar has been associated with a frame.
@deprecated
This function has been deprecated in favour of SetMenuLabel().
@see GetLabelTop() @see GetLabelTop()
*/ */
void SetLabelTop(int pos, const wxString& label); 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 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. associated command but just makes a separator line appear in the menu.
@note Please note that @e wxID_ABOUT and @e wxID_EXIT are @note
predefined by wxWidgets and have a special meaning since entries Please note that @e wxID_ABOUT and @e wxID_EXIT are predefined by wxWidgets
using these IDs will be taken out of the normal menus under MacOS X and have a special meaning since entries using these IDs will be taken out
and will be inserted into the system menu (following the appropriate of the normal menus under MacOS X and will be inserted into the system menu
MacOS X interface guideline). On PalmOS @e wxID_EXIT is disabled according (following the appropriate MacOS X interface guideline).
to Palm OS Companion guidelines. 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 Menu items may be either normal items, check items or radio items.
don't have any special properties while the check items have a boolean flag Normal items don't have any special properties while the check items have a
associated to them and they show a checkmark in the menu when the flag is set. 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 wxWidgets automatically toggles the flag value when the item is clicked and its
value may be retrieved using either wxMenu::IsChecked method value may be retrieved using either wxMenu::IsChecked method of wxMenu or
of wxMenu or wxMenuBar itself or by using wxMenuBar itself or by using wxEvent::IsChecked when you get the menu
wxEvent::IsChecked when you get the menu
notification for the item in question. notification for the item in question.
The radio items are similar to the check items except that all the other items 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 the radio items risks to not work correctly. Finally note that radio items
are not supported under Motif. 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} @library{wxcore}
@category{menus} @category{menus}
@see wxMenuBar, wxWindow::PopupMenu, @see wxMenuBar, wxWindow::PopupMenu, @ref overview_eventhandling,
@ref overview_eventhandling "Event Handling Overview", @ref wxFileHistory "wxFileHistory (most recently used files menu)"
@ref wxFileHistory "wxFileHistory (most recently used files menu)"
*/ */
class wxMenu : public wxEvtHandler class wxMenu : public wxEvtHandler
{ {
@@ -404,7 +444,7 @@ public:
wxMenu(long style); wxMenu(long style);
/** /**
Constructs a wxMenu object with a title Constructs a wxMenu object with a title.
@param title @param title
Title at the top of the menu (not always supported). 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). If set to wxMENU_TEAROFF, the menu will be detachable (wxGTK only).
*/ */
wxMenu(const wxString& title = "", long style = 0); wxMenu(const wxString& title = "", long style = 0);
/** /**
Destructor, destroying the menu. 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 @note
you delete or re-use the popup menu @e before destroying the Under Motif, a popup menu must have a valid parent (the window
parent window. Re-use in this context means popping up the menu on it was last popped up on) when being destroyed. Therefore, make sure
a different window from last time, which causes an implicit destruction you delete or re-use the popup menu @e before destroying the parent
and recreation of internal data structures. 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(); virtual ~wxMenu();
/** /**
Adds a menu item. Adds a menu item.
@param id @param id
The menu command identifier. The menu command identifier.
@@ -436,17 +478,48 @@ public:
By default, the handler for the wxEVT_MENU_HIGHLIGHT event displays By default, the handler for the wxEVT_MENU_HIGHLIGHT event displays
this string in the status line. this string in the status line.
@param kind @param kind
May be wxITEM_SEPARATOR, wxITEM_NORMAL, May be wxITEM_SEPARATOR, wxITEM_NORMAL, wxITEM_CHECK or wxITEM_RADIO
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(), @see AppendSeparator(), AppendCheckItem(), AppendRadioItem(),
AppendSubMenu(), Insert(), SetLabel(), AppendSubMenu(), Insert(), SetLabel(), GetHelpString(),
GetHelpString(), SetHelpString(), wxMenuItem SetHelpString(), wxMenuItem
*/ */
wxMenuItem* Append(int id, const wxString& item = wxEmptyString, wxMenuItem* Append(int id, const wxString& item = wxEmptyString,
const wxString& helpString = wxEmptyString, const wxString& helpString = wxEmptyString,
wxItemKind kind = wxITEM_NORMAL); wxItemKind kind = wxITEM_NORMAL);
/** /**
Adds a submenu. Adds a submenu.
@@ -464,25 +537,30 @@ public:
this string in the status line. this string in the status line.
@see AppendSeparator(), AppendCheckItem(), AppendRadioItem(), @see AppendSeparator(), AppendCheckItem(), AppendRadioItem(),
AppendSubMenu(), Insert(), SetLabel(), AppendSubMenu(), Insert(), SetLabel(), GetHelpString(),
GetHelpString(), SetHelpString(), wxMenuItem SetHelpString(), wxMenuItem
*/ */
wxMenuItem* Append(int id, const wxString& item, wxMenu* subMenu, wxMenuItem* Append(int id, const wxString& item, wxMenu* subMenu,
const wxString& helpString = wxEmptyString); const wxString& helpString = wxEmptyString);
/** /**
Adds a menu item object. This is the most generic variant of Append() method Adds a menu item object.
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, 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. such as bitmaps and fonts.
@param menuItem @param menuItem
A menuitem object. It will be owned by the wxMenu object after this function A menuitem object. It will be owned by the wxMenu object after this
is called, so do not delete it yourself. function is called, so do not delete it yourself.
@remarks
See the remarks for the other Append() overloads.
@see AppendSeparator(), AppendCheckItem(), AppendRadioItem(), @see AppendSeparator(), AppendCheckItem(), AppendRadioItem(),
AppendSubMenu(), Insert(), SetLabel(), AppendSubMenu(), Insert(), SetLabel(), GetHelpString(),
GetHelpString(), SetHelpString(), wxMenuItem SetHelpString(), wxMenuItem
*/ */
wxMenuItem* Append(wxMenuItem* menuItem); wxMenuItem* Append(wxMenuItem* menuItem);
@@ -495,9 +573,9 @@ public:
const wxString& helpString = ""); const wxString& helpString = "");
/** /**
Adds a radio item to the end of the menu. All consequent radio items form a Adds a radio item to the end of the menu.
group and when an item in the group is checked, all the others are All consequent radio items form a group and when an item in the group is
automatically unchecked. checked, all the others are automatically unchecked.
@see Append(), InsertRadioItem() @see Append(), InsertRadioItem()
*/ */
@@ -520,8 +598,8 @@ public:
const wxString& help = wxEmptyString); const wxString& help = wxEmptyString);
/** /**
Inserts a break in a menu, causing the next appended item to appear in a new Inserts a break in a menu, causing the next appended item to appear in
column. a new column.
*/ */
virtual void Break(); virtual void Break();
@@ -620,7 +698,7 @@ public:
@return Menu item object or NULL if none is found. @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. Returns the wxMenuItem given a position in the menu.
@@ -671,8 +749,10 @@ public:
size_t GetMenuItemCount() const; size_t GetMenuItemCount() const;
/** /**
Returns the list of items in the menu. wxMenuItemList is a pseudo-template Returns the list of items in the menu.
list class containing wxMenuItem pointers, see wxList.
wxMenuItemList is a pseudo-template list class containing wxMenuItem
pointers, see wxList.
*/ */
wxMenuItemList GetMenuItems() const; wxMenuItemList GetMenuItems() const;
@@ -687,17 +767,19 @@ public:
wxString GetTitle() const; wxString GetTitle() const;
/** /**
Inserts the given @a item before the position @e pos. Inserting the item Inserts the given @a item before the position @a pos.
at position GetMenuItemCount() is the same
Inserting the item at position GetMenuItemCount() is the same
as appending it. as appending it.
@see Append(), Prepend() @see Append(), Prepend()
*/ */
wxMenuItem* Insert(size_t pos, wxMenuItem* item); wxMenuItem* Insert(size_t pos, wxMenuItem* item);
/** /**
Inserts the given @a item before the position @e pos. Inserting the item Inserts the given @a item before the position @a pos.
at position GetMenuItemCount() is the same
Inserting the item at position GetMenuItemCount() is the same
as appending it. as appending it.
@see Append(), Prepend() @see Append(), Prepend()
@@ -799,8 +881,8 @@ public:
/** /**
Removes the menu item from the menu but doesn't delete the associated C++ 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 object. This allows you to reuse the same item later by adding it back to
(especially useful with submenus). the menu (especially useful with submenus).
@param id @param id
The identifier of the menu item to remove. 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. @return A pointer to the item which was detached from the menu.
*/ */
wxMenuItem* Remove(int id); wxMenuItem* Remove(int id);
/** /**
Removes the menu item from the menu but doesn't delete the associated C++ 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 object. This allows you to reuse the same item later by adding it back to
(especially useful with submenus). the menu (especially useful with submenus).
@param item @param item
The menu item to remove. The menu item to remove.
@@ -860,9 +942,10 @@ public:
/** /**
Sends events to @a source (or owning window if @NULL) to update the 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 menu UI.
wxWindow::PopupMenu, but
the application may call it at other times if required. 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); void UpdateUI(wxEvtHandler* source = NULL);
}; };

75
interface/wx/menuitem.h
View File

@@ -1,6 +1,6 @@
///////////////////////////////////////////////////////////////////////////// /////////////////////////////////////////////////////////////////////////////
// Name: menuitem.h // Name: menuitem.h
// Purpose: interface of wxMenuItem // Purpose: interface of wxMenu, wxMenuItem
// Author: wxWidgets team // Author: wxWidgets team
// RCS-ID: $Id$ // RCS-ID: $Id$
// Licence: wxWindows license // Licence: wxWindows license
@@ -9,9 +9,10 @@
/** /**
@class wxMenuItem @class wxMenuItem
A menu item represents an item in a menu. Note that you usually don't have to A menu item represents an item in a menu.
deal with it directly as wxMenu methods usually construct an
object of this class for you. 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 Also please note that the methods related to fonts and bitmaps are currently
only implemented for Windows and GTK+. only implemented for Windows and GTK+.
@@ -26,19 +27,38 @@ class wxMenuItem : public wxObject
public: public:
/** /**
Constructs a wxMenuItem object. 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 Menu items can be standard, or "stock menu items", or custom.
on, see @ref page_stockitems "Stock Items" for the full list) it is enough For the standard menu items (such as commands to open a file, exit the
to specify just the stock ID and leave @a text and @a helpString empty. In program and so on, see @ref page_stockitems for the full list) it is enough
fact, leaving at least @a text empty for the stock menu items is strongly 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 recommended as they will have appearance and keyboard interface (including
standard accelerators) familiar to the user. standard accelerators) familiar to the user.
For the custom (non-stock) menu items, @a text must be specified and while 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 @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 description (which is automatically shown by the library in the status bar
the menu item is selected) in this parameter. 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 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 @param parentMenu
Menu that the menu item belongs to. Can be @NULL if the item is 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 case the given kind is ignored and taken to be @c wxITEM_SEPARATOR
instead. instead.
@param text @param text
Text for the menu item, as shown on the menu. An accelerator Text for the menu item, as shown on the menu. An accelerator key can
key can be specified using the ampersand " character. In order to embed an be specified using the ampersand " character. In order to embed an
ampersand character in the menu item text, the ampersand must be doubled. ampersand character in the menu item text, the ampersand must be doubled.
@param helpString @param helpString
Optional help string that will be shown on the status bar. Optional help string that will be shown on the status bar.
@param kind @param kind
May be @c wxITEM_SEPARATOR, @c wxITEM_NORMAL, @c wxITEM_CHECK or @c May be @c wxITEM_SEPARATOR, @c wxITEM_NORMAL, @c wxITEM_CHECK or
wxITEM_RADIO @c wxITEM_RADIO
@param subMenu @param subMenu
If non-@NULL, indicates that the menu item is a 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 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() @see GetItemLabelText(), GetLabelText()
*/ */
@@ -131,23 +151,26 @@ public:
/** /**
Returns the text associated with the menu item without any accelerator Returns the text associated with the menu item without any accelerator
characters it might contain. characters it might contain.
@deprecated This function is deprecated in favour of GetItemLabelText(). @deprecated This function is deprecated in favour of GetItemLabelText().
@see GetText(), GetLabelFromText() @see GetText(), GetLabelFromText()
*/ */
wxString GetLabel() const; wxString GetLabel() const;
/** /**
@deprecated This function is deprecated; please use GetLabelText() instead. @deprecated This function is deprecated; please use GetLabelText() instead.
@see GetText(), GetLabel() @see GetText(), GetLabel()
*/ */
static wxString GetLabelFromText(const wxString& text); 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: For example:
@code @code
wxMenuItem::GetLabelfromText( "&Hello\tCtrl-h"); wxMenuItem::GetLabelfromText("&Hello\tCtrl-h");
@endcode @endcode
will return just @c "Hello". will return just @c "Hello".
@@ -169,7 +192,9 @@ public:
/** /**
Returns the text associated with the menu item. Returns the text associated with the menu item.
@deprecated This function is deprecated. Please use @deprecated This function is deprecated. Please use
GetItemLabel() or GetItemLabelText() instead. GetItemLabel() or GetItemLabelText() instead.
*/ */
wxString GetName() const; wxString GetName() const;
@@ -182,7 +207,9 @@ public:
/** /**
Returns the text associated with the menu item, such as it was passed to the 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. wxMenuItem constructor, i.e. with any accelerator characters it may contain.
@deprecated This function is deprecated in favour of GetItemLabel(). @deprecated This function is deprecated in favour of GetItemLabel().
@see GetLabel(), GetLabelFromText() @see GetLabel(), GetLabelFromText()
*/ */
wxString GetText() const; wxString GetText() const;
@@ -223,15 +250,14 @@ public:
void SetBackgroundColour(const wxColour& colour) const; void SetBackgroundColour(const wxColour& colour) const;
/** /**
Sets the bitmap for the menu item (Windows and GTK+ only). It is Sets the bitmap for the menu item (Windows and GTK+ only).
equivalent to wxMenuItem::SetBitmaps(bmp, wxNullBitmap). It is equivalent to wxMenuItem::SetBitmaps(bmp, wxNullBitmap).
*/ */
virtual void SetBitmap(const wxBitmap& bmp); virtual void SetBitmap(const wxBitmap& bmp);
/** /**
Sets the checked/unchecked bitmaps for the menu item (Windows only). The first Sets the checked/unchecked bitmaps for the menu item (Windows only).
bitmap The first bitmap is also used as the single bitmap for uncheckable menu items.
is also used as the single bitmap for uncheckable menu items.
*/ */
void SetBitmaps(const wxBitmap& checked, void SetBitmaps(const wxBitmap& checked,
const wxBitmap& unchecked = wxNullBitmap); const wxBitmap& unchecked = wxNullBitmap);
@@ -268,6 +294,7 @@ public:
/** /**
Sets the text associated with the menu item. Sets the text associated with the menu item.
@deprecated This function is deprecated in favour of SetItemLabel(). @deprecated This function is deprecated in favour of SetItemLabel().
*/ */
virtual void SetText(const wxString& text); virtual void SetText(const wxString& text);

56
interface/wx/metafile.h
View File

@@ -11,20 +11,21 @@
This is a type of device context that allows a metafile object to be 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 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 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 Adding metafile capability to an application should be easy if you
already write to a wxDC; simply pass the wxMetafileDC to your drawing already write to a wxDC; simply pass the wxMetafileDC to your drawing
function instead. You may wish to conditionally compile this code so it 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 is not compiled under X (although no harm will result if you leave it in).
in).
Note that a metafile saved to disk is in standard Windows metafile format, Note that a metafile saved to disk is in standard Windows metafile format,
and cannot be imported into most applications. To make it importable, and cannot be imported into most applications. To make it importable,
call the function ::wxMakeMetafilePlaceable after call the function ::wxMakeMetafilePlaceable after closing your disk-based
closing your disk-based metafile device context. metafile device context.
@library{wxcore} @library{wxcore}
@category{dc} @category{dc}
@@ -35,8 +36,8 @@ class wxMetafileDC : public wxDC
{ {
public: public:
/** /**
Constructor. If no filename is passed, the metafile is created Constructor.
in memory. If no filename is passed, the metafile is created in memory.
*/ */
wxMetafileDC(const wxString& filename = ""); wxMetafileDC(const wxString& filename = "");
@@ -46,8 +47,8 @@ public:
~wxMetafileDC(); ~wxMetafileDC();
/** /**
This must be called after the device context is finished with. A This must be called after the device context is finished with.
metafile is returned, and ownership of it passes to the calling A metafile is returned, and ownership of it passes to the calling
application (so it should be destroyed explicitly). application (so it should be destroyed explicitly).
*/ */
wxMetafile* Close(); wxMetafile* Close();
@@ -61,11 +62,14 @@ public:
A @b wxMetafile represents the MS Windows metafile object, so metafile A @b wxMetafile represents the MS Windows metafile object, so metafile
operations have no effect in X. In wxWidgets, only sufficient functionality 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 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 in a future version.
is to use a wxMetafileDC.
Presently, the only way of creating a metafile is to use a wxMetafileDC.
@onlyfor{wxmsw}
@library{wxcore} @library{wxcore}
@category{FIXME} @category{gdi,misc}
@see wxMetafileDC @see wxMetafileDC
*/ */
@@ -73,16 +77,17 @@ class wxMetafile : public wxObject
{ {
public: public:
/** /**
Constructor. If a filename is given, the Windows disk metafile is Constructor.
read in. Check whether this was performed successfully by
using the @ref isok() wxMetafile:IsOk member. 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 = ""); wxMetafile(const wxString& filename = "");
/** /**
Destructor. Destructor.
See @ref overview_refcountdestruct "reference-counted object destruction" for
more info. See @ref overview_refcount_destruct for more info.
*/ */
~wxMetafile(); ~wxMetafile();
@@ -101,10 +106,25 @@ public:
Passes the metafile data to the clipboard. The metafile can no longer be 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 used for anything, but the wxMetafile object must still be destroyed by
the application. the application.
Below is a example of metafile, metafile device context and clipboard use Below is a example of metafile, metafile device context and clipboard use
from the @c hello.cpp example. Note the way the metafile dimensions 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 are passed to the clipboard, making use of the device context's ability
to keep track of the maximum extent of drawing commands. 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); bool SetClipboard(int width = 0, int height = 0);
}; };

251
interface/wx/mimetype.h
View File

@@ -13,17 +13,60 @@
MIME types from a system-specific location and the filename extensions to the MIME types from a system-specific location and the filename extensions to the
MIME types and vice versa. After initialization the functions MIME types and vice versa. After initialization the functions
GetFileTypeFromMimeType() and GetFileTypeFromExtension() GetFileTypeFromMimeType() and GetFileTypeFromExtension()
may be called: they will return a wxFileType object which may be called: they will return a wxFileType object which may be further
may be further queried for file description, icon and other attributes. 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. 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. 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} @library{wxbase}
@category{misc} @category{misc}
@@ -52,7 +95,7 @@ public:
/** /**
Gather information about the files with given extension and return the Gather information about the files with given extension and return the
corresponding wxFileType object or @NULL if the extension is unknown. 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, 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. 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 This function returns @true if either the given @a mimeType is exactly
same as @a wildcard or if it has the same category and the subtype of 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 wildcard is '*'. Note that the '*' wildcard is not allowed in
@a mimeType itself. @a mimeType itself.
The comparison don by this function is case insensitive so it is not 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. necessary to convert the strings to the same case before calling it.
*/ */
static bool IsOfType(const wxString& mimeType, const wxString& wildcard); static bool IsOfType(const wxString& mimeType, const wxString& wildcard);
}; };
@@ -87,12 +130,14 @@ wxMimeTypesManager* wxTheMimeTypesManager;
/** /**
@class wxFileType @class wxFileType
This class holds information about a given @e file type. File type is the same This class holds information about a given @e file type.
as
MIME type under Unix, but under Windows it corresponds more to an extension than File type is the same as MIME type under Unix, but under Windows it corresponds
to MIME type (in fact, several extensions may correspond to a file type). This more to an extension than to MIME type (in fact, several extensions may
object may be created in several different ways: the program might know the file correspond to a file type).
extension and wish to find out the corresponding MIME type or, conversely, it
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 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 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 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 typically correspond to the extension ".txt", but may as well be associated with
".ini" or ".conf". ".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} @library{wxbase}
@category{FIXME} @category{misc}
@see wxMimeTypesManager @see wxMimeTypesManager
*/ */
@@ -137,30 +248,19 @@ public:
/** /**
This function is primarily intended for GetOpenCommand and GetPrintCommand This function is primarily intended for GetOpenCommand and GetPrintCommand
usage but may be also used by the application directly if, for example, you want usage but may be also used by the application directly if, for example, you
to use some non-default command to open the file. 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
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. 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 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 assumed that the command reads the data on stdin and so the effect is the same
as " %s" were appended to the string. as " %s" were appended to the string.
Unlike all other functions of this class, there is no error return for this Unlike all other functions of this class, there is no error return for this
function. function.
*/ */
@@ -177,24 +277,27 @@ public:
/** /**
If the function returns @true, the array @a extensions is filled If the function returns @true, the array @a extensions is filled
with all extensions associated with this file type: for example, it may 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 contain the following two elements for the MIME type "text/html"
absence of the leading dot): "html" and "htm". (notice the absence of the leading dot): "html" and "htm".
@b Windows: This function is currently not implemented: there is no @b Windows: This function is currently not implemented: there is no
(efficient) way to retrieve associated extensions from the given MIME type on (efficient) way to retrieve associated extensions from the given MIME type
this platform, so it will only return @true if the wxFileType object was on this platform, so it will only return @true if the wxFileType object was
created created by wxMimeTypesManager::GetFileTypeFromExtension function in the
by wxMimeTypesManager::GetFileTypeFromExtension first place.
function in the first place.
*/ */
bool GetExtensions(wxArrayString& extensions); bool GetExtensions(wxArrayString& extensions);
/** /**
If the function returns @true, the @c iconLoc is filled with the If the function returns @true, the @c iconLoc is filled with the
location of the icon for this MIME type. A wxIcon may be location of the icon for this MIME type.
created from @a iconLoc later. A wxIcon may be created from @a iconLoc later.
@b Windows: The function returns the icon shown by Explorer for the files of @b Windows: The function returns the icon shown by Explorer for the files of
the specified type. the specified type.
@b Mac: This function is not implemented and always returns @false. @b Mac: This function is not implemented and always returns @false.
@b Unix: MIME manager gathers information about icons from GNOME @b Unix: MIME manager gathers information about icons from GNOME
and KDE settings and thus GetIcon's success depends on availability and KDE settings and thus GetIcon's success depends on availability
of these desktop environments. of these desktop environments.
@@ -208,11 +311,12 @@ public:
bool GetMimeType(wxString* mimeType) const; bool GetMimeType(wxString* mimeType) const;
/** /**
Same as GetMimeType() but returns array of MIME Same as GetMimeType() but returns array of MIME types.
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 This array will contain only one item in most cases but sometimes,
one file extension is mapped to different MIME types by KDE, mailcap and notably under Unix with KDE, may contain more MIME types.
mime.types. This happens when one file extension is mapped to different MIME types
by KDE, mailcap and mime.types.
*/ */
bool GetMimeType(wxArrayString& mimeTypes); bool GetMimeType(wxArrayString& mimeTypes);
@@ -220,52 +324,27 @@ public:
/** /**
With the first version of this method, if the @true is returned, the 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 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 executed (see wxExecute()) in order to open the file of the given type.
given type. In this case, the name of the file as well as any other parameters
is retrieved from MessageParameters() In this case, the name of the file as well as any other parameters
class. is retrieved from MessageParameters() class.
In the second case, only the filename is specified and the command to be used 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 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 indicate that an error occurred (typically meaning that there is no standard way
to open this kind of files). to open this kind of files).
*/ */
bool GetOpenCommand(wxString* command, bool GetOpenCommand(wxString* command, MessageParameters& params);
MessageParameters& params);
wxString GetOpenCommand(const wxString& filename); wxString GetOpenCommand(const wxString& filename);
//@} //@}
/** /**
If the function returns @true, the string pointed to by @a command is filled If the function returns @true, the string pointed to by @a command is filled
with the command which must be executed (see wxExecute()) in with the command which must be executed (see wxExecute()) in order to
order to print the file of the given type. The name of the file is print the file of the given type.
retrieved from MessageParameters() class.
*/ The name of the file is retrieved from the MessageParameters class.
bool GetPrintCommand(wxString* command,
MessageParameters& params);
/**
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.
*/ */
bool GetPrintCommand(wxString* command, MessageParameters& params);
}; };

60
interface/wx/minifram.h
View File

@@ -9,41 +9,44 @@
/** /**
@class wxMiniFrame @class wxMiniFrame
A miniframe is a frame with a small title bar. It is suitable for floating A miniframe is a frame with a small title bar.
toolbars that must not It is suitable for floating toolbars that must not take up too much screen area.
take up too much screen area.
An example of mini frame can be seen in the @ref overview_sampledialogs An example of mini frame can be seen in the @ref page_samples_dialogs
"dialogs sample"
using the "Mini frame" command of the "Generic dialogs" submenu. using the "Mini frame" command of the "Generic dialogs" submenu.
@beginStyleTable @beginStyleTable
@style{wxICONIZE} @style{wxICONIZE}
Display the frame iconized (minimized) (Windows only). Display the frame iconized (minimized) (Windows only).
@style{wxCAPTION} @style{wxCAPTION}
Puts a caption on the frame. Puts a caption on the frame.
@style{wxMINIMIZE} @style{wxMINIMIZE}
Identical to wxICONIZE. Identical to wxICONIZE.
@style{wxMINIMIZE_BOX} @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} @style{wxMAXIMIZE}
Displays the frame maximized (Windows only). Displays the frame maximized (Windows only).
@style{wxMAXIMIZE_BOX} @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} @style{wxCLOSE_BOX}
Displays a close box on the frame. Displays a close box on the frame.
@style{wxSTAY_ON_TOP} @style{wxSTAY_ON_TOP}
Stay on top of other windows (Windows only). Stay on top of other windows (Windows only).
@style{wxSYSTEM_MENU} @style{wxSYSTEM_MENU}
Displays a system menu (Windows and Motif only). Displays a system menu (Windows and Motif only).
@style{wxTINY_CAPTION_HORIZ} @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} @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} @style{wxRESIZE_BORDER}
Displays a resizeable border around the window. Displays a resizeable border around the window.
@endStyleTable @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} @library{wxcore}
@category{managedwnd} @category{managedwnd}
@@ -52,7 +55,11 @@
class wxMiniFrame : public wxFrame class wxMiniFrame : public wxFrame
{ {
public: public:
//@{ /**
Default ctor.
*/
wxMiniFrame();
/** /**
Constructor, creating the window. Constructor, creating the window.
@@ -60,37 +67,32 @@ public:
The window parent. This may be @NULL. If it is non-@NULL, the frame will 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. always be displayed on top of the parent window on Windows.
@param id @param id
The window identifier. It may take a value of -1 to indicate a default The window identifier. It may take a value of -1 to indicate a default value.
value.
@param title @param title
The caption to be displayed on the frame's title bar. The caption to be displayed on the frame's title bar.
@param pos @param pos
The window position. The value wxDefaultPosition indicates a default position, The window position. The value wxDefaultPosition indicates a default position,
chosen by chosen by either the windowing system or wxWidgets, depending on platform.
either the windowing system or wxWidgets, depending on platform.
@param size @param size
The window size. The value wxDefaultSize indicates a default size, chosen by The window size. The value wxDefaultSize indicates a default size, chosen by
either the windowing system or wxWidgets, depending on platform. either the windowing system or wxWidgets, depending on platform.
@param style @param style
The window style. See wxMiniFrame. The window style. See wxMiniFrame.
@param name @param name
The name of the window. This parameter is used to associate a name with the The name of the window. This parameter is used to associate a name with
item, the item, allowing the application user to set Motif resource values for
allowing the application user to set Motif resource values for
individual windows. individual windows.
@remarks The frame behaves like a normal frame on non-Windows platforms. @remarks The frame behaves like a normal frame on non-Windows platforms.
@see Create() @see Create()
*/ */
wxMiniFrame();
wxMiniFrame(wxWindow* parent, wxWindowID id, wxMiniFrame(wxWindow* parent, wxWindowID id,
const wxString& title, const wxString& title,
const wxPoint& pos = wxDefaultPosition, const wxPoint& pos = wxDefaultPosition,
const wxSize& size = wxDefaultSize, const wxSize& size = wxDefaultSize,
long style = wxCAPTION | wxRESIZE_BORDER, long style = wxCAPTION | wxRESIZE_BORDER,
const wxString& name = "frame"); const wxString& name = "frame");
//@}
/** /**
Destructor. Destroys all child windows and menu bar if present. Destructor. Destroys all child windows and menu bar if present.
@@ -98,8 +100,8 @@ public:
virtual ~wxMiniFrame(); virtual ~wxMiniFrame();
/** /**
Used in two-step frame construction. See wxMiniFrame() Used in two-step frame construction.
for further details. See wxMiniFrame() for further details.
*/ */
bool Create(wxWindow* parent, wxWindowID id, bool Create(wxWindow* parent, wxWindowID id,
const wxString& title, const wxString& title,

52
interface/wx/module.h
View File

@@ -14,19 +14,19 @@
automatically called on wxWidgets startup and exit. automatically called on wxWidgets startup and exit.
To define a new kind of module, derive a class from wxModule, override the To define a new kind of module, derive a class from wxModule, override the
wxModule::OnInit and wxModule::OnExit wxModule::OnInit and wxModule::OnExit functions, and add the
functions, and add the DECLARE_DYNAMIC_CLASS and IMPLEMENT_DYNAMIC_CLASS to DECLARE_DYNAMIC_CLASS and IMPLEMENT_DYNAMIC_CLASS to header and implementation
header and implementation files (which can be the same file). On files (which can be the same file).
initialization, wxWidgets will find all classes derived from wxModule, create On initialization, wxWidgets will find all classes derived from wxModule, create
an instance of each, and call each OnInit function. On exit, wxWidgets will an instance of each, and call each wxModule::OnInit function. On exit, wxWidgets
call the OnExit function for each module instance. will call the wxModule::OnExit function for each module instance.
Note that your module class does not have to be in a header file. Note that your module class does not have to be in a header file.
For example: For example:
@code @code
// A module to allow DDE initialization/cleanup // A module to allow DDE initialization/cleanup
// without calling these functions from app.cpp or from // without calling these functions from app.cpp or from
// the user's application. // the user's application.
class wxDDEModule: public wxModule class wxDDEModule: public wxModule
@@ -73,7 +73,7 @@
@endcode @endcode
@library{wxbase} @library{wxbase}
@category{FIXME} @category{misc}
*/ */
class wxModule : public wxObject class wxModule : public wxObject
{ {
@@ -88,27 +88,32 @@ public:
*/ */
virtual ~wxModule(); virtual ~wxModule();
//@{
/** /**
Call this function from the constructor of the derived class. @a dep must be Call this function from the constructor of the derived class.
the CLASSINFO() of a wxModule-derived class and the
corresponding module will be loaded before and unloaded after @a dep must be the CLASSINFO() of a wxModule-derived class and the
this module. 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.
@param dep @param dep
The class information object for the dependent module. 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 @param classname
The class name of the dependent module. The class name of the dependent module.
*/ */
void AddDependency(wxClassInfo* dep);
void AddDependency(const char* classname); void AddDependency(const char* classname);
//@}
/** /**
Provide this function with appropriate cleanup for your module. Provide this function with appropriate cleanup for your module.
@@ -116,9 +121,8 @@ public:
virtual void OnExit(); virtual void OnExit();
/** /**
Provide this function with appropriate initialization for your module. If the Provide this function with appropriate initialization for your module.
function If the function returns @false, wxWidgets will exit immediately.
returns @false, wxWidgets will exit immediately.
*/ */
virtual bool OnInit(); virtual bool OnInit();
}; };

7
interface/wx/mousestate.h
View File

@@ -21,6 +21,7 @@
This class is implemented entirely inline in @<wx/mousestate.h@> and thus This class is implemented entirely inline in @<wx/mousestate.h@> and thus
has no linking requirements. has no linking requirements.
@nolibrary
@category{misc} @category{misc}
@see wxGetMouseState(), wxMouseEvent @see wxGetMouseState(), wxMouseEvent
@@ -37,10 +38,12 @@ public:
Returns X coordinate of the physical mouse event position. Returns X coordinate of the physical mouse event position.
*/ */
wxCoord GetX() const; wxCoord GetX() const;
/** /**
Returns Y coordinate of the physical mouse event position. Returns Y coordinate of the physical mouse event position.
*/ */
wxCoord GetY() const; wxCoord GetY() const;
/** /**
Returns the physical mouse position. Returns the physical mouse position.
*/ */
@@ -50,18 +53,22 @@ public:
Returns @true if the left mouse button changed to down. Returns @true if the left mouse button changed to down.
*/ */
bool LeftDown() const; bool LeftDown() const;
/** /**
Returns @true if the middle mouse button changed to down. Returns @true if the middle mouse button changed to down.
*/ */
bool MiddleDown() const; bool MiddleDown() const;
/** /**
Returns @true if the right mouse button changed to down. Returns @true if the right mouse button changed to down.
*/ */
bool RightDown() const; bool RightDown() const;
/** /**
Returns @true if the first extra button mouse button changed to down. Returns @true if the first extra button mouse button changed to down.
*/ */
bool Aux1Down() const; bool Aux1Down() const;
/** /**
Returns @true if the second extra button mouse button changed to down. Returns @true if the second extra button mouse button changed to down.
*/ */

13
interface/wx/msgdlg.h
View File

@@ -15,14 +15,13 @@
@library{wxcore} @library{wxcore}
@category{cmndlg} @category{cmndlg}
@see @ref overview_wxmessagedialogoverview "wxMessageDialog overview" @see @ref overview_cmndlg_msg
*/ */
class wxMessageDialog : public wxDialog class wxMessageDialog : public wxDialog
{ {
public: public:
/** /**
Constructor specifying the message box properties. Constructor specifying the message box properties.
Use ShowModal() to show the dialog. Use ShowModal() to show the dialog.
@a style may be a bit list of the following identifiers: @a style may be a bit list of the following identifiers:
@@ -56,8 +55,7 @@ public:
wxICON_ERROR. wxICON_ERROR.
@style{wxICON_QUESTION} @style{wxICON_QUESTION}
Displays a question mark symbol. This icon is automatically used Displays a question mark symbol. This icon is automatically used
with @c wxYES_NO so it's usually unnecessary to specify it with @c wxYES_NO so it's usually unnecessary to specify it explicitly.
explicitly.
@style{wxICON_INFORMATION} @style{wxICON_INFORMATION}
Displays an information symbol. This icon is used by default if @c 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 wxYES_NO is not given so it is usually unnecessary to specify it
@@ -67,8 +65,8 @@ public:
implemented only under MSW). implemented only under MSW).
@endStyleTable @endStyleTable
Notice that not all styles are compatible: only one of @c wxOK and @c Notice that not all styles are compatible: only one of @c wxOK and
wxYES_NO may be specified (and one of them must be specified) and at @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 most one default button style can be used and it is only valid if the
corresponding button is shown in the message box. corresponding button is shown in the message box.
@@ -161,8 +159,7 @@ public:
virtual bool SetYesNoLabels(const ButtonLabel& yes, const ButtonLabel& no); virtual bool SetYesNoLabels(const ButtonLabel& yes, const ButtonLabel& no);
/** /**
Shows the dialog, returning one of wxID_OK, wxID_CANCEL, wxID_YES, Shows the dialog, returning one of wxID_OK, wxID_CANCEL, wxID_YES, wxID_NO.
wxID_NO.
Notice that this method returns the identifier of the button which was Notice that this method returns the identifier of the button which was
clicked unlike wxMessageBox() function. clicked unlike wxMessageBox() function.

35
interface/wx/msgqueue.h
View File

@@ -11,22 +11,28 @@
wxMessageQueue allows passing messages between threads. wxMessageQueue allows passing messages between threads.
This class should be typically used to communicate between the main and worker This class should be typically used to communicate between the main and worker
threads. The main thread calls wxMessageQueue::Post and threads. The main thread calls wxMessageQueue::Post and the worker thread
the worker thread calls wxMessageQueue::Receive. calls wxMessageQueue::Receive.
For this class a message is an object of arbitrary type T. Notice that For this class a message is an object of arbitrary type T.
often there is a some special message indicating that the thread 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 should terminate as there is no other way to gracefully shutdown a thread
waiting on the message queue. waiting on the message queue.
@nolibrary @nolibrary
@category{FIXME} @category{misc}
@see wxThread @see wxThread
*/ */
class wxMessageQueue<T> class wxMessageQueue<T>
{ {
public: 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 Returns @true if the object had been initialized successfully, @false
if an error occurred. if an error occurred.
@@ -37,32 +43,31 @@ public:
Add a message to this queue and signal the threads waiting for messages Add a message to this queue and signal the threads waiting for messages
(i.e. the threads which called wxMessageQueue::Receive or (i.e. the threads which called wxMessageQueue::Receive or
wxMessageQueue::ReceiveTimeout). wxMessageQueue::ReceiveTimeout).
This method is safe to call from multiple threads in parallel. This method is safe to call from multiple threads in parallel.
*/ */
wxMessageQueueError Post(T const& msg); wxMessageQueueError Post(T const& msg);
/** /**
Block until a message becomes available in the queue. Waits indefinitely long Block until a message becomes available in the queue.
or until an error occurs. Waits indefinitely long or until an error occurs.
The message is returned in @e msg.
The message is returned in @a msg.
*/ */
wxMessageQueueError Receive(T& msg); wxMessageQueueError Receive(T& msg);
/** /**
Block until a message becomes available in the queue, but no more than Block until a message becomes available in the queue, but no more than
@a timeout milliseconds has elapsed. @a timeout milliseconds has elapsed.
If no message is available after @a timeout milliseconds then returns If no message is available after @a timeout milliseconds then returns
@b wxMSGQUEUE_TIMEOUT. @b wxMSGQUEUE_TIMEOUT.
If @a timeout is 0 then checks for any messages present in the queue If @a timeout is 0 then checks for any messages present in the queue
and returns immediately without waiting. and returns immediately without waiting.
The message is returned in @e msg.
The message is returned in @a msg.
*/ */
wxMessageQueueError ReceiveTimeout(long timeout, T& msg); wxMessageQueueError ReceiveTimeout(long timeout, T& msg);
/**
Default and only constructor. Use wxMessageQueue::IsOk to check
if the object was successfully initialized.
*/
wxMessageQueue();
}; };

34
interface/wx/mstream.h
View File

@@ -9,6 +9,7 @@
/** /**
@class wxMemoryOutputStream @class wxMemoryOutputStream
@todo describe me.
@library{wxbase} @library{wxbase}
@category{streams} @category{streams}
@@ -21,6 +22,9 @@ public:
/** /**
If @a data is @NULL, then it will initialize a new empty buffer which will If @a data is @NULL, then it will initialize a new empty buffer which will
grow if required. 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); wxMemoryOutputStream(char* data = NULL, size_t length = 0);
@@ -30,9 +34,8 @@ public:
virtual ~wxMemoryOutputStream(); virtual ~wxMemoryOutputStream();
/** /**
CopyTo allowed you to transfer data from the internal buffer of Allows you to transfer data from the internal buffer of wxMemoryOutputStream
wxMemoryOutputStream to an external buffer. @a len specifies the size of to an external buffer. @a len specifies the size of the buffer.
the buffer.
*/ */
size_t CopyTo(char* buffer, size_t len) const; size_t CopyTo(char* buffer, size_t len) const;
@@ -48,6 +51,7 @@ public:
/** /**
@class wxMemoryInputStream @class wxMemoryInputStream
@todo describe me.
@library{wxbase} @library{wxbase}
@category{streams} @category{streams}
@@ -57,19 +61,29 @@ public:
class wxMemoryInputStream : public wxInputStream class wxMemoryInputStream : public wxInputStream
{ {
public: public:
//@{
/** /**
Creates a new read-only memory stream, initializing it with the Initializes a new read-only memory stream which will use the specified
data from the given input stream @e stream. buffer data of length len. The stream does not take ownership of the buffer,
The @a len argument specifies the amount of data to read from i.e. the buffer will not be deleted in its destructor.
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).
*/ */
wxMemoryInputStream(const char* data, size_t len); 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); 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, wxMemoryInputStream(wxInputStream& stream,
wxFileOffset len = wxInvalidOffset); wxFileOffset len = wxInvalidOffset);
//@}
/** /**
Destructor. Destructor.