With this template you can add a new Menu component to your project. Menu is a complex component intended to manage and automatically arrange menu items. At the runtime the user can interact with the menu, scroll and activate the items. Please note that the items are available as separate component templates. When using the Menu component template in your project you will probably also add at least one Menu Item component. The following table provides an overview of the available Menu Item component templates:

Icon	Template name	Description
	Menu Item	Menu item is a simple widget the user can press in order to perform an action. Once you have added the menu item component to a unit, you can embed instances of this item wherever you edit a menu in your GUI project.
	Toggle Item	Toggle item is a simple menu item widget the user can press in order to toggle a value. It is also suitable to serve as a 'check box item'. Once you have added the menu item component to a unit, you can embed instances of this item wherever you edit a menu in your GUI project.
	Radio Item	Radio item is a simple menu item widget the user can press in order select an option. Once you have added the menu item component to a unit, you can embed instances of this item wherever you edit a menu in your GUI project.
	Slider Item	Slider item is a simple menu item widget the user can interact with in order to change a number value by touching and dragging a knob. Once you have added the menu item component to a unit, you can embed instances of this item wherever you edit a menu in your GUI project.
	Open Menu Item	Open menu item is a simple menu item widget the user can press in order to enter a sub menu. Once you have added the menu item component to a unit, you can embed instances of this item wherever you edit a menu in your GUI project.
	Exit Menu Item	Exit menu item is a simple menu item widget the user can press in order to leave the actual menu and return to the superior menu. Once you have added the menu item component to a unit, you can embed instances of this item wherever you edit a menu in your GUI project.
	Menu Separator Item	Menu separator item is a very simple widget intended to separate menu items within a menu. As such the menu separator item doesn't react to user inputs. Once you have added the menu separator item component to a unit, you can embed instances of this item wherever you edit a menu in your GUI project.

Components created with this template are intended to be adapted to your particular design expectations. After adding the new Menu 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 Menu wherever you need in your GUI project. Because it serves as template, it is intentionally kept very simple. Nevertheless, Menus 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 Menu created by using the here described component template and diverse menu item templates:

The approach with component templates has two functions. Primarily the templates should simplify the development of new components. Instead of creating the Menu from scratch you can use the available template. The second function is more educative. The template implements fully working Menu 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 Menu 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 Menu component.

To create a new Menu 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 Menu component from a template:

The new created Menu 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 Menu component, you can use it to assemble one or more application specific menus. From technical point of view, you fill the Menu component with all desired menu items. At the runtime, when the Menu component is presented to the user, the component takes care of correct displaying the items, handling user inputs and scrolling large menus containing many items.

Except very simple use cases, GUI applications implement more than one menu. Complex applications integrate an entire tree-like menu system composed of a top-level and several nested sub-level menus. When interacting with such menu system the user navigates between superior and sub menus forth and back conveniently. In more sophisticated use cases an application can even implement multiple separate context specific menu systems. In other words, an application may contain multiple menus, each containing a completely different set of menu items.

For reasons of efficiency and reusability it is less recommended to create the individual menus each as a separate copy of the Menu component template. Instead, consider the once created Menu component as a generic, common menu implementation. The individual menus (e.g. MainMenu, SettingsMenu, NetworkMenu, VideoMenu, EngineMenu, etc.) are just components descending from the generic Menu component. In this manner, the implementation of the Menu component is not duplicated. Nevertheless, the descending menu components inherit the common implementation and all menus appear and behave equally. See also Subclassing components.

The following are the typical steps to create a new component by deriving it from the already existing, generic Menu component. Please note, since components are classes they can exist within units only:

You can repeat the above steps for all individual menus you plan to implement in your application. Each derived menu component appears in the unit as a separate brick. From technical point of view it is a separate class descending from the common Menu component class.

The following are the typical steps to fill a menu with menu items. Technically seen, you embed an instance of the item class in-place within a superior menu component. At the runtime, the menu component takes care of the correct initialization, arrangement and the displaying of all embedded item components:

The position of the items doesn't matter. The Menu component will automatically arrange the items within its area and if necessary enlarge or reduce their size. Moreover, the size of the menu itself is adapted to the number and to the size of the enclosed items. This layout algorithm is part of the Menu component template. Consequently, when you move an item within the menu, it does not have any effect on its final position.

However, the order in which the items will be displayed at the runtime does correspond to the order in which the item objects are stored within the menu component. This is the order in which the items have been originally added. Consequently, the first added item appears at the top of the menu while the last added item is arranged at the end of the menu. See also the column Order in the members area of the Inspector window:

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

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 Menu appears as a white rectangle surrounded by a border and displaying a caption text. Additionally all items existing within the menu are automatically arranged from top to bottom. Our intention is to keep the component templates as minimalistic as possible so they don't distract you with less important design details:

