programming

具有IDE功能的编辑器

Documentation on programming using the Coolwidgets library.

For documentation on macro programming Cooledit with the Python
scripting language, see the man page, cooledit(1).

(This document is ALPHA)


*******************************************************************************

Overview: What is the Coolwidgets library?
------------------------------------------

Coolwidgets was written for the X Window System in C as an easy to use, 
GPL'd highlevel API that runs in parrallel with XLib. It supports a
variety of basic widget types, like buttons, pull-down menus,
scrollbars, text display boxes, as well as many convience dialog boxes.
Its most promanent feature is a powerful generic text editor widget.
This widget can be draw with a single command and provides a ready to
use editor with undo, macros, and MSW/MAC highlight/movements keys. Drag
and drop is also supported: XDND version 2. The look and feel of the
library is somewhat like applications from other operating systems. 
Coolwidgets is artistically designed for a most pleasing 3D look. It is
been tested on a variety of unix platforms.

Coolwidgets supports only a single display. It can be used with minimal 
knowledge of XLib, although this knowledge is needed for extending the 
library.

The type of applications you may want to write using Coolwidgets would 
be text based applications that use a single font throughout, and also
applications that would benefit from an internal editor. For example,
mail and news readers. Porting of terminal applications using coolwidgets
is very easy. Other types of applications are not excluded however, since
there are no limitations on the kind of widgets you can create.

Other features:

- Coolwidgets does not require any libraries besides libX11
- single 256-byte structure for all widgets.
- internal AlarmEvent's can be recieved by the application for easy,
    continuous, real time handling of graphics.
- cooledit amalgamates expose events internally so that efficiant exposes
    are reported to graphics applications.
- full proportional font support on all widgets, including the text 
    box, and editor widgets.
- automatic generation of hotkeys for buttons.
- ready to use filebrowser with file filter and seperate directory 
    and file selection lists.
- automatic text history on all input lines.
- efficient redraw code for the editor and textbox's; draws text with
    an absolute minimum of server load - coolwidgets are fast.
- XDND version 2 drag and drop support, to and from input widget,
    editor widget, text box's, filebrowser.



*******************************************************************************

List of Supported Widgets
-------------------------

These are they:

- Text buttons
- Graphical buttons
- Single level pull down menus
- Scrollable text display box and selection boxes
- Scrollable text/selection box with columnated fields for tabulated
		list (think file list with |name|size|permissions|)
- Full screen text editor
- Radio buttons and check boxes
- Text input lines with histories
- Password input lines
- Number input lines
- Scrollbars
- Progress bars



*******************************************************************************

'Hello World' example program
-----------------------------

The best idea to see how the library works is to look at a trivial
application:

(This example appears in the examples directory)

--------------------cut-here---------------------------------------

/* hello.c - simple example usage of the coolwidget X API */
#include <coolwidget.h>

void main (int argc, char **argv)
{
    Window win;
    CInitData cooledit_startup;
    CEvent cwevent;
    int y;

/* intialise the library */
    memset (&cooledit_startup, 0, sizeof (cooledit_startup));
    cooledit_startup.name = argv[0];	/* won't bother with other init's like geom and display */
    cooledit_startup.font = "-*-helvetica-bold-r-*--14-*-*-*-p-*-iso8859-1";
    CInitialise (&cooledit_startup);

/* create main window */
    win = CDrawMainWindow ("hello", "Hello");

    CGetHintPos (0, &y);	/* y position where to start drawing */
    CDrawText ("hellotext", win, 0, y, " Hello World ");	/* the lable "hellotext" may be used to identify the widget later */
    CCentre ("hellotext");	/* we want the text centred from left to right */
    CGetHintPos (0, &y);	/* get the next y position below the last widget drawn */
    CDrawButton ("done", win, 0, y, AUTO_SIZE, " Done ");	/* draw a button... */
    CCentre ("done");		/* ...centred */
    CSetSizeHintPos ("hello");	/* set the window size to just fit the widgets */

    CFocus (CIdent ("done"));
/* show the window */
    CMapDialog ("hello");

/* Run the application. */
    do {
	CNextEvent (0, &cwevent);
	if (cwevent.type == QuitApplication)	/* pressed WM's "close" button */
	    break;
    } while (strcmp (cwevent.ident, "done"));

/* close connection to the X display */
    CShutdown ();
}

--------------------cut-here---------------------------------------



