diff --git a/macos/error.h b/macos/error.h index ce9f1e9..61247be 100644 --- a/macos/error.h +++ b/macos/error.h @@ -7,40 +7,62 @@ // Error codes, corresponding to messages in a STR# resource. This should be // kept in sync with STR# rSTRS_Errors in resources.r. typedef enum { + // An unknown error occurred. kErrUnknown = 1, + // An internal error occurred. kErrInternal, + // Out of memory. kErrOutOfMemory, + // Could not save project "^1". kErrCouldNotSaveProject, } ErrorCode; -// Show an error dialog with the given error message, then quit the program. +// ExitError shows an error dialog with the given error message, then quits the +// program. void ExitError(ErrorCode errCode); -// Show an error dialog with the given error message and an OS error code, then -// quit the program. +// ExitErrorOS shows an error dialog with the given error message and an OS +// error code, then quits the program. void ExitErrorOS(ErrorCode errCode, short osErr); -// Show an out of memory error and quit the program. +// ExitMemError shows an out of memory error and quits the program. void ExitMemError(void); -// Show an assertion error and quit the program. +// ExitAssert shows an assertion error and quits the program. The message may be +// NULL. void ExitAssert(const unsigned char *file, int line, const unsigned char *message); +// EXIT_ASSERT shows an assertion error and quits the program. The message may +// be NULL. #define EXIT_ASSERT(str) ExitAssert("\p" __FILE__, __LINE__, str) +// ASSERT checks that the given condition is true. Otherwise, it displays an +// error message and quits the program. #define ASSERT(p) \ do { \ if (!(p)) \ ExitAssert("\p" __FILE__, __LINE__, "\p" #p); \ } while (0) +// An ErrorParams contains the parameters for displaying en error alert window. +// This structure should be zeroed before use, in case additional fields are +// added. struct ErrorParams { + // The application error code. If this is zero, it will be treated as + // kErrInternal. ErrorCode err; + + // The OS error code. This is displayed at the end of the error message, + // unless it is zero. short osErr; + + // If the error messages contain any string substitutions like "^1", those + // substitutions are replaced with this string. const unsigned char *strParam; }; +// ShowError shows an error alert window to the user. void ShowError(const struct ErrorParams *p); #endif diff --git a/macos/main.c b/macos/main.c index 8f97d46..51e0fb9 100644 --- a/macos/main.c +++ b/macos/main.c @@ -17,6 +17,7 @@ void QuitApp(void) ExitToShell(); } +// HandleClose handles a request to close the given window. static void HandleClose(WindowRef window) { ProjectHandle project; @@ -33,6 +34,7 @@ static void HandleClose(WindowRef window) } } +// AdjustMenus adjusts menus before selecting a menu item. static void AdjustMenus(void) { WindowRef window; @@ -66,6 +68,8 @@ static void AdjustMenus(void) } } +// HandleMenuCommand handles a menu command. The top 16 bits store the menu ID, +// and the low 16 bits store the item within that menu. static void HandleMenuCommand(long command) { int menuID = command >> 16; @@ -114,7 +118,7 @@ static void HandleMenuCommand(long command) SysBeep(1); } -// Handle a mouse down event. +// HandleMouseDown handles a mouse down event. static void HandleMouseDown(EventRecord *event) { short clickPart; @@ -171,6 +175,7 @@ static void HandleMouseDown(EventRecord *event) } } +// HandleKeyDown handles a key down event. static void HandleKeyDown(EventRecord *event) { long command; @@ -183,6 +188,7 @@ static void HandleKeyDown(EventRecord *event) } } +// HandleActivate handles a window activate event. static void HandleActivate(EventRecord *event) { ProjectHandle project; @@ -204,6 +210,7 @@ static void HandleActivate(EventRecord *event) SetPort(savedPort); } +// HandleUpdate handles a window update event. static void HandleUpdate(EventRecord *event) { ProjectHandle project; diff --git a/macos/project.h b/macos/project.h index 215f79a..6d1e460 100644 --- a/macos/project.h +++ b/macos/project.h @@ -4,26 +4,26 @@ #ifndef MACOS_PROJECT_H #define MACOS_PROJECT_H -// Handle to a synchronization project. +// A ProjectHandle is a handle to a synchronization project. typedef struct Project **ProjectHandle; -// Create a new empty synchronization project. +// ProjectNew creates a new empty synchronization project. void ProjectNew(void); -// Adjust menus before selecting a menu item. +// ProjectAdjustMenus adjusts menus before selecting a menu item. void ProjectAdjustMenus(ProjectHandle project, MenuHandle fileMenu); -// Handle a menu command or equivalent. +// ProjectCommand handles a menu command or equivalent. void ProjectCommand(WindowRef window, ProjectHandle project, int menuID, int item); -// Handle an update event for a project window. +// ProjectUpdate handles an update event for a project window. void ProjectUpdate(WindowRef window, ProjectHandle project); -// Set whether a project window is active. +// ProjectActivate sets whether a project window is active. void ProjectActivate(WindowRef window, ProjectHandle project, int isActive); -// Handle a mouse down event in a window. +// ProjectMouseDown handles a mouse down event in a window. void ProjectMouseDown(WindowRef window, ProjectHandle project, EventRecord *event); diff --git a/macos/strutil.h b/macos/strutil.h index 345bcfd..cfb5b9c 100644 --- a/macos/strutil.h +++ b/macos/strutil.h @@ -4,21 +4,21 @@ #ifndef MACOS_STRUTIL_H #define MACOS_STRUTIL_H -// Write a formatted string. +// StrFormat writes a formatted string to another string, replacing it. void StrFormat(unsigned char *dest, const unsigned char *msg, ...); -// Append a formatted string to another string. +// StrAppend appends a formatted string to another string. // // %% - literal % // %d - int argument // %S - Pascal string argument void StrAppendFormat(unsigned char *dest, const unsigned char *msg, ...); -// Copy a Pascal string. Aborts the program if the string does not fit in the -// destination buffer. +// StrCopy copies a Pascal string. Aborts the program if the string does not fit +// in the destination buffer. void StrCopy(unsigned char *dest, int dest_size, unsigned char *src); -// Substitute ^1 in the string with param. +// StrSubstitute substitute ^1 in the string with param. void StrSubstitute(unsigned char *str, const unsigned char *param); #endif