diff --git a/docs/extensions/tizenx/guides/overview.md b/docs/extensions/tizenx/guides/overview.md new file mode 100644 index 0000000000..6b8761963e --- /dev/null +++ b/docs/extensions/tizenx/guides/overview.md @@ -0,0 +1,15 @@ +# Guides + +This section provides detailed tutorials, best practices, and code examples to help you master the specific libraries within the Tizen Extension ecosystem. + +## Tizen.UI + +The Tizen.UI guides focus on streamlining user interface development. Learn how to construct responsive, maintainable, and readable UI code. + +## TizenX.ZLog + +The TizenX.ZLog guides are dedicated to application diagnostics and logging. + +### Where to go next? + +Select a topic from the sidebar to dive deeper into a specific module. If you are new to the Tizen Extension Library, we recommend starting with the Tizen.UI Getting Started guide to see immediate visual results in your application. diff --git a/docs/extensions/tizenx/guides/tizen-ui/csharp_markup.md b/docs/extensions/tizenx/guides/tizen-ui/csharp_markup.md new file mode 100644 index 0000000000..d5bdd13feb --- /dev/null +++ b/docs/extensions/tizenx/guides/tizen-ui/csharp_markup.md @@ -0,0 +1,634 @@ + +# C# Markup + +## OVERVIEW + +Tizen.UI C# Markup is a set of fluent helper methods and classes designed to simplify the process of building declarative user interfaces in code. The fluent API provided by C# Markup is available in the `Tizen.UI` and `Tizen.UI.Layouts` namespace. + +Just as with XAML, C# Markup enables a clean separation between UI (View) and Business Logic (View Model). + +## EXAMPLE + +Here are some brief examples showing how common tasks can be achieved through the use of the C# Markup. + +### Sizing +C# Markup allows us to define the sizing fluently and therefore chain multiple methods together to reduce the verbosity of our code: + +```cs +new TextView().DesiredSize(200, 40); +``` + +### Binding + +The Binding extensions provide a series of extension methods that support configuring Bindings on a `View`. + +The extensions offer the following methods: + +#### Bind (One way binding) +A one way binding from a view model property called `Title` to the `Text` property of an `TextView` can be created as follows: +```cs +new TextView().Bind(TextView.TextProperty, "Title") + +//or + +new TextView().BindText("Title")) +``` + +#### TwoWayBind (Two way binding) +A two way binding from a view model property called `UserText` to the `Text` property of an `TextField` can be created as follows: +```cs +new TextField().TwoWayBind(TextFieldBindings.TextProperty, "UserText") + +//or + +new TextField().BindText("UserText")) +``` + +### View +The `View` extensions provide a series of extension methods that support configuring the alignment of controls inheriting from `View`. + +#### FixedWidth +The `FixedWidth` method sets the `View.WidthResizePolicy` property to `ResizePolicy.Fixed`. +Here's an example setting `TextView.WidthResizePolicy` to `ResizePolicy.Fixed` using `FixedWidth`: +```cs +new TextView().FixedWidth() +``` + +#### FixedHeight +The `FixedHeight` method sets the `View.HeightResizePolicy` property to `ResizePolicy.Fixed`. +Here's an example setting `TextView.HeightResizePolicy` to `ResizePolicy.Fixed` using `FixedHeight`: +```cs +new TextView().FixedHeight() +``` + +#### Fixed +The `Fixed` method sets both the `View.WidthResizePolicy` property and the `View.HeightResizePolicy` property to `ResizePolicy.Fixed`. +Here's an example setting both `TextView.WidthResizePolicy` and `TextView.HeightResizePolicy` to `ResizePolicy.Fixed` using `Fixed`: +```cs +new TextView().Fixed() +``` + +#### UseNaturalSizeWidth +The `UseNaturalSizeWidth` method sets the `View.WidthResizePolicy` property to `ResizePolicy.UseNaturalSize`. +Here's an example setting `TextView.WidthResizePolicy` to `ResizePolicy.UseNaturalSize` using `UseNaturalSizeWidth`: +```cs +new TextView().UseNaturalSizeWidth() +``` + +#### UseNaturalSizeHeight +The `UseNaturalSizeHeight` method sets the `View.HeightResizePolicy` property to `ResizePolicy.UseNaturalSize`. +Here's an example setting `TextView.HeightResizePolicy` to `ResizePolicy.UseNaturalSize` using `UseNaturalSizeHeight`: +```cs +new TextView().UseNaturalSizeHeight() +``` + +#### UseNaturalSize +The `UseNaturalSize` method sets both the `View.WidthResizePolicy` property and the `View.HeightResizePolicy` property to `ResizePolicy.UseNaturalSize`. +Here's an example setting both `TextView.WidthResizePolicy` and `TextView.HeightResizePolicy` to `ResizePolicy.UseNaturalSize` using `UseNaturalSize`: +```cs +new TextView().UseNaturalSize() +``` + +#### FillToParentWidth +The `FillToParentWidth` method sets the `View.WidthResizePolicy` property to `ResizePolicy.FillToParent`. +Here's an example setting `TextView.WidthResizePolicy` to `ResizePolicy.FillToParent` using `FillToParentWidth`: +```cs +new TextView().FillToParentWidth() +``` + +#### FillToParentHeight +The `FillToParentHeight` method sets the `View.HeightResizePolicy` property to `ResizePolicy.FillToParent`. +Here's an example setting `TextView.HeightResizePolicy` to `ResizePolicy.HeightResizePolicy` using `FillToParentHeight`: +```cs +new TextView().FillToParentHeight() +``` + +#### FillToParent +The `FillToParent` method sets both the `View.WidthResizePolicy` property and the `View.HeightResizePolicy` property to `ResizePolicy.FillToParent`. +Here's an example setting both `TextView.WidthResizePolicy` and `TextView.HeightResizePolicy` to `ResizePolicy.FillToParent` using `FillToParent`: +```cs +new TextView().FillToParent() +``` + +#### Margin +The `Padding`extension method allows you to set the margin for the `View`. +```cs +new TextView().Margin(50, 0, 0, 0) +new TextView().Margin(50) +``` + +#### MinimumWidth / MinimumHeight +The `MinimumWidth` and `MinimumHeight` extension method allows you to set the minimum width the `View` will request during layout. +```cs +new TextView.MinimumWidth(10) +new TextView.MinimumHeight(10) +``` + +#### MaximumWidth / MaximumHeight +The `MaximumWidth` and `MaximumHeight` extension method allows you to set the maximum width the `View` will request during layout. +```cs +new TextView.MaximumWidth(100) +new TextView.MaximumHeight(100) +``` + +#### FillHorizontal +The `FillHorizontal` method sets the `View.LayoutParam().HorizontalLayoutAlignment` property to LayoutAlignment.Fill. +Here's an example setting `TextView.HorizontalLayoutAlignment` to `LayoutAlignment.Fill` using `FillHorizontal`: +```cs +new TextView().FillHorizontal() +``` + +#### FillVertical +The `FillVertical` method sets the `View.LayoutParam().VerticalLayoutAlignment` property to LayoutAlignment.Fill. +Here's an example setting `TextView.VerticalLayoutAlignment` to `LayoutAlignment.Fill` using `FillVertical`: +```cs +new TextView().FillVertical() +``` + +#### Fill +The `Fill` method sets both the `View.LayoutParam().HorizontalLayoutAlignment` property and the `View.LayoutParam().VerticalLayoutAlignment` property to `LayoutAlignment.Fill`. +Here's an example setting both `TextView.VerticalLayoutAlignment` and `TextView.HorizontalLayoutAlignment` to `LayoutAlignment.Fill` using `Fill`: +```cs +new TextView().Fill() +``` + +#### StartHorizontal +The `StartHorizontal` method sets the `View.LayoutParam().HorizontalLayoutAlignment` property to LayoutAlignment.Start. +Here's an example setting `TextView.HorizontalLayoutAlignment` to `LayoutAlignment.Start` using `StartHorizontal`: +```cs +new TextView().StartHorizontal() +``` + +#### StartVertical +The `StartVertical` method sets the `View.LayoutParam().VerticalLayoutAlignment` property to LayoutAlignment.Start. +Here's an example setting `TextView.VerticalLayoutAlignment` to `LayoutAlignment.Start` using `StartVertical`: +```cs +new TextView().StartVertical() +``` + +#### Start +The `Start` method sets both the `View.LayoutParam().HorizontalLayoutAlignment` property and the `View.LayoutParam().VerticalLayoutAlignment` property to `LayoutAlignment.Start`. +Here's an example setting both `TextView.VerticalLayoutAlignment` and `TextView.HorizontalLayoutAlignment` to `LayoutAlignment.Start` using `Start`: +```cs +new TextView().Start() +``` + +#### CenterHorizontal +The `CenterHorizontal` method sets the `View.LayoutParam().HorizontalLayoutAlignment` property to LayoutAlignment.Center. +Here's an example setting `TextView.HorizontalLayoutAlignment` to `LayoutAlignment.Center` using `CenterHorizontal`: +```cs +new TextView().CenterHorizontal() +``` + +#### CentetVertical +The `CentetVertical` method sets the `View.LayoutParam().VerticalLayoutAlignment` property to LayoutAlignment.Center. +Here's an example setting `TextView.VerticalLayoutAlignment` to `LayoutAlignment.Center` using `CentetVertical`: +```cs +new TextView().CentetVertical() +``` + +#### Center +The `Center` method sets both the `View.LayoutParam().HorizontalLayoutAlignment` property and the `View.LayoutParam().VerticalLayoutAlignment` property to `LayoutAlignment.Center`. +Here's an example setting both `TextView.VerticalLayoutAlignment` and `TextView.HorizontalLayoutAlignment` to `LayoutAlignment.Center` using `Center`: +```cs +new TextView().Center() +``` + +#### EndHorizontal +The `EndHorizontal` method sets the `View.LayoutParam().HorizontalLayoutAlignment` property to LayoutAlignment.End. +Here's an example setting `TextView.HorizontalLayoutAlignment` to `LayoutAlignment.End` using `EndHorizontal`: +```cs +new TextView().EndHorizontal() +``` + +#### EndVertical +The `EndVertical` method sets the `View.LayoutParam().VerticalLayoutAlignment` property to LayoutAlignment.End. +Here's an example setting `TextView.VerticalLayoutAlignment` to `LayoutAlignment.End` using `EndVertical`: +```cs +new TextView().EndVertical() +``` + +#### End +The `End` method sets both the `View.LayoutParam().HorizontalLayoutAlignment` property and the `View.LayoutParam().VerticalLayoutAlignment` property to `LayoutAlignment.End`. +Here's an example setting both `TextView.VerticalLayoutAlignment` and `TextView.HorizontalLayoutAlignment` to `LayoutAlignment.End` using `End`: +```cs +new TextView().End() +``` + +### TextView +The `TextView` extensions provide a series of extension methods that support configuring a `TextView`. + +The extensions offer the following methods: + +#### Text +The `Text` method sets the `Text` property on an `TextView`. +```cs +new TextView().Text("This is TextView") +``` + +#### TextColor +The `TextColor` method sets the `TextColor` property on an `TextView`. +```cs +new TextView().TextColor(Color.Black) +``` + +#### TextColorFromHex +The `TextColorFromHex` method sets the `TextColor` property on an `TextView` as a hexadecimal string. +```cs +new TextView().TextColorFromHex("#ffffff") +``` + +#### FontSize +The `FontSize` method sets the `FontSize` property on an `TextView`. +```cs +new TextView().FontSize(15) +``` + +#### MultiLine +The `MultiLine` method sets the `MultiLine` property on an `TextView`. +```cs +new TextView().MultiLine(true) +``` + +#### TextStartHorizontal +The `TextStartHorizontal` method sets the `TextView.HorizontalAlignment` property to TextAlignment.Start. +```cs +new TextView().TextStartHorizontal() +``` + +#### TextStartVertical +The `TextStartVertical` method sets the `TextView.VerticalAlignment` property to TextAlignment.Start. +```cs +new TextView().TextStartVertical() +``` + +#### TextStart +The `TextStart` method sets both the `TextView.HorizontalAlignment` property and the `TextView.VerticalAlignment` property to TextAlignment.Start. +```cs +new TextView().TextStart() +``` + +#### TextCenterHorizontal +The `TextCenterHorizontal` method sets the `TextView.HorizontalAlignment` property to TextAlignment.Center. +```cs +new TextView().TextCenterHorizontal() +``` + +#### TextCenterVertical +The `TextCenterVertical` method sets the `TextView.VerticalAlignment` property to TextAlignment.Center. +```cs +new TextView().TextCenterVertical() +``` + +#### TextCenter +The `TextCenter` method sets both the `TextView.HorizontalAlignment` property and the `TextView.VerticalAlignment` property to TextAlignment.Center. +```cs +new TextView().TextCenter() +``` + +#### TextEndHorizontal +The `TextEndHorizontal` method sets the `TextView.HorizontalAlignment` property to TextAlignment.End. +```cs +new TextView().TextEndHorizontal() +``` + +#### TextEndVertical +The `TextEndVertical` method sets the `TextView.VerticalAlignment` property to TextAlignment.End. +```cs +new TextView().TextEndVertical() +``` + +#### TextEnd +The `TextEnd` method sets both the `TextView.HorizontalAlignment` property and the `TextView.VerticalAlignment` property to TextAlignment.End. +```cs +new TextView().TextEnd() +``` + +### ImageView +The `ImageView` extensions provide a series of extension methods that support configuring a `ImageView`. + +The extensions offer the following methods: + +#### ResourceUrl +The `ResourceUrl` method sets the `ResourceUrl` property on an `ImageView`. + +The following example sets the `ResourceUrl` to "image.png": + +```cs +new ImageView().ResourceUrl("image.png") +``` + +### Layout +The `Layout` extensions provide a series of extension methods that support positioning `View`s in `Layout`s. + +The extensions offer the following methods: + +#### Padding +The `Padding`extension method allows you to set the inner padding of the `Layout`. +```cs +new FlexBox().Padding(10) +new HStack().Padding(50, 0, 50, 0) +``` + +### StackBase +The `StackBase` extensions provide a series of extension methods that support positioning `View`s in `StackBase` layouts such as `HStack`, `VStack`. + +The extensions offer the following methods: + +#### Spacing +The `Spacing`extension method allows you to set the amount of space between children in `StackBase` layout. + +```cs +new HStack().Spacing(50); +``` + +### AbsoluteLayout + +The `AbsoluteLayout` extensions provide a series of extension methods that support positioning `View`s in `AbsoluteLayout`s. + +The extensions offer the following methods: + +#### LayoutBounds #### +The `LayoutBounds `extension method allows you to set the position and size of a `View` in an `AbsoluteLayout`. + +#### LayoutFlags #### +The `LayoutFlags` extension method allows you to set a flag that indicates that the layout bounds position and size values for a child are proportional to the size of the `AbsoluteLayout`. + +```cs +new AbsoluteLayout +{ + new VStack + { + new ImageView() + .DesiredHeight(154) + .ResourceUrl("image.png"), + new TextView + .Text("Read Information") + .TextColorFromHex("#565656") + .FontSize(30) + } + .LayoutBounds(0, 0, 1, 1) + .LayoutFlags(AbsoluteLayoutFlags.All) + .Margin(0, 0, 30, 30) + .Spacing(20) +} +``` + +### FlexBox +The `FlexBox` extensions provide a series of extension methods that support positioning a `View` in a `FlexBox`. + +The extensions offer the following methods: + +#### Direction +The `Direction` method sets the `Direction` property on a `FlexBox`. + +The following example sets the `Direction` to `FlexDirection.Row`: + +```cs +new FlexBox().Direction(FlexDirection.Row); + +// or + +new FlexBox().Row(); +``` + +#### AlignItems +The `AlignItems` method sets the `AlignItems` property on a `FlexBox`. + +The following example sets the `AlignItems` to `FlexAlignItems.Center`: + +```cs +new FlexBox().AlignItems(FlexAlignItems.Center); + +// or + +new FlexBox().CenterItems(); +``` + +#### JustifyContent +The `JustifyContent` method sets the `JustifyContent` property on a `FlexBox`. + +The following example sets the `JustifyContent` to `FlexJustify.Start`: + +```cs +new FlexBox().JustifyContent(FlexJustify.SpaceBetween); + +// or + +new FlexBox().SpaceBetweenJustify(); +``` + +#### Grow +The `Grow` method sets the `View.FlexParam().Grow` property on a `View`. +```cs +new TextView().Grow(.5f); +``` + +#### Shrink +The `Shrink` method sets the `View.FlexParam().Shrink` property on a `View`. +```cs +new TextView().Shrink(.5f); +``` + +#### AlignSelf +The `AlignSelf` method sets the `View.FlexParam().AlignSelf` property on a `View`. +```cs +new TextView().AlignSelf(FlexAlignSelf.Auto); + +// or + +new TextView().AutoAlign(); +``` + +#### Basis +The `Basis` method sets the `View.FlexParam().Basis` property on a `View`. +```cs +new TextView().AutoBasis(); + +// or + +new TextView().Basis(.5f); + +// or + +new TextView().RelativeBasis(.5f); +``` + +#### Order +The `Order` method sets the `View.FlexParam().Order` property on a `View`. +```cs +new TextView().Order(1); +``` + +### Grid +The `Grid` extensions provide a series of extension methods that support configuring a `Grid`. + +#### Defining Rows and Columns + +To define rows and columns for a `Grid`, `Tizen.UI.Layouts` provides two helper methods: +- `Columns.Define` +- `Rows.Define` + +To leverage these helper methods, we first add the following `using static` directive to the top of our class: +```cs +using static Tizen.UI.Layouts.GridRowColumns; +``` + +After adding the above using `static directive`, we can then define our Row + Column sizes using the following values to set the `GridLength`: + + +Tizen.UI.Layout | XAML | Tizen.UI.Layouts.GridRowColumns +---|---|--- +GridLength.Auto | Auto | Auto +GridLength.Star | * | Star +new GridLength(2, GridLength.Star) | 2* | Stars(2) +new GridLength(20, GridLength.Absolute) | 20 | 20 + +Putting it all together, we can now define a Grid's Rows + Columns: +```cs +new Grid +{ + ColumnDefinitions = Columns.Define(30, Star, Stars(2)), + RowDefinitions = Rows.Define(Auto, Star), +}; +``` + +The following example demonstrates how to create a Grid with 2 Rows: +- Row 0 Size: `GridLength.Auto` +- Row 1 Size: `GridLength.Star` + +The following example demonstrates how to create a Grid with 3 Columns: +- Column 0 Size: `new GridLength(30, GridLength.Absolute)` +- Column 1 Size: `GridLength.Star` +- Column 2 Size: `new GridLength(GridLength.Star, 2)`: + +```cs +// Add this using static to enable Columns.Define and Rows.Define +using static Tizen.UI.Layouts.GridRowColumns; + +// ... + +new Grid +{ + ColumnDefinitions = Columns.Define(30, Star, Stars(2)), + RowDefinitions = Rows.Define(Auto, Star), + + new TextView() + .Text("This TextView is in Row 0 Column 0") + .Row(0).Column(0) + + new TextView() + .Text("This TextView is in Row 0 Column 1") + .Row(0).Column(1) + + new TextView() + .Text("This TextView is in Row 0 Column 2") + .Row(1).Column(2) + + new TextView() + .Text("This TextView is in Row 1 Column 0") + .Row(1).Column(0) + + new TextView() + .Text("This TextView is in Row 1 Column 1") + .Row(1).Column(1) + + new TextView() + .Text("This TextView is in Row 1 Column 2") + .Row(1).Column(2) +} +``` + +#### Row +The `Row` method sets the `Grid.Row` and `Grid.RowSpan` on a View. + +The following example sets the `Grid.Row` of a TextView to 0 and its `Grid.RowSpan` to 2, then sets the `Grid.Row` of a TextView to 1: +```cs +new Grid +{ + new TextView() + .Text("This TextView is in Row 0 and spans 2 Columns") + .Column(0, 2), + + new TextView() + .Text("This TextView is in Row 1 and does not span multiple columns") + .Column(1) +}; +``` + +#### Column +The `Column` method sets the `Grid.Column` and `Grid.ColumnSpan` on a `View`. + +The following example sets the `Grid.Column` of a `TextView` to 0 and its `Grid.ColumnSpan` to 2, then sets the `Grid.Column` of a TextView to 1: + +```cs +new Grid +{ + new Button() + .Text("This TextView is in Row 0 and spans 2 Columns") + .Column(0, 2), + + new TextView() + .Text("This TextView is in Row 1 and does not span multiple columns") + .Column(1) +}; +``` + +### ScrollView +The `ScrollView` extensions provide a series of extension methods that support configuring `ScrollView`. + +The extensions offer the following methods: + +#### ScrollDirection ##### + +The `ScrollDirection` method sets the `ScrollDirection` property on a `ScrollView`. + +The following example sets the `ScrollDirection` to `ScrollDirection.Both`: + +```cs +new ScrollView().ScrollDirection(ScrollDirection.Both); + +// or + +new ScrollView().ScrollBoth(); +``` + + +#### HorizontalScrollBarVisibility #### +The `HorizontalScrollBarVisibility` method sets the `HorizontalScrollBarVisibility` property on a `ScrollView`. + +The following example sets the `HorizontalScrollBarVisibility` to `ScrollBarVisibility.Auto`: + +```cs +new ScrollView().HorizontalScrollBarVisibility(ScrollBarVisibility.Auto); + +// or + +new ScrollView().ScrollBarAutoHorizontal(); +``` + +#### VerticalScrollBarVisibility #### +The `VerticalScrollBarVisibility` method sets the `VerticalScrollBarVisibility` property on a `ScrollView`. + +The following example sets the `VerticalScrollBarVisibility` to `ScrollBarVisibility.Auto`: + +```cs +new ScrollView().VerticalScrollBarVisibility(ScrollBarVisibility.Auto); + +// or + +new ScrollView().ScrollBarAutoVertical(); +``` + +#### ScrollBarVisibility #### +The `ScrollBarVisibility` method sets both the `VerticalScrollBarVisibility` and `HorizontalScrollBarVisibility` properties on a `ScrollView`. + +The following example sets both the `VerticalScrollBarVisibility` and `HorizontalScrollBarVisibility` to `ScrollBarVisibility.Auto`: + +```cs +new ScrollView().ScrollBarVisibility(ScrollBarVisibility.Auto); + +// or + +new ScrollView().ScrollBarAuto(); +``` \ No newline at end of file diff --git a/docs/extensions/tizenx/guides/tizen-ui/getting-started.md b/docs/extensions/tizenx/guides/tizen-ui/getting-started.md new file mode 100644 index 0000000000..9fed3a5882 --- /dev/null +++ b/docs/extensions/tizenx/guides/tizen-ui/getting-started.md @@ -0,0 +1,80 @@ + +# Create Your First Application + +All Tizen Extension Libraries are distributed as individual NuGet packages. +You can browse and add them to your Tizen .NET project directly from the Visual Studio NuGet Package Manager. + +## Getting Started: Create Your First Tizen.UI Application + +This guide demonstrates how to create your first Tizen .NET application using the **Tizen.UI** template. Tizen.UI, provided as part of the Tizen Extension Library, is a lightweight and high-performance UI framework for building Tizen .NET applications. + +This guide uses **Visual Studio 2022** to create and run a basic "Hello, Tizen.UI" project. + +## 1. Prerequisites + +Before you start, you must set up your Tizen .NET development environment. This includes installing the Tizen SDK and the necessary IDE extensions. + +Follow the official installation guides on the Tizen Developers site: + +* **Tizen SDK & Visual Studio Tools:** [Learn How to Install](https://samsungtizenos.com/docs/sdktools/?sid=6VEghbxamZ1b1RPs6dXO) + +* **Visual Studio Code Extension:** [Learn How to Install](https://samsungtizenos.com/docs/sdktools/?sid=IxbvHeBMNspcp66uVvC) + +## 2. Create a New Project + +1. Launch Visual Studio. On the start window, select **Create a new project**. + + ![Create Project](./images/vs_create_project.png) + +2. In the 'Create a new project' dialog, use the search bar to filter for "Tizen". + +3. Select the **Tizen UI Application (Samsung Electronics)** template from the list and click **Next**. + + ![Select Tizen UI Application Project](./images/vs_select_tizenui_project.png) + +## 3. Configure Your Project + +1. On the 'Configure your new project' screen, enter a **Project name** (e.g., "HelloTizenUI") and choose a **Location** for your project. Click **Create**. + + ![Set Project Name](./images/vs_set_project_name.png) + +1. A 'Tizen Project Wizard' dialog will appear. +2. Under the **Framework** dropdown, select **.NET 8.0 (tizen10.0)**. +3. Verify the **Package Name** is correct (e.g., "org.tizen.HelloTizenUI"). +4. Click **OK**. + + ![Set Framework](./images/vs_set_framework.png) + +## 4. Review and Build the "Hello Tizen.UI" Project + +Visual Studio will generate a minimal "Hello Tizen.UI" solution. + + ![Tizen.UI Template Application](./images/vs_template_app.png) + +1. Once the project loads, right-click the project in the **Solution Explorer**. + +2. Select **Build** (or press **Ctrl+B**) to compile the project and ensure there are no errors. + +### Tizen.UI Package References + +This template is configured to use the **Tizen.UI** framework. + + ![Exploring Nuget Package Manager](./images/vs_nuget_package_manager.png) + +You can verify this by right-clicking the project and selecting **Manage NuGet Packages...**. You will see that the project references the `Tizen.UI` packages, which are delivered through the Tizen Extension Libraries. You can use this interface to add or remove other Tizen Extension Library packages as your application requires. + +## 5. Run the Application + +1. In the Visual Studio toolbar, select a Tizen emulator (e.g., "Tizen Emulator (tizen10.0-x86)") as the debug target. + +2. Press the **Start** button (the green play icon) or press **F5** to build, deploy, and launch the application on the selected emulator. + + ![Launch Tizen Application](./images/vs_launch_app.png) + +3. After a moment, you will see your new "Hello Tizen.UI" application running in the emulator. + +--- + +## Next Steps + +Congratulations! You have successfully built and run your first Tizen.UI application. You are now ready to explore the Tizen.UI framework and start building your app's user interface. diff --git a/docs/extensions/tizenx/guides/tizen-ui/images/vs_create_project.png b/docs/extensions/tizenx/guides/tizen-ui/images/vs_create_project.png new file mode 100644 index 0000000000..3ed0dfd81d Binary files /dev/null and b/docs/extensions/tizenx/guides/tizen-ui/images/vs_create_project.png differ diff --git a/docs/extensions/tizenx/guides/tizen-ui/images/vs_launch_app.png b/docs/extensions/tizenx/guides/tizen-ui/images/vs_launch_app.png new file mode 100644 index 0000000000..014426e279 Binary files /dev/null and b/docs/extensions/tizenx/guides/tizen-ui/images/vs_launch_app.png differ diff --git a/docs/extensions/tizenx/guides/tizen-ui/images/vs_nuget_package_manager.png b/docs/extensions/tizenx/guides/tizen-ui/images/vs_nuget_package_manager.png new file mode 100644 index 0000000000..01062e88cb Binary files /dev/null and b/docs/extensions/tizenx/guides/tizen-ui/images/vs_nuget_package_manager.png differ diff --git a/docs/extensions/tizenx/guides/tizen-ui/images/vs_select_tizenui_project.png b/docs/extensions/tizenx/guides/tizen-ui/images/vs_select_tizenui_project.png new file mode 100644 index 0000000000..3b68d8d485 Binary files /dev/null and b/docs/extensions/tizenx/guides/tizen-ui/images/vs_select_tizenui_project.png differ diff --git a/docs/extensions/tizenx/guides/tizen-ui/images/vs_set_framework.png b/docs/extensions/tizenx/guides/tizen-ui/images/vs_set_framework.png new file mode 100644 index 0000000000..fb6ced0e69 Binary files /dev/null and b/docs/extensions/tizenx/guides/tizen-ui/images/vs_set_framework.png differ diff --git a/docs/extensions/tizenx/guides/tizen-ui/images/vs_set_project_name.png b/docs/extensions/tizenx/guides/tizen-ui/images/vs_set_project_name.png new file mode 100644 index 0000000000..c4c717c137 Binary files /dev/null and b/docs/extensions/tizenx/guides/tizen-ui/images/vs_set_project_name.png differ diff --git a/docs/extensions/tizenx/guides/tizen-ui/images/vs_start_without_debugging.png b/docs/extensions/tizenx/guides/tizen-ui/images/vs_start_without_debugging.png new file mode 100644 index 0000000000..37aa48f2b5 Binary files /dev/null and b/docs/extensions/tizenx/guides/tizen-ui/images/vs_start_without_debugging.png differ diff --git a/docs/extensions/tizenx/guides/tizen-ui/images/vs_template_app.png b/docs/extensions/tizenx/guides/tizen-ui/images/vs_template_app.png new file mode 100644 index 0000000000..a1a721fc8a Binary files /dev/null and b/docs/extensions/tizenx/guides/tizen-ui/images/vs_template_app.png differ diff --git a/docs/extensions/tizenx/guides/tizen-ui/layouts/aboluteLayout.md b/docs/extensions/tizenx/guides/tizen-ui/layouts/aboluteLayout.md new file mode 100644 index 0000000000..7e7fb75cff --- /dev/null +++ b/docs/extensions/tizenx/guides/tizen-ui/layouts/aboluteLayout.md @@ -0,0 +1,173 @@ + +# AbsoluteLayout + +## Overview + +- A Layout that position View within a fixed space or relative to the available space using proportions. + +## Measurement Rules + +- If the Layout size is not fixed, the Layout measures its size based on the outermost bounds defined by the position and size specified in each child's AbsoluteParam. + +## Layout Options + +There options are set on the Child views. + +### LayoutBounds + +Specifies the position and size where the view is placed. + +```csharp +view.LayoutBounds(x, y, width, height); +``` + +- Values: can be set as absolute values or proportional values. +- Proportional Settings: + - Position: 0 places the view at the start position, 1 places it at the end position. + - Size: The size is calculated proportionally to the Layout size. 1 matches the full size of the Layout. +- Auto-sizing: If -1 is specified for the size, the View is automatically laid out using its original measured size. + +### LayoutFlags + +Specifies whether the values set in LayoutBounds are interpreted as proportional values or absolute values. + +```csharp +view.LayoutFlags(flags); +``` + +- Default: The default value is None, meaning the X/Y/Width/Height in layoutBounds are interpreted as absolute values. + +|Flag| Description| +|-|-| +|None|No flags set| +|XProportional|Indicates that the X position of the child element should be proportional to its parent.| +|YProportional|Indicates that the Y position of the child element should be proportional to its parent.| +|WidthProportional|Indicates that the width of the child element should be proportional to its parent.| +|HeightProportional|Indicates that the height of the child element should be proportional to its parent.| +|PositionProportional|Indicates that both the X and Y positions of the child element should be proportional to its parent.| +|SizeProportional|Indicates that both the width and height of the child element should be proportional to its parent.| +|All|Indicates that all properties of the child element should be proportional to its parent.| + +- Combination: Individual flags can be combined using bitwise OR operations. + +```csharp +// Example: Setting X and Width as proportional. +view.LayoutFlags(AbsoluteLayoutFlags.XProportional | AbsoluteLayoutFlags.WidthProportional); +``` + +## Usage Examples + +### Centering a View + +Placing a 100x100 Red view in the center (0.5, 0.5) of a 600x600 AbsoluteLayout using its own measured size (-1, -1). + +```csharp +new AbsoluteLayout +{ + DesiredWidth = 600, + DesiredHeight = 600, + BackgroundColor = Color.LightBlue, + Children = + { + new View + { + BackgroundColor = Color.Red, + DesiredHeight = 100, + DesiredWidth = 100, + }.LayoutBounds(0.5f, 0.5f, -1, -1).LayoutFlags(AbsoluteLayoutFlags.PositionProportional) + } +} +``` + +![Example: Centering a View](./assets/absolute_example1.png) + +### Direct Sizing with LayoutBound + +Positioning a view by directly specifying the size using LayoutBounds. + +```csharp +new AbsoluteLayout +{ + DesiredWidth = 600, + DesiredHeight = 600, + BackgroundColor = Color.LightBlue, + Children = + { + new View + { + BackgroundColor = Color.Red, + }.LayoutBounds(0.5f, 0.5f, 100, 100).LayoutFlags(AbsoluteLayoutFlags.PositionProportional) + } +} +``` + +![Example: Direct Sizing with LayoutBound](./assets/absolute_example2.png) + +### Difference between DesiredWidth/Height and LayoutBounds + +- DesiredWidth/Height: The size excluding the Margin. +- LayoutBounds: The size calculated including the Margin. + +```csharp +new AbsoluteLayout +{ + DesiredWidth = 600, + DesiredHeight = 600, + BackgroundColor = Color.LightBlue, + Children = + { + new View + { + BackgroundColor = Color.Red, + DesiredWidth = 100, + DesiredHeight = 100, + }.LayoutBounds(0.5f, 0.5f, -1, -1) + .LayoutFlags(AbsoluteLayoutFlags.PositionProportional) + .Margin(10) + } +} +``` + +```csharp +new AbsoluteLayout +{ + DesiredWidth = 600, + DesiredHeight = 600, + BackgroundColor = Color.LightBlue, + Children = + { + new View + { + BackgroundColor = Color.Red, + }.LayoutBounds(0.5f, 0.5f, 100, 100) + .LayoutFlags(AbsoluteLayoutFlags.PositionProportional) + .Margin(10) + } +} +``` + +![Example: Difference between DesiredWidth/Height and LayoutBounds](./assets/absolute_example3.png) + +### Responsive Layout with Fixed Position + +Using PositionProportional and Margin to create a responsive layout, and placing a view at the bottom-right corner regardless of the layout size. + +```csharp +new AbsoluteLayout +{ + DesiredWidth = 600, + DesiredHeight = 600, + BackgroundColor = Color.LightBlue, + Children = + { + new View + { + BackgroundColor = Color.Red, + DesiredHeight = 100, + DesiredWidth = 100, + }.LayoutBounds(1f, 1f, -1, -1) + .LayoutFlags(AbsoluteLayoutFlags.PositionProportional) + .Margin(0, 0, 100, 100) + } +} +``` diff --git a/docs/extensions/tizenx/guides/tizen-ui/layouts/assets/absolute_bound_option.png b/docs/extensions/tizenx/guides/tizen-ui/layouts/assets/absolute_bound_option.png new file mode 100644 index 0000000000..ed6371f4a5 Binary files /dev/null and b/docs/extensions/tizenx/guides/tizen-ui/layouts/assets/absolute_bound_option.png differ diff --git a/docs/extensions/tizenx/guides/tizen-ui/layouts/assets/absolute_example1.png b/docs/extensions/tizenx/guides/tizen-ui/layouts/assets/absolute_example1.png new file mode 100644 index 0000000000..0136927751 Binary files /dev/null and b/docs/extensions/tizenx/guides/tizen-ui/layouts/assets/absolute_example1.png differ diff --git a/docs/extensions/tizenx/guides/tizen-ui/layouts/assets/absolute_example2.png b/docs/extensions/tizenx/guides/tizen-ui/layouts/assets/absolute_example2.png new file mode 100644 index 0000000000..d61700283b Binary files /dev/null and b/docs/extensions/tizenx/guides/tizen-ui/layouts/assets/absolute_example2.png differ diff --git a/docs/extensions/tizenx/guides/tizen-ui/layouts/assets/absolute_example3.png b/docs/extensions/tizenx/guides/tizen-ui/layouts/assets/absolute_example3.png new file mode 100644 index 0000000000..f3af639317 Binary files /dev/null and b/docs/extensions/tizenx/guides/tizen-ui/layouts/assets/absolute_example3.png differ diff --git a/docs/extensions/tizenx/guides/tizen-ui/layouts/assets/absolute_example4.png b/docs/extensions/tizenx/guides/tizen-ui/layouts/assets/absolute_example4.png new file mode 100644 index 0000000000..f3af639317 Binary files /dev/null and b/docs/extensions/tizenx/guides/tizen-ui/layouts/assets/absolute_example4.png differ diff --git a/docs/extensions/tizenx/guides/tizen-ui/layouts/assets/absolute_example_video.mp4 b/docs/extensions/tizenx/guides/tizen-ui/layouts/assets/absolute_example_video.mp4 new file mode 100644 index 0000000000..0f3980f83c Binary files /dev/null and b/docs/extensions/tizenx/guides/tizen-ui/layouts/assets/absolute_example_video.mp4 differ diff --git a/docs/extensions/tizenx/guides/tizen-ui/layouts/assets/absolute_measure.png b/docs/extensions/tizenx/guides/tizen-ui/layouts/assets/absolute_measure.png new file mode 100644 index 0000000000..a37f964f27 Binary files /dev/null and b/docs/extensions/tizenx/guides/tizen-ui/layouts/assets/absolute_measure.png differ diff --git a/docs/extensions/tizenx/guides/tizen-ui/layouts/assets/grid_example1.png b/docs/extensions/tizenx/guides/tizen-ui/layouts/assets/grid_example1.png new file mode 100644 index 0000000000..14a86de1e6 Binary files /dev/null and b/docs/extensions/tizenx/guides/tizen-ui/layouts/assets/grid_example1.png differ diff --git a/docs/extensions/tizenx/guides/tizen-ui/layouts/assets/grid_example2.png b/docs/extensions/tizenx/guides/tizen-ui/layouts/assets/grid_example2.png new file mode 100644 index 0000000000..ce9fb4b8bb Binary files /dev/null and b/docs/extensions/tizenx/guides/tizen-ui/layouts/assets/grid_example2.png differ diff --git a/docs/extensions/tizenx/guides/tizen-ui/layouts/assets/grid_spacing.png b/docs/extensions/tizenx/guides/tizen-ui/layouts/assets/grid_spacing.png new file mode 100644 index 0000000000..9337634330 Binary files /dev/null and b/docs/extensions/tizenx/guides/tizen-ui/layouts/assets/grid_spacing.png differ diff --git a/docs/extensions/tizenx/guides/tizen-ui/layouts/assets/layout_hierarchy.png b/docs/extensions/tizenx/guides/tizen-ui/layouts/assets/layout_hierarchy.png new file mode 100644 index 0000000000..2918371b3c Binary files /dev/null and b/docs/extensions/tizenx/guides/tizen-ui/layouts/assets/layout_hierarchy.png differ diff --git a/docs/extensions/tizenx/guides/tizen-ui/layouts/assets/layout_invalidate_process.png b/docs/extensions/tizenx/guides/tizen-ui/layouts/assets/layout_invalidate_process.png new file mode 100644 index 0000000000..c1de991841 Binary files /dev/null and b/docs/extensions/tizenx/guides/tizen-ui/layouts/assets/layout_invalidate_process.png differ diff --git a/docs/extensions/tizenx/guides/tizen-ui/layouts/assets/layout_process.png b/docs/extensions/tizenx/guides/tizen-ui/layouts/assets/layout_process.png new file mode 100644 index 0000000000..05a1257795 Binary files /dev/null and b/docs/extensions/tizenx/guides/tizen-ui/layouts/assets/layout_process.png differ diff --git a/docs/extensions/tizenx/guides/tizen-ui/layouts/assets/stack_example1.png b/docs/extensions/tizenx/guides/tizen-ui/layouts/assets/stack_example1.png new file mode 100644 index 0000000000..77d3a26b72 Binary files /dev/null and b/docs/extensions/tizenx/guides/tizen-ui/layouts/assets/stack_example1.png differ diff --git a/docs/extensions/tizenx/guides/tizen-ui/layouts/assets/stack_example2.png b/docs/extensions/tizenx/guides/tizen-ui/layouts/assets/stack_example2.png new file mode 100644 index 0000000000..db7054a6da Binary files /dev/null and b/docs/extensions/tizenx/guides/tizen-ui/layouts/assets/stack_example2.png differ diff --git a/docs/extensions/tizenx/guides/tizen-ui/layouts/assets/stack_example3.png b/docs/extensions/tizenx/guides/tizen-ui/layouts/assets/stack_example3.png new file mode 100644 index 0000000000..2605b3af5f Binary files /dev/null and b/docs/extensions/tizenx/guides/tizen-ui/layouts/assets/stack_example3.png differ diff --git a/docs/extensions/tizenx/guides/tizen-ui/layouts/assets/stack_expand_first.png b/docs/extensions/tizenx/guides/tizen-ui/layouts/assets/stack_expand_first.png new file mode 100644 index 0000000000..f9521254a6 Binary files /dev/null and b/docs/extensions/tizenx/guides/tizen-ui/layouts/assets/stack_expand_first.png differ diff --git a/docs/extensions/tizenx/guides/tizen-ui/layouts/assets/stack_expand_none.png b/docs/extensions/tizenx/guides/tizen-ui/layouts/assets/stack_expand_none.png new file mode 100644 index 0000000000..4debfb0c6d Binary files /dev/null and b/docs/extensions/tizenx/guides/tizen-ui/layouts/assets/stack_expand_none.png differ diff --git a/docs/extensions/tizenx/guides/tizen-ui/layouts/assets/stack_itemalignment_center.png b/docs/extensions/tizenx/guides/tizen-ui/layouts/assets/stack_itemalignment_center.png new file mode 100644 index 0000000000..009c77a6cc Binary files /dev/null and b/docs/extensions/tizenx/guides/tizen-ui/layouts/assets/stack_itemalignment_center.png differ diff --git a/docs/extensions/tizenx/guides/tizen-ui/layouts/assets/stack_itemalignment_end.png b/docs/extensions/tizenx/guides/tizen-ui/layouts/assets/stack_itemalignment_end.png new file mode 100644 index 0000000000..55456a02f9 Binary files /dev/null and b/docs/extensions/tizenx/guides/tizen-ui/layouts/assets/stack_itemalignment_end.png differ diff --git a/docs/extensions/tizenx/guides/tizen-ui/layouts/assets/stack_itemalignment_start.png b/docs/extensions/tizenx/guides/tizen-ui/layouts/assets/stack_itemalignment_start.png new file mode 100644 index 0000000000..a5617bbc36 Binary files /dev/null and b/docs/extensions/tizenx/guides/tizen-ui/layouts/assets/stack_itemalignment_start.png differ diff --git a/docs/extensions/tizenx/guides/tizen-ui/layouts/assets/stack_layoutalignment_center.png b/docs/extensions/tizenx/guides/tizen-ui/layouts/assets/stack_layoutalignment_center.png new file mode 100644 index 0000000000..e5c26f3dfe Binary files /dev/null and b/docs/extensions/tizenx/guides/tizen-ui/layouts/assets/stack_layoutalignment_center.png differ diff --git a/docs/extensions/tizenx/guides/tizen-ui/layouts/assets/stack_layoutalignment_end.png b/docs/extensions/tizenx/guides/tizen-ui/layouts/assets/stack_layoutalignment_end.png new file mode 100644 index 0000000000..dea48e09ff Binary files /dev/null and b/docs/extensions/tizenx/guides/tizen-ui/layouts/assets/stack_layoutalignment_end.png differ diff --git a/docs/extensions/tizenx/guides/tizen-ui/layouts/assets/stack_layoutalignment_fill.png b/docs/extensions/tizenx/guides/tizen-ui/layouts/assets/stack_layoutalignment_fill.png new file mode 100644 index 0000000000..10953cb985 Binary files /dev/null and b/docs/extensions/tizenx/guides/tizen-ui/layouts/assets/stack_layoutalignment_fill.png differ diff --git a/docs/extensions/tizenx/guides/tizen-ui/layouts/assets/stack_layoutalignment_start.png b/docs/extensions/tizenx/guides/tizen-ui/layouts/assets/stack_layoutalignment_start.png new file mode 100644 index 0000000000..f5908a887d Binary files /dev/null and b/docs/extensions/tizenx/guides/tizen-ui/layouts/assets/stack_layoutalignment_start.png differ diff --git a/docs/extensions/tizenx/guides/tizen-ui/layouts/assets/stack_measure.png b/docs/extensions/tizenx/guides/tizen-ui/layouts/assets/stack_measure.png new file mode 100644 index 0000000000..4fbc0652fe Binary files /dev/null and b/docs/extensions/tizenx/guides/tizen-ui/layouts/assets/stack_measure.png differ diff --git a/docs/extensions/tizenx/guides/tizen-ui/layouts/assets/stack_spacing.png b/docs/extensions/tizenx/guides/tizen-ui/layouts/assets/stack_spacing.png new file mode 100644 index 0000000000..600991c275 Binary files /dev/null and b/docs/extensions/tizenx/guides/tizen-ui/layouts/assets/stack_spacing.png differ diff --git a/docs/extensions/tizenx/guides/tizen-ui/layouts/grid.md b/docs/extensions/tizenx/guides/tizen-ui/layouts/grid.md new file mode 100644 index 0000000000..a0a2a847da --- /dev/null +++ b/docs/extensions/tizenx/guides/tizen-ui/layouts/grid.md @@ -0,0 +1,226 @@ + +# Grid + +## Overview + +- A layout that defines rows and columns of specific sizes and positions children within those specific rows and columns. + +## Measurement Rules + +- The size is determined based on the specifications defined in RowDefinitions and ColumnDefinitions using GridLength. + +## Placement Rules + +- Children are placed in the specific cell designated by their Row and Column indices. + +## Layout Options + +### Options set on the Grid + +#### RowDefinitions / ColumnDefinitions + +Manages the definitions for rows and columns. + +```csharp +grid.RowDefinition.Add(length); +grid.ColumnDefinitions.Add(length); +``` + +- Example: Using object initializer during instantiation. + +```csharp +new Grid { + RowDefinitions = { + 200, + GridLength.Start, + GridLength.Auto, + }, + ColumnDefinitions = { + GridLength.Start, + } +} +``` + +#### GridLength + +|GridLength| Description | +|-|-| +|`GridLength.Auto` | Measures the size of the View contained in the Cell and sets the Cell size to match it. | +|`GridLength.Star` | Expands the Cell to fill the remaining space in the Grid. | +|`float`| Sets the Cell size to a fixed numeric value. | + +#### ColumnSpacing + +Sets the distance between columns. + +```csharp +grid.ColumnSpacing = value; +``` + +#### RowSpacing + +Sets the distance between rows. + +```csharp +grid.RowSpacing = value; +``` + +![Grid spacing](./assets/grid_spacing.png) + +### Options set on the Child + +#### Row + +Selects the Row index where the child will be placed. + +#### Column + +Selects the Column index where the child will be placed. + +#### RowSpan + +Sets the number of Rows the child spans across. + +#### ColumnSpan + +Sets the number of Columns the child spans across. + +### Usage Examples + +#### Example 1 + +The Grid is fixed at 800x350. + +- Row Configuration: Set to 100, GridLength.Auto, and GridLength.Star. + - Row 0: Fixed at 100. + - Row 1: Set to Auto. Since the Blue View placed here has a height of 200, this row becomes 200. + - Row 2: Set to Star. It takes the remaining space (350 - 100 - 200), which results in 50. +- Column Configuration: Set to GridLength.Star, GridLength.Star. + - The total width of 800 is distributed equally, resulting in 400 for each column. +- Blue View: Since ColumnSpan is set to 2, it is placed across both columns. + + + + + + + + + + +
Code Behavior
+ +```csharp +new Grid +{ + DesiredWidth = 800, + DesiredHeight = 350, + BackgroundColor = Color.LightGray, + RowDefinitions = { 100, GridLength.Auto, GridLength.Star }, + ColumnDefinitions = { GridLength.Star, GridLength.Star }, + Children = + { + new View + { + BackgroundColor = Color.Red, + }.Row(0).Column(0), + new View + { + BackgroundColor = Color.LightPink, + }.Row(0).Column(1), + + new View + { + BackgroundColor = Color.Blue, + DesiredHeight = 200, + }.Row(1).Column(0).ColumnSpan(2), + new View + { + BackgroundColor = Color.Green, + }.Row(2).Column(0), + + new View + { + BackgroundColor = Color.LightBlue, + }.Row(2).Column(1), + } +} +``` + + ![Grid Example1](./assets/grid_example1.png)
+ +#### Example 2 + +- Row Configuration: Defined as Star and 10. + - With a total height of 100, two rows are created: one with a fixed height of 10, and the other taking the remaining height (90). +- Column Configuration: Defined as 4 Stars. + - The total width of 800 is divided by 4, resulting in 4 columns of 200 width each. +- LightGreen Views: RowSpan is set to 2, so they are placed to fill the entire height (spanning both rows). +- Indicator View: Set to Row(1) and Column(1). + - It is placed in the cell corresponding to the fixed height of 10 (2nd row) and the 2nd column. + - Since it shares the cell at Row 1, Column 1 with the LightGreen View, they are placed overlapping each other in that space. + + + + + + + + + + +
Code Behavior
+ +```csharp +new Grid +{ + DesiredWidth = 800, + DesiredHeight = 100, + BackgroundColor = Color.LightGray, + ColumnDefinitions = { + GridLength.Star, + GridLength.Star, + GridLength.Star, + GridLength.Star + }, + RowDefinitions = { + GridLength.Star, + 10 + }, + Children = + { + new View + { + BorderlineColor = Color.Black, + BorderlineWidth = 1, + BackgroundColor = Color.LightGreen, + }.Row(0).Column(0).RowSpan(2), + new View + { + BorderlineColor = Color.Black, + BorderlineWidth = 1, + BackgroundColor = Color.LightGreen, + }.Row(0).Column(1).RowSpan(2), + new View + { + BorderlineColor = Color.Black, + BorderlineWidth = 1, + BackgroundColor = Color.LightGreen, + }.Row(0).Column(2).RowSpan(2), + new View + { + BorderlineColor = Color.Black, + BorderlineWidth = 1, + BackgroundColor = Color.LightGreen, + }.Row(0).Column(3).RowSpan(2), + + // indicator + new View + { + BackgroundColor = Color.Black, + }.Row(1).Column(1), + } +} +``` + + ![Grid Example1](./assets/grid_example2.png)
\ No newline at end of file diff --git a/docs/extensions/tizenx/guides/tizen-ui/layouts/overview.md b/docs/extensions/tizenx/guides/tizen-ui/layouts/overview.md new file mode 100644 index 0000000000..49328cefd6 --- /dev/null +++ b/docs/extensions/tizenx/guides/tizen-ui/layouts/overview.md @@ -0,0 +1,92 @@ + +# Tizen.UI.Layout Overview + +## OVERVIEW + +**Layout** arranges and groups UI components in your application. + +- **AbsoluteLayout** is used to position and size using explicit values, or values relative to the size of the layout. +- **ScrollView** is a container capable of scrolling if its content requires. +- **HStack** organizes child views in a one-dimensional horizontal stack. +- **VStack** organizes child views in a one-dimensional vertical stack. +- **FlexBox** brings the similar capabilities of [CSS Flexible Box Layout](https://www.w3.org/TR/css-flexbox-1/). +- **Grid** is used for displaying elements in rows and columns. + +**Layout** delegates layout and measurement to a **LayoutManager**. + +- Each layout manager class implements the **ILayoutManager** interface. + +![Tizen.UI Layout Hierarchy](./assets/layout_hierarchy.png) + +## Layout Process + +**ILayoutManager** works in two phases – **`Measure()`** and **`ArrangeChildren()`**. + + ![Tizen.UI Layout Process](./assets/layout_process.png) + +### Basics + +#### Measure-based Layouts + +- Every View's size can be determined through the Measure process. +- Layouts themselves can also be measured. Unless a Layout has a fixed size explicitly set, it measures its Children to calculate the most optimal (fitting) size for itself. + +#### Properties to Avoid When Using Layouts + +When a View is added to a Layout, certain properties should not be used as the Layout system takes control over them. + +- `X`, `Y`, `Width`, `Height` + + Since the position and size are calculated and updated by the Layout, any manual values set for these properties will be overwritten by the Layout. + +- `WidthResizePolicy`, `HeightResizePolicy` + + These policies are designed to control sizing when a View is added to a standard ViewGroup. They are not applicable and are ignored when the View is added to a Layout. + +- `ParentOrigin`, `PivotPoint`, `PositionUsesPivotPoint` + + These properties alter the coordinate system of the View. Using them may cause the View to be rendered at a position different from the one calculated by the Layout. Therefore, they should be avoided to ensure correct placement. + +#### What is a RootLayout? + +- Conceptually, a RootLayout refers to a Layout whose parent is not another Layout. +- Unlike child layouts, a RootLayout's size is determined by: + - Manually setting the Width and Height. + - Automatically resizing via WidthResizePolicy or HeightResizePolicy when it is added to a ViewGroup or a Layer. +- While standard Layouts determine their size based on their children (Measure), a RootLayout's size is primarily defined by the external container (Layer or ViewGroup) it resides in and the applied ResizePolicy. + +### Step 1. Measure() + +- Calculates and returns the total size of the layout given the constraints. +- The total size of the layout is determined by its children. +- Measures for the layout are propagated in a chain to measures for the children. + +### Step2. ArrangeChildren() + +- Arranges children according to their measured size and returns the actual size of the layout. +- Unlike `Measure()`, it is not called in a chain. Simply places child view by setting their position or/and size. +- Once arranged, the native DALi engine triggers a Re-layout event to perform the required layout. + +## When is layout triggered? + +### Case 1. When the root layout is arranged + +- Starts the layout in response to a `Relayout` event raised by DALi(`ResizePolicy`) or manual size change. +- In the `Relayout` event handler, the view is measured according to the size assigned to it. +- After measuring all the sub-child views, arrange the child views. + +### Case 2. When the size of child view is changed + +- Changes in the size of children are notified by `MeasureInvalidated` event. + + ![Tizen.UI Layout Invalidated Process](./assets/layout_invalidate_process.png) + +> ℹ️ Even if the size of the child view is generated multiple times in one rendering loop, ensure that the layout can only be performed once per rendering loop. + +### Case 3. When the child view is added or removed + +- If the size of the layout or the arrangement of child views changes, layout will occurs. + +### Case 4. When the `UpdatedLayout()` is called by user + +- Call the Layout.UpdateLayout() to perform measure using the current view size and then arrange children. diff --git a/docs/extensions/tizenx/guides/tizen-ui/layouts/stack.md b/docs/extensions/tizenx/guides/tizen-ui/layouts/stack.md new file mode 100644 index 0000000000..e9a79cff51 --- /dev/null +++ b/docs/extensions/tizenx/guides/tizen-ui/layouts/stack.md @@ -0,0 +1,239 @@ + +# HStack & VStack + +## Overview + +- HStack: Arranges children sequentially in a horizontal line. +- VStack: Arranges children sequentially in a vertical line. + +## Measurement Rules + +- If the Layout size is not Fixed: + - Main Axis Size (Width for HStack, Height for VStack): Calculated as the sum of the Main Axis sizes of all children. + - Cross Axis Size (Height for HStack, Width for VStack): Determined by the child with the largest Cross Axis size. + + ![Stack Measurement Rules](./assets/stack_measure.png) + +## Placement Rules + +- The Layout measures the size of each child and places them sequentially along the Main Axis based on their measured size. +- Main Axis: Since space is allocated based on the child's measured size, there is no difference between the allocated spaces and the child's size. +- Cross Axis: Space is allocated based on the largest child in the stack. Therefore, the allocated space may be the larger than an individual child's size. This is where Cross-Axis Alignment is applied. + +## Layout Options + +### Option set on the Parent (Layout) + +#### Spacing + +Sets the gap between children. + +```csharp +stack.Spacing(value); +``` + +![Stack Spacing](./assets/stack_spacing.png) + +#### ItemAlignment + +Determines how to handle remaining space on the Main Axis. + +- Condition: The Layout's size must be fixed, and there must be remaining pace after placing all children. + +```csharp +stack.ItemAlignment(align); +``` + +![Stack ItemAlignment Start](./assets/stack_itemalignment_start.png) +![Stack ItemAlignment Center](./assets/stack_itemalignment_center.png) +![Stack ItemAlignment End](./assets/stack_itemalignment_end.png) + +### Options set on the Child + +#### Cross-Axis Alignment + +Determine how the child is positioned on the Cross Axis. + +- HStack: Uses VerticalLayoutAlignment. +- VStack: Uses HorizontalLayoutAlignment. + +```csharp +// For HStack +view.HorizontalLayoutAlignment(align); + +// For VStack +view.VerticalLayoutAlignment(align); +``` + +- Logic: As mentioned in the measurement rules, the stack's cross-axis size is determined by the largest child. Consequently, a child might be smaller than the stack's allocated cross-axis space. This option decides how to position the child within that extra space. +- Default Behavior: The default value is Fill. If not set, the child stretches to match the stack's cross-axis size. +- Exception: If DesiredHeight (for HStack) or DesiredWidth (for VStack) is explicitly set, the Fill option is ignored. The view retains its desired size and defaults to Center alignment. + +|Option|Description|Example| +|-|-|-| +|LayoutAlignment.Fill| Fill the entire area if possible. | ![LayoutAlignment Fill](./assets/stack_layoutalignment_fill.png) | +|LayoutAlignment.Start|Align with the leading edge of the available space, as determined by `View.LayoutDirection`. | ![LayoutAlignment Start](./assets/stack_layoutalignment_start.png) | +|LayoutAlignment.Center|The center of an alignment.| ![LayoutAlignment Center](./assets/stack_layoutalignment_center.png) | +|LayoutAlignment.End|Align with the trailing edge of the available space, as determined by `View.LayoutDirection` | ![LayoutAlignment End](./assets/stack_layoutalignment_end.png)| + +#### Expand + +An option to expand the child's size to fill the remaining space in the Main axis. + +- Conditions: The Stack must have a fixed size, and there must be extra space available after measuring all children. + +```csharp +view.Expand(); +view.Expand(2); +``` + +|No Expand | Expand first child | +|-|-| +|![image](./assets/stack_expand_none.png)|![image](./assets/stack_expand_first.png)| + +- Behavior: If Expand is set on two or more Views within the stack, the remaining space is distributed proportionally based on the values provided. If called without arguments, the default weight i 1. + +## Usage Examples + +### Basic Alignment + +- Green View: DesiredHeight is not set. The default VerticalLayoutAlignment (Fill) is applied, so it stretches to match the HStask's height. +- Yellow View: DesiredHeight is not set, but VerticalLayoutAlignment is set to Start. Therefore, it is positioned at the top. + + + + + + + + + + +
Code Behavior
+ +```csharp +new HStack +{ + DesiredWidth = 800, + DesiredHeight = 300, + BackgroundColor = Color.LightBlue, + Children = + { + new View + { + BackgroundColor = Color.Red, + DesiredHeight = 100, + DesiredWidth = 100, + }, + new View + { + BackgroundColor = Color.Green, + DesiredWidth = 300, + }, + + new View + { + BackgroundColor = Color.Yellow, + DesiredHeight = 150, + DesiredWidth = 200, + }.VerticalLayoutAlignment(LayoutAlignment.Start), + } +} +``` + + +![Stack Example: Basic Alignment](./assets/stack_example1.png) +
+ +### Using Expand + +- Green View: Expand is applied. +- Result: After accounting for the Red and Yellow view, all remaining width in the HStack is allocated to the Green View. + + + + + + + + + + +
Code Behavior
+ +```csharp +new HStack +{ + DesiredWidth = 800, + DesiredHeight = 300, + BackgroundColor = Color.LightBlue, + Children = + { + new View + { + BackgroundColor = Color.Red, + DesiredWidth = 100, + }, + new View + { + BackgroundColor = Color.Green, + }.Expand(), + new View + { + BackgroundColor = Color.Yellow, + DesiredWidth = 200, + }, + } +} +``` + +![Stack Example: Expand](./assets/stack_example2.png) +
+ +### Expand with DesiredSize & Alignment + +This example modifies Example 2 with two changes: the Green View ha DesiredWidth set to 100 and HorizontalLayoutAlignment (Main Axis alignment) set to Start. + +- Result: Due to Expand, the Green View is allocated the remaining space of the HStack. However, because a pecific DesiredWidth (100) is set, the View's actual content size creates a discrepancy with the allocated space. +- Alignment: Since the alignment is set to Start, the Green View sits at the beginnig of it allocated slot, leaving the reset of the expanded space as empty margin. +- Summary: Although the view received a large allocation of space (via Expand), it chose to render at its desired size and positioned itself at the start, leaving the rest of the allocated space empty. + + + + + + + + + + +
Code Behavior
+ +```csharp +new HStack +{ + DesiredWidth = 800, + DesiredHeight = 300, + BackgroundColor = Color.LightBlue, + Children = + { + new View + { + BackgroundColor = Color.Red, + DesiredWidth = 100, + }, + new View + { + BackgroundColor = Color.Green, + DesiredWidth = 100, + }.Expand().HorizontalLayoutAlignment(LayoutAlignment.Start), + new View + { + BackgroundColor = Color.Yellow, + DesiredWidth = 200, + }, + } +} +``` + + ![Stack Example: Expand with DesiredSize & Alignment](./assets/stack_example3.png)
\ No newline at end of file diff --git a/docs/extensions/tizenx/guides/tizen-ui/overview.md b/docs/extensions/tizenx/guides/tizen-ui/overview.md new file mode 100644 index 0000000000..19cf4a7ef6 --- /dev/null +++ b/docs/extensions/tizenx/guides/tizen-ui/overview.md @@ -0,0 +1,43 @@ +# Tizen.UI + +**Tizen.UI** is a lightweight, high-performance C# UI framework for building modern Tizen .NET applications. You can explore the full [API reference](https://pages.github.sec.samsung.net/NUI/Tizen.UI/api/) for a detailed look at all components. + +## Key Concepts + +Tizen.UI was engineered to be lighter and more performant by focusing on four key design principles. + +### 1. Slim View Hierarchy + +The framework provides a simpler and lighter view hierarchy than traditional frameworks. We provide only the essential APIs, reducing overhead and complexity. + +### 2. Enhanced Layout System + +Tizen.UI uses an efficient two-phase layout process: **Measure()** and **Arrange()**. This system optimizes layout passes by recalculating only within the scope of changes, leading to faster UI rendering. + +### 3. Effective Memory Management + +Performance is a core feature. Tizen.UI achieves this through several advanced memory management techniques: + +* **Minimized Reflection:** Reduces the use of expensive runtime reflection. +* **Optimized Data Objects:** Native and C# data objects are managed independently. C# data objects are represented as `structs` to avoid heap allocation. This means you can create and delete C# data objects frequently without incurring the cost of native object creation calls. +* **Object Pooling:** Objects created once (per type) are held in a pool and reused for subsequent creations. This pattern applies to objects that use the Stack, drastically reducing garbage collection. +* **Smart Lifecycle Management:** When a parent view is removed, it automatically removes all of its child views. This eliminates the need for developers to manually clean up the view tree in the `Dispose()` method of each component + +### 4. C# Markup (Declarative UI) +Tizen.UI includes a set of fluent helper methods and classes designed to simplify building declarative user interfaces directly in C# code, aligning with modern development patterns. + +## Modular Packages + +Tizen.UI is fully modular. You can include only the packages you need. + +* `Tizen.UI` +* `Tizen.UI.Components` +* `Tizen.UI.Components.Material` +* `Tizen.UI.Layouts` +* `Tizen.UI.Primitives2D` +* `Tizen.UI.Scene3D` +* `Tizen.UI.Skia` +* `Tizen.UI.Visuals` +* `Tizen.UI.Widget` +* `Tizen.UI.WindowBorder` +* `Tizen.UI.Tools` diff --git a/docs/extensions/tizenx/guides/tizenx-zlog/overview.md b/docs/extensions/tizenx/guides/tizenx-zlog/overview.md new file mode 100644 index 0000000000..a8c3175ec1 --- /dev/null +++ b/docs/extensions/tizenx/guides/tizenx-zlog/overview.md @@ -0,0 +1,30 @@ + +# TizenX.ZLog (Utility) + +**TizenX.ZLog** is a high-performance logging library designed specifically for performance-critical applications on Tizen. Its key feature is the **minimization of temporary string object creation** during logging operations, which significantly reduces garbage collector (GC) pressure. + +## Key Features + +### Zero-Allocation String Interpolation + +ZLog uses an advanced string interpolation method that avoids allocating temporary string objects on the heap. + +* **No Temporary Objects:** Drastically reduces GC pressure. +* **Memory Efficient:** Uses thread-local buffers for string building. +* **Stack-Based Allocation:** Utilizes stack allocation where possible. + +### Comprehensive Logging Levels + +ZLog supports all standard logging levels: + +* Verbose: Detailed debugging information +* Debug: Debug-level messages +* Info: General informational messages +* Warn: Warning conditions +* Error: Error conditions +* Fatal: Critical error conditions + +### Advanced Features + +* **Automatic Caller Info:** Automatically captures the file path, function name, and line number of the log call. +* **UTF-8 Encoding:** Full support for UTF-8 encoding in log messages. diff --git a/docs/extensions/tizenx/guides/toc.md b/docs/extensions/tizenx/guides/toc.md new file mode 100644 index 0000000000..d31184d7ff --- /dev/null +++ b/docs/extensions/tizenx/guides/toc.md @@ -0,0 +1,12 @@ +# [Overview](overview.md "source:https://github.com/Samung/tizen-docs/blob/add-tizenx/docs/extensions/tizenx/guides/overview.md tags:['TizenX', 'extension', 'library', 'Tizen.UI', 'TizenX.ZLog'], authors:['jh5.cho@samsung.com']") +# [Tizen.UI]() +## [Overview](tizen-ui/overview.md "source:https://github.com/Samsung/tizen-docs/blob/add-tizenx/docs/extensions/tizenx/guides/tizen-ui/overview.md tags:['TizenX', 'Tizen.UI']") +## [Getting Started](tizen-ui/getting-started.md "source: https://github.com/Samsung/tizen-docs/blob/add-tizenx/docs/extensions/tizenx/guides/tizen-ui/getting-started.md tags:['TizenX', 'Tizen.UI'], authors:['jh5.cho@samsung.com']") +## [Layouts]() +### [Overview](tizen-ui/layouts/overview.md "source: https://github.com/Samsung/tizen-docs/blob/add-tizenx/docs/extensions/tizenx/guides/tizen-ui/layouts/overview.md tags:['Tizen.UI', 'Layout'], authors:['jh5.cho@samsung.com']") +### [AbsoluteLayout](tizen-ui/layouts/aboluteLayout.md "source: https://github.com/Samsung/tizen-docs/blob/add-tizenx/docs/extensions/tizenx/guides/tizen-ui/layouts/aboluteLayout.md tags:['Tizen.UI', 'Layout', 'AboluteLayout'], authors:['jh5.cho@samsung.com']") +### [Grid](tizen-ui/layouts/grid.md "source: https://github.com/Samsung/tizen-docs/blob/add-tizenx/docs/extensions/tizenx/guides/tizen-ui/layouts/grid.md tags:['Tizen.UI', 'Layout', 'Grid'], authors:['jh5.cho@samsung.com']") +### [HStack&VStack](tizen-ui/layouts/stack.md "source: https://github.com/Samsung/tizen-docs/blob/add-tizenx/docs/extensions/tizenx/guides/tizen-ui/layouts/stack.md tags:['Tizen.UI', 'Layout', 'Stack', 'HStack', 'VStack'], authors:['jh5.cho@samsung.com']") +## [C# Markup](tizen-ui/csharp_markup.md "source: https://github.com/Samsung/tizen-docs/blob/add-tizenx/docs/extensions/tizenx/guides/tizen-ui/csharp_markup.md tags:['Tizen.UI', 'Markup'], authors:['jh5.cho@samsung.com']") +# [TizenX.ZLog]() +## [Overview](tizenx-zlog/overview.md "source:https://github.com/Samsung/tizen-docs/blob/add-tizenx/docs/extensions/tizenx/guides/tizenx-zlog/overview.md tags:['TizenX', 'TizenX.ZLog'], authors:['jh5.cho@samsung.com']") \ No newline at end of file diff --git a/docs/extensions/tizenx/overview.md b/docs/extensions/tizenx/overview.md new file mode 100644 index 0000000000..9a21f25d12 --- /dev/null +++ b/docs/extensions/tizenx/overview.md @@ -0,0 +1,28 @@ +# Tizen Extension Library + +## What is Tizen Extension Library? + +The Tizen eXtension Library (TizenX) is a collection of modular, open-source libraries that enhance and extend the Tizen platform. + +Unlike built-in platform APIs, TizenX libraries are unbundled from the operating system and delivered **independently via NuGet**. This approach allows developers to adopt new features, UI components, and performance improvements at their own pace, free from the long OS update cycle. + +> **Extend. Experience. Evolve.** + +TizenX provides you with ready-to-use components, productivity tools, and pre-integrated functionalities that simplify app development and boost performance. + +## Why TizenX? + + * **Modern .NET Design** + All libraries comply with the .NET Design Guidelines and follow the latest architectural patterns. + + * **Performance and Optimization** + Benefit from built-in memory and performance optimizations designed for the Tizen platform. + + * **Enhanced Productivity** + Build apps faster with commercial-level UI components, declarative UI helpers, enhanced layouts, and powerful development tools. + + * **Flexible and Modular** + TizenX is divided into independent modules. You can include only the libraries you need, keeping your application lightweight. + + * **Rapid Updates** + Receive the latest features and bug fixes through NuGet without waiting for a new Tizen OS release.