*******************************************************************************

A slightly more elaborate example program
-----------------------------------------

The file editor/smalledit.c contains a more comprehensive example. See 
this file to find out how a powerful text editor is created in just 
under 400 lines.



*******************************************************************************

Is it easy to create my own application, ready for distribution?
----------------------------------------------------------------

Probably the easiest way to create your own application is to just 
copy the entire cooledit distribution, and replace the editor directory 
with your own directory. If you are going to distribute this package as 
freeware, you may want to leave the examples and doc directory intact for 
other programmers. Replace files like NEWS, README, cooledit.1 etc. 
Don't delete the NEWS and README files, however - they are required by 
automake - rather just empty them if you aren't going to use them.

You should then get hold of  automake  and  autoconf. Then edit the 
Makefile.am files and to correspond to your own filelists. You may need 
to incorporate new macros into configure.in. If you are porting an 
existing application, just merge the two configure.in files.

Set
    $cmdline_use_dependencies = 0;
in the automake executable (i.e. /usr/local/bin/automake on my system).

Then just run remake. The autmake Makefile files take care of just about 
everything. See the  autoconf  documentation for more information. If 
you are going to rebuild manually
    automake
    autoheader
    autoconf
will redo everything.

This way, the Coolwidget library will be included in your distribution,
and people won't have to go fetch it. When coolwidget grows, I will 
release a dynamically linked version, and you will then include the
'widget' directory at your own discretion.



*******************************************************************************

Basics: programming with Coolwidgets
------------------------------------

There are a few things you need to know before you jump right in and 
start programming.

A 'widget' in this library is a graphic item like a scrollbar or button.
Each widget type is called a 'kind' and is one of those ennumerated in 
coolwidget.h (eg C_TEXTBOX_WIDGET). Even a dialog box window is a 'widget'
with other widgets drawn over it. Each widget has a parent window, and a
window of its own. Each widget exists by virtue of a structure of type
CWidget. The CWidget structures are allocated internally by the library
and are stored in a global array that can be hold a maximum of 1024 widgets.
There is only one such structure (CWidget) which is presently 248 bytes long.
This structure has members for the data of all the different widgets.
This may seem inefficent, since a button uses hardly any of the structure,
but considering that 100 widgets would be only 25kB, it is not an
appreciable ineffiency. Where a lot of memory is needed (like the editor
widget - which needs a more involved structure), there are hooks to point
to specific structures.

Each widget is given a unique text identifier string. You must ensure 
that no two widgets have the same string and that the strings are than
32 characters long. You can use these strings to identify the widget
after creating it, without having to declare global variables. The library 
uses these strings to remember things about the widget (such as input 
histories of the input line widget). Most procedures which operate on 
widgets take as an argument either the widget's identifier string, or a
pointer to the widget's structure, depending on the typical context of
the procedure.

Functions and macros are provided to convert between the following three
things:
    - The widget's character string identifier
	    (usually declared as 'char *ident')
    - A pointer to the widget's CWidget structure
	    (usually declared as 'CWidget *w' or 'CWidget *wdt')
    - The widgets window
	    (usually declared as 'Window win')



These functions are:

Window CWindowOf (CWidget * w);
char *CIdentOf (CWidget * w);
Window CWindowOfWidget (const char *ident);
CWidget *CWidgetOfWindow (Window win);
CWidget *CIdent (const char *ident);

If a widget matching the specified string identifier is not found,
a NULL value is returned, which means a widget with that name is
not in existance.



*******************************************************************************

Function naming conventions:
----------------------------

A more-or-less consistant naming scheme has been adopted through-out
the library. All functions that create widgets are called CDrawSomething().
All common library functions are named using the Xlib function naming
standard, but with a C (for Coolwidgets) instead of an X. Functions
internal to the library are named using the GNU standard
i.e. some_function(), not SomeFunction(). Low level library functions
(they are acceptable to use, but are likely to be used less often), are
also named with the GNU standard. You should use GNU naming for your
own programs, and X naming for extending the library. Numeric #define's
are named like SCOPE_SOME_NUMERIC_DEFINE, where 'SCOPE' is the widget
or thing that it applies to.

I havn't stuck to all these rules with absolute rigidity.



*******************************************************************************

Initialising, running and exiting the library:
----------------------------------------------

To intialise the library, just create a structure of type CInitData, fill 
in the fields you like (zero for don't-cares) and call CInitialise with