

                                  TWS
                              Readme File


                              Release 4.0


                 What's new and changed for this release
                        Registration information



---------------------------------------------------------------------------
WHAT'S NEW
---------------------------------------------------------------------------
This release of TWS adds some interesting new functionality, as well as
expanding on some existing functions and fixing some bugs. A summary of
modifications and additions from the previous release:

    *   Added alternate visual styles for the checkbox gadget (radio
        buttons). The new styles are 'button' (looks like a pushbutton,
        but doesn't spring back), and 'round' (button is round instead
        of square).

    *   New Gadgets:

        Scroll bar
        Pixmaps (rewritten and expanded for this version)
        RotateList

    *   New functions:

        SM_GetCheckboxType
        SM_SetCheckboxType
        SM_AttachGadget
        SM_CreateScrollbar
        SM_PtDeviceToContent
        SM_PtContentToCanvas
        SM_PtDeviceToCanvas
        SM_PtCanvasToDevice
        SM_PtContentToDevice
        SM_SetButtonRect
        SM_CreateScrollbar
        SM_DestroyScrollbar
        SM_GetScrollbarPosition
        SM_GetScrollbarMax
        SM_GetScrollbarMin
        SM_GetScrollbarData
        SM_GetScrollbarScale
        SM_SetScrollbarPosition
        SM_SetScrollbarMinMax
        SM_SetScrollbarRect
        SM_SetScrollbarData
        SM_SetScrollbarScale
        SM_GetMouse
        SM_CreatePixmap
        SM_SetPixmapPixel
        SM_GetPixmapPixel
        SM_WritePixmap
        SM_ReadPixmap
        SM_MovePixmap
        SM_PointInRect
        SM_CreateGraphState
        SM_CreateIcon
        SM_StringWidth
        GR_SetBlocking
        GR_UnsetBlocking
        SM_GetStringlistSelectString
        SM_SetStringlistList
        SM_RefreshGadgets
        SM_GetLabelData
        SM_SetLabelSculptType
        SM_GetDefaultBevelDepth
        SM_IsColorEqual
        SM_CopyPixmap
        SM_SetPixmapBlocking
        SM_SetGainFocusProc
        SM_SetLoseFocusProc
        SM_LoadSystemFont
        GR_ImageSize
        GR_GetImage
        GR_PutImage
        GR_SetLineStyle
        SM_SetEditstringGroup
        SM_GetEditstringGroup
        SM_GetTextFont
        SM_CreatePanel
        SM_IsMinimized
        SM_SetStringlistSelection
        SM_SaveAsPCX
        SM_SaveWindowAsPCX
        SM_SaveScreenAsPCX
        SM_SaveAsPostscript

    *   New constants

        Name              Value     Defined in
