Document Window.h and tidy it up

src/CarbonWindow.c

@@ -436,10 +436,10 @@ static void Window_ConnectEvents(void) {
 /*########################################################################################################################*
  *--------------------------------------------------Public implementation--------------------------------------------------*
  *#########################################################################################################################*/
-void Window_Create(int x, int y, int width, int height, const String* title, struct GraphicsMode* mode, struct DisplayDevice* device) {
+void Window_Create(int x, int y, int width, int height, struct GraphicsMode* mode) {
 	Rect r;
 	OSStatus res;
-	CFStringRef titleCF;
+	
 	ProcessSerialNumber psn;
 	
 	r.left = x; r.right  = x + width; 
@@ -449,12 +449,7 @@ void Window_Create(int x, int y, int width, int height, const String* title, str
 						  kWindowInWindowMenuAttribute | kWindowLiveResizeAttribute,
 						  &r, &win_handle);
 	if (res) ErrorHandler_Fail2(res, "Failed to create window");
-	
+
-	/* TODO: Use UTF8 encoding instead!!!! */
-	/* Use Platform_ConvertString */
-	titleCF = CFStringCreateWithBytes(kCFAllocatorDefault, title->buffer, title->length, kCFStringEncodingASCII, false);
-	SetWindowTitleWithCFString(win_handle, titleCF);
-	
 	Window_SetLocation(r.left, r.right);
 	Window_SetSize(Rect_Width(r), Rect_Height(r));
 	Window_UpdateSize();
@@ -475,6 +470,14 @@ void Window_Create(int x, int y, int width, int height, const String* title, str
 	Window_Exists = true;
 }
 
+void Window_SetTitle(const String* title) {
+	CFStringRef titleCF;
+	/* TODO: Use UTF8 encoding instead!!!! */
+	/* Use Platform_ConvertString */
+	titleCF = CFStringCreateWithBytes(kCFAllocatorDefault, title->buffer, title->length, kCFStringEncodingASCII, false);
+	SetWindowTitleWithCFString(win_handle, titleCF);
+}
+
 /* NOTE: All Pasteboard functions are OSX 10.3 or later */
 PasteboardRef Window_GetPasteboard(void) {
 	PasteboardRef pbRef;
@@ -535,10 +538,7 @@ void Window_SetClipboardText(const String* value) {
 }
 /* TODO: IMPLEMENT void Window_SetIcon(Bitmap* bmp); */
 
-bool Window_GetVisible(void) {
+bool Window_GetVisible(void) { return IsWindowVisible(win_handle); }
-	return IsWindowVisible(win_handle);
-}
-
 void Window_SetVisible(bool visible) {
 	if (visible == Window_GetVisible()) return;
 	

src/Game.c

@@ -752,7 +752,8 @@ void Game_Run(int width, int height, const String* title, struct DisplayDevice*
 	double time;
 	
 	GraphicsMode_MakeDefault(&mode);
-	Window_Create(x, y, width, height, title, &mode, device);
+	Window_Create(x, y, width, height, &mode);
+	Window_SetTitle(title);
 	Window_SetVisible(true);
 
 	Game_Load();

src/NixWindow.c

@@ -194,7 +194,7 @@ static void Window_RefreshBounds(XEvent* e) {
 *--------------------------------------------------Public implementation--------------------------------------------------*
 *#########################################################################################################################*/
 static XVisualInfo GLContext_SelectVisual(struct GraphicsMode* mode);
-void Window_Create(int x, int y, int width, int height, const String* title, struct GraphicsMode* mode, struct DisplayDevice* device) {
+void Window_Create(int x, int y, int width, int height, struct GraphicsMode* mode) {
 	win_display = DisplayDevice_Meta[0];
 	win_screen  = DisplayDevice_Meta[1];
 	win_rootWin = DisplayDevice_Meta[2];
@@ -221,8 +221,6 @@ void Window_Create(int x, int y, int width, int height, const String* title, str
 		0, win_visual.depth /* CopyFromParent*/, InputOutput, win_visual.visual, mask, &attributes);
 
 	if (!win_handle) ErrorHandler_Fail("XCreateWindow call failed");
-	char str[600]; Platform_ConvertString(str, title);
-	XStoreName(win_display, win_handle, str);
 
 	XSizeHints hints  = { 0 };
 	hints.base_width  = width;
@@ -252,6 +250,12 @@ void Window_Create(int x, int y, int width, int height, const String* title, str
 	Window_Exists = true;
 }
 
+void Window_SetTitle(const String* title) {
+	char str[600]; 
+	Platform_ConvertString(str, title);
+	XStoreName(win_display, win_handle, str);
+}
+
 char clipboard_copy_buffer[256];
 String clipboard_copy_text = String_FromArray(clipboard_copy_buffer);
 char clipboard_paste_buffer[256];

src/Platform.c

@@ -1694,7 +1694,7 @@ ReturnCode Audio_StopAndFree(AudioHandle handle) {
 *--------------------------------------------------------Platform---------------------------------------------------------*
 *#########################################################################################################################*/
 #ifdef CC_BUILD_WIN
-void Platform_ConvertString(void* data, const String* src) {
+int Platform_ConvertString(void* data, const String* src) {
 	WCHAR* dst = data;
 	int i;
 	if (src->length > FILENAME_SIZE) ErrorHandler_Fail("String too long to expand");
@@ -1703,6 +1703,7 @@ void Platform_ConvertString(void* data, const String* src) {
 		*dst = Convert_CP437ToUnicode(src->buffer[i]); dst++;
 	}
 	*dst = '\0';
+	return src->length * 2;
 }
 
 void Platform_Init(void) {
@@ -1801,7 +1802,7 @@ int Platform_GetCommandLineArgs(int argc, STRING_REF const char** argv, String*
 }
 #endif
 #ifdef CC_BUILD_POSIX
-void Platform_ConvertString(void* data, const String* src) {
+int Platform_ConvertString(void* data, const String* src) {
 	uint8_t* dst = data;
 	Codepoint cp;
 	int i, len;
@@ -1812,6 +1813,7 @@ void Platform_ConvertString(void* data, const String* src) {
 		len = Stream_WriteUtf8(dst, cp); dst += len;
 	}
 	*dst = '\0';
+	return len;
 }
 
 void Platform_Init(void) {

src/Platform.h

@@ -47,8 +47,9 @@ void GraphicsMode_Make(struct GraphicsMode* m, int bpp, int depth, int stencil,
 void GraphicsMode_MakeDefault(struct GraphicsMode* m);
 
 /* Encodes a string in platform specific format. (e.g. unicode on windows, UTF8 on linux) */
-/* NOTE: Only useful for platform specific function calls - do NOT try to interpret the data. */
+/* NOTE: Only useful for platform specific function calls - do NOT try to interpret the data. 
-void Platform_ConvertString(void* data, const String* src);
+Returns the number of bytes written, excluding trailing NULL terminator. */
+NOINLINE_ int Platform_ConvertString(void* data, const String* src);
 /* Initalises the platform specific state */
 void Platform_Init(void);
 /* Frees the platform specific state */

src/String.c

@@ -517,21 +517,21 @@ Codepoint Convert_CP437ToUnicode(char c) {
 }
 
 char Convert_UnicodeToCP437(Codepoint cp) {
-	char value; Convert_TryUnicodeToCP437(cp, &value); return value;
+	char c; Convert_TryUnicodeToCP437(cp, &c); return c;
 }
 
-bool Convert_TryUnicodeToCP437(Codepoint cp, char* value) {
+bool Convert_TryUnicodeToCP437(Codepoint cp, char* c) {
 	int i;
-	if (cp >= 0x20 && cp < 0x7F) { *value = (char)cp; return true; }
+	if (cp >= 0x20 && cp < 0x7F) { *c = (char)cp; return true; }
 
 	for (i = 0; i < Array_Elems(Convert_ControlChars); i++) {
-		if (Convert_ControlChars[i] == cp) { *value = i; return true; }
+		if (Convert_ControlChars[i] == cp) { *c = i; return true; }
 	}
 	for (i = 0; i < Array_Elems(Convert_ExtendedChars); i++) {
-		if (Convert_ExtendedChars[i] == cp) { *value = i + 0x7F; return true; }
+		if (Convert_ExtendedChars[i] == cp) { *c = i + 0x7F; return true; }
 	}
 
-	*value = '?'; return false;
+	*c = '?'; return false;
 }
 
 void String_DecodeUtf8(String* str, uint8_t* data, uint32_t len) {

src/String.h

@@ -62,12 +62,12 @@ NOINLINE_ int String_UNSAFE_Split(STRING_REF const String* str, char c, String*
 /* If c is not found, sets key to str and value to String_Empty, returns false. */
 NOINLINE_ bool String_UNSAFE_Separate(STRING_REF const String* str, char c, String* key, String* value);
 
-/* Returns whether all characters of the strings are equal. */
+/* Whether all characters of the strings are equal. */
 NOINLINE_ bool String_Equals(const String* a, const String* b);
-/* Returns whether all characters of the strings are case-insensitively equal. */
+/* Whether all characters of the strings are case-insensitively equal. */
 NOINLINE_ bool String_CaselessEquals(const String* a, const String* b);
-/* Returns whether all characters of the strings are case-insensitively equal. */
+/* Whether all characters of the strings are case-insensitively equal. */
-/* NOTE: This is faster than String_CaselessEquals(a, String_FromReadonly(b)) */
+/* NOTE: Faster than String_CaselessEquals(a, String_FromReadonly(b)) */
 NOINLINE_ bool String_CaselessEqualsConst(const String* a, const char* b);
 /* Breaks down an integer into an array of digits. */
 /* NOTE: Digits are in reverse order, so e.g. '200' becomes '0','0','2' */
@@ -135,9 +135,14 @@ NOINLINE_ bool String_CaselessEnds(const String* str, const String* sub);
 /* else returns 0. NOTE: The return value is not just in -1,0,1! */
 NOINLINE_ int  String_Compare(const String* a, const String* b);
 
+/* See String_Format4 */
 void String_Format1(String* str, const char* format, const void* a1);
+/* See String_Format4 */
 void String_Format2(String* str, const char* format, const void* a1, const void* a2);
+/* See String_Format4 */
 void String_Format3(String* str, const char* format, const void* a1, const void* a2, const void* a3);
+/* Formats the arguments in a string, similiar to printf or C# String.Format
+NOTE: This is a low level API. Argument count and types are not checked at all. */
 void String_Format4(String* str, const char* format, const void* a1, const void* a2, const void* a3, const void* a4);
 
 /* Converts a code page 437 character to its unicode equivalent. */
@@ -145,7 +150,7 @@ Codepoint Convert_CP437ToUnicode(char c);
 /* Converts a unicode character to its code page 437 equivalent, or '?' if no match. */
 char Convert_UnicodeToCP437(Codepoint cp);
 /* Attempts to convert a unicode character to its code page 437 equivalent. */
-bool Convert_TryUnicodeToCP437(Codepoint cp, char* value);
+bool Convert_TryUnicodeToCP437(Codepoint cp, char* c);
 /* Appends all characters from UTF8 encoded data to the given string. */
 void String_DecodeUtf8(String* str, uint8_t* data, uint32_t len);
 

src/WinWindow.c

@@ -387,7 +387,7 @@ static LRESULT CALLBACK Window_Procedure(HWND handle, UINT message, WPARAM wPara
 /*########################################################################################################################*
 *--------------------------------------------------Public implementation--------------------------------------------------*
 *#########################################################################################################################*/
-void Window_Create(int x, int y, int width, int height, const String* title, struct GraphicsMode* mode, struct DisplayDevice* device) {
+void Window_Create(int x, int y, int width, int height, struct GraphicsMode* mode) {
 	win_Instance = GetModuleHandleW(NULL);
 	/* TODO: UngroupFromTaskbar(); */
 
@@ -396,34 +396,33 @@ void Window_Create(int x, int y, int width, int height, const String* title, str
 	AdjustWindowRect(&rect, win_Style, false);
 
 	WNDCLASSEXW wc = { 0 };
-	wc.cbSize = sizeof(WNDCLASSEXW);
+	wc.cbSize    = sizeof(WNDCLASSEXW);
-	wc.style = CS_OWNDC;
+	wc.style     = CS_OWNDC;
 	wc.hInstance = win_Instance;
-	wc.lpfnWndProc = Window_Procedure;
+	wc.lpfnWndProc   = Window_Procedure;
 	wc.lpszClassName = win_ClassName;
 	/* TODO: Set window icons here */
 	wc.hCursor = LoadCursorW(NULL, IDC_ARROW);
 
 	ATOM atom = RegisterClassExW(&wc);
-	if (atom == 0) {
+	if (!atom) ErrorHandler_Fail2(GetLastError(), "Failed to register window class");
-		ErrorHandler_Fail2(GetLastError(), "Failed to register window class");
-	}
-	WCHAR str[300]; Platform_ConvertString(str, title);
 
-	win_Handle = CreateWindowExW(0, atom, str, win_Style,
+	win_Handle = CreateWindowExW(0, atom, NULL, win_Style,
 		rect.left, rect.top, Rect_Width(rect), Rect_Height(rect),
 		NULL, NULL, win_Instance, NULL);
+	if (!win_Handle) ErrorHandler_Fail2(GetLastError(), "Failed to create window");
 
-	if (!win_Handle) {
-		ErrorHandler_Fail2(GetLastError(), "Failed to create window");
-	}
 	win_DC = GetDC(win_Handle);
-	if (!win_DC) {
+	if (!win_DC) ErrorHandler_Fail2(GetLastError(), "Failed to get device context");
-		ErrorHandler_Fail2(GetLastError(), "Failed to get device context");
-	}
 	Window_Exists = true;
 }
 
+void Window_SetTitle(const String* title) {
+	WCHAR str[300]; 
+	Platform_ConvertString(str, title);
+	SetWindowTextW(win_Handle, str);
+}
+
 void Window_GetClipboardText(String* value) {
 	/* retry up to 10 times*/
 	int i;

src/Window.h

@@ -30,52 +30,96 @@
    OTHER DEALINGS IN THE SOFTWARE.
 */
 
+/* The states a window can be in. */
 typedef enum WindowState_ {
 	WINDOW_STATE_NORMAL, WINDOW_STATE_MINIMISED, WINDOW_STATE_MAXIMISED, WINDOW_STATE_FULLSCREEN
 } WindowState;
 struct GraphicsMode;
-struct DisplayDevice;
 
-void Window_Create(int x, int y, int width, int height, const String* title, struct GraphicsMode* mode, struct DisplayDevice* device);
+/* Creates a new window of the given size at the given position on screen. */
+void Window_Create(int x, int y, int width, int height, struct GraphicsMode* mode);
+/* Sets the text of the titlebar above the window. */
+void Window_SetTitle(const String* title);
+/* Gets the text currently on the clipboard. */
+/* NOTE: You must have created a window beforehand. (necessary for X11) */
 void Window_GetClipboardText(String* value);
+/* Sets the text currently on the clipboard. */
+/* NOTE: You must have created a window beforehand. (necessary for X11) */
 void Window_SetClipboardText(const String* value);
 /* TODO: IMPLEMENT void Window_SetIcon(Bitmap* bmp); */
 
-bool Window_Exists, Window_Focused;
+/* Whether the window is actually valid (i.e. not destroyed). */
+bool Window_Exists;
+/* Whether the user is interacting with the window. */
+bool Window_Focused;
+/* Whether the window is visible on screen at all. */
+/* NOTE: This does not count when just hidden behind other windows. */
 bool Window_GetVisible(void);
+/* Sets whether the window is visible on screen at all. */
 void Window_SetVisible(bool visible);
+/* Returns the platform-specific handle to the window. */
 void* Window_GetWindowHandle(void);
+/* Gets the current state of the window, see WindowState enum. */
 int Window_GetWindowState(void);
+/* Sets the current state of the window, see WindowState enum. */
 void Window_SetWindowState(int state);
 
+/* The external bounds of the window in screen coordinates. */
+/* Size of external bounds is client size + borders + title */
 Rect2D Window_Bounds;
+/* Size of the internal bounds of the window. */
+/* This is the size of area that can be drawn on. (i.e. content size) */
 Size2D Window_ClientSize;
-
+/* Sets the position and external size of the window. */
 void Window_SetBounds(Rect2D rect);
+/* Sets the position of the window on the screen. */
 void Window_SetLocation(int x, int y);
+/* Sets the external size of the window. */
+/* NOTE: You usually want to use Window_SetClientSize instead. */
 void Window_SetSize(int width, int height);
+/* Sets the internal size of the window. */
 void Window_SetClientSize(int width, int height);
 
+/* Closes then destroys the window. */
+/* Raises the WindowClosing and WindowClosed events. */
 void Window_Close(void);
+/* Processes all pending window messages/events. */
 void Window_ProcessEvents(void);
 /* Transforms the specified point from screen to client coordinates. */
 Point2D Window_PointToClient(int x, int y);
 /* Transforms the specified point from client to screen coordinates. */
 Point2D Window_PointToScreen(int x, int y);
 
+/* Gets the position of the cursor in screen coordinates. */
 Point2D Window_GetScreenCursorPos(void);
+/* Sets the position of the cursor in screen coordinates.*/
 void Window_SetScreenCursorPos(int x, int y);
+/* Whether the cursor is visible when over this window. */
 bool Window_GetCursorVisible(void);
+/* Sets whether the cursor is visible when over this window. */
+/* NOTE: You must be careful with this! OS typically uses a counter for visibility,
+so setting invisible multiple times means you must then set visible multiple times. */
 void Window_SetCursorVisible(bool visible);
 
 #ifndef CC_BUILD_D3D9
+/* Initalises an OpenGL context that most closely matches the input arguments. */
+/* NOTE: You must have created a window beforehand, as the GL context is attached to the window. */
 void GLContext_Init(struct GraphicsMode* mode);
+/* Updates the OpenGL context after the window is resized. */
 void GLContext_Update(void);
+/* Destroys the OpenGL context. */
+/* NOTE: This also unattaches the OpenGL context from the window. */
 void GLContext_Free(void);
 
 #define GLContext_IsInvalidAddress(ptr) (ptr == (void*)0 || ptr == (void*)1 || ptr == (void*)-1 || ptr == (void*)2)
+/* Returns the address of a function pointer for the given OpenGL function. */
+/* NOTE: The platform may still return an address for unsupported functions. 
+You must check the OpenGL version and/or GL_EXTENSIONS string for actual support! */
 void* GLContext_GetAddress(const char* function);
+/* Swaps the front and back buffer, displaying the back buffer on screen. */
 void GLContext_SwapBuffers(void);
+/* Sets whether synchronisation with the monitor is used. */
+/* NOTE: The underlying platform may choose to still ignore this. */
 void GLContext_SetVSync(bool enabled);
 #endif
 #endif