Foenix A2650 OS/f Library: window.h File Reference

Searching...

No Matches

#include "control.h"
#include "mouse.h"
#include <stdbool.h>
#include <mcp/syscalls.h>
#include "a2560k.h"

Data Structures
struct	ClipRect

struct	Window

struct	NewWinTemplate

Functions
Window *	Window_New (NewWinTemplate the_win_template, void(event_handler)(EventRecord *))
	Allocate a Window object the_win_template->width_: cannot be smaller than WIN_DEFAULT_MIN_WIDTH, cannot be greater than WIN_DEFAULT_MAX_WIDTH the_win_template->height_: cannot be smaller than WIN_DEFAULT_MIN_HEIGHT, cannot be greater than WIN_DEFAULT_MAX_HEIGHT the_win_template->min_width_: cannot be smaller than WIN_DEFAULT_MIN_WIDTH the_win_template->min_height_: cannot be smaller than WIN_DEFAULT_MIN_HEIGHT the_win_template->max_width_: cannot be smaller than WIN_DEFAULT_MIN_WIDTH the_win_template->max_height_: cannot be smaller than WIN_DEFAULT_MIN_HEIGHT. More...

bool	Window_Destroy (Window **the_window)

NewWinTemplate *	Window_GetNewWinTemplate (char *the_win_title)
	Allocate and populate a new window template object Assigns (but does not copy) the passed title string; leaves bitmaps NULL; assigns the pre-defined default value to all other fields Calling method must free the returned NewWinTemplate pointer after creating a window with it. More...

bool	Window_AddClipRect (Window the_window, Rectangle new_rect)
	Copy the passed rectangle to the window's clip rect collection If the window already has the maximum allowed number of clip rects, the rectangle will not be added. More...

bool	Window_MergeClipRects (Window *the_window)
	Merge and de-duplicate clip rects Consolidating the clip rects will happen reduce unnecessary reblitting. More...

bool	Window_BlitClipRects (Window *the_window)
	Blit each clip rect to the screen, and clear all clip rects when done This is the actual mechanics of rendering the window to the screen. More...

bool	Window_GenerateDamageRects (Window the_window, Rectangle the_old_rect)
	Calculate damage rects, if any, caused by window moving or being resized NOTE: it is not necessarily an error condition if a given window doesn't end up with damage rects as a result of this operation: if the window rect doesn't intersect the incoming rect, no damage is relevant. More...

bool	Window_AcceptDamageRect (Window the_window, Rectangle damage_rect)
	Copy the passed rectangle to the window's clip rect collection, translating to local coordinates as it does so NOTE: the incoming rect is assumed to be using global, not window-local coordinates. More...

MouseMode	Window_CheckForDragZone (Window *the_window, int16_t x, int16_t y)
	Checks if the passed coordinate is within one of the draggable event zones Draggable event zones include the title bar, 4 single-direction resize zones on the window edges, and the lower-right traditional resize zone. More...

bool	Window_SetSelectedControl (Window the_window, Control the_control)
	Sets the passed control as the currently selected control and unselects any previously selected control. More...

bool	Window_AddControl (Window the_window, Control the_control)
	Adds the passed control to the window's list of controls. More...

Control *	Window_AddNewControlFromTemplate (Window the_window, ControlTemplate the_template, int16_t the_id, int16_t group_id)
	Instantiate a new control from the passed template, and add it to the window's list of controls. More...

Control *	Window_AddNewControl (Window the_window, control_type the_type, int16_t width, int16_t height, int16_t x_offset, int16_t y_offset, h_align_type the_h_align, v_align_type the_v_align, char the_caption, int16_t the_id, int16_t group_id)
	Instantiate a new control of the type specified, and add it to the window's list of controls. More...

void	Window_InvalidateTitlebar (Window *the_window)
	Invalidate the title bar and the controls in the title bar Call when switching from inactive to active window, and vice versa, to force controls and title bar to redraw appropriately. More...

void	Window_InvalidateControlByID (Window *the_window, uint16_t the_control_id)
	Invalidate the control matching the ID passed. More...

Control *	Window_GetSelectedControl (Window *the_window)
	Get the control listed as the currently selected control. More...

Control *	Window_GetLastControl (Window *the_window)
	Find and return the last control in the window's chain of controls This corresponds to the first control with a NULL value for next_. More...

Control *	Window_GetControl (Window *the_window, int16_t the_control_id)
	Return a pointer to the control owned by the window that matches the specified ID NOTE: Control IDs 0-3 are reserved by the system for standard controls (close, minimize, etc.). More...

int16_t	Window_GetControlID (Window the_window, Control the_control)
	Return the ID of the control passed, if the window actually owns that control NOTE: Control IDs 0-3 are reserved by the system for standard controls (close, minimize, etc.). More...

Control *	Window_GetControlAtXY (Window *the_window, int16_t x, int16_t y)
	Find the control, if any, located at the specified local coordinates Transparency is not taken into account: if the passed coordinate intersects the control's rectangle at any point, it is considered a match. More...

void	Window_SetTitle (Window the_window, char the_title)
	Replace the current window title with the passed string Note: the passed string will be copied into storage by the window. More...

void	Window_SetVisible (Window *the_window, bool is_visible)
	Set the window's visibility flag. More...

void	Window_SetDisplayOrder (Window *the_window, int8_t the_display_order)
	Set the display order of the window NOTE: This does not immediately re-render or change the display order visibly. More...

void	Window_SetActive (Window *the_window, bool is_active)
	Set the passed window's active flag. More...

void	Window_SetState (Window *the_window, window_state the_state)
	Set the window's state (maximized, minimized, etc.) NOTE: This does not immediately cause the window to render in the passed state. More...

