AuroraMiddleware/wxWidgets
1
0
Fork 0
Code Issues Pull Requests 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
Show Stats 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
@wxheader{mdi.h}
An MDI client window is a child of wxMDIParentFrame, and manages zero or
more wxMDIChildFrame objects.
@library{wxcore}
@category{managedwnd}
@remarks
The client window is the area where MDI child windows exist. It doesn't have to
@ -32,6 +28,9 @@
Under Windows 95, the client window will automatically have a sunken border style
when the active child is not maximized, and no border style when a child is maximized.
@library{wxcore}
@category{managedwnd}
@see wxMDIChildFrame, wxMDIParentFrame, wxFrame
*/
class wxMDIClientWindow : public wxWindow
@ -73,7 +72,6 @@ public:
/**
@class wxMDIParentFrame
@wxheader{mdi.h}
An MDI (Multiple Document Interface) parent frame is a window which can contain
MDI child frames in its own 'desktop'. It is a convenient way to avoid window
@ -176,6 +174,9 @@ public:
@remarks During the construction of the frame, the client window will be
created. To use a different class from wxMDIClientWindow, override
OnCreateClient().
Under Windows 95, the client window will automatically have a
sunken border style when the active child is not maximized,
and no border style when a child is maximized.
@see Create(), OnCreateClient()
*/
@ -220,8 +221,8 @@ public:
virtual void Cascade();
/**
Used in two-step frame construction. See wxMDIParentFrame()
for further details.
Used in two-step frame construction.
See wxMDIParentFrame() for further details.
*/
bool Create(wxWindow* parent, wxWindowID id,
const wxString& title,
@ -316,7 +317,7 @@ public:
Note that it is probably impossible to have a client window that scrolls
as well as painting a bitmap or pattern, since in @b OnScroll, the scrollbar
positions always return zero. (Solutions to: julian.smart@btopenworld.com).
positions always return zero.
@see GetClientWindow(), wxMDIClientWindow
*/
@ -353,8 +354,8 @@ public:
virtual void SetToolBar(wxWindow* toolbar);
/**
Call this to change the current Window menu. Ownership of the menu object
passes to the frame when you call this function.
Call this to change the current Window menu.
Ownership of the menu object passes to the frame when you call this function.
This call is available under Windows only.
@ -375,7 +376,6 @@ public:
/**
@class wxMDIChildFrame
@wxheader{mdi.h}
An MDI child frame is a frame that can only exist on a wxMDIClientWindow,
which is itself a child of wxMDIParentFrame.
@ -407,6 +407,19 @@ public:
Displays a thick frame around the window (Windows and Motif only).
@endStyleTable
@remarks
Although internally an MDI child frame is a child of the MDI client window,
in wxWidgets you create it as a child of wxMDIParentFrame.
You can usually forget that the client window exists.
MDI child frames are clipped to the area of the MDI client window, and may
be iconized on the client window.
You can associate a menubar with a child frame as usual, although an MDI
child doesn't display its menubar under its own title bar.
The MDI parent frame's menubar will be changed to reflect the currently
active child frame.
If there are currently no children, the parent frame's own menubar will
be displayed.
@library{wxcore}
@category{managedwnd}
@ -466,8 +479,8 @@ public:
virtual void Activate();
/**
Used in two-step frame construction. See wxMDIChildFrame()
for further details.
Used in two-step frame construction.
See wxMDIChildFrame() for further details.
*/
bool Create(wxWindow* parent, wxWindowID id,
const wxString& title,

186
interface/wx/mediactrl.h
View File

@ -65,19 +65,15 @@ public:
/**
@class wxMediaCtrl
wxMediaCtrl is a class for displaying types of
media, such as videos, audio files, natively through native codecs.
wxMediaCtrl is a class for displaying types of media, such as videos, audio
files, natively through native codecs.
wxMediaCtrl uses native backends to render media, for example on Windows
there is a ActiveMovie/DirectShow backend, and on Macintosh there is a
QuickTime backend.
@library{wxmedia}
@category{media}
@see wxMediaEvent
@section class_mediactrl_rendering_media Rendering media
@section mediactrl_rendering_media Rendering media
Depending upon the backend, wxMediaCtrl can render and display pretty much any
kind of media that the native system can - such as an image, mpeg video, or mp3
@ -93,7 +89,7 @@ public:
of the backend. For example, QuickTime cannot set the playback rate of certain
streaming media - while DirectShow is slightly more flexible in that regard.
@section class_mediactrl_operation Operation
@section mediactrl_operation Operation
When wxMediaCtrl plays a file, it plays until the stop position is reached
(currently the end of the file/stream). Right before it hits the end of the stream,
@ -120,85 +116,120 @@ public:
}
@endcode
When wxMediaCtrl stops, either by the @c EVT_MEDIA_STOP not being vetoed, or by manually
calling Stop(), where it actually stops is not at the beginning, rather, but at the beginning
of the stream. That is, when it stops and play is called, playback is gauranteed to start at
the beginning of the media. This is because some streams are not seekable, and when stop is
called on them they return to the beginning, thus wxMediaCtrl tries to keep consistant for all types
of media.
When wxMediaCtrl stops, either by the @c EVT_MEDIA_STOP not being vetoed, or
by manually calling Stop(), where it actually stops is not at the beginning,
rather, but at the beginning of the stream. That is, when it stops and play
is called, playback is gauranteed to start at the beginning of the media.
This is because some streams are not seekable, and when stop is called on
them they return to the beginning, thus wxMediaCtrl tries to keep consistant
for all types of media.
Note that when changing the state of the media through Play() and other methods, the media may not
actually be in the @c wxMEDIASTATE_PLAYING, for example. If you are relying on the media being in
certain state catch the event relevant to the state. See wxMediaEvent for the kinds of events that
you can catch.
Note that when changing the state of the media through Play() and other methods,
the media may not actually be in the @c wxMEDIASTATE_PLAYING, for example.
If you are relying on the media being in certain state catch the event relevant
to the state. See wxMediaEvent for the kinds of events that you can catch.
@section class_mediactrl_video_size Video size
By default, wxMediaCtrl will scale the size of the video to the requested amount passed to either
its constructor or Create(). After calling Load or performing an equivilant operation, you can
subsequently obtain the "real" size of the video (if there is any) by calling GetBestSize().
Note that the actual result on the display will be slightly different when ShowPlayerControls is
activated and the actual video size will be less then specified due to the extra controls provided
by the native toolkit. In addition, the backend may modify GetBestSize() to include the size of
the extra controls - so if you want the real size of the video just disable ShowPlayerControls().
@section mediactrl_video_size Video size
The idea with setting GetBestSize() to the size of the video is that GetBestSize() is a wxWindow-derived
function that is called when sizers on a window recalculate. What this means is that if you use sizers
by default the video will show in its original size without any extra assistance needed from the user.
By default, wxMediaCtrl will scale the size of the video to the requested
amount passed to either its constructor or Create().
After calling wxMediaCtrl::Load or performing an equivilant operation,
you can subsequently obtain the "real" size of the video (if there is any)
by calling wxMediaCtrl::GetBestSize(). Note that the actual result on the
display will be slightly different when wxMediaCtrl::ShowPlayerControls is
activated and the actual video size will be less then specified due to the
extra controls provided by the native toolkit.
In addition, the backend may modify wxMediaCtrl::GetBestSize() to include
the size of the extra controls - so if you want the real size of the video
just disable wxMediaCtrl::ShowPlayerControls().
@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
for a particular reason, such as QuickTime for playing .mov files, all you need to do to choose a specific
backend is to pass the name of the backend class to Create().
Normally, when you use wxMediaCtrl it is just a window for the video to play in.
However, some toolkits have their own media player interface.
For example, QuickTime generally has a bar below the video with a slider.
A special feature available to wxMediaCtrl, you can use the toolkits interface
instead of making your own by using the ShowPlayerControls() function.
There are several options for the flags parameter, with the two general flags
being @c wxMEDIACTRLPLAYERCONTROLS_NONE which turns off the native interface,
and @c wxMEDIACTRLPLAYERCONTROLS_DEFAULT which lets wxMediaCtrl decide what
native controls on the interface.
Be sure to review the caveats outlined in @ref mediactrl_video_size before doing so.
@section mediactrl_choosing_backend Choosing a backend
Generally, you should almost certainly leave this part up to wxMediaCtrl -
but if you need a certain backend for a particular reason, such as QuickTime
for playing .mov files, all you need to do to choose a specific backend is
to pass the name of the backend class to wxMediaCtrl::Create().
The following are valid backend identifiers:
@beginTable
@row2col{@b wxMEDIABACKEND_DIRECTSHOW, Use ActiveMovie/DirectShow. Uses the native ActiveMovie (I.E. DirectShow) control. Default backend on Windows and supported by nearly all Windows versions, even some Windows CE versions. May display a windows media player logo while inactive.}
@row2col{@b wxMEDIABACKEND_QUICKTIME, Use QuickTime. Mac Only. WARNING: May not working correctly embedded in a wxNotebook.}
@row2col{@b wxMEDIABACKEND_GSTREAMER, Use GStreamer. Unix Only. Requires GStreamer 0.8 along with at the very least the xvimagesink, xoverlay, and gst-play modules of gstreamer to function. You need the correct modules to play the relavant files, for example the mad module to play mp3s, etc.}
@row2col{@b wxMEDIABACKEND_WMP10, Uses Windows Media Player 10 (Windows only) - works on mobile machines with Windows Media Player 10 and desktop machines with either Windows Media Player 9 or 10}
@endTable
- @b wxMEDIABACKEND_DIRECTSHOW: Use ActiveMovie/DirectShow.
Uses the native ActiveMovie (I.E. DirectShow) control.
Default backend on Windows and supported by nearly all Windows versions,
even some Windows CE versions.
May display a windows media player logo while inactive.
- @b wxMEDIABACKEND_QUICKTIME: Use QuickTime. Mac Only.
WARNING: May not working correctly embedded in a wxNotebook.
- @b wxMEDIABACKEND_GSTREAMER, Use GStreamer. Unix Only.
Requires GStreamer 0.8 along with at the very least the xvimagesink, xoverlay,
and gst-play modules of gstreamer to function.
You need the correct modules to play the relavant files, for example the
mad module to play mp3s, etc.
- @b wxMEDIABACKEND_WMP10, Uses Windows Media Player 10 (Windows only) -
works on mobile machines with Windows Media Player 10 and desktop machines
with either Windows Media Player 9 or 10.
Note that other backends such as wxMEDIABACKEND_MCI can now be found at wxCode(http://wxcode.sourceforge.net/).
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
and implement the methods you want. The methods in wxMediaBackend correspond to those in wxMediaCtrl except
for CreateControl which does the actual creation of the control, in cases where a custom control is not
needed you may simply call wxControl::Create().
@section mediactrl_creating_backend Creating a backend
Creating a backend for wxMediaCtrl is a rather simple process.
Simply derive from wxMediaBackendCommonBase and implement the methods you want.
The methods in wxMediaBackend correspond to those in wxMediaCtrl except for
wxMediaCtrl::CreateControl which does the actual creation of the control,
in cases where a custom control is not needed you may simply call wxControl::Create().
You need to make sure to use the @c DECLARE_CLASS and @c IMPLEMENT_CLASS macros.
The only real tricky part is that you need to make sure the file in compiled in, which if there are
just backends in there will not happen and you may need to use a force link hack
(see http://www.wxwidgets.org/wiki/index.php/RTTI).
The only real tricky part is that you need to make sure the file in compiled in,
which if there are just backends in there will not happen and you may need to
use a force link hack (see http://www.wxwidgets.org/wiki/index.php/RTTI).
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
{
public:
/**
Default constructor - you MUST call Create before calling any other methods of wxMediaCtrl.
Default constructor - you MUST call Create() before calling any
other methods of wxMediaCtrl.
*/
wxMediaCtrl();
/**
Constructor that calls Create(). You may prefer to call Create() directly to check
to see if wxMediaCtrl is available on the system.
Constructor that calls Create().
You may prefer to call Create() directly to check to see if
wxMediaCtrl is available on the system.
@param parent
parent of this control. Must not be @NULL.
@ -213,8 +244,7 @@ public:
@param style
Optional styles.
@param szBackend
Name of backend you want to use, leave blank to make
wxMediaCtrl figure it out.
Name of backend you want to use, leave blank to make wxMediaCtrl figure it out.
@param validator
validator to use.
@param name
@ -226,14 +256,14 @@ public:
const wxValidator& validator = wxDefaultValidator,
const wxString& name = wxPanelNameStr);
/**
Creates this control. Returns @false if it can't load the movie located at @a fileName
Creates this control.
Returns @false if it can't load the movie located at @a fileName
or it cannot load one of its native backends.
If you specify a file to open via @a fileName and you don't specify a backend to
use, wxMediaCtrl tries each of its backends until one that can render the path referred to
by @a fileName can be found.
If you specify a file to open via @a fileName and you don't specify a
backend to use, wxMediaCtrl tries each of its backends until one that
can render the path referred to by @a fileName can be found.
@param parent
parent of this control. Must not be @NULL.
@ -248,8 +278,7 @@ public:
@param style
Optional styles.
@param szBackend
Name of backend you want to use, leave blank to make
wxMediaCtrl figure it out.
Name of backend you want to use, leave blank to make wxMediaCtrl figure it out.
@param validator
validator to use.
@param name
@ -263,7 +292,8 @@ public:
/**
Obtains the best size relative to the original/natural size of the
video, if there is any. See @ref class_mediactrl_video_size for more information.
video, if there is any.
See @ref mediactrl_video_size for more information.
*/
wxSize GetBestSize();
@ -290,8 +320,8 @@ public:
/**
Gets the volume of the media from a 0.0 to 1.0 range.
@note Due to rounding and other errors the value returned may not be the exact value
sent to SetVolume().
@note Due to rounding and other errors the value returned may not be the
exact value sent to SetVolume().
*/
double GetVolume();
@ -306,8 +336,9 @@ public:
bool Load(const wxString& fileName);
/**
Loads the location that uri refers to. Note that this is very implementation-dependant,
although HTTP URI/URLs are generally supported, for example. Returns @false if loading fails.
Loads the location that uri refers to. Note that this is very
implementation-dependant, although HTTP URI/URLs are generally
supported, for example. Returns @false if loading fails.
*/
bool Load(const wxURI& uri);
@ -324,7 +355,8 @@ public:
bool LoadURI(const wxURI& uri);
/**
Same as Load(const wxURI& uri, const wxURI& proxy). Kept for wxPython compatibility.
Same as Load(const wxURI& uri, const wxURI& proxy).
Kept for wxPython compatibility.
*/
bool LoadURIWithProxy(const wxURI& uri, const wxURI& proxy);
@ -375,7 +407,7 @@ public:
default controls provided by the toolkit. The function takes a
wxMediaCtrlPlayerControls enumeration, please see available show modes there.
For more see @ref class_mediactrl_player_controls.
For more see @ref mediactrl_player_controls.
Currently only implemented on the QuickTime and DirectShow backends.
The function returns @true on success.
@ -385,7 +417,7 @@ public:
/**
Stops the media.
See @ref class_mediactrl_operation for an overview of how stopping works.
See @ref mediactrl_operation for an overview of how stopping works.
*/
bool Stop();

132
interface/wx/memory.h
View File

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

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.
@remarks
To respond to a menu selection, provide a handler for EVT_MENU, in the frame
that contains the menu bar.
If you have a toolbar which uses the same identifiers as your EVT_MENU entries,
events from the toolbar will also be processed by your EVT_MENU event handlers.
Tip: under Windows, if you discover that menu shortcuts (for example, Alt-F
to show the file menu) are not working, check any EVT_CHAR events you are
handling in child windows.
If you are not calling event.Skip() for events that you don't process in
these event handlers, menu shortcuts may cease to work.
@library{wxcore}
@category{menus}
@see wxMenu, @ref overview_eventhandling "Event Handling Overview"
@see wxMenu, @ref overview_eventhandling
*/
class wxMenuBar : public wxWindow
{
public:
/**
Construct an empty menu barM
Construct an empty menu bar.
@param style
If wxMB_DOCKABLE the menu bar can be detached (wxGTK only).
*/
wxMenuBar(long style = 0);
/**
Construct a menu bar from arrays of menus and titles.
@ -45,8 +59,8 @@ public:
long style = 0);
/**
Destructor, destroying the menu bar and removing it from the parent frame (if
any).
Destructor, destroying the menu bar and removing it from the parent
frame (if any).
*/
virtual ~wxMenuBar();
@ -54,7 +68,7 @@ public:
Adds the item to the end of the menu bar.
@param menu
The menu to add. Do not deallocate this menu after calling Append.
The menu to add. Do not deallocate this menu after calling Append().
@param title
The title of the menu.
@ -116,8 +130,10 @@ public:
/**
Returns the index of the menu with the given @a title or @c wxNOT_FOUND if no
such menu exists in this menubar. The @a title parameter may specify either
the menu title (with accelerator characters, i.e. @c "File") or just the
such menu exists in this menubar.
The @a title parameter may specify either the menu title
(with accelerator characters, i.e. @c "&File") or just the
menu label (@c "File") indifferently.
*/
int FindMenu(const wxString& title) const;
@ -176,6 +192,9 @@ public:
@remarks Use only after the menubar has been associated with a frame.
@deprecated
This function is deprecated in favour of GetMenuLabel() and GetMenuLabelText().
@see SetLabelTop()
*/
wxString GetLabelTop(int pos) const;
@ -225,8 +244,7 @@ public:
/**
Inserts the menu at the given position into the menu bar. Inserting menu at
position 0 will insert it in the very beginning of it, inserting at position
GetMenuCount() is the same as calling
Append().
GetMenuCount() is the same as calling Append().
@param pos
The position of the new menu in the menu bar
@ -267,10 +285,9 @@ public:
void Refresh();
/**
Removes the menu from the menu bar and returns the menu object - the caller is
responsible for deleting it. This function may be used together with
Insert() to change the menubar
dynamically.
Removes the menu from the menu bar and returns the menu object - the caller
is responsible for deleting it. This function may be used together with
Insert() to change the menubar dynamically.
@see Replace()
*/
@ -286,8 +303,8 @@ public:
@param title
The title of the menu.
@return The menu which was previously at position pos. The caller is
responsible for deleting it.
@return The menu which was previously at position pos.
The caller is responsible for deleting it.
@see Insert(), Remove()
*/
@ -329,6 +346,9 @@ public:
@remarks Use only after the menubar has been associated with a frame.
@deprecated
This function has been deprecated in favour of SetMenuLabel().
@see GetLabelTop()
*/
void SetLabelTop(int pos, const wxString& label);
@ -360,20 +380,20 @@ public:
with a special identifier -1 is a separator item and doesn't have an
associated command but just makes a separator line appear in the menu.
@note Please note that @e wxID_ABOUT and @e wxID_EXIT are
predefined by wxWidgets and have a special meaning since entries
using these IDs will be taken out of the normal menus under MacOS X
and will be inserted into the system menu (following the appropriate
MacOS X interface guideline). On PalmOS @e wxID_EXIT is disabled according
to Palm OS Companion guidelines.
@note
Please note that @e wxID_ABOUT and @e wxID_EXIT are predefined by wxWidgets
and have a special meaning since entries using these IDs will be taken out
of the normal menus under MacOS X and will be inserted into the system menu
(following the appropriate MacOS X interface guideline).
On PalmOS @e wxID_EXIT is disabled according to Palm OS Companion guidelines.
Menu items may be either normal items, check items or radio items. Normal items
don't have any special properties while the check items have a boolean flag
associated to them and they show a checkmark in the menu when the flag is set.
Menu items may be either normal items, check items or radio items.
Normal items don't have any special properties while the check items have a
boolean flag associated to them and they show a checkmark in the menu when
the flag is set.
wxWidgets automatically toggles the flag value when the item is clicked and its
value may be retrieved using either wxMenu::IsChecked method
of wxMenu or wxMenuBar itself or by using
wxEvent::IsChecked when you get the menu
value may be retrieved using either wxMenu::IsChecked method of wxMenu or
wxMenuBar itself or by using wxEvent::IsChecked when you get the menu
notification for the item in question.
The radio items are similar to the check items except that all the other items
@ -385,12 +405,32 @@ public:
the radio items risks to not work correctly. Finally note that radio items
are not supported under Motif.
@section menu_allocation Allocation strategy
All menus except the popup ones must be created on the heap.
All menus attached to a menubar or to another menu will be deleted by their
parent when it is deleted.
As the frame menubar is deleted by the frame itself, it means that normally
all menus used are deleted automatically.
@section menu_eventhandling Event handling
If the menu is part of a menubar, then wxMenuBar event processing is used.
With a popup menu, there is a variety of ways to handle a menu selection event
(wxEVT_COMMAND_MENU_SELECTED).
Derive a new class from wxMenu and define event table entries using the EVT_MENU macro.
Set a new event handler for wxMenu, using an object whose class has EVT_MENU entries.
Provide EVT_MENU handlers in the window which pops up the menu, or in an
ancestor of this window.
@library{wxcore}
@category{menus}
@see wxMenuBar, wxWindow::PopupMenu,
@ref overview_eventhandling "Event Handling Overview",
@ref wxFileHistory "wxFileHistory (most recently used files menu)"
@see wxMenuBar, wxWindow::PopupMenu, @ref overview_eventhandling,
@ref wxFileHistory "wxFileHistory (most recently used files menu)"
*/
class wxMenu : public wxEvtHandler
{
@ -404,7 +444,7 @@ public:
wxMenu(long style);
/**
Constructs a wxMenu object with a title
Constructs a wxMenu object with a title.
@param title
Title at the top of the menu (not always supported).
@ -412,20 +452,22 @@ public:
If set to wxMENU_TEAROFF, the menu will be detachable (wxGTK only).
*/
wxMenu(const wxString& title = "", long style = 0);
/**
Destructor, destroying the menu.
Note: under Motif, a popup menu must have a valid parent (the window
it was last popped up on) when being destroyed. Therefore, make sure
you delete or re-use the popup menu @e before destroying the
parent window. Re-use in this context means popping up the menu on
a different window from last time, which causes an implicit destruction
and recreation of internal data structures.
@note
Under Motif, a popup menu must have a valid parent (the window
it was last popped up on) when being destroyed. Therefore, make sure
you delete or re-use the popup menu @e before destroying the parent
window. Re-use in this context means popping up the menu on a different
window from last time, which causes an implicit destruction and
recreation of internal data structures.
*/
virtual ~wxMenu();
/**
Adds a menu item.
Adds a menu item.
@param id
The menu command identifier.
@ -436,17 +478,48 @@ public:
By default, the handler for the wxEVT_MENU_HIGHLIGHT event displays
this string in the status line.
@param kind
May be wxITEM_SEPARATOR, wxITEM_NORMAL,
wxITEM_CHECK or wxITEM_RADIO
May be wxITEM_SEPARATOR, wxITEM_NORMAL, wxITEM_CHECK or wxITEM_RADIO
@remarks
This command can be used after the menu has been shown, as well as on
initial creation of a menu or menubar.
The item string for the normal menu items (not submenus or separators)
may include the accelerator which can be used to activate the menu item
from keyboard.
The accelerator string follows the item label and is separated from it
by a TAB character ('\\t').
Its general syntax is any combination of "CTRL", "ALT" and "SHIFT" strings
(case doesn't matter) separated by either '-' or '+' characters and followed
by the accelerator itself.
The accelerator may be any alphanumeric character, any function key
(from F1 to F12) or one of the special characters listed in the table
below (again, case doesn't matter):
- DEL or DELETE: Delete key
- INS or INSERT: Insert key
- ENTER or RETURN: Enter key
- PGUP: PageUp key
- PGDN: PageDown key
- LEFT: Left cursor arrow key
- RIGHT: Right cursor arrow key
- UP: Up cursor arrow key
- DOWN: Down cursor arrow key
- HOME: Home key
- END: End key
- SPACE: Space
- TAB: Tab key
- ESC: or ESCAPE Escape key (Windows only)
@see AppendSeparator(), AppendCheckItem(), AppendRadioItem(),
AppendSubMenu(), Insert(), SetLabel(),
GetHelpString(), SetHelpString(), wxMenuItem
AppendSubMenu(), Insert(), SetLabel(), GetHelpString(),
SetHelpString(), wxMenuItem
*/
wxMenuItem* Append(int id, const wxString& item = wxEmptyString,
const wxString& helpString = wxEmptyString,
wxItemKind kind = wxITEM_NORMAL);
/**
Adds a submenu.
@ -464,25 +537,30 @@ public:
this string in the status line.
@see AppendSeparator(), AppendCheckItem(), AppendRadioItem(),
AppendSubMenu(), Insert(), SetLabel(),
GetHelpString(), SetHelpString(), wxMenuItem
AppendSubMenu(), Insert(), SetLabel(), GetHelpString(),
SetHelpString(), wxMenuItem
*/
wxMenuItem* Append(int id, const wxString& item, wxMenu* subMenu,
const wxString& helpString = wxEmptyString);
/**
Adds a menu item object. This is the most generic variant of Append() method
because it may be used for both items (including separators) and submenus and
because you can also specify various extra properties of a menu item this way,
Adds a menu item object.
This is the most generic variant of Append() method because it may be
used for both items (including separators) and submenus and because
you can also specify various extra properties of a menu item this way,
such as bitmaps and fonts.
@param menuItem
A menuitem object. It will be owned by the wxMenu object after this function
is called, so do not delete it yourself.
A menuitem object. It will be owned by the wxMenu object after this
function is called, so do not delete it yourself.
@remarks
See the remarks for the other Append() overloads.
@see AppendSeparator(), AppendCheckItem(), AppendRadioItem(),
AppendSubMenu(), Insert(), SetLabel(),
GetHelpString(), SetHelpString(), wxMenuItem
AppendSubMenu(), Insert(), SetLabel(), GetHelpString(),
SetHelpString(), wxMenuItem
*/
wxMenuItem* Append(wxMenuItem* menuItem);
@ -495,9 +573,9 @@ public:
const wxString& helpString = "");
/**
Adds a radio item to the end of the menu. All consequent radio items form a
group and when an item in the group is checked, all the others are
automatically unchecked.
Adds a radio item to the end of the menu.
All consequent radio items form a group and when an item in the group is
checked, all the others are automatically unchecked.
@see Append(), InsertRadioItem()
*/
@ -520,8 +598,8 @@ public:
const wxString& help = wxEmptyString);
/**
Inserts a break in a menu, causing the next appended item to appear in a new
column.
Inserts a break in a menu, causing the next appended item to appear in
a new column.
*/
virtual void Break();
@ -620,7 +698,7 @@ public:
@return Menu item object or NULL if none is found.
*/
const wxMenuItem * FindItem(int id, wxMenu** menu = NULL) const;
const wxMenuItem* FindItem(int id, wxMenu** menu = NULL) const;
/**
Returns the wxMenuItem given a position in the menu.
@ -671,8 +749,10 @@ public:
size_t GetMenuItemCount() const;
/**
Returns the list of items in the menu. wxMenuItemList is a pseudo-template
list class containing wxMenuItem pointers, see wxList.
Returns the list of items in the menu.
wxMenuItemList is a pseudo-template list class containing wxMenuItem
pointers, see wxList.
*/
wxMenuItemList GetMenuItems() const;
@ -687,17 +767,19 @@ public:
wxString GetTitle() const;
/**
Inserts the given @a item before the position @e pos. Inserting the item
at position GetMenuItemCount() is the same
Inserts the given @a item before the position @a pos.
Inserting the item at position GetMenuItemCount() is the same
as appending it.
@see Append(), Prepend()
*/
wxMenuItem* Insert(size_t pos, wxMenuItem* item);
/**
Inserts the given @a item before the position @e pos. Inserting the item
at position GetMenuItemCount() is the same
Inserts the given @a item before the position @a pos.
Inserting the item at position GetMenuItemCount() is the same
as appending it.
@see Append(), Prepend()
@ -799,8 +881,8 @@ public:
/**
Removes the menu item from the menu but doesn't delete the associated C++
object. This allows you to reuse the same item later by adding it back to the menu
(especially useful with submenus).
object. This allows you to reuse the same item later by adding it back to
the menu (especially useful with submenus).
@param id
The identifier of the menu item to remove.
@ -808,11 +890,11 @@ public:
@return A pointer to the item which was detached from the menu.
*/
wxMenuItem* Remove(int id);
/**
Removes the menu item from the menu but doesn't delete the associated C++
object. This allows you to reuse the same item later by adding it back to the menu
(especially useful with submenus).
object. This allows you to reuse the same item later by adding it back to
the menu (especially useful with submenus).
@param item
The menu item to remove.
@ -860,9 +942,10 @@ public:
/**
Sends events to @a source (or owning window if @NULL) to update the
menu UI. This is called just before the menu is popped up with
wxWindow::PopupMenu, but
the application may call it at other times if required.
menu UI.
This is called just before the menu is popped up with wxWindow::PopupMenu,
but the application may call it at other times if required.
*/
void UpdateUI(wxEvtHandler* source = NULL);
};

75
interface/wx/menuitem.h
View File

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

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

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 and vice versa. After initialization the functions
GetFileTypeFromMimeType() and GetFileTypeFromExtension()
may be called: they will return a wxFileType object which
may be further queried for file description, icon and other attributes.
may be called: they will return a wxFileType object which may be further
queried for file description, icon and other attributes.
Under Windows, the MIME type information is queried from registry.
Under Linux and Unix, it is queried from the XDG data directories.
Under Windows, the MIME type information is queried from registry. Under
Linux and Unix, it is queried from the XDG data directories.
Currently, wxMimeTypesManager is limited to reading MIME type information.
The application should not construct its own manaer: it should use the
The application should not construct its own manager: it should use the
object pointer ::wxTheMimeTypesManger.
@section mimetypemanager_helpers Helper functions
All of these functions are static (i.e. don't need a wxMimeTypesManager object
to call them) and provide some useful operations for string representations of
MIME types. Their usage is recommended instead of directly working with MIME
types using wxString functions.
- wxMimeTypesManager::IsOfType()
@section mimetypemanager_ctor Constructor and destructor
NB: You won't normally need to use more than one wxMimeTypesManager object
in a program.
- wxMimeTypesManager::wxMimeTypesManager()
- wxMimeTypesManager::~wxMimeTypesManager()
@section mimetypemanager_query Query database
These functions are the heart of this class: they allow to find a file type
object from either file extension or MIME type.
If the function is successful, it returns a pointer to the wxFileType object
which must be deleted by the caller, otherwise NULL will be returned.
- wxMimeTypesManager::GetFileTypeFromMimeType()
- wxMimeTypesManager::GetFileTypeFromExtension()
@section mimetypemanager_init Initialization functions
Unix: These functions may be used to load additional files (except for the
default ones which are loaded automatically) containing MIME information in
either mailcap(5) or mime.types(5) format.
- wxMimeTypesManager::ReadMailcap()
- wxMimeTypesManager::ReadMimeTypes()
- wxMimeTypesManager::AddFallbacks()
@library{wxbase}
@category{misc}
@ -52,7 +95,7 @@ public:
/**
Gather information about the files with given extension and return the
corresponding wxFileType object or @NULL if the extension is unknown.
The @a extension parameter may have, or not, the leading dot, if it has it,
it is stripped automatically. It must not however be empty.
*/
@ -66,15 +109,15 @@ public:
/**
This function returns @true if either the given @a mimeType is exactly the
same as @a wildcard or if it has the same category and the subtype of
This function returns @true if either the given @a mimeType is exactly
the same as @a wildcard or if it has the same category and the subtype of
@a wildcard is '*'. Note that the '*' wildcard is not allowed in
@a mimeType itself.
The comparison don by this function is case insensitive so it is not
necessary to convert the strings to the same case before calling it.
*/
static bool IsOfType(const wxString& mimeType, const wxString& wildcard);
};
@ -87,12 +130,14 @@ wxMimeTypesManager* wxTheMimeTypesManager;
/**
@class wxFileType
This class holds information about a given @e file type. File type is the same
as
MIME type under Unix, but under Windows it corresponds more to an extension than
to MIME type (in fact, several extensions may correspond to a file type). This
object may be created in several different ways: the program might know the file
extension and wish to find out the corresponding MIME type or, conversely, it
This class holds information about a given @e file type.
File type is the same as MIME type under Unix, but under Windows it corresponds
more to an extension than to MIME type (in fact, several extensions may
correspond to a file type).
This object may be created in several different ways: the program might know the
file extension and wish to find out the corresponding MIME type or, conversely, it
might want to find the right extension for the file to which it writes the
contents of given MIME type. Depending on how it was created some fields may be
unknown so the return value of all the accessors @b must be checked: @false
@ -116,8 +161,74 @@ wxMimeTypesManager* wxTheMimeTypesManager;
typically correspond to the extension ".txt", but may as well be associated with
".ini" or ".conf".
@section filetype_example MessageParameters class
One of the most common usages of MIME is to encode an e-mail message.
The MIME type of the encoded message is an example of a message parameter.
These parameters are found in the message headers ("Content-XXX").
At the very least, they must specify the MIME type and the version of MIME
used, but almost always they provide additional information about the message
such as the original file name or the charset (for the text documents).
These parameters may be useful to the program used to open, edit, view or
print the message, so, for example, an e-mail client program will have to
pass them to this program. Because wxFileType itself can not know about
these parameters, it uses MessageParameters class to query them.
The default implementation only requires the caller to provide the file name
(always used by the program to be called - it must know which file to open)
and the MIME type and supposes that there are no other parameters.
If you wish to supply additional parameters, you must derive your own class
from MessageParameters and override GetParamValue() function, for example:
@code
// provide the message parameters for the MIME type manager
class MailMessageParameters : public wxFileType::MessageParameters
{
public:
MailMessageParameters(const wxString& filename,
const wxString& mimetype)
: wxFileType::MessageParameters(filename, mimetype)
{
}
virtual wxString GetParamValue(const wxString& name) const
{
// parameter names are not case-sensitive
if ( name.CmpNoCase("charset") == 0 )
return "US-ASCII";
else
return wxFileType::MessageParameters::GetParamValue(name);
}
};
@endcode
Now you only need to create an object of this class and pass it to, for example,
GetOpenCommand like this:
@code
wxString command;
if ( filetype->GetOpenCommand(&command,
MailMessageParameters("foo.txt", "text/plain")) )
{
// the full command for opening the text documents is in 'command'
// (it might be "notepad foo.txt" under Windows or "cat foo.txt" under Unix)
}
else
{
// we don't know how to handle such files...
}
@endcode
Windows: As only the file name is used by the program associated with the
given extension anyhow (but no other message parameters), there is no need
to ever derive from MessageParameters class for a Windows-only program.
@library{wxbase}
@category{FIXME}
@category{misc}
@see wxMimeTypesManager
*/
@ -137,30 +248,19 @@ public:
/**
This function is primarily intended for GetOpenCommand and GetPrintCommand
usage but may be also used by the application directly if, for example, you want
to use some non-default command to open the file.
The function replaces all occurrences of
format specification
with
%s
the full file name
%t
the MIME type
%{param}
the value of the parameter @e param
usage but may be also used by the application directly if, for example, you
want to use some non-default command to open the file.
The function replaces all occurrences of:
- %s with the full file name
- %t with the MIME type
- %{param} with the value of the parameter @e param
using the MessageParameters object you pass to it.
If there is no '%s' in the command string (and the string is not empty), it is
assumed that the command reads the data on stdin and so the effect is the same
as " %s" were appended to the string.
Unlike all other functions of this class, there is no error return for this
function.
*/
@ -177,24 +277,27 @@ public:
/**
If the function returns @true, the array @a extensions is filled
with all extensions associated with this file type: for example, it may
contain the following two elements for the MIME type "text/html" (notice the
absence of the leading dot): "html" and "htm".
contain the following two elements for the MIME type "text/html"
(notice the absence of the leading dot): "html" and "htm".
@b Windows: This function is currently not implemented: there is no
(efficient) way to retrieve associated extensions from the given MIME type on
this platform, so it will only return @true if the wxFileType object was
created
by wxMimeTypesManager::GetFileTypeFromExtension
function in the first place.
(efficient) way to retrieve associated extensions from the given MIME type
on this platform, so it will only return @true if the wxFileType object was
created by wxMimeTypesManager::GetFileTypeFromExtension function in the
first place.
*/
bool GetExtensions(wxArrayString& extensions);
/**
If the function returns @true, the @c iconLoc is filled with the
location of the icon for this MIME type. A wxIcon may be
created from @a iconLoc later.
location of the icon for this MIME type.
A wxIcon may be created from @a iconLoc later.
@b Windows: The function returns the icon shown by Explorer for the files of
the specified type.
@b Mac: This function is not implemented and always returns @false.
@b Unix: MIME manager gathers information about icons from GNOME
and KDE settings and thus GetIcon's success depends on availability
of these desktop environments.
@ -208,11 +311,12 @@ public:
bool GetMimeType(wxString* mimeType) const;
/**
Same as GetMimeType() but returns array of MIME
types. This array will contain only one item in most cases but sometimes,
notably under Unix with KDE, may contain more MIME types. This happens when
one file extension is mapped to different MIME types by KDE, mailcap and
mime.types.
Same as GetMimeType() but returns array of MIME types.
This array will contain only one item in most cases but sometimes,
notably under Unix with KDE, may contain more MIME types.
This happens when one file extension is mapped to different MIME types
by KDE, mailcap and mime.types.
*/
bool GetMimeType(wxArrayString& mimeTypes);
@ -220,52 +324,27 @@ public:
/**
With the first version of this method, if the @true is returned, the
string pointed to by @a command is filled with the command which must be
executed (see wxExecute()) in order to open the file of the
given type. In this case, the name of the file as well as any other parameters
is retrieved from MessageParameters()
class.
executed (see wxExecute()) in order to open the file of the given type.
In this case, the name of the file as well as any other parameters
is retrieved from MessageParameters() class.
In the second case, only the filename is specified and the command to be used
to open this kind of file is returned directly. An empty string is returned to
indicate that an error occurred (typically meaning that there is no standard way
to open this kind of files).
*/
bool GetOpenCommand(wxString* command,
MessageParameters& params);
bool GetOpenCommand(wxString* command, MessageParameters& params);
wxString GetOpenCommand(const wxString& filename);
//@}
/**
If the function returns @true, the string pointed to by @a command is filled
with the command which must be executed (see wxExecute()) in
order to print the file of the given type. The name of the file is
retrieved from MessageParameters() class.
*/
bool GetPrintCommand(wxString* command,
MessageParameters& params);
/**
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.
with the command which must be executed (see wxExecute()) in order to
print the file of the given type.
The name of the file is retrieved from the MessageParameters class.
*/
bool GetPrintCommand(wxString* command, MessageParameters& params);
};

