JGraphics
[User Interface]

JGraphics is the API for creating user interface objects introduced with Max 5. More...

Collaboration diagram for JGraphics:

Data Structures
struct	t_jgraphics_font_extents
	A structure for holding information related to how much space the rendering of a given font will use. More...
Modules
	JSurface
	A surface is an abstract base class for something you render to.
	Scalable Vector Graphics
	JFont
	JGraphics Matrix Transformations
	The t_jmatrix is one way to represent a transformation.
	JPattern
	A pattern is like a brush that is used to fill a path with.
	Colors
	TextField
	The textfield is a high-level text display object that may be used by a UI object to represent text in a patcher.
	TextLayout
	A textlayout is lower-level text rendering object used by higher-level entities such as TextField.
	Popup Menus
	Popup menu API so externals can create popup menus that can also be drawn into.
	Box Layer
	The boxlayer functions provide way to make it easier to use cached offscreen images (layers) in your drawing.
Defines
#define	JGRAPHICS_RECT_BOTTOM(rect) (((rect)->y)+((rect)->height))
	Determine the coordinate of the bottom of a rect.
#define	JGRAPHICS_RECT_RIGHT(rect) (((rect)->x)+((rect)->width))
	Determine the coordinate of the right side of a rect.
#define	JGRAPHICS_PI (3.1415926535897932384626433832795028842)
	Utility macro to return the value of Pi.
#define	JGRAPHICS_2PI (2. * 3.1415926535897932384626433832795028842)
	Utility macro to return the value of twice Pi.
#define	JGRAPHICS_PIOVER2 (0.5 * 3.1415926535897932384626433832795028842)
	Utility macro to return the value of half of Pi.
#define	JGRAPHICS_3PIOVER2 ((3.0 * JGRAPHICS_PI) / 2.0)
	Utility macro to return the 270º Case.
Typedefs
typedef typedefBEGIN_USING_C_LINKAGE struct _jgraphics	t_jgraphics
	An instance of a jgraphics drawing context.
typedef struct _jpath	t_jpath
	An instance of a jgraphics path.
typedef struct _jtextlayout	t_jtextlayout
	An instance of a jgraphics text layout object.
typedef struct _jtransform	t_jtransform
	An instance of a jgraphics transform.
typedef struct _jsvg	t_jsvg
	An instance of an SVG object.
typedef struct _jpopupmenu	t_jpopupmenu
	An instance of a pop-up menu.
Enumerations
enum	t_jgraphics_format { JGRAPHICS_FORMAT_ARGB32, JGRAPHICS_FORMAT_RGB24, JGRAPHICS_FORMAT_A8 }
	Enumeration of color formats used by jgraphics surfaces. More...
enum	t_jgraphics_fileformat { JGRAPHICS_FILEFORMAT_PNG, JGRAPHICS_FILEFORMAT_JPEG }
	Enumeration of file formats usable for jgraphics surfaces. More...
enum	t_jgraphics_text_justification { JGRAPHICS_TEXT_JUSTIFICATION_LEFT = 1, JGRAPHICS_TEXT_JUSTIFICATION_RIGHT = 2, JGRAPHICS_TEXT_JUSTIFICATION_HCENTERED = 4, JGRAPHICS_TEXT_JUSTIFICATION_TOP = 8, JGRAPHICS_TEXT_JUSTIFICATION_BOTTOM = 16, JGRAPHICS_TEXT_JUSTIFICATION_VCENTERED = 32, JGRAPHICS_TEXT_JUSTIFICATION_HJUSTIFIED = 64, JGRAPHICS_TEXT_JUSTIFICATION_CENTERED = JGRAPHICS_TEXT_JUSTIFICATION_HCENTERED + JGRAPHICS_TEXT_JUSTIFICATION_VCENTERED }
	Enumeration of text justification options, which are specified as a bitmask. More...
Functions
int	jgraphics_round (double d)
	Utility for rounding a double to an int.
t_jgraphics *	jgraphics_reference (t_jgraphics *g)
	Get a reference to a graphics context.
void	jgraphics_destroy (t_jgraphics *g)
	Release or free a graphics context.
