docs-maui
docs-maui copied to clipboard
dotnet
Clarify ICanvas and GraphicsView
This documentation is terrible! Following it only leads to confusion, dead-ends, and frustration.
Stop abusing your readers by sending them into page linking hell! Discuss the ICanvas in the context of GraphicsView and vice-versa on the same page instead of cross-linking back and forth. They are related and inseparable, so why separate them when discussing them?
Your examples are utterly useless. We know how to draw, but we want to know where to draw. There's not a single complete example on the page! Just snippets of drawing code without context! Do you expect your reader to reconstruct the samples? Where do they go? Fortunately, some of us have prior experience with graphics libraries.
public class MyGraphics : IDrawable
{
// Put your drawing code in here!
public void Draw(ICanvas canvas, RectF dirtyRect)
{
canvas.StrokeColor = Colors.GreenYellow;
canvas.StrokeSize = 6;
canvas.DrawLine(10, 10, 90, 100);
}
}
Finally, why are you telling us to Invalidate() the canvas when it's not necessary?:
"GraphicsView has an Invalidate method that informs the canvas that it needs to redraw itself. This method must be invoked on a GraphicsView instance:"
graphicsView.Invalidate();
Assume for it is necessary, where do we obtain a reference to graphics view and, once again, where do we perform the Invalidate()?
There's simply no excuse for such a poor documentation.
Document Details
⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.
- ID: 2deb823c-ccc8-fdef-6cf8-bb70a2c21939
- Version Independent ID: 2deb823c-ccc8-fdef-6cf8-bb70a2c21939
- Content: .NET MAUI GraphicsView - .NET MAUI
- Content Source: docs/user-interface/controls/graphicsview.md
- Product: dotnet-mobile
- Technology: dotnet-maui
- GitHub Login: @davidbritch
- Microsoft Alias: dabritch
Hi. I'm sorry that the article isn't helping you, and I would like to help make it better. I do believe there are a few things we can do to make this article more useful. Some of the ideas I have are:
-
The intro could explain the relationship between
GraphicsView,IDrawable, andICanvasbetter, this may help conceptually understand how this all works. -
The
Create a GraphicsViewsection could be clarified, even the header. And progression steps should be provided, (1) Create the drawable, what does it do? (2) create aGraphicsViewcontrol (3) tell the control what it draws by associating the drawable with the view.
I would also love to understand what drove you to this article. What were you trying to figure out exactly? Just a basic "draw custom stuff on the screen" or something more advanced?
To talk directly to some of your points:
Discuss the ICanvas in the context of GraphicsView
I wouldn't categorize this as linking hell, there are only three links on the page, two of them are to the same destination: the giant article describing how to use the canvas to draw.
Where to draw
Your examples are utterly useless. We know how to draw, but we want to know where to draw.
The section Position and size graphical objects describes where the canvas is drawing to on the screen:
DOC: The location and size of the ICanvas on a page can be determined by examining properties of the RectF argument in the Draw method. ........... These properties can be used to position and size graphical objects on the ICanvas. For example, graphical objects can be placed at the center of the Canvas by using the Center.X and Center.Y values as arguments to a drawing method.
Invalidate
Finally, why are you telling us to Invalidate() the canvas when it's not necessary?
I agree, this section could contain more information about when invalidate is called automatically and when you would be required to call it manually. The GraphicsView is a control, that you placed in your XAML tree. When layout moves the control around and sizes it, invalidate is called for you. If you externally want to refresh, like on a button click event, you would need to tell the graphics view to invalidate, thus processing your drawable info.
To add to what @adegeo has said:
Discuss the ICanvas in the context of GraphicsView and vice-versa on the same page instead of cross-linking back and forth. They are related and inseparable, so why separate them when discussing them?
Although the docs don't currently make this clear, Microsoft.Maui.Graphics is a library that's available as a separate NuGet package. As well as using it in .NET MAUI apps, you could also use it from Xamarin apps (all platforms), WinForms, WPF, UWP, WinUI, Tizen, even Linux. However, using Microsoft.Maui.Graphics types with a GraphicsView is specific to .NET MAUI. So the GraphicsView content is specific to MAUI, while the Microsoft.Maui.Graphics content is generic to all platforms. They have to be kept separated for when the docsets for other products need to link into the Microsoft.Maui.Graphics content.
We know how to draw, but we want to know where to draw. There's not a single complete example on the page! Just snippets of drawing code without context! Do you expect your reader to reconstruct the samples? Where do they go?
The intention has always been for each page to link to a sample, from which the code in the docs comes from. However, it's taking time to make them all live. The GraphicsView sample has recently gone live (https://docs.microsoft.com/samples/dotnet/maui-samples/userinterface-graphicsview/) and the docs will soon be linking to it.
One thing that seems important to mention in https://learn.microsoft.com/en-gb/dotnet/maui/user-interface/controls/graphicsview#invalidate-the-canvas is what that Invalidate() method actually does.
Does the method just lead to calling public void Draw(ICanvas canvas, RectF dirtyRect) or is the content of my canvas cleared completely before public void Draw(ICanvas canvas, RectF dirtyRect) is called? I guess that it's clear for some and less clear for others who do not work with 2D graphics every day.
