Amazon Lumberyard UI Extensions Guide Version 1.28 Amazon Lumberyard UI Extensions Guide

Amazon's trademarks and trade dress may not be used in connection with any product or service that is not Amazon's, in any manner that is likely to cause confusion among customers, or in any manner that disparages or discredits Amazon. All other trademarks not owned by Amazon are the property of their respective owners, who may or may not be aﬃliated with, connected to, or sponsored by Amazon. Amazon Lumberyard UI Extensions Guide

Table of Contents

...... vi Introduction to Lumberyard UI development ...... 1 Control gallery tool ...... 2 How to use the Amazon Qt control gallery ...... 2 Component development guidelines ...... 4 Style sheets and StyleManager ...... 4 Get started with UI component development ...... 4 UI development best practices ...... 5 Frequently asked questions ...... 5 UI component library ...... 7 Breadcrumbs ...... 7 Anatomy of the breadcrumbs widget ...... 10 Basic breadcrumb ...... 10 Breadcrumb with path navigation and browse ...... 11 C++ API reference ...... 12 Browse edit ...... 12 Anatomy of the browse edit widget ...... 12 Basic browse edit ...... 13 Browse edit with custom icon and placeholder text ...... 14 Browse edit with tooltips and validator ...... 15 Disabled browse edit ...... 15 C++ API reference ...... 16 Related links ...... 16 Button styles ...... 16 Usage guidelines ...... 16 Applying styles ...... 17 C++ API reference ...... 18 Card ...... 18 Anatomy of the card widget ...... 19 Basic card ...... 20 Card with context menu and help icon ...... 21 Card with secondary content ...... 21 Card with modiﬁed content ...... 22 Disabled card ...... 22 Mock disabled card ...... 22 Card with warning state ...... 23 Card with notiﬁcation ...... 23 C++ API reference ...... 24 Related links ...... 24 Checkbox ...... 24 Usage guidelines ...... 25 Basic checkbox ...... 26 C++ API reference ...... 26 Related links ...... 26 Combobox ...... 27 Usage guidelines ...... 27 Basic combobox ...... 28 Combobox with validator ...... 29 C++ API reference ...... 29 Context menu ...... 29 Usage guidelines ...... 30 Basic context menu ...... 31 C++ API reference ...... 32 Filtered search ...... 32

Version 1.28 iii Amazon Lumberyard UI Extensions Guide

Anatomy of the filtered search widget ...... 32 Basic filtered search ...... 33 Filtered search with filter type icons ...... 34 Limiting the width of the search field ...... 35 C++ API reference ...... 35 Line edit ...... 35 Anatomy of the line edit widget ...... 35 Basic line edit ...... 36 Line edit with search ...... 37 Listening for line edit changes ...... 37 Line edit as a drop target ...... 37 Line edit with validator ...... 38 Disabled line edit ...... 38 C++ API reference ...... 39 Related links ...... 39 Number edit spinbox ...... 39 Anatomy of the spinbox widget ...... 39 Basic spinbox ...... 40 C++ API reference ...... 40 Progress indicators ...... 40 Usage guidelines ...... 41 Basic progress bar ...... 42 Basic progress spinner ...... 43 C++ API reference ...... 43 Radio button ...... 43 Usage guidelines ...... 44 Basic radio button ...... 44 C++ API reference ...... 45 Reflected property editor ...... 45 Reflected property editor in a card ...... 46 Scrollbar ...... 46 Scrollbar display modes ...... 47 Scrollbar with dark style ...... 47 C++ API reference ...... 48 Slider and slider combo ...... 48 Usage guidelines ...... 49 Basic slider with midpoint ...... 49 Slider with tooltip ...... 49 Basic slider combo ...... 50 C++ API reference ...... 50 Styled dock ...... 50 Fancy docking using the styled dock widget ...... 53 C++ API reference ...... 54 Tab ...... 55 Usage guidelines ...... 55 Basic tab ...... 55 C++ API reference ...... 56 Table view ...... 56 Basic table view ...... 57 C++ API reference ...... 58 Toggle switch ...... 58 Usage guidelines ...... 59 Basic toggle switch ...... 60 C++ API reference ...... 60 Related links ...... 26 Tree view ...... 60 Usage guidelines ...... 61

Version 1.28 iv Amazon Lumberyard UI Extensions Guide

Basic tree view ...... 62 C++ API reference ...... 63 UI icon assets ...... 64 Component icons ...... 64 Entity outliner icons ...... 66 C++ API reference index ...... 69

Version 1.28 v Amazon Lumberyard UI Extensions Guide

This guide is a work in progress. Please provide feedback using the Feedback link at the top of the web page. More coverage of the Lumberyard UI component library is coming!

Version 1.28 vi Amazon Lumberyard UI Extensions Guide

Introduction to Lumberyard UI development

Introduced with Amazon Lumberyard version 1.25 and the release of UI 2.0, Lumberyard’s custom Qt widget library provides developers with access to the same UI components used throughout Lumberyard. Using this library, UI developers can build their own tools and extensions for Lumberyard, while maintaining a coherent and standardized UI experience. This custom library provides new and extended widgets, and includes a set of styles and user interaction patterns that are applied on top of the Qt framework - the C++ library that Lumberyard relies on for its UI. The library can be extended to support your own customizations and modiﬁcations.

Our objective with this UI extensions guide is to provide you with extensive documentation on all aspects of Lumberyard user interface development using the custom widget library, covering both the design and development sides of your implementation. We intend to cover as many use cases, workflows, code samples, and usage guidelines as possible to explain how to use these components efficiently and effectively. We also provide links throughout the guide to the separate, C++ API reference documentation, for when you need detailed information about each method and property available to you in the library. And finally, we intend to continue adding to this source of information over time, to extend the wealth of information found in these pages.

Version 1.28 1 Amazon Lumberyard UI Extensions Guide How to use the Amazon Qt control gallery

Lumberyard Qt control gallery tool

Use the Amazon Qt Control Gallery tool to see the Amazon Lumberyard custom Qt widget library in action. There, you will ﬁnd sample code and working examples of selected components.

How to use the Amazon Qt control gallery

Before you begin, make sure that you have Lumberyard 1.25 or later installed on your machine.

Version 1.28 2 Amazon Lumberyard UI Extensions Guide How to use the Amazon Qt control gallery

1. Open File Explorer and go to your build directory. (For example, C:\{your-lumberyard- installation-path}\{version}\dev\Bin64vc142\ or Bin64vc141\.) 2. Double-click on AmazonQtControlGallery.exe to launch the Amazon Qt Control Gallery tool.

3. Use the main dropdown menu to navigate through the pages. For each component, the right column shows a live example of how the widget looks and works. In the left column, you will ﬁnd sample code related to each component.

Note The gallery does not cover how to set up a window for your tool, or the basics of how the Qt library works. Its primary objective is to illustrate the styles and features of the components in the library.

Version 1.28 3 Amazon Lumberyard UI Extensions Guide Style sheets and StyleManager

Lumberyard UI component development guidelines

For many of the basic components (such as check boxes, push buttons, and line edits), you will use the base Qt widgets (such as QCheckBox, QPushButton, QLineEdit) and the custom styling and behavior is applied automatically. Components that require extended functionality, or are unique to Lumberyard, are custom classes that can be subclassed and can include a combination of Qt widgets. In these cases, the class deﬁnitions live in this folder: dev/Code/Framework/AzQtComponents/AzQtComponents/ Components/. Style sheets and StyleManager

The Lumberyard UI is built upon Qt Style Sheets, which is a powerful mechanism for customizing the appearance of widgets. The concepts and syntax are similar to Cascading Style Sheets (CSS).

In Qt Style Sheets, the AzQtComponents module has a StyleManager class, which installs a custom QProxyStyle class at the application level. The QProxyStyle class overrides the styling of all widgets with custom styling. This is how you can use a basic Qt widget(such as QPushButton or QCheckBox) and give it the custom styling.

The StyleManager class is pre-loaded with a series of base style sheets, starting with dev/Code/ Framework/AzQtComponents/AzQtComponents/Components/Widgets/BaseStyleSheet.qss. This style sheet applies custom styling for each individual widget, each of which is separated into ﬁles such as “CheckBox.qss” and “PushButton.qss”. This styling is applied down through the entire widget hierarchy, starting from the top application layer. Additional custom style sheets can be applied at lower levels (such as in your own custom tool) that aﬀect only that widget and any of its children.

Get started with UI component development

Depending on your tools and existing code, accessing the new library of components might require some initial setup.

If your tool is part of the core Lumberyard Editor or is part of a gem, and uses the Lumberyard Editor’s Qt Application, you’re already set up and ready to go. Just include the header for the component that you need to use from the dev/Code/Framework/AzQtComponents/AzQtComponents/Components/ folder. If Visual Studio is raising errors, make sure AzQtComponents is listed in the use and include sections in the wscript ﬁle, as shown in the following example.

def build(bld): bld.DefineGem( editor = dict( use = ['AzQtComponents'], ... ) )

For standalone tools with their own Qt Application, you must take some extra steps to make sure that the new styling is applied correctly.

1. Set the attributes to correctly handle high DPI screens before creating the QApplication.

Version 1.28 4 Amazon Lumberyard UI Extensions Guide UI development best practices

#include

QCoreApplication::setAttribute(Qt::AA_EnableHighDpiScaling); QCoreApplication::setAttribute(Qt::AA_UseHighDpiPixmaps); QGuiApplication::setHighDpiScaleFactorRoundingPolicy(Qt::HighDpiScaleFactorRoundingPolicy::PassThrough); AzQtComponents::Utilities::HandleDpiAwareness(AzQtComponents::Utilities::PerScreenDpiAware);

QApplication app(argc, argv);

2. Instantiate a StyleManager, which loads the style sheets and custom settings for the new UI.

#include

AzQtComponents::StyleManager* styleManager = new AzQtComponents::StyleManager(this); const bool useLegacyStyle = false; styleManager->initialize(app, useLegacyStyle);

The StyleManager automatically loads the base style sheets, but you can add other resources as well. See the Stylesheet page of the Control Gallery tool (p. 2) for more information.

UI development best practices

Writing code to extend the core Lumberyard Editor? Here are some high level suggestions to comply with the UI guidelines:

• The UI styling uses an AWS standard color palette, which includes grays and blues. Creating a custom style and color override will have your tool looking inconsistent with the rest of the Lumberyard Editor. We suggest avoiding custom style overrides whenever possible so that Lumberyard appears as one cohesive application. • The Editor now supports vector file formats for icons, which prevents them from appearing blurry or pixelated on high DPI displays. Make sure to use SVG files for your icons, and replace old PNGs and JPGs with vector graphics images in existing tools if possible. • When using a custom icon not provided by Lumberyard, the icon should be a multiple of 16 x 16. • Moving forward, we want to make sure the user experience is cohesive and familiar throughout the whole Lumberyard Editor. You should avoid making one-off custom changes; and when you add new features, add them to the library so that they are available to the whole Editor instead of just a single tool. • Avoid subclassing or encapsulating the widgets from the component library. If you need some specific behavior, check our resources to verify if it’s already available in the component library via specific settings.

Frequently asked questions

Question: Can I copy the code example directly from the AmazonQtControlGallery?

• Yes. Please note that not all settings will be covered by this tool. Use this extensions guide and the Lumberyard UI Extensions C++ API Reference to ﬁnd additional examples and documentation.

Question: What about visual and color modiﬁcations to the controls?

• We do not endorse custom modiﬁcations to the layout and visual design as we want to support an experience that feels uniﬁed across all of our tooling. Nonetheless, sometimes minor spacing and

Version 1.28 5 Amazon Lumberyard UI Extensions Guide Frequently asked questions

style adjustments may be needed. See the Stylesheet page of the Control Gallery tool (p. 2) for more information on how to load a custom QSS style sheet.

Question: Why should I use the existing widget styling instead of creating my own?

• Over the past several years, we have listened to feedback from all kinds of customers who are building games with Lumberyard, and one common note was that the user experience across the diﬀerent tools of the Editor felt fragmented. The component library was built with this feedback in mind, and aims to bring uniﬁed and coherent standards to the whole Editor.

On the development side, this solution allows for better modularity and code reuse, with the objective of reducing the work needed from developers to create interfaces. Unifying the UI controls also allows improvements to be easily shared, since the whole Editor automatically uses them once applied, and likewise reduces the possibility of issues during library updates or core changes.

Question: Why should I not create subclasses or encapsulate the existing widgets?

• The component library aims to simplify development and streamline the user experience. By subclassing or encapsulating the UI components to change their behavior or add features, special cases are added to the code base. These cases would then need special documentation and testing to avoid regressions. Subclassing or encapsulating UI components provides very little beneﬁt, compared to keeping all UI components together in one place.

Subclassing is also detrimental to discoverability, since it is much harder for a new developer to find, import and re-use code that was built specifically in a tool without creating new dependencies or duplicating code. In the past, this has lead to multiple tools creating their own special controls that did very similar things, but in wildly different ways that made it hard to unify them and verify their behavior.

Version 1.28 6 Amazon Lumberyard UI Extensions Guide Breadcrumbs

Lumberyard UI component library

In the Lumberyard UI component library, you will ﬁnd an explanation of each UI component (i.e. widget), along with guidelines for their usage. Typically, each page contains the following information:

• Use cases • Screenshots and explanations of component features • Usage guidelines • Code snippets showing you how to use the most common features • Links to C++ API reference page for each component • Links to related information in the Qt widget library

Topics • Lumberyard UI breadcrumb navigation component (p. 7) • Lumberyard UI browse edit component (p. 12) • Lumberyard UI button styles (p. 16) • Lumberyard UI card component (p. 18) • Lumberyard UI checkbox component (p. 24) • Lumberyard UI combobox component (p. 27) • Lumberyard UI menu component (p. 29) • Lumberyard UI ﬁltered search widget (p. 32) • Lumberyard UI line edit component (p. 35) • Lumberyard UI spinbox component (p. 39) • Lumberyard UI progress indicators (p. 40) • Lumberyard UI radio button style (p. 43) • Lumberyard UI reﬂected property editor (p. 45) • Lumberyard UI scrollbar styles (p. 46) • Lumberyard UI sliders (p. 48) • Lumberyard UI styled dock widget (p. 50) • Lumberyard UI tab component (p. 55) • Lumberyard UI table view component (p. 56) • Lumberyard UI toggle switch component (p. 58) • Lumberyard UI tree view component (p. 60)

Additionally, a complete guide to the C++ API can be found in the Lumberyard UI Extensions C++ API Reference.

Lumberyard UI breadcrumb navigation component

Use the breadcrumbs component to enable users to track their position along a hierarchical path. Breadcrumbs include a path from the home page to the user’s current location. The points in the

Version 1.28 7 Amazon Lumberyard UI Extensions Guide Breadcrumbs breadcrumbs refer to a directory or node. Users can easily move positions in the path by selecting one of the breadcrumbs.

For an example of the "breadcrumb" concept, see the Anim Graph navigation in the Lumberyard Animation Editor.

Version 1.28 8 Amazon Lumberyard UI Extensions Guide Breadcrumbs

Version 1.28 9 Amazon Lumberyard UI Extensions Guide Anatomy of the breadcrumbs widget

In an Anim Graph breadcrumb, the graph’s name is displayed as the top level of navigation. Each node that you open appears as a clickable hyperlink. Anatomy of the breadcrumbs widget

Breadcrumbs have several customization options. The standard, horizontal layout includes the following features:

1. Path history navigation

(Optional) Enable users to navigate backwards and forwards in their history of breadcrumb paths selections. For example, if you browse to, or choose, a new path in the list, then choose the back button, you will navigate back to the previous breadcrumb position. 2. Breadcrumb trail

Shows the full path from root to tail. Users can select any point in the path to set a new path. Previously selected paths are automatically added to the navigational history. 3. Browse button

(Optional) Technically not part of the breadcrumb. The browse button is often useful because it enables a user to select a completely new path, instead of choosing a diﬀerent point in the current path. You push the new path to your breadcrumbs widget in your browse button handler code.

4. Truncation menu

If the entire breadcrumb path cannot ﬁt in the allotted space, the points on the path that don’t ﬁt are stacked in a dropdown menu. Users can select these points from the truncation menu.

Basic breadcrumb

The simplest breadcrumb example includes the breadcrumbs widget and an optional, initial path. Your code can react to path changes by connecting to the pathChanged signal. Alternatively, you can call pushPath to set the breadcrumb state to match the current state of your project.

When passing a path QString into pushPath, use either forward slash ('/') or backward slash ('\\') as a path separator.

Example

Version 1.28 10 Amazon Lumberyard UI Extensions Guide Breadcrumb with path navigation and browse

#include

// Create a new breadcrumbs widget. AzQtComponents::BreadCrumbs* breadCrumbs = new AzQtComponents::BreadCrumbs(parent);

// (Optional) Set the initial path. QString initialPath = "C:/Documents/SubDirectory1/Subdirectory2/SubDirectory3"; breadCrumbs->pushPath(initialPath);

// Add the widget to a previously defined QHBoxLayout. layout->addWidget(breadCrumbs);

// Listen for path changes. connect(breadCrumbs, &AzQtComponents::BreadCrumbs::pathChanged, this, [](const QString& newPath) { // Handle path change as needed by your project. });

// Add breadcrumbs to a UI layout as needed.

Breadcrumb with path navigation and browse

In some scenarios, it’s useful for users to be able to navigate back and forth in their navigation history. In addition, you might want to oﬀer a browse button to select a new path.

In the following example, createBackForwardToolBar provides the forward and backward navigation arrows, and a NavigationButton::Browse from AzQtComponents provides a ﬁle browser button.

Example

#include #include

// Create a new breadcrumbs widget. AzQtComponents::BreadCrumbs* breadCrumbs = new AzQtComponents::BreadCrumbs(parent);

// (Optional) Set the initial path. QString initialPath = "C:/Documents/SubDirectory1/Subdirectory2/SubDirectory3"; breadCrumbs->pushPath(initialPath);

// Create the browse button widget. auto browseButton = breadCrumbs->createButton(AzQtComponents::NavigationButton::Browse);

// Add the widgets to a previously defined QHBoxLayout. layout->addWidget(breadCrumbs->createBackForwardToolBar()); layout->addWidget(breadCrumbs->createSeparator()); layout->addWidget(breadCrumbs); layout->addWidget(breadCrumbs->createSeparator()); layout->addWidget(browseButton);

// Update the breadcrumb path from the output of the browse button. connect(browseButton, &QPushButton::pressed, breadCrumbs, [breadCrumbs] { QString newPath = QFileDialog::getExistingDirectory(breadCrumbs, "Select a new path"); if (!newPath.isEmpty()) { breadCrumbs->pushPath(newPath); } });

Version 1.28 11 Amazon Lumberyard UI Extensions Guide C++ API reference

// Listen for path changes. connect(breadCrumbs, &AzQtComponents::BreadCrumbs::pathChanged, this, [](const QString& newPath) { // Handle path change as needed by your project. });

// Add the breadcrumbs to a UI layout as needed.

C++ API reference

For details on the breadcrumbs API, see the following topic in the Lumberyard UI Extensions C++ API Reference:

• AzQtComponents::BreadCrumbs

Lumberyard UI browse edit component

The browse edit component is one of several types of input boxes offered by the Qt and Lumberyard UI libraries. Use the browse edit component to enable users to choose one or more values from a selection window. Typical uses include selecting a file from a directory, or one or more items from a list - for example: choosing motions from a collection of animation assets. The selection window is opened using either a button along the right edge, or a double-click in the input box. Chosen values can be cleared using the clear button, if this button has been enabled. Note Use a dropdown combo box (p. 27) instead if there is a predefined list of items to select, and a user only needs to select one value from the list. Anatomy of the browse edit widget

Browse edit widgets have several customization options. Standard features including the following elements:

1. Label

While not technically part of the widget, you should give input boxes a label in the UI layout. 2. Placeholder text

(Optional) Hint text that you set using setPlaceholderText() appears here when the widget text is empty. 3. Input box

Text that you set using setText() appears here. Users can double-click here to open the selection window that you have connected to the BrowseEdit::attachedButtonTriggered signal. Single click actions do nothing here, unless the read-only attribute has not been set to true.

Version 1.28 12 Amazon Lumberyard UI Extensions Guide Basic browse edit

Note Generally when using the browse edit component, you set the input box to be read only. If you want to allow users to edit the value directly from the input box, use the line edit (p. 35) component instead, with a detached button next to it. 4. Attached button

(Optional) The browse edit input box has an attached button. The default button uses a folder icon, but you can specify a diﬀerent icon. To specify what happens when users press the button, connect to the BrowseEdit::attachedButtonTriggered signal. Note When using a custom icon not provided by Lumberyard, the icon should be a multiple of 16 x 16 and should only be in SVG format. 5. Tooltip

(Optional) If you set tooltip text for the widget, it will appear near where the user hovers.

6. Clear button

(Optional) If you enable the clear button for the widget, it will appear when the input box is not empty. When users choose the clear button, the input box returns to an empty value.

7. Error state indicator

(Optional) If you set a validator for the input box, and validation fails, an error state indicator icon appears at the end of the input box, before the clear button. 8. Error tooltip

(Optional) When an error state exists, if an error tooltip has been set for the widget, it will appear near where the user hovers. This tooltip appears in place of the normal tooltip text while an error state exists. If you set a validator for the input box, it is highly recommended that you also set an error tooltip.

Basic browse edit

A simple example of this component includes the browse edit widget and an attached button handler. In this example, we enable the user to pick a ﬁle from the ﬁle browser, and have chosen to enable the clear button.

Version 1.28 13 Amazon Lumberyard UI Extensions Guide Browse edit with custom icon and placeholder text

