Functions

The API supports several functions which are available from C as well as C++. All are available from OpenAlias, and some are available in OpenModel as well (with reduced functionality).

AlPrintf(), AlVprintf()

Header file: AlLiveData.h

Prototype:

void AlPrintf( AlOutputType ot, const char* fmt, ... );
void AlVprintf( AlOutputType ot, const char* fmt, va_list ap );

Description:

These functions work like printf() but can output to the prompt line or the errlog file. This function is available to OpenModel and OpenAlias, however in OpenModel kErrlog, kPrompt, and kPromptNoHistory output to stdout.

AlOutputType is one of:

• kStdout
• kStderr
• kErrlog
• kPrompt
• kPromptNoHistory

AlFileBrowser()

Header file: AlLiveData.h

Prototype:

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. Note that the fileExtension field is currently unimplemented and has no effect (this may be implemented in the future). This function is not available in OpenModel.

Arguments:

• < mode - this is either kFileBrowseRead or kFileBrowseWrite. kFileBrowseWrite will prompt the user with a blank filename.
• > returnFilename - the browser will allocate a string for the return filename and point `returnFilename' to it. It is up to the caller to free this string using delete [].
• < acceptString - the string that is printed on the `accept' button. This string cannot be NULL. (This will be a string such as "Load", "Okay", "Accept", etc.)
• < showSample - if TRUE, then icon sized samples of the data files will be shown.
• < fileExtension - the extension for the file. Currently 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

Example:

char *filename;
statusCode stat = AlFileBrowser( kFileBrowseRead, &filename,
		"Load", FALSE, NULL );
AlPrintf( kPrompt, "You selected %s.", filename );
free (filename);

AlInvokeSchemeFile()

Header file: AlLiveData.h

Prototype:

 const char* AlInvokeSchemeFile( char * fname, const char *dirName );

Description:

This function causes the named Scheme file to be run. This is most often done in the plugin_init() function of a plug-in to cause the initial values for option box variables to be set. This function is not available in OpenModel.

Arguments:

• < fname - this is the name of the Scheme file which will be invoked.
• < dirName - an optional argument. This specifies the absolute pathname to the specified file.

Returns

• NULL - if the file cannot be found
• A string representing the output of the execution of the Scheme file, usually the NULL string, if the command succeeded

InvokeSchemeCommand()

Header file: AlLiveData.h

Prototype:

const char *AlInvokeSchemeCommand( const char *command );

Description:

This function causes the given scheme command to be invoked.

Arguments:

• < command - this is the Scheme command to be invoked.

Returns

• A string representing the output of the execution of the Scheme file, usually the NULL string, if the command succeeded

AlGetInteger(), AlGetDouble(), AlGetString()

Header file: AlLiveData.h

Prototype:

statusCode AlGetInteger( const char * name, int& value );
statusCode AlGetDouble( const char * name, double& value );
statusCode AlGetString( const char * name, const char *& value );

Description:

These functions get the value of the given Scheme variable. sSuccess is returned if the value was successfully returned. These functions are not available in OpenModel.

AlSetInteger(), AlSetDouble(), AlSetString()

Header file: AlLiveData.h

Prototype:

statusCode AlSetInteger( const char * name, int value );
statusCode AlSetDouble( const char * name, double value );
statusCode AlSetString( const char * name, const char * value );

Description:

These functions set the value of the given Scheme variable. sSuccess is returned if the value was successfully returned. These functions are not available in OpenModel.

These functions can be used in a init_option_function that will be described in the section on "General Option Box Attributes" for setting values in the option box before it is displayed.

AlIsValid()

Header file: AlObject.h

Prototype:

boolean AlIsValid( AlObject* obj );

Description:

This is the central function to call to check that a given OpenAlias pointer references a valid object. Three checks will be performed - the first is done here, and simply checks that the pointer is non-null. The other two checks are done in the isValid method of the object, which checks that the object's data field is valid, and finally that the object is in the currently active stage (universe).

Arguments:

• < obj - Any AlObject pointer (could be NULL).

Return codes:

• TRUE - the object is valid
• FALSE - the object is invalid

AlAreEqual()

Header file: AlObject.h

Prototype:

boolean AlAreEqual(AlObject* o1, AlObject* o2);

Description:

This function should be called whenever it is necessary to check whether two OpenAlias pointers are referencing the same Alias object. Note that the two pointers may reference different OpenAlias wrappers, but those wrappers may both reference the same Alias object. Use this function instead of checking for pointer equality.

Note: if both pointers are NULL, FALSE will be returned.

Arguments:

• < o1 - Any AlObject pointer (could be NULL).
• < o2 - Any AlObject pointer (could be NULL).

Return codes:

• TRUE - the two pointers reference the same Alias object
• FALSE - the two pointers reference different Alias objects or one of the pointers is NULL.

AlGetAliasPreference()

Header file: AlLiveData.h

Prototype:

const char *AlGetAliasPreference( const char *name );

Description:

This function gets the value of the Alias preference of the given name. An Alias preference is an assignment of a value to a name. These assignments are defined in the file $HOME/.AliasPrefs. They are settable through the preferences window in Alias, or by editing the file directly. This function is not available in OpenModel. This function will return the value of the preference, or NULL if the given name does not exist.

Arguments:

• < name - The name of the preference to get.

AlPromptBox()

Header file: AlLiveData.h

Prototype:

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

Description:

This function brings up a dialog box, prompting the user for confirmation. Two kinds of dialog boxes are supported: yes/no/cancel and ok/cancel. The width of the prompt box will be set by the longest line of the message. This function is not available in OpenModel.

Arguments:

• < type - The kind of dialog box to create: kYesNoCancel or kOkCancel.
• < msg - The text to print in the dialog box.
• > answer - The result of the invocation.
• < x,y - The location on the screen to create the dialog box. -1,-1 specifies the current cursor position.

Return codes:

• sSuccess - The dialog box executed normally. In this case the value of answer is the user's response.
• sFailure - The dialog box failed to execute normally. In this case the value of answer is undefined.