60
interface/wx/minifram.h
View File

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

52
interface/wx/module.h
View File

@ -14,19 +14,19 @@
automatically called on wxWidgets startup and exit.
To define a new kind of module, derive a class from wxModule, override the
wxModule::OnInit and wxModule::OnExit
functions, and add the DECLARE_DYNAMIC_CLASS and IMPLEMENT_DYNAMIC_CLASS to
header and implementation files (which can be the same file). On
initialization, wxWidgets will find all classes derived from wxModule, create
an instance of each, and call each OnInit function. On exit, wxWidgets will
call the OnExit function for each module instance.
wxModule::OnInit and wxModule::OnExit functions, and add the
DECLARE_DYNAMIC_CLASS and IMPLEMENT_DYNAMIC_CLASS to header and implementation
files (which can be the same file).
On initialization, wxWidgets will find all classes derived from wxModule, create
an instance of each, and call each wxModule::OnInit function. On exit, wxWidgets
will call the wxModule::OnExit function for each module instance.
Note that your module class does not have to be in a header file.
For example:
@code
// A module to allow DDE initialization/cleanup
// A module to allow DDE initialization/cleanup
// without calling these functions from app.cpp or from
// the user's application.
class wxDDEModule: public wxModule
@ -73,7 +73,7 @@
@endcode
@library{wxbase}
@category{FIXME}
@category{misc}
*/
class wxModule : public wxObject
{
@ -88,27 +88,32 @@ public:
*/
virtual ~wxModule();
//@{
/**
Call this function from the constructor of the derived class. @a dep must be
the CLASSINFO() of a wxModule-derived class and the
corresponding module will be loaded before and unloaded after
this module.
The second version of this function allows a dependency to be added by
name without access to the class info. This is useful when a module is
declared entirely in a source file and there is no header for the declaration
of the module needed by CLASSINFO(), however errors are
not detected until run-time, instead of compile-time, then.
Note that circular dependencies are detected and result in a fatal error.
Call this function from the constructor of the derived class.
@a dep must be the CLASSINFO() of a wxModule-derived class and the
corresponding module will be loaded before and unloaded after this module.
@param dep
The class information object for the dependent module.
*/
void AddDependency(wxClassInfo* dep);
/**
Call this function from the constructor of the derived class.
This overload allows a dependency to be added by name without access to
the class info.
This is useful when a module is declared entirely in a source file and
there is no header for the declaration of the module needed by CLASSINFO(),
however errors are not detected until run-time, instead of compile-time, then.
Note that circular dependencies are detected and result in a fatal error.
@param classname
The class name of the dependent module.
*/
void AddDependency(wxClassInfo* dep);
void AddDependency(const char* classname);
//@}
/**
Provide this function with appropriate cleanup for your module.
@ -116,9 +121,8 @@ public:
virtual void OnExit();
/**
Provide this function with appropriate initialization for your module. If the
function
returns @false, wxWidgets will exit immediately.
Provide this function with appropriate initialization for your module.
If the function returns @false, wxWidgets will exit immediately.
*/
virtual bool OnInit();
};

