Xamarin.forms: [Spec] RefreshView

[samhouts]

RefreshView

Part of CollectionView

Represents a container control that provides refresh functionality for its content.

API

public class RefreshView : ContentView
{
    public static readonly BindableProperty CommandProperty;
    public ICommand Command { get; set; }

    public static readonly BindableProperty CommandParameterProperty;
    public object CommandParameter { get; set; }

    public static readonly BindableProperty IsEnabledProperty;
    public bool IsEnabled { get; set; }

    public bool IsRefreshing { get; set; }

    public Color BackgroundColor {get; set;}
    public Color RefreshColor {get; set;}
}

UWP Platform Specific

UWP is the only platform that has this concept implemented natively so for now we will just implement a platform specific for UWP users that won't to be able to change this

```C#
public enum RefreshPullDirection PullDirection

### Properties

| API | Description |
| ------------- | ------------- |
| Command | Gets or sets the command to execute when this item is invoked. |
| CommandParameter | Optional parameter passed to the refresh command. |
| IsEnabled | Gets or sets a value indicating whether the user can interact with RefreshView. |
| IsRefreshing | This indicates the current state of the refresh control. Developers will need to set this back to false to indicate that a refresh has completed. If this is set to true it will trigger the command and the refresh visualization on the platform. This will automatically transition to true when the user has performed the required actions to trigger the platforms Refresh Control |
| BackgroundColor | iOS - Background Color of the UIView that contains the progress circle. Android- Background Color of the progress circle  | 
| RefreshColor| Color of the circle itself | 

## RefreshPullDirection

```csharp
public enum RefreshPullDirection
{
    LeftToRight,
    TopToBottom,
    RightToLeft,    
    BottomToTop
}

Enum Values

| API | Description | Notes |
| ------------- | ------------- | ------------- |
| LeftToRight | The user must pull from left to right to refresh. | May be pushed to a future phase. |
| TopToBottom | The user must pull from top to bottom to refresh. | |
| RightToLeft | The user must pull from right to left to refresh. | May be pushed to a future phase. |
| BottomToTop | The user must pull from bottom to top to refresh. | May be pushed to a future phase. |

Examples

<RefreshView BackgroundColor="Green" RefreshColor="Pink">

UWP

Android

iOS

[adrianknight89]

@samhouts I think we need a ticket for header and footer implementation as well.

Should #5142 be closed?

Isn't IsEnabled part of ContentView already?

[hanchhanch]

Where is it available?
I have Xamarin.Forms v4.0.0.394984-pre10 and this type cannot be resolved.
Other than that, is this page the only available information on this secret type?
without which the new collectionView is close to unusable...

[adrianknight89]

@hanchhanch It hasn't been worked on yet, and I agree that without a refresh view, CollectionView is unusable for production. I hope that it can be worked on soon.

@samhouts @hartez Regarding RefreshPullDirection, why would anyone want to pull from right to left or bottom to top? I couldn't think of a reason for using these.

[samhouts]

Bottom to top, refresh a chat or log that loads bottom in? Right to left, customized localization?

[MarcelWinkelEBF]

@hanchhanch @adrianknight89 for me it was a little bit of a surprise that the RefreshView is not implemented yet. We switched to the CollectionView because we are using some stuff that was looking to be easier with the CollectionView. After switching we found some issues with the CV and although the missing RefreshView. For now we are using the Pull To Refresh vom Syncfusion since still have a license until we can switch completly to Xamarin Controls. Maybe it's an alternative for you to.

[adrianknight89]

@MarcelWinkelEBF Have you documented those issues on here? It'd be great to know what they are so they can be fixed.

[hanchhanch]

