Global variables shared by all functions in the application. More...

Collaboration diagram for Burger::Globals:

Static Public Member Functions
static uint16_t	RegisterWindowClass (uint_t uIconResID=0)
	Create the global Burgerlib Window Class.

static void	UnregisterWindowClass (void)
	Release the global Burgerlib Window Class.

static void	AddToMenubar (NSMenu *pNSMenu)
	Add a new NSMenu to the application menu bar (MacOSX Only)

static NSString *	GetApplicationName (void)
	Query the application's plist for the Bundle name.

static void	CreateApplicationMenu (void)
	Add a new application menu for to the application menu bar (MacOSX Only)

static void	CreateWindowMenu (void)
	Add a new view menu for window selection to the application menu bar (MacOSX Only)

static void	CreateViewMenu (void)
	Add a new view menu for full screen toggling to the application menu bar (MacOSX Only)

static void	CreateHelpMenu (void)
	Add a new help menu with search to the application menu bar (MacOSX Only)

static void	CreateDefaultMenus (void)
	Create a new application menu bar (MacOSX Only)

static void	GetHIDDeviceName (String pOutput, __IOHIDDevice pDevice)
	Obtain the name of an HID device (MacOSX Only)

static __CFDictionary *	CreateHIDDictionary (uint_t uPage, uint_t uUsage)
	Create a MutableDictionary for use to the HID Manager (MacOSX Only)

static void	GetDisplayName (String *pOutput, uint_t uDisplayID)
	Get the name of a monitor (MacOSX Only)

static int	NumberFromKey (const __CFDictionary pDictionary, const char pKey)
	Get an integer from a Dictionary (MacOSX Only)

static uint_t	GetQuickTimeVersion (void) noexcept
	Return the version of QuickTime.

static eError	GetErrorCode (void) noexcept
	Get the current error code the application will return on exit.

static void	SetErrorCode (eError iNewError) noexcept
	Set the current error code.

static char *	GetErrorMsg (void) noexcept
	Get the pointer to the global error message buffer.

static void	SetErrorMsg (const char *pMessage,...)
	Update the current error message.

static uint_t	AreWarningsEnabled (void) noexcept
	Return non-zero if warning logging is enabled.

static uint_t	GetErrorBombFlag (void) noexcept
	Get the current flag to treat warnings as fatal errors.

static uint_t	SetErrorBombFlag (uint_t uNewFlag) noexcept
	Set the current flag to treat warnings as fatal errors.

static uint_t	GetExitFlag (void) noexcept
	Get the "shutdown in progress" flag.

static void	SetExitFlag (uint_t uNewFlag) noexcept
	Set the current flag if a shut down is in progress.

static void	Shutdown (void)
	Immediately shut down the application.

static void	Shutdown (int iError)
	Immediately shut down the application with an error code.

static uint32_t	Version (void)
	Return the version of Burgerlib.

static uint32_t	VersionBuild (void)
	Return the build number of Burgerlib.

static uint_t	LaunchURL (const char *pURL)
	Load and launch a web page from an address string.

static int	ExecuteTool (const char pFilename, const char pParameters, OutputMemoryStream *pOutput=nullptr)
	Execute a tool and capture the text output.

Private Attributes
uint_t	m_uMacOSVersion
	Discovered version of MacOS (MacOS only)

uint_t	m_uQuickTimeVersion
	QuickTime's version in 0x0102 (1.2) format.

uint8_t	m_bMacOSTested
	MacOS version was tested (MacOS only)

uint8_t	m_bQuickTimeVersionValid
	TRUE if Quicktime's version is valid.

Static Private Attributes
static uint16_t	g_uAtom
	Atom assigned to my class (Windows only)

static uint32_t	g_uQuickTimeVersion
	QuickTime's version in 0x0102 (1.2) format.

static uint8_t	g_bQuickTimeVersionValid
	TRUE if Quicktime's version is valid.

static eError	g_iErrorCode
	Global default error code used by Globals::Shutdown().

static char	g_ErrorMsg [512]
	Global Buffer containing the last fatal error or warning.

static uint_t	g_bBombFlag
	TRUE if non-fatal errors are treated as fatal

static uint_t	g_bExitFlag
	Global TRUE if the app is in the process of shutting down.

static Globals	g_Globals
	Singleton instance of the global variables.

Detailed Description

Global variables shared by all functions in the application.

These globals are used for the application to manage operating system resources that have a global effect.

See also: Burger::Debug or Burger::Windows

Member Function Documentation

◆ AddToMenubar()

void BURGER_API Burger::Globals::AddToMenubar ( NSMenu * pNSMenu )

static

Add a new NSMenu to the application menu bar (MacOSX Only)

Given a created NSMenu, add the item as a submenu to the main menu bar

Note: This is only available on Mac OSX

Parameters

pNSMenu A valid pointer to an NSMenu

See also: CreateApplicationMenu(), CreateWindowMenu(), CreateViewMenu() or CreateHelpMenu()

◆ AreWarningsEnabled()

static uint_t Burger::Globals::AreWarningsEnabled ( void )

inlinestaticnoexcept

Return non-zero if warning logging is enabled.

For debugging, if this flag returns a non-zero value, log messages if a non-fatal error condition occurs.

Returns: FALSE if logging is not requests, non-zero to enable logging.

See also: Burger::get_traceflags()

◆ CreateApplicationMenu()

void BURGER_API Burger::Globals::CreateApplicationMenu ( void )

static

Add a new application menu for to the application menu bar (MacOSX Only)

Creates an NSMenu with the name of the application and add a several entries.

"About %s" with no hot key and calls orderFrontStandardAboutPanel "Preferences…" with a hot key of Option-',' and has no action "Services" with no hot key and calls no action and is attached to setServicesMenu "Hide %s" with no hot key and calls hide "Hide others" with no hot key and calls hideOtherApplications "Show All" with no hot key and calls unhideAllApplications "Quit %s" with a hot key of Option-Q and calls terminate

Note: This is only available on Mac OSX

See also: AddToMenubar(), CreateWindowMenu(), CreateViewMenu() or CreateHelpMenu()

◆ CreateDefaultMenus()

void BURGER_API Burger::Globals::CreateDefaultMenus ( void )

static

Create a new application menu bar (MacOSX Only)

If there's no [NSApp mainMenu], create one.

Note: This is only available on Mac OSX

See also: CreateApplicationMenu(), CreateWindowMenu(), CreateViewMenu() or CreateHelpMenu()

◆ CreateHelpMenu()

void BURGER_API Burger::Globals::CreateHelpMenu ( void )

static

Add a new help menu with search to the application menu bar (MacOSX Only)

Creates an NSMenu called "Help" and adds two entries, the first is the "Search" text entry field, followed by a menu item of "%s Help" where s is the pApplicationName and it called the showHelp selector when invoked.

Note: This is only available on Mac OSX

See also: AddToMenubar(), CreateApplicationMenu(), CreateWindowMenu() or CreateViewMenu()

◆ CreateHIDDictionary()

CFMutableDictionaryRef BURGER_API Burger::Globals::CreateHIDDictionary	(	uint_t	uPage,
		uint_t	uUsage )

static

Create a MutableDictionary for use to the HID Manager (MacOSX Only)

Given a Page and Usage key values, create a dictionary for passing into the IOHID Kit manager.

Note: This is only available on Mac OSX

Parameters

uPage	Value to associate with kIOHIDDeviceUsagePageKey
uUsage	Value to associate with kIOHIDDeviceUsageKey

Returns: NULL if failed, or a valid CFMutableDictionaryRef value

◆ CreateViewMenu()

void BURGER_API Burger::Globals::CreateViewMenu ( void )

static

Add a new view menu for full screen toggling to the application menu bar (MacOSX Only)

Creates an NSMenu called "View" and add a single entry: "Toggle Full Screen". The menu item triggers the selector toggleFullScreen when invoked. The hot key is Option-Enter (ALT-Enter)

This function tests if it's running on 10.6 or higher, if this test fails, the function does nothing.

Note: This is only available on Mac OSX

See also: AddToMenubar(), CreateApplicationMenu(), CreateWindowMenu() or CreateHelpMenu()

◆ CreateWindowMenu()

void BURGER_API Burger::Globals::CreateWindowMenu ( void )

static

Add a new view menu for window selection to the application menu bar (MacOSX Only)

Creates an NSMenu called "Window" and add a several entries.

"Minimize" with a hot key of Option-M and calls performMiniaturize "Zoom" with no hot key and calls performZoom "Bring All to Front" with no hot key and calls arrangeInFront

Note: This is only available on Mac OSX

See also: AddToMenubar(), CreateApplicationMenu(), CreateViewMenu() or CreateHelpMenu()

◆ ExecuteTool()

int BURGER_API Burger::Globals::ExecuteTool	(	const char *	pFilename,
		const char *	pParameters,
		OutputMemoryStream *	pOutput = nullptr )

static

Execute a tool and capture the text output.

If another program needs to be executed, call it with a command line and capture the text output into a stream if desired

Parameters

pFilename	Pointer to a "C" string of the executable in Burgerlib format
pParameters	Pointer to a "C" string of the command line parameters (No translation is performed)
pOutput	Pointer to a OutputMemoryStream to store the captured output. NULL is acceptable if output capturing is not desired

Returns: Error code on failure, zero if the program was executed and it returned zero on exit

◆ GetApplicationName()

NSString *BURGER_API Burger::Globals::GetApplicationName ( void )

static

Query the application's plist for the Bundle name.

To determine the name of the application for updating menus or other systems that need the application's for display, call this function which checks "CFBundleDisplayName" first, "CFBundleName" second and the processName last.

Note: Don't release the returned NSString!; This is only available on Mac OSX

Returns: Pointer to a NSString * with the name if found, NULL if not.

◆ GetDisplayName()

void Burger::Globals::GetDisplayName	(	String *	pOutput,
		uint_t	uDisplayID )

static

Get the name of a monitor (MacOSX Only)

Given a CGDirectDisplayID, return the name of a monitor. If the monitor has no name, in cases such as if it's a Mac without a monitor, it will be set to "Inactive"

Note: This is only available on Mac OSX

Parameters

pOutput	Pointer to the String to receive the name of the monitor
uDisplayID	CGDirectDisplayID of the monitor to obtain the name from

◆ GetErrorBombFlag()

static uint_t Burger::Globals::GetErrorBombFlag ( void )

inlinestaticnoexcept

Get the current flag to treat warnings as fatal errors.

When Burger::Debug::Warning is called, it will test the state of this boolean flag and if TRUE, it will abort code execution and exit immediately.

Returns: TRUE if warnings are treated as errors, FALSE if not. (FALSE is default).

See also: Burger::Globals::SetErrorBombFlag(uint_t)

◆ GetErrorCode()

static eError Burger::Globals::GetErrorCode ( void )

inlinestaticnoexcept

Get the current error code the application will return on exit.

When the main() function exits, this is the error code that should be returned.

int main(void)
{
    DoStuff();
    // Somewhere, the code may have set an error code. Pass it along to
    // the operating system
    return Burger::Globals::GetErrorCode();
}

Returns: The current application error state

See also: Burger::Globals::SetErrorCode(int)

◆ GetErrorMsg()

static char * Burger::Globals::GetErrorMsg ( void )

inlinestaticnoexcept

Get the pointer to the global error message buffer.

Calls to many functions that fail will update this buffer to return verbose output.

Note: This buffer is modified by functions passing warnings and errors. Copy the string immediately and use the copy.; Do not attempt to modify the buffer the pointer points to.

Returns: A pointer to a global static buffer.

See also: Burger::Globals::SetErrorMsg(const char *,...)

◆ GetExitFlag()

static uint_t Burger::Globals::GetExitFlag ( void )

inlinestaticnoexcept

Get the "shutdown in progress" flag.

If the application has called Globals::Shutdown(), this flag is set to TRUE to prevent recursion if Globals::Shutdown() is called by cleanup code.

Returns: TRUE if shut down is in progress, FALSE if not.

See also: Burger::Globals::SetExitFlag(uint_t)

◆ GetHIDDeviceName()

void BURGER_API Burger::Globals::GetHIDDeviceName	(	String *	pOutput,
		__IOHIDDevice *	pDevice )

static

Obtain the name of an HID device (MacOSX Only)

Given an IOHIDDeviceRef, query for a device name, and if none is found, a manufacturer name and store it in the output.

Note: This is only available on Mac OSX

Parameters

pOutput	Pointer to a String class instance to recieve the string
pDevice	Pointer to a valid IOHIDDeviceRef

◆ GetQuickTimeVersion()

uint_t BURGER_API Burger::Globals::GetQuickTimeVersion ( void )

staticnoexcept

Return the version of QuickTime.

Detect if QuickTime is available, and if so, query it for the version present. If QuickTime is not available, the version returned is zero.

This function is written so it only asks for the version once from QuickTime. It will cache the version and return the cached value on subsequent calls.

By invoking DEEP magic, I will divine the version of QuickTimeX that is present. It will do a manual check of the system folder for either QTIM32.dll (Old) or Quicktime.qts (Current) and pull the version resource from the file.

Returns: Version in the format of 0x0102 -> 1.2, 0x773 = 7.7.3

◆ LaunchURL()

uint_t BURGER_API Burger::Globals::LaunchURL ( const char * pURL )

static

Load and launch a web page from an address string.

For Windows and MacOS platforms, this will open a web browser to a specific URL. It will use the default browser selected by the user from the operating system settings

Parameters

pURL	Pointer to a UTF8 string with the URL to a web page to open

Returns: Zero for no error, non-zero for error

◆ NumberFromKey()

int Burger::Globals::NumberFromKey	(	const __CFDictionary *	pDictionary,
		const char *	pKey )

static

Get an integer from a Dictionary (MacOSX Only)

Given a CFDictionaryRef and a query key, look up the item in the dictionary and if present, return the value as an integer. Returns zero on failure.

Note: This is only available on Mac OSX

Parameters

pDictionary	CFDictionaryRef of the dictionary to query
pKey	"C" string of the data to query

Returns: Zero on failure or the integer value found in the dictionary

◆ RegisterWindowClass()

uint16_t BURGER_API Burger::Globals::RegisterWindowClass ( uint_t uIconResID = 0 )

static

Create the global Burgerlib Window Class.

Windows requires a WNDCLASS definition declared to allow the creation of application specific windows. Burgerlib uses it's own custom callback function and it's declared after this function is called which calls RegisterClassExW() in windows that creates an ATOM of the type BurgerGameClass.

The string can be obtained with a call to get_window_class_name() if it's desired for an application to create a Burgerlib window without Burgerlib doing it for you.

The ATOM is released on application shutdown, or manually with a call to UnregisterWindowClass()

If this function had previously created the game class, it will return the ATOM that was created before and exit immediately.

Note: This function requires that set_instance() has been called. Burgerlib does this automatically when creating a GameApp class instance, however if no GameApp was created, the INSTANCE must be passed manually for this function to work properly; This is only available on Windows

Parameters

uIconResID Numeric ID of the Windows Icon to attach to the window that's in the EXE files resource data (0 to use the default application icon from Windows)

See also: UnregisterWindowClass(void)

◆ SetErrorBombFlag()

static uint_t Burger::Globals::SetErrorBombFlag ( uint_t uNewFlag )

inlinestaticnoexcept

Set the current flag to treat warnings as fatal errors.

When Burger::Debug::Warning is called, it will test the state of this boolean flag and if TRUE, it will abort code execution and exit immediately.

Parameters

uNewFlag If non-zero, it will set the flag, zero will clear it.

Returns: The previous Error Bomb Flag

See also: Burger::Globals::GetErrorBombFlag()

◆ SetErrorCode()

static void Burger::Globals::SetErrorCode ( eError iNewError )

inlinestaticnoexcept

Set the current error code.

When the application shuts down, main() will return an integer error code. This function will set that code.

Parameters

iNewError The new error code, zero means no error.

See also: Burger::Globals::GetErrorCode()

◆ SetErrorMsg()

void BURGER_ANSIAPI Burger::Globals::SetErrorMsg	(	const char *	pMessage,
			... )

static

Update the current error message.

If the input message pointer is not NULL, then store the message string into the global error string buffer using printf() rules. If it's NULL, set the string to "".

Parameters

pMessage Pointer to a string suitable for printf or NULL.

See also: Burger::Globals::GetErrorMsg(), Burger::Debug::Fatal or Burger::Debug::Warning

◆ SetExitFlag()

static void Burger::Globals::SetExitFlag ( uint_t uNewFlag )

inlinestaticnoexcept

Set the current flag if a shut down is in progress.

If the application has called Globals::Shutdown(), this flag is set to TRUE to prevent recursion if Globals::Shutdown() is called by cleanup code.

This function should set this flag if it's implementing its own form of Globals::Shutdown() or is manually calling exit()

Parameters

uNewFlag If non-zero, it will set the flag, zero will clear it.

See also: Burger::Globals::GetExitFlag()

◆ Shutdown() [1/2]

void BURGER_API Burger::Globals::Shutdown ( int iError )

static

Immediately shut down the application with an error code.

Calls exit() with the error code (Default is zero)

Note: This will kill the application unless it's already in shutdown. All global destructors are called to clean up all sub-systems. If this function returns, immediately exit from the function since the application is already in shut down mode.

Parameters

iError Error code to return when main() is returned from.

See also: Burger::Globals::Shutdown() and Globals::SetExitFlag()

◆ Shutdown() [2/2]

void BURGER_API Burger::Globals::Shutdown ( void )

static

Immediately shut down the application.

Calls exit() with the currently logged error code (Default is zero) The exit flag is set to prevent recursion.

Note: This will kill the application. All global destructors are called to clean up all sub-systems.

See also: Burger::Globals::Shutdown(int)

◆ UnregisterWindowClass()

