Figure 10-0

Display 10-0

SwatDisplay 10-0

Table 10-0
3Chapter Title

n	UserAddAutoExec()

void	UserAddAutoExec(

	const char *		appName);

This routine adds an application to the list of those, like Welcome, that are 
automatically started by the UI when it loads. It is passed one argument:

appName	This is a pointer to a null-terminated string containing the 
name of the application. The application must be in 
SP_APPLICATION or SP_SYS_APPLICATION.

Include:	ui.goh

n	UserCreateDialog()

optr	UserCreateDialog(

	optr	dialogBox);

This routine duplicates a template dialog box, attaches the dialog box to an 
application object, and sets it fully GS_USABLE so that it may be called with 
UserDoDialog(). Dialog boxes created in such a manner should be removed 
and destroyed with UserDestroyDialog() when no longer needed.

dialogBox	Optr to template dialog box (within a template object block). 
The block must be sharable, read-only and the top 
GenInteraction called with this routine must not be linked into 
any generic tree. The optr returned is a created, fully-usable 
dialog box.

See Also:	UserDestroyDialog()

n	UserCreateInkDestinationInfo()

MemHandle 	UserCreateInkDestinationInfo(

	optr 		dest,

	GStateHandle 		gs,

	word		brushSize,

	GestureCallback		*callback);

This routine creates an InkDestinationInfo structure to be returned with 
MSG_META_QUERY_IF_PRESS_IS_INK. The callback routine must be 
declared _pascal.

Include:	ui.goh

Structures:	

	typedef Boolean _pascal GestureCallback (

		Point *arrayOfInkPoints, 

		word numPoints, 

		word numStrokes);

n	UserDestroyDialog()

void	UserDestroyDialog(

	optr	dialogBox);

This routine destroys the passed dialog box, usually created with 
UserCreateDialog(). This routine may only be used to destroy dialog boxes 
occupying a single block; the block must also hold nothing other than the 
dialog box to be destroyed. It is for this reason that it is wise to only use this 
routine to destroy dialogs created with UserCreateDialog().

See Also:	UserCreateDialog()

n	UserDoDialog()

InteractionCommand UserDoDialog(

	optr	dialogBox);

UserDoDialog() brings a pre-instantiated dialog box on-screen, blocking 
the calling thread until the user responds to the dialog. You must pass the 
optr of a GIV_DIALOG Interaction that is set both 
GIA_INITIATED_VIA_USER_DO_DIALOG and GIA_MODAL. 

This routine returns the InteractionCommand of the particular response 
trigger selected by the user. This InteractionCommand may be either a 
predefined type (such as IC_YES) or a custom one defined using 
IC_CUSTOM_START.

The pre-defined InteractionCommands are:

IC_NULL
IC_DISMISS
IC_APPLY
IC_RESET
IC_OK
IC_YES
IC_NO
IC_STOP
IC_EXIT
IC_HELP
IC_INTERACTION_COMPLETE

This routine may return IC_NULL for those cases in which a system 
shutdown causes the dialog to be dismissed before the user has entered a 
response. 

Warnings:	This routine blocks the calling thread until the dialog box receives a 
MSG_GEN_GUP_INTERACTION_COMMAND. Since the application thread is 
blocked, it cannot be responsible for sending this message or for handling 
messages from the response triggers. 

See Also:	UserStandardDialog(), UserStandardDialogOptr()

n	UserGetInterfaceLevel()

UIInterfaceLevel UserGetInterfaceLevel(void)

This routine returns the current UIInterfaceLevel. This is a word-sized 
enumerated type. It has the following values:

UIIL_NOVICE
UIIL_BEGINNING_INTERMEDIATE
UIIL_ADVANCED_INTERMEDIATE
UIIL_ADVANCED
UIIL_GURU

Include:	ui.goh

n	UserLoadApplication



extern GeodeHandle UserLoadApplication(

	AppLaunchFlags 		alf,

	Message 		attachMethod,

	MemHandle 		appLaunchBlock,

	char 		*filename,

	StandardPath 		sPath,

	GeodeLoadError 		*err);

Loads an application.  Changes to standard application directory before 
attempting GeodeLoad on filename passed. Stores the filename being 
launched into the AppLaunchBlock, so that information needed to restore 
this application instance will be around later if needed.

n	UserRemoveAutoExec()

void	UserRemoveAutoExec(

	const char *		appName);

This routine removes an application from the list of those to be launched on 
start-up. It is passed one argument:

appName	This is a pointer to a null-terminated string containing the 
name of the application.

Include:	ui.goh

n	UserStandardDialog()

