1. Build-A-Button Glenn G. Chappell CHAPPELLG@member.ams.org U. of Alaska Fairbanks CS 381 Lecture Notes Wednesday, October 8, 2003

2. 8 Oct 2003CS 3812 Review: Introduction to Widgets In a GUI, when a user specifies an action to be performed, a “widget” is often used. A widget (also called a control, esp. in MacOS) is a portion of the screen dedicated to mouse input. So widgets are a great application of picking! Examples: Checkboxes Radio buttons Scroll bars Buttons Menu pop-ups Some text boxes We will look at issues involved in the inclusion of widgets in a GUI and their implementation.

3. 8 Oct 2003CS 3813 Note There were no slides shown during this class meeting. Rather, there was a discussion of how to put together a C++ class to implement a button widget. The following slides are a summary of that discussion.

4. 8 Oct 2003CS 3814 Build-A-Button: Requirements We wish to implement a button widget for OpenGL/GLUT programs. The button should have the following features in common with the buttons found in most modern GUI’s: It is shown as a screen-aligned rectangle with a centered label (text- only, for now). To initiate the action represented by the button, press and release the mouse on the button. While the mouse is down on the button, it should have a pressed-in appearance. Moving the mouse off the button while it is down makes the button come out again. The mouse may be moved anywhere while it is down; the button’s action only happens if the mouse position when it is pressed and when it is released both lie on the button. The button should have a disabled state, in which the label is shown in gray and the button does not respond to mouse-down events.

5. 8 Oct 2003CS 3815 Build-A-Button: What We Will Not Do Buttons found in modern GUI’s have features that we will not be implementing. For example: The ability to hide & show the button. Graphic labels. “Pressing” buttons via keypresses (e.g., ). Various kinds of highlighting: Highlight button on mouse-over. Highlight button that is activated by pressing. Highlight button that is selected by pressing. Click-and-drag to move buttons around. Text pop-ups explaining a button’s function.

6. 8 Oct 2003CS 3816 Build-A-Button: Button Features [1/2] We began the process of moving from requirements to design. The button will be implemented as a single C++ class. It will be “stand-alone”, not requiring any associated “widget manager” class. We asked two questions: “What should the button class be able to do?” and “What does the button class need to know?” The answers to these two questions will correspond roughly, but not exactly, to the function and data members of the class, respectively. Our preliminary answers are found on the next slide.

7. 8 Oct 2003CS 3817 Build-A-Button: Button Features [2/2] Button does: Draw itself. Configure its appearance. Change appearance based on mouse clicks & movement. Be enabled/disabled. Button knows: Its location. Its size. Its out/in state. The action performed when it is clicked. Its text label. Is the mouse currently in this button? Enable/disable state. Was last mouse-down in this button?

8. 8 Oct 2003CS 3818 Build-A-Button: Class Members [1/4] We turned our lists into lists of function & data members. “Initiate … action …” will not be a function member. This is properly a data member: a button must know what to do when pressed. Keep a pointer to an “action” callback function. “Change appearance …” is ambiguous. Changing pressed to not pressed, etc., is part of mouse-handling. Button configuration is handled by several function members. Mouse-handling, above, is really two function members: one to handle mouse clicks, and one to handle mouse motion. Any C++ class needs constructors, etc. Which items in the “know” column are data members? Those which must be remembered from one call to another. So toss “Is the mouse currently in this button?” out of the list. A “Visible?” data member is a great idea. Any serious button implementation would include this feature. I did not. (Deal with it.)

9. 8 Oct 2003CS 3819 Build-A-Button: Class Members [2/4] Function Members Display. Called by GLUT display function. Handle mouse click. Called by GLUT mouse function with its param’s. Handle mouse motion. Called by GLUT motion function with its param’s. Configure button. Several function members (one for each of starred data members). Default constructor. Destructor. Data Members *Position. Left, bottom. *Size. Width, height. *Text label. *Pointer to action callback function. *Enabled? I call this “ active ” in the Button class. Currently tracking mouse? Pressed?

10. 8 Oct 2003CS 38110 Build-A-Button: Class Members [3/4] Configuring a button could be done in two different ways: Have a constructor with a large number of parameters. Have a number of configuration functions. I opted for the latter approach, for the same reasons that the function-call-intensive approach works well for OpenGL. We included a default constructor and a destructor. In a C++ class, two more “administrative” functions are usually written: copy constructor and copy assignment operator. These are problematic. What if you copy a button that is pressed in? Do you now have two pressed buttons? I avoided such issues by making both functions inaccessible (declared private and never defined). This does not seem to reduce class functionality significantly. So buttons cannot be passed to functions by value, but they can be passed by reference.

11. 8 Oct 2003CS 38111 Build-A-Button: Class Members [4/4] Whenever an object can deal with the mouse, some mouse events will be handled by it, and some will not. Often only the object itself knows whether a given mouse event is to be handled by it. The object generally needs to be able to tell the outside world whether it has handled a given mouse event. So: The mouse handling function members return a bool indicating whether this button has handled the mouse event. The button action can be handled in two different ways: The button keeps a pointer to the function to be called. Then the button calls this function when it needs to. The button simply tells the outside world when the action needs to be performed. I opted for the former strategy, as it seems to be a bit cleaner in this context. Professional-quality GUI toolkits will often offer both methods.

12. 8 Oct 2003CS 38112 Build-A-Button: Implementation An implementation of the button class we discussed can be found in button.h & button.cpp on the web page. I followed standard C++ conventions with these. The class is named “ Button ”. Note that the name begins with an upper-case letter. The “.h ” file includes the class definition; it should be #include ’d in any source file that uses the class. The header begins with an #ifndef to make sure it is only #include ’d once. The “.cpp ” file includes the code for all but the simplest member functions in the class; it should be compiled along with the other application source code. An example program that uses the Button class is in colorchange.cpp, also on the web page. Of course, I led discussion in the direction of the package I had already written. This is not to say that my way is the best way. Some features would definitely be different in a serious implementation. More on this next time.