582 lines
13 KiB
Plaintext
582 lines
13 KiB
Plaintext
/*
|
|
* Copyright 2011 Haiku, Inc. All rights reserved.
|
|
* Distributed under the terms of the MIT License.
|
|
*
|
|
* Authors:
|
|
* John Scipione, jscipione@gmail.com
|
|
*
|
|
* Corresponds to:
|
|
* headers/os/interface/Alert.h rev 42274
|
|
* src/kits/interface/Alert.cpp rev 42274
|
|
*/
|
|
|
|
|
|
/*!
|
|
\file Alert.h
|
|
\ingroup interface
|
|
\ingroup libbe
|
|
\brief BAlert class definition and support enums.
|
|
*/
|
|
|
|
|
|
/*!
|
|
\enum alert_type
|
|
\ingroup interface
|
|
\brief Type of alert.
|
|
|
|
Determines which icon (if any) is displayed in the alert dialog.
|
|
Choose one option. If the constructor doesn't include an
|
|
alert_type argument than \c B_EMPTY_ALERT is used.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\var alert_type B_EMPTY_ALERT
|
|
|
|
No icon
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
/*!
|
|
\var alert_type B_INFO_ALERT
|
|
|
|
\image html https://www.haiku-os.org/images/alert_info_32.png
|
|
|
|
Info icon
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
/*!
|
|
\var alert_type B_IDEA_ALERT
|
|
|
|
\image html https://www.haiku-os.org/images/alert_idea_32.png
|
|
|
|
Idea icon
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
/*!
|
|
\var alert_type B_WARNING_ALERT
|
|
|
|
\image html https://www.haiku-os.org/images/alert_warning_32.png
|
|
|
|
Warning icon
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
/*!
|
|
\var alert_type B_STOP_ALERT
|
|
|
|
\image html https://www.haiku-os.org/images/alert_stop_32.png
|
|
|
|
Stop icon
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\enum button_spacing
|
|
\ingroup interface
|
|
\brief Method of spacing of buttons in alerts.
|
|
|
|
Determines how the buttons on the alert dialog are spaced relative
|
|
to each other. Choose one option. If the constructor doesn't include a
|
|
button_spacing argument than \c B_EVEN_SPACING is used.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\var button_spacing B_EVEN_SPACING
|
|
|
|
If the alert dialog has more than one button than the buttons are
|
|
spaced evenly across the bottom of the alert dialog.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\var button_spacing B_OFFSET_SPACING
|
|
|
|
If the alert dialog has more than one button than the leftmost button
|
|
is offset to the left-hand side of the dialog while the rest of the
|
|
buttons are grouped on the right. This is useful to separate off a
|
|
leftmost "Cancel" or "Delete" button.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\class BAlert
|
|
\ingroup interface
|
|
\ingroup libbe
|
|
\brief The BAlert class defines a modal alert dialog which displays a short
|
|
message and provides a set of labeled buttons that allow the user to
|
|
respond.
|
|
|
|
The alert can be configured with a set of one to three buttons. These
|
|
buttons are assigned indexes 0, 1, and 2 from right-to-left respectively
|
|
and are automatically positioned by the system. The user can either click
|
|
on one of the buttons or use a shortcut key to select a button.
|
|
|
|
The layout of the buttons can be configured by setting the #button_width
|
|
and #button_spacing properties in the BAlert constructor. The icon displayed
|
|
in the alert can also be configured by setting the #alert_type property. The
|
|
right-most button (index 0) is the default button which can be activated
|
|
by pushing the \key{Enter} key.
|
|
|
|
Below is an example of an unsaved changes alert dialog:
|
|
|
|
\image html BAlert_example.png
|
|
|
|
When the user responds by selecting one of the buttons the alert window is
|
|
removed from the screen. The index of the selected button is returned to
|
|
the calling application and the BAlert object is deleted.
|
|
|
|
The code used to create and display an alert dialog like the one shown
|
|
above is shown below:
|
|
|
|
\code
|
|
BAlert* alert = new BAlert("Close and save dialog", "Save changes to...",
|
|
"Cancel", "Don't save", "Save", B_WIDTH_AS_USUAL, B_OFFSET_SPACING,
|
|
B_WARNING_ALERT);
|
|
alert->SetShortcut(0, B_ESCAPE);
|
|
int32 button_index = alert->Go();
|
|
\endcode
|
|
|
|
The messaged displayed in the dialog window along with the button labels
|
|
are set by the strings in the contructor. The Cancel button is offset to
|
|
the left relative to the other buttons by setting the \c B_OFFSET_SPACING
|
|
flag. The \c B_WARNING_ALERT flag displays the exclamation mark icon in
|
|
the dialog.
|
|
|
|
Any alert with a Cancel button should map the \key{Escape} key as shown in
|
|
the example above. You can setup additional shortcut keys for the buttons
|
|
with the SetShortcut() method.
|
|
|
|
The Go() method does the work of loading up and removing the alert
|
|
window and returns the index of the button that the user selected.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BAlert::BAlert()
|
|
\brief Create an unconfigured BAlert dialog.
|
|
|
|
This method creates an unconfigured BAlert. You can configure it with
|
|
methods like SetText(), SetType() and SetButtonSpacing.
|
|
|
|
It is advised to use one of the other constructors that help set up all
|
|
the configuration in one go, instead of doing it piece by piece with this
|
|
method.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BAlert::BAlert(const char* title, const char* text,
|
|
const char* button1, const char* button2, const char* button3,
|
|
button_width width, alert_type type)
|
|
\brief Creates and initializes a BAlert dialog.
|
|
|
|
\param title The title of the window. Since the alert window doesn't have
|
|
a title tab, the title is not actually displayed anywhere but is
|
|
useful for debugging purposes.
|
|
\param text The text that is displayed at the top of the window.
|
|
\param button1 Button 1 label
|
|
\param button2 Button 2 label
|
|
\param button3 Button 3 label
|
|
\param width A constant that describes how the button should be sized.
|
|
Options are
|
|
\li \c B_WIDTH_AS_USUAL
|
|
\li \c B_WIDTH_FROM_WIDEST
|
|
\li \c B_WIDTH_FROM_LABEL
|
|
|
|
See button_width for details.
|
|
\param type Constant that determines which alert icon is displayed.
|
|
Options are
|
|
\li \c B_EMPTY_ALERT
|
|
\li \c B_INFO_ALERT
|
|
\li \c B_IDEA_ALERT
|
|
\li \c B_WARNING_ALERT
|
|
\li \c B_STOP_ALERT
|
|
|
|
See alert_type for details.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BAlert::BAlert(const char* title, const char* text, const char* button1,
|
|
const char* button2, const char* button3, button_width width,
|
|
button_spacing spacing, alert_type type)
|
|
\brief Creates and initializes a BAlert dialog.
|
|
|
|
You can also set the \a spacing with this constructor.
|
|
|
|
\param title The title of the window. Since the alert window doesn't have
|
|
a title tab, the title is not actually displayed anywhere but is
|
|
useful for debugging purposes.
|
|
\param text The text that is displayed at the top of the window.
|
|
\param button1 Button 1 label
|
|
\param button2 Button 2 label
|
|
\param button3 Button 3 label
|
|
\param width A constant that describes how the button should be sized.
|
|
Options are
|
|
\li \c B_WIDTH_AS_USUAL
|
|
\li \c B_WIDTH_FROM_WIDEST
|
|
\li \c B_WIDTH_FROM_LABEL
|
|
|
|
See button_width for details.
|
|
\param spacing Determines how the buttons are spaced. Options are
|
|
\li \c B_EVEN_SPACING
|
|
\li \c B_OFFSET_SPACING
|
|
|
|
See button_spacing for details.
|
|
\param type Constant that determines which alert icon is displayed.
|
|
Options are
|
|
\li \c B_EMPTY_ALERT
|
|
\li \c B_INFO_ALERT
|
|
\li \c B_IDEA_ALERT
|
|
\li \c B_WARNING_ALERT
|
|
\li \c B_STOP_ALERT
|
|
|
|
See alert_type for details.
|
|
|
|
\since BeOS R4
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BAlert::BAlert(BMessage* data)
|
|
\brief Unarchives an alert from a BMessage.
|
|
|
|
\param data The archive.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BAlert::~BAlert()
|
|
\brief Destructor method.
|
|
|
|
Standard Destructor method to delete a BAlert.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\name Archiving
|
|
*/
|
|
|
|
|
|
//! @{
|
|
|
|
|
|
/*!
|
|
\fn BArchivable* BAlert::Instantiate(BMessage* data)
|
|
\brief Instantiates a BAlert from a BMessage.
|
|
|
|
\param data The message to instantiate the BAlert.
|
|
|
|
\returns a BArchivable object of the BAlert.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn status_t BAlert::Archive(BMessage* data, bool deep) const
|
|
\brief Archives the BAlert into \a archive.
|
|
|
|
\param data The target archive which the BAlert \a data will go into.
|
|
\param deep Whether or not to recursively archive the BAlert's children.
|
|
|
|
\return A status code.
|
|
\retval B_OK The archive operation was successful.
|
|
\retval B_BAD_VALUE The archive operation failed.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
//! @}
|
|
|
|
|
|
/*!
|
|
\fn alert_type BAlert::Type() const
|
|
\brief Get the alert_type of this alert.
|
|
|
|
\return Returns one of the values from the alert_type enum.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn void BAlert::SetType(alert_type type)
|
|
\brief Set the type of the alert.
|
|
|
|
\param type Pass one of the alert_type enum values to set the type.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn void BAlert::SetIcon(BBitmap *bitmap)
|
|
\brief Set a custom icon for the alert.
|
|
|
|
\param bitmap A valid BBitmap. The bitmap is copied.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn void BAlert::SetText(const char *text)
|
|
\brief Set the text for the alert.
|
|
|
|
\param text The text you want the alert to display.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn void BAlert::SetButtonSpacing(button_spacing spacing)
|
|
\brief Set the button spacing for the alert.
|
|
|
|
\param spacing Pass one of the button_spacing values to configure the
|
|
spacing.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn void BAlert::SetButtonWidth(button_width width)
|
|
\brief Set the button width for the buttons of the alert.
|
|
|
|
\param width Pass one of the button_width values to configure the width.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn void BAlert::SetShortcut(int32 index, char key)
|
|
\brief Sets the shortcut character which is mapped to a button at the
|
|
specified \a index.
|
|
|
|
A button can only have one shortcut except for the rightmost button which,
|
|
in addition to the shortcut you set, is always mapped to \c B_ENTER.
|
|
|
|
If you create a "Cancel" button then you should set its shortcut to
|
|
\c B_ESCAPE.
|
|
|
|
\param index The \a index of the button to set the shortcut to.
|
|
\param key The shortcut character to set.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn char BAlert::Shortcut(int32 index) const
|
|
\brief Gets the shortcut character which is mapped to a button at the
|
|
specified \a index.
|
|
|
|
\param index The \a index of the button to get the shortcut of.
|
|
|
|
\return The shortcut character mapped to the button at the specified
|
|
\a index.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn int32 BAlert::Go()
|
|
\brief Displays the alert window.
|
|
|
|
This version of Go() that does not include an invoker is
|
|
synchronous. Go() returns once the user has clicked a button and
|
|
the panel has been removed from the screen. The BAlert object is
|
|
deleted before the method returns.
|
|
|
|
If the BAlert is sent a \c B_QUIT_REQUESTED message while the alert
|
|
window is still on screen then Go() returns -1.
|
|
|
|
\returns The index of the button clicked.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn status_t BAlert::Go(BInvoker* invoker)
|
|
\brief Displays the alert window from a specified \a invoker.
|
|
|
|
This version of Go() with an \a invoker is asynchronous. It returns
|
|
immediately with \c B_OK and the button \a index is set to the field
|
|
of the BMessage that is sent to the target of the \a invoker.
|
|
|
|
Go() deletes the BAlert object after the message is sent.
|
|
|
|
If you call Go() with a \c NULL invoker argument than the BMessage
|
|
is not sent.
|
|
|
|
If the BAlert is sent a \c B_QUIT_REQUESTED method while the alert
|
|
window is still on screen then the message is not sent.
|
|
|
|
\returns A status code.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn void BAlert::MessageReceived(BMessage* message)
|
|
\brief Initiates an action from a received message.
|
|
|
|
\copydetails BWindow::MessageReceived()
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn void BAlert::FrameResized(float newWidth, float newHeight)
|
|
\brief Resizes the alert dialog.
|
|
|
|
\copydetails BWindow::FrameResized()
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn void BAlert::AddButton(const char *label, char key=0)
|
|
\brief Adds a button to the alert.
|
|
|
|
\param label The label of the button.
|
|
\param key The key a user can press to quickly select this button.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn int32 BAlert::CountButtons() const
|
|
\brief Counts the number of buttons in the alert.
|
|
|
|
\return The number of buttons in this alert window.
|
|
|
|
\see AddButton() and ButtonAt()
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BButton* BAlert::ButtonAt(int32 index) const
|
|
\brief Returns a pointer to the BButton at the specified \a index.
|
|
|
|
The \a index of the buttons begins at \c 0 and counts from left to right.
|
|
If a BButton does not exist for the specified \a index then \c NULL is
|
|
returned.
|
|
|
|
\param index The \a index of the desired button.
|
|
|
|
\return A pointer to the BButton at the specified \a index.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BTextView* BAlert::TextView() const
|
|
\brief Returns the Alert's TextView.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BHandler* BAlert::ResolveSpecifier(BMessage* message, int32 index,
|
|
BMessage* specifier, int32 what, const char* property)
|
|
\copydoc BHandler::ResolveSpecifier()
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn status_t BAlert::GetSupportedSuites(BMessage* data)
|
|
\copydoc BWindow::GetSupportedSuites()
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn void BAlert::DispatchMessage(BMessage* msg, BHandler* handler)
|
|
\brief Sends out a message.
|
|
|
|
\copydetails BWindow::DispatchMessage()
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn void BAlert::Quit()
|
|
\brief Quits the window closing it.
|
|
|
|
\copydetails BWindow::Quit()
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn bool BAlert::QuitRequested()
|
|
\brief Hook method that gets called with the window is closed.
|
|
|
|
\copydetails BWindow::QuitRequested()
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BPoint BAlert::AlertPosition(float width, float height)
|
|
\brief Resizes the Alert window to the width and height specified and
|
|
return the Point of the top-left corner of the alert window.
|
|
|
|
\param width The desired \a width of the alert window.
|
|
\param height The desired \a height of the alert window.
|
|
|
|
\returns The BPoint of the top-left corner of the Alert window.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn status_t BAlert::Perform(perform_code code, void* _data)
|
|
\brief Perform some action. (Internal Method)
|
|
|
|
\param code The perform code.
|
|
\param _data A pointer to store some data.
|
|
|
|
\returns A status code.
|
|
|
|
\sa BLooper::Perform()
|
|
|
|
\since Haiku R1
|
|
*/
|