Home

Win32 Controls: The Spin Button

 

Introduction to the Spin Button

 

Description

The spin button is a Windows control used to increase and decrease values by clicking an up or a down buttons. Visually, the spin button resembles the up-down control. There are some differences with regards to their respective configuration.

 

Practical LearningPractical Learning: Introducing the Spin Edit Control

  1. To start a new project, on the main menu, click File -> New ->  VCL Forms Application - C++Builder
  2. In the Object Inspector, change the properties of the form as follows:
    Caption: Movie Reviewer
    Name:    frmReviewer
    Position: poScreenCenter
  3. To save the project, on the Standard toolbar, click the Save All button Save All
  4. Click the New Folder button
  5. Set the name to MovieReviewer1 and press Enter twice
  6. Set the name of the unit to Reviewer and click Save
  7. Set the name of the project to MovieReviewer and click Save
  8. To test the application, press F9 (that will also create a folder named Debug)
  9. After viewing the form, close it and return to your programming environment
  10. From the resources that accompany these lessons, copy the annie.bmp, bhc.bmp, dave.bmp, disgent.bmp, fatal.bmp, housesitter.bmp, newjack.bmp, and showgirls.bmp files
  11. Paste them in the Debug sub-folder of the current project

Creating a Spin Button

A spin button is based on the TSpinButton class that is derived from TWinControl:

TSpinButton Inheritance

To add a spin button to your application, in the Samples section of the Tool Palette, click the TSpinButton icon TSpinButton and click the form or container.

The spin button is equipped with a constructor. The TSpinButton class’s constructor is typically used to dynamically create a spin button.

Practical LearningPractical Learning: Creating a Spin Button

  1. Design the form as follows:
     
    Movie Reviewer
    Control Caption Kind Name
    TLabel TLabel Title:    
    TEdit TEdit     edtTitle
    TSpinButton TSpinButton     sbtPosition
    TLabel TLabel Director:    
    TEdit TEdit     edtDirector
    TLabel TLabel (c) Year:    
    TEdit TEdit     edtCopyrightYear
    TLabel TLabel Rating:    
    TEdit TEdit     edtRating
    TLabel TLabel Length:    
    TEdit TEdit     edtLength
    TImage TImage     imgMovie
    TBitBtn TBitBtn   bkClose  
  2. Save all
  3. Under the Code Editor, click Reviewer.h and change it as follows:
    private:	// User declarations
    	UnicodeString Titles[8];
    	UnicodeString Directors[8];
    	UnicodeString CopyrightYears[8];
    	UnicodeString Ratings[8];
    	UnicodeString Lengths[8];
    	UnicodeString Pictures[8];
    
    	int Position;
    	void __fastcall ShowStatistics();
    public:		// User declarations
    	__fastcall TfrmReviewer(TComponent* Owner);
    };
    //---------------------------------------------------------------------------
    extern PACKAGE TfrmReviewer *frmReviewer;
    //---------------------------------------------------------------------------
    #endif
  4. Press F12 to display the form
  5. Double-click an unoccupied area of the form to generate its OnCreate event
  6. Change the Reviewer.cpp file as follows:
    //---------------------------------------------------------------------------
    
    #include <vcl.h>
    #pragma hdrstop
    
    #include "Reviewer.h"
    //---------------------------------------------------------------------------
    #pragma package(smart_init)
    #pragma link "Spin"
    #pragma resource "*.dfm"
    TfrmReviewer *frmReviewer;
    //---------------------------------------------------------------------------
    __fastcall TfrmReviewer::TfrmReviewer(TComponent* Owner)
    	: TForm(Owner)
    {
    	Titles[0]         = L"Distinguished Gentleman (The)";
    	Directors[0]      = L"Jonathan Lynn";
    	CopyrightYears[0] = L"1992";
    	Ratings[0]        = L"R";
    	Lengths[0]        = L"112 Minutes";
    	Pictures[0]       = L"distgent.bmp";
    
    	Titles[1]         = L"Fatal Attraction";
    	Directors[1]      = L"Adrian Lyne";
    	CopyrightYears[1] = L"1987";
    	Ratings[1]        = L"R";
    	Lengths[1]        = L"119 Minutes";
    	Pictures[1]       = L"fatal.bmp";
    
    	Titles[2]         = L"New Jack City";
    	Directors[2]      = L"Mario Van Peebles";
    	CopyrightYears[2] = L"1991";
    	Ratings[2]        = L"R";
    	Lengths[2]        = L"97 Minutes";
    	Pictures[2]       = L"newjack.bmp";
    
    	Titles[3]         = L"Showgirls";
    	Directors[3]      = L"Paul Verhoeven";
    	CopyrightYears[3] = L"1995";
    	Ratings[3]        = L"NC-17";
    	Lengths[3]        = L"128 Minutes";
    	Pictures[3]       = L"showgirls.bmp";
    
    	Titles[4]         = L"Annie";
    	Directors[4]      = L"John Huston";
    	CopyrightYears[4] = L"1982";
    	Ratings[4]        = L"PG";
    	Lengths[4]        = L"126 Minutes";
    	Pictures[4]       = L"annie.bmp";
    
    	Titles[5]         = L"Dave";
    	Directors[5]      = L"Ivan Reitman";
    	CopyrightYears[5] = L"1993";
    	Ratings[5]        = L"R";
    	Lengths[5]        = L"110 Minutes";
    	Pictures[5]       = L"Dave.bmp";
    
    	Titles[6]         = L"Housesitter";
    	Directors[6]      = L"Frank Oz";
    	CopyrightYears[6] = L"1992";
    	Ratings[6]        = L"PG";
    	Lengths[6]        = L"110 Minutes";
    	Pictures[6]       = L"housesitter.bmp";
    
    	Titles[7]         = L"Beverly Hills Cop";
    	Directors[7]      = L"Martin Brest";
    	CopyrightYears[7] = L"1984";
    	Ratings[7]        = L"R";
    	Lengths[7]        = L"105 Minutes";
    	Pictures[7]       = L"bhc.bmp";
    }
    //---------------------------------------------------------------------------
    void __fastcall TfrmReviewer::ShowStatistics()
    {
    	edtTitle->Text = Titles[Position];
    	edtDirector->Text = Directors[Position];
    	edtCopyrightYear->Text = CopyrightYears[Position];
    	edtRating->Text = Ratings[Position];
    	edtLength->Text = Lengths[Position];
    	imgMovie->Picture->LoadFromFile(Pictures[Position]);
    }
    //---------------------------------------------------------------------------
    void __fastcall TfrmReviewer::FormCreate(TObject *Sender)
    {
    	Position = 0;
    	ShowStatistics();
    }
    //---------------------------------------------------------------------------
  7. Press F12 to return to the form
  8. Save all
 

Characteristics of a Spin Button

 

The Up and the Down Glyphs

 
 

Two of the properties that differentiate the spin button from the up-down control is that the spin button control allows you to add your own button indicators as bitmaps. To assist you with this, the TSpinButton class is equipped with the UpGlyph and the DownGlyph properties. Both are of type TBitmap:

__property Graphics::TBitmap * UpGlyph = {read=GetUpGlyph,write=SetUpGlyph};
__property Graphics::TBitmap * DownGlyph = {read=GetDownGlyph,write=SetDownGlyph};

To visually specify which bitmap must point up on the control, click the ellipsis button on the UpGlyph field of the Object Inspector. You can also specify a bitmap that would point down using the DownGlyph property:

 

Spin Edit

The Spin Button Events

The biggest difference between an UpDown control and a spin button is the way each handles the incrementing and decrementing of its values. Simply put, the spin button does not have a value to the sense of a progress control; you must set, assign, and configure the value or position of the spin button on your own. While the main event of an UpDown control occurs when the user clicks one of its arrows, to apply a specific behavior, you can either consider the whole event or find out what button was clicked. The spin button uses two different events for each button. Clicking the up pointing arrow fires the OnUpClick() event while the OnDownClick event fires when the user clicks the down pointing arrow.

Practical LearningPractical Learning: Using the Spin Button

  1. On the form, click the spin button
  2. In the Object Inspector, click Events
  3. Double-click the right field of OnDownClick
  4. Implement the event as follows:
    //---------------------------------------------------------------------------
    void __fastcall TfrmReviewer::sbtPositionDownClick(TObject *Sender)
    {
    	if( Position <= 0 )
    		Position = 7;
    	else
    		Position--;
    
    	ShowStatistics();
    }
    //---------------------------------------------------------------------------
  5. In the Events section of the Object Inspector, double-click the empty field on the right side of OnUpClick
  6. Implement the event as follows:
    //---------------------------------------------------------------------------
    void __fastcall TfrmReviewer::sbtPositionUpClick(TObject *Sender)
    {
    	if( Position >= 7 )
    		Position = 0;
    	else
    		Position++;
    
    	ShowStatistics();
    }
    //---------------------------------------------------------------------------
  7. Save all
  8. To test the form, on the main menu, click Run -> Run

    Movie Reviewer
     
    Movie Reviewer
     
    Movie Reviewer
  9. After experimenting with the spin button, close the form
 
 
 
 

Home Copyright © 2010-2011 FunctionX, Inc.