Cross-Platform GUI Programmingwith wxWidgets

Julian Smart and Kevin Hock

with Stefan Csomor

Upper Saddle River, NJ • Boston • Indianapolis • San Francisco

...\\\ New York • Toronto • Montreal • London • Munich • ParisPRENTICE

HALL Madrid • Capetown • Sydney • Tokyo • Singapore • Mexico CityPTR

Contents

Foreword by Mitch Kapor xxiii

Preface xxv

Acknowledgments xxxiii

About the Authors xxxv

1 Introduction 1What Is wxWidgets? 1Why Use wxWidgets? 2A Brief History of wxWidgets 5The wxWidgets Community 6wxWidgets and Object-Oriented Programming 7License Considerations 7The wxWidgets Architecture 8

wxMSW 8wxGTK 8wxX11 9wxMotif 10wxMac 10wxCocoa 10wxWinCE 10wxPalmOS 12wxOS2 12wxMGL 12Internal Organization 12

Summary 13

2 Getting Started 15A Small wxWidgets Sample 15The Application Class 16

vii

viii Contents

The Frame Class 17

The Event Handlers 18

The Frame Constructor 19

The Whole Program 20

Compiling and Running the Program 22

Program Flow 23

Summary 23

3 Event Handling 25Event-Driven Programming 25Event Tables and Handlers 26Skipping Events 29Pluggable Event Handlers 29Dynamic Event Handlers 30Window Identifiers 31Defining Custom Events 34Summary 37

4 Window Basics 39Anatomy of a Window 39

The Concept of a Window 40Client and Non-Client Areas 40Scrollbars 41Caret and Cursor 41Top-Level Windows 41Coordinate System 41Painting 41Color and Font 42Window Variant 42Sizing 42Input 42Idle Time Processing and UI Updates 42Window Creation and Deletion 43Window Styles 44

A Quick Guide to the Window Classes 44Base Window Classes 45Top-Level Windows 45Container Windows 45Non-Static Controls 45Static Controls 46Menus 46Control Bars 46

Base Window Classes 46wxWindow 47

wxWindow Styles 47wxWindow Events 49

Contents ix

wxWindow Member Functions 50wxControl 54

wxControlWithltems 54wxControlWithltems Member Functions 54

Top-Level Windows 55wxFrame 55

wxFrame Styles 58wxFrame Events 59wxFrame Member Functions 60Non-Rectangular Frames 61Mini-Frames 63

wxMDlParentFrame 63wxMDlParentFrame Styles 64wxMDlParentFrame Member Functions 65

wxMDlChildFrame 65wxMDlChildFrame Styles 65wxMDlChildFrame Member Functions 66

wxDialog 66wxDialog Styles 69wxDialog Events 70wxDialog Member Functions 71

wxPopupWindow 71Container Windows 72

wxPanel 72wxPanel Styles 72wxPanel Member Functions 72

wxNotebook 72Notebook Theme Management 74wxNotebook Styles 74wxNotebook Events 75wxNotebook Member Functions 75Alternatives to wxNotebook 76

wxScrolledWindow 76wxScrolledWindow Styles 78wxScrolledWindow Events 78wxScrolledWindow Member Functions 79Scrolling Without Using wxScrolledWindow 80

wxSplitterWindow 81wxSplitterWindow Styles 83wxSplitterWindow Events 83wxSplitterWindow Member Functions 84Sizing Issues with wxSplitterWindow 84Alternatives to wxSplitterWindow 85

Non-Static Controls 86wxButton 86

x Contents

wxButton Styles 86wxButton Events 87wxButton Member Functions 87

wxButton Labels 87wxBitmapButton 89

wxBitmapButton Styles 90wxBitmapButton Events 90wxBitmapButton Member Functions 90

wxChoice 90wxChoice Styles 91wxChoice Events 91wxChoice Member Functions 91

wxComboBox 91wxComboBox Styles 92wxComboBox Events 93wxComboBox Member Functions 93

wxCheckBox 93wxCheckBox Styles 94wxCheckBox Events 95wxCheckBox Member Functions 95

wxListBox and wxCheckListBox 95wxListBox and wxCheckListBox Styles 97wxListBox and wxCheckListBox Events 97wxListBox Member Functions 98wxCheckListBox Member Functions 98

wxRadioBox 98wxRadioBox Styles 99wxRadioBox Events 100wxRadioBox Member Functions 100

wxRadioButton 100wxRadioButton Styles 101wxRadioButton Events 101wxRadioButton Member Functions 101

wxScrollBar 101wxScrollBar Styles 102wxScrollBar Events 102wxScrollBar Member Functions 103

wxSpinButton 103wxSpinButton Styles 104wxSpinButton Events 104wxSpinButton Member Functions 104

wxSpinCtrl 104wxSpinCtrl Styles 105wxSpinCtrl Events 105wxSpinCtrl Member Functions 106

wxSlider 106

Contents xi

wxSlider Styles 106wxSlider Events 107wxSlider Member Functions 107

wxTextCtrl 107wxTextCtrl Styles 109wxTextCtrl Events 110wxTextCtrl Member Functions 110

wxToggleButton 111wxToggleButton Styles 112wxToggleButton Events 112wxToggleButton Member Functions 112

Static Controls 112wxGauge 112

wxGauge Styles 113wxGauge Events 113wxGauge Member Functions 113

wxStaticText 113wxStaticText Styles 114wxStaticText Member Functions 114

wxStaticBitmap 114wxStaticBitmap Styles 115wxStaticBitmap Member Functions 115

wxStaticLine 115wxStaticLine Styles 115wxStaticLine Member Functions 116

wxStaticBox 116wxStaticBox Styles 116wxStaticBox Member Functions 116

Menus 116wxMenu 117

wxMenu Events 118wxMenu Member Functions 120

Control Bars 122

wxMenuBar 122wxMenuBar Styles 123

wxMenuBar Events 123

wxMenuBar Member Functions 123

wxToolBar 124Tool Bitmap Colors Under Windows 125wxToolBar Styles 126

wxToolBar Events 126wxToolBar Member Functions 127

wxStatusBar 128wxStatusBar Styles 129wxStatusBar Events 129wxStatusBar Member Functions 129

Summary 130

xii Contents

5 Drawing and Printing 131Understanding Device Contexts 131

Available Device Contexts 132Drawing on Windows with wxClientDC 133Erasing Window Backgrounds 134Drawing on Windows with wxPaintDC 135Drawing on Bitmaps with wxMemoryDC 138Creating Metafiles with wxMetafileDC 138Accessing the Screen with wxScreenDC 139Printing with wxPrinterDC and wxPostScriptDC 139

Drawing Tools 140wxColour 141wxPen 142wxBrush 143wxFont 145wxPalette 147

Device Context Drawing Functions 148Drawing Text 150Drawing Lines and Shapes 152Drawing Splines 156Drawing Bitmaps 157Filling Arbitrary Areas 159Logical Functions 159

Using the Printing Framework 161More on wxPrintout 163Scaling for Printing and Previewing 165Printing under Unix with GTK+ 167

3D Graphics with wxGLCanvas 168Summary 170

6 Handling Input 171Mouse Input 171

Handling Button and Motion Events 173Handling Mouse Wheel Events 174

Handling Keyboard Events 175An Example Character Event Handler 178Key Code Translation 179Modifier Key Variations 179Accelerators 180

Handling Joystick Events 181wxJoystick Events 183wxJoystickEvent Member Functions 184wxJoystick Member Functions 184

Summary 185

Contents xiii

7 Window Layout Using Sizers 187Layout Basics 187Sizers 188

Common Features of Sizers 190Programming with Sizers 192

Programming with wxBoxSizer 193Programming with wxStaticBoxSizer 196Programming with wxGridSizer 197Programming with wxFlexGridSizer 198Programming with wxGridBagSizer 200

Further Layout Issues 201Dialog Units 202Platform-Adaptive Layouts 202Dynamic Layouts 204

Summary 204

8 Using Standard Dialogs 205Informative Dialogs 205

wxMessageDialog 205wxMessageDialog Example 207wxMessageBox 207

wxProgressDialog 208wxProgressDialog Example 209wxBusylnfo 210

wxBusylnfo Example 210wxShowTip 210

wxShowTip Example 211File and Directory Dialogs 212

wxFileDialog 212wxFileDialog Styles 214wxFileDialog Functions 215wxFileDialog Example 215

wxDirDialog 216wxDirDialog Functions 218wxDirDialog Example 218

Choice and Selection Dialogs 218wxColourDialog 218

wxColourData Functions 221wxColourDialog Example 221

wxFontDialog 221wxFontData Functions 223Font Selector Example 224

wxSingleChoiceDialog 224wxSingleChoiceDialog Example 225

xiv Contents

wxMultiChoiceDialog 225

wxMultiChoiceDialog Example 226

Entry Dialogs 227

wxNumberEntryDialog 227

wxNumberEntryDialog Example 227

wxTextEntryDialog and wxPasswordEntryDialog 227

wxTextEntryDialog Example 228

wxFindReplaceDialog 228Handling Events from the Dialog 229wxFindDialogEvent Functions 230Passing Data to the Dialog 230wxFindReplaceData Functions 230Find and Replace Example 231

Printing Dialogs 232wxPageSetupDialog 232

wxPageSetupData Functions 235wxPageSetupDialog Example 235

wxPrintDialog 235wxPrintDialogData Functions 238wxPrintDialog Example 238

Summary 239

9 Writing Custom Dialogs 241Steps in Creating a Custom Dialog 241An Example: PersonalRecordDialog 242

Deriving a New Class 243Designing Data Storage 243Coding the Controls and Layout 244Data Transfer and Validation 247Handling Events 249Handling UI Updates 250Adding Help 251

Tooltips 251Context-Sensitive Help 251Online Help 252

The Complete Class 253Invoking the Dialog 253

Adapting Dialogs for Small Devices 254Further Considerations in Dialog Design 255

Keyboard Navigation 255Data and UI Separation 256Layout 256Aesthetics 257Alternatives to Dialogs 257

Contents xv

Using wxWidgets Resource Files 257Loading Resources 258Using Binary and Embedded Resource Files 259Translating Resources 261The XRC Format 261Writing Resource Handlers 262Foreign Controls 263

Summary 264

10 Programming with Images 265Image Classes in wxWidgets 265Programming with wxBitmap 267

Creating a wxBitmap 268Setting a wxMask 269The XPM Format 270Drawing with Bitmaps 271Packaging Bitmap Resources 272

Programming with wxlcon 272Creating a wxlcon 273Using wxlcon 274Associating an Icon with an Application 274

Programming with wxCursor 275Creating a wxCursor 276Using wxCursor 278Using wxSetCursorEvent 278

Programming with wxlmage 279Loading and Saving Images 280Transparency 282Transformations 284Color Reduction 284Manipulating wxlmage Data Directly 285

Image Lists and Icon Bundles 285Customizing Art in wxWidgets 288Summary 290

11 Clipboard and Drag and Drop 291Data Objects 291

Data Source Duties 292Data Target Duties 292

Using the Clipboard 293Implementing Drag and Drop 294

Implementing a Drag Source 2941. Preparation 2952. Drag Start 295

xvi Contents

3. Dragging 295

4. Processing the Result 296

Implementing a Drop Target 297

1. Initialization 297

2. Dragging 298

3. Drop 298

Using Standard Drop Targets 298

Creating a Custom Drop Target 299More an wxDataObject 300

Deriving from wxDataObject 301The wxWidgets Drag and Drop Sample 302

Drag and Drop Helpers in wxWidgets 311wxTreeCtrl 311wxListCtrl 312wxDraglmage 313

Summary 316

12 Advanced Window Classes 317wxTreeCtrl 317

wxTreeCtrl Styles 319wxTreeCtrl Events 320wxTreeCtrl Member Functions 321

wxListCtrl 322wxListCtrl Styles 323wxListCtrl Events 324wxListltem 325wxListCtrl Member Functions 327Using wxListCtrl 329Virtual List Controls 330

wxWizard 331wxWizard Events 331wxWizard Member Functions 332wxWizard Example 332

wxHtmlWindow 338wxHtmlWindow Styles 341wxHtmlWindow Member Functions 342Embedding Windows in HTML Pages 343HTML Printing 344

wxGrid 346The wxGrid System of Classes 348wxGrid Events 349wxGrid Member Functions 350

Functions for Creation, Deletion, and Data Retrieval 350Presentation Functions 351Functions for Setting and Getting wxGrid Metrics 352

Contents xvii

Selection and Cursor Functions 352Miscellaneous wxGrid Functions 353

wxTaskBarlcon 354wxTaskBarlcon Events 358wxTaskBarlcon Member Functions 358

Writing Your Own Controls 359The Custom Control Declaration 360Adding DoGetBestSize 362Defining a New Event Class 363Displaying Information an the Control 363Handling Input 364Defining Default Event Handlers 364Implementing Validators 365Implementing Resource Handlers 367Determining Control Appearance 367A More Complex Example: wxThumbnailCtrl 369

Summary 371

13 Data Structure Classes 373Why Not STL? 373Strings 374

Using wxString 374wxString, Characters, and String Literals 375Basic wxString to C Pointer Conversions 375Standard C String Functions 376Converting to and from Numbers 377wxStringTokenizer 378wxRegEx 379

wxArray 379Array Types 379wxArrayString 380Array Construction, Destruction, and Memory Management 381Array Sample Code 381

wxList and wxNode 383

wxHashMap 385Storing and Processing Dates and Times 387

wxDateTime 388

wxDateTime Constructors and Modifiers 388wxDateTime Accessors 388Getting the Current Time 389Parsing and Formatting Dates 389Date Comparisons 389Date Arithmetic 389

Helper Data Structures 391wxObject 391

Contents

wxLongLong 392

wxPoint and wxRealPoint 392

wxRect 392

wxRegion 393

wxSize 394

wxVariant 394

Summary 395

14 Files and Streams 397

File Classes and Functions 397