Example

#include #include

// Create a new browse edit widget. AzQtComponents::BrowseEdit* browseEdit = new AzQtComponents::BrowseEdit(parent);

// Enable the clear button. browseEdit->setClearButtonEnabled(true);

// Require users to use the attached button or double-click the input box to open the selection window. browseEdit->setLineEditReadOnly(true);

// Connect the attached button to the QFileDialog function. connect(browseEdit, &AzQtComponents::BrowseEdit::attachedButtonTriggered, this, [this]() { QString file = QFileDialog::getOpenFileName(this, "Select a file asset"); if (!file.isEmpty()) { QFileInfo fileName(file); browseEdit->setText(fileName.fileName()); } });

// Then add browseEdit to a UI layout as needed. Browse edit with custom icon and placeholder text

The following example shows how to replace the default button icon with your own, and how to add placeholder text that appears when the value is empty. Note When using a custom icon not provided by Lumberyard, the icon should be a multiple of 16 x 16 and should only be in SVG format.

Example

#include #include

// Set a custom attached button icon. QIcon icon(":/stylesheet/img/help.svg"); browseEdit->setAttachedButtonIcon(icon);

// Require users to use the attached button or double-click the input box to open the selection window. browseEdit->setLineEditReadOnly(true);

// Set the placeholder text. browseEdit->setPlaceholderText("Enter an offset value");

// Connect the attached button to the QInputDialog function. connect(browseEdit, &AzQtComponents::BrowseEdit::attachedButtonTriggered, this, [this]() { QString text = QInputDialog::getText(this, "Offset", "Enter an offset value"); if (!text.isEmpty()) { browseEdit->setText(text); } });

Version 1.28 14 Amazon Lumberyard UI Extensions Guide Browse edit with tooltips and validator

Browse edit with tooltips and validator

In the following example, both a standard tooltip and an error tooltip have been deﬁned. The standard tooltip appears when a mouse hovers over the widget. The error tooltip appears when a mouse hovers over the widget while an error state exists.

Error states occur when a validator has been set and its validation has failed.

Example

#include #include #include

// Set a custom attached button icon. QIcon icon(":/stylesheet/img/help.svg"); browseEdit->setAttachedButtonIcon(icon);

// Enable the clear button. browseEdit->setClearButtonEnabled(true);

// Require users to use the attached button or double-click the input box to open the selection window. browseEdit->setLineEditReadOnly(true);

// Set the placeholder text. browseEdit->setPlaceholderText("Enter an integer between 0 and 9999");

// Define and set the validator. QRegExp intRangeExp("[0-9]\\d{0,3}$"); browseEdit->setValidator(new QRegExpValidator(intRangeExp, 0));

// Set the tooltip text. browseEdit->setToolTip("Enter an offset value using the button."); browseEdit->setErrorToolTip("Acceptable values are integers between 0 and 9999.");

// Connect the attached button to the QInputDialog function. connect(browseEdit, &AzQtComponents::BrowseEdit::attachedButtonTriggered, this, [this]() { QString text = QInputDialog::getText(this, "Offset", "Enter an integer between 0 and 9999"); if (!text.isEmpty()) { browseEdit->setText(text); } }); Disabled browse edit

In the following example, the widget and its features have been disabled in code.

Example

#include

Version 1.28 15 Amazon Lumberyard UI Extensions Guide C++ API reference

// Disable the widget. browseEdit->setEnabled(false);

C++ API reference

For details on the browse edit API, see the following topic in the Lumberyard UI Extensions C++ API Reference:

• AzQtComponents::BrowseEdit

Related links

For components related to the browse edit component, see the following topics:

• Line edit (p. 35) • Number edit spinbox (p. 39)

Lumberyard UI button styles

Use buttons to enable users to make selections that cause the UI to take action. There are four types of button styles in Lumberyard:

• Primary button • Secondary button • Dropdown button • Icon button

Usage guidelines

Follow these guidelines as you design your UI with buttons:

1. Buttons should trigger events

Version 1.28 16 Amazon Lumberyard UI Extensions Guide Applying styles

Choosing a button should always trigger an event. For example, the event might be submitting a form, opening a dialog, or showing a dropdown menu. 2. Primary button vs secondary button

Only one primary button per page should receive the primary button color. We recommend that you always set the aﬃrmative button with the primary button color. All other actions on the page should be styled with the secondary button color, which will help users establish what the primary action on any given window or panel is. 3. Button placement in a dialog

The buttons should be placed on the bottom right hand corner of the dialog, with the aﬃrmative button on the left, and the dismissive button on the right on the Windows platform. This reduces cognitive load for users and clariﬁes the hierarchy of available actions on the page.

When on the iOS platform, the button placement should follow the iOS platform guideline, which is the aﬃrmative button on the right, and the dismissive button on the left. 4. Button placement on a card

Because cards have ﬂexible layouts, we recommend that you place the button in a location suited to the content and context, while maintaining consistency within the product. When the button isn’t attached to any labels, it’s suggested to place the button in the center of the area. 5. Dropdown menus

Use dropdown menus where there is more than one value associated with the button. When users choose the button and select the desired value, buttons should immediately trigger an event. 6. Icon buttons

Use icon buttons when there isn’t enough space to display the full text on the button. However, the context should be clear to users what action will be triggered after clicking on the icon button. The icon shown on the button should also clearly represent the meaning of the function. Use a mouseover tooltip to display the text version of the button.

Avoid these design choices when using buttons:

• Don’t include a button as part of a sentence. • Don’t include more than one primary colored button on a UI. • Don’t use an icon button when there isn’t enough context for users to know the purpose of the button. • Never hide a button if a button is disabled. A button should always be visible to the user, no matter its state.

Applying styles

You can apply one of the four button styles either in the Qt Designer, where it is saved in the .ui ﬁle, or in your code. Refer to the comments in the example below for details.

Example

#include #include #include #include

// Secondary button is the default style for QPushButton. QPushButton* pushButtonSecondary = new QPushButton(parent);

Version 1.28 17 Amazon Lumberyard UI Extensions Guide C++ API reference

// To define a QPushButton as a primary button, // set "default" property to true in the .ui, or apply the primary style. QPushButton* pushButtonPrimary = new QPushButton(parent); AzQtComponents::PushButton::applyPrimaryStyle(ui->dropdown);

// Apply the icon style to a QToolButton by adding an icon. QIcon icon(":/stylesheet/img/logging/add-filter.svg"); QToolButton* toolButton = new QToolButton(parent); toolButton->setIcon(icon);

// You can also apply the small icon style to an icon button. AzQtComponents::PushButton::applySmallIconStyle(toolButton);

// Add the dropdown style to a push button or tool button using setMenu(). QMenu* menu = new QMenu(parent); auto menuOption = menu->addAction("Option"); menuOption->setCheckable(true); pushButtonSecondary->setMenu(menu); toolButton->setMenu(menu);

C++ API reference

For details on the button styles, see the following topic in the Lumberyard UI Extensions C++ API Reference:

• AzQtComponents::PushButton

Relevant Qt documentation includes the following topics:

• QPushButton Class • QToolButton Class

Lumberyard UI card component

Use cards to display information in highly interactive, ﬂexible containers. Users can easily stack, reorder, and collapse these containers. All content within a card should relate to only one idea. Cards should be easy to scan for relevant and actionable information, and are predominantly used to display editable details for a component or a class.

For example, a card might include common properties, action buttons, advanced settings, and a context menu for additional actions:

Version 1.28 18 Amazon Lumberyard UI Extensions Guide Anatomy of the card widget

To make it easier for users to scan a card, make the content layout consistent. This includes using the same font size, style, and spacing for headings and content. Be consistent with your use of images and icons, and primary and secondary actions (if required). Card titles are key to allowing users to easily scan the content, so make sure the titles are highly visible. Anatomy of the card widget

Cards allow for a certain amount of customization. The basic layout of a card includes the following features:

1. Expander and header bar

Cards expand or collapse when users click the arrow on the top left.

If the card can be moved, users press and drag the header bar to reposition the card. 2. Card icon

(Optional) Cards can have their own unique icon related to their purpose. For the full list of icons, see the section called “Component icons” (p. 64). Note Two icons are required for new components: • A 16 x 16 SVG with a background box for the perspective window. • An SVG for everywhere else in the editor, without a background box. 3. Card name

Each card has their own name related to their purpose. You can conﬁgure the name to change from white to orange to signify that content in the widget has been modiﬁed. 4. Help icon

(Optional) Cards can display a link to documentation that describes the card’s functionality. 5. Context menu icon

(Optional) The card’s context menu opens when users choose this icon. The context menu can also be opened by right-clicking the card header with a mouse. 6. Card content widget Version 1.28 19 Amazon Lumberyard UI Extensions Guide Basic card

This area contains the content widget for the card. Most cards contain a reﬂected property editor (p. 45) component, but cards can hold any widget. 7. Advanced options

(Optional) When a secondary content widget is set, a label for it is displayed here. The Advanced options menu expands or collapses when users choose the arrow on the left of the label. You can customize the label’s text. 8. Notiﬁcations

(Optional) Notiﬁcations (p. 23) that you added to the card are displayed here. Buttons or other widgets can be added to notiﬁcations as a means of resolving them. 9. Call to action region

(Optional) Supplemental actions should be placed at the bottom of the card. We refer to this as the Call to Action region. Typically, a call to action is represented by a button added to the bottom of a content widget, or in a card notiﬁcation. Avoid using primary buttons here because they should be reserved for the overall action on a page. Instead, use secondary or tertiary buttons, link buttons, and icon buttons here.

Basic card

The simplest card consists of these components:

• Card header • Expand/collapse icon • (Optional) Card icon • Card name • (Optional) Context menu (enabled by default) • Card content

Example

#include #include

// Create the card. AzQtComponents::Card* card = new AzQtComponents::Card(parent);

// Set the card icon. card->header()->setIcon(QIcon(QStringLiteral(":/stylesheet/img/some_icon.svg")));

// Set the card title. card->setTitle("Example Card");

// Disable the context menu (enabled by default). card->header()->setHasContextMenu(false);

// Add the content widget. card->setContentWidget(new QWidget());

Version 1.28 20 Amazon Lumberyard UI Extensions Guide Card with context menu and help icon

// Add the card to a UI layout as needed.

Card with context menu and help icon

Display a help icon on the card to redirect users to a webpage for documentation.

The following code demonstrates how to set up a help link and start a context menu.

Example

// Set the card help icon. card->header()->setHelpURL("https://aws.amazon.com/documentation/lumberyard/");

// Enable the context menu (enabled by default). card->header()->setHasContextMenu(true);

// Some base code to add a context menu. // contextMenuRequested is triggered both by clicking the context menu icon // and by right clicking the Card header. connect(ui->basicCard, &AzQtComponents::Card::contextMenuRequested, this, [](const QPoint& point) { QMenu basicMenu; basicMenu.addAction(new QAction("Some Action", nullptr)); basicMenu.exec(point); }); // Note: The menu can be created in advance and executed on contextMenuRequested.

Card with secondary content

Display a secondary content widget. Its title is customizable.

Example

// Set the secondary content title. card->setSecondaryTitle("Advanced Options");

// Add the secondary content widget.

Version 1.28 21 Amazon Lumberyard UI Extensions Guide Card with modiﬁed content

card->setSecondaryContentWidget(new QWidget());

Card with modiﬁed content

Conﬁgure the care title to change color when the content is edited, diﬀerent from the parent slice, or has not been saved yet. We recommend enabling this functionality on all cards.

Example

// Set the content modified state in response to content change. card->header()->setContentModified(true);

Disabled card

Fully disable the card, including header bar icons and child widgets. Note If you want the card content to be disabled, but allow users to still use the help button and context menu in the header bar, use the Mock Disabled (p. 22) state.

Example

// Disable the card widget using a Qt function. All functionality of the card is disabled. card->setEnabled(false);

Mock disabled card

Disable primary and secondary widgets on the card, but keep the header bar enabled. The following card features remain functional:

• Expand/collapse

Version 1.28 22 Amazon Lumberyard UI Extensions Guide Card with warning state

• Help • Context menu

Example

// Display the card as disabled while retaining functionality in the header bar. card->mockDisabledState(true);

Card with warning state

Set a warning state on the card header. Note You can independently set the disabled state and warning state.

Example

// Display a warning icon in the header bar to indicate a warning state. card->header()->setWarning(true);

Card with notiﬁcation

Add notifications to indicate misconfigurations and other errors. Remove the notification when the issue is resolved.

Customize the notiﬁcation with the following:

• Message • (Optional) Action button • (Optional) Custom widget

Note In addition to buttons, you can use addFeature(QWidget*) to add a custom widget to the warning notiﬁcation.

Version 1.28 23 Amazon Lumberyard UI Extensions Guide C++ API reference

Example

#include

// Create a new notification with a message string. AzQtComponents::CardNotification* notification = card->addNotification("A warning message indicating a conflict or problem.");

// (Optional) Add a custom button to the notification. QPushButton* button = notification->addButtonFeature("Clear Warnings");

// Connect a behavior to the button. connect(button, &QPushButton::clicked, ui->functionalCard, &AzQtComponents::Card::clearNotifications);

C++ API reference

For details on the card API, see the following topics in the Lumberyard UI Extensions C++ API Reference:

• AzQtComponents::Card • AzQtComponents::CardHeader • AzQtComponents::CardNotiﬁcation

Related links

For additional information related to the card component, see the following topics:

• Reﬂected Property Editor (p. 45)

Lumberyard UI checkbox component

Use checkboxes to enable users to select from a list of choices, when users can select any number of choices (including zero, one, or several). Each checkbox is independent of all other checkboxes in the list, so checking one box doesn’t uncheck the others.

Version 1.28 24 Amazon Lumberyard UI Extensions Guide Usage guidelines

Usage guidelines

Follow these guidelines as you design your UI with checkboxes:

1. Each checkbox should have a clear yes/no state for its choice. 2. Default a checkbox to "checked" only when there is clear reason to believe that a user will expect that, or when it reﬂects the user’s current state. 3. Ensure that clicking or tapping the label selects the checkbox. 4. When using checkboxes in tree views, the partial selected states should be included.

Avoid these design choices when using checkboxes:

• Don’t order checkboxes horizontally. • Don’t trigger an event upon selection of a radio button, such as spawning a popover, popup, new page, or new window.

Version 1.28 25 Amazon Lumberyard UI Extensions Guide Basic checkbox

Basic checkbox

Set up and control checkboxes in Qt Designer or in code.

Note that to set the "partially checked" state in tri-state checkboxes, you must use code.

Example

#include

QCheckBox* checkBox = new QCheckBox(parent);

// To set a checkBox to checked, do one of the following: checkBox->setCheckState(Qt::Checked); checkBox->setChecked(true);

// To set a checkbox to unchecked, do one of the following: checkBox->setCheckState(Qt::Unchecked); checkBox->setChecked(false);

// To turn a checkBox into a tri-state checkbox, so it can be on, off, or partial: checkBox->setTristate(true);

// To set a checkBox to partially on: checkBox->setCheckState(Qt::PartiallyChecked);

// To disable the checkBox: checkBox->setEnabled(false);

C++ API reference

For details on the checkbox API, see the following topic in the Lumberyard UI Extensions C++ API Reference:

• AzQtComponents::CheckBox

Relevant Qt documentation includes the following topics:

• QCheckBox Class

Related links

For additional information related to the checkbox component, see the following topics:

• Toggle switch (p. 58)

Version 1.28 26 Amazon Lumberyard UI Extensions Guide Combobox

Lumberyard UI combobox component

Use comboboxes to oﬀer users a list of options from a dropdown menu. You deﬁne whether or not the input box is editable. An editable input box allows the user to type in a value or select a value from the dropdown menu.

Usage guidelines

Follow these guidelines as you design your UI with comboboxes:

1. When a user mouses over the combobox, a border line should show around the combobox. 2. Use a dropdown list to give the user an option to make a single choice from a set of mutually exclusive options.

Version 1.28 27 Amazon Lumberyard UI Extensions Guide Basic combobox

3. Use a dropdown list when the number of options is greater than 2 and less than "a lot". When you have only one or two options, use a radio button (p. 43) group instead. It’s diﬃcult to prescribe an upper limit on the number of options, because it depends on context. However, it is acceptable to have a long list of choices when users are likely to be familiar with them and the options are well-ordered and easily scannable to the eye. 4. Set a default value that most users would likely select. If you choose not to use a default value, include strong and clear placeholder text instead, such as "select size". 5. Sort the values to best match the mental model of your users. Use your best judgment on how a user will expect options to be ordered, such as sequential dates or car models. Often, using an alphabetical or numerical order is appropriate, or you might consider grouping options by theme.

Avoid these design choices when using comboboxes:

• Don’t use a dropdown list when users might want to select multiple options. In that case, use a set of checkboxes, or buttons instead.

Basic combobox

Set up and control comboboxes in Qt Designer or in code.

Example

#include

// Create the combobox. QComboBox* comboBox = new QComboBox(parent);

// Add choices to the dropdown menu and set the default value. for (int i = 1; i <= 5; i++) { comboBox->addItem(QString("Option %1").arg(i), i - 1); } comboBox->setCurrentIndex(0);

// (Optional) Use placeholder text if you choose not to set a default value. // When setting placeholder text, the combobox must be editable. comboBox->setEditable(true); comboBox->lineEdit()->setPlaceholderText("Choose an option"); comboBox->setCurrentIndex(-1);

// To disable the combo box: comboBox->setDisabled(true);

Version 1.28 28 Amazon Lumberyard UI Extensions Guide Combobox with validator

Combobox with validator

In the following example, a simple validator has been deﬁned. When validation fails, an error icon appears in the combobox’s input box.

The default QComboBox implementation only sets a validator to the underlying QLineEdit, meant for editable QComboBox widgets. The AzQtComponents::ComboBox::setValidator function binds a validator to the QComboBox instead, and it won’t be deleted until the QComboBox itself is destroyed.

Example

#include #include

// Define a simple validator where the first choice is always invalid. class FirstIsErrorComboBoxValidator : public AzQtComponents::ComboBoxValidator { public: QValidator::State validateIndex(int index) const override { return (index == 0) ? QValidator::Invalid : QValidator::Acceptable; } };

// Add the validator to a previously defined combobox. auto validator = new FirstIsErrorComboBoxValidator(); AzQtComponents::ComboBox::setValidator(comboBox, validator);

C++ API reference

For details on the combobox API, see the following topic in the Lumberyard UI Extensions C++ API Reference:

• AzQtComponents::ComboBox

Relevant Qt documentation includes the following topics:

• QComboBox Class

Lumberyard UI menu component

A context menu (also called contextual or pop-up menu) appears upon user interaction, such as a right- click mouse operation. Use a context menu to oﬀer users a limited set of choices that are related to the current state, or context, of the component to which the menu belongs. Typically, the available choices are actions related to the selected object.

Version 1.28 29 Amazon Lumberyard UI Extensions Guide Usage guidelines

Usage guidelines

Follow these guidelines as you design your UI with context menus:

1. Include only the most commonly used commands that are appropriate in the current context. For example, in the context menu for selected text, it makes sense to include editing commands, but not a save or print command. 2. Limit the hierarchical depth of context menus to one or two levels. Sub-menus in context menus can be diﬃcult to navigate without accidentally dismissing the parent menu. If you must include sub- menus, restrict them to a single level. 3. Make context menu items available in a menu bar, if available. A context menu is hidden by default and a user might not know it exists, so it shouldn’t be the only way to access a command. In particular, avoid using a context menu as the only way to access an advanced feature. 4. Use a pop-up button to elevate context menu functionality. You can use a pop-up button to provide application-wide context menu functionality in a toolbar. The toolbar of a Finder window, for example, includes a pop-up button that gives users access to the same commands that are displayed in a context menu when control-clicking the selected item. 5. Context menus can also be used in the list view. Your UI should provide a hint to users that they can use right-click to show the context menu.

Avoid these design choices when using context menus:

Version 1.28 30 Amazon Lumberyard UI Extensions Guide Basic context menu

• Don’t set a default item in a context menu. If a user opens the menu and closes it without selecting anything, no action should occur.

Basic context menu

Context menus are based on the QMenu Qt widget. You can create one in Qt Designer or in your code. You can also modify them in code at runtime.

Example

#include

// Create the menu. QMenu* menu = new QMenu(parent);

// Add some actions. menu->addAction(QStringLiteral("Load")); menu->addAction(QStringLiteral("Save"));

// Add an action with a search icon. menu->addAction(QIcon(QStringLiteral(":/stylesheet/img/search.svg")), QStringLiteral("Search"));

// Add a separator. menu->addSeparator();

// Add a submenu. auto submenu = menu->addMenu(QStringLiteral("Submenu"));

// Add some checkable actions in the submenu. auto appleAction = submenu->addAction(QStringLiteral("Show Apples")); appleAction->setCheckable(true); appleAction->setChecked(true); auto orangeAction = submenu->addAction(QStringLiteral("Show Oranges")); orangeAction->setCheckable(true); auto pearAction = submenu->addAction(QStringLiteral("Show Pears")); pearAction->setCheckable(true);

// Add an action that is disabled. auto disabledAction = menu->addAction(QStringLiteral("Disabled")); disabledAction->setEnabled(false);

Version 1.28 31 Amazon Lumberyard UI Extensions Guide C++ API reference

C++ API reference

For details on the menu API used for styling of context menus, see the following topic in the Lumberyard UI Extensions C++ API Reference:

• AzQtComponents::Menu

Relevant Qt documentation includes the following topics:

• QMenu Class

Lumberyard UI ﬁltered search widget

Use the filtered search widget to give users advanced search options in your Lumberyard UI tools. You can see this interface in action in Lumberyard tools such as the Entity Outliner and Asset Browser. To quickly narrow their search to the results that they’re looking for, users can select one or more "type filters" to apply to the search terms that they type in the search field. Anatomy of the filtered search widget

Entity Outliner in the Lumberyard Editor uses multiple filter categories in a filtered search widget to help users find an entity with specific components or settings. In the following example, we’re looking for all entities with Script Canvas components.

1. Search ﬁeld

Users enter search terms here. In the Entity Outliner, they can enter entity names. For example, in the previous image they might enter the term Light to start looking for all entities that have the word "light" in their name.

Version 1.28 32 Amazon Lumberyard UI Extensions Guide Basic ﬁltered search

2. Filter menu button

(Optional) Add one or more type filters to your filtered search widget to show the filter menu button. When users select this button, the filter menu opens. 3. Filter type search field

Users can enter text in this field to narrow the list of filter types shown in the filter menu. 4. Filter type category

When adding ﬁlter types using the AddTypeFilter function, you can specify a category for grouping ﬁlter types. 5. Filter type

Users can select one or more filter types to narrow the search results to show only the results that match the types selected from the filter menu. You can add filter types, along with a filter type category, using the AddTypeFilter function. 6. Applied filters

By default, any filters that users select from the filter menu will appear under the search field. You can turn this off by calling setEnabledFiltersVisible(false) on your filtered search widget.

You can also add an icon in front of the name of the applied ﬁlter. See how to do this in the ﬁltered type icon (p. 34) example. 7. Search results

Show the search results below the search ﬁeld.

Basic ﬁltered search

The following example demonstrates how to create a simple ﬁltered search widget.

Example

#include

// Create a filtered search widget. auto filteredSearchWidget = new AzQtComponents::FilteredSearchWidget(parent);

Version 1.28 33 Amazon Lumberyard UI Extensions Guide Filtered search with ﬁlter type icons

}

// Connect the TextFilterChanged signal to a QSortFilterProxyModel. MyProxyModel proxyModel; connect(filteredSearchWidget, &AzQtComponents::FilteredSearchWidget::TextFilterChanged, proxyModel, static_cast(&MyProxyModel::setFilterRegExp));

// Connect the TypeFilterChanged signal to a proxy model that has a slot that can // handle changes of the type: // FilteredSearchWidget::TypeFilterChanged(const SearchTypeFilterList& activeTypeFilters) connect(filteredSearchWidget, &AzQtComponents::FilteredSearchWidget::TypeFilterChanged, proxyModel, &MyProxyModel::ApplyTypeFilters);

Filtered search with ﬁlter type icons

Add optional icons to your ﬁlter types using the extraIconFilename property of the AzQtComponents::SearchTypeFilter.

Example

#include

// Create a filtered search widget. auto filteredSearchWidget = new AzQtComponents::FilteredSearchWidget(parent);

// Add a filter type category and filter types. const QStringList filterTypes = { "Apple", "Orange", "Pear", "Banana" }; const QString filterCategory = "Fruit"; for (const auto& filterType : filterTypes) { AzQtComponents::SearchTypeFilter filterWithIcon(filterCategory, filterType); filterWithIcon.extraIconFilename = ":/stylesheet/img/tag_visibility_on.svg"; filteredSearchWidget->AddTypeFilter(filterWithIcon); }

Version 1.28 34 Amazon Lumberyard UI Extensions Guide Limiting the width of the search ﬁeld

Limiting the width of the search ﬁeld

Use setTextFilterFillsWidth(false) to limit the width of the search ﬁeld and prevent it from expanding to the full width of the widget.

Example

filteredSearchWidget->setTextFilterFillsWidth(false);

C++ API reference

For details on the ﬁltered search API, see the following topic in the Lumberyard UI Extensions C++ API Reference:

• AzQtComponents::FilteredSearchWidget

Lumberyard UI line edit component

The line edit component is one of several types of input boxes oﬀered by the Qt and Lumberyard UI libraries. Use the line edit component to enable users to enter free-form text. Be mindful of the length of text intended for a ﬁeld, and always pair with a useful, clear label. Anatomy of the line edit widget

Line edit widgets have several customization options. Standard features including the following elements:

1. Label

While not technically part of the widget, you should give input boxes a label in the UI layout. 2. Placeholder text

Version 1.28 35 Amazon Lumberyard UI Extensions Guide Basic line edit

(Optional) Hint text set in the UI, or using setPlaceholderText(), appears here when the widget text is empty. 3. Input box

Text entered by the user, or that you set using setText(), appears here. 4. Tooltip

(Optional) If you set tooltip text for the widget, it will appear near where the user hovers.

5. Clear button

(Optional) If you enable the clear button for the widget, it will appear when the input box is not empty. When users choose the clear button, the input box returns to an empty value.

6. Error state indicator

(Optional) If you set a validator for the input box, and validation fails, an error state indicator icon appears at the end of the input box, before the clear button. 7. Error tooltip

(Optional) When an error state exists, if an error message has been set for the widget, it will appear near where the user hovers. This tooltip appears in place of the normal tooltip text while an error state exists. If you don’t set the error message, the default error tooltip text is "Invalid input".

Basic line edit

A simple line edit component starts with the QLineEdit Qt widget. You can set additional options by changing widget settings in the Qt Designer or in code.

Example

#include

// Create a new line edit widget. QLineEdit* lineEdit = new QLineEdit(parent);

// Set the placeholder text. lineEdit->setPlaceholderText("Hint text");

// Enable the clear button. lineEdit->setClearButtonEnabled(true);

Version 1.28 36 Amazon Lumberyard UI Extensions Guide Line edit with search

// Then add lineEdit to a UI layout as needed.

Line edit with search

The AzQtComponents::LineEdit class provides several static style functions that apply a style to a QLineEdit widget. One example is the search style, which adds a search icon. Additional styles are documented in the API reference for AzQtComponents::LineEdit.

Example

#include #include

// Add a search icon. AzQtComponents::LineEdit::applySearchStyle(lineEdit);

// Listen for changes to the text by the user. connect(lineEdit, &QLineEdit::textEdited, this, [](const QString& newText) { // Perform the search as the user is typing. });

Listening for line edit changes

The following examples demonstrate how to listen for various types of text changes in a QLineEdit widget.

Example

#include

// Listen for changes to the text, either by the user or when setText() is called. connect(lineEdit, &QLineEdit::textChanged, this, [](const QString& newText) { // Handle text change. });

// Listen for changes to the text by the user. connect(lineEdit, &QLineEdit::textEdited, this, [](const QString& newText) { // Handle when user changes the text. });

// Listen for when the Return or Enter key has been pressed, or when the input box loses focus. connect(lineEdit, &QLineEdit::editingFinished, this, [lineEdit]() { // New text can be retrieved from lineEdit->text(). });

Line edit as a drop target

The following examples demonstrate how to apply or remove the drop target style to a QLineEdit widget.

Version 1.28 37 Amazon Lumberyard UI Extensions Guide Line edit with validator

Example

#include #include

// To show the QLineEdit as a valid drop target: AzQtComponents::LineEdit::applyDropTargetStyle(lineEdit, true);

// To show the QLineEdit as an invalid drop target: AzQtComponents::LineEdit::applyDropTargetStyle(lineEdit, false);

// To clear the drop target style: AzQtComponents::LineEdit::removeDropTargetStyle(lineEdit);

Line edit with validator

In the following example, both a validator and an error message for the error tooltip have been deﬁned. The standard tooltip appears when a mouse hovers over the widget. The error tooltip appears when a mouse hovers over the widget while an error state exists.

Error states occur when a validator has been set and its validation has failed.

Example

#include #include #include

// Define and set the validator. auto validator = new QDoubleValidator(lineEdit); validator->setNotation(QDoubleValidator::StandardNotation); validator->setTop(4.0); validator->setBottom(3.0); lineEdit->setValidator(validator);

// Set the error tooltip text. AzQtComponents::LineEdit::setErrorMessage(lineEdit, QStringLiteral("Value must be between 3.0 and 4.0"));

Disabled line edit

In the following example, the widget and its features have been disabled in code.

Example

#include

// Disable the widget. lineEdit->setEnabled(false);

Version 1.28 38 Amazon Lumberyard UI Extensions Guide C++ API reference

C++ API reference

For details on the line edit API, see the following topic in the Lumberyard UI Extensions C++ API Reference:

• AzQtComponents::LineEdit

Relevant Qt documentation includes the following topics:

• QLineEdit Class

Related links

For components related to the line edit component, see the following topics:

• Browse edit (p. 12) • Number edit spinbox (p. 39)

Lumberyard UI spinbox component

Use a spinbox as a number edit component to enable users to use a variety of controls to "spin" up or down a numeric value in an input box. The value is changed by the amount speciﬁed in the step value.

Use the SpinBox class for signed integer values, and the DoubleSpinBox class to hold double values. Note In scenarios where you would use the spinbox, also consider using the slider combo (p. 48) widget, which combines the extra visual cues of a slider with the ease of adjustment of a spinbox. Anatomy of the spinbox widget

Spinboxes provide the user with a variety of controls for entering or changing their numerical value.

1. Input box value

The current value in the input box area is editable. 2. Increment and decrement buttons

Users click on the increment or decrement button to adjust the numeric value by the step amount. 3. Spin control

The spin control appears when a pointer is near the edge of the input box. This is a faster way for the user to adjust the current value by the step amount. The user continuously changes the value as they move in the direction of one of the arrows while pressing the mouse button.

Version 1.28 39 Amazon Lumberyard UI Extensions Guide Basic spinbox

4. Current value indicator

The current value appears in this dialog box when a user hovers over the component for 1 second. Unlike the display of the value in the input box edit region, the value displayed here will not be truncated.

Basic spinbox

The following example demonstrates the creation of a simple, double spinbox.

Example

#include

// Create a new double spinbox widget. AzQtComponents::DoubleSpinBox* doubleSpinBox = new AzQtComponents::DoubleSpinBox(parent);

// Set its range from 0.0 to 20.0 and its initial value to 15.0. doubleSpinBox->setRange(0.0, 20.0); doubleSpinBox->setValue(15.0);

// Set the step value to 0.1. doubleSpinBox->setSingleStep(0.1);

C++ API reference

For details on the spinbox API’s, see the following topics in the Lumberyard UI Extensions C++ API Reference:

• AzQtComponents::SpinBox • AzQtComponents::DoubleSpinBox

Relevant Qt documentation includes the following topics:

• QSpinBox Class • QDoubleSpinBox Class

Lumberyard UI progress indicators

Use progress and status indicators to communicate to users that the Lumberyard application is working on a process, and what the result of that process is when it’s ﬁnished. Indicators should be employed when there’s a chance the user could be left wondering whether or not a process is working or hung.

Version 1.28 40 Amazon Lumberyard UI Extensions Guide Usage guidelines

Usage guidelines

Follow these guidelines as you design your UI with progress indicators:

1. Display progress when a latency of 3 milliseconds or more is expected. 2. Consider context and ﬂow when determining where and when to show progress. 3. Progress indicators are animated to reinforce that an activity is occurring.

Note See additional usage guidelines in the following sections, which apply to speciﬁc types of progress indicators.

Avoid these design choices when using progress indicators:

• Don’t use more than one progress indicator at a time.

Version 1.28 41 Amazon Lumberyard UI Extensions Guide Basic progress bar

Basic progress bar

Display determinate progress as a linear progress bar, to show a process or a task that has a deﬁnite start and end. In this scenario, the system is aware of how many steps are taken, and a likelihood of time for completion.

In the case where a system is malfunctioning, or doesn’t have either of these data points, consider using a spinner.

Additional usage guidelines for progress bars include the following:

1. If possible, use text to clearly display to the user that the system is working. For particularly long processes, consider using a combination of text to indicate where they are in the process, as shown in the previous image. 2. When available, display a numeric count under the progress bar, too. 3. For progress bars in a dialog, provide a single button to cancel the process.

The following example demonstrates the initialization of a simple progress bar. Refer to the Qt documentation on QProgressBar to learn additional features.

Example

#include

// Create the progress bar. QProgressBar* progressBar = new QProgressBar(parent);

// Set the numeric range of the bar. progressBar->setRange(0, 36);

// Set the current progress value. progressBar->setValue(12);

// Hide the progress text, as specified by the UX spec. It defaults to on, so it should be turned off. progressBar->setTextVisible(false);

Version 1.28 42 Amazon Lumberyard UI Extensions Guide Basic progress spinner

// Note that it can also be set from the .ui file, or from Qt Designer or Creator.

Basic progress spinner

Use spinners when it’s unclear when the process will ﬁnish.

Additional usage guidelines for spinners include the following:

1. Display spinners in the context of windows, panels, lists, or inline with other elements.

Example

#include

// Create the spinner. AzQtComponents::StyledBusyLabel* spinner = new AzQtComponents::StyledBusyLabel(parent);

// Set the spinner icon size. spinner->SetBusyIconSize(18);

// Start the spinner. spinner->SetIsBusy(true);

C++ API reference

For details on the progress indicator API’s, see the following topics in the Lumberyard UI Extensions C++ API Reference:

• AzQtComponents::ProgressBar • AzQtComponents::StyledBusyLabel (spinner)

Relevant Qt documentation includes the following topics:

• QProgressBar

Lumberyard UI radio button style

Use radio buttons to enable users to select from two or more options, when users must select exactly one choice. Choosing a radio button deselects the previously selected button.

Version 1.28 43 Amazon Lumberyard UI Extensions Guide Usage guidelines

Usage guidelines

Follow these guidelines as you design your UI with radio buttons:

1. Use radio buttons when you have two or more mutually exclusive options. 2. Ensure that clicking or tapping the label selects the radio button. 3. One radio button should always be selected by default. 4. Keep radio buttons from the same radio group in close proximity.

Avoid these design choices when using radio buttons:

• Don’t order radio buttons horizontally. • Don’t trigger an event upon selection of a radio button, such as spawning a popover, popup, new page, or new window.

Basic radio button

Set up and control radio buttons in Qt Designer or in code.

Version 1.28 44 Amazon Lumberyard UI Extensions Guide C++ API reference

Radio buttons that belong to the same parent will automatically be part of an exclusive group. You can create your own groups too, using a QButtonGroup.

Example

#include #include

QRadioButton* radioButton1 = new QRadioButton(parent); QRadioButton* radioButton2 = new QRadioButton(parent);

// Create a mutually exclusive group. QButtonGroup* buttonGroup = new QButtonGroup(this); buttonGroup->addButton(radioButton1); buttonGroup->addButton(radioButton2);

// To set a radio button to the selected state: radioButton1->setChecked(true);

// To disable a radio button: radioButton1->setEnabled(false);

C++ API reference

For details on the radio button API, see the following topic in the Lumberyard UI Extensions C++ API Reference:

• AzQtComponents::RadioButton

Relevant Qt documentation includes the following topics:

• QRadioButton Class

Lumberyard UI reﬂected property editor

A reﬂected property editor automatically lays out controls for user-editable properties that are reﬂected using the edit context. It is frequently used as a content widget to populate card (p. 18) components.

For more information about reﬂecting and the edit context, see the Lumberyard User Guide topic on Reﬂecting a Component for Serialization and Editing.

Version 1.28 45 Amazon Lumberyard UI Extensions Guide Reﬂected property editor in a card

Reﬂected property editor in a card

The following code shows how to add a simple reﬂected property editor to a card, like the one pictured in the image at the beginning of this topic.

For a complete working example, which demonstrates the concepts of edit context and reﬂection, see the Reﬂected Property Editor page in the Control gallery tool (p. 2), and browse the source code for that page. This can be found in your Lumberyard dev directory: Code\Framework\AzQtComponents \AzQtComponents\Gallery\ReflectedPropertyEditorPage.cpp.

Example

#include #include #include #include

// Create a card component and set its title and header icon. AzQtComponents::Card* card = new AzQtComponents::Card(parent); card->setTitle(QStringLiteral("Card")); card->header()->setIcon(QIcon(QStringLiteral(":/Gallery/Grid-small.svg")));

// Create a reflected property editor. auto cardPropertyEditor = aznew AzToolsFramework::ReflectedPropertyEditor(card);

// Add the reflected property editor to the card as a content widget. card->setContentWidget(cardPropertyEditor);

Lumberyard UI scrollbar styles

Lumberyard provides several style choices for your scrollbars. With the default style, the scrollbar is always visible. However, you have the option to set the scrollbar display mode so that it only appears when users hover over the scroll area.

Additionally, in 1.26, you can apply a dark style to the scrollbar to make it more visible on light backgrounds.

The following examples demonstrate how to apply these styles.

Version 1.28 46 Amazon Lumberyard UI Extensions Guide Scrollbar display modes

Scrollbar display modes

Use AzQtComponents::ScrollBar::setDisplayMode to set the scrollbar display mode. The default mode is AlwaysShow. Example

#include #include using namespace AzQtComponents;

// Use a scroll area that was created earlier in your code or .ui file. QScrollArea* scrollArea;

// Set the scrollbar to appear only when users hover over the scroll area. ScrollBar::setDisplayMode(scrollArea, ScrollBar::ScrollBarMode::ShowOnHover);

// Set it back to default so that it always appears. ScrollBar::setDisplayMode(scrollArea, ScrollBar::ScrollBarMode::AlwaysShow); Scrollbar with dark style

Use AzQtComponents::ScrollBar::applyDarkStyle to make the scrollbar more visible on light backgrounds.

ScrollBar::applyLightStyle reverts the scrollbar back to the default style. Example

#include

Version 1.28 47 Amazon Lumberyard UI Extensions Guide C++ API reference

#include

// Use a scroll area that was created earlier in your code or .ui file. QScrollArea* scrollArea;

// Set the scrollbar style to dark, to make the scrollbar more visible on light backgrounds. AzQtComponents::ScrollBar::applyDarkStyle(scrollArea);

// Revert the scrollbar style back to the default light style. AzQtComponents::ScrollBar::applyLightStyle(scrollArea); C++ API reference

For details on the scrollbar API, see the following topic in the Lumberyard UI Extensions C++ API Reference:

• AzQtComponents::ScrollBar

Relevant Qt documentation includes the following topics:

• QScrollArea Class

Lumberyard UI sliders

Use a slider to enable users to control a variable by moving a knob or lever horizontally or vertically. The visual feedback shows users where the current value is within the range of valid values.

Slider

The basic slider is a styled version of the QSlider widget from the Qt library.

Use the SliderInt class for signed integer values, and the SliderDouble class for double values.

Slider combo

A slider combo is a combination of the slider and spinbox widgets. In practice, sliders can be difficult for the user to manipulate with precision. Therefore, it is recommended that for fine control, you use a slider combo, which combines the visual feedback of the slider with the precise fine-tuning capability of the spinbox.

Version 1.28 48 Amazon Lumberyard UI Extensions Guide Usage guidelines

Use the SliderCombo class for signed integer values, and the SliderDoubleCombo class for double values. Usage guidelines

Follow these guidelines as you design your UI with sliders:

1. Sliders work best when the specific value does not matter to the user, and an approximate value is good enough. Example: selecting a volume or defining the color gradient. 2. When placing a slider control on the UI, it’s best to show the outcome side by side with the control, so a user can review and confirm if the value they select matches their expectation.

Avoid these design choices when using sliders:

• Don’t use the slider when picking an exact value is important to the goal of the interface. • Don’t use the slider if you don’t have the start and end value for your use case. Use the number edit input box instead.

Basic slider with midpoint

The following example demonstrates the creation of a simple, integer slider using the optional midpoint style.

Example

#include

// Create a new integer slider widget. AzQtComponents::SliderInt* sliderInt = new AzQtComponents::SliderInt(parent);

// Set its range from -10 to 10 and its initial value to 2. sliderInt->setRange(-10, 10); sliderInt->setValue(2);

// Apply the optional midpoint style to visually represent the midpoint along the slider. AzQtComponents::Slider::applyMidPointStyle(sliderInt);

// Use setEnabled to disable a slider. sliderInt->setEnabled(false); Slider with tooltip

Add a tooltip to provide context for the value in the slider.

Example

#include

Version 1.28 49 Amazon Lumberyard UI Extensions Guide Basic slider combo

sliderInt->setToolTipFormatting("Opacity", "%"); Basic slider combo

The following example demonstrates the creation of a double slider combo.

Example

#include

// Create a new integer slider widget. SliderDoubleCombo* sliderDoubleCombo = new SliderDoubleCombo(parent);

// Set the range of the slider from 0.0 to 100.0. sliderDoubleCombo->setSoftRange(0.0, 100.0);

// Set the initial value shown in the input box and the slider to 75.0. sliderDoubleCombo->setValue(75.0);

// (Optional) Set the range of valid values for the input box. // While the slider can adjust the value between the min and max of the soft range, // the min and max of the range determine what can be entered in the input box. sliderDoubleCombo->setRange(-1.0, 100.0); C++ API reference

For details on the slider API’s, see the following topic in the Lumberyard UI Extensions C++ API Reference:

Slider:

• AzQtComponents::Slider • AzQtComponents::SliderInt • AzQtComponents::SliderDouble

Slider combo:

• AzQtComponents::SliderCombo • AzQtComponents::SliderDoubleCombo

Relevant Qt documentation includes the following topics:

• QSlider Class

Lumberyard UI styled dock widget

Use styled dock widgets in conjunction with DockMainWindow and FancyDocking components to create the custom docking solution in Lumberyard called "fancy docking", which provides users with a variety of options for arranging their window layout.

Fancy docking provides four docking drop zones around the edge of a target, and one in the center that’s used to dock a window as a tabbed pane. Dragging a window or toolbar over an interface element or the edges of the window causes docking targets to appear to show you where you can dock. You can dock

