The ProcUI group of functions provide an interface to manage transitions between the different states of an application. More...

Collaboration diagram for ProcUI:

Typedefs
typedef void(*	ProcUISaveCallback) (void)
	Called when the application needs to save. More...

typedef uint32_t(*	ProcUISaveCallbackEx) (void *)
	Called when the application needs to save. More...

typedef uint32_t(*	ProcUICallback) (void *)
	Generic ProcUI callback. More...

typedef enum ProcUICallbackType	ProcUICallbackType

typedef enum ProcUIStatus	ProcUIStatus

Enumerations
enum	ProcUICallbackType { PROCUI_CALLBACK_ACQUIRE , PROCUI_CALLBACK_RELEASE , PROCUI_CALLBACK_EXIT , PROCUI_CALLBACK_NET_IO_START , PROCUI_CALLBACK_NET_IO_STOP , PROCUI_CALLBACK_HOME_BUTTON_DENIED }

enum	ProcUIStatus { PROCUI_STATUS_IN_FOREGROUND , PROCUI_STATUS_IN_BACKGROUND , PROCUI_STATUS_RELEASE_FOREGROUND , PROCUI_STATUS_EXITING }

Functions
void	ProcUIClearCallbacks ()
	Unregister all ProcUI callbacks. More...

void	ProcUIDrawDoneRelease ()
	Signifies to ProcUI that the current application has released all foreground resources, drawn its last frame, and is ready to be moved into the background. More...

BOOL	ProcUIInForeground ()
	Determines whether the application is in the foreground. More...

BOOL	ProcUIInShutdown ()
	Determines whether the application is in shutdown and should quit. More...

void	ProcUIInit (ProcUISaveCallback saveCallback)
	Initialises the ProcUI library for use. More...

void	ProcUIInitEx (ProcUISaveCallbackEx saveCallback, void *arg)
	Initialises the ProcUI library for use; using a save callback that takes arguments. More...

BOOL	ProcUIIsRunning ()
	Determines whether the ProcUI library is running/initialised. More...

ProcUIStatus	ProcUIProcessMessages (BOOL block)
	Main runloop for ProcUI. More...

void	ProcUIRegisterCallback (ProcUICallbackType type, ProcUICallback callback, void *param, uint32_t priority)
	Register a callback for certain ProcUI events. More...

void	ProcUIRegisterCallbackCore (ProcUICallbackType type, ProcUICallback callback, void *param, uint32_t priority, uint32_t core)
	Register a callback for certain ProcUI events, executed on the given core. More...

void	ProcUIRegisterBackgroundCallback (ProcUICallback callback, void *param, OSTime interval)
	Register a callback which will be called periodically while in background. More...

void	ProcUISetSaveCallback (ProcUISaveCallbackEx saveCallback, void *arg)
	Sets the save callback. More...

void	ProcUIShutdown ()
	Shut down the ProcUI library for the current application. More...

ProcUIStatus	ProcUISubProcessMessages (BOOL block)
	ProcUIProcessMessages(), but for secondary cores. More...

Detailed Description

The ProcUI group of functions provide an interface to manage transitions between the different states of an application.

After calling ProcUIInit() or ProcUIInitEx(), an application may call ProcUIProcessMessages() to process and update its state. These states may include:

PROCUI_STATUS_IN_FOREGROUND - The default state of an application. All system resources and hardware is available, and the application runs without any serious restrictions.
PROCUI_STATUS_IN_BACKGROUND - When the user instructs the OS to switch to a secondary application (HOME menu overlay, Internet Browser, etc.) the application enters this background state. Background applications are heavily restricted - they get a small amount of CPU time on core 2 (all other threads are suspended), access to filesystems, and some network IO. They have no access to graphics, inputs or user interaction of any kind.
PROCUI_STATUS_RELEASE_FOREGROUND - The user has requested a foreground switch. The current application must release all foreground-only resources, calling ProcUIDrawDoneRelease() when it's ready to go into the background.
PROCUI_STATUS_EXITING - The application must release all resources, call ProcUIShutdown(), and exit.

An application can determine its state by either examining ProcUIProcessMessages()'s return value, or using callbacks via ProcUIRegisterCallback().

Typedef Documentation

◆ ProcUISaveCallback

typedef void(* ProcUISaveCallback) (void)

Called when the application needs to save.

Definition at line 47 of file procui.h.

◆ ProcUISaveCallbackEx

typedef uint32_t(* ProcUISaveCallbackEx) (void *)

Called when the application needs to save.

void* argument is provided in ProcUIInitEx().

Definition at line 52 of file procui.h.

◆ ProcUICallback

typedef uint32_t(* ProcUICallback) (void *)

Generic ProcUI callback.

void* argument is provided in ProcUIRegisterCallback().

Definition at line 57 of file procui.h.

◆ ProcUICallbackType

typedef enum ProcUICallbackType ProcUICallbackType

◆ ProcUIStatus

typedef enum ProcUIStatus ProcUIStatus

Enumeration Type Documentation

◆ ProcUICallbackType

enum ProcUICallbackType

Enumerator
PROCUI_CALLBACK_ACQUIRE	Application acquires the foreground.
PROCUI_CALLBACK_RELEASE	Application must release the foreground.
PROCUI_CALLBACK_EXIT	Application must exit.
PROCUI_CALLBACK_NET_IO_START	Application may start using networking.
PROCUI_CALLBACK_NET_IO_STOP	Application must stop using networking.
PROCUI_CALLBACK_HOME_BUTTON_DENIED	The user attempted to press the HOME button but was denied.

Definition at line 59 of file procui.h.

◆ ProcUIStatus

enum ProcUIStatus

Enumerator
PROCUI_STATUS_IN_FOREGROUND	The application is in the foreground. All resources may be used.
PROCUI_STATUS_IN_BACKGROUND	The application is in the background, only limited resources are usable.
PROCUI_STATUS_RELEASE_FOREGROUND	The application must release the foregound - see ProcUIDrawDoneRelease()
PROCUI_STATUS_EXITING	The application must release all resources (including ProcUI) and quit.

Definition at line 75 of file procui.h.

Function Documentation

◆ ProcUIClearCallbacks()

void ProcUIClearCallbacks ( )

Unregister all ProcUI callbacks.

See also

ProcUIRegisterCallback()

◆ ProcUIDrawDoneRelease()

void ProcUIDrawDoneRelease ( )

Signifies to ProcUI that the current application has released all foreground resources, drawn its last frame, and is ready to be moved into the background.

Should only be called when the application is in the PROCUI_STATUS_RELEASE_FOREGROUND state.

Note: After calling this function, the context will switch next time ProcUIProcessMessages() is called. All user threads on core 0 and 1 will be suspended once this happens.

Warning: Do not attempt to use foreground-only resources after calling this function and its accompanying ProcUIProcessMessages(). You should wait until ProcUI indicates PROCUI_STATUS_IN_FOREGROUND.

◆ ProcUIInForeground()

BOOL ProcUIInForeground ( )

Determines whether the application is in the foreground.

Returns: true if the application is in foreground (e.g. during PROCUI_STATUS_IN_FOREGROUND or PROCUI_STATUS_RELEASE_FOREGROUND).

See also

◆ ProcUIInShutdown()

BOOL ProcUIInShutdown ( )

Determines whether the application is in shutdown and should quit.

Returns: true if the application status is PROCUI_STATUS_EXITING.

See also

◆ ProcUIInit()

void ProcUIInit ( ProcUISaveCallback saveCallback )

Initialises the ProcUI library for use.

Parameters

saveCallback A callback to be called when the application needs to save. The callback cannot be NULL and it must call OSSavesDone_ReadyToRelease().

See also

◆ ProcUIInitEx()

void ProcUIInitEx	(	ProcUISaveCallbackEx	saveCallback,
		void *	arg
	)

Initialises the ProcUI library for use; using a save callback that takes arguments.

Parameters

saveCallback	A callback to be called when the application needs to save. The callback cannot be NULL and it must call OSSavesDone_ReadyToRelease().
arg	An argument to pass into saveCallbackEx.

See also

◆ ProcUIIsRunning()

BOOL ProcUIIsRunning ( )

Determines whether the ProcUI library is running/initialised.

Returns: true if the ProcUI library is initialised.

See also