When using the above described PresentDialog() method, the menu 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 Menu with additional animations (e.g. sliding). For more details see the section Customize provided Dialog transition animations.

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

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 Menu 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 Menu appears displaying a caption text, a white background surrounded by a border and an area where the menu items are automatically arranged. Our intention is to keep the component templates as minimalistic as possible so they don't distract you with less important design details. The Menu can react to touch and keyboard inputs for navigation and automatically scrolls large menus containing many items. The appearance of the menu border and caption text reflects the actual state of the menu. Especially when the menu is focused (able to receive keyboard events), the border appears thick.

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

Icon	Member	Description
	Caption	The property Caption stores the text to display within the menu 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 menu size.
	KeyHandler	This key handler reacts to key press events. When the user presses cursor keys (Up, Down, Left, Right), the handler is activated and the method onPressKey is called. This enables keyboard navigation between menu items.
	onPressKey	This internal slot method is called when the KeyHandler has been activated (when the user has pressed a cursor key). Thereupon, the method navigates to the neighbor menu item in the corresponding direction and scrolls the menu if necessary.
	autoResize	This internal slot method is called automatically when the number or size of menu items changes. The method calculates the optimal size for the menu to fit all items and adjusts the menu's Bounds property accordingly.
	Background	This Filled Rectangle view displays in the template the background of the menu. The background is white per default.
	Border	This Border view displays in the template the border of the menu. Depending on the menu'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 menu. The text content is determined by the property Caption. Depending on the menu's actual state, the text color changes.
	Outline	This Outline view groups all menu items together and manages their automatic arrangement. The outline handles scrolling for large menus and determines the formation (vertical/horizontal) of the items. Per default, items are arranged vertically from top to bottom.
	SlideTouchHandler	This Slide Touch Handler enables the user to scroll the menu items by touching and dragging with a finger or mouse. The handler provides inertia and friction for smooth scrolling behavior.
	UpdateViewState	This method is invoked automatically after the state of the component has been changed. In case of the Menu, the method updates the views Background, Border and CaptionText so they reflect the menu's current state.
	UpdateLayout	This method is invoked automatically when the layout of the menu changes (e.g. when items are added, removed, or the menu is resized). The method triggers the autoResize slot to recalculate the menu size.
	enabled	This variable stores the current state of the menu. It is true if the menu is allowed to handle user inputs (the component is enabled). See also Control the Enabled state of nested components. If the menu is actually disabled, the variable is consequently false.
	modal	This variable stores the current state of the menu. It is true if the menu is actually presented as modal dialog (the menu grabs all user inputs and overlays all other GUI components).
	focused	This variable stores the current state of the menu. It is true if the menu lies on the focus path and can receive keyboard events. The user can thereupon control the menu via keyboard.

During its lifetime, the Menu 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 Menu 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 menu lies on the focus path. Being in this state, the menu 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 Menu 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 Menu or even remove the existing functionality if it is not needed in your case.

Originally, if not yet modified, the Menu appears displaying a caption text, a white background surrounded by a border and an area where the menu items are automatically arranged. 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 menu 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 Menu template contains per default the views Background, Border and CaptionText. If desired, you can modify the views. For example, you can display them with other colors depending on the actual state of the menu. For this purpose you change the implementation of the above explained method UpdateViewState responsible for tracking the state alternations within the Menu.

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 menu the views Background, Border and CaptionText 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 menu is focused:

If not needed, you can delete the per default existing views Background, Border or CaptionText. 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 Menu. For example, you can add an Image view to display an icon or logo within the menu header. Or you add additional Text views to display supplementary information. 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 menu. Following steps explain the workflow:

Also possible, you can replace the existing views by other views. For example, in the original version, the Menu displays the caption 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 Menu is determined by the thick blue border surrounding the Canvas area. However, the Menu component is designed to automatically adjust its size according to the number and size of the enclosed menu items. This auto-sizing behavior is implemented in the autoResize slot method. When you start the Prototyper, you will notice that the menu adapts its size to fit all items.

