Development Info:

Written 12/01/2000 for ithought-a2
Anthony Taranto

Extending ithought

ithought is a very open ended program. ithought itself does nothing more than organize entries of text internally. It is the extensibility of ithought that makes it useful. ithought extensions, also called "actions", are invoked by an ithought user to perform a task using the text body of an ithought entry. Possible tasks include uploading the text to an online diary site, sending the text as an email, or anything else you can think of. ithought actions can either be compiled into .so files from a language such as C or C++, or they can be written in an interpereted scripting language such as bash, perl, python, or ruby. Once the action gets invoked by ithought, the possibilities are unlimited. This document will inform programmers on how to write extensions for ithought.

Writing compiled extensions in C/C++ (.so files)

Basic Info

This section will examine a rather useless action called "stdout". This action does nothing more than take the body of the entry it was passed and print it to the standard output. Here is the complete code of "stdout.c":

char *menu_title( void ){
        return( "stdout" );
}

char *get_info( void ){
        return( "The stdout module outputs the entry body to stdout." );
}

void module_action( int widget, char **body ){
        printf( "%s\n", *body );
}

An ithought action written in C must have three functions that the main ithought program can call after the action has been dynamically linked into a running ithought process:

char *menu_title( void );
char *get_info( void );
void *module_action( int widget, char **body );

The string returned by menu_title() is the string that ithought places in the actions popup menu. In most cases, this should be the name of the action. In this case, the stdout function returns the string "stdout". When the ithought user selects the menu option labeled "stdout", he will be invoking this action.


The string returned by get_info() is a more descriptive output of what the action does. This string is displayed under the "Actions" tab of the ithought program, when the user clicks on the name of your action in the list on the left of this tab. This string can be much longer, and should provide the user with a good deal of information on what to expect should the action be invoked. The "stdout" action is rather straightforward, it outputs the string "The stdout module outputs the entry body to stdout.". Not very exciting, but a good description of the action. Programmers are incouraged to place their names and email addresses in this string, allowing ithought users to contact them.


module_action() is where your action does it's work. The first parameter is a pointer to the GTK+ widget that invoked your action. Because not all actions are implemented in GTK+, the GtkWidget type may not exist, therefore prompting the use of this parameter as an int. You should never need to do anything with this parameter, and accessing a GtkWidget in a non-gtk action as a type int will lead to Bad Things. You have been warned. The parameter the action author is interested in is the char **body. This is the string representing the body of the ithought entry that your action was invoked to work with. If you do not feel comfortable working with a type char **, define a type char * to point to your text with this code:

char *myCharP = *body;

Your action is now free to do whatever it wishes with this text. The stdout action does nothing more than print it using printf(). Althought ithought will only call these three functions, you are free to define other functions.

Compiling into an .so file

Compile your .c file into a .o file with the following command:

gcc -c myAction.c

Make this .o file into a .so file using this command:

gcc -shared myAction.o -o myAction.so

ithought loads .so actions from the directory ~/.ithought/action_module/ when it is run. All .so actions should be placed in that directory.

Writing Interpereted Extensions in a Scripting Language

Basic Info

Actions can also be written in interpereted/scripting languages. ithought will call script actions in one of the following 3 ways:

myAction.pl title
myAction.pl info
myAction.pl action "body of ithought entry"

These three possibilities are equivalent to the three necessary functions of compiled actions. If your script action receives "title" as a first argument, it should write it's title to stdout. ithought will use the output as the name of the action in the popup menu. When info is the first argument, ithought will take the output of your script and display it in the "Actions" tab of the ithought program when your action is selected from the list. It is important to note that ithought runs an action script with the "info" argument once, as the action is loaded, while in compiled actions the get_info() function is called each time the user selects the action in the "Actions" tab (NOTE: this may change).

Finally, when the first argument is "action", the body of the ithought entry that your action has been invoked on is passed to your script as the second argument. Your action scripts can now perform their function using this text. Note that althought your scripts stdout is piped to the ithought process, ithought will echo the output of your script action to the stdout of the ithought process.

ithought loads all script actions from the ~/.ithought/actions_scripts/ directory when run. Script action files must be executable for ithought to utilize them.