programming

具有IDE功能的编辑器

a pointer to the structure.

Before quiting execute the CShutdown() procedure.

These two function are the start and end of any Coolwidget application. 
The main loop of the application must contain the line
    CNextEvent(...);
This function is the core of the library. It responds to X events, 
handles callbacks, translates various low level events to higher level
events and so on. It returns the low level event XEvent structure, and 
a higher level CEvent structure which is simpler to interpret.

If you don't know how X works just remember that everything that comes 
through your mouse and keyboard is returned by this function. If no 
events are available, it will wait for one.



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

Commandline options:
--------------------

The library has a very nice function to process command-line options of
the form
    my_prog [-aAbBcC] [-long_a] [-long_b] ... [--some-option <argument>] 
	<filename1> <filename2> ... etc. etc.
in any order. In other words, almost any kind of command line syntax 
seen today.

Use it as follows: (see widget/cmdlineopt.h for full specs)

First declare all the options you would like:

/* anything on the command-line that is not part of an option goes into here */
char *command_line_files[] =
{0, 0, 0, 0, 0, 0, 0, 0,
 0, 0, 0, 0, 0, 0, 0, 0,
 0, 0, 0, 0, 0, 0, 0, 0,
 0, 0, 0, 0, 0, 0, 0, 0,
 0, 0, 0, 0, 0, 0, 0, 0,
 0, 0, 0, 0, 0, 0, 0, 0,
 0, 0, 0, 0, 0, 0, 0, 0,
 0, 0, 0, 0, 0, 0, 0, 0};

/* you can specify defaults here: */
char *option_background_color = 0;
char *option_foreground_red = 0;
char *option_foreground_green = 0;
char *option_foreground_blue = 0;
char *option_font = "-*-helvetica-bold-r-*--14-*-*-*-p-*-iso8859-1",
int get_help = 0;
int get_version = 0;
int option_verbose = 0;
char *option_display = 0;
char *option_geometry = 0;

struct prog_options cooledit_options[] =
{
    {' ', "", "", ARG_STRINGS, 0, command_line_files, 0},
    {0, "-bg", "--background-color", ARG_STRING, &option_background_color, 0, 0},
    {'R', "", "--foreground-red", ARG_STRING, &option_foreground_red, 0, 0},
    {'G', "", "--foreground-green", ARG_STRING, &option_foreground_green, 0, 0},
    {'B', "", "--foreground-blue", ARG_STRING, &option_foreground_blue, 0, 0},
    {'f', "-fn", "-font", ARG_STRING, &option_font, 0, 0},
    {'h', "-?", "--help", ARG_SET, 0, 0, &get_help},
    {'H', "-help", "--help", ARG_SET, 0, 0, &get_help},
    {'V', "-v", "--version", ARG_SET, 0, 0, &get_version},
    {0, "", "-verbose", ARG_SET, 0, 0, &option_verbose},
    {'d', "", "-display", ARG_STRING, &option_display, 0, 0},
    {'g', "-geom", "-geometry", ARG_STRING, &option_geometry, 0, 0},
    {0, 0, 0, 0, 0, 0, 0}
};

void process_command_line (int argc, char **argv)
{
    int error;
    error = get_cmdline_options (argc, argv, cooledit_options);

    if (error) {
	fprintf (stderr, "%s: error processing commandline argument %d\n", argv[0], error);
	usage ();
	exit (1);
    }
    if (get_help)
	usage ();
    if (get_version)
	version ();
    if (get_help || get_version)
	exit (0);
}



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

String utility functions:
-------------------------

The most inportant of these is the catstrs function:

char *catstrs (const char *first,...);

eg.
    a = catstrs ("hello", " ", "there", "!", 0);
returns a as
    "hello there!"

Note: The last arg must always be 0. The result of this function must
*NEVER* be free'd. It automatically free's strings older than 64 calls
to catstrs.

Do *NOT* use the catstrs function inside a loop, because it only stores 
the last 64 results. Hence also do not use it for strings you need to 
keep for a long time (use a = strdup(catstrs(...)); ...; free(a); 
instead).

Other utility functions are:

(see stringtools.c for a more detailed explanation of what these do.)

/* case insensitive strchr */
char *strcasechr (const char *p, int c);
/* returns "-1234" from i = -1234, use result before next call and do not free result */
char *itoa (int i);
/* result must not be free'd */
char *get_current_wd (char *buffer, int size);
/* returns 0 on success */
int change_directory (const char *path);
/* use result before next call and do not free result */
char *name_trunc (const char *txt, int trunc_len);
/* does tilde expansion. result must be free'd, CInitialise() must be called before use */
char *canonicalize_pathname (const char *given_path);
/* strlen, but not more than count */
size_t strnlen (const char *s, size_t count);
/* returns the size of a printf string WITHOUT printing it! */
size_t vfmtlen (const char *fmt, va_list ap);
/* sprintf and allocate in one go, result must be free'd */
char *vsprintf_alloc (const char *fmt, va_list ap);
char *sprintf_alloc (const char *fmt,...);