◆ ProcUIProcessMessages()

ProcUIStatus ProcUIProcessMessages ( BOOL block )

Main runloop for ProcUI.

This function processes messages from the OS and provides it an opportinity to take control (to open the HOME menu overlay, for example). Returns the current state of the application.

Parameters

block Determines whether the function should block before returning. If false, the function returns immediately and all messages and callbacks are processed asynchronously.

Returns: The current state of the program. See ProcUIStatus. If block is false, this value is undefined and should be ignored.

Warning: ProcUI's non-blocking mode is not widely used and may have undocumented behaviour. Be careful with callbacks and the return value.

Note: This function should only be called from the main core. See OSIsMainCore() and ProcUISubProcessMessages().

◆ ProcUIRegisterCallback()

void ProcUIRegisterCallback	(	ProcUICallbackType	type,
		ProcUICallback	callback,
		void *	param,
		uint32_t	priority
	)

Register a callback for certain ProcUI events.

Parameters

type	The event to register a callback for. See ProcUICallbackType.
callback	Function pointer for the callback to call when the given event occurs.
param	Argument for the callback.
priority	The priority of the callback.

See also

ProcUIRegisterCallbackCore()

◆ ProcUIRegisterCallbackCore()

void ProcUIRegisterCallbackCore	(	ProcUICallbackType	type,
		ProcUICallback	callback,
		void *	param,
		uint32_t	priority,
		uint32_t	core
	)

Register a callback for certain ProcUI events, executed on the given core.

Parameters

type	The event to register a callback for. See ProcUICallbackType.
callback	Function pointer for the callback to call when the given event occurs.
param	Argument for the callback.
priority	The priority of the callback.
core	The core ID to run the callback on.

See also

ProcUIRegisterCallback()

◆ ProcUIRegisterBackgroundCallback()

void ProcUIRegisterBackgroundCallback	(	ProcUICallback	callback,
		void *	param,
		OSTime	interval
	)

Register a callback which will be called periodically while in background.

Parameters

callback	Function pointer for the callback.
param	Argument for the callback.
interval	The interval between callbacks.

◆ ProcUISetSaveCallback()

void ProcUISetSaveCallback	(	ProcUISaveCallbackEx	saveCallback,
		void *	arg
	)

Sets the save callback.

Unlike ProcUIInitEx(), this function can be called while ProcUI is already running.

Parameters

saveCallback	A callback to be called when the application needs to save. The callback cannot be NULL and it must call OSSavesDone_ReadyToRelease().
arg	An argument to pass into saveCallbackEx.

See also

◆ ProcUIShutdown()

void ProcUIShutdown ( )

Shut down the ProcUI library for the current application.

This should be called before the app exits.

Note: Do not attempt to use any ProcUI library functions after calling this function, except for ProcUIInit() or ProcUIInitEx().

◆ ProcUISubProcessMessages()

ProcUIStatus ProcUISubProcessMessages ( BOOL block )

ProcUIProcessMessages(), but for secondary cores.

Parameters

block Determines whether the function should block before returning. If false, the function returns immediately and all messages and callbacks are processed asynchronously.

Returns: The current state of the program - see ProcUIStatus. If block is false, this value is undefined and should be ignored.

Warning: ProcUI's non-blocking mode is not widely used and may have undocumented behaviour. Be careful with callbacks and the return value.

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ ProcUISaveCallback

◆ ProcUISaveCallbackEx

◆ ProcUICallback

◆ ProcUICallbackType

◆ ProcUIStatus

Enumeration Type Documentation

◆ ProcUICallbackType

◆ ProcUIStatus

Function Documentation

◆ ProcUIClearCallbacks()

◆ ProcUIDrawDoneRelease()

◆ ProcUIInForeground()

◆ ProcUIInShutdown()

◆ ProcUIInit()

◆ ProcUIInitEx()

◆ ProcUIIsRunning()

◆ ProcUIProcessMessages()

◆ ProcUIRegisterCallback()

◆ ProcUIRegisterCallbackCore()

◆ ProcUIRegisterBackgroundCallback()

◆ ProcUISetSaveCallback()

◆ ProcUIShutdown()

◆ ProcUISubProcessMessages()