MapleHelp - access help from external code
|
Calling Sequence
|
|
MapleHelp(kv, topic, section, writechar, writeattrib, width, data)
|
|
Parameters
|
|
kv
|
-
|
kernel handle of type MKernelVector
|
topic
|
-
|
topic name
|
section
|
-
|
section name or NULL
|
writechar
|
-
|
character output function
|
writeattrib
|
-
|
attribute output function
|
width
|
-
|
integer screen width
|
data
|
-
|
arbitrary data passed to the write callbacks
|
|
|
|
|
Description
|
|
•
|
The MapleHelp function searches for and retrieves a help page or a section of a help page, based on the topic passed to it. The results are passed as a stream of characters and attributes to the specified callback functions.
|
•
|
The topic parameter specifies the help page retrieved. For example, to look up help on integration, set topic = "int".
|
•
|
The section argument indicates which section of the page to display. If this is passed as "" or NULL, the entire page is displayed. To restrict display to a particular section of the page, pass one of the following values.
|
"usage"
|
Shows just the function name (one-line description) and
|
|
calling sequence information
|
|
|
"description"
|
Shows the detailed description of the function
|
|
|
"examples"
|
Shows examples of the function's usage
|
|
|
"seealso"
|
Shows a list of alternate topics related to this
|
|
function
|
|
|
|
|
•
|
The writechar function is called once for each character of output. This function must be declared to match the following prototype.
|
M_BOOL M_DECL writechar( void *data, int c );
|
|
|
|
The writechar function can terminate rendering by returning TRUE.
|
•
|
The writeattrib parameter specifies the function to which attribute information is passed. Each given attribute applies to all subsequent character sent to writechar until a new attribute is given. This function must be declared to match the following prototype.
|
M_BOOL M_DECL writeattrib( void *data, int attrib );
|
|
|
|
The following are the possible attribute values given to the second argument of the callback.
|
FN_NORM
|
normal text mode
|
|
|
FN_ITAL
|
italic text mode
|
|
|
FN_BOLD
|
boldfaced text mode
|
|
|
FN_UNDER
|
underlined text mode
|
|
|
|
|
|
The writeattrib function can be omitted by passing NULL for the writeattrib parameter.
|
•
|
The width parameter indicates the width, in characters, to which the help information is formatted. Examples and tables are always formatted with padded spaces, centered in the middle of the given width. Therefore, specifying a large number for width does not cause output to arrive in a single line, but rather generates output containing many blanks.
|
•
|
The data pointer is passed to the writechar and writeattrib callback functions. It can point to any data that might be useful during processing of the callbacks.
|
•
|
The MapleHelp function returns NULL if successful, or it returns a pointer to an error message if unsuccessful.
|
|
|
Examples
|
|
#include "maplec.h"
|
typedef struct {
|
int size, len;
|
char *string;
|
} myString;
|
static M_BOOL M_DECL myWriteChar( void *data, int c )
|
{
|
myString *output = (myString*)data;
|
if( output->size-1 == output->len ) {
|
output->size *= 2;
|
output->string = realloc(output->string,sizeof(char)*output->size);
|
if( !output->string )
|
return( TRUE );
|
}
|
output->string[output->len++] = (char)c;
|
output->string[output->len] = '0';
|
return( FALSE );
|
}
|
ALGEB M_DECL MyHelpToString( MKernelVector kv, ALGEB *args )
|
{
|
char *topic, *err;
|
myString output;
|
ALGEB r;
|
if( 1 != MapleNumArgs(kv,(ALGEB)args) ) {
|
MapleRaiseError(kv,"one argument expected");
|
return( NULL );
|
}
|
topic = MapleToString(kv,args[1]);
|
output.size = 256;
|
output.len = 0;
|
output.string = (char*)malloc(256*sizeof(char));
|
output.string[0] = '0';
|
if( (err=MapleHelp(kv,topic,NULL,myWriteChar,NULL,70,&output)) ) {
|
if( output.string )
|
free(output.string);
|
MapleRaiseError(kv,err);
|
}
|
if( !output.string ) {
|
r = NULL;
|
MapleRaiseError(kv,"out of memory");
|
}
|
else {
|
r = ToMapleString(kv,output.string);
|
free(output.string);
|
}
|
return( r );
|
}
|
|
|
Execute the external function from Maple.
>
|
|
>
|
|
>
|
|
>
|
|
| (1) |
>
|
|
| (2) |
|
|