2009-10-05 18:54:13 -04:00
|
|
|
/////////////////////////////////////////////////////////////////////////////
|
|
|
|
// 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.
|
|
|
|
|
|
|
|
|
2009-10-05 18:55:10 -04:00
|
|
|
Currently this class is implemented generically (i.e. in the same
|
|
|
|
platform-independent way for all ports) and also natively in wxGTK but the
|
|
|
|
native implementation requires a recent -- as of this writing -- GTK+ 2.18
|
|
|
|
version.
|
2009-10-05 18:54:13 -04:00
|
|
|
|
|
|
|
@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
|
2009-10-05 18:55:40 -04:00
|
|
|
of the previous one. If any buttons are added to the info bar using
|
|
|
|
this method, the default "Close" button is not shown as it is assumed
|
|
|
|
that the extra buttons already allow the user to close it.
|
2009-10-05 18:54:13 -04:00
|
|
|
|
2009-10-05 18:55:32 -04:00
|
|
|
Clicking the button will generate a normal EVT_COMMAND_BUTTON_CLICKED
|
|
|
|
event which can be handled as usual. The default handler in wxInfoBar
|
|
|
|
itself closes the window whenever a button in it is clicked so 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. On the other hand, if you don't skip the event, the info bar will
|
|
|
|
remain opened so make sure to do it for at least some buttons to allow
|
|
|
|
the user to close it.
|
|
|
|
|
|
|
|
Notice that the generic wxInfoBar implementation handles the button
|
|
|
|
events itself and so they are not propagated to the info bar parent and
|
|
|
|
you need to either inherit from wxInfoBar and handle them in your
|
|
|
|
derived class or use wxEvtHandler::Connect(), as is done in the dialogs
|
|
|
|
sample, to handle the button events in the parent frame.
|
2009-10-05 18:54:13 -04:00
|
|
|
|
|
|
|
@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());
|
|
|
|
|
2009-10-05 18:55:17 -04:00
|
|
|
/**
|
|
|
|
Remove a button previously added by AddButton().
|
|
|
|
|
|
|
|
@param btnid
|
|
|
|
Id of the button to remove. If more than one button with the same
|
|
|
|
id is used in the info bar (which is in any case not recommended),
|
|
|
|
the last, i.e. most recently added, button with this id is removed.
|
|
|
|
*/
|
|
|
|
void RemoveButton(wxWindowID btnid);
|
|
|
|
|
2009-10-05 18:54:13 -04:00
|
|
|
/**
|
|
|
|
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
|
2009-10-05 18:55:10 -04:00
|
|
|
One of wxICON_NONE, wxICON_INFORMATION (default), wxICON_QUESTION,
|
2009-10-05 18:54:13 -04:00
|
|
|
wxICON_WARNING or wxICON_ERROR values. These flags have the same
|
2009-10-05 18:55:10 -04:00
|
|
|
meaning as in wxMessageDialog for the generic version, i.e. show
|
|
|
|
(or not, in case of wxICON_NONE) the corresponding icon in the bar
|
|
|
|
but can be interpreted by the native versions. For example, the
|
|
|
|
GTK+ native implementation doesn't show icons at all but uses this
|
|
|
|
parameter to select the appropriate background colour for the
|
|
|
|
notification.
|
2009-10-05 18:54:13 -04:00
|
|
|
*/
|
|
|
|
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
|
2009-10-05 18:55:10 -04:00
|
|
|
progressively show it on the platforms which support it (currently only
|
|
|
|
wxMSW). The methods here allow to change the default effect used (or
|
|
|
|
disable it entirely) and change its duration.
|
2009-10-05 18:54:13 -04:00
|
|
|
*/
|
|
|
|
//@{
|
|
|
|
|
|
|
|
/**
|
|
|
|
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);
|
|
|
|
|
|
|
|
//@}
|
|
|
|
};
|