word	UserStandardDialog(

	char *		helpContext,

	char *		customTriggers,

	char *		arg2,

	char *		arg1,

	char *		string,

	CustomDialogBoxFlags		dialogFlags);

UserStandardDialog() creates and displays either a custom dialog box or 
one of several pre-defined standard dialog boxes. 

Most often, you will use this routine to create a custom dialog box that 
conforms to a standardized dialog. In this case, pass the 
CustomDialogType of SDBT_CUSTOM as the routine's first argument. You 
must then supply other parameters to create the custom dialog box.

If instead you wish to use one of the pre-defined CustomDialogType types, 
you should pass that type as the first argument to this routine. Some of these 
standard types require you to pass string parameters. Other arguments 
should be passed as null.

For custom dialog boxes you must pass a CustomDialogType 
(CDT_WARNING, CDT_NOTIFICATION, CDT_QUESTION, or CDT_ERROR). 
This chooses the proper icon glyph to display within the dialog box. (For 
example, a CDT_WARNING dialog might contain a large exclamation-point 
glyph.) Make sure that you use CDBF_DIALOG_TYPE_OFFSET to pass this 
value.

You should also pass a valid GenInteractionType. In most cases, this will 
be either GIT_NOTIFICATION, GIT_AFFIRMATION, or 
GIT_MULTIPLE_RESPONSE. Make sure that you use 
CDBF_INTERACTION_TYPE_OFFSET to pass this value.

Also pass the routine a string to display to the user. This string may be either 
text or graphics based.

If the CustomDialogType is GIT_MULTIPLE_RESPONSE, you must also set 
up a Response Trigger Table with several trigger parameters.

n	UserStandardDialogOptr()

word	UserStandardDialogOptr(

	char		*helpContext,

	optr		customTriggers,

	optr		arg2,

	optr		arg1,

	optr		string

	CustomDialogBoxFlags		dialogFlags);

UserStandardDialogOptr() performs the same functionality as 
UserStandardDialog() except that optrs to strings and string parameters 
are passed instead of fptrs. This is useful for localized strings in resource 
blocks.

See Also:	UserStandardDialog(), UserDoDialog() 

n	UserStandardSound()



void	UserStandardSound(

	StandardSoundType		type,

	...);

This routine plays a simple sequence of notes. It can be used to play a 
standard system sound, a single custom tone, or a sequence of tones.

The routine takes a variable number of arguments. The first argument is a 
member of the StandardSoundType enumerated type. This argument 
specifies what kind of tone or tones will be played. Depending on the 
StandardSoundType passed, zero, one, or two additional arguments may 
be needed. StandardSoundType contains the following members:

SST_ERROR	This is the sound played when an "Error" dialog comes up. No 
further arguments are needed.

SST_WARNING
This is a general warning sound. No further arguments are 
needed.

SST_NOTIFY	This is a general notification sound. No further arguments are 
needed.

SST_NO_INPUT
This is the sound played when a user's input is not going 
anywhere (e.g. when he clicks the mouse outside a modal dialog 
box).

SST_KEY_CLICK
This is the sound produced when the keyboard is pressed, or 
when the user clicks on a floating keyboard. No further 
arguments are required.

SST_CUSTOM_SOUND
Play a custom sampled sound. This requires one more 
argument, the memory handle of the sound to be played.

SST_CUSTOM_BUFFER
Play a custom buffer of instrumental sound. This requires one 
further argument, a pointer to the memory block containing 
the sound buffer. Note that the "tempo" value used to play this 
buffer will be one tick per thirty-second note, probably much 
faster than you would otherwise expect.

SST_CUSTOM_NOTE
By passing this argument, you can have a single custom note 
played. You must provide one further argument, the handle of 
the note (such as returned by SoundAllocNote()).

n	UtilAsciiToHex32()

Boolean	UtilAsciiToHex32(

	const char *		string,

	dword *		value);

This routine converts a null-terminated ASCII string into a 32-bit integer. 
The string may begin with a hyphen, indicating a negative number. Aside 
from that, the string may contain nothing but numerals until the null 
termination. It may not contain whitespace.

If the routine is successful, it will return false and write an equivalent signed 
long integer to *value. If it fails, it will return true and write a member of the 
UtilAsciiToHexError enumerated type to *value. This type contains the 
following members:

UATH_NON_NUMERIC_DIGIT_IN_STRING
This string contained a non-numeric character before the 
trailing null (other than the allowed leading hyphen).

UATH_CONVERT_OVERFLOW
The string specified a number to large to be expressed as a 
signed 32-bit integer.

Include:	system.h

n	UtilHex32ToAscii()



word	UtilHex32ToAscii(

	char *		buffer,

	sdword		value, 

	UtilHexToAsciiFlags 		flags);

