AlertWindow Class Reference

A window that displays a message and has buttons for the user to react to it. More...

Inherits TopLevelWindow, and ButtonListener.

Public Types
enum	AlertIconType { NoIcon, QuestionIcon, WarningIcon, InfoIcon }
	The type of icon to show in the dialog box. More...
enum	ColourIds { backgroundColourId = 0x1001800, textColourId = 0x1001810, outlineColourId = 0x1001820 }
	A set of colour IDs to use to change the colour of various aspects of the alert box. More...
Public Member Functions
	AlertWindow (const String &title, const String &message, AlertIconType iconType, Component *associatedComponent=0)
	Creates an AlertWindow.
	~AlertWindow ()
	Destroys the AlertWindow.
AlertIconType	getAlertType () const throw ()
	Returns the type of alert icon that was specified when the window was created.
void	setMessage (const String &message)
	Changes the dialog box's message.
void	addButton (const String &name, int returnValue, const KeyPress &shortcutKey1=KeyPress(), const KeyPress &shortcutKey2=KeyPress())
	Adds a button to the window.
int	getNumButtons () const
	Returns the number of buttons that the window currently has.
void	addTextEditor (const String &name, const String &initialContents, const String &onScreenLabel=String::empty, bool isPasswordBox=false)
	Adds a textbox to the window for entering strings.
const String	getTextEditorContents (const String &nameOfTextEditor) const
	Returns the contents of a named textbox.
void	addComboBox (const String &name, const StringArray &items, const String &onScreenLabel=String::empty)
	Adds a drop-down list of choices to the box.
ComboBox *	getComboBoxComponent (const String &nameOfList) const
	Returns a drop-down list that was added to the AlertWindow.
void	addTextBlock (const String &text)
	Adds a block of text.
void	addProgressBarComponent (double &progressValue)
	Adds a progress-bar to the window.
void	addCustomComponent (Component *component)
	Adds a user-defined component to the dialog box.
int	getNumCustomComponents () const
	Returns the number of custom components in the dialog box.
Component *	getCustomComponent (int index) const
	Returns one of the custom components in the dialog box.
Component *	removeCustomComponent (int index)
	Removes one of the custom components in the dialog box.
bool	containsAnyExtraComponents () const
	Returns true if the window contains any components other than just buttons.
Static Public Member Functions
static void JUCE_CALLTYPE	showMessageBox (AlertIconType iconType, const String &title, const String &message, const String &buttonText=String::empty, Component *associatedComponent=0)
	Shows a dialog box that just has a message and a single button to get rid of it.
static bool JUCE_CALLTYPE	showOkCancelBox (AlertIconType iconType, const String &title, const String &message, const String &button1Text=String::empty, const String &button2Text=String::empty, Component *associatedComponent=0)
	Shows a dialog box with two buttons.
static int JUCE_CALLTYPE	showYesNoCancelBox (AlertIconType iconType, const String &title, const String &message, const String &button1Text=String::empty, const String &button2Text=String::empty, const String &button3Text=String::empty, Component *associatedComponent=0)
	Shows a dialog box with three buttons.
static bool JUCE_CALLTYPE	showNativeDialogBox (const String &title, const String &bodyText, bool isOkCancel)
	Shows an operating-system native dialog box.
Protected Member Functions
void	paint (Graphics &g)
void	mouseDown (const MouseEvent &e)
void	mouseDrag (const MouseEvent &e)
bool	keyPressed (const KeyPress &key)
void	buttonClicked (Button *button)
void	lookAndFeelChanged ()
void	userTriedToCloseWindow ()
int	getDesktopWindowStyleFlags () const

Detailed Description

A window that displays a message and has buttons for the user to react to it.

For simple dialog boxes with just a couple of buttons on them, there are some static methods for running these.

For more complex dialogs, an AlertWindow can be created, then it can have some buttons and components added to it, and its runModalLoop() method is then used to show it. The value returned by runModalLoop() shows which button the user pressed to dismiss the box.

See also:: ThreadWithProgressWindow

Member Enumeration Documentation

enum AlertWindow::AlertIconType

The type of icon to show in the dialog box.

Enumerator:

NoIcon	No icon will be shown on the dialog box.
QuestionIcon	A question-mark icon, for dialog boxes that need the user to answer a question.
WarningIcon	An exclamation mark to indicate that the dialog is a warning about something and shouldn't be ignored.
InfoIcon	An icon that indicates that the dialog box is just giving the user some information, which doesn't require a response from them.

enum AlertWindow::ColourIds

A set of colour IDs to use to change the colour of various aspects of the alert box.

These constants can be used either via the Component::setColour(), or LookAndFeel::setColour() methods.

See also:: Component::setColour, Component::findColour, LookAndFeel::setColour, LookAndFeel::findColour

