You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@royale.apache.org by ca...@apache.org on 2020/08/22 17:26:03 UTC
[royale-docs] branch master updated: jewel view and responsive view
This is an automated email from the ASF dual-hosted git repository.
carlosrovira pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/royale-docs.git
The following commit(s) were added to refs/heads/master by this push:
new 6a4d14f jewel view and responsive view
6a4d14f is described below
commit 6a4d14fa409576a10b413ce562b2837ad9d7b3bd
Author: Carlos Rovira <ca...@apache.org>
AuthorDate: Sat Aug 22 19:25:52 2020 +0200
jewel view and responsive view
---
component-sets/jewel.md | 15 ++-
component-sets/jewel/jewel-drawer.md | 4 +-
component-sets/jewel/jewel-responsiveview.md | 166 ++++++++++++++++++++++++++
component-sets/jewel/jewel-view.md | 167 +++++++++++++++++++++++++++
4 files changed, 345 insertions(+), 7 deletions(-)
diff --git a/component-sets/jewel.md b/component-sets/jewel.md
index c3023d1..68b2330 100644
--- a/component-sets/jewel.md
+++ b/component-sets/jewel.md
@@ -58,6 +58,7 @@ If the component name is a link, you can click it to see more information about
| Type | Name | Description | Available SDK | State |
|------------------ |------------------------------------------------------ |--------------------------------------------------------------------------------- |------------------ |-------------- |
| __Containers__ | [Application](component-sets/jewel/application) | The root container of a Jewel Application | 0.9.4 | Complete |
+| | [ApplicationMainContent](component-sets/jewel/applicationmaincontent) | Container for ISelectableContent | 0.9.4 | Complete |
| | [ButtonBar](component-sets/jewel/buttonbar) | Container that displays a series of buttons | 0.9.7 | Complete |
| | [Card](component-sets/jewel/card) | Content (text, images,...) container with optional title and actions zones | 0.9.4 | Complete |
| | [Container](component-sets/jewel/container) | Container that surrounds other components | 0.9.4 | Complete |
@@ -66,13 +67,15 @@ If the component name is a link, you can click it to see more information about
| | [Group](component-sets/jewel/group) | The most simple container that groups other components | 0.9.4 | Complete |
| | [HContainer](component-sets/jewel/hcontainer) | Container that layout other components horizontaly | 0.9.7 | Complete |
| | [HGroup](component-sets/jewel/hgroup) | Group that layout other components horizontaly | 0.9.7 | Complete |
-| | Grid | Container that uses Grid Layout and needs other immediate children to work as cells and host content. | 0.9.4 | Complete |
-| | SimpleTable | A basic HTML table that can be declared in MXML | 0.9.4 | Complete |
-| | Table | A complex HTML table element filled from a data source. Cells are ItemRenderers. | 0.9.4 | In Progress |
+| | [Grid](component-sets/jewel/grid) | Container for responsive layout of childrens. | 0.9.4 | Complete |
+| | [ResponsiveView](component-sets/jewel/responsiveview) | The main view for a responsive Application | 0.9.4 | Complete |
| | TabBarContent | A container to use with TabBar and capable of presenting organized content | 0.9.4 | Complete |
+| | SectionContent | A container to separate content and present to the user | 0.9.4 | Complete |
+| | ScrollableSectionContent | A scrollable container to separate content and present to the user | 0.9.4 | Complete |
| | [VContainer](component-sets/jewel/vcontainer) | Container that layout other components verticaly | 0.9.7 | Complete |
+| | [View](component-sets/jewel/view) | The main view in the Application | 0.9.4 | Complete |
| | [VGroup](component-sets/jewel/vgroup) | Group that layout other components verticaly | 0.9.7 | Complete |
-| | Wizard | 11.0+ | 0.9.4 | Complete |
+| | Wizard | A container that navigates from one content to the next. | 0.9.4 | Complete |
| __Components__ | [Alert](component-sets/jewel/alert) | Displays a message and one or more buttons in a view that pops up over all other controls and views. | 0.9.4 | Complete |
| | [Button](component-sets/jewel/button) | A commonly-used rectangular button with a text label. Users can click or tap it to take an action. | 0.9.4 | Complete |
| | [CheckBox](component-sets/jewel/checkbox) | Consists of a box that can contain a check mark and an optional label. | 0.9.4 | Complete |
@@ -83,6 +86,7 @@ If the component name is a link, you can click it to see more information about
| | DropDownList | | 0.9.4 | Complete |
| | Form | | 0.9.4 | Complete |
| | FormItem | | 0.9.4 | Complete |
+| | HSlider | | 0.9.4 | Complete |
| | Icon | | 0.9.4 | Complete |
| | Image | | 0.9.4 | Complete |
| | [Label](component-sets/jewel/label) | Used for single or multi lined text labels | 0.9.4 | Complete |
@@ -90,9 +94,10 @@ If the component name is a link, you can click it to see more information about
| | NumericStepper | | 0.9.4 | |
| | PopUp | | 0.9.4 | Complete |
| | [RadioButton](component-sets/jewel/radiobutton) | Lets the user make a single choice within a set of mutually exclusive choices | 0.9.4 | Complete |
-| | HSlider | | 0.9.4 | Complete |
| | VSlider | | 0.9.6 | Complete |
| | SnackBar | | 0.9.4 | Complete |
+| | SimpleTable | A basic HTML table that can be declared in MXML | 0.9.4 | Complete |
+| | Table | A complex HTML table element filled from a data source. Cells are ItemRenderers. | 0.9.4 | In Progress |
| | TabBar | | 0.9.4 | Complete |
| | [TextInput](component-sets/jewel/textinput) | A control for single-line text field. | 0.9.4 | Complete |
diff --git a/component-sets/jewel/jewel-drawer.md b/component-sets/jewel/jewel-drawer.md
index b97c2c0..e2cc431 100644
--- a/component-sets/jewel/jewel-drawer.md
+++ b/component-sets/jewel/jewel-drawer.md
@@ -88,11 +88,11 @@ var dc:DrawerContent = new DrawerContent();
// add elements to DrawerContent like Navigation, Divider...
// ...and add the DrawerContent to the Drawer
d.addElement(dc);
-// finally add the Drawer to the parent (usually ApplicationResponsiveView)
+// finally add the Drawer to the parent (usually a ResponsiveView)
parent.addElement(d);
```
-where `parent` is the container where the control will be added. Usually parent is [Jewel ApplicationResponsiveView](https://royale.apache.org/asdoc/index.html#!org.apache.royale.jewel/ApplicationResponsiveView){:target='_blank'}, since Drawers are used on responsive applications.
+where `parent` is the container where the control will be added. Usually parent is [Jewel ResponsiveView](https://royale.apache.org/asdoc/index.html#!org.apache.royale.jewel/ResponsiveView){:target='_blank'}, since Drawers are used on responsive applications.
## Relevant Properties and Methods
diff --git a/component-sets/jewel/jewel-responsiveview.md b/component-sets/jewel/jewel-responsiveview.md
new file mode 100644
index 0000000..e1b2fd9
--- /dev/null
+++ b/component-sets/jewel/jewel-responsiveview.md
@@ -0,0 +1,166 @@
+---
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+layout: docpage
+title: Jewel View
+description: The Jewel View
+permalink: /component-sets/jewel/responsiveview
+---
+[< Jewel Components list](component-sets/jewel)
+
+# Jewel View
+
+## Reference
+
+Available since version __0.9.4__.
+
+| Class | Extends |
+|------------------------------ |---------------------------------- |
+| [org.apache.royale.jewel.ResponsiveView](https://royale.apache.org/asdoc/index.html#!org.apache.royale.jewel/ResponsiveView){:target='_blank'} | [View](https://royale.apache.org/asdoc/index.html#!org.apache.royale.jewel.supportClasses.view/View){:target='_blank'}
+
+<sup>_Note: This component is currently only available for JavaScript._</sup>
+
+## Overview
+
+The ResponsiveView class is the class used as the `initialView` in a responsive Royale Jewel [Application](component-sets/jewel/application). It is generally used as the root tag of __MXML__ documents and UI controls and containers are added to it.
+
+It normaly can host a [TopAppBar](component-sets/jewel/topappbar), [FooterBar](component-sets/jewel/footerbar), [Drawer](component-sets/jewel/drawer) and a [ApplicationMainContent](component-sets/jewel/applicationmaincontent) with other organized content for navigation.
+
+For non responsive applications you can use just a simple [View](component-sets/jewel/view) instead.
+
+## Example of use
+
+In __MXML__ declare a `ResponsiveView` like this:
+
+```mxml
+<j:ResponsiveView xmlns:fx="http://ns.adobe.com/mxml/2009"
+ xmlns:j="library://ns.apache.org/royale/jewel">
+
+ <!-- ResponsiveView code goes here -->
+</j:ResponsiveView>
+```
+
+> ResponsiveView doesn't need to specify `width` and `height` since are sized 100% in both directions by default. In this way we can use the width of the application container to apply responsive rules on any part of the application.
+
+or directly in the application mxml fil inside the `initialView`:
+
+```mxml
+<j:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
+ xmlns:j="library://ns.apache.org/royale/jewel">
+ ...
+ <j:initialView>
+ <j:ResponsiveView>
+ <!-- ResponsiveView code goes here -->
+ </j:ResponsiveView>
+ </j:initialView>
+</j:Application>
+```
+
+In __ActionScript__ we can do the same in the following way:
+
+```as3
+// instantiate the view
+var responsiveView:ResponsiveView = new ResponsiveView();
+// add content to the view and and add to application's initialView
+application.initialView = responsiveView;
+```
+
+where `application` is the Jewel Application.
+
+## Relevant Properties and Methods
+
+> Check the Reference of [org.apache.royale.jewel.ResponsiveView](https://royale.apache.org/asdoc/index.html#!org.apache.royale.jewel/ResponsiveView){:target='_blank'} for a more detailed list of properties and methods.
+
+### Properties
+
+| PROPERTY | Type | Description |
+|----------------------- |--------------| ------------------------------------------------------------------------------------------------------|
+| __applicationModel__ | _Object_ | A reference to the Application's model. |
+| __currentState__ | _String_ | The name of the current state. |
+| __numElements__ | _int_ | The number of element children that can be laid out. |
+| __mxmlContent__ | _Array_ | The array of childs for this view. Is the [DefaultProperty](features/as3/metadata#default-property). |
+| __popUpParent__ | _IPopUpHostParent_ | A view can be the parent of a popup that will be part of the layout. |
+| __popUpHost__ | _IPopUpHost_ | A view can host popups that will be part of the layout. |
+| __states__ | _Array_ | The array of view states. These should be instances of [org.apache.royale.states.State](https://royale.apache.org/asdoc/index.html#!org.apache.royale.states/State){:target='_blank'}|
+
+### Methods
+
+| Method | Parameters |Description |
+|----------------------|----------------------------------------------------------------|-------------------------------------------------------|
+| __addElement__ | c(IChild), dispatchEvent(Boolean=true) | Add a component to the parent. |
+| __addElementAt__ | c(IChild), index(int), dispatchEvent(Boolean=true) | Add a component to the parent at the specified index. |
+| __getElementIndex__ | c(IChild) | Gets the index of this subcomponent. |
+| __getElementAt__ | index(int) | Get a component from the parent at specified index. |
+| __removeElement__ | c(IChild), dispatchEvent(Boolean=true) | Remove a component from the parent. |
+
+## Relevant Events
+
+The most important event is `initComplete`, which indicates that the initialization of the view is complete.
+
+Is needed when some action coded in a callback function need to be triggered as the view is ready to use after initialization.
+
+You can attach callback listeners to the _initComplete_ event in __MXML__ as follows:
+
+```mxml
+<j:ResponsiveView initComplete="initCompleteHandler(event)"/>
+```
+
+the _initComplete_ event will use the `initCompleteHandler` callback function you provide in __ActionScript__:
+
+```mxml
+<fx:Script>
+ <![CDATA[
+ private function initCompleteHandler(event:Event):void {
+ trace("ResponsiveView is ready!");
+ }
+ ]]>
+</fx:Script>
+```
+
+When the view is initialized the message _"ResponsiveView is ready!"_ appears in the console log.
+
+In __ActionScript__ we can add an event handler this way:
+
+```as3
+var rv:ResponsiveView = new ResponsiveView();
+rv.addEventListener('initComplete', initCompleteHandler);
+```
+
+## Relevant Beads
+
+| Bead Type | Implementation | Description |
+|----------------- |------------------------------------------------ |------------------------------------------------ |
+| [GroupView](https://royale.apache.org/asdoc/index.html#!org.apache.royale.html.beads/GroupView){:target='_blank'} | [org.apache.royale.core.IBeadView](https://royale.apache.org/asdoc/index.html#!org.apache.royale.core/IBeadView){:target='_blank'} | This is the default view bead. |
+| [ViewLayout](https://royale.apache.org/asdoc/index.html#!org.apache.royale.jewel.beads.layouts/ViewLayout){:target='_blank'} | [org.apache.royale.core.IBeadLayout](https://royale.apache.org/asdoc/index.html#!org.apache.royale.core/IBeadLayout){:target='_blank'} | This is the default layout bead. |
+
+## Optional Beads
+
+| Bead Type | Implementation | Description |
+|----------------- |------------------------------------------------ |------------------------------------------------ |
+| [ViewDataBinding](https://royale.apache.org/asdoc/index.html#!org.apache.royale.binding/ViewDataBinding){:target='_blank'} | [org.apache.royale.binding.DataBindingBase](https://royale.apache.org/asdoc/index.html#!org.apache.royale.binding/DataBindingBase){:target='_blank'} | Provide binding capabilities to the view. |
+
+## More examples
+
+* [Creating a Hello World in Apache Royale](https://royale.apache.org/creating-a-hello-world-in-apache-royale/){:target='_blank'}
+* [Using the Jewel Alert Control](https://royale.apache.org/using-jewel-alert-control/){:target='_blank'}
+* [Using View States to show or hide content](https://royale.codeoscopic.com/using-view-states-to-show-or-hide-content/){:target='_blank'}
+
+## Related controls {#related-controls}
+
+Other useful Jewel view components are:
+
+* [View](component-sets/jewel/view)
+* [Application](component-sets/jewel/application)
diff --git a/component-sets/jewel/jewel-view.md b/component-sets/jewel/jewel-view.md
new file mode 100644
index 0000000..e28bee3
--- /dev/null
+++ b/component-sets/jewel/jewel-view.md
@@ -0,0 +1,167 @@
+---
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+layout: docpage
+title: Jewel View
+description: The Jewel View
+permalink: /component-sets/jewel/view
+---
+[< Jewel Components list](component-sets/jewel)
+
+# Jewel View
+
+## Reference
+
+Available since version __0.9.4__.
+
+| Class | Extends | Implements |
+|------------------------------ |---------------------------------- |--------------------------------- |
+| [org.apache.royale.jewel.View](https://royale.apache.org/asdoc/index.html#!org.apache.royale.jewel/View){:target='_blank'} | [ViewBase](https://royale.apache.org/asdoc/index.html#!org.apache.royale.jewel.supportClasses.view/ViewBase){:target='_blank'} | [IMXMLDocument](https://royale.apache.org/asdoc/index.html#!org.apache.royale.core/IMXMLDocument){:target='_blank'} |
+
+<sup>_Note: This component is currently only available for JavaScript._</sup>
+
+## Overview
+
+The View class is the class used as the `initialView` in a Royale Jewel [Application](component-sets/jewel/application). It is generally used as the root tag of __MXML__ documents and UI controls and containers are added to it.
+
+For responsive applications you can use [ResponsiveView](component-sets/jewel/responsiveview) instead.
+
+## Example of use
+
+In __MXML__ declare a `View` like this:
+
+```mxml
+<j:View xmlns:fx="http://ns.adobe.com/mxml/2009"
+ xmlns:j="library://ns.apache.org/royale/jewel"
+ width="100%" height="100%">
+
+ <!-- View code goes here -->
+</j:View>
+```
+
+or directly in the application mxml file inside the `initialView`:
+
+```mxml
+<j:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
+ xmlns:j="library://ns.apache.org/royale/jewel">
+ ...
+ <j:initialView>
+ <j:View width="100%" height="100%">
+ <!-- View code goes here -->
+ </j:View>
+ </j:initialView>
+</j:Application>
+```
+
+In __ActionScript__ we can do the same in the following way:
+
+```as3
+// instantiate the view
+var view:View = new View();
+// add content to the view and and add to application's initialView
+application.initialView = view;
+```
+
+where `application` is the Jewel Application.
+
+## Relevant Properties and Methods
+
+> Check the Reference of [org.apache.royale.jewel.View](https://royale.apache.org/asdoc/index.html#!org.apache.royale.jewel/View){:target='_blank'} for a more detailed list of properties and methods.
+
+### Properties
+
+| PROPERTY | Type | Description |
+|----------------------- |--------------| ------------------------------------------------------------------------------------------------------|
+| __applicationModel__ | _Object_ | A reference to the Application's model. |
+| __currentState__ | _String_ | The name of the current state. |
+| __numElements__ | _int_ | The number of element children that can be laid out. |
+| __mxmlContent__ | _Array_ | The array of childs for this view. Is the [DefaultProperty](features/as3/metadata#default-property). |
+| __popUpParent__ | _IPopUpHostParent_ | A view can be the parent of a popup that will be part of the layout. |
+| __popUpHost__ | _IPopUpHost_ | A view can host popups that will be part of the layout. |
+| __states__ | _Array_ | The array of view states. These should be instances of [org.apache.royale.states.State](https://royale.apache.org/asdoc/index.html#!org.apache.royale.states/State){:target='_blank'}|
+
+### Methods
+
+| Method | Parameters |Description |
+|----------------------|----------------------------------------------------------------|-------------------------------------------------------|
+| __addElement__ | c(IChild), dispatchEvent(Boolean=true) | Add a component to the parent. |
+| __addElementAt__ | c(IChild), index(int), dispatchEvent(Boolean=true) | Add a component to the parent at the specified index. |
+| __getElementIndex__ | c(IChild) | Gets the index of this subcomponent. |
+| __getElementAt__ | index(int) | Get a component from the parent at specified index. |
+| __removeElement__ | c(IChild), dispatchEvent(Boolean=true) | Remove a component from the parent. |
+
+## Relevant Events
+
+The most important event is `initComplete`, which indicates that the initialization of the view is complete.
+
+Is needed when some action coded in a callback function need to be triggered as the view is ready to use after initialization.
+
+You can attach callback listeners to the _initComplete_ event in __MXML__ as follows:
+
+```mxml
+<j:View initComplete="initCompleteHandler(event)"/>
+```
+
+the _initComplete_ event will use the `initCompleteHandler` callback function you provide in __ActionScript__:
+
+```mxml
+<fx:Script>
+ <![CDATA[
+ private function initCompleteHandler(event:Event):void {
+ trace("View is ready!");
+ }
+ ]]>
+</fx:Script>
+```
+
+When the view is initialized the message _"View is ready!"_ appears in the console log.
+
+In __ActionScript__ we can add an event handler this way:
+
+```as3
+var v:View = new View();
+v.addEventListener('initComplete', initCompleteHandler);
+```
+
+## Relevant Beads
+
+| Bead Type | Implementation | Description |
+|----------------- |------------------------------------------------ |------------------------------------------------ |
+| [GroupView](https://royale.apache.org/asdoc/index.html#!org.apache.royale.html.beads/GroupView){:target='_blank'} | [org.apache.royale.core.IBeadView](https://royale.apache.org/asdoc/index.html#!org.apache.royale.core/IBeadView){:target='_blank'} | This is the default view bead. |
+| [ViewLayout](https://royale.apache.org/asdoc/index.html#!org.apache.royale.jewel.beads.layouts/ViewLayout){:target='_blank'} | [org.apache.royale.core.IBeadLayout](https://royale.apache.org/asdoc/index.html#!org.apache.royale.core/IBeadLayout){:target='_blank'} | This is the default layout bead. |
+
+## Optional Beads
+
+| Bead Type | Implementation | Description |
+|----------------- |------------------------------------------------ |------------------------------------------------ |
+| [ViewDataBinding](https://royale.apache.org/asdoc/index.html#!org.apache.royale.binding/ViewDataBinding){:target='_blank'} | [org.apache.royale.binding.DataBindingBase](https://royale.apache.org/asdoc/index.html#!org.apache.royale.binding/DataBindingBase){:target='_blank'} | Provide binding capabilities to the view. |
+
+### Common Beads
+
+Jewel `View` can use any of the layout beads available in Jewel library. Also you can check [Related controls](component-sets/jewel/view.html#related-controls) section to see some preconfigured views with specific layouts.
+
+## More examples
+
+* [Creating a Hello World in Apache Royale](https://royale.apache.org/creating-a-hello-world-in-apache-royale/){:target='_blank'}
+* [Using the Jewel Alert Control](https://royale.apache.org/using-jewel-alert-control/){:target='_blank'}
+* [Using View States to show or hide content](https://royale.codeoscopic.com/using-view-states-to-show-or-hide-content/){:target='_blank'}
+
+## Related controls {#related-controls}
+
+Other useful Jewel view components are:
+
+* [ResponsiveView](component-sets/jewel/responsiveview)
+* [Application](component-sets/jewel/application)