// Copyright (c) Jon Thysell <http://jonthysell.com>
// Licensed under the MIT License.

/**
 * @file MacCommon.h
 *
 * This file includes some common utility functions for use by Macintosh
 * applications and the Macintosh Toolbox.
 */

#ifndef MACCOMMON_H
#define MACCOMMON_H

#include "Common.h"

/** The first non-reserved resource ID. */
#define BaseResID       128

/** Constant to put a Window to the top of the stack. */
#define MoveToFront     (WindowPtr)-1L

/** An empty Pascal string. */
#define EmptyString     "\p"

/** A nil filter. */
#define NilFilterProc   nil

/** Enum defining nine equal boxes within a rectangle. */
typedef enum eBoxAlignment
{
    Top,
    TopLeft,
    Left,
    BottomLeft,
    Bottom,
    BottomRight,
    Right,
    TopRight,
    Center
} BoxAlignment;

/**
 * Toolbox function to set the default Button in a Dialog.
 * @param theDialog The target Dialog.
 * @param itemID The ID of the Button to set as the default.
 * @return An error code.
 */
pascal OSErr SetDialogDefaultItem(DialogPtr theDialog, int16_t itemID) = { 0x303C, 0x0304, 0xAA68 };

/**
 * Displays an error message and optionally terminates the application.
 * @param message The message to display.
 * @param isFatal Whether or not the application should terminate.
 */
void ShowError(Str255 message, bool isFatal);

/**
 * Prompts the user to confirm continuing with a (destructive) action.
 * @param message The message to display.
 * @return The user's choice whether or not to continue.
 */
bool ShowConfirm(Str255 message);

/**
 * Centers an inner Rect within a static outer Rect.
 * @param pOuterRect The static outer Rect.
 * @param pInnerRect The inner Rect to move.
 */
void CenterRect(const Rect *pOuterRect, Rect *pInnerRect);

/**
 * Centers an inner Rect horizontally within a static outer Rect.
 * @param pOuterRect The static outer Rect.
 * @param pInnerRect The inner Rect to move.
 */
void CenterRectH(const Rect *pOuterRect, Rect *pInnerRect);

/**
 * Centers an inner Rect vertically within a static outer Rect.
 * @param pOuterRect The static outer Rect.
 * @param pInnerRect The inner Rect to move.
 */
void CenterRectV(const Rect *pOuterRect, Rect *pInnerRect);

/**
 * Combines two Rects into a new Rect, by moving the right Rect directly
 * to the right of the left Rect (tops aligned), and finding the smallest
 * Rect which contains them both.
 * @param pLeftRect The Rect on the left.
 * @param pRightRect The Rect on the right.
 * @param pDestRect The concatenated Rect.
 */
void ConcatenateRect(const Rect *pLeftRect, const Rect *pRightRect, Rect *pDestRect);

/**
 * Gets the Rect at the given BoxAlignment within the static outer Rect.
 * @param pOuterRect The static outer Rect.
 * @param boxAlignment The target BoxAlignment.
 * @param pBoxRect The Rect within the outer rect at the BoxAlignment.
 */
void GetBoxRect(const Rect *pOuterRect, const BoxAlignment boxAlignment, Rect *pBoxRect);

/**
 * Gets the Rect which bounds the given picture.
 * @param picHandle The target picture.
 * @param pDestRect The Rect bounding the picture.
 */
void GetPictureRect(const PicHandle picHandle, Rect *pDestRect);

/**
 * Gets the Rect which bounds the given picture if it had been scaled.
 * @param picHandle The target picture.
 * @param scale The scale factor.
 * @param pDestRect The Rect bounding the scaled picture.
 */
void GetScaledPicFrame(const PicHandle picHandle, const uint8_t scale, Rect *pDestRect);

/**
 * Draws the given picture scaled at the pen's location.
 * @param picHandle The target picture.
 * @param scale The scale factor.
 */
void DrawScaledPic(const PicHandle pic, const uint8_t scale);

/**
 * Gets the specified resource or creates it if it doesn't exist.
 * @param resType The resource type.
 * @param resID The resource ID.
 * @param byteCount The size of the resource if it needs to be created.
 * @param resName The resource name if it needs to be created.
 * @return Handle to the resource.
 */
Handle GetOrAddResource(ResType resType, uint16_t resID, Size byteCount, Str255 resName);

#endif