Git Product home page Git Product logo

surface-duo-sdk-xamarin-samples's Introduction

page_type name languages products description urlFragment
sample
Surface Duo - Xamarin SDK samples
csharp
surface-duo
xamarin
Samples showing how to use the Surface Duo SDK to achieve dual-screen user interface patterns using Xamarin and Xamarin.Forms.
all

Surface Duo - Xamarin SDK samples

This repository contains Xamarin.Android and Xamarin.Forms samples for Surface Duo, all accessible from a single Visual Studio solution. The samples covers all dual-screen app patterns from Microsoft docs.

Get Started

To learn how to load your app on to emulator, and to use it, refer to the Surface Duo developer docs and Xamarin.Forms dual-screen docs.

Prerequisites

Before running the samples, be sure that you have the following items installed on and attached to your computer:

Contents

This repository features native Xamarin.Android and Xamarin.Forms samples for different approaches how to work with two screens.

Be sure the Surface Duo emulator is already running or your device is attached to your computer. Select the target of your choicet from the Visual Studio device list before running the sample.

The Surface Duo 2 emulator will appear as <build> (Android 11.0 - API 30).

Xamarin.Android

The Xamarin.Android samples all use the Xamarin.AndroidX.Window.WindowJava NuGet, which exposes the Jetpack Window Manager package for dual-screen and foldable support on Surface Duo and other devices.

Every sample of Xamarin.Android is a runnable project. To start for example the CampanionPane sample, expand the Xamarin.Android Native folder and set the related sample as Startup project.

Xamarin.Android Surface Duo Companion view sample screenshot

CompanionPane

The companion pane pattern is a great opportunity to take advantage of added screen real-estate by taking second-level surfaces that are otherwise hidden and exposing them when the app is spanned.

DragAndDrop

Support for drag-and-drop ensures a great user experience using all the different input types supported by the Surface Duo.

This sample demonstrates how to implement drag-and drop in your Android app, following the Android drag and drop guidance.

DualView

Having two screens provides a natural affordance to compare and contrast two versions of the same type of content side-by-side, like two images, lists, or documents.

It can also be used to show the same information in two different ways at the same time, with each screen working seamlessly to provide more information to the user. For example, a list of restaurants on one screen, and a map with locations on the other.

ExtendedCanvas

The extended canvas pattern is the simplest dual-screen pattern, but it's powerful. You may consider this pattern if you need a bigger canvas for a task such as drawing, or if your app has a free-flowing canvas that the user can freely scroll to avoid the seam if some important content is obscured. This provides the benefit of giving your app more screen real-estate, rather than constricting it to one screen or another.

This pattern only applies to the canvas portion of the UI. You may still need to use one of the other techniques to accommodate the seam if it will obscure the non-canvas portion of the app.

IntentToSecondScreen

This sample demonstrates how to cause an activity to open on the second screen (as long as it's empty, otherwise the activity will launch over the current one).

In the main activity, choose an option to start: another activity from the current app or a URL in a browser window:

ListDetail

The list-detail pattern has a main pane (usually with a list view) and a details pane for content. When an item in the list is selected, the details pane is updated. This pattern is naturally good for when you have a wider viewing area. It is frequently used for email and address books.

Taking advantage of the two distinct screens and snapping to the natural boundary, you could use one screen to show the "items" list and the other to show details of the selected item.

TwoPage

Some apps naturally tend to a book-like paging experience. You can use the natural boundary to show several items from a collection -like pages or pictures - which otherwise might have required the user to view one at a time.

Depending on your app, you could decide to paginate per 2 pages or advance one page at a time.

WindowManager

Visit the Jetpack Window Manager for Xamarin docs for more information on using Jetpack Window Manager in your apps.

Xamarin.Forms

The Xamarin.Forms samples all use the Xamarin.Forms.DualScreen NuGet, which exposes the underlying Xamarin.DuoSDK NuGet that only works on Surface Duo devices.

All samples on how to use the SDK using Xamarin.Forms are in one sample app. Expand the solution's Xamarin.Forms folder and ensure the DualScreenDemos.Android project is the startup project.

Xamarin.Forms Surface Duo Sample App Screenshot with list of all included examples

TwoPane

The TwoPaneView playground lets you experiment with the different layout options it supports. Read the TwoPaneView docs for details on how to control the layout.

CompanionPane

The companion pane pattern is a great opportunity to take advantage of added screen real-estate by taking second-level surfaces that are otherwise hidden and exposing them when the app is spanned.

DualView

Having two screens provides a natural affordance to compare and contrast two versions of the same type of content side-by-side, like two images, lists, or documents.

It can also be used to show the same information in two different ways at the same time, with each screen working seamlessly to provide more information to the user. For example, a list of restaurants on one screen, and a map with locations on the other.

and many more

The sample itself uses diffrent controls itself that brings the unique features of dual screen devices to life. Other examples are focuses on diffrent APIs like the Xamarin.Forms DualScreenInfo API. Read the Microsoft docs article for further information.

(Optional) Add API keys

To use the DualView and ExtendCanvas samples, you will first need to create an Google Map API key. Follow the instructions outlined here to create an API key.

After you have an API key, put it in the following files:

  • DualView/Resources/Assets/googlemap.html
  • ExtendCanvas/Resources/Assets/googlemapsearch.html
  • XamarinForms/Xamarin.Duo.Forms.Samples.Android/Assets/googlemap.html
  • XamarinForms/Xamarin.Duo.Forms.Samples.Android/Assets/googlemapsearch.html

By replacing YOUR_API_KEY string with your actual key the map views will be displayed.

Related links

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.

When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.

surface-duo-sdk-xamarin-samples's People

Contributors

conceptdev avatar dependabot[bot] avatar microsoftopensource avatar pureween avatar redth avatar tscholze avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

surface-duo-sdk-xamarin-samples's Issues

Can't select Surface Duo emulator in Visual Studio for Mac.

Hi,

I'm trying to run the Xamarin.Forms sample on my Android Surface Duo emulator running in the background. When I go to make the selection for the emulator, after I select it, it default back to the other AVD device I have saved instead. It doesn't like it when I select the emulator. I haven't tested it where if I delete the other AVD, if it just default onto itself but this is a bug.

EDIT: After exiting VS and playing around with the selector, I got it to correctly default to the right one and it works. Idk if this still considered a bug worth an investigation into or not however? Looks like maybe that happens on first time trying to default to the emulator?

[Proposal] Update readme.md with more detailed explanations and helpful resources for interested developers

With this issue, I want to propose changes to the README.me file of the Surface Duo Xamarin samples.

Motivation

In my opinion, the current readme does not show all the effort the team puts into the SDK and the samples for Xamarin apps.
With just some wording changes or re-structuring of the Readme-filemaybe more interested developers could be motivated to try out the samples.

In comparison to the Readme files of its sister repositories, the Xamarin one lacks different kinds of information.

Ideas for enhancements

Extend Getting Started

It seems to be standard that sample projects list what’s required to get started in a simple bullet point list without the need of reading documentation first.
The modern Microsoft does not longer require Windows or paied apps to get started. This could be too “beginner”-ish but I would not harm.

With the release of the beta versions of Visual Studio 2022 it would maybe more helpful to state that the samples best work currently in Visual Studio 2019 – if this is true.

Sample content and structure

Furthermore, the great quality of the sample app could be highlighted by providing a detailed list of explanations about the different included view samples. This could be done by simply linking the Readme-file of each project or in addition to this with further information in which use case which view project could be used as inspiration. This could be achieved by simple linking the related Microsoft Docs article (design) introduction to dual-screen devices.

Personal note:
It was a bit irritating what the actual difference between is between “Dual View” and “Dual Page”.
This kind of information are already available at the GitHub compose sample.

Xamarin.Forms & Xamarin.Android

At the beginning it was a little bit hard to understand that this is a Xamarin.Android and Xamarin.Forms sample repository. I know that the current Readme contains a section that describes this circumstance. Nevertheless, it could be more obvious that both “worlds” are included in this sample app. I would go that far that the very first headline could be changed to “Surface Duo – Xamarin.Forms & Xamarin.Android SDK samples”.

Add links to streams, blogs, and social media

The Surface Duo SDK team does a really good job in spreading out the word and trying to engage new developers to join the dual screen side of app development.

To support this effort the Readme could also include:

  • Surface Duo Dev Twitch account with timetable
  • Surface Duo Dev blog
  • Surface Duo Getting Started Docs page
  • Surface Duo Dev Twitter account

Additional ideas:

  • Team member’s Twitter account with information why to follow (Cesar = Kotlin expert)
  • Well-known dual screen app Xamarin developers Twitter or GitHub accounts
  • YouTube links BUILD sessions or DroidCon talks

All I want to show with such section is, that the dual screen developer community is small but striving and growing.

Unify “Related links” across all Surface Duo sample repositories

Add more information that are already included in other sample repositories. One of the missing sections are “CI build status badges” or for example the “Related links” section.

Other small details

As everywhere else there is room for improvement outside the suggest ideas of enhancements. For example, to align the screenshots all the same. Another low hanging fruit would be (outside of the readme but visible to the repositories’ visitor) to enable or disable GitHub features. The Wiki button just redirects to the Readme and other sample repos use the “Release” feature of GitHub, the Xamarin’s one seems not to facilitate this feature.

Are community contributions are welcomed? (includes list of possible enhancements)

Hi team,
Are community contributions to this repository is welcomed? Or will the source change dramatically in the near future?

Ideas
I have the following enhancements in mind:

  • Unify code formatting
    • Removing unused imports
    • Removing duplicated line spaces
    • This would help to „read“ the lib classes
  • Add documentation to the Surface Duo related library classes like TwoPaneView, both of the services, etc.
    • E.g what does the height or witch configuration enum values mean in detail (which value is related to which pane configuration?)
    • Add relationship diagram how the lib classes works together
    • DuoPage has FormsWindow which contains the LayoutService that relies on a working dependency injected member
  • Add „how to get started“ section which classes you have to use for your own project
    • Platform specific dependency classes and unit of them (MainActivity.cs changes)
  • Improve services to work in other apps
    • E.g. Make isDuo property public accessible

Contact
If anyone wants to chat wit me about this topic, tweet me @tobonaut on Twitter. :)

Update samples to use Jetpack Window Manager stable

Window Manager is an API that provides information about dual-screen and foldable display features, that work not just for Surface Duo but also devices from other OEMs.

There is a pre-release binding available on NuGet - Xamarin.AndroidX.Window - which has been implemented in the Xamarin.Android samples in this repo.

We've our updated docs and blog.

Pre-requisites

This issue relies on Google releasing the stable version of Jetpack Window Manager.

Google reference

There is documentation, a blog post, and a codelab on how to use it in Kotlin.

Xamarin.Forms

This applies to the Xamarin.Android samples in this repo. The Xamarin.Forms samples will require Window Manager to be incorporated into the Xamarin.Forms.DualScreen NuGet package, which is a separate task.

Update samples to use Jetpack Window Manager beta

Window Manager is an API that provides information about dual-screen and foldable display features, that work not just for Surface Duo but also devices from other OEMs.

There is a pre-release binding available on NuGet - Xamarin.AndroidX.Window - that exposes the functionality in the alpha versions of Window Manager on Android. There is documentation, a blog post, and a codelab on how to use it in Kotlin.

This applies to the Xamarin.Android samples in this repo. The Xamarin.Forms samples will require Window Manager to be incorporated into the Xamarin.Forms.DualScreen NuGet package, which is a separate task.

[Feature request] Introduce helper to determine if an Xamarin.Forms app runs on a Duo device

Idea

The large screens of the Duo are able to present more information than any other "single" screen Android device.
That's why I need to know if the app is running on a Surface Duo or not. In my optionen, please correct me if this feature already exists, a simple member provided by the SDK that indicatates if it is running on a Duo would be great.

Example extension

public static class DualScreenInfoExtensions
{
    public static bool IsDuo(this DualScreenInfo dualScreenInfo)
    {
        return DualScreenInfo.Current.HingeBounds.Width != 0;
     }
}
 

Example usage

For example to show a multi column layout for "is a Duo" and a single column layout for "is not a Duo"

if(DualScreenInfo.Current.IsDuo())
{
    SecondColumnWidth = new GridLength(1, GridUnitType.Star);
}
else
{
    SecondColumnWidth = new GridLength(0, GridUnitType.Absolute);
}

TechCommunity
I also opened a post in the official Surface Duo SDK TechCommunity forum.

For DEVs

There are 50,000 flutter apps in both the iOS and Android store. What you saw was your own ignorance (not meant as an insult) of the technology. It works VERY well for iOS, Android and now macOS (with the majority of those apps getting ported to macOS almost immediately giving macOS the major win that Windows needs right now)

Web is about to go mainline and works very well too. As of June 25th you can write for iOS, Android, macOS and Web from one environment by simply learning Dart. (And yes, it supports essentially everything that Xamarin Forms does but with a pixel perfect renderer on all platforms)

The weaknesses of flutter are:

Some plugins haven't yet been ported to Web. They're coming quickly however.
Dart is not nearly the language that C# is.
Flutter doesn't have the Xamarin eco-system for Simulators, and compile to store etc. that Xamarin does.
Windows support is still lacking.
Linux support is still lacking.
There literally are no other downsides. I've built the same app in Xamarin and flutter and the flutter app looks way better, functions way better and is more stable. The development environment though limited is also way more stable.

#1 is just a time thing.
#2 The flutter rendering engine is C++ code and ANY language can be hooked to it. @SteveSandersonMS did a POC of Blazor running against flutter. That work needs to be taken seriously and made into a full project. There's 0 reason why C# can't be used with flutter and it would give flutter a vastly better development experience.
#3 All of Xamarin tools could come over easily with the remote simulators etc. This is just a decision by MS. If you recall they had these working for Cordova before they dumped cordova support in VS.net. So it's already there and could easily be extended and publish to the stores is already there and just needs the blazor tooling.
#4 This is on MS. Google has asked in a blog post for help from Microsoft. Microsoft has provided support for Duo in Flutter recently. If MS added Windows support and the ability to write plugins in C# UWP instead of having to use win32 and C++ Flutter's Windows ecosystem would flurish quickly because of the massively larger developer pool.
#5. Not sure this even matters.

I'm a Microsoft guy. I love C#. It's by far the best development language made. XAML is another story but I'm going to ignore it for now. I would much rather never have touched Dart. It's a lame language that google created to compete with C# and Typescript and prove that they could make it more simple and in the process made most things more difficult.

I would very much love to see Microsoft succeed. But their current approach of project reunion is a fool's errand. With the exception of games and some highly specialized tools that require realtime responsiveness/low level hardware, Windows development on its current track is an ever shrinking market and reunion doesn't change that or give MS any new opportunities to expand that. Windows has quickly become a web browser with Office. Office is literally the only reason why most companies haven't switched to chromebooks or linux on desktops. Maui is just more of the same Xamarin that has proven to be a complete flop. Xamarin forms in specific is a mess. It's so bad that in 2019 they went 3 months without a build of visual studio that could
compile to all 3 stores at the same time because of bugs. Exactly 3 people even watched the bug reports. Changing the name and providing a syntax more similar to Flutter without the rendering engine that flutter provides is a pointless waste of resources because it still won't be used.

By adopting the flutter rendering engine and bolting on C# like dart is right now and then providing all of the tools necessary so that a dev never needs to own a Mac Microsoft has the opportunity to win BIGLY. And they have the opportunity to have their competitor do work for them. That means Duo and Neo get an app ecosystem and become relevant, and it means that Windows app development has a chance again.

Four UX samples don't respond to app-spanning

When you span CompanionPane, DualView, MasterDetail, TwoPage they don't adapt to both screens 😟

For example, this view takes up both screens when it should adapt to being spanned:

companion-pane-bug

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.