            wxCmm version 0.1a Jul 2003


Overview
========

        wxCmm keeps the maximal compatibility with wxWindows, including
    the same classes and methods. The way of using them was also similar
    except necessary changes.

        This document will show you the difference between wxCmm and
    wxWindows. Since it is not a wxWindows tutorial, you may neede to
    read some documents for wxWindows in order to learn it.
    
        To use this library, You need Sphinx C-- Compiler 0.239c b8 or 
    above. 



Your First Program
==================

        "minimal.c--" is a minimal example using wxCmm:

        #pragma option w32
        #includepath "..\wxCmm"
        #include "wxCmm.h--"
        
        void main()
        {
            wxTheApp.onInit = #init;
            wxTheApp.mainLoop();
        }

        wxFrame frame;

        void init()
        {
            frame.wxFrame(NULL,-1,"A minimal wxCmm example");
            frame.Show(TRUE);
        }
    
        We will explain it in three parts:

    1. First, define the path of wxCmm and including "wxCmm.h--".

    2. Assign the initialization function in main() by passing the address
       #init to wxTheApp.onInit. Then wxTheApp.mainLoop() will activate 
       the message loop of Windows and the program is running.

    3. Build a basic frame in init() and show it.

        wxTheApp is a global wxApp object, and it is the only one. It has
        two major method, one is mainLoop() and gc() is another (we will
        see it later).

        A regular application at least needs one wxFrame object as a main
        window. Or you can use wxDialog object as a main window. You can
        see a example in "dialog2.c--".



Classes, Objects, and Methods
=============================

        All classes in wxCmm have constructors. Because the function in
    C-- could not be overridden, if a class has different constructors,
    different names will be used. For example, wxFrame() is the most
    common constructor for wxFrame. But if you want to pass more
    parameters, you can use wxFrameFullArgs(). You can find the detail
    in the following paragraphs (Naming Rules & List of Classes).

        Some classes have destructor and some have not, but you don't
    worry about it. The "delete" operator of C-- will automatically check
    it. All you need to do is delete something when they are not in use.
    The "delete" operator will also free the allocated memory, too.
        
        The objects in C-- can be generated in different ways: declare as
    global variable, local variable, or generated them by the "new" 
    operator. Different ways of generation make different ways of using 
    them.

        Global and local object are in similar manner. You can using the 
    "." operator to access the members. Take "minimal.c--" as an example:

        wxFrame frame;

        frame.wxFrame(NULL,-1,"A wxCmm example");
        frame.Show(TRUE);

        In this case, first line declare the variable frame as a global
    wxFrame object, but no constructor was called. So you must call it
    be yourself. At this time, the most common constructor wxFrame() was
    called, while you can also use wxFrameFullArgs() when more parameters
    are needed.

        You can delete the frame when it is useless. For global or local
    variable, the "delete" operator will calling the destructor (because
    no allocated memory need to be freed). And the result of calling the
    destructor of wxFrame is destroying them.

        Something special: local variables will be destroyed automatically
    when return in function. No more "delete" operator is needed. So some
    temporary objects, like wxPaintDC or so, declaring as local variables
    are quite suitable. But wxFrame object is usually not declared as local
    variable, or it will disappear when the function return!

        Objects generated by the "new" operator are quite different. When
    you generate an object this way, it returns an address of an object. 
    Because the compiler never know what object does this address point to,
    so you must adding the class name when access the member. Besides, when
    you "new" an object, the constructor of it is also called.
    As example:

        Object frame;
        frame = new wxFrame(0,-1,"A wxCmm example");
        ESI = frame;
        ESI.wxFrame.frame.Show(TRUE);

        The frame in this example is different from previous one. This
    frame is only a pointer to an object, not an object. It means, this
    frame is identical to previous #frame.

        Let's see the last two lines. In C-- grammar, to access an object
    by pointer, you must load this pointer to a register first, and then
    using this register as base to access other class members. And as noted
    before, class name must be assigned at the same time.

        When this object is useless, delete it in the same way. As the 
    reason referred before, class name must be added, too. Therefore,
    compiler knows what destructor will be called. And of course, the
    allocated memory will be freed. For example:

        delete frame wxFrame;

        There is something else to know:

    1. Constructor always returns the "this" pointer from ESI. So the second
       line in the above example: " ESI = frame; " can be omitted.

    2. Although all registers can be used as the base to access an object,
       EAX cannot be used. Using EBX or EDI is suggested. Because these two
       registers won't be changed in any methods, more than one method could
       be called at the same time. Such as:

       EBX = new wxSize(0,0);
       EBX.wxSize.SetWidth(10);
       EBX.wxSize.SetHeight(10);
        ...

    3. Alias of standard constructor can generate objects by the "new"
       operator, too. For example:

       frame = new wxFrameFullArgs(...);

       Since it still a wxFrame object, so delete it as this:

       delete frame wxFrame;




Garbage Collection
==================

        wxCmm has a easy-using garbage collection system. All you need
    to do is to invoke the method gc() in the wxTheApp object:
    
        wxTheApp.gc(); 
        
        In wxCmm, objects generated by the "new" operator can be separated
    into two types: One is discardable, and another is indiscardable. In
    default, objects are all indiscardable. If you don't delete them, they
    will exist forever. However, discardable objects do not need to be 
    deleted one by one. When wxTheApp.gc() is invoking, they will be clear 
    in the same time.

        The usage of these two types of objects is of the same manner. The
    only difference between them is the prefix of the constructor. The
    constructor of a discardable object has an uppercased prefix. 
    For example:

        new WxSize(0,0);
    
        It is convenient to use them as anonymous objects, such as:
        
        frame.SetBackgroundColor(new WxColor(0,0,0xFF));

        Sometimes the objects returned by methods are also discardable,
    and wxColor object returned by wxPen::GetColor() is an instance.




Event Mechanism
===============

        When writing Windows programs, it is difficult to handle event
    messages. wxCmm provides an easy way to do this: using the "connect"
    function to connect among the window, the event, and the event handler.

        There are two main types of the connect function. One of them is
    connect(), and you can use it to connect the objects of wxWindow and
    the event handlers. The other one is connectMenu(), which was used to 
    connect the menu events and the event handlers. For example:

        connect(#frame,wxEVT_RIGHT_DOWN,#onAbout);
        When a frame meets the wxEVT_RIGHT_DOWN event, calls onAbout();

        connectMenu(#frame,wxID_EXIT,#onExit);
        When an item's ID is wxID_EXIT and being selected, calls onExit();

        Here comes a example of event handler:

        void onAbout(dword event)
        {   
            wxMessageBox(#frame, "Hello", "HelloMsg", wxOK);
        }

        All event handlers will get a wxEvent object as its parameter. You 
    can get information about the message type and which object generates
    the message by this parameter. So multiple messages could use the same
    one handler. There are examples in "example1.c--".

        Attention! If a event was connected to two or more handler, they 
    will be invoked in the order when events are connected. But if a event
    with default action was connected, the default action will never be
    executed. For example, you can change the default context menu of
    wxTextCtrl this way, or make sure the wxDialog object will be closed 
    when right-upper corner X being pressed.

        There is another connect function: connectId(). You can use it to
    connect the IDs of control objects of a dialog. But this function could
    only connect the default actions, like button pressed or so. It usually
    used when dialog was defined in a .rc file, and all controls was
    generated by system itself.

        Of course, you can use other methods to get wxControl objects 
    referred to controls, then connect it with connect(). You can see
    "dialog3.c--" for detailed example.




Memory Allocating Functions
===========================

        There are three build-in memory allocating functions: Alloc(),
    ReAlloc(), and Free(). Here are their usages:

        dword Alloc(dword sizeOfByte);
        Returns an address when success. Returns NULL when failed.

        dword ReAlloc(dword addr,sizeOfByte);
        Returns a new address when success. Returns NULL when failed.

        dword Free(dword addr);
        Returns TRUE when success. Returns FALSE when failed.


        Free() is identical to the "delete" operator. You can use "delete"
    to free the allocated memory.




Naming Rules
============

        Almost all objects in wxCmm have the same names with wxWindows. But
    if it must be renames, following rules will be obeyed:

    1. The constructor with the same name of the class will has the most
       simple parameter list. If it was postfixed by FullArgs, more 
       parameters could be given.

       Ex: wxFrame(), wxFrameFullArgs()

       When FromResource was postfixed, data could be loaded from resources.
       Ex: wxDialog(), wxDialogFromResource()

       When Ref was postfixed, it means using ColorRef(RGB), not wxColor
       object.
       Ex: GetColor(), GetColorRef()
    
    2. When a method using wxSize or wxPoint, it was usually divided into
       two methods for the X-axis and the Y-axis.
       Ex: void  GetSize(dword wxSizeAddr)
           dword GetSizeX()
           dword GetSizeY()

    3. All colour in wxWindows will be color in wxCmm.