void	jgraphics_new_path (t_jgraphics *g)
	Begin a new path.
t_jpath *	jgraphics_copy_path (t_jgraphics *g)
	Get a copy of the current path from a context.
void	jgraphics_path_destroy (t_jpath *path)
	Release/free a path.
void	jgraphics_append_path (t_jgraphics g, t_jpath path)
	Add a path to a graphics context.
void	jgraphics_close_path (t_jgraphics *g)
	Close the current path in a context.
void	jgraphics_path_roundcorners (t_jgraphics *g, double cornerRadius)
	Round out any corners in a path.
void	jgraphics_get_current_point (t_jgraphics g, double x, double *y)
	Get the current location of the cursor in a graphics context.
void	jgraphics_arc (t_jgraphics *g, double xc, double yc, double radius, double angle1, double angle2)
	Add a circular, clockwise, arc to the current path.
void	jgraphics_ovalarc (t_jgraphics *g, double xc, double yc, double radiusx, double radiusy, double angle1, double angle2)
	Add a non-circular arc to the current path.
void	jgraphics_arc_negative (t_jgraphics *g, double xc, double yc, double radius, double angle1, double angle2)
	Add a circular, counter-clockwise, arc to the current path.
void	jgraphics_curve_to (t_jgraphics *g, double x1, double y1, double x2, double y2, double x3, double y3)
	Add a cubic Bezier spline to the current path.
void	jgraphics_rel_curve_to (t_jgraphics *g, double x1, double y1, double x2, double y2, double x3, double y3)
	Add a cubic Bezier spline to the current path, using coordinates relative to the current point.
void	jgraphics_line_to (t_jgraphics *g, double x, double y)
	Add a line segment to the current path.
void	jgraphics_rel_line_to (t_jgraphics *g, double x, double y)
	Add a line segment to the current path, using coordinates relative to the current point.
void	jgraphics_move_to (t_jgraphics *g, double x, double y)
	Move the cursor to a new point and begin a new subpath.
void	jgraphics_rel_move_to (t_jgraphics *g, double x, double y)
	Move the cursor to a new point and begin a new subpath, using coordinates relative to the current point.
void	jgraphics_rectangle (t_jgraphics *g, double x, double y, double width, double height)
	Add a closed rectangle path in the context.
void	jgraphics_oval (t_jgraphics *g, double x, double y, double width, double height)
	Deprecated -- do not use.
void	jgraphics_rectangle_rounded (t_jgraphics *g, double x, double y, double width, double height, double ovalwidth, double ovalheight)
	Add a closed rounded-rectangle path in the context.
void	jgraphics_ellipse (t_jgraphics *g, double x, double y, double width, double height)
	Add a closed elliptical path in the context.
void	jgraphics_select_font_face (t_jgraphics g, const char family, t_jgraphics_font_slant slant, t_jgraphics_font_weight weight)
	Specify a font for a graphics context.
void	jgraphics_select_jfont (t_jgraphics g, t_jfont jfont)
	Specify a font for a graphics context by passing a t_jfont object.
void	jgraphics_set_font_size (t_jgraphics *g, double size)
	Specify the font size for a context.
void	jgraphics_set_underline (t_jgraphics *g, char underline)
	Turn underlining on/off for text in a context.
void	jgraphics_show_text (t_jgraphics g, const char utf8)
	Display text at the current position in a context.
void	jgraphics_font_extents (t_jgraphics g, t_jgraphics_font_extents extents)
	Return the extents of the currently selected font for a given graphics context.
void	jgraphics_text_measure (t_jgraphics g, const char utf8, double width, double height)
	Return the height and width of a string given current graphics settings in a context.
void	jgraphics_text_measure_wrapped (t_jgraphics g, const char utf8, double wrapwidth, long includewhitespace, double width, double height, long *numlines)
	Return the height, width, and number of lines that will be used to render a given string.
long	jgraphics_system_canantialiastexttotransparentbg ()
	Determine if you can anti-alias text to a transparent background.
void	jgraphics_user_to_device (t_jgraphics g, double x, double *y)
	User coordinates are those passed to drawing functions in a given t_jgraphics context.