void	Window_EvaluateWindowChange (Window the_window, int16_t x, int16_t y, int16_t width, int16_t *height)
	Evaluate potential change to window position or size, and correct if out of allowed limits Negative value positions will be corrected to 0. More...

void	Window_ChangeWindow (Window *the_window, int16_t x, int16_t y, int16_t width, int16_t height, bool update_norm)
	Change position and/or size of window NOTE: passed x, y will be checked against the window's min/max values Will also adjust the position of the built-in maximize/minimize/normsize controls. More...

void	Window_Maximize (Window *the_window)
	Set the window to full-screen size (maximize mode) Sets window's x, y, width, height parameters to match those of the screen. More...

void	Window_NormSize (Window *the_window)
	Set the window to normal size (window-size mode) Sets window's x, y, width, height parameters to those stored in norm_x, etc. More...

void	Window_Minimize (Window *the_window)
	Hides the window (minimize mode) Does not change the window's x, y, width, height parameters, it just makes it invisible. More...

char *	Window_GetTitle (Window *the_window)
	Get a pointer to the current window title Note: It is not guaranteed that every window will have a title. More...

uint32_t	Window_GetUserData (Window *the_window)
	Get the value stored in the user data field of the window. More...

window_type	Window_GetType (Window *the_window)
	Get the window's type (normal, backdrop, dialog, etc.) More...

window_state	Window_GetState (Window *the_window)
	Get the window's state (maximized, minimized, etc.) More...

Bitmap *	Window_GetBitmap (Window *the_window)
	Get the bitmap object used as the offscreen buffer for the window NOTE: this is not a pointer into VRAM, or directly to the screen. More...

int16_t	Window_GetX (Window *the_window)
	Get the global horizontal coordinate of the window. More...

int16_t	Window_GetY (Window *the_window)
	Get the global vertical coordinate of the window. More...

int16_t	Window_GetWidth (Window *the_window)
	Get the width of the window. More...

int16_t	Window_GetHeight (Window *the_window)
	Get the height of the window. More...

bool	Window_IsBackdrop (Window *the_window)
	Check if a window is a backdrop window or a regular window. More...

bool	Window_IsVisible (Window *the_window)
	Check if a window should be visible or not NOTE: this does not necessarily mean the window isn't currently rendered to the screen. More...

bool	Window_IsActive (Window *the_window)
	Get the active/inactive condition of the window. More...

void	Window_Render (Window *the_window)
	Draw/re-draw any necessary components, and blit the window (or parts of it, via cliprects) to the screen. More...

void	Window_ClearContent (Window *the_window)
	Clears the content area rect by filling it with the theme's backcolor. More...

void	Window_UpdateTheme (Window *the_window)
	Updates the current window controls, etc., to match the current system theme. More...

void	Window_Invalidate (Window *the_window)
	Mark entire window as invalidated This will cause it to be redrawn and fully reblitted in the next render cycle. More...

void	Window_GlobalToLocal (Window the_window, int16_t x, int16_t *y)
	Convert the passed x, y global coordinates to local (to window) coordinates. More...

void	Window_LocalToGlobal (Window the_window, int16_t x, int16_t *y)
	Convert the passed x, y local coordinates to global coordinates. More...

bool	Window_SetFont (Window the_window, Font the_font)
	Set the font This is the font that will be used for any subsequent font drawing in this Window This also sets the font of the window's bitmap This only affects programmer-controlled drawing actions; it will not change the title bar font, the icon font, etc. More...

bool	Window_SetColor (Window *the_window, uint8_t the_color)
	Set the "pen" color This is the color that the next pen-based graphics function will use This also sets the pen color of the window's bitmap This only affects functions that use the pen: any graphics function that specifies a color will use that instead. More...

bool	Window_SetPenXYFromGlobal (Window *the_window, int16_t x, int16_t y)
	Set the local "pen" position within the window, based on global coordinates This also sets the pen position of the window's bitmap This is the location that the next pen-based graphics function will use for a starting location. More...

bool	Window_SetPenXY (Window *the_window, int16_t x, int16_t y)
	Set the "pen" position within the content area This also sets the pen position of the window's bitmap This is the location that the next pen-based graphics function will use for a starting location. More...

bool	Window_Blit (Window the_window, Bitmap src_bm, int16_t src_x, int16_t src_y, int16_t width, int16_t height)
	Blit from source bitmap to the window's content area, at the window's current pen coordinate The source bitmap can be the window's bitmap: you can use this to copy a chunk of pixels from one part of a window to another. More...

bool	Window_FillBox (Window *the_window, int16_t width, int16_t height, uint8_t the_color)
	Fill a rectangle drawn from the current pen location, for the passed width/height. More...

bool	Window_FillBoxRect (Window the_window, Rectangle the_coords, uint8_t the_color)
	Fill pixel values for the passed Rectangle object, using the specified LUT value. More...

bool	Window_SetPixel (Window *the_window, uint8_t the_color)
	Set the color of the pixel at the current pen location. More...

bool	Window_DrawLine (Window *the_window, int16_t x1, int16_t y1, int16_t x2, int16_t y2, uint8_t the_color)
	Draws a line between 2 passed coordinates. More...

bool	Window_DrawHLine (Window *the_window, int16_t the_line_len, uint8_t the_color)
	Draws a horizontal line from the current pen location, for n pixels, using the specified pixel value. More...

bool	Window_DrawVLine (Window *the_window, int16_t the_line_len, uint8_t the_color)
	Draws a vertical line from specified coords, for n pixels. More...

bool	Window_DrawBoxRect (Window the_window, Rectangle the_coords, uint8_t the_color)
	Draws a rectangle based on the passed Rectangle object, using the specified LUT value. More...

bool	Window_DrawBoxCoords (Window *the_window, int16_t x1, int16_t y1, int16_t x2, int16_t y2, uint8_t the_color)
	Draws a rectangle based on 2 sets of coords, using the specified LUT value. More...

bool	Window_DrawBox (Window *the_window, int16_t width, int16_t height, uint8_t the_color, bool do_fill)
	Draws a rectangle based on start coords and width/height, and optionally fills the rectangle. More...

bool	Window_DrawRoundBox (Window *the_window, int16_t width, int16_t height, int16_t radius, uint8_t the_color, bool do_fill)
	Draws a rounded rectangle from the current pen location, with the specified size and radius, and optionally fills the rectangle. More...

bool	Window_DrawCircle (Window *the_window, int16_t radius, uint8_t the_color)
	Draw a circle centered on the current pen location Based on http://rosettacode.org/wiki/Bitmap/Midpoint_circle_algorithm#C. More...

char *	Window_DrawStringInBox (Window the_window, int16_t width, int16_t height, char the_string, int16_t num_chars, char *wrap_buffer, bool(continue_function)(void))
	Draw a string in a rectangular block on the window, with wrap. More...

void	Window_Print (Window *the_window)

Function Documentation

◆ Window_AcceptDamageRect()

bool Window_AcceptDamageRect	(	Window *	the_window,
		Rectangle *	damage_rect
	)

Copy the passed rectangle to the window's clip rect collection, translating to local coordinates as it does so NOTE: the incoming rect is assumed to be using global, not window-local coordinates.

Coordinates will be translated to window-local. Note: it is safe to pass non-intersecting rects to this function: it will check for non-intersection; will trim copy of clip to just the intersection

Parameters

the_window	– reference to a valid Window object.
damage_rect	– reference to the rectangle describing the coordinates to be added to the window as a clipping rect.. Coordinates of this rect must be global!

Returns: : Returns true if the passed rect has any intersection with the window. Returns false if not intersection, or on any error condition.

◆ Window_AddClipRect()

bool Window_AddClipRect	(	Window *	the_window,
		Rectangle *	new_rect
	)

Copy the passed rectangle to the window's clip rect collection If the window already has the maximum allowed number of clip rects, the rectangle will not be added.

NOTE: the incoming rect must be using window-local coordinates, not global. No translation will be performed.

Parameters

the_window	– reference to a valid Window object.
new_rect	– reference to the rectangle describing the coordinates to be added to the window as a clipping rect. Coordinates of this rect must be window-local! Coordinates in rect are copied to window storage, so it is safe to free the rect after calling this function.

Returns: : Returns true if rect is copied successfully. Returns false on any error, or if the window already had the maximum number of allowed clip rects.

◆ Window_AddControl()

bool Window_AddControl	(	Window *	the_window,
		Control *	the_control
	)

Adds the passed control to the window's list of controls.

Parameters

the_window	– reference to a valid Window object.
the_control	– reference to a valid Control object.

Returns: : Returns false in any error condition

◆ Window_AddNewControl()

Control * Window_AddNewControl	(	Window *	the_window,
		control_type	the_type,
		int16_t	width,
		int16_t	height,
		int16_t	x_offset,
		int16_t	y_offset,
		h_align_type	the_h_align,
		v_align_type	the_v_align,
		char *	the_caption,
		int16_t	the_id,
		int16_t	group_id
	)

Instantiate a new control of the type specified, and add it to the window's list of controls.

Parameters

the_window	– reference to a valid Window object.
the_type	– the type of control to be created. See the control_type enum definition.
width	– width, in pixels, of the control to be created
height	– height, in pixels, of the control to be created
x_offset	– horizontal offset, in pixels, from the left or right edge of the control, to the left or right edge of the parent rect, depending on the alignment choice
y_offset	– vertical offset, in pixels, from the top or bottom edge of the control, to the top or bottom edge of the parent rect, depending on the alignment choice
the_h_align	– horizontal alignment choice; determines if the control is located relative to the right or left edge of the parent rect, or is centered
the_v_align	– vertical alignment choice; determines if the control is located relative to the top or bottom edge of the parent rect, or is centered
the_caption	– optional string to be used as the caption for the control. Not all controls support captions. The string will be copied to the control's storage, so it is safe to free the string after calling this function.
the_id	– the unique ID (within the specified window) to be assigned to the control. WARNING: assigning multiple controls the same ID will result in undefined behavior.
group_id	– 1 byte group ID value to be assigned to the control. Pass CONTROL_NO_GROUP if the control is not to be part of a group.

Returns: : Returns a pointer to the new control, or NULL in any error condition

◆ Window_AddNewControlFromTemplate()

Control * Window_AddNewControlFromTemplate	(	Window *	the_window,
		ControlTemplate *	the_template,
		int16_t	the_id,
		int16_t	group_id
	)

Instantiate a new control from the passed template, and add it to the window's list of controls.

Parameters

the_window	– reference to a valid Window object.
the_template	– reference to a valid, populated ControlTemplate object. The created control will take most of its properties from this template.
the_id	– the unique ID (within the specified window) to be assigned to the control. WARNING: assigning multiple controls the same ID will result in undefined behavior.
group_id	– 1 byte group ID value to be assigned to the control. Pass CONTROL_NO_GROUP if the control is not to be part of a group.

Returns: : Returns a pointer to the new control, or NULL in any error condition

◆ Window_Blit()

bool Window_Blit	(	Window *	the_window,
		Bitmap *	src_bm,
		int16_t	src_x,
		int16_t	src_y,
		int16_t	width,
		int16_t	height
	)

Blit from source bitmap to the window's content area, at the window's current pen coordinate The source bitmap can be the window's bitmap: you can use this to copy a chunk of pixels from one part of a window to another.

If the destination location cannot fit the entirety of the copied rectangle, the copy will be truncated, but will not return an error.

Parameters

the_window	– reference to a valid Window object.
src_bm	– the source bitmap. It must have a valid address within the VRAM memory space.
src_x	– the upper left coordinate within the source bitmap, for the rectangle you want to copy. May be negative.
src_y	– the upper left coordinate within the source bitmap, for the rectangle you want to copy. May be negative.
width	– the scope of the copy, in pixels.
height	– the scope of the copy, in pixels.

◆ Window_BlitClipRects()

bool Window_BlitClipRects ( Window * the_window )

Blit each clip rect to the screen, and clear all clip rects when done This is the actual mechanics of rendering the window to the screen.

Parameters

the_window – reference to a valid Window object.

Returns: : Returns true if there are either no clips to blit, or if there are clips and they are blitted successfully. Returns false on any error.

◆ Window_ChangeWindow()

void Window_ChangeWindow	(	Window *	the_window,
		int16_t	x,
		int16_t	y,
		int16_t	width,
		int16_t	height,
		bool	update_norm
	)

Change position and/or size of window NOTE: passed x, y will be checked against the window's min/max values Will also adjust the position of the built-in maximize/minimize/normsize controls.

Parameters

the_window	– reference to a valid Window object.
x	– The new global horizontal position
y	– The new global vertical position
width	– The new width
height	– The new height
update_norm	– if true, the window's normal x/y/width/height properties will be updated to match the passed values. Pass false if setting maximize size, etc.

will contain global rect of window before resize/move

◆ Window_CheckForDragZone()

MouseMode Window_CheckForDragZone	(	Window *	the_window,
		int16_t	x,
		int16_t	y
	)

Checks if the passed coordinate is within one of the draggable event zones Draggable event zones include the title bar, 4 single-direction resize zones on the window edges, and the lower-right traditional resize zone.

Parameters

the_window	– reference to a valid Window object.
x	– window-local horizontal coordinate
y	– window-local vertical coordinate

◆ Window_ClearContent()

void Window_ClearContent ( Window * the_window )

Clears the content area rect by filling it with the theme's backcolor.

Parameters

the_window – reference to a valid Window object.

◆ Window_Destroy()

bool Window_Destroy ( Window ** the_window )

Parameters

the_window – reference to a valid Window object.

◆ Window_DrawBox()

bool Window_DrawBox	(	Window *	the_window,
		int16_t	width,
		int16_t	height,
		uint8_t	the_color,
		bool	do_fill
	)

Draws a rectangle based on start coords and width/height, and optionally fills the rectangle.

Parameters

the_window	– reference to a valid Window object.
width	– width, in pixels, of the rectangle to be drawn
height	– height, in pixels, of the rectangle to be drawn
the_color	– a 1-byte index to the current LUT
do_fill	– If true, the box will be filled with the provided color. If false, the box will only draw the outline.

Returns: : returns false on any error/invalid input.

◆ Window_DrawBoxCoords()

bool Window_DrawBoxCoords	(	Window *	the_window,
		int16_t	x1,
		int16_t	y1,
		int16_t	x2,
		int16_t	y2,
		uint8_t	the_color
	)

Draws a rectangle based on 2 sets of coords, using the specified LUT value.

Parameters

the_window	– reference to a valid Window object.
x1	– the starting horizontal position within the content area of the window
y1	– the starting vertical position within the content area of the window
x2	– the ending horizontal position within the content area of the window
y2	– the ending vertical position within the content area of the window
the_color	– a 1-byte index to the current LUT

Returns: : returns false on any error/invalid input.

◆ Window_DrawBoxRect()

bool Window_DrawBoxRect	(	Window *	the_window,
		Rectangle *	the_coords,
		uint8_t	the_color
	)

Draws a rectangle based on the passed Rectangle object, using the specified LUT value.

Parameters

the_window	– reference to a valid Window object.
the_coords	– the starting and ending coordinates within the content area of the window
the_color	– a 1-byte index to the current LUT

Returns: : returns false on any error/invalid input.

◆ Window_DrawCircle()

bool Window_DrawCircle	(	Window *	the_window,
		int16_t	radius,
		uint8_t	the_color
	)

Draw a circle centered on the current pen location Based on http://rosettacode.org/wiki/Bitmap/Midpoint_circle_algorithm#C.

Parameters

the_window	– reference to a valid Window object.
radius	– radius, in pixels, measured from the window's current pen location
the_color	– a 1-byte index to the current color LUT

◆ Window_DrawHLine()

bool Window_DrawHLine	(	Window *	the_window,
		int16_t	the_line_len,
		uint8_t	the_color
	)

Draws a horizontal line from the current pen location, for n pixels, using the specified pixel value.

Parameters

the_window	– reference to a valid Window object.
the_line_len	– The total length of the line, in pixels
the_color	– a 1-byte index to the current LUT

Returns: : returns false on any error/invalid input.

◆ Window_DrawLine()

bool Window_DrawLine	(	Window *	the_window,
		int16_t	x1,
		int16_t	y1,
		int16_t	x2,
		int16_t	y2,
		uint8_t	the_color
	)

Draws a line between 2 passed coordinates.

Use for any line that is not perfectly vertical or perfectly horizontal

Parameters

