With this template you can add a new Alert component to your project. Alert is a complex component intended to display a message text with additional push buttons. At the runtime the application presents the Alert to the user in order to inform him/her about an event or to ask the user for a confirmation. When one of the push buttons found in the Alert is activated, the component sends signals to associated slot methods where your particular implementation is executed. If the Alert is focused the component can also be controlled by pressing keys on the keyboard or by using hardware buttons.

Components created with this template are intended to be adapted to your particular design expectations. After adding the new Alert you should edit the component, change its appearance and if desired also its behavior. Once you have adapted the component, you can embed instances of this Alert wherever you need in your GUI project. Because it serves as template, it is intentionally kept very simple. Nevertheless, Alerts created by the template are working widgets. If desired, they can already be used as they are. The following figure demonstrates the default appearance of the Alert created by using the here described component template:

The approach with component templates has two functions. Primarily the templates should simplify the development of new components. Instead of creating the Alert from scratch you can use the available template. The second function is more educative. The template implements fully working Alert component you can investigate and learn about the corresponding programming aspects. The template is well documented. It contains annotations and inline comments with instructions helping you to understand how the component works and how it can be adapted to your particular needs.

This chapter provides an overview how the Alert component template is used within your own application and how you adapt this component according to your particular needs. You will find here also further details concerning the internal implementation of the Alert component.

To create a new Alert component from a template you simply Drag & Drop it between the Templates window and the Composer with an opened unit. This is important in that by using the component templates you add in fact a new class to your project. Classes, in turn, can exist within units only. The following are the typical steps to create a new Alert component from a template:

The new created Alert component appears accompanied by annotation providing helpful tips how to proceed. If undesired, you can select and delete the annotation.

Once you have created the Alert component, you can use it in your application to display messages to the user or to ask the user for a confirmation. For example, when the user intents to delete a file, an Alert may be displayed asking the user whether or not to proceed.

Component templates are intended to create widgets which can be modified and adapted to your particular design expectations. In the following sections you will learn how to do this. Originally, if not yet modified, the Alert appears as a white rectangle surrounded by a border and displaying a caption and message text. Additional two push buttons are available. Our intention is to keep the component templates as minimalistic as possible so they don't distract you with less important design details:

The Alert component exposes several properties permitting instances of the Alert to be configured conveniently. The Alert component descends from the Mosaic class Core::Group and as consequence, it inherits a lot of properties from this base class. Particular to the Alert component are only few following properties:

Property	Description
Caption	The property Caption stores the text to display within the alert header.
Message	The property Message stores the text to display within the message area of the alert.
Button1Label	The property Button1Label stores the text to display in the first push button.
Button2Label	The property Button2Label stores the text to display in the second push button.
OnButton1	The property OnButton1 can store a slot method to signal when the user activates the first push button.
OnButton2	The property OnButton2 can store a slot method to signal when the user activates the second push button.

The usual approach is to present alerts programmatically as so-called dialogs. The following code demonstrates how to achieve this. It creates an instance of the previously created Alert component (e.g. Application::Alert) and presents it as dialog using the method PresentDialog():

When using the above described PresentDialog() method, the alert is arranged in the center of the superior GUI component. In case of rootthis it is the center of the entire screen. If desired, you can provide in the second parameter of the PresentDialog() method a transition object configured to apply other layout rules to the presented dialog. The transition objects also permit you to display the Alert with additional animations (e.g. sliding). For more details see the section Customize provided Dialog transition animations.

The following steps explain how to position an alert, for example, aligned to the right edge of its owner component, vertically centered, with 20 pixels distance from this edge:

In its default version, the Alert component includes two Push Buttons. When the user activates one of the buttons, a signal is sent to the associated slot method. The slot method is connected to the component by simply assigning it to the for this purpose available properties OnButton1 and OnButton2. You can initialize the properties with already existing slot methods or you add a new one and implement it as desired. The following steps describe how to do this:

Component templates are intended to create widgets which can be adapted and enhanced to your particular design expectations. For this purpose, once you have added a new Alert component to your project, you can open the component class for editing. Thereupon the implementation of the component appears in a new Composer page:

Originally, if not yet modified, the Alert appears displaying a caption text, a message text, a white background surrounded by a border and two push buttons. Our intention is to keep the component templates as minimalistic as possible so they don't distract you with less important design details. The Alert can react to touch and keyboard inputs. The appearance of the alert border and text reflects the actual state of the alert. Especially when the alert is focused (able to receive keyboard events), the border appears thick.

This default functionality is implemented by following members belonging to the Alert. These members are explicitly intended to be modified. Understanding this internal structure is thus the first step before you start to adapt the Alert to your particular needs:

Icon	Member	Description
	Caption	The property Caption stores the text to display within the alert header.
	OnSetCaption	The onset method belongs to the property Caption. Each time the value of the property is changed, the code implemented in the method is executed to update the caption text view and recalculate the alert size.
	Message	The property Message stores the text to display within the message area of the alert.
	OnSetMessage	The onset method belongs to the property Message. Each time the value of the property is changed, the code implemented in the method is executed to update the message text view and recalculate the alert size.
	Button1Label	The property Button1Label stores the text to display in the first push button.
	OnSetButton1Label	The onset method belongs to the property Button1Label. Each time the value of the property is changed, the code implemented in the method is executed to update the button's label and recalculate the alert size.
	Button2Label	The property Button2Label stores the text to display in the second push button.
	OnSetButton2Label	The onset method belongs to the property Button2Label. Each time the value of the property is changed, the code implemented in the method is executed to update the button's label and recalculate the alert size.
	OnButton1	The property OnButton1 can store a slot method to signal when the user activates the first push button.
	OnSetOnButton1	The onset method belongs to the property OnButton1. Each time the value of the property is changed, the code implemented in the method is executed to connect the button with the specified slot method.
	OnButton2	The property OnButton2 can store a slot method to signal when the user activates the second push button.
	OnSetOnButton2	The onset method belongs to the property OnButton2. Each time the value of the property is changed, the code implemented in the method is executed to connect the button with the specified slot method.
	KeyHandler	This key handler reacts to key press events. When the user presses the Tab key, the handler is activated and the method onPressKey is called. This enables keyboard navigation between the push buttons.
	onPressKey	This internal slot method is called when the KeyHandler has been activated (when the user has pressed the Tab key). Thereupon, the method navigates to the next push button in the alert.
	autoResize	This internal slot method is called automatically when the content of the alert changes (caption, message, button labels). The method calculates the optimal size for the alert to fit all content and adjusts the alert's Bounds property accordingly.
	Background	This Filled Rectangle view displays in the template the background of the alert. The background is white per default.
	Border	This Border view displays in the template the border of the alert. Depending on the alert's actual state variables enabled, focused and modal the border's color and thickness changes.
	CaptionText	This Text view displays the caption text at the top of the alert. The text content is determined by the property Caption. Depending on the alert's actual state, the text color changes.
	MessageText	This Text view displays the message text in the center of the alert. The text content is determined by the property Message. The text is wrapped automatically within the available area. Depending on the alert's actual state, the text color changes.
	PushButton1	This Push Button widget represents the first button in the alert. The button's label is determined by the property Button1Label and when activated, it signals to the slot method specified in the property OnButton1.
	PushButton2	This Push Button widget represents the second button in the alert. The button's label is determined by the property Button2Label and when activated, it signals to the slot method specified in the property OnButton2.
	UpdateViewState	This method is invoked automatically after the state of the component has been changed. In case of the Alert, the method updates the views Background, Border, CaptionText and MessageText so they reflect the alert's current state.
	UpdateLayout	This method is invoked automatically when the layout of the alert changes (e.g. when the alert is resized or content is modified). The method triggers the autoResize slot to recalculate the alert size.
	enabled	This variable stores the current state of the alert. It is true if the alert is allowed to handle user inputs (the component is enabled). See also Control the Enabled state of nested components. If the alert is actually disabled, the variable is consequently false.
	modal	This variable stores the current state of the alert. It is true if the alert is actually presented as modal dialog (the alert grabs all user inputs and overlays all other GUI components).
	focused	This variable stores the current state of the alert. It is true if the alert lies on the focus path and can receive keyboard events. The user can thereupon control the alert via keyboard.