void	jgraphics_device_to_user (t_jgraphics g, double x, double *y)
	User coordinates are those passed to drawing functions in a given t_jgraphics context.
void	jgraphics_getfiletypes (void dummy, long count, long *filetypes, char alloc)
	Get a list of of filetypes appropriate for use with jgraphics surfaces.
long	jgraphics_rectintersectsrect (t_rect r1, t_rect r2)
	Simple utility to test for rectangle intersection.
long	jgraphics_rectcontainsrect (t_rect outer, t_rect inner)
	Simple utility to test for rectangle containment.
void	jgraphics_position_one_rect_near_another_rect_but_keep_inside_a_third_rect (t_rect positioned_rect, const t_rect positioned_near_this_rect, const t_rect *keep_inside_this_rect)
	Generate a t_rect according to positioning rules.

Detailed Description

JGraphics is the API for creating user interface objects introduced with Max 5.

It includes functions for drawing vector-based shapes, managing pop-up menus, rendering text, and importing graphics resources. The API design is inspired by and analogous to the Cairo API, though the underlying implementation is actually drawn using JUCE (JUCE functions, however, cannot be called directly).

Define Documentation

#define JGRAPHICS_2PI (2. * 3.1415926535897932384626433832795028842)

Utility macro to return the value of twice Pi.

#define JGRAPHICS_3PIOVER2 ((3.0 * JGRAPHICS_PI) / 2.0)

Utility macro to return the 270º Case.

#define JGRAPHICS_PI (3.1415926535897932384626433832795028842)

Utility macro to return the value of Pi.

#define JGRAPHICS_PIOVER2 (0.5 * 3.1415926535897932384626433832795028842)

Utility macro to return the value of half of Pi.

Enumeration Type Documentation

enum t_jgraphics_fileformat

Enumeration of file formats usable for jgraphics surfaces.

Enumerator:

JGRAPHICS_FILEFORMAT_PNG	Portable Network Graphics (PNG) format.
JGRAPHICS_FILEFORMAT_JPEG	JPEG format.

enum t_jgraphics_format

Enumeration of color formats used by jgraphics surfaces.

Enumerator:

JGRAPHICS_FORMAT_ARGB32	Color is represented using 32 bits, 8 bits each for the components, and including an alpha component.
JGRAPHICS_FORMAT_RGB24	Color is represented using 32 bits, 8 bits each for the components. There is no alpha component.
JGRAPHICS_FORMAT_A8	The color is represented only as an 8-bit alpha mask.

enum t_jgraphics_text_justification

Enumeration of text justification options, which are specified as a bitmask.

Enumerator:

JGRAPHICS_TEXT_JUSTIFICATION_LEFT	Justify left.
JGRAPHICS_TEXT_JUSTIFICATION_RIGHT	Justify right.
JGRAPHICS_TEXT_JUSTIFICATION_HCENTERED	Centered horizontally.
JGRAPHICS_TEXT_JUSTIFICATION_TOP	Justified to the top.
JGRAPHICS_TEXT_JUSTIFICATION_BOTTOM	Justified to the bottom.
JGRAPHICS_TEXT_JUSTIFICATION_VCENTERED	Centered vertically.
JGRAPHICS_TEXT_JUSTIFICATION_HJUSTIFIED	Horizontally justified.
JGRAPHICS_TEXT_JUSTIFICATION_CENTERED	Shortcut for Centering both vertically and horizontally.

Function Documentation

void jgraphics_append_path	(	t_jgraphics *	g,
		t_jpath *	path
	)

Add a path to a graphics context.

Parameters:

	g	The graphics context.
	path	The path to add.

void jgraphics_arc	(	t_jgraphics *	g,
		double	xc,
		double	yc,
		double	radius,
		double	angle1,
		double	angle2
	)

Add a circular, clockwise, arc to the current path.

Parameters:

	g	The graphics context.
	xc	The horizontal coordinate of the arc's center.
	yc	The vertical coordinate of the arc's center.
	radius	The radius of the arc.
	angle1	The starting angle of the arc in radians. Zero radians is center right (positive x axis).
	angle2	The terminal angle of the arc in radians. Zero radians is center right (positive x axis).