the_window	– reference to a valid Window object.
x1	– the starting horizontal position within the content area of the window
y1	– the starting vertical position within the content area of the window
x2	– the ending horizontal position within the content area of the window
y2	– the ending vertical position within the content area of the window
the_color	– a 1-byte index to the current color LUT Based on http://rosettacode.org/wiki/Bitmap/Bresenham%27s_line_algorithm#C. Used in C128 Lich King.

◆ Window_DrawRoundBox()

bool Window_DrawRoundBox	(	Window *	the_window,
		int16_t	width,
		int16_t	height,
		int16_t	radius,
		uint8_t	the_color,
		bool	do_fill
	)

Draws a rounded rectangle from the current pen location, with the specified size and radius, and optionally fills the rectangle.

Parameters

the_window	– reference to a valid Window object.
width	– width, in pixels, of the rectangle to be drawn
height	– height, in pixels, of the rectangle to be drawn
radius	– radius, in pixels, of the arc to be applied to the rectangle's corners. Minimum 3, maximum 20.
the_color	– a 1-byte index to the current color LUT
do_fill	– If true, the box will be filled with the provided color. If false, the box will only draw the outline.

Returns: : returns false on any error/invalid input.

◆ Window_DrawStringInBox()

char * Window_DrawStringInBox	(	Window *	the_window,
		int16_t	width,
		int16_t	height,
		char *	the_string,
		int16_t	num_chars,
		char **	wrap_buffer,
		bool(*)(void)	continue_function
	)

Draw a string in a rectangular block on the window, with wrap.

The current font, pen location, and pen color of the window will be used If a word can't be wrapped, it will break the word and move on to the next line. So if you pass a rect with 1 char of width, it will draw a vertical line of chars down the screen.

Parameters

the_window	– reference to a valid Window object.
width	– the horizontal size of the text wrap box, in pixels. The total of 'width' and the current X coord of the bitmap must not be greater than width of the window's content area.
height	– the vertical size of the text wrap box, in pixels. The total of 'height' and the current Y coord of the bitmap must not be greater than height of the window's content area.
the_string	– the null-terminated string to be displayed.
num_chars	– either the length of the passed string, or as much of the string as should be displayed.
wrap_buffer	– pointer to a pointer to a temporary text buffer that can be used to hold the wrapped ('formatted') characters. The buffer must be large enough to hold num_chars of incoming text, plus additional line break characters where necessary.
continue_function	– optional hook to a function that will be called if the provided text cannot fit into the specified box. If provided, the function will be called each time text exceeds available space. If the function returns true, another chunk of text will be displayed, replacing the first. If the function returns false, processing will stop. If no function is provided, processing will stop at the point text exceeds the available space.

Returns: : returns a pointer to the first character in the string after which it stopped processing (if string is too long to be displayed in its entirety). Returns the original string if the entire string was processed successfully. Returns NULL in the event of any error.

◆ Window_DrawVLine()

bool Window_DrawVLine	(	Window *	the_window,
		int16_t	the_line_len,
		uint8_t	the_color
	)

Draws a vertical line from specified coords, for n pixels.

Parameters

the_window	– reference to a valid Window object.
the_line_len	– The total length of the line, in pixels
the_color	– a 1-byte index to the current LUT

Returns: : returns false on any error/invalid input.

◆ Window_EvaluateWindowChange()

void Window_EvaluateWindowChange	(	Window *	the_window,
		int16_t *	x,
		int16_t *	y,
		int16_t *	width,
		int16_t *	height
	)

Evaluate potential change to window position or size, and correct if out of allowed limits Negative value positions will be corrected to 0.

Parameters

the_window	– reference to a valid Window object.
x	– Pointer to the proposed new horizontal position. If less than 0, it will be set to 0.
y	– Pointer to the proposed new vertical position. If less than 0, it will be set to 0.
width	– Pointer to the proposed new width. Will be set to window's minimum or maximum if necessary.
height	– Pointer to the proposed new height. Will be set to window's minimum or maximum if necessary.

◆ Window_FillBox()

bool Window_FillBox	(	Window *	the_window,
		int16_t	width,
		int16_t	height,
		uint8_t	the_color
	)

Fill a rectangle drawn from the current pen location, for the passed width/height.

Parameters

the_window	– reference to a valid Window object.
width	– width, in pixels, of the rectangle to be drawn
height	– height, in pixels, of the rectangle to be drawn
the_color	– a 1-byte index to the current LUT

Returns: : returns false on any error/invalid input.

◆ Window_FillBoxRect()

bool Window_FillBoxRect	(	Window *	the_window,
		Rectangle *	the_coords,
		uint8_t	the_color
	)

Fill pixel values for the passed Rectangle object, using the specified LUT value.

Parameters

the_window	– reference to a valid Window object.
the_coords	– the starting and ending coordinates within the content area of the window
the_color	– a 1-byte index to the current LUT

Returns: : returns false on any error/invalid input.

◆ Window_GenerateDamageRects()

bool Window_GenerateDamageRects	(	Window *	the_window,
		Rectangle *	the_old_rect
	)

Calculate damage rects, if any, caused by window moving or being resized NOTE: it is not necessarily an error condition if a given window doesn't end up with damage rects as a result of this operation: if the window rect doesn't intersect the incoming rect, no damage is relevant.

Parameters

the_window	– reference to a valid Window object.
the_old_rect	– reference to the rectangle to be checked for overlap with the specified window. Coordinates of this rect must be global!

Returns: : Returns true if 1 or more damage rects were created. Returns false on any error condition, or if no damage rects needed to be created.

◆ Window_GetBitmap()

Bitmap * Window_GetBitmap ( Window * the_window )

