Beginning REALbasic - From Novice To Professional (2006)

To work with the NotePlayer control, you add a copy of it to your REALbasic application. This copy is visible in the REALbasic IDE, but it won’t be visible to the end user when the application runs. To work with this control, you must specify the type of instrument to be used to play musical notes. You do this by setting the Instrument property to an Integer representing one of instruments listed in Table 11-1.

Table 11-1. A Listing of Instruments with Which You Can Play Notes in a REALbasic Application

The NotePlayer class has only one method called PlayNote, which plays a note at a specified pitch level and velocity. Pitch and velocity are specified as integers, each of which has a range from 0 to 127. For pitch, each increment raises the pitch by a half step. Middle C begins at 60. For velocity, 127 specifies a hard key press and 0 represents a key no longer being pressed. For example, the following code statement demonstrates how to play a note on a Xylophone, using a medium pitch and velocity.

NotePlayer1.Instrument = 14

NotePlayer1.PlayNote(60,60)

Using the NotePlayer control, you can simulate the playing of many different musical instruments. This includes, for example, different types of pianos. Figure 11-2 shows a REALbasic application that simulates the playing of six different minipianos.

Figure 11-2. A small virtual piano implemented as a REALbasic application, running on Windows

To create this example, open a new REALbasic application and add NotePlayer control, seven PushButton controls, and a StaticText control and align them as you see in Figure 11-2. Then, assign a title of RB Piano Player to the window’s Title property and open the application’s menu bar and remove the Edit menu. Next, add an Instruments menu and add the following menu items to it:

•Acoustic Grand Piano

•Bright Acoustic Piano

•Electric Grand Piano

•Honky-tonk Piano

•Rhodes Piano

•Chorused Piano

Next, add six event handlers, one for each of the specified instruments. Add the following code statements to the Instrument AcousticGrandPiano event handler.

NotePlayer1.Instrument = 1 txtPianoName.Text = "Acoustic Grand Piano"

As you can see, when executed, this menu handler sets the musical instrument to Acoustic Grand Piano and displays the name of the instrument in the StaticText control for the user to see. Next, add the following pairs of code statements to the appropriate menu handlers.

NotePlayer1.Instrument = 2

txtPianoName.Text = "Bright Acoustic Piano"

NotePlayer1.Instrument = 6 txtPianoName.Text = "Chorused Piano"

NotePlayer1.Instrument = 3 txtPianoName.Text = "Electric Grand Piano"

NotePlayer1.Instrument = 4 txtPianoName.Text = "Honky-tonk Piano"

NotePlayer1.Instrument = 5 txtPianoName.Text = "Rhodes Piano”

Next, set the caption of the first PushButton control to C and double-click it to open its Action event handler in the Code Editor. Enter the following code statement.

NotePlayer1.PlayNote(60,127)

This statement plays a note with medium pitch at the maximum possible velocity. Assign the second PushButton control a caption of D and add the following code statement to its Action event handler.

NotePlayer1.PlayNote(62,127)

Assign the second PushButton control a caption of E, and then add the following code statement to its Action event handler.

NotePlayer1.PlayNote(64,127)

Assign the third PushButton control a caption of F and add the following code statement to its Action event handler.

NotePlayer1.PlayNote(65,127)

Assign the fourth PushButton control a caption of G, and then add the following code statement to its Action event handler.

NotePlayer1.PlayNote(67,127)

Assign the fifth PushButton control a caption of A and add the following code statement to its Action event handler.

NotePlayer1.PlayNote(69,127)

Assign the last PushButton control a caption of B, and then add the following code statement to its Action event handler.

NotePlayer1.PlayNote(71,127)

At this point, you have the programming logic defined for each of the PushButton controls and menu items. One last step remains, telling the application what instrument to set as the default instrument at startup. To do this, add the following code to the Piano window’s Open event handler.

NotePlayer1.Instrument = 1 txtPianoName.Text = "Acoustic Grand Piano"

Now, save and run your application. You’ll see you can switch between and play various types of pianos.

■Note You can find a working example of this application on this book’s companion CD-ROM.

Working with Graphics

REALbasic provides strong support for working with graphics. For example, in previous chapters, you learned how to open and display graphic files using methods belonging to the FolderItem class and the ImageWell control. While the ImageWell control can be used to display graphic files, it does not provide any properties or methods that facilitate the creation of graphics. This chapter expands on your understanding of REALbasic’s graphic support by teaching you how to create and draw graphics files by using the Canvas control, and properties and methods belonging to the Graphics class.

REALbasic’s Coordinate System

To create custom graphics using REALbasic, you need to know a bit about REALbasic’s coordinate system, which determines where graphics are drawn in a Canvas control or on the background of a window. This coordinate system is made up of a grid of pixels. The upper lefthand corner of Canvas controls or windows represents the origin of the grid and has coordinates of 0,0. That is, the first argument represents the distance from the left-hand side and the second argument represents the distance from the top of the Canvas control or window.

Most of the methods you use to draw graphics are based on two sets of information. The first set of information is the upper-left hand coordinate position of the graphic to be drawn. The second set of information required to draw most images is the height and width of the image to be drawn.

Displaying Graphic Files as a Window’s Background Image

One way to liven the appearance of an application’s window is to display a background color. You can do this by enabling the HasBackColor property, and then selecting a color by clicking the ellipsis icon located in the window’s BackColor property to open and select a background color from the Color Picker window, as Figure 11-3, Figure 11-4, and Figure 11-5 show.

■Note To display a background color in a window, the HasBackColor property must be enabled.

Figure 11-3. The Color Picker, as seen on Mac OS X

Figure 11-4. The Color Picker, as seen on Windows

Figure 11-5. The Color Picker, as seen on Linux

Or, you can specify a window’s background color via code, as the following shows.

Me.HasBackColor = True

Me.BackColor = RGB(255,0,0)

USING DIFFERENT COLOR MODELS

In REALbasic, you can specify a color value using any of three color models: RGB, HSV, or CMY. RGB is based on the selection of red, green, and blue values. HSV is based on the selection of hue, saturation, and value. CMY is based on the selection of cyan, magenta, and yellow. For each of these three models, you must specify a value in the range of 0–255. For example, you could specify a color of white using the RGB color model, as the following shows.

Dim CustomColor As Color

CustomColor = RGB(255, 255, 255)

Or, you could specify a color of black, as you see in the following.

Dim CustomColor As Color

CustomColor = RGB(0, 0, 0)

REALbasic also enables you to specify a color value by specifying a hexadecimal value of a color based on the RGB model, as you see in the following.

Dim CustomColor As Color

CustomColor - &cff0000

This example sets the window’s background color to red (for example, RGB(255, 0, 0)).

You can also spruce up a window by displaying a picture as a background image. This can be done by importing a picture into your project and setting the BackDrop property in the window’s Open event handler, as you see in the following.

Me.BackDrop = Mountains

Me.Width = BackDrop.Width

Me.Height = BackDrop.Height

In this example, a jpeg file named Mountains is displayed in the window’s background. In addition, the height and width of the window were resized to match the height and width of the jpeg file.

Drawing Custom Graphics

You can programmatically draw graphics in windows and on canvas controls. Doing so requires you to use methods and properties belonging to the Graphics class. Using these properties and methods, you can draw individual pixels, lines, and numerous shapes, such as ovals and rectangles. You can also draw standard dialog icons, such as the Note, Caution, and Stop icons.

Both the window and Canvas control support a Paint event. The Canvas control and window’s Paint event handler is the central location for any application that has program code used to draw. The Paint event executes any time a window or Canvas control needs to be drawn or redrawn. For example, the Paint event executes whenever a window or Canvas control is opened. The Paint event also executes whenever a Canvas control or window is resized or when a previously hidden portion of a Canvas control or window becomes exposed. The Paint event is set up as a Subroutine and is passed the Graphics object each time it is executed, as you see in the following.

Sub Paint(g As Graphics)

This provides your code statements with immediate access to all the properties and methods belonging to the Graphics class.

Drawing Pixels

Using the Pixel property belonging to the Graphics class, you can draw individual pixels to create extremely detailed graphics. As a quick demonstration, place the following code statements in the Paint event handler for a new project’s window, and then run it.

Dim CustomColor As Color CustomColor = RGB(255, 0, 0) g.Pixel(50,100) = CustomColor

If you look closely at the window, you can see a pixel has been drawn in red (using the RGB function and a Color object named CustomColor) at a location that is 50 pixels from the lefthand side of the window and 100 pixels down from the top of the window.

Drawing Text

Using the Graphics class’s properties and methods, you can also draw text on window and Canvas controls, as you can see in the following.

g.ForeColor = RGB(0,0,0)

g.Bold = True g.TextFont = "Arial" g.TextSize = 24

g.DrawString "Once upon a time ...", 25, 50

In this example, the Graphics class’s ForeColor property is set equal to black. In addition, the Graphics class’s Bold, TextFont, and TextSize properties are also specified. Finally, the DrawString method is executed. This method takes as parameters a text string and the upper left-hand coordinates at which the text string should be drawn. Figure 11-6 shows the output produced by this example.

Figure 11-6. Drawing text, as seen on Linux

Drawing Icons

The Graphics class also provides methods for drawing standard Caution, Note, and Stop icons. These methods are named as follows:

•DrawCautionIcon

•DrawNoteIcon

•DrawStopIcon

Each of these methods requires you to pass to it the coordinates at which the icon should be drawn, as you see in the following example.

g.ForeColor = RGB(0, 0, 255)

g.DrawStopIcon 90, 45 g.Bold = True

g.DrawString "Error: Something went wrong.", 90, 70

In this example, the DrawStopIcon method is used to draw a Stop icon at coordinates 90, 45. Next, the DrawString method is used to draw a descriptive text string just to the right of the icon, as Figure 11-7 shows.

Figure 11-7. Drawing text and icon, as seen on Linux

Drawing Lines

The Graphics class also provides you with the capability to draw lines on window and Canvas controls using its DrawLine method. This method requires four sets or arguments. The first two arguments represent the starting coordinates of the line to be drawn and the last two arguments represent the ending coordinates of the line. The following shows an example of how to use the DrawLine method.

g.ForeColor = RGB(255,0,0)

g.DrawLine 50, 50, 200, 200

Figure 11-8 shows the output generated by this example, which as you can see is a straight line. The beginning of the line is 50 pixels from the left-hand side of the window and 50 pixels from the top. The end of the line is 200 pixels from the left-hand side of the window and 200 pixels from the top.