$Id: HACKING 539 2007-07-18 11:52:43Z tpgww $ This file is part of emelFM2. It was ripped off from xchat2. Just some tips if you're going to help with emelFM2 code (patches etc).. == Source code style conventions == * Use "//" C++ style comments. * Use tabs, not spaces, to indent code. (Recommended is a tab size of 4.) * Stick to the same consistant coding style: void routine (void) { if (function (gpointer a, gint b, gchar *c)) { //do something gint x = b + 1; printf (_("Break lines after 80 characters, in general.\n)) rt->set = e2_option_tree_register (option_name, group_name, option_name, NULL, NULL, NULL, E2_OPTION_TREE_UP_DOWN | E2_OPTION_TREE_ADD_DEL); printf (_("or _perhaps_ NOT after 80, if the line is just a string that needs to be internationalised like this.\n")); } } (vertically aligned braces, a space after if, while, functions, etc.). == How to make a really nice and clean patch? == * Please provide unified format diffs (run diff -u). * Call your patch something more meaningfull than emelfm2.diff. Have two directories, unpacked from the original archive: emelfm2-0.0.9 emelfm2-0.0.9p1 Then edit/compile the emelfm2-0.0.9p1 directory. When you're done, make a patch with: cd emelfm2-0.0.9p1 make clean cd .. diff -urN emelfm2-0.0.0 emelfm2-0.0.0p1 > emelfm2-something.diff == Some UI design rules == * Dialogs should be quitable by pressing ESC and activatable pressing ENTER. * All windows and dialogs should be freely resizable, ie they must not have a minimum size. * Provide context menus where possible. * Have a flat dialog hierarchy, ie don't have a million dialogs on top of each other to achieve something. * Dialogs must not block the main window. * Be configurable and scaleable, ie don't boast of advanced functionality but provide it through context menus and expanders. NOTE: the emelfm2 plugin api will probably change. Thus the following information is subject to change. == Plugin Development == Here is an outline of the Plugin Writing process. Hopefully I will be able to write a more extensive document when I get time. Step 1) #include "emelfm2.h" <- You need this to get access to all the functions and data structures of emelFM Step 2) Write the function that does what you want your plugin to do when activated. For example, if you want a plugin that prints "Hello World", then you would write this function. void hello_world() { status_message("Hello World\n"); } * The restricions for this function are that it must return void and can take no parameters. Step 3) Write an init_plugin function something like this: gint init_plugin(Plugin *p) { p->name = "Hello World"; p->description = "Prints \"Hello World\" on the output window."; p->plugin_cb = hello_world; /* This is whatever you named the function */ /* in Step 2 */ return TRUE; } * This function *must* be called init_plugin, take a Plugin * argument, and return gint. Step 4) If your plugin needs any cleaning up when it is unloaded you can *optionally* implement an unload_plugin function as follows: void unload_plugin(Plugin *p) { status_message("I'm being unloaded\n"); } * This function *must* be called unload_plugin, take a Plugin * argument, and return void. Step 5) Add your plugin to the "OBJS = " line in the Makfile. For example, if the source file for your plugin is hello_world.c, then you would add hello_world.so to the "OBJS = " list in the Makefile. emelFM Internals ~~~~~~~~~~~~~~~~ There are four major data structures that you will probably need to understand. ViewInfo: The backbone of emelFM is the ViewInfo structure. These structures hold everything that makes up the two panels in the interface. FileInfo: This is a simple data structure that corresponds to a single row in the panel file list. They contain two fields, the filename and a stat struct that holds the information retrieved from calling lstat on the file. App: The App data structure encompasses the entire user interface of emelFM. It includes two ViewInfo objects, corresponding to the right and left panels, and numerous GtkWidget objects needed for the interface. Config: The Config data structure holds all the configuration information including filetypes, bookmarks, plugins, etc. When emelFM is started it creates a global App object called 'app' and a global Config object called 'cfg'. It then creates two pointers to ViewInfo objects called 'curr_view' and 'other_view'. At any given time 'curr_view' will point to the panel that currently has focus and 'other_view' will point to the other panel. Important functions: GList *get_selection(ViewInfo *view); This will return a GList of FileInfo objects coresponding to the files selected (or tagged) in the panel corresponding to view. For example if you called get_selection(curr_view) it would return the selected files in the active panel. There are numerous examples in the source of how to use the GList returned by this function.