Thanks @MarcelWinkelEBF , we also use PullToRefresh separately (https://www.nuget.org/packages/Refractored.XamForms.PullToRefresh/)

[MarcelWinkelEBF]

@adrianknight89 we had some issues but mostly they are already reported.

1. Changing the ItemsLayout dynamically is not working. So we have to re-create the CV in C# everytime the layout changes. I know I have seen a Github issue somewhere but by now I'm not able to find it anymore.

2. https://github.com/xamarin/Xamarin.Forms/issues/6158
   This was also an issue but for now I think the SelectedItem = null is working. Anyway in our case it looks like there is one more issue. We will make a toggle between multi and single selection and from what I found out is that the cleaning of the selection list is causing an Exception: ArgumentOutOfRangeException

3. Another excetion: SIGABRT: Cannot access a disposed object. Object name: 'SelectableItemsViewController'.
   But this happens while navigating. So I'm still checking this one because I think this is more on my side.

4. Grouping is missing, but I saw today that there is already a suggestion in the main thread.

5. https://github.com/xamarin/Xamarin.Forms/issues/6126

6. https://github.com/xamarin/Xamarin.Forms/pull/6085 somehow like point 2

7. My CollectionView creates more items to "display" than it should. So the count is higher than my ItemsSource but this is just happening as a list. This seems to be an issue with a combination of Grid / StackLayout / CV. Now I'm calculating the hight depending of the ItemsSource count and it's looking good. For this one I should create an issue when I have time to re-write the code to get to this behavior.

In general mostly all issues can be ignored as long as I re-create a CV with the specific configuration. But since the issues are discused I guess it will be figured out in some future versions.

[adrianknight89]

@samhouts I'm somewhat confused by RefreshVisualizationState. If I hold and swipe down without lifting my finger, the refresh indicator is supposed to be gradually changing with each delta change on the y axis. At least, this is how ListView functions today. In this scenario, is RefreshVisualizationState supposed to be Idle or Active?

[hartez]

It's Idle if the rendering control is not currently refreshing, and Active if the rendering control is currently refreshing. There's no provision in this spec for any intermediate states.

In a later phase of development, we may do something closer to UWP's RefreshVisualizerState if we can reasonably map the other platforms' states (UIRefreshControl and SwipeRefreshLayout don't have that level of granularity by default). Or we may simply provide a delta value and let folks react to the distance the control has been pulled.

[PureWeen]

API Updates

• Removed VisualizationState for now as this concept only exists on UWP and even there it's readonly
• Added IsRefreshing as the way to modify the state of the refresh control and flip it back to a non refreshing state visually
• Moved PullDirection to a platform specific UWP property because that's the only platform this concept exists natively. We will look at adding this to all platforms at a later date if the need is there
• Added a BackgroundColor and RefreshColor to let users customize the color a bit

[adrianknight89]

@PureWeen If we can create a truly custom refresh view like this one, then do we need the BackgroundColor and RefreshColor? RefreshView is already a ContentView, so BackgroundColor should be available. RefreshColor can be a custom implementation as part of the nested child.

[PureWeen]

Added pictures for the color APIs

@adrianknight89

RefreshView is already a ContentView, so BackgroundColor should be available

It is. I only list it as part of the API so we can indicate what it will do with respect to this control

If we can create a truly custom refresh view

Eventually we will look at adding a ContentView API <RefreshView.Content

But for now I think just having basic coloring properties for simple customization is useful. The coloring properties have a pretty one to one mapping to properties natively.

Android has setProgressBackgroundColor and setProgressBackgroundColorSchemeColor
UWP is just setting Foreground/Background on the RefreshVisualizer
iOS is setting the BackgroundColor and TintColor

[arsoftcr]

is not there a way to do the pull to refresh from bottom to top instead of top to bottom yet?

[brminnick]

@arsoftcr It is currently available on Windows.

From the RefreshView spec:

UWP is the only platform that has this concept implemented natively so for now we will just implement a platform specific for UWP users that won't to be able to change this

Set RefreshView.RefreshPullDirection to BottomToTop: https://docs.microsoft.com/xamarin/xamarin-forms/platform/windows/refreshview-pulldirection