23. Sharing Our Library

[LarryMc]

We've finished our control and are eager to share it with the rest of the world.  We know how to use it and how it works. Problem is the rest of the world doesn't know how it works.  And we can't assume they know how to use it.

The first thing we need to address is how it works.  This is the hard part.  After spending so much time working on the control's creation we know every little detail about how it works.  We now have to switch gears and generate some form of 'help' for potential users.  It needs to be written as if the user has never dreamed of such a control.

Help should include a license (to tell the user what they can and can't do with your offering); a list of the functions available to the user; a description of what each of the passed parameters are for; and an example of the proper use of each function.

For a simple control, such as our gage, the 'help' can be simple.  For the original gage we included the help inside the demo program (shown below).

Code Select Expand

/**********************************************************************************************
* GageRLM2_example.eba
* Round Gage Control Library V2.0
* Copyright (c)T.L. McCaughn 2008 All Rights Reserved
*
***********************************************************************************************
License:
Copyright (c) 2008 T. L. McCaughn.  All Rights Reserved.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to
compile into their commercial, personal and educational applications.

Redistribution of the Software is limited to your own development team and/or
immediate family and it cannot be made publicly available or distributable as
a stand alone product or part of any library collection or similar product,
even if that offering is free, without the expressed written permission of the
author.

Ionic Wind Software is hereby granted a royalty free license to distribute
the Software for free via its forum or by packaging it with other software,
even if the other software is not free, provided the warranty disclaimer is
included with any distribution.
-------------------------------------------------------------------------------------------
Disclaimer:
THIS SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESSED OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT.  IN NO EVENT SHALL THE
AUTHOR OR COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE. THE AUTHOR NEITHER PROMISES NOR IMPLIES THAT THIS SOFTWARE WILL
BE MAINTAINED, FIXED, REPAIRED, OR IMPROVED.  THE USER ASSUMES ALL RISK OF USING
THE SOFTWARE AND ACKNOWLEDGES SUCH BY LINKING THE SOFTWARE INTO ANY APPLICATION.
==========================================================================================
FUNCTIONS:
----------------------------------------------------------------------------------------
AddGageRLM(win as WINDOW,l as string, t as INT, d as INT, id as UINT )
Purpose: To add a round gage control to an existing window
Where:
win - parent window
l - left edge of rect enclosing gage
t - top edge of rect enclosing gage
d - diameter of gage
id - control id


ConfigGageRLM(win as WINDOW,style as int, title as string,u as INT,rmin as int,rmax as int,dmin as int,dmax as int,sf as int, id as UINT )
Purpose: To add a round gage control to an existing window
Where:
win - parent window
style - gage style *
title - gage title *
u - gage measurement units *
rmin - min raw value range of control *
rmax - max raw value range of control *
dmin - min dial value range of control *
dmax - max dial value range of control *
sf - scale factor(multiplier) used with dial value *
id - control id

* NOTES:

style: ROUND270B - Dial is approx 270 degree arc w/single pointer; gap@bottom
(new) ROUND270T - Dial is approx 270 degree arc w/single pointer; gap@top
(new) ROUND270L - Dial is approx 270 degree arc w/single pointer; gap@left
(new) ROUND270R - Dial is approx 270 degree arc w/single pointer; gap@right
ROUND360SGL - Dial is 360 degree w/single pointer
ROUND360DBL - Dial is 360 degree w/two pointers
ROUNDCLOCK12 - Dial is 12 hour clock w/ hour/minute/second pointers
ROUNDCLOCK24 - Dial is 24 hour clock w/ hour/minute/second pointers
(new) ROUND2PENV - Dial has 2 Scales/pointers - scale is vertical
(new) ROUND2PENH - Dial has 2 Scales/pointers - scale is horizonal

title: Displayed above the center of dial on all gages.
On ROUND2PENV/H gages title is display on each half of dial face preceeded
by #1 (top or left scale) or #2 (bottom or right scale)

u: Displayed below the center of dial on all gages except ROUNDCLOCK12/24.
On ROUND2PENV/H gages units are displayed on each half of dial face
Typical entries psi, mph, feet, "H2O, "Hg, kph, %, pounds, meters, etc.

rmin/rmax:
ROUND270B/T/L/R - input values that represent 0-100% of dial range
ROUND360SGL/ROUND360DBL - input values that represent 360 degree rotation of
         long pointer- rmin must be 0; rmax must be positive
ROUNDCLOCK12/24 - not used (set to 0)
ROUND2PENV/H - input values that represent 0-100% of dial range
dmin/dmax:
ROUND270B/T/L/R - represent 0%-100% of dial range. The maximum
 difference between dmin and dmin is 15.
ROUND360SGL/ROUND360DBL - not used - internally set to 0 and 10
ROUNDCLOCK12 - not used - internally set to 0 and 12
ROUNDCLOCK24 - not used - internally set to 0 and 24

sf:
For all gage styles except ROUNDCLOCK12/24
Scale Factor to multiply gage dial numbers by to get actual value represented.
Displayed in the lower half of the dial face. Both sides of ROUND2PENV/H

In addition to the above the ROUND360SGL/ROUND360DBL gages have an additional feature:
Directly under the center of the dial is a box that contains a 7 digit display.
For ROUND360SGL this display is incremented 1 for each revolution the pointer makes.
For ROUND360DBL this display is incremented 1 for each revolution the short pointer makes.
(The short pointer makes 1 revolution for every 10 the long pointer makes.)
---------------------------------------------------------------------------------------------
SetGagePos1RLM(win as WINDOW,id as UINT,pos as INT)
Purpose: To update the current pointer position of the gage
Where:
win - parent window
id - control id
pos - current value of pointer position *

* NOTE:
ROUND270B/T/L/R - pos value must be => rmin and <= rmax
ROUND360SGL/ROUND360DBL - pos value may be > rmax and the number of revolutions will
 be calculated based upon rmin/rmax.
ROUNDCLOCK12/24 - value of pos is not used. When this function is called the clock is updated
 based upon the internal clock in the user's PC.
ROUND2PENV/H - top or left pen (#1)
---------------------------------------------------------------------------------------------
SetGagePos2RLM(win as WINDOW,id as UINT,pos as INT)
Purpose: To update the current pointer position of the gage
Where:
win - parent window
id - control id
pos - current value of pointer position *

* NOTE:
ROUND270B/T/L/R - N/A
ROUND360SGL/ROUND360DBL - N/A
ROUNDCLOCK12/24 - N/A
ROUND2PENV/H - bottom or right pen (#2)

---------------------------------------------------------------------------------------------
SetGageDialDarkRLM(win as WINDOW,id as UINT)
Purpose: To change the gage's dial face from white to grey
Where:
win - parent window
id - control id
----------------------------------------------------------------------------------------------
SetGagePanelColorRLM(win as WINDOW,id as UINT,pnlcolor as UINT)
Purpose: To change the color of the rectangle that contains the gage.
Where:
win - parent window
id - control id
pnlcolor - color in form of RGB(0,0,0)
The default color when creating the gage control is obtained internally
using getsyscolor(0)

LIMITATION: GAGE CONTROL LIBRARY WORKS ONLY WITHIN A WINDOW
    IT DOES NOT WORK WITH A DIALOG
*********************************************************************************************/
The above could have been placed in a separate text or html file.

For more complicated controls a compiled help file (*.chm) may be required.

With the 'how it works' portion out of the way we need to address the 'how to use it' aspect.
We have a distributable static lib, its associated include file, a demo program, and some form of help. The one mistake we can not make is to assume the new user knows what to do with those files.

There are several approaches that can be used.

The simplest thing to do with "casual" users of your control is to provide a readme.txt file explaining that the .lib file is to be copied into the IWBDev/lib folder; the .inc file is to be copied into the IWBDev/include folder; and that the

Code Select Expand

$INCLUDE "myControl.inc"

line should be added at the top of each source file that the user intends to use the control in.

If the nature of your control is such that it will be used often by most users it may warrant what we call the "power user" option.
This involves the creation of an IWBasic 'Command Pak', the discussion of which is outside the scope of this tutorial

You may also automate the process by creating an installer; similar to that used by IWBasic itself, as well as the add-on libraries.  There are various installer creation tools available on the internet.  Our personal preference is InnoSetup with its add-on, ISTool.

And it never hurts to add additional examples.

______________________________

Coming Next - Conclusion