------------------------------------------------------------
        SMCBOXBUTTON        1       smchkbx.h
        SMCBOXOVAL          2       smchkbx.h
        PIXMAP              17      smtypes.h
        NOEVENTS            0x0000  smevent.h
        GRNOBORDER          0       smgraph.h
        GRLINEBORDER        1       smgraph.h
        GRRAISEDBORDER      2       smgraph.h
        GRRECESSBORDER      3       smgraph.h
        ICONONLY            8       smtypes.h
        SMPIXMAPID          0xabcd  smpixmap.h
        SMPMNOFILE          1       smpixmap.h
        SMPMBADTYPE         2       smpixmap.h
        TXTNORMAL           0       smwindow.h
        TXTBOLD             1       smwindow.h
        TXTITALIC           2       smwindow.h
        TXTUNDERLINE        4       smwindow.h
        TXTSTRIKEOUT        8       smwindow.h
        TXTPROPORTIONAL   128       smwindow.h
        CANVAS_REGION      18       smtypes.h
        APP_TITLE_REGION   19       smtypes.h
        SMMEDIUMGRAY        5       smcolor.h

    *   Icons.  The window minimize buttons now work if the window has
        an icon attached to it.  The icon is created and attached using
        the new SM_CreateIcon() function.  Icons can have pixmaps
        (images) attached to them and can be moved about within the
        Workspace region.

    *   A new demo/utility program, Iconedit, for creating, editing and
        storing TWS pixmaps suitable for icons.  Drawing is in a
        "fatbit"-style window. Line, box, circle geometric shapes and
        undo.  Source code included!

    *   If the parent window argument to SM_AddGadget() is NULL, the
        gadget will be allocated and initialized but not attached to any
        window. A pointer to the new gadget is returned. The gadget can
        later be attached to a window using SM_AttachGadget().

    *   A new gadget field, nofree, prevents a gadget from being freed
        when its parent window is closed. This field is accessed via the
        SM_SetGadgetNofree() function. It can be used to create
        "persistent" gadgets that can be reused and is related to the new
        functionality above.

    *   The Editstring Gadget:

        *   now has a user data field of type (void *) and a user
            callback function. The callback function is unique because
            its arguments are a pointer to the editstring gadget, AND a
            pointer to the event that was passed to the gadget. The
            editstring user callback function is called on every event
            (both keystroke and mouse events) for the editstring, before
            the editstring shell function processes the event. You can
            use this callback function to modify the characters (such as
            forcing all letters to uppercase) or provide other
            processing (such as a keyclick -- see with WINTEST7 demo
            program).  This should make it relatively easy to build
            validated data entry routines;

        *   now remains active if the cursor is clicked outside the
            editstring boundary (unless the cursor is clicked on a
            different editstring -- see the note about "groups" below).
            Before, clicking outside the editstring deselected it. The
            new behaviour is more flexible because you can type to enter
            text into the string, and click on buttons outside the
            string, resume typing, etc. Pressing ENTER still deactivates
            the string;

        *   can accept strings longer than the bounding rectangle.
            Entering text beyond the right edge of the bound cause the
            string to scroll.  The arrow keys, home, end, and backspace
            keys also scroll the string as necessary;

        *   recognizes the DEL key;

        *   now can be set into "groups" for easy toggling between
            active editstrings.  With a group of editstrings, selecting
            among them can be done using the mouse or using the TAB key.
            There is no particular geometry associated with groups, much
            the same as there is none with checkboxes.  The syntax for
            editstring groups is different than checkboxes, however.

    *   You can now apply a border to the graphics canvas. The border
        can be a single line, or a recessed or raised sculpt. You can
        also leave the canvas unbordered. If a bordered canvas is larger
        than the window's content region, then obviously the border
        won't be visible. The function GR_SetCanvasBorder() changes the
        graphics canvas border state.  If the canvas is bordered, the
        area within the canvas available for drawing is reduced by the
        border width.  The function GR_GetCanvasWidth() and
        GR_GetCanvasDepth() return the size of the drawable canvas
        region (not including the border).

    *   The window system no longer creates a default graphics state
        when a window is created.  If an application expects to draw in
        a window it must explicitly allocate a graphics state first.
        This includes using window color tables and canvas save-unders.
        The function GR_CreateGraphState() creates a graphics state for
        a window.

    *   The Stringlist Gadget

        *   Now includes optional scrolling.  A new parameter to the
            SM_CreateStringlist function, scrollflag, controls whether a
            slider will be attached to a Stringlist. If scrollflag is
            True the slider lets the user scroll through the list if
            it's longer than the gadget rectangle. If the list fits in
            the rectangle then the slider will still be displayed but
            does nothing.  The scrollbar is drawn inside the rectangle
            specified for the Stringlist itself, reducing the space
            available for string display.  The width of the slider is
            the same as the title bar depth (use the function
            SM_GetDefaultTitlebarDepth() to get the title bar depth
            value). The application should take this into account when
            creating scrollable stringlists.

        *   A user data field has been added.  A new void * parameter
            has been added to the SM_CreateStringlist function.  This
            makes the Stringlist gadget more "symmetrical" with other
            TWS gadgets.

        *   Can contain multiple columns of strings.  A new parameter
            when the stringlist is created determines the number of
            columns the strings will be displayed in.  The list of
            strings is still passed as a single list -- the system
            breaks the list up as necessary.  If a stringlist is
            specified with 1 column it behaves just as before.  For 2 or
            more columns, a horizontal slider is added to the bottom of
            the string boundary rectangle for scrolling the columns
            sideways within the rectangle.  The system decides how many
            strings will be in each column, and how many columns will
            fit inside the specified rectangle, and creates sliders
            accordingly.

    *   New configuration file options:

        BevelDepth      Controls the degree of "sculpting" for the 3D
                        portions of the user interface.  If not
                        specified in the configuration file, or if set
                        to 0 or less, the default is 1 pixel of
                        sculpting for resolutions up to 800x600, and 2
                        pixels for higher resolutions.

                        BevelDepth controls just about all window and
                        gadget regions -- window borders and title bar,
                        menu bar, buttons, checkboxes, menu
                        highlighting, etc. Multi-pixel bevels are always
                        drawn inside the interface region.  Window title
                        bars and menu bars automatically take into
                        account the bevel depth when they're created,
                        but you'll have to be aware of it when creating
                        buttons, etc. in your application programs.
                        Previous versions of TWS always used 1 pixel of
                        sculpting.


        FocusColor      Sets the color for focus window border, titlebar
                        and menu bar, and for gadgets that use the focus
                        color (like selected radio buttons).  Specified
                        as three integer values R G B, each value in the
                        range 0..255. Setting the focus color overrides
                        the window ColorScheme color.

        TitleColor      Sets the color for window and application
                        titles. Specified as three integer values R G B,
                        each value in the range 0..255.  Setting the
                        title color overrides the ColorScheme title
                        color.

        WindowLimits    Controls whether or not the window manager will
                        allow windows to be created that extend off the
                        edges of the screen.  In previous versions, if
                        the application requested a window that would
                        have extended off the edge of the physical
                        screen, TWS automatically reduced the window so
                        that it would fit.  The WindowLimits
                        configuration option controls this.  Possible
                        values are ON or OFF; default is ON.

    *   A new window style, SIMPLE, is a basic sculpted rectangle
        without any title bar.  Used by the new message dialogs.

    *   The SM_GetMouse function now returns False if the cursor moves
        outside of the window, as well as if no buttons are pressed. In
        either case, the (x,y) coordinates returned are relative to the
        argument window content region.

    *   Graphics drawing speed can be improved using the new blocking
        functions.  Usually when a graphics function is called, the
        system sets the drawing color, line style, drawing mode,
        clipping region, etc., for each call.  With blocking enabled,
        however, these things are set once, and the system then assumes
        that nothing has changed since blocking was set.  This results
        in 2X or more speedup for long, complex drawing tasks.

    *   New standard dialogs: I've included some new standard "dialog"
        convenience functions.  These include:

            SM_Picklist         Select a string from a list of strings
                                with scrolling, cancelling, editing;

            SM_GetFilename      Choose a filename from a display of
                                filenames and subdirectories.  Search
                                directories by selecting from the
                                subdirectory list.

            SM_YesNoDialog      Displays a message provided by the
                                application along with OK and Cancel
                                buttons.

            SM_YesNoCancelDialog    Like the YesNoDialog except there
                                are three buttons; Yes, No, and Cancel.

        Message dialogs (SM_YesNoDialog, etc.) accept a message string
        and return fixed values based on the reply button pressed by the
        user. The dialog window is drawn in a fixed screen location
        (approximately the center).  The window size is adjusted to fit
        the message string, and the message string is word-wrapped as
        necessary to fit into the dialog window.  The labels for the
        buttons are also supplied by the application.

    *   New more distinctive visual styles for pressed buttons, slider
        channels, etc.

    *   You can now specify a number of border decoration styles for
        labels, including raised or recessed beveled, chiseled, and
        solid line.

    *   The system now notices if an input event occurred in a window's
        graphics canvas region.  The event's region field value will be
        CANVAS_REGION.

    *   The Textbox gadget now accepts a wordwrap parameter.  If True,
        the gadget will wrap lines wider than the gadget boundary.  Also
        the Textbox gadget is much faster and more memory-efficient than
        previously.

    *   Windows now include event callback functions for window get focus
        and lose focus events.

    *   A new workspace window feature called "Panels".  A panel is a
        type of window that is independent of the window stack.  The
        panel is at the same level as the workspace window and "tiles"
        it in a particular way.  The content region of the workspace is
        reduced by the panel size, so no application window can ever
        obscure a panel.  This makes panels useful for program status
        displays, clocks, etc.

    *   Line styles for graphics : solid (default), dashed, or dot lines.

    *   Graphics "image" routines (capture an image from a graphics canvas).

    *   Event handler hook to the printscreen key.  Pressing Ctrl-PrtScr
        causes the system to call an application function with
        pre-defined window, screen rectangle and character string
        arguments.  Typically the event callback function would use the
        string as a file name, and the rectangle and/or window as the
        region of the screen to be dumped.  There are also new utility
        routines in the TWS library for writing PCX and PostScript
        files.

    *   Bugs fixed:

        *   The SM_GetPoint() function returned the wrong color. It now
            expects the x,y coordinate passed in to already be in window
            graphics canvas coordinates. (Before it expected to get
            device coordinates).

        *   Menus weren't allowed in a DIALOG-style window. Originally,
            DIALOG windows were going to be restricted to simple message
            panels. Over time they've evolved until the only difference
            between a standard DOCUMENT-style window and a DIALOG window
            is that the DOCUMENT window can be resized.

        *   Rich McCoy of Total Control Engineering noticed that it was
            possible to drag a window "inside-out" while resizing it,
            after which there would be no way to recover the window.
            DOCUMENT-style windows now have a default minimum size which
            should prevent this.

        *   Mssr. McCoy also discovered that if you continue to drag the
            mouse after a slider has reached its boundary, you can
            eventually crash the system.  I haven't been able to
            reproduce this.

        *   Pixmaps would hang the system on certain video hardware and
            modes. Pixmaps have been completely rewritten for this
            release.

        *   The function SM_GetMouse() didn't work as advertised.

        *   The SM_CreateEditstring function took the gadget's bounding
            box as the fourth argument, instead of the second argument
            like all other TWS gadgets.  Though this isn't exactly a
            bug, I changed the function to be consistent with the
            others.  You will have to change calls in existing code.
            Sorry for the inconvenience.

        *   The function SM_SetEditstringString didn't work properly.
            Specifically, when I changed the editstring to copy the user
            string instead of just include it, I didn't change this
            function accordingly.

        *   Gadgets that were COMPLETELY outside a window were not
            always clipped to the window content.

        *   Some of the graphics routines didn't restore the correct
            system clipping area after they were done.

        *   If a position in a stringlist beyond the last string item
            was selected, the display could be corrupted and potentially
            garbage results returned.

        *   Also, if no string in a stringlist was selected (clicking on
            a selected string results in this condition), then calling
            SM_GetStringlistString() would return a bogus result.

        *   Also, an invalid start value (ie., less than 0) to the
            SM_CreateStringlist() function would result in a bogus
            display and crash the system on exit. This is now checked.

        *   The Textbox gadget has been rewritten.  Although it worked
            OK before it was quite slower and less memory efficient than
            it could have been.  Also see the new word wrap option
            described above.

        *   The system didn't notice when a window pull-down menu was
            off the screen. Now if a menu would grow below the bottom of
            the screen, the system will pop the menu up instead of down.
            If the menu extends off the right edge of the screen the
            system will move it to the left so that the entire menu is
            on-screen.

        *   In some cases a window title wouldn't draw in the correct
            color.

        *   The border for a Label gadget, when enabled, was drawn a few
            pixels outside the boundary rectangle specified by the
            application. This was thought to be confusing and not
            consistent with the other gadgets. Now the Label border is
            drawn inside the specified rectangle.

        *   A NULL string in a label would display as garbage.

        *   The graphics state for a SM_GadgetToWindow() window was not
            freed when the window was freed using SM_FreeWindow().

        *   Closing a non-focus window now works properly.

        *   An interface function to retrieve the text font was missing.

        *   Setting an application menu using SM_SetApplicationMenu()
            caused the workspace content to be resized inappropriately.

        *   Although the application can supply a procedure to be called
            whenever a window is closed, the return value from the procedure
            was ignored.  Now if the window close event application
            procedure returns a non-zero value, the window will NOT be
            closed and the value will be returned through the event
            loop.

        *   In some situations the BACKING attribute for the graphics
            canvas was not handled properly.

        *   In some situations the slider would not position all the way
            to the top or all the way to the bottom of its range.

        *   The background procedure handler would sometimes fail to
            correctly evaluate the logic for calling a background
            procedure.  The result was some background procedures
            failing to be called.