Enumerator:

backgroundColourId	The background colour for the window.
textColourId	The colour for the text.
outlineColourId	An optional colour to use to draw a border around the window.

Constructor & Destructor Documentation

AlertWindow::AlertWindow	(	const String &	title,
		const String &	message,
		AlertIconType	iconType,
		Component *	associatedComponent = `0`
	)

Creates an AlertWindow.

Parameters:

	title	the headline to show at the top of the dialog box
	message	a longer, more descriptive message to show underneath the headline
	iconType	the type of icon to display
	associatedComponent	if this is non-zero, it specifies the component that the alert window should be associated with. Depending on the look and feel, this might be used for positioning of the alert window.

AlertWindow::~AlertWindow ( )

Destroys the AlertWindow.

Member Function Documentation

AlertIconType AlertWindow::getAlertType ( ) const throw ()

Returns the type of alert icon that was specified when the window was created.

void AlertWindow::setMessage ( const String & message )

Changes the dialog box's message.

This will also resize the window to fit the new message if required.

void AlertWindow::addButton	(	const String &	name,
		int	returnValue,
		const KeyPress &	shortcutKey1 = `KeyPress()`,
		const KeyPress &	shortcutKey2 = `KeyPress()`
	)

Adds a button to the window.

Parameters:

	name	the text to show on the button
	returnValue	the value that should be returned from runModalLoop() if this is the button that the user presses.
	shortcutKey1	an optional key that can be pressed to trigger this button
	shortcutKey2	a second optional key that can be pressed to trigger this button

int AlertWindow::getNumButtons ( ) const

Returns the number of buttons that the window currently has.

void AlertWindow::addTextEditor	(	const String &	name,
		const String &	initialContents,
		const String &	onScreenLabel = `String::empty`,
		bool	isPasswordBox = `false`
	)

Adds a textbox to the window for entering strings.

Parameters:

	name	an internal name for the text-box. This is the name to pass to the getTextEditorContents() method to find out what the user typed-in.
	initialContents	a string to show in the text box when it's first shown
	onScreenLabel	if this is non-empty, it will be displayed next to the text-box to label it.
	isPasswordBox	if true, the text editor will display asterisks instead of the actual text

See also:: getTextEditorContents

const String AlertWindow::getTextEditorContents ( const String & nameOfTextEditor ) const

Returns the contents of a named textbox.

After showing an AlertWindow that contains a text editor, this can be used to find out what the user has typed into it.

Parameters:

nameOfTextEditor

the name of the text box that you're interested in

See also:: addTextEditor

void AlertWindow::addComboBox	(	const String &	name,
		const StringArray &	items,
		const String &	onScreenLabel = `String::empty`
	)

Adds a drop-down list of choices to the box.

After the box has been shown, the getComboBoxComponent() method can be used to find out which item the user picked.

Parameters:

	name	the label to use for the drop-down list
	items	the list of items to show in it
	onScreenLabel	if this is non-empty, it will be displayed next to the combo-box to label it.

See also:: getComboBoxComponent

ComboBox* AlertWindow::getComboBoxComponent ( const String & nameOfList ) const

Returns a drop-down list that was added to the AlertWindow.

Parameters:

nameOfList

the name that was passed into the addComboBox() method when creating the drop-down

Returns:: the ComboBox component, or 0 if none was found for the given name.

void AlertWindow::addTextBlock ( const String & text )

Adds a block of text.

This is handy for adding a multi-line note next to a textbox or combo-box, to provide more details about what's going on.

void AlertWindow::addProgressBarComponent ( double & progressValue )

Adds a progress-bar to the window.

Parameters:

progressValue

a variable that will be repeatedly checked while the dialog box is visible, to see how far the process has got. The value should be in the range 0 to 1.0

void AlertWindow::addCustomComponent ( Component * component )

Adds a user-defined component to the dialog box.

Parameters:

component

the component to add - its size should be set up correctly before it is passed in. The caller is responsible for deleting the component later on - the AlertWindow won't delete it.

int AlertWindow::getNumCustomComponents ( ) const

Returns the number of custom components in the dialog box.

See also:: getCustomComponent, addCustomComponent

Component* AlertWindow::getCustomComponent ( int index ) const

Returns one of the custom components in the dialog box.

Parameters:

index

a value 0 to (getNumCustomComponents() - 1). Out-of-range indexes will return 0

See also:: getNumCustomComponents, addCustomComponent

Component* AlertWindow::removeCustomComponent ( int index )

Removes one of the custom components in the dialog box.

Note that this won't delete it, it just removes the component from the window

Parameters:

index

a value 0 to (getNumCustomComponents() - 1). Out-of-range indexes will return 0

Returns:: the component that was removed (or zero)

See also:: getNumCustomComponents, addCustomComponent