This routine converts a 32-bit unsigned integer to its ASCII representation 
and writes it to the specified buffer. It returns the length of the string (not 
counting the nulll termination, if any). The routine is passed the following 
arguments:

buffer	This is a pointer to a character buffer. The buffer must be long 
enough to accommodate the largest string; that is, there must 
be ten bytes for the characters, plus one for the trailing null (if 
necessary).

value	This is the value to convert to ASCII.

flags	This is a record of UtilHexToAscii flags. The following flags 
are available:

UHTAF_INCLUDE_LEADING_ZEROS
Pad the string with leading zeros to a length of ten total 
characters.

UHTAF_NULL_TERMINATE
Add a null to the end of the string. If this flag is set, the buffer 
must be at least 11 bytes long. If it is clear, the buffer may be 
ten bytes long.

Include:	system.h

n	VarDataFlagsPtr()

VarDataFlags 	VarDataFlagsPtr(

	void *	ptr);

This macro fetches the flags of a variable data type when given a pointer to 
the extra data for the type. The flags are stored in a VarDataFlags record. 
Only the flags VDF_EXTRA_DATA and/or VDF_SAVE_TO_STATE will be 
returned.

Include:	object.h

Warnings:	You must pass a pointer to the beginning of the vardata entry's extra data 
space.

n	VarDataSizePtr()

word	VarDataSizePtr(

	void *	ptr);

This macro fetches the size of a variable data entry when given a pointer to 
the extra data for the type.

Include:	object.h

Warnings:	You must pass a pointer to the beginning of the vardata entry's extra data 
space.

n	VarDataTypePtr()

word	VarDataTypePtr(

	void *	ptr);

This macro fetches the type of a variable data entry when given a pointer to 
the extra data of the entry. The type is stored in a VarDataFlags record. All 
flags outside the VDF_TYPE section will be cleared.

Include:	object.h

Warnings:	You must pass a pointer to the beginning of the vardata entry's extra data 
space.

n	VisObjectHandlesInkReply()



void	VisObjectHandlesInkReply(void);

n	VisTextGraphicCompressGraphic()



extern VMChain VisTextGraphicCompressGraphic(

	VisTextGraphic 		*graphic,

	FileHandle 		sourceFile,

	FileHandle 		destFile,

	BMFormat format,

	word xRes, 

	word yRes);

This routine compresses the bitmaps in a VisTextGraphic.

n	VMAlloc()



VMBlockHandle 	VMAlloc(

	VMFileHandle		file,			

	word		size,			/* Size of a file in bytes */

	word		userID);			/* ID # to associate with block */

This routine creates a VM block. The block is not initialized. Before you use 
the block, you must lock it with VMLock(). If you pass a size of zero bytes, 
the VM block will be given an entry in the VM handle table, but no space in 
memory or in the file will be used; a global memory block will have to be 
assigned with VMAttach().

Include:	vm.h

See Also:	VMAllocLMem(), VMAttach()

n	VMAllocLMem()



VMBlockHandle 	VMAllocLmem(

	VMFileHandle		file,				

	LMemType		ltype,				/* Type of LMem heap to create */

	word		headerSize);				/* Size to leave for LMem header...
						 * pass zero for standard header */

This routine allocates a VM block and initializes it to contain an LMem heap. 
You must pass the type of LMem heap to create. If you want a fixed data 
space, you must pass the total size to leave for a header (including the 
LMemBlockHeader); otherwise, pass a zero header size, indicating that 
only enough space for an LMemBlockHeader should be left. You do not 
need to specify a block size, since the heap will automatically expand to 
accommodate chunk allocations.

The block's user ID number is undefined. You will need to lock the block with 
VMLock() before accessing the chunks.

Include:	vm.h

Be Sure To:	When you access chunks, remember to pass the block's global memory handle 
to the LMem routines (not the block's VM handle).

See Also:	LMemInitHeap(), VMAlloc(), VMAttach()

n	VMAttach()



VMBlockHandle 	VMAttach(

	VMFileHandle		file,

	VMBlockHandle		vmBlock,

	MemHandle		mh);

This routine attaches an existing global memory block to a VM block. It is 
passed the following arguments:

file	The file's VMFileHandle.

vmBlock	The handle of the VM block to which the memory block should 
be attached. Any data associated with that block will be lost. If 
you pass a null VMBlockHandle, a new VM block will be 
allocated.

mh	The handle of the global memory block to attach.

The routine returns the handle of the VM block to which the memory block 
was attached.

If you attach to a pre-existing VM block, its user ID will be preserved. If you 
create a new block (by passing a null vmBlock argument), the user ID will be 
undefined.

Include:	vm.h

n	VMCheckForModifications()



Boolean	VMCheckForModifications(

	VMFileHandle		file);

This routine returns true if the VM file has been dirtied or updated since the 
last full save.

Include:	vm.h

n	VMClose()



word	VMClose(

	VMFileHandle		file,

	Boolean		noErrorFlag);

This routine updates and closes a VM file. If it is successful, it returns false. 
If it fails, it returns a member of the FileError enumerated type. Note that 
the routine closes the file even if it could not successfully update the file; in 
this case, any changes since the last update will be lost. For this reason, it is 
safest to call VMUpdate() first, then (after the file has been successfully 
updated) call VMClose().

If noErrorFlag is true, VMClose() will fatal-error if it could not succesfully 
update and close the file.

Include:	vm.h

n	VMCompareVMChains()



Boolean	VMCompareVMChains(

	VMFileHandle		sourceFile,

	VMChain		sourceChain,

	VMFileHandle		destFile,

	VMChain		destChain);

This routine compares two VM chains or DB items. It returns true if the two 
are identical; otherwise it returns false.

Include:	vm.h

n	VMCopyVMBlock()



VMBlockHandle 	VMCopyVMBlock(

	VMFileHandle		sourceFile,

	VMBlockHandle		sourceBlock,

	VMFileHandle		destFile);

This routine creates a duplicate of a VM block in the specified destination file 
(which may be the same as the source file). It returns the duplicate block's 
handle. The duplicate will have the same user ID as the original block.

Include:	vm.h

n	VMCopyVMChain()



VMChain 	VMCopyVMChain(

	VMFileHandle		sourceFile,

	VMChain		sourceChain,

	VMFileHandle		destFile);

This routine creates a duplicate of a VM chain (or DB item) in the specified 
destination file (which may be the same as the source file). It returns the 
duplicate's VMChain structure. All blocks in the duplicate will have the 
same user ID numbers as the corresponding original blocks.

Include:	vm.h

n	VMDetach()



MemHandle 	VMDetach(

	VMFileHandle		file,

	VMBlockHandle		block,

	GeodeHandle		owner);			/* Pass zero to have block owned by 
					 * current thread's owner */

This routine detaches a global memory block from a VM block. If the VM block 
is not currently in memory, VMDetach() allocates a memory block and 
copies the VM block into it. If the VM block is dirty, VMDetach() will update 
the block to the file before detaching it.

Include:	vm.h

n	VMDirty()



void	VMDirty(

	MemHandle		mh);

This routine marks a locked VM block as dirty.

Include:	vm.h

n	VMFind()



VMBlockHandle 	VMFind(

	VMFileHandle		file,

	VMBlockHandle		startBlock,

	word		userID);

This routine finds a VM block with the specified user ID number. If the second 
argument is NullHandle the routine will return the matching block with the 
lowest handle. If the second argument is non-null, it will return the first 
matching block whose handle is larger than the one passed (in numerical 
order).

Include:	vm.h

n	VMFree()



void	VMFree(

	VMFileHandle		file,

	VMBlockHandle		block);

This routine frees the specified VM block. If a global memory block is 
currently attached to the VM block, it is freed too.

Include:	vm.h

n	VMFreeVMChain()



void	VMFreeVMChain(

	VMFileHandle		file,

	VMChain		chain);

This routine frees the specified VM chain or DB item. If a chain is specified, 
all blocks in the chain will be freed.

Include:	vm.h

n	VMGetAttributes()



word	VMGetAttributes(

	VMFileHandle		file);

Each VM file contains a set of VMAttributes flags. These determine how the 
VM manager will treat the file. This routine returns the current flags.

Include:	vm.h

Tips and Tricks:	When the Document Control objects create files, they automatically initialize 
the attributes appropriately.

See Also:	VMSetAttributes()

n	VMGetDirtyState()



word	VMGetDirtyState(

	VMFileHandle		file);

This routine finds out if a file has been dirtied. It returns a word-sized value. 
The upper byte of the return value is non-zero if the file has not been dirtied 
since the last save, auto-save, or update; the lower byte is non-zero if the file 
has not been dirtied since the last save. Thus, if the return value is zero, the 
file must be updated.

Include:	vm.h

Tips and Tricks:	VMUpdate() is optimized for updating clean files. For this reason, it is faster 
to call VMUpdate() then it is to first check the dirty state, then call 
VMUpdate() only if the file is dirty.

n	VMGetMapBlock()



VMBlockHandle 	VMGetMapBlock(

	VMFIleHandle		file);

This routine returns the VM block handle of the file's map block.

Include:	vm.h

n	VMGrabExclusive()



VMStartExclusiveReturnValue VMGrabExclusive(

	VMFileHandle		file,

	word		timeout,

	VMOperation		operation,

	VMOperation *		currentOperation);

This routine gets exclusive access to a VM file for this thread.

Include:	vm.h

n	VMInfo()



Boolean	VMInfo(

	VMFileHandle		file,

	VMBlockHandle		block,

	VMInfoStruct *		info

This routine writes the memory handle, block size, and user ID number of the 
block. It returns false if the handle is invalid or free.

Include:	vm.h

n	VMLock()



void *	VMLock(

	VMFileHandle		file,

	VMBlockHandle		block,

	MemHandle*		mh);

This routine locks a VM block into the global heap. It returns the block's base 
address.

Include:	vm.h

n	VMMemBlockToVMBlock()



VMBlockHandle 	VMMemBlockToVMBlock(

	MemHandle		mh,

	VMFileHandle*		file);

This routine gets the VM block and file handles for a specified memory block. 
It returns the VM block handle and copies the VM file handle into *file.

The memory handle passed must be the handle of a block which is attached 
to a VM file. If it is not, the results are undefined.

Include:	vm.h

n	VMModifyUserID()



void	VMModifyUserID(

	VMFileHandle		file,

	VMBlockHandle		block,

	word		userID);

This routine changes a VM block's user ID number.

Include:	vm.h

n	VMOpen()



VMFileHandle 	VMOpen(

	char *		name,				/* Name of file to open/create */

	VMAccessFlags		flags,

	VMOpenType		mode,

	word		compression);				/* Compression threshold percentage 
						 * passed as an integer */

This routine opens or creates a VM file. It returns the handle of the opened 
file. If it is unable to open the file, it sets the error value for 
ThreadGetError(). VMOpen() looks for the file in the thread's working 
directory (unless a temporary file is being created, as described below). The 
routine takes four arguments:

name	A pointer to a string containing the name of the file to open. 
The file will be opened in the thread's current working 
directory. If a temporary file is being opened, this buffer should 
contain the full path of the directory in which to create the file, 
followed by fourteen null bytes (counting the string-ending 
null). VMOpen() will write the name of the temporary file in 
those trailing nulls.

flags	This specifies what kind of access to the file you need. The flags 
are described below.

mode	This specifies how the file should be opened. The types are 
described below.

compression 	The compression threshold percentage, passed as an integer. 
For example, to set a compression threshold of 50%, pass the 
integer `50'. When the percentage of used space in the file drops 
below the compression threshold, the VM manager will 
automatically compress the file. To use the system default 
threshold, pass a threshold of zero. The compression threshold 
is set only when the file is created; this argument is ignored if 
an existing file is opened.

The VMAccessFlags specify what kind of access to the file the caller wants. 
The following flags are available:

VMAF_FORCE_READ_ONLY
If set, the file will be opened read-only, even if the default would 
be to open the file read/write. Blocks in read-only files cannot 
be dirtied, and changes in memory blocks will not be updated 
to the disk VM blocks.

VMAF_FORCE_READ_WRITE
If set, the file will be opened for read/write access, even if the 
default would be to open the file for read-only access.

VMAF_SHARED_MEMORY
If set, the VM manager should try to use shared memory when 
locking VM blocks; that is, the same memory block will be used 
for a given VM block no matter which thread locks the block.

VMAF_FORCE_DENY_WRITE
If set, then open the file deny-write; that is, no other threads 
will be allowed to open the file for read/write access.

VMAF_DISALLOW_SHARED_MULTIPLE
If this flag is set, files with the file attribute 
GFHF_SHARED_MULTIPLE cannot be opened.

VMAF_USE_BLOCK_LEVEL_SYNCHRONIZATION
If set, the block-level synchronization mechanism of the VM 
manager is assumed to be sufficient; the more restrictive 
StartExclusive/EndExclusive mechanism is not used. This is 
primarily intended for system software.

You must also specify how the file should be opened. To do this, you pass a 
member of the VMOpenType enumerated type. The following types are 
available:

VMO_TEMP_FILE
If this is passed, the file will be a temporary data file. When you 
create a temporary file, you pass a directory path, not a file 
name. The path should be followed by fourteen null bytes, 
including the string's terminating null. The system will choose 
an appropriate file name and add it to the path string.

VMO_CREATE_ONLY
If this is passed, the document will be created. If a document 
with the specified name already exists in the working directory, 
VMOpen() will return an error condition.

VMO_CREATE
If this is passed, the file will be created if it does not already 
exist; otherwise it will be opened.

VMO_CREATE_TRUNCATE
If this is passed, the file will be created if it does not already 
exist; otherwise, it will be opened and truncated (all data 
blocks will be freed).

VMO_OPEN
Open existing file. If file does not exist, return an error 
condition.

If for any reason VMOpen() is unable to open the requested file, it will 
returns a null file handle. It will also set the error value for 
ThreadGetError(). The possible error conditions are:

VM_FILE_EXISTS
VMOpen() was passed VMO_CREATE_ONLY, but the file 
already exists.

VM_FILE_NOT_FOUND
VMOpen() was passed VMO_OPEN, but the file does not exist.

VM_SHARING_DENIED
The file was opened by another geode, and access was denied.

VM_OPEN_INVALID_VM_FILE
VMOpen() was instructed to open an invalid VM file (or a 
non-VM file).

VM_CANNOT_CREATE
VMOpen() cannot create the file (but it does not already exist).

VM_TRUNCATE_FAILED
VMOpen() was passed VMO_CREATE_TRUNCATE; the file 
exists, but could not be truncated.

VM_WRITE_PROTECTED
VMOpen() was passed VMAF_FORCE_READ_WRITE, but the 
file was write-protected.

Include:	vm.h

Tips and Tricks:	If you use the document control objects, they will take care of opening files as 
necessary; you will not need to call VMOpen().

See Also:	FileOpen()

n	VMPreserveBlocksHandle()



void	VMPreserveBlocksHandle(

	VMFileHandle		file,

	VMBlockHandle		block);

Keep the same global memory block with this VM block until the block is 
explicitly detached or the VM block is freed.

Include:	vm.h

n	VMReleaseExclusive()



void VMReleaseExclusive(

	VMFileHandle 		file);

This routine releases a thread's exclusive access to a VM file.

Include:	vm.h

n	VMRevert()



void	VMRevert(

	VMFileHandle		file,);

This routine reverts a file to its last-saved state.

Include:	vm.h

n	VMSave()



void	VMSave(

	VMFileHandle		file);

This routine updates and saves a file, freeing all backup blocks.

Include:	vm.h

n	VMSaveAs()



VMFileHandle VMSaveAs(

	VMFileHandle		file,

	const char		*name,

	VMAccessFlags		flags.

	VMOpenTypes		mode,

	word		compression);

This routine saves a file under a new name. The old file is reverted to its 
last-saved condition.

Include:	vm.h

n	VMSetAttributes()



word	VMSetAttributes(

	VMFileHandle		file,				

	VMAttributes		attrToSet,				/* Turn these flags on... */

	VMAttributes		attrToClear);				/* after turning these flags off */

This routine changes a VM file's VMAttributes settings. The routine returns 
the new attribute settings.

Include:	vm.h

Tips and Tricks:	When the Document Control objects create files, they automatically initialize 
the attributes appropriately.

Warnings:	If you turn off VMA_BACKUP, make sure you do it right after a save or revert 
(when there are no backup blocks).

See Also:	VMGetAttributes()

n	VMSetExecThread()



void	VMSetExecThread(

	VMFileHandle		file,

	ThreadHandle		thread);

Set which thread will execute methods of all objects in the file.

Include:	vm.h

n	VMSetMapBlock()



void	VMSetMapBlock(

	VMFileHandle		file,

	VMBlockHandle		block);

This routine sets the map block for a VM file. 

Include:	vm.h

n	VMSetReloc()



void	VMSetReloc(

	VMFileHandle		file,

	void (*reloc) 		(VMFileHandle					file,

			 VMBlockHandle					block,

			 MemHandle					mh,

			 void					*data,

			 VMRelocTypes					type));

This routine sets a data-relocation routine for the VM file.

Include:	vm.h

n	VMUnlock()



void	VMUnlock(

	MemHandle		mh);

This routine unlocks a locked VM block. Note that the block's global memory 
handle is passed (not its VM handle).

Include:	vm.h

n	VMUpdate()



word	VMUpdate(

	VMFileHandle		file);

This routine updates dirty blocks to the disk.

Include:	vm.h

Tips and Tricks:	VMUpdate() is optimized for updating clean files to the disk. Therefore, it is 
faster to call VMUpdate() whenever you think it might be necessary, than it 
is to check the dirty state and then call VMUpdate() only if the file is 
actually dirty.

n	VMVMBlockToMemBlock()



MemHandle 	VMVMBlockToMemBlock(

	VMFileHandle		file,

	VmBlockHandle		block);

This routine returns the global handle of the memory block attached to a 
specified VM block. If no global block is currently attached, it will allocate and 
attach one.

Include:	vm.h

n	WinAckUpdate()



void	WinAckUpdate(

	WindowHandle		win);

This routine acknowledges that the application has received 
MSG_META_EXPOSED for the specified window, but chooses not to do any 
updating.

Include:	win.h

n	WinApplyRotation()



void	WinApplyRotation(

	WindowHandle		win,

	WWFixedAsDWord		angle,

	WinInvalFlag		flag);

This routine applies the specified rotation to the window's transformation 
matrix.

Include:	win.h

n	WinApplyScale()



void	WinApplyScale(

	WindowHandle		win,

	WWFixedAsDWord		xScale,

	WWFixedAsDWord		yScale,

	WinInvalFlag		flag);

This routine applies the specified scale factor to the window's transformation 
matrix.

Include:	win.h

n	WinApplyTranform()



void	WinApplyTransform(

	WindowHandle		win,

	const TransMatrix *		tm,

	WinInvalFlag		flag);

This routine concatenates the passed transformation matrix with the 
window's transformation matrix. The result will be the window's new 
transformation matrix.

Include:	win.h

n	WinApplyTranslation()



void	WinApplyTranslation(

	WindowHandle		win,

	WWFixedAsDWord		xTrans,

	WWFixedAsDword		yTrans,

	WinInvalFlag		flag);

This routine applies the specified translation to the window's transformation 
matrix.

Include:	win.h

n	WinApplyTranslationDWord()



void	WinApplyExtTranslation(

	WindowHandle		win,

	sdword		xTrans,

	sdword		yTrans,

	WinInvalFlag		flag);

This routine applies the specified translation to the window's transformation 
matrix. The translations are specified as 32-bit integers.

Include:	win.h

n	WinChangeAck()



WindowHandle WinChangeAck(

	WindowHandle		win,

	sword		x,

	sword		y,

	optr *		winOD);

Include:	win.h

n	WinChangePriority()



void	WinChangePriority(

	WindowHandle		win,

	WinPassFlags		flags,

	word		layerID);

This routine changes the priority for the specified window.

Include:	win.h

n	WinClose()



void	WinClose(

	WindowHandle		win);

This routine closes and frees the specified window.

Include:	win.h

n	WinDecRefCount()

void	WinDecRefCount(

	WindowHandle		win);

This routine is part of the window closing mechanism.

n	WinEnsureChangeNotification()

void	WinEnsureChangeNotification(void);

Include:	win.h

n	WinGeodeGetInputObj()

optr	WinGeodeGetInputObj(

	GeodeHandle		obj);

This routine fetches the optr of the input object for the specified geode. If 
there is no such object, it returns a null optr.

Include:	win.h

n	WinGeodeGetParentObj()

optr	WinGeodeGetParentObj(

	GeodeHandle		obj);

This routine fetches the optr of the parent object of the specified geode. If 
there is no such object, it returns a null optr.

Include:	win.h

n	WinGeodeSetActiveWin()

void	WinGeodeSetActiveWin(

	GeodeHandle		gh,

	WindowHandle		win);

This routine sets the active window for the specified geode.

Include:	win.h

n	WinGeodeSetInputObj()

void	WinGeodeSetInputObj(

	GeodeHandle		gh,

	optr		iObj);

This routine sets the input object for the specified geode.

Include:	win.h

n	WinGeodeSetParentObj()

void	WinGeodeSetParentObj(

	GeodeHandle		gh,

	optr		pObj);

This routine sets the parent object for the specified geode.

Include:	win.h

n	WinGeodeSetPtrImage()

void	WinGeodeSetPtrImage(

	GeodeHandle		gh,

	optr		ptrCh);

This routine sets the pointer image for the specified geode.

Include:	win.h

n	WinGetInfo()



dword	WinGetInfo(

	WindowHandle		win,

	WinInfoTypes		type,

	void *		data);

This routine retrieves the private data from a GState.

Include:	win.h

n	WinGetTransform()



void	WinGetTransform(

	WindowHandle		win,

	TransMatrix *		tm);

This routine retrieves the transformation matrix for the specified window. It 
writes the matrix to *tm.

Include:	win.h

n	WinGetWinScreenBounds()



void	WinGetWinScreenBounds(

	WindowHandle		win,

	Rectangle *		bounds);

This routine returns the bounds of the on-screen portion of a window 
(specified in screen co-ordinates). It writes the bounds to *bounds.

Include:	win.h

n	WinGrabChange()



Boolean	WinGrabChange(

	WindowHandle		win,

	optr		newObj);

This routine allows an object to grab pointer events. It returns zero if it was 
successful; otherwise it returns non-zero.

Include:	win.h

n	WinInvalReg()



void	WinInvalReg(

	WindowHandle		win,

	const Region *		reg,

	word		axParam,

	word		bxParam,

	word		cxParam,

	word		dxParam);

This routine invalidates the specified region or rectangle.

Include:	win.h

n	WinMove()



void	WinMove(

	WindowHandle		win,

	sword		xMove,

	sword		yMove,

	WinPassFlags		flags);

This routine moves a window. If the WPF_ABS bit of flags is set, the window's 
new position is specified relative to its parent's position. If it is clear, the 
window's new position is specified relative to its current position.

Include:	win.h

n	WinOpen()



WindowHandle WinOpen(

	Handle		parentWinOrVidDr,

	optr		inputRecipient,

	optr		exposureRecipient,

	WinColorFlags		colorFlags,

	word		redOrIndex,

	word		green,

	word		blue,

	word		flags,

	word		layerID,

	GeodeHandle		owner,

	const Region *		winReg,

	word		axParam,

	word		bxParam,

	word		cxParam,

	word		dxParam);

This routine allocates and initializes a window and (optionally) an associated 
GState.

Include:	win.h

n	WinReleaseChange()

void	WinReleaseChange(

	WindowHandle		win,

	optr		obj);

This routine releases an object's grab on the change OD.

Include:	win.h

n	WinResize()



void	WinResize(

	WindowHandle		win,

	const Region *		reg,

	word		axParam,

	word		bxParam,

	word		cxParam,

	WinPassFlags		flags);

This routine resizes a window. It can move it as well.

Include:	win.h

n	WinScroll()



void	WinScroll(

	WindowHandle		win,

	WWFixedAsDWord		xMove,

	WWFixedAsSWord		yMove,

	PointWWFixed *		scrollAmt);

This routine scrolls a window.

Include:	win.h

n	WinSetInfo()



void	WinSetInfo(

	WindowHandle		win,

	WinInfoType		type,

	dword		data);

This routine sets some data for the specified window.

Include:	win.h

n	WinSetNullTransform()



void	WinSetNullTransform(

	WindowHandle		win,

	WinInvalFlag		flag);

This routine changes a window's transformation matrix to the null (or 
identity) matrix.

Include:	win.h

n	WinSetPtrImage()

void	WinSetPtrImage(

	WindowHandle		win,

	WinSetPtrImageLevel		ptrLevel,

	optr		ptrCh);

This routine sets the pointer image within the range handled by the specified 
window.

Include:	win.h

n	WinSetTransform()



void	WinSetTransform(

	WindowHandle		win,

	const TransMatrix *		tm,

	WinInvalFlag		flag);

This routine replaces the window's transformation matrix with the one 
passed in *tm.

Include:	win.h

n	WinSuspendUpdate()



void	WinSuspendUpdate(

	WindowHandle		win);

This routine suspends the sending of update messages to the window. The 
messages will be sent when WinUnSuspendUpdate() is called.

Include:	win.h

n	WinTransform()

XYValueAsDWord 	WinTransform(

	WindowHandle		win,

	sword		x,

	sword		y);

This routine translates the passed document coordinates into screen 
coordinates.

Include:	win.h

n	WinTransformDWord()

void	WinTransformDWord(

	WindowHandle		win,

	sdword		xCoord,

	sdword		yCoord,

	PointDWord *		screenCoordinates);

This routine translates the passed document coordinates into screen 
coordinates. The translated coordinates are written to *screenCoordinates.

Include:	win.h

n	WinUnSuspendUpdate()



void	WinUnSuspendUpdate(

	WindowHandle		win);

This routine cancels a previous WinSuspendUpdate() call.

Include:	win.h

n	WinUntransform

XYValueAsDWord 	WinUntransform(

	WindowHandle		win,

	sword		x,

	sword		y);

This routine translates the passed screen coordinates into document 
coordinates.

Include:	win.h

n	WinUnTransformDWord()

void	WinTransformDWord(

	WindowHandle		win,

	sdword		xCoord,

	sdword		yCoord,

	PointDWord *		documentCoordinates);

This routine translates the passed screen coordinates into document 
coordinates. The translated coordinates are written to 
*documentCoordinates.

Include:	win.h

n	WWFixedToFrac



word	WWFixedToFrac(WWFixed wwf)

This macro lets you address the fractional portion of a WWFixed value. It is 
legal to use this to assign a value to the fractional protion; that is,

WWFixedToFrac(myWWFixed) = 5;

is perfectly legal.

Include:	geos.h

n	WWFixedToInt



word	WWFixedToInt(WWFixed wwf)

This macro lets you address the intetgral portion of a WWFixed value. It is 
legal to use this to assign a value to the integral protion; that is,

WWFixedToInt(myWWFixed) = 5;

is perfectly legal.

Include:	geos.h
