Pen Object Library: 1.1 The Ink Object: Instance Data and Messages

When setting up an Ink object, probably the only pieces of instance data the application will be concerned with will be II_flags , II_dirtyOutput , and II_dirtyMsg .

Most of the flags are easy to understand, with the possible exceptions of the IF_HAS_TARGET and IF_DIRTY fields, which should not be set when creating the object in any case.

Code Display 21-1 InkClass Instance Data

/* 	II_flags:
 * 	  This field holds flags governing the object's behavior:
 *		IF_MOUSE_FLAGS, 	
 * 		IF_SELECTING, 		
 * 		IF_HAS_TARGET,
 *		IF_HAS_SYS_TARGET,
 *		IF_DIRTY,
 *		IF_ONLY_CHILD_OF_CONTENT, 
 *		IF_CONTROLLED, (Set if to be used with an InkControl)
 *		IF_INVALIDATE_ERASURES,
 * 		IF_HAS_UNDO */
@instance 	InkFlags 			II_flags = IF_HAS_UNDO;

/*   	II_tool:
 * 	This field keeps track of how the user is interacting with the Ink. There
 * 	are three possible tools: IT_PENCIL, IT_SELECTOR, and IT_ERASER. */
@instance 	InkTool 		II_tool;

 /* 	II_penColor:
 * 	The color to use when drawing ink. */
@instance 	Color 		II_penColor = C_BLACK;

/* 	II_segments:
 * 	Do not set this field explicitly. This field is a handle to the chunk array
 * 	containing the pen segments. The segments are stored as an array of Point
 * 	structures. The stored coordinates are all positive; any x coordinate with
 * 	its sign bit set belongs to the last point in a gesture. Thus, a small 
 * 	cross shape centered at (72, 72) might be stored:
 * 		(0x0048, 0x0046) 
 * 		(0x8048, 0x004A) [note sign bit set in x coordinate]
 * 		(0x0046, 0x0048)
 * 		(0x804A, 0x0048)		 [sign bit set in x coordinate]	*/
@instance 	ChunkHandle 		II_segments;

/* 	II_dirtyMsg, II_dirtyOutput:
 * 	Together, these fields form an Action Descriptor. When the Ink processes
 * 	a point of pen information, erases anything, or handles an undo event the
 * 	IF_DIRTY flag will be set. If the flag was not set already, then the Ink
 *	will send the AD's message to the AD's object. The handler for this message
 * 	should probably clear the IF_DIRTY bit. */
@instance optr			II_dirtyOutput;
@instance Message	 		II_dirtyMsg;

@instance Rectangle 			II_selectBounds;			/* Internal */
@instance GStateHandle			II_cachedGState;			/* Internal */
@instance TimerHandle 			II_antTimer;			/* Internal */
@instance word 			II_antTimerID;			/* Internal */
@instance byte			II_antMask;			/* Internal */

/*	ATTR_INK_STROKE_SIZE:
 * 	Size of line used to draw ink. */
@vardata    InkStrokeSize   ATTR_INK_STROKE_SIZE;

typedef struct {
	byte    ISS_width;
	byte    ISS_height;
} InkStrokeSize;

/* 	ATTR_INK_MAX_POINTS: 
 * 	Maximum number of points of ink data the object is prepared to store. */
@vardata    word ATTR_INK_MAX_POINTS;

Most of the Ink messages just change or retrieve the values of the instance fields. The exceptions are two messages which help those applications which need to save or transfer the Ink object's pen data. Use MSG_INK_SAVE_TO_DB_ITEM to save the pen data to an arbitrary DB item. If the application changes this information and wishes to pass it back to the ink object, use MSG_INK_LOAD_FROM_DB_ITEM .

MSG_INK_SET_TOOL

void 	MSG_INK_SET_TOOL(
        InkTool 	tool);

This message allows the Ink to switch between pencil and eraser tools, changing the II_tool field.

Source: Unrestricted.

Destination: Any Ink object.

Parameters: tool A tool, either IT_PENCIL or IT_ERASER.

Return: Nothing.

Interception: Unlikely.

MSG_INK_GET_TOOL

InkTool 	MSG_INK_GET_TOOL();

This message returns the Ink's present tool, as stored in II_tool .

Source: Unrestricted.

Destination: Any Ink object.

Parameters: None.

Return: The present tool, either IT_PENCIL or IT_ERASER.

Interception: Unlikely.

MSG_INK_SET_PEN_COLOR

void 	MSG_INK_SET_PEN_COLOR(
        Color 	clr);