wxFile and wxFFile 397wxTextFile 399wxTempFile 400

wxDir 400wxFileName 401File Functions 402

Stream Classes 403File Streams 403Memory and String Streams 405Reading and Writing Data Types 405Socket Streams 406Filter Streams 407Zip Streams 407Virtual File Systems 408

Summary 411

15 Memory Management, Debugging, and Error Checking 413Memory Management Basics 413

Creating and Deleting Window Objects 413Creating and Copying Drawing Objects 415Initializing Your Application Object 415Cleaning Up Your Application 416

Detecting Memory Leaks and Other Errors 416Facilities for Defensive Programming 418Error Reporting 419

wxMessageOutput Versus wxLog 423Providing Run-Time Type Information 424Using wxModule 426Loading Dynamic Libraries 427Exception Handling 428Debugging Tips 429

Debugging X11 Errors 429Simplify the Problem 430Debugging a Release Build 430

Summary 431

Contents xix

16 Writing International Applications 433Introduction to Internationalization 433Providing Translations 434

poEdit 434Step-by-Step Guide to Using Message Catalogs 435Using wxLocale 437

Character Encodings and Unicode 438Converting Data 439wxEncodingConverter 440wxCSConv (wxMBConv) 440Converting Outside of a Temporary Buffer 441Help Files 442

Numbers and Dates 443Other Media 443A Simple Sample 444Summary 446

17 Writing Multithreaded Applications 447When to Use Threads, and When Not To 447Using wxThread 448

Creation 449Specifying Stack Size 450Specifying Priority 450

Starting the Thread 450How to Pause a Thread or Wait for an External Condition 450Termination 451

Synchronization Objects 451wxMutex 451Deadlocks 452wxCriticalSection 453wxCondition 453

wxCondition Example 453wxSemaphore 456

The wxWidgets Thread Sample 456Alternatives to Multithreading 457

Using wxTimer 457Idle Time Processing 459Yielding 460

Summary 460

18 Programming with wxSocket 463Socket Classes and Functionality Overview 464Introduction to Sockets and Basic Socket Processing 464

The Client 465The Server 466

xxContents

Connecting to a Server 467

Socket Addresses 468

Socket Clients 468

Socket Events 469

Socket Event Types 469

wxSocketEvent Major Member Functions 469

Using Socket Events 470

Socket Status and Error Notifications 470

Sending and Receiving Socket Data 471

Reading 471

Writing 472

Creating a Server 472

wxSocketServer Major Member Functions 472Handling a New Connection Event 472

Socket Event Recap 473Socket Flags 473

Blocking and Non-Blocking Sockets in wxWidgets 474The Impossible Socket Combination 475

How Flags Affect Socket Behavior 475Using wxSocket as a Standard Socket 476

Using Socket Streams 476File Sending Thread 477File Receiving Thread 478

Alternatives to wxSocket 479Summary 480

19 Working with Documents and Views 481Document/View Basics 481

Step 1: Choose an Interface Style 483Step 2: Create and Use Frame Classes 483Step 3: Define Your Document and View Classes 486Step 4: Define Your Window Classes 495Step 5: Use wxDocManager and wxDocTemplate 497

Other Document/View Capabilities 500Standard Identifiers 500Printing and Previewing 500File History 500Explicit Document Creation 501

Strategies for Implementing Undo/Redo 501Summary 503

20 Perfecting Your Application 505Single Instance or Multiple Instances? 506Modifying Event Handling 510Reducing Flicker 512

Contents xxi

Implementing Online Help 513Using a Help Controller 515Extended wxWidgets HTML Help 517Authoring Help 518Other Ways to Provide Help 519Context-Sensitive Help and Tooltips 520Menu Help 521

Parsing the Command Line 521Storing Application Resources 523

Reducing the Number of Data Files 523Finding the Application Path 524

Invoking Other Applications 525Running an Application 525Launching Documents 525Redirecting Process Input and Output 527

Managing Application Settings 529Storing Settings 530Editing Settings 531

Application Installation 532Installation on Windows 532Installation on Linux 534

Shared Library Issues on Linux 535Installation on Mac OS X 535

Following UI Design Guidelines 538Standard Buttons 538Menus 538Icons 539Fonts and Colors 539Application Termination Behavior 539Further Reading 540

Summary 540

A Installing wxWidgets 543

B Building Your Own wxWidgets Applications 559

C Creating Applications with DialogBlocks 575

D Other Features in wxWidgets 585

E Third-Party Tools for wxWidgets 593

F wxWidgets Application Showcase 601

G Using the CD-ROM 611

xxii Contents

H How wxWidgets Processes Events 613

I Event Classes and Macros 617

J Code Listings 627

K Porting from MFC 643

Glossary 657

Index 663