Documentation tasks

[smoogipoo]

This is a permanent issue where we will list areas of the framework that need better documentation. Feel free to tackle these tasks if you have time.

XMLDoc improvements

TooltipContainer

• The reuse of tooltips.
• The reuse of custom tooltips, on a per-type basis, and how to avoid re-use.
• How content is passed from Drawable to a custom tooltip (TooltipContent / SetContent()).

Drawable

• DrawSize does not account for scale of either the Drawable itself or any of its parents.
• DrawScale does not account for scale of parents.
• End event handler methods (e.g. OnKeyUp, OnFocusLost, etc...) need rewording to better indicate which requires handling begin event. ButtonDownInputQueue includes sibling drawables to the one handling it #3625 (comment)

Wiki documentation

We hope to add more auxiliary documentation on the wiki covering common patterns in the framework. If you wish to contribute to this (and don't have access) please feel free to post an article in this thread and we will transfer it across.

Drawables

Layout

• How coordinates systems work (and relative sizing)
• How to use DrawSizePreservingFillContainer to make custom coordinate spaces (and aspect ratio enforcement) for hierarchies
• How anchor / origin work (can be roughly transferred from my blog post source)

Event handling

• When drawables receive end events must be mentioned correctly. ButtonDownInputQueue includes sibling drawables to the one handling it #3625 (comment)

Fonts

• How to generate binary font files using the bmfont config file (https://github.com/ppy/osu-framework/blob/master/osu.Framework/Resources/Fonts/bmfont.bmfc)
• How to add font resources to the game

Debugging

• How to display and use the global statistics tool to track and hunt down performance issues.

[TimOliver]

Here's what I've got for the layout system so far: https://github.com/ppy/osu-framework/wiki/Coordinate-and-Layout-System

[bdach]

@TimOliver FYI I can't actually see any text there; think it might only be visible to you at this point (probably stored locally browser-side).

[TimOliver]

@bdach Ah, I renamed the page title. I didn't realise the old URLs don't automatically redirect. I updated it now! :)

[frenzibyte]

Finished up the Font section:

• Converting to binary font with texture files
• Adding font resources to the game
• Using font for a sprite text with FontUsage (probably important for specifying what font to use)

Published to the osu!framework wiki: https://github.com/ppy/osu-framework/wiki/Setting-Up-Fonts

[Coppertine]

@iiSalman You need to spesify that all BMFont files are safed as fnt where as osu!framework can only read .bin, you have to change the extension first. You can write .bin in the save as window as it would just so MyAwesomeFont.bin.font and MyAwesomeFont.bin-0.png respectively

[frenzibyte]

well, fun fact: osu!framework reads both .bin and .fnt (check FontStore.cs), so it's unnecessary to do that IMO, maybe leaving a note saying it may be better to change the extension to .bin as the font is of binary data for your collaborators not to confuse it with text / XML descriptors, will do that. Nevermind, the font itself starts with the magic string FNT anyways.

[Redageddon]

One of the biggest things that is needed is, how do screen transitions work. For example: How do I open screen A and close screen B. This cannot be inferred from osu!lazer and osu!framework doesn't have documentation on how to make something like that

[Redageddon]

I don't even mean specifically for 'Screen'. I just mean, more explanation could be given on how to, lets say, show a beatmap selection screen when a button is pressed in main menu