This message changes the color used to draw the ink, changing the value in II_penColor .

Source: Unrestricted.

Destination: Any Ink object.

Parameters: clr Index to a palette (e.g. C_RED).

Return: Nothing.

Interception: Unlikely.

MSG_INK_SET_DIRTY_AD

void 	MSG_INK_SET_DIRTY_AD(
        word	 method,
        optr	 object);

This message sets the Action Descriptor to be activated when the user dirties the object, changing the values in II_dirtyMsg and II_dirtyOutput .

Source: Unrestricted.

Destination: Any Ink object.

Parameters: method The message to send when the object is dirty.

object: The object which should receive the above message.

Return: Nothing.

Interception: Unlikely.

MSG_INK_SET_MAX_POINTS

void MSG_INK_SET_MAX_POINTS(
        word 	maxPoints);

Set the maximum number of points of ink data the object is prepared to store.

Source: Unrestricted.

Destination: Any Ink object.

Parameters: maxPoints The message to send when the object is dirty.

Return: Nothing.

Interception: Unlikely.

MSG_INK_SET_FLAGS

void 	MSG_INK_SET_FLAGS(
        InkFlags 	setFlags,
        InkFlags 	clearFlags);

This message changes the value of the II_flags field. Note that something which sets the IF_DIRTY bit should probably also perform the action stored in the II_dirtyMsg and II_dirtyOutput fields.

Source: Unrestricted.

Destination: Any Ink object.

Parameters: setFlags The flags to turn on.

clearFlags: The flags to turn off.

Return: Nothing.

Interception: Unlikely.

MSG_INK_GET_FLAGS

InkFlags 	MSG_INK_GET_FLAGS();

This message gets the value of the II_flags field.

Source: Unrestricted.

Destination: Any Ink object.

Parameters: None.

Return: The present value of the II_flags field.

Interception: Unlikely.

MSG_INK_DELETE_LAST_GESTURE

int MSG_INK_DELETE_LAST_GESTURE();

This message removes the last gesture stored by the ink object; if the object had no ink stored, then nothing happens. The message returns zero if nothing was deleted.

Source: Unrestricted.

Destination: Any Ink object.

Parameters: None.

Return: Zero if nothing deleted.

Interception: Unlikely.

MSG_INK_SET_STROKE_SIZE

void MSG_INK_SET_STROKE_SIZE(
        byte 	width, 
        byte 	height);

Set the brush size to use when drawing ink.

Source: Unrestricted.

Destination: Any Ink object.

Parameters: width Brush width.

height: Brush height.

Return: Nothing.

Interception: Unlikely.

MSG_INK_SAVE_TO_DB_ITEM

void	MSG_INK_SAVE_TO_DB_ITEM(
        DBReturn		* RetValue,
        InkDBFrame		* ptr);

This message saves the Ink's pen data into the passed DB item. The pen data will be stored compressed. Calling this message sets the object not dirty.

Source: Unrestricted.

Destination: Any Ink object.

Parameters: ptr A pointer to an InkDBFrame structure, shown below.

RetValue: A pointer to an empty DBReturn structure, to be filled by the handler.

Return: The structure pointed to by RetValue will contain the returned information.

Structures: The InkDBFrame and DBReturn structures are defined below:

  typedef struct {
	Rectangle			IDBF_bounds;
		/* The bounds of the Ink data */
	VMFileHandle			IDBF_VMFile;
		/* VM file to write to*/

	DBGroupAndItem 			IDBF_DBGroupAndItem;
		/* DB Item to save to 
		 * (or NULL to create a new one) */

	word 			IDBF_DBExtra;
		/* Extra space to skip at start
		 * of block */
} InkDBFrame;

  typedef struct {
	word		DBR_group;
	word		DBR_item;
	word		DBR_unused1;
	word		DBR_unused2;
} DBReturn;

Interception: Unlikely.

MSG_INK_LOAD_FROM_DB_ITEM

void	MSG_INK_LOAD_FROM_DB_ITEM(
        InkDBFrame 	*ptr);

This message loads the compressed data into the Ink from the passed DB item. If a NULL handle is passed, then the Ink is cleared. This message marks the Ink as clean.

Source: Unrestricted.

Destination: Any Ink object.

Parameters: ptr A pointer to an InkDBFrame structure.

Return: Nothing.

Structures: For the InkDBFrame structure, see MSG_INK_SAVE_TO_DB_ITEM .

Interception: Unlikely.

GEOS SDK TechDocs |

1 The Ink Object | Next:

1.2 Storing Ink to DB Items