If you want to manually configure the Canvas area size (for example, to better visualize the menu 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 Menu template (Background, Border, Outline and SlideTouchHandler) are automatically adjusted to fill the area of the menu. The CaptionText view is aligned at the top. All other views you have eventually added later to the Menu 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 Menu. 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 menu resizes, you configure its Layout property accordingly. For example, to keep an icon in the top-right corner:

When creating your own Menu component you should ensure that instances of the menu can be configured to control all the features implemented in it. For example, if you have enhanced the menu to display some icon, you should allow this icon to be specified individually for each menu instance. In this way several menu instances can exist at the same time, each displaying another icon.

To control the features in your menu 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 menu. When the value of the property changes, the menu can react to it and update its appearance accordingly. The properties reflect thus the settings within your menu. Together they form the interface of the component.

Usually, each particular setting within a component is represented by the corresponding property. Thus, a menu where icon and background color can be configured will require two properties: one for the icon and one for the color. In its original version, the Menu contains already one property Caption which stores the text to display in the menu header. 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 Menu component, you can evaluate and modify the properties similarly to how you access variables. Especially, when the menu instance is selected, you see in Inspector window the property and can change it there. The modification is immediately visible in the Composer window.

If desired, the properties can also be modified at the runtime of your application. For example, the menu caption can be adapted to reflect the current context. For this purpose you access and modify the affected property directly within Chora code:

The Menu 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. These are per default the cursor keys (Up, Down, Left, Right):

The method takes care of keyboard navigation between menu items. When the user presses a cursor key, the method determines the navigation direction and looks for the next menu item in that direction. If found, the focus is passed to the found item. In case of large menus, the method also scrolls to the focused item with an animation effect:

Usually you will not need to edit the implementation of the method. It corresponds already to whatever typical menus do. Nevertheless, you are free to change this default functionality if you want some particular behavior to be implemented in your menu. For example, you can modify the scroll animation duration or disable the animation completely.

Per default the key handler is configured to accept the cursor keys (Up, Down, Left, Right). If necessary you can change this behavior and adapt the menu 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 menu to also accept navigation with W, A, S, D keys, you can add an additional key handler. 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 Menu is an interactive component that supports touch-based and mouse-based scrolling for large menus. For this purpose the template contains the Slide Touch Handler object named SlideTouchHandler. This handler covers the entire area where menu items are displayed and enables the user to scroll by touching and dragging:

The handler provides following scrolling features:

Usually you will not need to modify the handler's configuration. However, you can adjust the scrolling behavior by changing following properties:

Property	Description
SlideHorz	Enables/disables horizontal scrolling. Set to false per default for vertical menus.
SlideVert	Enables/disables vertical scrolling. Set to true per default for vertical menus.
Friction	Controls the deceleration rate after releasing the finger/mouse. Higher values (e.g. 0.05) cause faster deceleration. Lower values (e.g. 0.005) cause longer inertia. Default value is 0.01.

If your device does not support touch or mouse input, you can remove the SlideTouchHandler object. In such case, keyboard navigation (via the KeyHandler) will be the only way to navigate through menu items.

The Menu component automatically arranges all enclosed menu items using the Outline view. This outline view groups the items together and manages their layout according to the configured Formation property. Per default, items are arranged vertically from top to bottom.

The automatic arrangement occurs whenever:

The arrangement algorithm is triggered by the UpdateLayout method, which then invokes the autoResize slot method. This method calculates the optimal size for the menu based on:

If the calculated size exceeds the maximum allowed size, the menu becomes scrollable. The SlideTouchHandler enables smooth touch-based scrolling with inertia and friction effects.

Per default, items are arranged vertically (top to bottom). If you want to arrange items horizontally, you need to:

The autoResize method is responsible for calculating the optimal size of the menu based on its content. When you modify the menu by adding additional views (like icons, decorations, or other elements), you may need to adapt the implementation of this method to correctly account for the additional space required.

In its original implementation, the method calculates the menu size based on following main factors:

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

The critical calculation is where the method ensures the menu is wide enough for the caption text plus 20 pixels margin:

Let's assume you have added an Image view named MenuIcon to display an icon next to the caption text. The icon is positioned to the right of the caption and has a width of 36 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:

In the last case, assigning an icon with different size should trigger the menu to update its layout. For this purpose you should invoke InvalidateViewState every time a new icon is assigned to the menu. Assuming you have implemented a property Icon for such purpose, then you would adapt the onset method of this property.

If you have added multiple decorative elements around the caption (for example, an icon on the left and a status indicator on the right), you need to account for all of them:

If you want to change the default 20 pixels margin around the caption text (for example, to use 30 pixels left margin and 15 pixels right margin), modify the calculation as shown below. Don't forget to reposition the caption text view to lie 30 pixel away from the left edge of the menu:

Similarly, if you have added views that affect the minimum height of the menu (like a subtitle text below the caption), you need to modify the height calculation:

The autoResize method calculates the minimum size. The actual menu size at runtime will be at least this size, but can be larger if needed to accommodate all items. The method also limits the maximum size to 60% of the screen size per default. If you need different maximum size constraints, modify the following section in the method:

In the section Adapt the appearance of the component you learned how state alternations within the Menu are processed and how views existing in the component are updated in order to reflect the actual state. Accordingly, when the menu becomes focused (able to receive keyboard events), the menu does appear highlighted. When the menu loses focus again, the menu 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 Menu to update its appearance with animations. For example, instead of instantly switching between the focused and not-focused appearance, such menu 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 menu. Following are the steps how to do this: