AlLiveData

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 	AlScrollablePromptBox( AlConfirmType , char *, char *, 
		AlAnswerType * );
statusCode 	AlStringPromptBox( AlConfirmType type, char *,
		AlAnswerType *,char *& );
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 );
char	*makeAltPath(const char *dirName, const char *suffix);

Description

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

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 /*::*/ AlScrollablePromptBox( AlConfirmType type, char *msg, char *scrollMsg, AlAnswerType *answer )

Description

Bring up a dialog box, prompting the user for confirmation. The width of the confirm box will be set to accommodate the longest sentence in ’staticMsg’. Sentences in ’staticMsg’ should be delineated by new-line characters, that is, ’\n’. A scrollable widget will contain the text of ’scrollMsg’. Sentences in ’scrollMsg’ should also be delineated with new-line characters. The width of the scrollable widget is fixed and does not grow with the size of the confirm box. The dialog box will come up at the current cursor location. Use this method to display short fixed messages above a longer free-form message.

Arguments

< type - the type of prompt box to create

< staticMsg - the static text to place in the prompt box

< scrollMsg - the scrollable text to place in the prompt box

> answer - a code for which button was pressed

Return Codes

sSuccess - the confirm box executed successfully

sFailure - the confirm box failed to execute successfully. This could be due to being too early in Alias’ initialization state as plug-ins are autoloading. Note: the value of answer is undefined.

sInvalidArgument - null parameter enter

statusCode /*::*/ AlStringPromptBox( AlConfirmType type,char *msg, AlAnswerType *answer, char *& msgResponse )

Description

Bring up a dialog box which allows the user to prompt for a user string response. Instructions to the user can be specified with the ’msg’ parameter.

Notes:

1. The dialog box will come up at the current cursor location.

2. The msgResponse string is owned by Alias and should not be freed by the API application.

3. If several calls to this function will be done one after the other, then the msgResponse should be copied since it will be overwritten in the following call.

Arguments

< type - the type of prompt box to create

< msg - static text information for the user

> answer - a code for which button was pressed

> msgResponse - the text that the user entered

Return Codes

sSuccess - the confirm box executed successfully

sFailure - the confirm box failed to execute successfully. This could be due to being too early in Alias’ initialization state as plug-ins are autoloading. Note: the value of answer is undefined.

sInvalidArgument - msg is NULL or answer is NULL

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 (that is, 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" and so on.

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

char * makeAltPath(const char *dirName, const char *suffix)

Description

Directory name utility for converting a path to a sibling directory. This function is used by plug-ins for finding sibling directories such as scm, help and so on. For example, makeAltPath ("/usr/aw/plugins/lib", "scm") will return "/usr/aw/plugins/scm".

Arguments

< dirName - plug-in path name

< suffix - directory name of the sibling