AlLiveData

Utility functions for OpenAlias. These functions do not belong to a class.

Synopsis

#include <AlLiveData.h>

Enumeration types:

typedef enum {

kFileBrowseRead,

kFileBrowseWrite

} AlFileBrowseMode;

typedef enum {

kOK_Cancel,

kYes_No_Cancel,

kOK_Only,

kYes_No

} AlConfirmType;

typedef enum {

kOK,

kYes,

kNo,

kCancel

} AlAnswerType;

void AlAllowMenuRebuilds( boolean );

void AlRebuildMenus( void );

void AlResetAllMenus( void );

statusCode AlDebugResetOptionBox( const char * );

const char* AlInvokeSchemeCommand( const char * );

const char* AlInvokeSchemeFile( const char*, const char * = NULL );

statusCode AlFileBrowser( AlFileBrowseMode, char **, const char *,

boolean, const char * );

statusCode AlFileBrowser( AlFileBrowseMode, char **, const char *,

boolean, const char *, const char * );

boolean AlEscapeKeyPressed( void );

statusCode AlPromptBox( AlConfirmType, char*, AlAnswerType*, short, short );

statusCode AlGetInteger( const char *, int& );

statusCode AlGetDouble( const char *, double& );

statusCode AlGetString( const char *, const char *& );

statusCode AlSetInteger( const char *, int );

statusCode AlSetDouble( const char *, double );

statusCode AlSetString( const char *, const char* );

void AlPrintf( unsigned int, const char*, ... );

void AlVprintf( unsigned int, const char*, va_list ap );

Description

These functions are support functions for use with OpenAlias plug-ins.

Summary

void AlAllowMenuRebuilds( boolean on_or_off )

Description

Controls if AlRebuildMenus() will execute.

void AlRebuildMenus( void )

Description

Rebuilds the Alias menus.

void AlResetAllMenus( void )

Description

Forces a rebuild of all of the menus

const char* AlInvokeSchemeFile( const char * filename, const char *filenamePrefix )

Description

Executes a Scheme file and returns back the string from the execution. NULL is returned if the file could not be found. Usually an empty string indicates success. This routine will also search in a "scm" subdirectory for the filename. This feature allows existing plug-ins to keep working with the new "scm" subdirectory setup being used.

Arguments

< filename - the name of the file to execute

< filenamePrefix - if not NULL, the pathname to prefix to the filename

Return Values

NULL - the file could not be found

"" - the command succeeded

const char * AlInvokeSchemeCommand( const char *command )

Description

Executes a Scheme command. The string result is returned.

Arguments

< command - the command string to execute

statusCode AlGetInteger( const char * name, int& value )

Description

Retrieves the value of the named integer from the Scheme environment

Arguments

< name - the name of the Scheme variable

> value - the returned value

Return Codes

sInvalidArgument - name was NULL

sSuccess - the value was returned

sFailure - the variable could not be found

statusCode AlGetDouble( const char * name, double& value )

Description

Retrieves the value of the named double from the Scheme environment

Arguments

< name - the name of the Scheme variable

> value - the returned value

Return Codes

sInvalidArgument - name was NULL

sSuccess - the value was returned

sFailure - the variable could not be found

statusCode AlGetString( const char * name, const char *& value )

Description

Retrieves the value of the named string from the Scheme environment. Note that as with all other strings in the API, this one must not be deleted.

Arguments

< name - the name of the Scheme variable

> value - a pointer to the resulting string

Return Codes

sInvalidArgument - name was NULL

sSuccess - the value was returned

sFailure - the variable could not be found

statusCode AlSetInteger( const char *name, int val )

Description

Sets the value of the named integer in the Scheme environment.

Arguments

< name - the name of the Scheme variable

< value - the int value

Return Codes

sSuccess - the value was set

sFailure - the variable could not be found

statusCode AlSetDouble( const char *name, double val )

Description

Sets the value of the named double in the Scheme environment.

Arguments

< name - the name of the Scheme variable

< value - the double value

Return Codes

sSuccess - the value was set

sFailure - the variable could not be found

statusCode AlSetString( const char *name, const char *val )

Description

Sets the value of the named string in the Scheme environment.

Arguments

< name - the name of the Scheme variable

< value - a pointer to the string value

Return Codes

sSuccess - the value was set

sFailure - the variable could not be found

const char * AlGetAliasPreference( const char * pref )

Description

Gets the Alias preference (from the .AliasPrefs file) associated with the string passed in. The returned value is the value of the preference, or NULL if the given entry does not exist. The string returned does not have to be deallocated.

statusCode AlPromptBox( AlConfirmType type, char *msg, AlAnswerType* answer,short x, short y )

Description

Invokes a dialog box, prompting the user for confirmation. The width of the dialog box is set to accommodate the longest sentence in the specified message (msg). Sentences in 'msg' should be delineated by new-line characters (that is, '\n'). To invoke the dialog box at the current cursor location, pass in -1 and -1 for x and y.

Arguments

< type - the type of prompt box to create

< msg - the text to place in the prompt box

> answer - a code for which button was pressed

< x - the x location for the confirm box

< y - the y location for the confirm box

Return Codes

sSuccess - the confirm box executed successfully

sFailure - the confirm box failed to execute successfully. Note that in this case, the value of answer is undefined.

statusCode AlDebugResetOptionBox( const char *editorName )

Description

Resets the editor option box. It is intended to be used by people who modify the option box and want to see the changes (i.e. debugging ). This may create a severe memory leak.

Arguments

< editorName - the name of the editor to reset

Return Codes

sSuccess - the editor was reset

sFailure - the editor could not be reset

statusCode AlFileBrowser( AlFileBrowseMode mode, char **returnFilename, const char *acceptString, boolean showSample, const char *fileExtension )

Description

Prompts the user with a file browser to select a filename.

If the mode is kFileBrowseWrite, then the browser will prompt the user with a blank filename.

The browser will allocate a string(using strdup) for the return filename and point 'returnFilename' to it. It is up to the caller to free it, using 'free()'.

The 'acceptString' is the text that is printed on the accept button. This will be a string such as "Load", "Okay", "Accept" etc.

Example code

char *filename;
statusCode stat = AlFileBrowser( kFileBrowseRead, &filename, "Okay String", FALSE, 
"myextension" );
if( stat == sSuccess )
{
	.. do something with filename ...
	free( filename );
}

Arguments

< mode - this is either kFileBrowseRead or kFileBrowseWrite

> returnFilename - address of the string pointer that is to be set to the file name

< acceptString - the non-NULL string that is printed on the 'accept' button

< showSample - if TRUE, icon sized samples of the data files will be shown

< fileExtension - the extension for the file. Setting this has no effect.

Return Codes

sInvalidArgument - an invalid argument was given

sSuccess - a filename was selected (*returnFileName will point to the string)

sFailure - an error occurred or no filename was selected

statusCode /*::*/ AlFileBrowser( AlFileBrowseMode mode, char **returnFilename, const char *acceptString, boolean showSample, const char *fileExtension, const char *defaultPath )

Description:

Same as the other AlFileBrowser method with the addition that a 'defaultPath' can be specified.

If defaultPath is NULL or the length of defaultPath is greater than FILENAME_MAX, then sInvalidArgument will be returned.

boolean AlEscapeKeyPressed( void )

Description

Checks if the Escape key has been pressed. Can be used to allow the user to abort an operation.

Example code:

for ( int i = 0; i < 40000; i++ )
{
	rebuildFractalImage( i );
	if ( AlEscapeKeyPressed() )
        		return sFailure;
}

Return Values

TRUE - Escape key has been pressed

FALSE - Escape key has not been pressed