void BURGER_API Burger::Globals::UnregisterWindowClass ( void )

static

Release the global Burgerlib Window Class.

When RegisterWindowClass(uint_t) is called, it will create a global ATOM of the window class. This function will unregister the class. This function is called on shutdown automatically

Note: This is only available on Windows

See also: RegisterWindowClass(uint_t)

◆ Version()

uint32_t BURGER_API Burger::Globals::Version ( void )

static

Return the version of Burgerlib.

Returns the version of Burgerlib in a single number.

Currently, Burgerlib is 5.0.3

uint32_t uVersion = Globals::Version();
uint32_t uMajor = (uVersion>>24);
uint32_t uMinor = (uVersion>>16)&0xFFU;
uint32_t uPatch = (uVersion&0xFFFFU);

Returns: Version in a single 32 bit value

See also: VersionBuild(void)

◆ VersionBuild()

uint32_t BURGER_API Burger::Globals::VersionBuild ( void )

static

Return the build number of Burgerlib.

Returns the change list number that generated this version of Burgerlib. Use this value to determine if a specific version is needed for compatibility

Returns: Build number in a single 32 bit value

See also: Version(void)

Member Data Documentation

◆ g_bBombFlag

uint_t Burger::Globals::g_bBombFlag

staticprivate

TRUE if non-fatal errors are treated as fatal

◆ g_bExitFlag

uint_t Burger::Globals::g_bExitFlag

staticprivate

Global TRUE if the app is in the process of shutting down.

◆ g_bQuickTimeVersionValid

uint8_t Burger::Globals::g_bQuickTimeVersionValid

staticprivate

TRUE if Quicktime's version is valid.

(Windows only)

◆ g_ErrorMsg

char Burger::Globals::g_ErrorMsg

staticprivate

Global Buffer containing the last fatal error or warning.

◆ g_Globals

Burger::Globals Burger::Globals::g_Globals

staticprivate

Singleton instance of the global variables.

◆ g_iErrorCode

Burger::eError Burger::Globals::g_iErrorCode

staticprivate

Global default error code used by Globals::Shutdown().

◆ g_uAtom

uint16_t Burger::Globals::g_uAtom

staticprivate

Atom assigned to my class (Windows only)

◆ g_uQuickTimeVersion

uint32_t Burger::Globals::g_uQuickTimeVersion

staticprivate

QuickTime's version in 0x0102 (1.2) format.

(Windows only)

◆ m_bMacOSTested

uint8_t Burger::Globals::m_bMacOSTested

private

MacOS version was tested (MacOS only)

◆ m_bQuickTimeVersionValid

uint8_t Burger::Globals::m_bQuickTimeVersionValid

private

TRUE if Quicktime's version is valid.

(MacOS only)

◆ m_uMacOSVersion

uint_t Burger::Globals::m_uMacOSVersion

private

Discovered version of MacOS (MacOS only)

◆ m_uQuickTimeVersion

uint_t Burger::Globals::m_uQuickTimeVersion

private

QuickTime's version in 0x0102 (1.2) format.

(MacOS only)

Static Public Member Functions

Private Attributes

Static Private Attributes

Detailed Description

Member Function Documentation

◆ AddToMenubar()

◆ AreWarningsEnabled()

◆ CreateApplicationMenu()

◆ CreateDefaultMenus()

◆ CreateHelpMenu()

◆ CreateHIDDictionary()

◆ CreateViewMenu()

◆ CreateWindowMenu()

◆ ExecuteTool()

◆ GetApplicationName()

◆ GetDisplayName()

◆ GetErrorBombFlag()

◆ GetErrorCode()

◆ GetErrorMsg()

◆ GetExitFlag()

◆ GetHIDDeviceName()

◆ GetQuickTimeVersion()

◆ LaunchURL()

◆ NumberFromKey()

◆ RegisterWindowClass()

◆ SetErrorBombFlag()

◆ SetErrorCode()

◆ SetErrorMsg()

◆ SetExitFlag()

◆ Shutdown() [1/2]

◆ Shutdown() [2/2]

◆ UnregisterWindowClass()

◆ Version()

◆ VersionBuild()

Member Data Documentation

◆ g_bBombFlag

◆ g_bExitFlag

◆ g_bQuickTimeVersionValid

◆ g_ErrorMsg

◆ g_Globals

◆ g_iErrorCode

◆ g_uAtom

◆ g_uQuickTimeVersion

◆ m_bMacOSTested

◆ m_bQuickTimeVersionValid

◆ m_uMacOSVersion

◆ m_uQuickTimeVersion