Get the bitmap object used as the offscreen buffer for the window NOTE: this is not a pointer into VRAM, or directly to the screen.

Parameters

the_window – reference to a valid Window object.

Returns: : Returns a pointer to the bitmap used by the window. Returns NULL in any error condition.

◆ Window_GetControl()

Control * Window_GetControl	(	Window *	the_window,
		int16_t	the_control_id
	)

Return a pointer to the control owned by the window that matches the specified ID NOTE: Control IDs 0-3 are reserved by the system for standard controls (close, minimize, etc.).

Other control IDs are specified by the programmer for each window. Control IDs are not global, they are window-specific.

Parameters

the_window	– reference to a valid Window object.
the_control_id	– ID of the control that you want to find

Returns: : Returns a pointer to the control with the ID passed, or NULL if no match found, or on any error condition

◆ Window_GetControlAtXY()

Control * Window_GetControlAtXY	(	Window *	the_window,
		int16_t	x,
		int16_t	y
	)

Find the control, if any, located at the specified local coordinates Transparency is not taken into account: if the passed coordinate intersects the control's rectangle at any point, it is considered a match.

Parameters

the_window	– reference to a valid Window object.
x	– window-local horizontal coordinate
y	– window-local vertical coordinate

Returns: : Returns a pointer to the control at the passed coordinates, or NULL if no match found, or on any error condition

◆ Window_GetControlID()

int16_t Window_GetControlID	(	Window *	the_window,
		Control *	the_control
	)

Return the ID of the control passed, if the window actually owns that control NOTE: Control IDs 0-3 are reserved by the system for standard controls (close, minimize, etc.).

Other control IDs are specified by the programmer for each window. Control IDs are not global, they are window-specific.

Parameters

the_window	– reference to a valid Window object.
the_control	– Pointer to the control whose ID you want to find

Returns: : Returns the ID of the control, or CONTROL_ID_NOT_FOUND if no match found, or CONTROL_ID_ERROR on any error condition

◆ Window_GetHeight()

int16_t Window_GetHeight ( Window * the_window )

Get the height of the window.

Parameters

the_window – reference to a valid Window object.

Returns: : Returns -1 in any error condition.

◆ Window_GetLastControl()

Control * Window_GetLastControl ( Window * the_window )

Find and return the last control in the window's chain of controls This corresponds to the first control with a NULL value for next_.

Parameters

the_window – reference to a valid Window object.

◆ Window_GetNewWinTemplate()

NewWinTemplate * Window_GetNewWinTemplate ( char * the_win_title )

Allocate and populate a new window template object Assigns (but does not copy) the passed title string; leaves bitmaps NULL; assigns the pre-defined default value to all other fields Calling method must free the returned NewWinTemplate pointer after creating a window with it.

Parameters

the_win_title – pointer to the string that will be assigned to the title_ property. No copy or allocation will take place.

Returns: : A NewWinTemplate with all values set to default, or NULL on any error condition

◆ Window_GetSelectedControl()

Control * Window_GetSelectedControl ( Window * the_window )

Get the control listed as the currently selected control.

Parameters

the_window – reference to a valid Window object.

Returns: : Returns a control pointer, or NULL on any error, or if there is no selected control currently

◆ Window_GetState()

window_state Window_GetState ( Window * the_window )

Get the window's state (maximized, minimized, etc.)

Parameters

the_window – reference to a valid Window object.

Returns: : Returns a window_state enum. Returns WIN_UNKNOWN_STATE in any error condition.

◆ Window_GetTitle()

char * Window_GetTitle ( Window * the_window )

Get a pointer to the current window title Note: It is not guaranteed that every window will have a title.

Backdrop windows, for example, do not have a title. Note: the window title is maintained by the window. Do not free the string pointer returned by this function!

Parameters

the_window – reference to a valid Window object.

Returns: : Returns a pointer to the title string. Returns NULL in any error condition.

◆ Window_GetType()

window_type Window_GetType ( Window * the_window )

Get the window's type (normal, backdrop, dialog, etc.)

Parameters

the_window – reference to a valid Window object.

Returns: : Returns a window_type enum. Returns WIN_UNKNOWN_TYPE in any error condition.

◆ Window_GetUserData()

uint32_t Window_GetUserData ( Window * the_window )

Get the value stored in the user data field of the window.

NOTE: this field is for the exclusive use of application programs. The system will not act on this data in any way: you are free to store whatever 4-byte value you want here.

Parameters

the_window – reference to a valid Window object.

Returns: : Returns an unsigned 32 bit value. Returns 0 in any error condition.

◆ Window_GetWidth()

int16_t Window_GetWidth ( Window * the_window )

Get the width of the window.

Parameters

the_window – reference to a valid Window object.

Returns: : Returns -1 in any error condition.

◆ Window_GetX()

int16_t Window_GetX ( Window * the_window )

Get the global horizontal coordinate of the window.

Parameters

the_window – reference to a valid Window object.

Returns: : Returns the horizontal portion of the upper-left coordinate of the window. Returns -1 in any error condition.

◆ Window_GetY()

int16_t Window_GetY ( Window * the_window )

Get the global vertical coordinate of the window.

Parameters

the_window – reference to a valid Window object.

Returns: : Returns the vertical portion of the upper-left coordinate of the window. Returns -1 in any error condition.

◆ Window_GlobalToLocal()

void Window_GlobalToLocal	(	Window *	the_window,
		int16_t *	x,
		int16_t *	y
	)

Convert the passed x, y global coordinates to local (to window) coordinates.

Parameters