During its lifetime, the Alert will assume different states as direct effect of user interactions and as result of other superior state alternations within the GUI application. To track its current state the Alert manages the above mentioned state variables: enabled, modal and focused. The variables are evaluated and updated within the implementation of the method UpdateViewState. This method evaluates the common component states (Enabled, Modal and Focused). At the end of the method the estimated states are stored in the state variables:

For example, the local variable isFocused will become true if the alert lies on the focus path. Being in this state, the alert should assume the appearance indicating that the user can actively interact with it via keyboard.

When common component states (Enabled, Modal or Focused) have changed, the method UpdateViewState is invoked automatically. You don't need to worry about it. Any other state alternations need to explicitly request an invocation of the UpdateViewState method. When you modify the Alert to handle other user inputs or perform other animations always ensure that each state alternation (each event) does request an invocation of UpdateViewState. In your implementation you use for this purpose the method InvalidateViewState.

Depending on your design expectations the default state management may require adaptations. Generally, you are free to modify the method UpdateViewState, add further state variables to your Alert or even remove the existing functionality if it is not needed in your case.

Originally, if not yet modified, the Alert appears displaying a caption text, a message text, a white background surrounded by a border and two push buttons. Our intention is to keep the component templates as minimalistic as possible so they don't distract you with less important design details. It's up to you to adapt the alert to have the expected appearance. The available possibilities are explained in the following sections. Please note, that you can combine the different approaches according to your application case:

The Alert template contains per default the views Background, Border, CaptionText and MessageText. If desired, you can modify the views. For example, you can display them with other colors depending on the actual state of the alert. For this purpose you change the implementation of the above explained method UpdateViewState responsible for tracking the state alternations within the Alert.

When you open the method UpdateViewState you will see that it does not only update the state variables but also updates the views existing within the component. Accordingly, depending on the actual state of the alert the views Background, Border, CaptionText and MessageText are displayed with other colors and the border with other thickness. By simply modifying this implementation you change the appearance. For example, you change the border color from black to blue when the alert is focused:

If not needed, you can delete the per default existing views Background, Border, CaptionText or MessageText. Doing this, please don't forget to also remove all references to the deleted views from the implementation of the UpdateViewState and autoResize methods. Otherwise you will get error messages next time the Composer contents is reloaded. To avoid this error message we recommend to perform the steps in following order:

You can add further views to your Alert. For example, you can add an Image view to display an icon indicating the type of alert (warning, error, info). Or you add additional decorative elements. The appearance of the views (e.g. colors) can be fixed, predetermined at the design time. Or it can change according to the actual state of the alert. Following steps explain the workflow:

Also possible, you can replace the existing views by other views. For example, in the original version, the Alert displays the message as an ordinary text. To make the component more sophisticated, you could replace the here used Text view by e.g. Attributed Text view to support rich formatted text. For this purpose:

The initial size of the Alert is determined by the thick blue border surrounding the Canvas area. However, the Alert component is designed to automatically adjust its size according to the displayed message, caption, and button labels. This auto-sizing behavior is implemented in the autoResize slot method. When you start the Prototyper, you will notice that the alert adapts its size to fit all content.

If you want to manually configure the Canvas area size (for example, to better visualize the alert during editing), you can adjust it by clicking and dragging the edges of the surrounding border (see also Resize the Canvas area). Keep in mind that this manual size adjustment is primarily for design-time convenience and won't affect the runtime auto-sizing behavior.

The views existing per default in the Alert template (Background and Border) are automatically adjusted to fill the area of the alert. The CaptionText view is aligned at the top. The MessageText view and push buttons (PushButton1 and PushButton2) are arranged programmatically in the autoResize method. All other views you have eventually added later to the Alert are not adjusted automatically.

To control the adjustment you have to explicitly configure for each view its Layout property. (see also Configure component layout). Let's assume, in order to display an icon you have added an Image view to the Alert. Then you have arranged the view within the Canvas area according to your design expectation. If you want now that the view remains aligned at a specific corner when the alert resizes, you configure its Layout property accordingly. For example, to keep an icon in the top-right corner next to the caption:

When creating your own Alert component you should ensure that instances of the alert can be configured to control all the features implemented in it. For example, if you have enhanced the alert to display different icons depending on the alert type (warning, error, info), you should allow this icon to be specified individually for each alert instance. In this way several alert instances can exist at the same time, each displaying a different icon.

To control the features in your alert you use properties. A property can be understood as variable where the corresponding setting is stored, e.g. the icon bitmap to display in the alert. When the value of the property changes, the alert can react to it and update its appearance accordingly. The properties reflect thus the settings within your alert. Together they form the interface of the component.

Usually, each particular setting within a component is represented by the corresponding property. Thus, an alert where icon and message can be configured will require two properties: one for the icon and one for the message. In its original version, the Alert contains already several properties which control the caption, message, button labels, and button slot methods. In order to enhance this interface by your own properties, following steps are necessary:

That is all. Now when you deal with instances of the Alert component, you can evaluate and modify the properties similarly to how you access variables. For example, the alert message and icon can be adapted to reflect the specific situation. For this purpose you access and modify the affected property directly within Chora code:

The Alert template contains per default two push buttons. Depending on your application needs, you can add further buttons or remove the existing ones. Following sections explain both scenarios:

If you need only a single button (for example, a simple "OK" acknowledgment alert), you can remove the second button:

The Alert is an interactive component. It can be controlled via keyboard or hardware buttons. For this purpose the template contains the Key Press Handler object named KeyHandler. To this handler is associated the slot method named onPressKey. The method is thus invoked when the user presses a key matching the filter condition specified in the handler object. This is per default the Tab key:

The method takes care of keyboard navigation between the push buttons. When the user presses the Tab key, the method looks for the next button and passes the focus to it:

Usually you will not need to edit the implementation of the method. It corresponds already to whatever typical alerts do. Nevertheless, you are free to change this default functionality if you want some particular behavior to be implemented in your alert.

Per default the key handler is configured to accept the Tab key. If necessary you can change this behavior and adapt the alert to react to other keys or key groups. The key handler provides for this purpose the configuration property Filter. For example, if you want the alert to accept navigation with cursor keys (Left and Right), you can modify the key handler's filter. For more details, see Configure the filter condition.

If your device does not contain any keyboard nor hardware buttons, the per default existing key handler and its associated slot method are unnecessary ballast. You can remove them in such case. We recommend to do this in following order to avoid eventual error messages because of broken references between still existing and the already removed members:

The Alert component automatically adjusts its size to fit the displayed content: caption, message, and button labels. This auto-sizing behavior is implemented in the autoResize slot method. The method is triggered automatically whenever the content changes (via the UpdateLayout method).

The size calculation algorithm considers following factors:

The calculated size ensures that:

When you modify the alert by adding additional views (like icons, decorations, or other elements), you may need to adapt the implementation of the autoResize method to correctly account for the additional space required.

Here is the relevant part of the default implementation that determines the width:

Let's assume you have added an Image view named AlertIcon to display an icon next to the message. The icon is positioned to the left of the message and has a width of 48 pixels. You also want 10 pixels spacing between the icon and the text. In this case, you need to modify the calculation in the autoResize method:

Or more elegantly, you can calculate the icon space dynamically:

If you have added views that affect the vertical spacing (like a subtitle below the caption), you need to modify the height calculation:

In the section Adapt the appearance of the component you learned how state alternations within the Alert are processed and how views existing in the component are updated in order to reflect the actual state. Accordingly, when the alert becomes focused (able to receive keyboard events), the alert does appear highlighted. When the alert loses focus again, the alert restores its normal appearance. The default implementation performs such appearance updates instantly, just in the moment when the respective state change took place.

If desired, you can modify the Alert to update its appearance with animations. For example, instead of instantly switching between the focused and not-focused appearance, such alert can fade-in/out the views, modulate their colors or sizes. For this purpose you use the Animation Effects. With an Animation Effect you can animate a property of a view existing in the alert. Following are the steps how to do this: