Knobs
Knobs are a very similar to proportional gadgets. Instead of sliding up and
down or left and right, they rotate.
Knobs are surprisingly easy to use. The knob can rotate in a full circle or
rotate between start and stop angles that you designate. You can specify how
many steps (or notches) there are in a full rotation and let the knob
circuitry translate from the angle to a value that makes sense in your
application. You can specify what the radius of the knob is, what color to
paint it, the radius of the arrow, and what color to paint that.
The Knob Structure
As with Intuition gadgets, there is a Knob data structure that needs to be
initialised with the proper parameters before it goes into use.
struct Knob {
struct Knob *NextKnob;
USHORT XCenter, YCenter;
USHORT Flags;
USHORT Value;
USHORT Range;
USHORT Angle;
USHORT Offset;
USHORT Steps;
USHORT ArrowRadius;
USHORT KnobRadius;
USHORT StartAngle;
USHORT StopAngle;
USHORT FillColor;
USHORT BorderColor;
USHORT ArrowColor;
USHORT KnobID;
USHORT AX, AY, OX, OY, OS;
void (*UpdateRoutine) ();
long UserData;
};
A description of each field and how you use it:
NextKnob Like gadgets, the knobs are strung in a linked list. This
points to the next knob in your window.
XCenter,YCenter These are the coordinates for the center of the knob.
Flags There are several flags you can set.
KNOB_DRAW Set this to instruct DrawKnobs to draw the
circle that makes up the body of the knob.
Normally, this is set, but you may wish not to
have the knob drawn. The outline of the knob is
drawn with the pen number in BorderColor.
KNOB_FILL When the knob is drawn, this says to fill the
knob with the pen specified in FillColor.
KNOB_COMPLEMENT The line (arrow) that is used to indicate where
the knob is pointing can be drawn either with
the pen specified by ArrowColor or by
complementing the background color. This flag
sets it to complement.
KNOB_RANGED If this flag is set, you don't want the knob to
rotate in a full circle. R,ather, it has a range
it covers. This range is between the start
point, StartAngle, and the end point, StopAngle.
The knob will only move between these two
points. If KNOB_RANGED is not set StartAngle and
StopAngle are ignored and the knob simply
rotates all the way around.
KNOB_CALCVALUE If this is set, InovaTools 1 will automatically
convert the knob angle into a value that makes
more sense for your program. That value is
stored in Value. Range is the total range that
the value can have. For example, if you desire
to have a knob that returns 0 for all the way to
the left and 23 for all the way to the right,
you'd set Range to be 24. This feature takes
care of some redundant math for you.
KNOB_MARKED With this set, little markers, at intervals
determined by Steps are inscribed on the outside
of the knob.
KNOB_MARKENDS With this set, two markers are placed at the
begin and end of the knob sweep. This only
works for knobs with KNOB_RANGED set.
Value This is a value that Intuitools computes for you if you
have the KNOB-CALCVALUE flag set. This number is calculated
from Angle, taking StartAngle, StopAngle, Range, and Steps
into account. Also, if KNOB_CALCVALUE is set and you wish
to change the knob orientation with a call to DrawArrow,
set this to the value you want and DrawArrow will translate
it to the proper angle.
Range You can specify a range for the calculated value. It can be
any integer up to 65535. For example, if you give a range
of 25, the numbers placed in Value will range from 0 to 24.
Angle This is the actual angle of the knob. In this system, a
circle has 65536 degrees. To translate Angle into degrees,
multiply by 360, then divide by 65536.
Offset You can specify an offset for the knob's angle. With an
offset of 0, the knob starts with an angle 0 that points
towards the top of the screen. Any offset added to this
rotates the starting angle clockwise. For example, the
color palette editor knobs start at the bottom, so they all
have an offset of 32768, which is exactly half a rotation.
Steps This sets how many notches there are in the sweep of the
knob, how many incremental steps it goes through to go from
one end to the other. For example, if Steps is 4, the knob
can only move between four, equally spaced, points.
ArrowRadius The length of the knob's arrow. The arrow starts at the
center of the knob and is drawn this long. The arrow can
overshoot the knob itself. The length is measured in
horizontal pixels.
KnobRadius The radius of the drawn knob.
StartAngle If you don't want the knob to travel a full circle, you set
KNOB_RANGED and stick the starting offset in StartAngle.
The offset is measured in degrees, where there are 65536
degrees in a full circle.
StopAngle If you don't want the knob to travel a full circle, you set
KNOB_RANGED and stick the finishing point in StopAngle. The
offset is measured in degrees, where there are 65536
degrees in a full circle.
FillColor This is the color to use to fill the knob. The knob is only
filled if ICNOB_FILL is set.
BorderColor This is the color to draw the outline of the knob with.
This only happens if KNOB_DRAW is set.
ArrowColor This is the color to draw the arrow. This pen is not used
if ICNOB_COMPLEMENT was set. Rather, the arrow is drawn by
complementing the background.
KnobID You can give each knob a unique id.
AX - OS Leave these alone.
UpdateRoutine As the knob is being rotated, you may wish to do real time
updates. For example, the palette editor changes the color
as the knob moves. If you put the pointer to a routine in
UpdateRoutine, this routzne will be called each time the
knob moves. The routine is passed two parameters:
Window A pointer to the window this knob is in.
Knob A pointer to the knob.
You may give the same routine to several of your knobs,
then use KnobID to figure out which one was passed to you.
UserData You are free to do whatever you like with this.
Using Knobs
First, create your list of Knob structures. Design your window and make sure
it has MOUSEBUTTONS set.
Use your standard Intuition code to open and manage the window. Once the
window is opened, add a call to DrawKnobs, which displays the knob list in
your window.
DrawKnobs(Window,KnobList);
Since you have enabled MOUSEBUTTONS, Intuition will send you a messa e each
time the left mouse button is clicked. When one of these events co mes in it
ma be because the user has clicked on a knob. Simply call KnobGadgets. If
the mouse did click on one of the knobs, it will process it, not returning
until the mouse is released. When it returns, it will return a pointer to
the knob that was clicked on. If none of the knobs is under the mouse,
KnobGadgets returns NULL immediately.
Here is an example that redraws the knobs when a REFRESN or NEWSIZE event is
received and calls KnobGadget when the mouse button is clicked:
message = GetIntuiMessage(window);
class = message->Class;
code = message->Code;
ReplyMsg(message);
if ((class == NEWSIZE) ||
(class == REFRESH)) DrawKnobs(window,knoblist);
else if ((class == MOUSEBUTTONS) &&
(code == SELECTDOWN))
{
knob = KnobGadgets(window,knoblist);
if (knob) printf("Selected Knob %ld\n",knob->KnobID);
else printf("Dunno\n");
}
When you are done and ready to close down, simply close the window. There is
nothing more that needs to be done with the knobs unless you created the
knob list with DupeKnobList, in which case you release the knob list with a
call to DeleteKnobList.