void jgraphics_arc_negative	(	t_jgraphics *	g,
		double	xc,
		double	yc,
		double	radius,
		double	angle1,
		double	angle2
	)

Add a circular, counter-clockwise, arc to the current path.

Parameters:

	g	The graphics context.
	xc	The horizontal coordinate of the arc's center.
	yc	The vertical coordinate of the arc's center.
	radius	The radius of the arc.
	angle1	The starting angle of the arc in radians. Zero radians is center right (positive x axis).
	angle2	The terminal angle of the arc in radians. Zero radians is center right (positive x axis).

void jgraphics_close_path ( t_jgraphics * g )

Close the current path in a context.

This will add a line segment to close current subpath.

Parameters:

g

The graphics context.

t_jpath* jgraphics_copy_path ( t_jgraphics * g )

Get a copy of the current path from a context.

Parameters:

g

A copy of the current path.

void jgraphics_curve_to	(	t_jgraphics *	g,
		double	x1,
		double	y1,
		double	x2,
		double	y2,
		double	x3,
		double	y3
	)

Add a cubic Bezier spline to the current path.

Parameters:

	g	The graphics context.
	x1	The first control point.
	y1	The first control point.
	x2	The second control point.
	y2	The second control point.
	x3	The destination point.
	y3	The destination point.

void jgraphics_destroy ( t_jgraphics * g )

Release or free a graphics context.

Parameters:

g

The context to release.

void jgraphics_device_to_user	(	t_jgraphics *	g,
		double *	x,
		double *	y
	)

User coordinates are those passed to drawing functions in a given t_jgraphics context.

Device coordinates refer to patcher canvas coordinates, before any zooming.

void jgraphics_ellipse	(	t_jgraphics *	g,
		double	x,
		double	y,
		double	width,
		double	height
	)

Add a closed elliptical path in the context.

Parameters:

	g	The graphics context.
	x	The horizontal origin.
	y	The vertical origin.
	width	The width of the rect.
	height	The height of the rect.

void jgraphics_font_extents	(	t_jgraphics *	g,
		t_jgraphics_font_extents *	extents
	)

Return the extents of the currently selected font for a given graphics context.

Parameters:

	g	Pointer to a jgraphics context.
	extents	The address of a t_jgraphics_font_extents structure to be filled with the results.

void jgraphics_get_current_point	(	t_jgraphics *	g,
		double *	x,
		double *	y
	)

Get the current location of the cursor in a graphics context.

Parameters:

	g	The graphics context.
	x	The address of a variable that will be set to the horizontal cursor location upon return.
	y	The address of a variable that will be set to the vertical cursor location upon return.

void jgraphics_getfiletypes	(	void *	dummy,
		long *	count,
		long **	filetypes,
		char *	alloc
	)

Get a list of of filetypes appropriate for use with jgraphics surfaces.

Parameters:

	dummy	Unused.
	count	The address of a variable to be set with the number of types in filetypes upon return.
	filetypes	The address of a variable that will represent the array of file types upon return.
	alloc	The address of a char that will be flagged with a 1 or a 0 depending on whether or not memory was allocated for the filetypes member.

Remarks:

This example shows a common usage of jgraphics_getfiletypes().

   char       filename[MAX_PATH_CHARS];
   long       *type = NULL;
   long       ntype;
   long       outtype;
   t_max_err  err;
   char       alloc;
   short      path;
   t_jsurface *surface;
   
   if (want_to_show_dialog) {
      jgraphics_getfiletypes(x, &ntype, &type, &alloc);
      err = open_dialog(filename, &path,(void *)&outtype, (void *)type, ntype);
      if (err)
         goto out;
   } 
   else {      
      strncpy_zero(filename, s->s_name, MAX_PATH_CHARS);
      err = locatefile_extended(filename, &path, &outtype, type, ntype);
      if (err)
         goto out;
   }
   surface = jgraphics_image_surface_create_referenced(filename, path); 
out:
   if (alloc)
      sysmem_freeptr((char *)type);

void jgraphics_line_to	(	t_jgraphics *	g,
		double	x,
		double	y
	)

Add a line segment to the current path.

Parameters:

	g	The graphics context.
	x	The destination point.
	y	The destination point.

