~eliasnaur/gio#61:
Miscellaneous observations on gio documentation

Having recently learned to use gio I thought that, as an outsider, my perspective on the documentation could be useful. In no particular order:

  • Consecutive clip operations result in the intersection of their clip areas. This is fine but you can't tell from the documentation whether this is the case. The other reasonable possibility would be that a clip operator will replace the previous one, of course.

  • I think that the rrect function, or something that can be used to clip in a circle shape, is useful enough that it should be exported publicly.

  • If I try to fill a shape all the way in the middle of a window should I bother specifying a tight bounding rectangle as argument to PaintOp, for performance? Or does it not matter?

  • The name SingleLine in text.LayoutOptions is unfortunate, it sounds like it will result in Layout returning a single line but in reality what it does is ignore newlines (the output of Layout can still be multiple lines if word wrapping is necessary).

  • The ownership model for the *op.Ops pointer passed to io/system.FrameEvent.Frame is unusual. Usually ownership of an argument is transferred to the called object either permanently, or until the function returns. The API of op.Ops would suggest the latter, because it has a Reset method, however that is not the case. Gio assumes ownership of the op.Ops object between the call to Frame and the time when a new FrameEvent is generated, concurrent changes to op.Ops during this time can (and will) cause crashes. I think that this is unusual enough that it should be described somewhere (unless it is and I just missed it).

  • The examples in the 'app' and 'op' packages use the app.Window.Update method. As far as I can tell it doesn't exist anymore.

Status
RESOLVED IMPLEMENTED
Submitter
Alessandro Arzilli
Assigned to
No-one
Submitted
8 days ago
Updated
3 days ago
Labels
No labels applied.

~eliasnaur REPORTED IMPLEMENTED 3 days ago

On Tue Nov 5, 2019 at 1:53 PM Alessandro Arzilli wrote:

Having recently learned to use gio I thought that, as an outsider, my perspective on the documentation could be useful. In no particular order:

Thank you for taking time to describe your outside perspective of the API and documentation.

  • Consecutive clip operations result in the intersection of their clip areas. This is fine but you can't tell from the documentation whether this is the case. The other reasonable possibility would be that a clip operator will replace the previous one, of course.

Added more documentation that clips intersect. Also noted that you can use StackOp to apply and revert a clip.

  • I think that the rrect function, or something that can be used to clip in a circle shape, is useful enough that it should be exported publicly.

Moved the clip operations to the new package gioui.org/op/clip and added RoundRect.

  • If I try to fill a shape all the way in the middle of a window should I bother specifying a tight bounding rectangle as argument to PaintOp, for performance? Or does it not matter?

Doesn't matter. Only the intersection between the bounds of the current clip and the PaintOp rectangle is drawn.

  • The name SingleLine in text.LayoutOptions is unfortunate, it sounds like it will result in Layout returning a single line but in reality what it does is ignore newlines (the output of Layout can still be multiple lines if word wrapping is necessary).

Not only is the name unfortunate, the functionality doesn't belong in low-level text layout. SingleLine is now gone.

  • The ownership model for the *op.Ops pointer passed to io/system.FrameEvent.Frame is unusual. Usually ownership of an argument is transferred to the called object either permanently, or until the function returns. The API of op.Ops would suggest the latter, because it has a Reset method, however that is not the case. Gio assumes ownership of the op.Ops object between the call to Frame and the time when a new FrameEvent is generated, concurrent changes to op.Ops during this time can (and will) cause crashes. I think that this is unusual enough that it should be described somewhere (unless it is and I just missed it).

Fixed. The *op.Ops is no longer touched after Frame returns.

  • The examples in the 'app' and 'op' packages use the app.Window.Update method. As far as I can tell it doesn't exist anymore.

Thanks, fixed.

Register here or Log in to comment, or comment via email.