7
interface/wx/mousestate.h
View File

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

13
interface/wx/msgdlg.h
View File

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

35
interface/wx/msgqueue.h
View File

@ -11,22 +11,28 @@
wxMessageQueue allows passing messages between threads.
This class should be typically used to communicate between the main and worker
threads. The main thread calls wxMessageQueue::Post and
the worker thread calls wxMessageQueue::Receive.
threads. The main thread calls wxMessageQueue::Post and the worker thread
calls wxMessageQueue::Receive.
For this class a message is an object of arbitrary type T. Notice that
often there is a some special message indicating that the thread
For this class a message is an object of arbitrary type T.
Notice that often there is a some special message indicating that the thread
should terminate as there is no other way to gracefully shutdown a thread
waiting on the message queue.
@nolibrary
@category{FIXME}
@category{misc}
@see wxThread
*/
class wxMessageQueue<T>
{
public:
/**
Default and only constructor.
Use wxMessageQueue::IsOk to check if the object was successfully initialized.
*/
wxMessageQueue();
/**
Returns @true if the object had been initialized successfully, @false
if an error occurred.
@ -37,32 +43,31 @@ public:
Add a message to this queue and signal the threads waiting for messages
(i.e. the threads which called wxMessageQueue::Receive or
wxMessageQueue::ReceiveTimeout).
This method is safe to call from multiple threads in parallel.
*/
wxMessageQueueError Post(T const& msg);
/**
Block until a message becomes available in the queue. Waits indefinitely long
or until an error occurs.
The message is returned in @e msg.
Block until a message becomes available in the queue.
Waits indefinitely long or until an error occurs.
The message is returned in @a msg.
*/
wxMessageQueueError Receive(T& msg);
/**
Block until a message becomes available in the queue, but no more than
@a timeout milliseconds has elapsed.
If no message is available after @a timeout milliseconds then returns
@b wxMSGQUEUE_TIMEOUT.
If @a timeout is 0 then checks for any messages present in the queue
and returns immediately without waiting.
The message is returned in @e msg.
The message is returned in @a 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
@todo describe me.
@library{wxbase}
@category{streams}
@ -21,6 +22,9 @@ public:
/**
If @a data is @NULL, then it will initialize a new empty buffer which will
grow if required.
@warning
If the buffer is created, it will be destroyed at the destruction of the stream.
*/
wxMemoryOutputStream(char* data = NULL, size_t length = 0);
@ -30,9 +34,8 @@ public:
virtual ~wxMemoryOutputStream();
/**
CopyTo allowed you to transfer data from the internal buffer of
wxMemoryOutputStream to an external buffer. @a len specifies the size of
the buffer.
Allows you to transfer data from the internal buffer of wxMemoryOutputStream
to an external buffer. @a len specifies the size of the buffer.
*/
size_t CopyTo(char* buffer, size_t len) const;
@ -48,6 +51,7 @@ public:
/**
@class wxMemoryInputStream
@todo describe me.
@library{wxbase}
@category{streams}
@ -57,19 +61,29 @@ public:
class wxMemoryInputStream : public wxInputStream
{
public:
//@{
/**
Creates a new read-only memory stream, initializing it with the
data from the given input stream @e stream.
The @a len argument specifies the amount of data to read from
the @e stream. Setting it to @e wxInvalidOffset means that
the @a stream is to be read entirely (i.e. till the EOF is reached).
Initializes a new read-only memory stream which will use the specified
buffer data of length len. The stream does not take ownership of the buffer,
i.e. the buffer will not be deleted in its destructor.
*/
wxMemoryInputStream(const char* data, size_t len);
/**
Creates a new read-only memory stream, initializing it with the data from
the given output stream @a stream.
*/
wxMemoryInputStream(const wxMemoryOutputStream& stream);
/**
Creates a new read-only memory stream, initializing it with the
data from the given input stream @a stream.
The @a len argument specifies the amount of data to read from the
@a stream. Setting it to @e wxInvalidOffset means that the @a stream
is to be read entirely (i.e. till the EOF is reached).
*/
wxMemoryInputStream(wxInputStream& stream,
wxFileOffset len = wxInvalidOffset);
//@}
/**
Destructor.