void jgraphics_move_to	(	t_jgraphics *	g,
		double	x,
		double	y
	)

Move the cursor to a new point and begin a new subpath.

Parameters:

	g	The graphics context.
	x	The new location.
	y	The new location.

void jgraphics_new_path ( t_jgraphics * g )

Begin a new path.

This action clears any current path in the context.

Parameters:

g

The graphics context.

void jgraphics_oval	(	t_jgraphics *	g,
		double	x,
		double	y,
		double	width,
		double	height
	)

Deprecated -- do not use.

Adds a closed oval path in the context, however, it does not scale appropriately.

Parameters:

	g	The graphics context.
	x	The horizontal origin.
	y	The vertical origin.
	width	The width of the oval.
	height	The height of the oval.

void jgraphics_ovalarc	(	t_jgraphics *	g,
		double	xc,
		double	yc,
		double	radiusx,
		double	radiusy,
		double	angle1,
		double	angle2
	)

Add a non-circular arc to the current path.

Parameters:

	g	The graphics context.
	xc	The horizontal coordinate of the arc's center.
	yc	The vertical coordinate of the arc's center.
	radiusx	The horizontal radius of the arc.
	radiusy	The vertical radius of the arc.
	angle1	The starting angle of the arc in radians. Zero radians is center right (positive x axis).
	angle2	The terminal angle of the arc in radians. Zero radians is center right (positive x axis).

void jgraphics_path_destroy ( t_jpath * path )

Release/free a path.

Parameters:

path

The path to release.

void jgraphics_path_roundcorners	(	t_jgraphics *	g,
		double	cornerRadius
	)

Round out any corners in a path.

This action clears any current path in the context.

Parameters:

	g	The graphics context.
	cornerRadius	The amount by which to round corners.

void jgraphics_position_one_rect_near_another_rect_but_keep_inside_a_third_rect	(	t_rect *	positioned_rect,
		const t_rect *	positioned_near_this_rect,
		const t_rect *	keep_inside_this_rect
	)

Generate a t_rect according to positioning rules.

Parameters:

	positioned_rect	The address of a valid t_rect whose members will be filled in upon return.
	positioned_near_this_rect	A pointer to a rect near which this rect should be positioned.
	keep_inside_this_rect	A pointer to a rect defining the limits within which the new rect must reside.

void jgraphics_rectangle	(	t_jgraphics *	g,
		double	x,
		double	y,
		double	width,
		double	height
	)

Add a closed rectangle path in the context.

Parameters:

	g	The graphics context.
	x	The horizontal origin.
	y	The vertical origin.
	width	The width of the rect.
	height	The height of the rect.

void jgraphics_rectangle_rounded	(	t_jgraphics *	g,
		double	x,
		double	y,
		double	width,
		double	height,
		double	ovalwidth,
		double	ovalheight
	)

Add a closed rounded-rectangle path in the context.

Parameters:

	g	The graphics context.
	x	The horizontal origin.
	y	The vertical origin.
	width	The width of the rect.
	height	The height of the rect.
	ovalwidth	The width of the oval used for the round corners.
	ovalheight	The height of the oval used for the round corners.

long jgraphics_rectcontainsrect	(	t_rect *	outer,
		t_rect *	inner
	)

Simple utility to test for rectangle containment.

Parameters:

	outer	The address of the first rect for the test.
	inner	The address of the second rect for the test.

Returns:: Returns true if the inner rect is completely inside the outer rect, otherwise false.

long jgraphics_rectintersectsrect	(	t_rect *	r1,
		t_rect *	r2
	)

Simple utility to test for rectangle intersection.

Parameters:

	r1	The address of the first rect for the test.
	r2	The address of the second rect for the test.

Returns:: Returns true if the rects intersect, otherwise false.

t_jgraphics* jgraphics_reference ( t_jgraphics * g )

Get a reference to a graphics context.

When you are done you should release your reference with jgraphics_destroy().

Parameters:

g

The context you wish to reference.

Returns:: A new reference to the context.

void jgraphics_rel_curve_to	(	t_jgraphics *	g,
		double	x1,
		double	y1,
		double	x2,
		double	y2,
		double	x3,
		double	y3
	)