Version 1.28 50 Amazon Lumberyard UI Extensions Guide Styled dock windows relative to any open pane, whether it is already docked, ﬂoating as a tab, or split in a column or row. To learn more fancy docking features and controls, see Customizing Lumberyard Editor.

Version 1.28 51 Amazon Lumberyard UI Extensions Guide Styled dock

Version 1.28 52 Amazon Lumberyard UI Extensions Guide Fancy docking using the styled dock widget

Fancy docking using the styled dock widget

Fancy docking can use up to ﬁve styled dock widgets added to a DockMainWindow. Setup involves the following implementation steps:

1. Construct a main window using AzQtComponents::DockMainWindow. 2. Construct a AzQtComponents::FancyDocking component using the main window. 3. Construct a AzQtComponents::StyledDockWidget for each edge and add it to the main window. 4. Construct a AzQtComponents::StyledDockWidget for the center and add it to the main window.

Version 1.28 53 Amazon Lumberyard UI Extensions Guide C++ API reference

For the complete working example pictured in the preceding image, be sure to look at the Styled Dock Widget page in the Control gallery tool (p. 2), and browse the source code for that page. This can be found in your Lumberyard dev directory: Code\Framework\AzQtComponents\AzQtComponents \Gallery\StyledDockWidgetPage.cpp.

The following code shows a simplistic example of the styled dock widget.

Example

#include #include #include

// Construct a main window and apply fancy docking. auto mainWindow = new AzQtComponents::DockMainWindow(this); auto fancyDocking = new AzQtComponents::FancyDocking(mainWindow);

// Add one AzQtComponents::StyledDockWidget per edge. auto leftDockWidget = new AzQtComponents::StyledDockWidget("Left Dock Widget", mainWindow); leftDockWidget->setObjectName(leftDockWidget->windowTitle()); leftDockWidget->setWidget(new QLabel("StyledDockWidget")); mainWindow->addDockWidget(Qt::LeftDockWidgetArea, leftDockWidget); auto topDockWidget = new AzQtComponents::StyledDockWidget("Top Dock Widget", mainWindow); topDockWidget->setObjectName(topDockWidget->windowTitle()); topDockWidget->setWidget(new QLabel("StyledDockWidget")); mainWindow->addDockWidget(Qt::TopDockWidgetArea, topDockWidget); auto rightDockWidget = new AzQtComponents::StyledDockWidget("Right Dock Widget", mainWindow); rightDockWidget->setObjectName(rightDockWidget->windowTitle()); rightDockWidget->setWidget(new QLabel("StyledDockWidget")); mainWindow->addDockWidget(Qt::RightDockWidgetArea, rightDockWidget); auto bottomDockWidget = new AzQtComponents::StyledDockWidget("Bottom Dock Widget", mainWindow); bottomDockWidget->setObjectName(bottomDockWidget->windowTitle()); bottomDockWidget->setWidget(new QLabel("StyledDockWidget")); mainWindow->addDockWidget(Qt::BottomDockWidgetArea, bottomDockWidget);

QWidget* centralWidget = new QWidget; QVBoxLayout* vl = new QVBoxLayout(centralWidget); vl->addWidget(new QLabel("Central Widget")); mainWindow->setCentralWidget(centralWidget);

C++ API reference

For details on the styled dock API and other components related to fancy docking, see the following topics in the Lumberyard UI Extensions C++ API Reference:

• AzQtComponents::StyledDockWidget • AzQtComponents::DockMainWindow • AzQtComponents::FancyDocking

Relevant Qt documentation includes the following topics:

• QDockWidget Class • QMainWindow Class

Version 1.28 54 Amazon Lumberyard UI Extensions Guide Tab

Lumberyard UI tab component

Use tabs to enable users to organize content at a high level, such as switching between views, data sets, or functional aspects of an application.

Tabs are also used in the widget headers. When there is more than one widget docked together, the widget headers are shown as tabs. Users can drag the tab/widget header to move it around and dock it elsewhere.

A tab can also display an action toolbar, where action buttons can be added and removed as needed.

Usage guidelines

Follow these guidelines as you design your UI with tabs:

1. Present tabs as a single row above their associated content. 2. Tab labels should succinctly describe the content within.

Basic tab

Create a simple tab widget with movable, closeable tabs and an action in the action toolbar.

Note that you can also customize the tab action toolbar using the AzQtComponents::TabWidgetActionToolBar class. To do this, you will need to include AzQtComponents/Components/Widgets/TabWidgetActionToolBar.h. You can add your customized toolbar using the tab widget’s setActionToolBar() function.

Example

Version 1.28 55 Amazon Lumberyard UI Extensions Guide C++ API reference

#include #include

// Create the tab widget. AzQtComponents::TabWidget* tabWidget = new AzQtComponents::TabWidget(parent);

// Add tabs to the tab widget. QWidget* tabA = new QWidget(); QWidget* tabB = new QWidget();

tabWidget->addTab(tabA, "Tab A"); tabWidget->addTab(tabB, "Tab B");

// Make the tabs movable. tabWidget->setMovable(true);

// Make the tabs closeable. tabWidget->setTabsClosable(true);

// For the tabs to close, TabCloseRequested signal must be connected. connect(tabWidget, &QTabWidget::tabCloseRequested, tabWidget, &QTabWidget::removeTab);

// Make the action toolbar visible. tabWidget->setActionToolBarVisible();

// Create an action for the action toolbar and add it to the tab widget. QAction* action1 = new QAction(QIcon(":/stylesheet/img/table_error.png"), "Action 1", parent); tabWidget->addAction(action1);

// NOTE: To perform an action when the action button is pressed, you will also need to connect the QAction::triggered signal.

C++ API reference

For details on the tab API’s, see the following topics in the Lumberyard UI Extensions C++ API Reference:

• AzQtComponents::TabWidget • AzQtComponents::TabWidgetActionToolBar

Relevant Qt documentation includes the following topics:

• QTabBar Class • QTabWidget Class

Lumberyard UI table view component

Use the table view component to present multiple columns of structured data in a table format. By default, this component employs sortable columns and "zebra striping" - where the background color of rows alternate - to help you create an easily readable, scannable, and sortable presentation of data.

Version 1.28 56 Amazon Lumberyard UI Extensions Guide Basic table view

Note AzQtComponents::TableView actually derives from QTreeView, not QTableView, to provide more customization over the size of rows. Basic table view

Create a simple logging table view.

For a more complex working example of a table view, view the sample tables on the Table View page in the Control gallery tool (p. 2), then examine the source code for that page found in your Lumberyard dev directory: Code\Framework\AzQtComponents\AzQtComponents\Gallery\TableViewPage.cpp. Note If a table view is combined with a tree view (p. 60), you might need to turn oﬀ zebra striping in one of the widgets using the setAlternatingRowColors(false) function.

Example

#include #include #include #include

// Create a log table model for this example. auto logModel = new AzToolsFramework::Logging::LogTableModel(this);

// Create the table view. auto tableView = new AzQtComponents::TableView(parent);

// Set the model for the table. tableView->setModel(logModel);

// Add a few lines of sample data.

Version 1.28 57 Amazon Lumberyard UI Extensions Guide C++ API reference

logModel->AppendLine( AzToolsFramework::Logging::LogLine( "An informative message for debugging purposes.", "Window", AzToolsFramework::Logging::LogLine::TYPE_MESSAGE, QDateTime::currentMSecsSinceEpoch()));

logModel->AppendLine( AzToolsFramework::Logging::LogLine( "A warning message for things that may not have gone as expected.", "Window", AzToolsFramework::Logging::LogLine::TYPE_WARNING, QDateTime::currentMSecsSinceEpoch()));

logModel->AppendLine( AzToolsFramework::Logging::LogLine( "Critical error message, something went wrong.", "Window", AzToolsFramework::Logging::LogLine::TYPE_ERROR, QDateTime::currentMSecsSinceEpoch()));

C++ API reference

For details on the table view API, see the following topic in the Lumberyard UI Extensions C++ API Reference:

• AzQtComponents::TableView

Relevant Qt documentation includes the following topics:

• QTreeView Class • QAbstractListModel Class

Lumberyard UI toggle switch component

Use a toggle switch to enable users to quickly switch between two states with a minimum of eﬀort. The state will be clearly reﬂected back to them and persisted across sessions.

Version 1.28 58 Amazon Lumberyard UI Extensions Guide Usage guidelines

Usage guidelines

Follow these guidelines as you design your UI with toggle switches:

1. Use the toggle switch when your widget has two binary states, for example: "on/off" or "yes/no". There should be no ambiguity about potential states. 2. Always use the active state of the toggle switch for the affirmative state. Affirmative states are those such as "on", "yes", or "active". Consistency here will help customers better understand at a glance the state of a setting. 3. Even if the active state always means "on", clearly indicate the consequences of the switch.

Avoid these design choices when using toggle switches:

• Don’t use when the options presented to the user are not binary. For example, if a mail setting has IMAP and POP as the two mail retrieval options, use a radio group instead. In this example there are actually four states - IMAP on, IMAP off, POP on, and POP off. • Don’t use if the state does not persist or get serialized across sessions. For example, don’t use for search filters, since filters are reset each time a user performs a new search.

Version 1.28 59 Amazon Lumberyard UI Extensions Guide Basic toggle switch

Basic toggle switch

Toggle switches are implemented using the QCheckBox Qt class. The toggle switch style is then applied using the static function, AzQtComponents::CheckBox::applyToggleSwitchStyle().

Example

#include #include

// Apply the toggle switch style to a QCheckBox. QCheckBox* toggleSwitch = new QCheckBox(parent); AzQtComponents::CheckBox::applyToggleSwitchStyle(toggleSwitch);

// To set the switch to the "on" state: toggleSwitch->setChecked(true);

// To set the switch to the "off" state: toggleSwitch->setChecked(false);

// To disable the toggle switch: toggleSwitch->setEnabled(false);

C++ API reference

For details on the checkbox API used to style a toggle switch, see the following topic in the Lumberyard UI Extensions C++ API Reference:

• AzQtComponents::CheckBox

Relevant Qt documentation includes the following topics:

• QCheckBox Class

Related links

For additional information related to the toggle switch component, see the following topics:

• Checkbox (p. 24)

Lumberyard UI tree view component

With the tree view component, users can navigate ﬁle system directories or a list of hierarchical data in Lumberyard. Each item, such as a node or a branch, can have sub-items. Items can be expanded to reveal sub-items.

The tree view component is often used in the following scenarios:

Version 1.28 60 Amazon Lumberyard UI Extensions Guide Usage guidelines

• Show system or predeﬁned contents, such as the settings in Inspector or system settings page. • Show user created contents, such as in File Directory or Outliner.

Example from Lumberyard Asset Browser:

Usage guidelines

Follow these guidelines as you design your UI with tree views:

1. When the tree hierarchy is anticipated to be deep, such as a tree view used in ﬁle directories, it is suggested to add a ﬁle path to help users know where they are in the path.

