wxWidgets/interface/wx/infobar.h
Vadim Zeitlin a92b5dfe8c Initial wxInfoBar implementation.
Add generic implementation, documentation and examples showing the use of the
new class in the samples.

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@62268 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
2009-10-05 22:54:13 +00:00

214 lines
7.4 KiB
C++

/////////////////////////////////////////////////////////////////////////////
// Name: wx/infobar.h
// Purpose: interface of wxInfoBar
// Author: Vadim Zeitlin
// RCS-ID: $Id$
// Copyright: (c) 2009 Vadim Zeitlin <vadim@wxwidgets.org>
// Licence: wxWindows license
/////////////////////////////////////////////////////////////////////////////
/**
An info bar is a transient window shown at top or bottom of its parent
window to display non-critical information to the user.
This class provides another way to show messages to the user, intermediate
between message boxes and status bar messages. The message boxes are modal
and thus interrupt the users work flow and should be used sparingly for
this reason. However status bar messages are often too easy not to notice
at all. An info bar provides a way to present the messages which has a much
higher chance to be noticed by the user but without being annoying.
Info bar may show an icon (on the left), text message and, optionally,
buttons allowing the user to react to the information presented. It always
has a close button at the right allowing the user to dismiss it so it isn't
necessary to provide a button just to close it.
wxInfoBar calls its parent wxWindow::Layout() method and assumes that it
will change the parent layout appropriately depending on whether the info
bar itself is shown or hidden. Usually this is achieved by simply using a
sizer for the parent window layout and adding wxInfoBar to this sizer as
one of the items. Considering the usual placement of the info bars,
normally this sizer should be a vertical wxBoxSizer and the bar its first
or last element so the simplest possible example of using this class would
be:
@code
class MyFrame : public wxFrame
{
...
wxInfoBar *m_infoBar;
};
MyFrame::MyFrame()
{
...
m_infoBar = new wxInfoBar(this);
wxSizer *sizer = new wxBoxSizer(wxVERTICAL);
sizer->Add(m_infoBar, wxSizerFlags().Expand());
... add other frame controls to the sizer ...
SetSizer(sizer);
}
void MyFrame::SomeMethod()
{
m_infoBar->ShowMessage("Something happend", wxICON_INFORMATION);
}
@endcode
See the dialogs sample for more sophisticated examples.
Only generic implementation of this class exists currently but it is
planned to provide a native GTK+-based version in future wxWidgets releases
so avoid the use of the methods marked "generic only" for maximal
portability.
@library{wxadv}
@category{miscwnd}
@see wxStatusBar, wxMessageDialog
@since 2.9.1
*/
class wxInfoBar : public wxWindow
{
public:
/**
Default constructor.
Use Create() for the objects created using this constructor.
*/
wxInfoBar();
/**
Constructor creating the info bar window.
@see Create()
*/
wxInfoBar(wxWindow *parent, wxWindowID winid = wxID_ANY);
/**
Create the info bar window.
Notice that unlike most of the other wxWindow-derived classes,
wxInfoBar is created hidden and is only shown when ShowMessage() is
called. This is more convenient as usually the info bar is created to
be shown at some later time and not immediately and so creating it
hidden avoids the need to call Hide() explicitly from the code using
it.
This should be only called if the object was created using its default
constructor.
@param parent
A valid parent window pointer.
@param winid
The id of the info bar window, usually unused as currently no
events are generated by this class.
*/
wxInfoBar(wxWindow *parent, wxWindowID winid = wxID_ANY);
/**
Add a button to be shown in the info bar.
The button added by this method will be shown to the right of the text
(in LTR layout), with each successive button being added to the right
of the previous one.
Clicking the button will generate a normal event which can be handled
as usual. Notice that if you wish the info bar to be hidden when the
button is clicked, simply call @c event.Skip() in the button handler to
let the base class handler do it.
@param btnid
Id of the button. It will be used in the button message clicking
this button will generate.
@param label
The label of the button. It may only be empty if @a btnid is one of
the stock ids in which case the corresponding stock label (see
wxGetStockLabel()) will be used.
*/
void AddButton(wxWindowID btnid, const wxString& label = wxString());
/**
Show a message in the bar.
If the bar is currently hidden, it will be shown. Otherwise its message
will be updated in place.
@param msg
The text of the message.
@param flags
One of wxICON_NONE (default), wxICON_INFORMATION, wxICON_QUESTION,
wxICON_WARNING or wxICON_ERROR values. These flags have the same
meaning as in wxMessageDialog, i.e. show the corresponding icon in
the bar.
*/
void ShowMessage(const wxString& msg, int flags = wxICON_NONE);
/**
@name Generic version customization methods.
All these methods exist in the generic version of the class only.
The generic version uses wxWindow::ShowWithEffect() function to
progressively show it on the platforms which support it. The methods
here allow to change the default effect used (or disable it entirely)
and change its duration.
*/
//@{
/**
Set the effects to use when showing and hiding the bar.
Either or both of the parameters can be set to wxSHOW_EFFECT_NONE to
disable using effects entirely.
Notice that if you place the bar at the bottom of the window you should
reverse the effects used for showing and hiding for better appearance.
@param showEffect
The effect to use when showing the bar. By default,
wxSHOW_EFFECT_SLIDE_TO_BOTTOM which is appropriate for the bars
placed at the top of the window.
@param hideEffect
The effect to use when hiding the bar. By default,
wxSHOW_EFFECT_SLIDE_TO_TOP which is appropriate for the bars placed
at the top of the window.
*/
void SetShowHideEffects(wxShowEffect showEffect, wxShowEffect hideEffect);
/// Return the effect currently used for showing the bar.
wxShowEffect GetShowEffect() const;
/// Return the effect currently used for hiding the bar.
wxShowEffect GetHideEffect() const;
/**
Set the duration of the animation used when showing or hiding the bar.
By default, 500ms duration is used.
@param duration
Duration of the animation, in milliseconds.
*/
void SetEffectDuration(int duration);
/// Return the effect animation duration currently used.
int GetEffectDuration() const;
/**
Overridden base class methods changes the font of the text message.
wxInfoBar overrides this method to use the font passed to it for its
text message part. By default a larger and bold version of the standard
font is used.
This method is generic-only.
*/
virtual bool SetFont(const wxFont& font);
//@}
};