Add a cubic Bezier spline to the current path, using coordinates relative to the current point.

Parameters:

	g	The graphics context.
	x1	The first control point.
	y1	The first control point.
	x2	The second control point.
	y2	The second control point.
	x3	The destination point.
	y3	The destination point.

void jgraphics_rel_line_to	(	t_jgraphics *	g,
		double	x,
		double	y
	)

Add a line segment to the current path, using coordinates relative to the current point.

Parameters:

	g	The graphics context.
	x	The destination point.
	y	The destination point.

void jgraphics_rel_move_to	(	t_jgraphics *	g,
		double	x,
		double	y
	)

Move the cursor to a new point and begin a new subpath, using coordinates relative to the current point.

Parameters:

	g	The graphics context.
	x	The new location.
	y	The new location.

int jgraphics_round ( double d )

Utility for rounding a double to an int.

Parameters:

d

floating-point input.

Returns:: rounded int output.

void jgraphics_select_font_face	(	t_jgraphics *	g,
		const char *	family,
		t_jgraphics_font_slant	slant,
		t_jgraphics_font_weight	weight
	)

Specify a font for a graphics context.

Parameters:

	g	The graphics context.
	family	The name of the font family (e.g. "Arial").
	slant	Define the slant to use for the font.
	weight	Define the weight to use for the font.

void jgraphics_select_jfont	(	t_jgraphics *	g,
		t_jfont *	jfont
	)

Specify a font for a graphics context by passing a t_jfont object.

Parameters:

	g	The graphics context.
	jfont	A jfont object whose attributes will be copied to the context.

void jgraphics_set_font_size	(	t_jgraphics *	g,
		double	size
	)

Specify the font size for a context.

Parameters:

	g	The graphics context.
	size	The font size.

void jgraphics_set_underline	(	t_jgraphics *	g,
		char	underline
	)

Turn underlining on/off for text in a context.

Parameters:

	g	The graphics context.
	underline	Pass true or false to set the appropriate behavior.

void jgraphics_show_text	(	t_jgraphics *	g,
		const char *	utf8
	)

Display text at the current position in a context.

Parameters:

	g	The graphics context.
	utf8	The text to display.

long jgraphics_system_canantialiastexttotransparentbg ( )

Determine if you can anti-alias text to a transparent background.

You might want to call this and then disable "useimagebuffer" if false *and* you are rendering text on a transparent background.

Returns:: Non-zero if you can anti-alias text to a transparent background.

void jgraphics_text_measure	(	t_jgraphics *	g,
		const char *	utf8,
		double *	width,
		double *	height
	)

Return the height and width of a string given current graphics settings in a context.

Parameters:

	g	Pointer to a jgraphics context.
	utf8	A string containing the text whose dimensions we wish to find.
	width	The address of a variable to be filled with the width of the rendered text.
	height	The address of a variable to be filled with the height of the rendered text.

void jgraphics_text_measure_wrapped	(	t_jgraphics *	g,
		const char *	utf8,
		double	wrapwidth,
		long	includewhitespace,
		double *	width,
		double *	height,
		long *	numlines
	)

Return the height, width, and number of lines that will be used to render a given string.

Parameters:

	g	Pointer to a jgraphics context.
	utf8	A string containing the text whose dimensions we wish to find.
	wrapwidth	The number of pixels in width at which the text should be wrapped if it is too long.
	includewhitespace	Set zero to not include white space in the calculation, otherwise set this parameter to 1.
	width	The address of a variable to be filled with the width of the rendered text.
	height	The address of a variable to be filled with the height of the rendered text.
	numlines	The address of a variable to be filled with the number of lines required to render the text.

void jgraphics_user_to_device	(	t_jgraphics *	g,
		double *	x,
		double *	y
	)

User coordinates are those passed to drawing functions in a given t_jgraphics context.

Device coordinates refer to patcher canvas coordinates, before any zooming.

JGraphics [User Interface]

Data Structures

Modules

Defines

Typedefs

Enumerations

Functions

Detailed Description

Define Documentation

Enumeration Type Documentation

Function Documentation

JGraphics
[User Interface]