# vlayout

**Repository Path**: HarmonyOS-tpc/vlayout

## Basic Information

- **Project Name**: vlayout
- **Description**: Project vlayout is a powerful LayoutManager extension for ListContainer, it provides a group of layouts for ListContainer
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2021-04-01
- **Last Updated**: 2023-04-17

## Categories & Tags

**Categories**: harmonyos-layout

**Tags**: None

## README

## vlayout

## Introduction
Project vlayout is a powerful LayoutManager extension for ListContainer, it provides a group of layouts for ListContainer. 
Make it able to handle a complicate situation when grid, list and other layouts in the same listContainer.

By providing a custom LayoutManager to ListContainer, VirtualLayout is able to layout child views with different style at single view elegantly.
The custom LayoutManager manages a serial of layoutHelpers where each one implements the specific layout logic for a certain position range items.
By the way, implementing our custom layoutHelper and providing it to the framework is also supported.

## Usage Instructions

1) Initialize LayoutManager :
```
ListContainer listContainer = (ListContainer) findComponentById(ResourceTable.Id_list_container);
VirtualLayoutManager virtualLayoutManager = new VirtualLayoutManager(this);
```
2) Use addAdapters to add layoutHelper data :
We can use DelegateAdapter for as a root adapter to make combination of our own adapters. Just make it extend DelegateAdapter.Adapter and overrides onCreateLayoutHelper method.
```
DelegateAdapter delegateAdapter = new DelegateAdapter(virtualLayoutManager);

// Then we can set sub- adapters
GridLayoutHelper layoutHelper = new GridLayoutHelper(2,2,shapeElement1,250);
adapterList.add(new SubAdapter(this, layoutHelper, 2));
adapterList.add(new SubAdapter(new GridLayoutHelper(3, 120,shapeElement1,2000)));

delegateAdapter.addAdapters(adapterList);
listContainer.setItemProvider(delegateAdapter);
```
3) OR Use setLayoutHelpers to set layoutHelper data : Another way to populate LayoutHelpers in ListContainer by below way :
```
 final List<LayoutHelper> helpers = new LinkedList<>();
 final GridLayoutHelper gridLayoutHelper = new GridLayoutHelper(4, 28, shapeElement1, shapeElement2,250);
 helpers.add(DefaultLayoutHelper.newHelper(7, shapeElement1, shapeElement2, 250));
 helpers.add(gridLayoutHelper);
 layoutManager.setLayoutHelpers(helpers);
```

4) Use VirtualLayoutAdapter directly instead of DelegateAdapter :
We can use setLayoutHelpers to populate list of helpers holding instance of different layoutHelpers and control will directly go to
VirtualLayoutManager using layoutManager.getComponent(position, component, componentContainer) in getComponent which is
overrided method of VirtualLayoutAdapter as shown below :
```
   listContainer.setItemProvider(new VirtualLayoutAdapter(layoutManager) {
     @Override
     public Component getComponent(int position, Component component, ComponentContainer componentContainer) {
            return layoutManager.getComponent(position, component, componentContainer);
     }
```
5) Supporting Image data using vlayout : If user want to set image data to any LayoutHelper then user need to pass below extra members of BaseLayoutHelper from application to vlayout lib :
```         
mLayoutHelper.viewImage = ResourceTable.Media_author;   //where mLayoutHelper.viewImage is actual image resource id present in media folder
mLayoutHelper.viewType = "Image";  //where mLayoutHelper.viewType should be "Image" in case of Image Component, for Text Component no need to pass anything or use this member.
```
Note: Currently not supporting array of images to be set in Image component.

Features
Added Support for

1.0.0
Initial Release

DebugAbilitySlice :

Supported Features:
1) LinearLayoutHelper
2) GridLayoutHelper

Not Supported Features:
1) StickyLayoutHelper
2) FixLayoutHelper

MainAbilitySlice :

Supported Features:
1) GridLayoutHelper
2) LinearLayoutHelper
3) DefaultLayoutHelper

Not Supported Features:
1) ScrollFixLayoutHelper

OnePlusNLayoutAbilitySlice :

Supported Features:
1) LinearLayoutHelper
2) GridLayoutHelper
3) OnePlusNLayoutHelper
4) OnePlusNLayoutHelperEx
5) Banner

Not Supported Features:
1) StickyLayoutHelper
2) ScrollFixLayoutHelper

TestAbilitySlice :

Supported Features:
1) GridLayoutHelper

VlayoutAbilitySlice :

Supported Features:
1) LinearLayoutHelper
2) SingleLayoutHelper
3) GridLayoutHelper
4) ColumnLayoutHelper
5) OnePlusNLayoutHelper
6) OnePlusNLayoutHelperEx
7) StaggeredGridLayoutHelper
8) BannerLayout
9) RangeGridLayoutHelper

Not Supported Features:
1) FloatLayoutHelper
2) StickyLayoutHelper
3) FixLayoutHelper
4) ScrollFixLayoutHelper

Unsupported features within app : Due to unavailability of recyclerview and current support of ListContainer in openharmony mentioned features
                                  are not supported (FloatLayoutHelper, StickyLayoutHelper, FixLayoutHelper, ScrollFixLayoutHelper) and we have below limitations :
1) StaggeredGridLayout child's can be drawn upto the screen visibility.
2) GridLayoutHelper must have the number of  childs according to the span so that it can fill the width. Otherwise empty spaces will be created.
3) Jump to functionality will treat some set of child's as a single child(ex: in grid one row will be treated as single element)
4) Numbering is given based on the layouts(each layouts will start from 0)
5) Jump functionality not handled for all Cases(same as original)
6) Orientation changes are not supported.(layout/device orientation)
7) Individual child view margins arrangement using setMargins api not supported.
8) RangeGridLayoutHelper : If we pass incorrect range (i.e. exceeding range more than total items) then it will draw all components defined in that object
    from staring point to end point and if we increase setWeight array elements more than span count then behaviour can be miscellaneous.
    SetHGap and SetVGap not supported.

Notes:
1) Test Ability actual scenario is made with support of original lib without using library component. Here we have prepared using GridLayoutHelper.
2) Current layout and orientations are set based on the original behaviour. Additional testing of these view are not done.
3) Colors and Margins will have slight differences from original .
4) Banner layout is same as LinearLayout. So no changes kept to separate it.

## Installation Instructions
```
Method 1: Generate har package from library and add it to lib folder.
       add following code to gradle of entry
       
       implementation fileTree(dir: 'libs', include: ['*.jar', '*.har'])
       
Method 2:
    allprojects{
        repositories{
            mavenCentral()
        }
    }
    implementation 'io.openharmony.tpc.thirdlib:vlayout:1.0.0'
```

##  License :
Vlayout is available under the MIT license.