bool AlertWindow::containsAnyExtraComponents ( ) const

Returns true if the window contains any components other than just buttons.

static void JUCE_CALLTYPE AlertWindow::showMessageBox	(	AlertIconType	iconType,
		const String &	title,
		const String &	message,
		const String &	buttonText = `String::empty`,
		Component *	associatedComponent = `0`
	)			`[static]`

Shows a dialog box that just has a message and a single button to get rid of it.

The box is shown modally, and the method returns after the user has clicked the button (or pressed the escape or return keys).

Parameters:

	iconType	the type of icon to show
	title	the headline to show at the top of the box
	message	a longer, more descriptive message to show underneath the headline
	buttonText	the text to show in the button - if this string is empty, the default string "ok" (or a localised version) will be used.
	associatedComponent	if this is non-zero, it specifies the component that the alert window should be associated with. Depending on the look and feel, this might be used for positioning of the alert window.

static bool JUCE_CALLTYPE AlertWindow::showOkCancelBox	(	AlertIconType	iconType,
		const String &	title,
		const String &	message,
		const String &	button1Text = `String::empty`,
		const String &	button2Text = `String::empty`,
		Component *	associatedComponent = `0`
	)			`[static]`

Shows a dialog box with two buttons.

Ideal for ok/cancel or yes/no choices. The return key can also be used to trigger the first button, and the escape key for the second button.

Parameters:

	iconType	the type of icon to show
	title	the headline to show at the top of the box
	message	a longer, more descriptive message to show underneath the headline
	button1Text	the text to show in the first button - if this string is empty, the default string "ok" (or a localised version of it) will be used.
	button2Text	the text to show in the second button - if this string is empty, the default string "cancel" (or a localised version of it) will be used.
	associatedComponent	if this is non-zero, it specifies the component that the alert window should be associated with. Depending on the look and feel, this might be used for positioning of the alert window.

Returns:: true if button 1 was clicked, false if it was button 2

static int JUCE_CALLTYPE AlertWindow::showYesNoCancelBox	(	AlertIconType	iconType,
		const String &	title,
		const String &	message,
		const String &	button1Text = `String::empty`,
		const String &	button2Text = `String::empty`,
		const String &	button3Text = `String::empty`,
		Component *	associatedComponent = `0`
	)			`[static]`

Shows a dialog box with three buttons.

Ideal for yes/no/cancel boxes.

The escape key can be used to trigger the third button.

Parameters:

	iconType	the type of icon to show
	title	the headline to show at the top of the box
	message	a longer, more descriptive message to show underneath the headline
	button1Text	the text to show in the first button - if an empty string, then "yes" will be used (or a localised version of it)
	button2Text	the text to show in the first button - if an empty string, then "no" will be used (or a localised version of it)
	button3Text	the text to show in the first button - if an empty string, then "cancel" will be used (or a localised version of it)
	associatedComponent	if this is non-zero, it specifies the component that the alert window should be associated with. Depending on the look and feel, this might be used for positioning of the alert window.

Returns:

one of the following values:

0 if the third button was pressed (normally used for 'cancel')
1 if the first button was pressed (normally used for 'yes')
2 if the middle button was pressed (normally used for 'no')

static bool JUCE_CALLTYPE AlertWindow::showNativeDialogBox	(	const String &	title,
		const String &	bodyText,
		bool	isOkCancel
	)			`[static]`

Shows an operating-system native dialog box.

Parameters:

	title	the title to use at the top
	bodyText	the longer message to show
	isOkCancel	if true, this will show an ok/cancel box, if false, it'll show a box with just an ok button

Returns:: true if the ok button was pressed, false if they pressed cancel.

void AlertWindow::paint ( Graphics & g ) [protected, virtual]

For internal use only.

Reimplemented from Component.

void AlertWindow::mouseDown ( const MouseEvent & e ) [protected, virtual]

For internal use only.

Reimplemented from Component.

void AlertWindow::mouseDrag ( const MouseEvent & e ) [protected, virtual]

For internal use only.

Reimplemented from Component.

bool AlertWindow::keyPressed ( const KeyPress & key ) [protected, virtual]

For internal use only.

Reimplemented from Component.

void AlertWindow::buttonClicked ( Button * button ) [protected, virtual]

For internal use only.

Implements ButtonListener.

void AlertWindow::lookAndFeelChanged ( ) [protected, virtual]

For internal use only.

Reimplemented from Component.

void AlertWindow::userTriedToCloseWindow ( ) [protected, virtual]

For internal use only.

Reimplemented from Component.

int AlertWindow::getDesktopWindowStyleFlags ( ) const [protected, virtual]

For internal use only.

Reimplemented from TopLevelWindow.

The documentation for this class was generated from the following file:

juce_AlertWindow.h

AlertWindow Class Reference

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation