Launcher documentation WIP

Introduction

In contrast to the in-game GUI, the Launcher only displays one Screen at a time

Each Screen is composed of a background and one or more Widgets:

You can use the following method to switch the active Screen:

void Launcher_SetScreen(struct LScreen* screen);

Launcher Screen

A Launcher Screen (shorted to LScreen) consists of the following members:

TODO: Talk about LScreen_Reset somewhere

Required members

void (*Init)(struct LScreen* s)

Called the first time this launcher screen is made active

At a minimum, the widgets and numWidgets members must be initialised here

struct LWidget** widgets

Points to an array containing pointers to the widgets in the screen

int numWidgets

Number of widgets in the screen

Example:

static struct LWidget* simpleScreen_widgets[] = {
	(struct LWidget*)&SimpleScreen.iptField,
	(struct LWidget*)&SimpleScreen.btnBack
};

void SimpleScreen_Init(struct LScreen* s) {
	s->widgets    = simpleScreen_widgets;
	s->numWidgets = Array_Elems(simpleScreen_widgets);
	...
}

Optional members - general

void (*Show)(struct LScreen* s)

Optional. Called every time this screen appears. (i.e. switching to this screen)

void (*Free)(struct LScreen* s)

Optional. Called every time this screen disappears. (i.e. switching to another screen)

void (*Layout)(struct LScreen* s)

Optional. Can be used to customise widget layout, but usually it's unnecessary to override the default method

void (*Tick)(struct LScreen* s)

Optional. Can be used to implement functionality that required periodic checking

Optional members - input

void (*KeyDown)(struct LScreen* s, int key, cc_bool wasDown)

void (*MouseUp)(struct LScreen* s, int idx)

void (*MouseWheel)(struct LScreen* s, float delta)

struct LWidget* onEnterWidget

Optional. Can be used to set the widget automatically clicked on when Enter is pressed and no other interactable widget is hovered over.

struct LWidget* hoveredWidget

struct LWidget* selectedWidget

Optional members - drawing

void (*DrawBackground)(struct LScreen* s, struct Context2D* ctx)

void (*ResetArea)(struct Context2D* ctx, int x, int y, int width, int height)

const char* title

TODO: this is kinda required usually... ?

How a launcher screen works

Init Showing Background drawing

Launcher Widgets

TODO

TODO mention interactable widgets

Widget layout / positioning

TODO. talk about anchoring and offsets. maybe move to screen?

example image of all the different anchors/offsets

Widget types

Button widgets

Checkbox widgets

Input widgets

Label widgets

Slider widgets

Complete example

TODO

TODO mention how struct declarion works. maybe should be in earlier section?

Example usage:

void SimpleScreen_SetActive(void) {
	struct SimpleScreen* s = &SimpleScreen;
	LScreen_Reset((struct LScreen*)s);
	s->Init = SimpleScreen_Init;

	s->title = "Title text";
	Launcher_SetScreen((struct LScreen*)s);
}