the_window	– reference to a valid Window object.
x	– the global horizontal position to be converted to window-local.
y	– the global vertical position to be converted to window-local.

◆ Window_Invalidate()

void Window_Invalidate ( Window * the_window )

Mark entire window as invalidated This will cause it to be redrawn and fully reblitted in the next render cycle.

Parameters

the_window – reference to a valid Window object.

◆ Window_InvalidateControlByID()

void Window_InvalidateControlByID	(	Window *	the_window,
		uint16_t	the_control_id
	)

Invalidate the control matching the ID passed.

Parameters

the_window	– reference to a valid Window object.
the_control_id	– ID of the control that you want to invalidate

◆ Window_InvalidateTitlebar()

void Window_InvalidateTitlebar ( Window * the_window )

Invalidate the title bar and the controls in the title bar Call when switching from inactive to active window, and vice versa, to force controls and title bar to redraw appropriately.

Parameters

the_window – reference to a valid Window object.

◆ Window_IsActive()

bool Window_IsActive ( Window * the_window )

Get the active/inactive condition of the window.

Parameters

the_window – reference to a valid Window object.

Returns: : Returns true if window is active, false if not

◆ Window_IsBackdrop()

bool Window_IsBackdrop ( Window * the_window )

Check if a window is a backdrop window or a regular window.

Parameters

the_window – reference to a valid Window object.

Returns: : Returns true if backdrop, false if not

◆ Window_IsVisible()

bool Window_IsVisible ( Window * the_window )

Check if a window should be visible or not NOTE: this does not necessarily mean the window isn't currently rendered to the screen.

This indicates if it will or won't be after the next render pass.

Parameters

the_window – reference to a valid Window object.

Returns: : Returns true if window should be rendered, false if not

◆ Window_LocalToGlobal()

void Window_LocalToGlobal	(	Window *	the_window,
		int16_t *	x,
		int16_t *	y
	)

Convert the passed x, y local coordinates to global coordinates.

Parameters

x	– the window-local horizontal position to be converted to global.
y	– the window-local vertical position to be converted to global.
the_window	– reference to a valid Window object.

◆ Window_Maximize()

void Window_Maximize ( Window * the_window )

Set the window to full-screen size (maximize mode) Sets window's x, y, width, height parameters to match those of the screen.

Parameters

the_window – reference to a valid Window object.

◆ Window_MergeClipRects()

bool Window_MergeClipRects ( Window * the_window )

Merge and de-duplicate clip rects Consolidating the clip rects will happen reduce unnecessary reblitting.

Parameters

the_window – reference to a valid Window object.

◆ Window_Minimize()

void Window_Minimize ( Window * the_window )

Hides the window (minimize mode) Does not change the window's x, y, width, height parameters, it just makes it invisible.

Parameters

the_window – reference to a valid Window object.

◆ Window_New()

Window * Window_New	(	NewWinTemplate *	the_win_template,
		void()(EventRecord )	event_handler
	)

Allocate a Window object the_win_template->width_: cannot be smaller than WIN_DEFAULT_MIN_WIDTH, cannot be greater than WIN_DEFAULT_MAX_WIDTH the_win_template->height_: cannot be smaller than WIN_DEFAULT_MIN_HEIGHT, cannot be greater than WIN_DEFAULT_MAX_HEIGHT the_win_template->min_width_: cannot be smaller than WIN_DEFAULT_MIN_WIDTH the_win_template->min_height_: cannot be smaller than WIN_DEFAULT_MIN_HEIGHT the_win_template->max_width_: cannot be smaller than WIN_DEFAULT_MIN_WIDTH the_win_template->max_height_: cannot be smaller than WIN_DEFAULT_MIN_HEIGHT.

Parameters

the_win_template	– a populated new window template whose data will be used to create the new window object
event_handler	– pointer to the function that will handle all events for the window. This function will be called when the system detects an event associated with the window.

◆ Window_NormSize()

void Window_NormSize ( Window * the_window )

Set the window to normal size (window-size mode) Sets window's x, y, width, height parameters to those stored in norm_x, etc.

Parameters

the_window – reference to a valid Window object.

◆ Window_Print()

void Window_Print ( Window * the_window )

Parameters

the_window – reference to a valid Window object.

◆ Window_Render()

void Window_Render ( Window * the_window )

Draw/re-draw any necessary components, and blit the window (or parts of it, via cliprects) to the screen.

Parameters

the_window – reference to a valid Window object.

◆ Window_SetActive()

void Window_SetActive	(	Window *	the_window,
		bool	is_active
	)

Set the passed window's active flag.

NOTE: This does not immediately cause the window to render as active or inactive, but it does invalidate the title bar so that it re-renders in the next render pass.

Parameters

the_window	– reference to a valid Window object.
is_active	– set to true if window is now considered the active window, false if not

◆ Window_SetColor()

bool Window_SetColor	(	Window *	the_window,
		uint8_t	the_color
	)

Set the "pen" color This is the color that the next pen-based graphics function will use This also sets the pen color of the window's bitmap This only affects functions that use the pen: any graphics function that specifies a color will use that instead.

Parameters

the_window	– reference to a valid Window object.
the_color	– a 1-byte index to the current LUT

Returns: Returns false on any error condition

◆ Window_SetDisplayOrder()

void Window_SetDisplayOrder	(	Window *	the_window,
		int8_t	the_display_order
	)

Set the display order of the window NOTE: This does not immediately re-render or change the display order visibly.

WARNING: This function is designed to be called by the system only: do not use this

Parameters

the_window	– reference to a valid Window object
the_display_order	– the new display order value for the window

◆ Window_SetFont()

bool Window_SetFont	(	Window *	the_window,
		Font *	the_font
	)

