Contents page

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. Rather, 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 KNOB_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 KNOB_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 routine 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.
UserData	field for your own use




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 REFRESH 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.



---