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 * );
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 );

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

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

Description

Retrieves the value of the named integer from the environment

Arguments

< name - the name of the 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 environment

Arguments

< name - the name of the 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 environment. Note that as with all other strings in the API, this one must not be deleted.

Arguments

< name - the name of the 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 environment.

Arguments

< name - the name of the 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 environment.

Arguments

< name - the name of the 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 environment.

Arguments

< name - the name of the 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