Set the font This is the font that will be used for any subsequent font drawing in this Window This also sets the font of the window's bitmap This only affects programmer-controlled drawing actions; it will not change the title bar font, the icon font, etc.

Those are controlled by the theme.

Parameters

the_window	– reference to a valid Window object.
the_font	– reference to a complete, loaded Font object.

Returns: Returns false on any error condition

◆ Window_SetPenXY()

bool Window_SetPenXY	(	Window *	the_window,
		int16_t	x,
		int16_t	y
	)

Set the "pen" position within the content area This also sets the pen position of the window's bitmap This is the location that the next pen-based graphics function will use for a starting location.

Parameters

the_window	– reference to a valid Window object.
x	– the horizontal position within the content area of the window. Will be clipped to the edges.
y	– the vertical position within the content area of the window. Will be clipped to the edges.

Returns: Returns false on any error condition

◆ Window_SetPenXYFromGlobal()

bool Window_SetPenXYFromGlobal	(	Window *	the_window,
		int16_t	x,
		int16_t	y
	)

Set the local "pen" position within the window, based on global coordinates This also sets the pen position of the window's bitmap This is the location that the next pen-based graphics function will use for a starting location.

Parameters

the_window	– reference to a valid Window object.
x	– the global horizontal position to be converted to window-local. Will be clipped to the edges.
y	– the global vertical position to be converted to window-local. Will be clipped to the edges.

Returns: Returns false on any error condition

◆ Window_SetPixel()

bool Window_SetPixel	(	Window *	the_window,
		uint8_t	the_color
	)

Set the color of the pixel at the current pen location.

Parameters

the_window	– reference to a valid Window object.
the_color	– a 1-byte index to the current LUT

Returns: : returns false on any error/invalid input.

◆ Window_SetSelectedControl()

bool Window_SetSelectedControl	(	Window *	the_window,
		Control *	the_control
	)

Sets the passed control as the currently selected control and unselects any previously selected control.

Parameters

the_window	– reference to a valid Window object.
the_control	– reference to a valid Control object.

Returns: : Returns false on any error

◆ Window_SetState()

void Window_SetState	(	Window *	the_window,
		window_state	the_state
	)

Set the window's state (maximized, minimized, etc.) NOTE: This does not immediately cause the window to render in the passed state.

Parameters

the_window	– reference to a valid Window object.
the_state	– the new state

◆ Window_SetTitle()

void Window_SetTitle	(	Window *	the_window,
		char *	the_title
	)

Replace the current window title with the passed string Note: the passed string will be copied into storage by the window.

The passing function is free to dispose of the passed string after calling this function.

Parameters

the_window	– reference to a valid Window object.
the_title	– string containing the new title for the window.

◆ Window_SetVisible()

void Window_SetVisible	(	Window *	the_window,
		bool	is_visible
	)

Set the window's visibility flag.

NOTE: This does not immediately cause the window to render. The window will be rendered on the next system rendering pass.

Parameters

the_window	– reference to a valid Window object.
is_visible	– set to true if window should be rendered in the next pass, false if not

◆ Window_UpdateTheme()

void Window_UpdateTheme ( Window * the_window )

Updates the current window controls, etc., to match the current system theme.

Parameters

the_window – reference to a valid Window object.

Data Structures

Functions

Function Documentation

◆ Window_AcceptDamageRect()

◆ Window_AddClipRect()

◆ Window_AddControl()

◆ Window_AddNewControl()

◆ Window_AddNewControlFromTemplate()

◆ Window_Blit()

◆ Window_BlitClipRects()

◆ Window_ChangeWindow()

◆ Window_CheckForDragZone()

◆ Window_ClearContent()

◆ Window_Destroy()

◆ Window_DrawBox()

◆ Window_DrawBoxCoords()

◆ Window_DrawBoxRect()

◆ Window_DrawCircle()

◆ Window_DrawHLine()

◆ Window_DrawLine()

◆ Window_DrawRoundBox()

◆ Window_DrawStringInBox()

◆ Window_DrawVLine()

◆ Window_EvaluateWindowChange()

◆ Window_FillBox()

◆ Window_FillBoxRect()

◆ Window_GenerateDamageRects()

◆ Window_GetBitmap()

◆ Window_GetControl()

◆ Window_GetControlAtXY()

◆ Window_GetControlID()

◆ Window_GetHeight()

◆ Window_GetLastControl()

◆ Window_GetNewWinTemplate()

◆ Window_GetSelectedControl()

◆ Window_GetState()

◆ Window_GetTitle()

◆ Window_GetType()

◆ Window_GetUserData()

◆ Window_GetWidth()

◆ Window_GetX()

◆ Window_GetY()

◆ Window_GlobalToLocal()

◆ Window_Invalidate()

◆ Window_InvalidateControlByID()

◆ Window_InvalidateTitlebar()

◆ Window_IsActive()

◆ Window_IsBackdrop()

◆ Window_IsVisible()

◆ Window_LocalToGlobal()

◆ Window_Maximize()

◆ Window_MergeClipRects()

◆ Window_Minimize()

◆ Window_New()

◆ Window_NormSize()

◆ Window_Print()

◆ Window_Render()

◆ Window_SetActive()

◆ Window_SetColor()

◆ Window_SetDisplayOrder()

◆ Window_SetFont()

◆ Window_SetPenXY()

◆ Window_SetPenXYFromGlobal()

◆ Window_SetPixel()

◆ Window_SetSelectedControl()

◆ Window_SetState()

◆ Window_SetTitle()

◆ Window_SetVisible()

◆ Window_UpdateTheme()