---------------------------------------------------------------------------
REGISTERING
---------------------------------------------------------------------------
The TWS graphics user interface library is distributed as shareware.  As
you know, shareware is a distribution method that allows interested
users to try a program before paying for it. If you continue to use the
program beyond the 30-day trial period you accept the obligation to pay
for it.

Unless you received your copy of TWS directly from me, you do not have a
registered copy. Here's how to register:

Send your name, address, phone number and e-mail addresses to:

    TWS
    PO Box 37464
    Albuquerque, NM  87176

Make a note of the version of TWS you are registering (this is release
4.0) and the compiler and graphics library you prefer.  Include a check
or money order for $79 payable to TWS.

On registering you'll be sent a package including the latest library
release for your compiler and graphics library, printed documentation
including tutorials, about 6,000 lines of examples and demo code, and
back issues of the TWSView newsletter.

In addition, I'm changing the policy on incremental releases.  In the
past I have not released "fractional" versions (like 3.1, 3.2, etc.).
Instead I've accumulated bug fixes and new functions into the major new
releases.

Beginning with this release, however, code with incremental improvements
like bug fixes and enhancements to existing functions will be available
*at no charge* to registered developers.  New major versions will
introduce new functionality (i.e., new gadgets) and will require
existing users to purchase upgrades (at special prices, of course).

Incremental versions will NOT be posted to BBS systems and are available
to registered developers only.

---------------------------------------------------------------------------
SOURCE CODE
---------------------------------------------------------------------------
The complete source code to the TWS Window System is available.
Registration is $159 and requires execution of a special non-disclosure
license agreement. Registered release 4.0 developers can request source
code by paying the difference between registration price and source code
price ($80).  Source code registration includes source code for all
compiler and graphic library versions of TWS.  Write for details.

---------------------------------------------------------------------------
TECH SUPPORT
---------------------------------------------------------------------------
Currently I provide two types of developer support:

    e-mail to CompuServe account 71160,2426;
    TWS newsletter, distributed 'occassionaly'

I'm sorry but I can only reply to technical questions from registered
developers.

I'm currently looking for a BBS on which I can provide support to those
of you without CompuServe accounts (if you run such a board please
contact me). I'm also looking into FAX service. Announcements of these
will be distributed in the newsletter.


----------------------------------------------------------------------------
THANKS
----------------------------------------------------------------------------
Whether or not you decide to register and use TWS, thanks for going to
the trouble to check it out.



Dean Clark
CIS 71160,2426