Version 1.28 61 Amazon Lumberyard UI Extensions Guide Basic tree view

Basic tree view

Create a simple tree view, with support for showing branch lines.

For a working example of a tree view, using the model shown in the preceding image, view the Tree View page in the Control gallery tool (p. 2), then examine the source code for that page found in your Lumberyard dev directory: Code\Framework\AzQtComponents\AzQtComponents\Gallery \TreeViewPage.cpp.

Example

#include #include

// Create the tree view. auto treeView = new QTreeView(parent);

// Set the model on the tree. treeView->setModel(new MyModel);

// Set a BranchDelegate to support branch lines in your tree view. treeView->setItemDelegate(new AzQtComponents::BranchDelegate());

// Show the connecting branch lines.

Version 1.28 62 Amazon Lumberyard UI Extensions Guide C++ API reference

AzQtComponents::TreeView::setBranchLinesEnabled(treeView, true); C++ API reference

For details on the tree view API, see the following topic in the Lumberyard UI Extensions C++ API Reference:

• AzQtComponents::TreeView

Relevant Qt documentation includes the following topics:

• QTreeView Class • QAbstractListModel Class

Version 1.28 63 Amazon Lumberyard UI Extensions Guide Component icons

Lumberyard UI assets

Browse the library of icons used in the Lumberyard development environment in the following pages.

If you’re looking for specific Lumberyard icon asset files, this Lumberyard file directory is a good place to start: dev\Code\Framework\AzQtComponents\AzQtComponents\Components\img\.

Lumberyard component icons

This page contains an organized collection of icons currently used by Lumberyard component cards. Use the following chart to help you ﬁnd an icon.

The component icons have been categorized into color categories to help you understand which content segment they belong to. Not all of our icons will be posted here, however if you need a new one or are looking for an icon resource that is not here, please reach out to [email protected] and we will get back to you promptly.

Please note that all component icons need to fit within one of the 14 component categories. When requesting an icon, indicate which category your new icon should belong to. If your feature creates an entirely new category, consult with the Lumberyard UX team to find color variations that fit within the color schema.

Version 1.28 64 Amazon Lumberyard UI Extensions Guide Component icons

Version 1.28 65 Amazon Lumberyard UI Extensions Guide Entity outliner icons

Lumberyard entity outliner icons

This page contains an organized collection of icons currently used in the Lumberyard Entity Outliner. Use the following charts to help you ﬁnd an icon.

Version 1.28 66 Amazon Lumberyard UI Extensions Guide Entity outliner icons

Version 1.28 67 Amazon Lumberyard UI Extensions Guide Entity outliner icons

Version 1.28 68 Amazon Lumberyard UI Extensions Guide

Lumberyard UI Extensions C++ API Reference index

This table lists the available C++ classes for working with the Lumberyard UI 2.0 system to extend the editor and tools. The C++ API reference is hosted outside of the user guide, so use this index to quickly ﬁnd what you need to look up on the external site. Each class is also accompanied by a brief description.

A complete guide to the UI API can be found in the Lumberyard UI Extensions C++ API Reference. The custom Qt widget library includes the following components:

Class Description

AssetBrowserFolderPage

AzQtComponents::AssetFolderListView

AzQtComponents::AssetFolderThumbnailView

AzQtComponents::AutoCustomWindowDecorations

AzQtComponents::AutoSettingsGroup

AzQtComponents::AzMessageBox

AzQtComponents::BranchDelegate

AzQtComponents::BreadCrumbs

AzQtComponents::BrowseEdit A widget combining a Line Edit and a Push Button. Use this widget when you want to extend a Line Edit with support for user interaction.

AzQtComponents::ButtonDivider

AzQtComponents::ButtonStripe

AzQtComponents::Card

AzQtComponents::CardHeader

AzQtComponents::CardNotiﬁcation

AzQtComponents::CheckBox

AzQtComponents::ColorComponentEdit

AzQtComponents::ColorGrid

AzQtComponents::ColorHexEdit

AzQtComponents::ColorLabel

AzQtComponents::ColorPreview

AzQtComponents::ColorRGBAEdit

AzQtComponents::ColorValidator

Version 1.28 69 Amazon Lumberyard UI Extensions Guide

Class Description

AzQtComponents::ColorWarning

AzQtComponents::ComboBox

AzQtComponents::ComboBoxValidator

AzQtComponents::ConﬁgHelpers::GroupGuard

AzQtComponents::CustomSlider

AzQtComponents::DockBar

AzQtComponents::DockBarButton

AzQtComponents::DockMainWindow

AzQtComponents::DockTabBar

AzQtComponents::DockTabWidget

AzQtComponents::DoubleSpinBox

AzQtComponents::DragAndDrop

AzQtComponents::DragAndDropContextBase

AzQtComponents::DragAndDropEvents

AzQtComponents::EditorProxyStyle

AzQtComponents::ElidingLabel

AzQtComponents::Eyedropper

AzQtComponents::FancyDocking

AzQtComponents::FancyDockingDropZoneState

AzQtComponents::FancyDockingDropZoneWidget

AzQtComponents::FancyDockingGhostWidget

AzQtComponents::FilteredSearchItemDelegate

AzQtComponents::FilteredSearchWidget

AzQtComponents::FilterCriteriaButton

AzQtComponents::GammaEdit

AzQtComponents::GlobalEventFilter

AzQtComponents::GradientSlider

AzQtComponents::HelpButton

AzQtComponents::HueSaturationValidator

AzQtComponents::HSLSliders

AzQtComponents::HSVSliders

Version 1.28 70 Amazon Lumberyard UI Extensions Guide

Class Description

AzQtComponents::InteractiveWindowGeometryChan ger

AzQtComponents::InteractiveWindowMover

AzQtComponents::InteractiveWindowResizer

AzQtComponents::Internal::AddSwatch

AzQtComponents::Internal::ColorController

AzQtComponents::Internal::OverlayWidgetLayer

AzQtComponents::LineEdit Class to handle styling and painting of QLineEdit widgets.

AzQtComponents::LogicalTabOrderingWidget

AzQtComponents::LumberyardStylesheet

AzQtComponents::Menu Class to handle styling and painting of QMenu controls.

AzQtComponents::MouseHider

AzQtComponents::OverlayWidget

AzQtComponents::Palette

AzQtComponents::PaletteCard

AzQtComponents::PaletteCardBase

AzQtComponents::PaletteCardCollection

AzQtComponents::PaletteView

AzQtComponents::ProgressBar

AzQtComponents::PushButton Class to handle styling and painting of QPushButton controls.

AzQtComponents::QuickPaletteCard

AzQtComponents::RadioButton Class to handle styling and painting of radio button controls.

AzQtComponents::RepolishMinimizer

AzQtComponents::RGBALowRangeValidator

AzQtComponents::RGBColorValidator

AzQtComponents::RGBSliders

AzQtComponents::ScreenGrabber

AzQtComponents::ScrollBar

AzQtComponents::SearchLineEdit

AzQtComponents::SearchTypeSelector

Version 1.28 71 Amazon Lumberyard UI Extensions Guide

Class Description

AzQtComponents::SegmentBar A control used to switch between diﬀerent sections of associated information.

AzQtComponents::SegmentControl

AzQtComponents::ShortcutDispatchTraits

AzQtComponents::Slider

AzQtComponents::SliderCombo

AzQtComponents::SliderDouble

AzQtComponents::SliderDoubleCombo

AzQtComponents::SliderInt

AzQtComponents::SpinBox

AzQtComponents::StatusBar

AzQtComponents::Style

AzQtComponents::StyledBusyLabel

AzQtComponents::StyledDetailsTableModel

AzQtComponents::StyledDetailsTableModel::TableEn try

AzQtComponents::StyledDetailsTableView

AzQtComponents::StyledDialog

AzQtComponents::StyledDockWidget

AzQtComponents::StyledDoubleSpinBox

AzQtComponents::StyledLineEdit

AzQtComponents::StyledSliderPrivate

AzQtComponents::StyledSpinBox

AzQtComponents::StylesheetPreprocessor

AzQtComponents::Style::DrawWidgetSentinel

AzQtComponents::StyleManager

AzQtComponents::StyleSheetCache

AzQtComponents::Swatch

AzQtComponents::TableView

AzQtComponents::TableViewItemDelegate

AzQtComponents::TableViewModel

AzQtComponents::TabBar

Version 1.28 72 Amazon Lumberyard UI Extensions Guide

Class Description

AzQtComponents::TabWidget

AzQtComponents::TabWidgetActionToolBar

AzQtComponents::TabWidgetActionToolBarContaine r

AzQtComponents::TagSelector

AzQtComponents::TagWidget

AzQtComponents::TagWidgetContainer

AzQtComponents::Text

AzQtComponents::TitleBar

AzQtComponents::TitleBarOverdrawHandler

AzQtComponents::TitleBarOverdrawHandlerWindow s

AzQtComponents::TitleBarOverdrawScreenHandler

AzQtComponents::ToolBar

AzQtComponents::ToolBarArea

AzQtComponents::ToolButton Class to handle styling and painting of QToolButton controls.

AzQtComponents::ToolButtonComboBox

AzQtComponents::ToolButtonLineEdit

AzQtComponents::ToolButtonWithWidget

AzQtComponents::TreeView

AzQtComponents::VectorEdit

AzQtComponents::VectorEditElement

AzQtComponents::VectorElement All ﬂexible vector GUI’s are constructed using a number vector elements. Each Vector element contains a label and a double spin box which show the label and the value respectively.

AzQtComponents::VectorInput Qt Widget that control holds an array of VectorElements. This control can be used to display any number of labeled ﬂoat values with conﬁgurable row(s) & column(s)

AzQtComponents::ViewportDragContext

AzQtComponents::WindowDecorationWrapper

BreadCrumbsPage

BrowseEditPage

ButtonPage

Version 1.28 73 Amazon Lumberyard UI Extensions Guide

Class Description

CardPage

CheckBoxPage

ColorLabelPage

ColorPickerPage

ComboBoxPage

ComponentDemoWidget

ConditionGroupWidget

ConditionWidget

DeploymentsWidget

DragAndDropPage

FilteredSearchWidgetPage

FixedStateButton

GalleryComponent

GradientSliderPage

HyperlinkPage

LevelOne

LevelThree

LevelTwo

LineEditPage

MainWidget

MenuPage

MyComboBox

ProgressIndicatorPage

RadioButtonPage

ReﬂectedPropertyEditorPage

ScopedCleanup

ScrollBarPage

SegmentControlPage

SliderComboPage

SliderPage

SpinBoxPage

Version 1.28 74 Amazon Lumberyard UI Extensions Guide

Class Description

SplitterPage

StyledDockWidgetPage

StyleSheetPage

SvgLabelPage

TableViewPage

TabWidgetPage

TitleBarPage

ToggleSwitchPage

ToolBarPage

TreeViewPage

TypographyPage

ViewportTitleDlg

Version 1.28 75