/* Also: these are set by CInitialise */
/* current directory */
extern char *current_directory;
/* home directory */
extern char *home_directory;

For writing to a dynamically expanding memory pool, use the 'pool' 
functions of pool.h. See dirtools.h for an example.



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

Compatability and utilities for different Unix's:
-------------------------------------------------

All these are supported, no need to include string.h:

void *memset (void *dest, int c, size_t n);
void *memchr (const void *s, int c, size_t n);
int memcmp (const void *m1, const void *m2, size_t n);
char *strstr (const char *s1, const char *s2);
size_t strspn (const char *s, const char *accept);
void *memmove (void *dest, const void *src, size_t n);
int strcasecmp (const char *p1, const char *p2);
int strncasecmp (const char *p1, const char *p2, size_t n);
char *strdup (const char *s);
int vsprintf (char *str, const char *fmt, va_list ap);



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

Drawing Widgets and Dialogs
---------------------------


This gets down to the nuts and bolts.
(see the example dialog just below this text. Also run cooledit and 
look at the dialogs to get an idea of what is actually happening)

Each widget has a function of like:
CDraw... (const char *ident, Window parent, int x, int y, ...);

You will have to see the header file coolwidget.h to see the specs, 
but here I will show you the basics.

Now window creation (and each widget has a one) requires two steps 
under X (an extra step if you are creating main windows that the window 
manager has to be aware of). Coolwidgets simplifies this procedure 
considerably:

step 1: create the window (the window exists, can be drawn to, but is 
	not shown).
step 2: set the windows attributes (main windows)
step 3: map the window (show the window)

For all widgets except window widgets, these steps are done 
automatically with a single command: CDraw...()

You can call a CDraw...() function to create a widget. The widget 
window will be mapped, and the widget will appear as soon as you start 
calling CNextEvent() (CNextEvent() 'runs' the library). (This is
provided the parent window is mapped, if it is not mapped, then the
widget will only appear once you map the parent window).

For dialog widgets, the procedure is slightly different. Typically, you 
would want to draw other widgets into a dialog widget.
This means that you don't know how big the dialog is until you have drawn 
its children widgets. Hence we draw the dialog, THEN draw its children, 
THEN set the size of the dialog, and THEN map the dialog.
The command for drawing a window widget is
    Window CDrawDialog (const char *identifier, Window parent, int x, int y);
which will create the widget, but will not map it. Then we draw widgets 
into the dialog; and then we call
    CSetSizeHintPos (char *ident_of_dialog);
to set the dialog to its proper size. Finally, we call
    CMapDialog (char *ident_of_dialog);
before running the dialog.

Here is a typical example:
This draws a dialog to enter the 'Subject:', 'Cc:' and 'To:' fields of a
mail message. A lot of this code is explained later on, just note the
general procedure. (This is very similar to the actual code used in 
cooledit.)


extern void pipe_mail (char *to, char *subject, char *cc);

void mail_subject_to_cc_dialog (Window in, int x, int y)
{
    Window win;
    CEvent cwevent;
    CState s;
    int y2;

    CBackupState (&s);
    CDisable ("*");

/*
   Draw the dialog and record the returned window,
   we need win as an argument to draw children widgets.
 */
    win = CDrawHeadedDialog ("mail", in, x, y, " Send Mail ");
    CGetHintPos (&x, &y);
    y2 = y;

    (CDrawText ("mail.tto", win, x, y, "To: "))->hotkey = 'T';
    CGetHintPos (0, &y);
    (CDrawTextInput ("mail.to", win, x, y, (FONT_MEAN_WIDTH) * 50, AUTO_HEIGHT, 1024, CLastInput ("mail.to")))->hotkey = 'T';
    CGetHintPos (0, &y);

    (CDrawText ("mail.tsubject", win, x, y, "Subject: "))->hotkey = 'S';
    CGetHintPos (0, &y);
    (CDrawTextInput ("mail.subject", win, x, y, (FONT_MEAN_WIDTH) * 50, AUTO_HEIGHT, 1024, CLastInput ("mail.subject")))->hotkey = 'S';
    CGetHintPos (0, &y);

    (CDrawText ("mail.tcc", win, x, y, "Copies to: "))->hotkey = 'C';
    CGetHintPos (0, &y);
    (CDrawTextInput ("mail.cc", win, x, y, (FONT_MEAN_WIDTH) * 50, AUTO_HEIGHT, 1024, CLastInput ("mail.cc")))->hotkey = 'C';
    CGetHintPos (0, &y);

    get_hint_limits (&x, 0);
    CDrawPixmapButton ("mail.send", win, x, y2, PIXMAP_BUTTON_TICK);
    CGetHintPos (0, &y2);
    CDrawPixmapButton ("mail.cancel", win, x, y2, PIXMAP_BUTTON_CROSS);

    (CIdent ("mail"))->position = WINDOW_ALWAYS_RAISED;

/* Set the size of the dialog to exactly fit all the widgets */
    CSetSizeHintPos ("mail");