8 ![ ](../assets/img/popup/popup-example.png) ![ ](./popup-example.png)
10 ## Description {#popupdescription}
12 The Popup control provides a generic way of displaying modal content.
14 The content is displayed until it is dismissed by hiding the Popup.
16 While the Popup is visible, it is displayed within a layer that is placed above any other actors.
18 Content behind the Popup is dimmed by default, although this is configurable.
21 ## Contents {#popupcontents}
24 The Popup is designed to be generic, but provide the necessary layout functionality to achieve this.
26 The Popup window is broken down into the following areas:
28 PopupBackgroundImage: This is the frame that appears around the edge of the Popup.
30 Within the Popup there are three main fields:
36 ![ ](../assets/img/popup/popup-fields.png) ![ ](./popup-fields.png)
38 Each field can contain any Actor.
40 Note: All actor properties are optional, allowing any combination of content areas.
41 Example: Image only popup (using the content field):
42 ![ ](../assets/img/popup/popup-image-content.png) ![ ](./popup-image-content.png)
44 ### Example content: {#popupfieldexample}
47 - Content: ImageView or TextLabel
48 - Footer: PushButton or Actor containing two PushButtons
50 ## Setting and getting the display state {#popupdisplaystate}
52 The popup will not be shown immediately upon parenting it / adding it to the stage. First the display state must be set.
53 The display state is represented by the property DISPLAY_STATE. It can be set with SHOWN and HIDDEN to show or hide the Popup.
54 However, when getting the state, you will also be told if the Popup is in the process of SHOWING or HIDING.
56 | Value | Setting the state | Getting the state |
57 |----------|--------------------------------|--------------------------------|
58 | SHOWN | Show the popup | The popup is fully shown |
59 | HIDDEN | Hide the popup | The popup is fully hidden |
60 | SHOWING | | The popup is transitioning in |
61 | HIDING | | The popup is transitioning out |
64 ## Signals {#popupsignals}
66 ### Display State Signals {#popupdisplaystatesignals}
68 All four state changes cause notifications via four respective signals that can be connected to.
70 ### OutsideTouched Signal {#popupoutsidetouched}
72 This signal is emitted whenever a touch is received outside of the popups area.
73 This is typically used to hide / dismiss the popup, but can be ignored if it is desired to force the user to make a selection using the controls within the Popup.
76 ## Transition effects {#popuptransitioneffects}
78 The Popup object has built-in transitional animation effects.
79 These can be user-defined by setting ANIMATION_MODE to CUSTOM, and setting the ENTRY_ANIMATION and
80 EXIT_ANIMATION properties accordingly.
82 The default to fading in and out.
85 ## Types of Popup {#popuptypes}
87 The Popup can be configured to a preset type by using named types within the type-registry.
89 These types are modifications / specialisations of a Popup. They provide the library user with a shortcut way of creating a specific type of Popup.
92 The Popup control features a "Toast" popup type. This is a Popup that appears at the bottom of the screen, typically with some text. They are normally for informational purposes only.
95 ### Key differences of the Toast popup {#popuptoastdifferences}
97 - The Popup will auto-hide itself after a few seconds.
98 - It is touch-transparent. This means touch events go through the Popup to Actors below, giving it non-modal behaviour.
99 - The backing is not dimmed. This allows the user to continue their actions without distraction.
101 Note: All the above features can be set or unset manually on the Popup control if desired.
103 Popup types can be created with the TypeRegistry (as they are not separate classes).
106 ### Example: {#popuptoastexample}
108 ![ ](../assets/img/popup/popup-toast.png) ![ ](./popup-toast.png)
110 Here is the code to produce the above example:
114 TypeInfo typeInfo = TypeRegistry::Get().GetTypeInfo( "PopupToast" );
117 BaseHandle baseHandle = typeInfo.CreateInstance();
120 Toolkit::Popup popup = Toolkit::Popup::DownCast( baseHandle );
121 popup.SetTitle( Toolkit::TextLabel::New( "This is a Toast Popup.\nIt will auto-hide itself" ) );
122 Stage::GetCurrent().Add( popup );
123 popup.SetDisplayState( Toolkit::Popup::SHOWN );
129 ## Contextual Mode {#popupcontextualmode}
131 Contextual Mode allows the popup can appear adjacent to it's parent in screen space.
133 If disabled, the Popup will ignore it's parent and appear centered on the stage (user positioning can override this).
135 If enabled, the contextual mode can be set to four directions. The Popup will be made adjacent on the selected axis.
139 myPopup.SetProperty( Toolkit::Popup::Properties::CONTEXTUAL_MODE, "BELOW" );
142 Will make the top of the Popup appear just below the bottom of the parent object (plus a margin).
144 The default is: NON_CONTEXTUAL which means no layout or positioning is performed.
146 | ContextualMode | Layout |
147 |-------------------|---------------------------------------------------------|
148 | NON_CONTEXTUAL | No contextual layout is performed |
149 | ABOVE | Popup is above vertically, centered horizontally |
150 | RIGHT | Popup is to the right horizontally, centered vertically |
151 | BELOW | Popup is below vertically, centered horizontally |
152 | LEFT | Popup is to the left horizontally, centered vertically |
155 ## Properties {#popupproperties}
157 Various properties provide more configuration on the Popup's styling.
159 This is a breakdown of remaining properties not described in detail above.
162 | Property | Type | Description |
163 |------------------------|---------|--------------------------------------------------------------------------|
164 | TOUCH_TRANSPARENT | bool | If true, allow touch events to travel through the popup. |
165 | TAIL_VISIBILITY | bool | If true, display a tail image on one of the edges of the popup. |
166 | TAIL_POSITION | Vector3 | Describes the position of the tail image. Orientation is inferred. |
167 | ANIMATION_DURATION | float | Duration used for entry and exit transition animations. |
168 | AUTO_HIDE_DELAY | int | If non-zero, the number of milliseconds before the popup will auto-hide. |
169 | BACKING_ENABLED | bool | True if backing (dimmed background) is enabled. |
170 | BACKING_COLOR | Vector4 | The color of the dimmed background. |
171 | TAIL_UP_IMAGE | string | The image to use for the tail if above the popup. |
172 | TAIL_DOWN_IMAGE | string | The image to use for the tail if below the popup. |
173 | TAIL_LEFT_IMAGE | string | The image to use for the tail if to the left of the popup. |
174 | TAIL_RIGHT_IMAGE | string | The image to use for the tail if to the right of the popup. |
177 # ConfirmationPopup Control {#popupconfirmation}
179 The ConfirmationPopup control provides a simple interface for providing automatic connection to control signals for common-use Popup use-cases.
181 ConfirmationPopup will automatically provide signals for 1 or 2 controls.
182 Note: The controls do not need to be PushButtons.
183 These signals are dynamically created. The controls (typically PushButtons) must be specifially named so the ConfirmationPopup can locate them.
185 ## Step 1 {#popupconfirmationstep1}
188 - Name your first control, or OK control: "controlOk"
189 - Name your second control, or Cancel control: "controlCancel"
191 ## Step 2 {#popupconfirmationstep2}
192 Tell the ConfirmationPopup the names of the signals to connect to for each control.
193 For example, if we are using PushButtons as controls, the signal name would be "clicked".
194 This allows us to use different control types.
196 - Set property "connectSignalOkSelected" with the name of the signal to connect to within the first control.
197 - Set property "connectSignalCancelSelected" with the name of the signal to connect to within the second control.
199 ## Step 3 {#popupconfirmationstep3}
200 Connect to the following respective signals within ConfirmationPopup:
202 - Connect to signal "controlSignalOk" to be signalled for the first control.
203 - Connect to signal "controlSignalCancel" to be signalled for the second control.
205 The ConfirmationPopup will dynamically make the connection between the signalling control, and your signal handler.
207 This allows connection of signals within both C++, JSON and Javascript APIs.
208 If more manual control or customisable layout is needed, then it is recommended to use the Popup widget directly for full control.
210 The JSON code example at the bottom of this document uses the ConfirmationPopup to allow signal connection from within the JSON description.
213 # C++ example of a Popup with two buttons {#popupexamplec}
215 This example creates a Popup with:
219 - Footer: ImageView (an image border around the buttons)
220 - PushButton (OK control)
221 - PushButton (Cancel control)
223 The example connects signals to the two buttons, and to the OutsideTouched signal.
226 Toolkit::Popup popup = Toolkit::Popup::New();
228 Toolkit::TextLabel titleActor = Toolkit::TextLabel::New( "Title" );
229 titleActor.SetProperty( Toolkit::TextLabel::Property::TEXT_COLOR, Color::WHITE );
230 titleActor.SetProperty( Toolkit::TextLabel::Property::HORIZONTAL_ALIGNMENT, "CENTER" );
231 popup.SetTitle( titleActor );
233 Toolkit::TextLabel contentActor = Toolkit::TextLabel::New( "Content text" );
234 contentActor.SetProperty( Toolkit::TextLabel::Property::TEXT_COLOR, Color::WHITE );
235 contentActor.SetProperty( Toolkit::TextLabel::Property::MULTI_LINE, true );
236 contentActor.SetProperty( Toolkit::TextLabel::Property::HORIZONTAL_ALIGNMENT, "CENTER" );
237 popup.SetContent( contentActor );
239 // Create the footer: Two buttons surrounded by an image.
240 ImageView footer = ImageView::New( DEFAULT_CONTROL_AREA_IMAGE_PATH );
241 footer.SetResizePolicy( ResizePolicy::FILL_TO_PARENT, Dimension::WIDTH );
242 footer.SetResizePolicy( ResizePolicy::FIXED, Dimension::HEIGHT );
243 footer.SetSize( 0.0f, 80.0f );
244 footer.SetAnchorPoint( AnchorPoint::CENTER );
245 footer.SetParentOrigin( ParentOrigin::CENTER );
247 Toolkit::PushButton okButton = Toolkit::PushButton::New();
248 okButton.SetLabelText( "OK" );
249 okButton.SetParentOrigin( ParentOrigin::CENTER );
250 okButton.SetAnchorPoint( AnchorPoint::CENTER );
251 okButton.SetResizePolicy( ResizePolicy::SIZE_FIXED_OFFSET_FROM_PARENT, Dimension::ALL_DIMENSIONS );
252 okButton.SetSizeModeFactor( Vector3( -20.0f, -20.0f, 0.0 ) );
253 okButton.ClickedSignal().Connect( this, &MyExample::OnOKButtonClicked );
255 Toolkit::PushButton cancelButton = Toolkit::PushButton::New();
256 cancelButton.SetLabelText( "Cancel" );
257 cancelButton.SetParentOrigin( ParentOrigin::CENTER );
258 cancelButton.SetAnchorPoint( AnchorPoint::CENTER );
259 cancelButton.SetResizePolicy( ResizePolicy::SIZE_FIXED_OFFSET_FROM_PARENT, Dimension::ALL_DIMENSIONS );
260 cancelButton.SetSizeModeFactor( Vector3( -20.0f, -20.0f, 0.0 ) );
261 cancelButton.ClickedSignal().Connect( this, &MyExample::OnCancelButtonClicked );
263 // Set up the footer's layout.
264 Toolkit::TableView controlLayout = Toolkit::TableView::New( 1, 2 );
265 controlLayout.SetParentOrigin( ParentOrigin::CENTER );
266 controlLayout.SetAnchorPoint( AnchorPoint::CENTER );
267 controlLayout.SetResizePolicy( ResizePolicy::FILL_TO_PARENT, Dimension::ALL_DIMENSIONS );
268 controlLayout.SetCellPadding( Size( 10.0f, 10.0f ) );
269 controlLayout.SetRelativeWidth( 0, 0.5f );
270 controlLayout.SetRelativeWidth( 1, 0.5f );
271 controlLayout.SetCellAlignment( Toolkit::TableView::CellPosition( 0, 0 ), HorizontalAlignment::CENTER, VerticalAlignment::CENTER );
272 controlLayout.SetCellAlignment( Toolkit::TableView::CellPosition( 0, 1 ), HorizontalAlignment::CENTER, VerticalAlignment::CENTER );
273 controlLayout.AddChild( okButton, Toolkit::TableView::CellPosition( 0, 0 ) );
274 controlLayout.AddChild( cancelButton, Toolkit::TableView::CellPosition( 0, 1 ) );
275 footer.Add( controlLayout );
276 popup.SetFooter( footer );
278 popup.OutsideTouchedSignal().Connect( this, &MyExample::OnPopupOutsideTouched );
280 // Add to stage (the popup is still invisible at this point).
281 Stage::GetCurrent().Add( popup );
283 // Display the popup.
284 mPopup.SetDisplayState( Toolkit::Popup::SHOWN );
288 # JSON example of a Popup with two buttons {#popupexamplejson}
290 This example creates a Popup with:
295 - PushButton (OK control)
296 - PushButton (Cancel control)
298 The example connects signals to the two buttons, and to the OutsideTouched signal.
299 This time without an image around the buttons. This could be added in the same way as the C++ example however.
305 "CONFIG_SCRIPT_LOG_LEVEL": "Verbose"
309 "type": "ConfirmationPopup",
310 "name": "confirmationPopup",
311 "parentOrigin": [0.5, 0.55, 0.5],
312 "anchorPoint": "CENTER",
313 "widthResizePolicy": "SIZE_RELATIVE_TO_PARENT",
314 "heightResizePolicy": "USE_NATURAL_SIZE",
315 "sizeModeFactor": [0.65, 1.0, 1.0],
316 "tailVisibility": false,
317 "displayChangeAnimationDuration": 1.0,
318 "contextualMode": "NON_CONTEXTUAL",
319 "animationMode": "ZOOM",
320 "connectSignalOkSelected": "clicked",
321 "connectSignalCancelSelected": "clicked",
324 "text": "Title text",
325 "textColor": [1, 1, 1, 1]
329 "text": "Content text",
330 "padding": [20, 20, 20, 0],
331 "textColor": [1, 1, 1, 1]
336 "widthResizePolicy": "FILL_TO_PARENT",
337 "heightResizePolicy": "FIXED",
338 "parentOrigin": "CENTER",
339 "anchorPoint": "CENTER",
342 "type": "PushButton",
344 "parentOrigin": "CENTER_LEFT",
345 "anchorPoint": "CENTER_LEFT",
346 "position": [20, 0, 0],
351 "type": "PushButton",
352 "name": "controlCancel",
353 "parentOrigin": "CENTER_RIGHT",
354 "anchorPoint": "CENTER_RIGHT",
355 "position": [-20, 0, 0],
357 "labelText": "Cancel"
363 "name": "controlSignalOk",
365 "actor": "confirmationPopup",
366 "property": "displayState",
370 "name": "controlSignalCancel",
372 "actor": "confirmationPopup",
373 "property": "displayState",
377 "name": "touchedOutside",
379 "actor": "confirmationPopup",
380 "property": "displayState",