QNX® PHOTON® MICROGUI® V6.3 PROGRAMMER’S GUIDE QNX Neutrino Realtime Operating System Photon microGUI Programmer’s Guide For QNX Neutrino 6.3.0 2005, QNX Software Systems 1995 – 2005, QNX Software Systems. All rights reserved. Printed under license by: QNX Software Systems Co. 175 Terence Matthews Crescent Kanata, Ontario K2M 1W8 Canada Voice: +1 613 591-0931 Fax: +1 613 591-3579 Email: [email protected] Web: http://www.qnx.com/ Publishing history November 1995 First edition December 1996 Second edition April 1998 Third edition July 2004 Fourth edition Electronic edition published 2005. Technical support options To obtain technical support for any QNX product, visit the Technical Support section in the Services area on our website (www.qnx.com). You’ll find a wide range of support options, including our free web-based Developer Support Center. QNX, Momentics, Neutrino, and Photon microGUI are registered trademarks of QNX Software Systems in certain jurisdictions. All other trademarks and trade names belong to their respective owners. Contents About This Guide xxxi Typographical conventions xxxiii Note to Windows users xxxiv What you’ll find in this guide xxxv What’s new in Photon for QNX Neutrino 6.3 xxxvii New content xxxvii What’s new in Photon for QNX Neutrino 6.2.1xxxviii New contentxxxviii Errataxxxviii What’s new in Photon for QNX Neutrino 6.2.0 xxxix New content xxxix What’s new in Photon for QNX Neutrino 6.0 xxxix 1 Introduction 1 Overview of the Photon architecture 3 Photon Application Builder (PhAB) 6 Widget concepts 8 Widget life cycle 13 Widget geometry 14 Programming paradigm 17 Text-mode application 18 Non-PhAB application 19 PhAB application 20 Photon libraries 21 API categories and libraries 21 October 6, 2005 Contents iii 2005, QNX Software Systems Versions and platforms 23 Building applications with PhAB — an overview 24 Step 1: Create modules 25 Step 2: Add widgets 25 Step 3: Attach callbacks 26 Step 4: Generate code 27 Step 5: Run your application 27 Step 6: Repeat any previous step 28 Writing applications without PhAB 28 2 Tutorials 29 Before you start... 31 Creating a Photon project and starting PhAB 31 PhAB’s Interface 32 Tutorial 1 — Hello, world 34 Creating the application 34 Generating code 36 Want more info? 38 Tutorial 2 — editing resources 38 Adding a button widget 39 Changing the bevel width 39 Changing the font 40 Changing the text alignment 42 Setting flags 43 Changing the fill color 44 Editing a pixmap 45 Editing multiline text 46 Editing a list of text items 48 Creating a template 50 Want more info? 53 Tutorial 3 — creating menus and menubars 54 About link callbacks 54 About instance names 55 iv Contents October 6, 2005 2005, QNX Software Systems Creating a menubar 55 Creating the File menu module 56 Adding menu items 57 Creating the Help menu module 59 Attaching link callbacks 59 Setting up the code 62 Want more info? 63 Tutorial 4 — creating dialogs 63 About dialogs 64 More on instance names 64 Attaching a dialog module 65 Adding widgets to the dialog 66 Adding a callback to the Done button 69 Modifying a generated code function 70 Compiling and Running 71 Want more info? 72 Tutorial 5 — creating windows 72 Creating a window 73 Attaching callbacks 73 Adding widgets 74 Generating and modifying the code 77 Compiling and running 81 Want more info? 81 3 PhAB’s Environment 83 Menus 85 File menu 85 Edit menu 86 Project menu 88 Build menu 89 Widget menu 91 View menu 92 Window menu 93 October 6, 2005 Contents v 2005, QNX Software Systems Help menu 94 Toolbars 95 Control panels 98 Widget palette 99 Modes (create vs select) 101 Resources panel 102 Callbacks panel 104 Module Tree panel 106 Module Links panel 108 Browse Files panel 109 Search dialog 111 Customizing your PhAB environment 112 General preferences 113 Color preferences 115 Dragging preferences 115 Grid preferences 116 4 Working with Applications 119 Creating an application 121 Opening an application 123 Saving an application 125 From the IDE 125 From standalone PhAB 126 Closing an application 128 Specifying project properties 128 Startup Windows tab 129 Generate Options tab 133 Run options 137 Build and Debug options 138 Importing files 139 Importing PhAB modules from other applications 140 Importing XBM images 140 Importing graphics images 141 vi Contents October 6, 2005 2005, QNX Software Systems Exporting files 141 5 Working with Modules 143 Module types 145 Anatomy of a module 145 Selecting a module 147 How modules are saved 148 Changing module resources 148 Creating a new module 148 Deleting a module 149 Iconifying modules 149 Displaying modules at run time 150 Positioning a module 150 Finding lost modules and icons 152 Window modules 152 Resizing a window module 153 Dialog modules 153 Resizing a dialog module 154 Predefined dialogs 154 Menu modules 155 Opening the menu editor 156 Specifying instance names 158 Creating hotkeys and shortcuts 158 Resizing a menu module 159 Creating command items 159 Creating submenu items 161 Creating separator items 161 Creating toggle items 162 Creating function items 162 Moving menu items 163 Using a menu module 163 Picture modules 164 Displaying a picture 165 October 6, 2005 Contents vii 2005, QNX Software Systems Using pictures as widget databases 166 Resizing a picture module 166 6 Creating Widgets in PhAB 167 Types of widgets 169 Instance names 170 Default instance name 170 When to assign a unique name 171 Instance names and translations 171 Duplicate names 172 Creating a widget 172 Creating several widgets 173 Canceling create mode 173 Selecting widgets 174 A single widget 174 Multiple widgets 175 Widgets within a group 178 Hidden widgets 178 Aligning widgets 179 To another widget 179 To a parent container 180 Distributing widgets 181 Common User Access (CUA) and handling focus 181 Changing focus with the keyboard 181 Controlling focus 182 Focus callbacks 183 Focus-handling functions 183 Ordering widgets 184 Dragging widgets 186 Setting a widget’s x and y coordinates 187 Transferring widgets between containers 187 Resizing widgets and modules 188 Clipboard 189 viii Contents October 6, 2005 2005, QNX Software Systems Cutting and copying 189 Pasting 191 Duplicating widgets and containers 192 Deleting widgets or modules 193 Matching widget resources and callbacks 193 Importing graphic files 195 Changing a widget’s class 196 Templates 196 Creating templates 197 Adding a widget class 199 Editing templates 201 Deleting templates 201 7 Editing Resources and Callbacks in PhAB 203 Editing widget resources 205 Pixmap editor 206 Setting the pixmap’s size 207 How to draw and erase 208 Choosing colors 208 Drawing freehand 209 Drawing lines, rectangles, and circles 209 Filling an enclosed area 209 Selecting an area 210 Nudging an area 210 Using the Pixmap toolbar 211 Other pixmap controls 211 Color editor 212 Full color editor 212 Quick color editor 214 Flag/choice editor 214 Flag resources 215 Option list resources 216 October 6, 2005 Contents ix 2005, QNX Software Systems Font editor 216 List editor 218 Editing existing list items 220 Deleting list items 220 Number editor 220 Text editors 221 Code editor 224 Layout editors 225 Fill layout info editor 225 Row layout info editor 226 Grid layout info editor: 227 Row layout data editor 228 Grid layout data editor 229 Callbacks 230 Editing callbacks 232 Module callbacks 234 Prerealize setup function 236 Postrealize setup function 236 Setup functions are stored in stub files 237 Code callbacks 237 Callback functions are stored in stub files 238 Hotkey callbacks 238 Hotkeys — the basics 238 Specifying the hotkey label 239 Specifying the callback 240 Processing hotkeys 242 Disabling hotkeys 242 Event handlers — raw and filter callbacks 244 8 Geometry Management 247 Container widgets 249 Geometry negotiation 249 Resize policy 251 x Contents October 6, 2005 2005, QNX Software Systems Absolute positioning 255 Aligning widgets using groups 256 Joining widgets into a group 257 Accessing widgets in a group 257 Aligning widgets horizontally or vertically 257 Aligning widgets in rows and columns 258 Using the Group flags 259 Splitting apart a group 261 Constraint management using anchors 262 Anchor resources 265 Using layouts 267 PtFillLayout 271 PtRowLayout 274 PtGridLayout 279 Using hints 291 Enforcing position or size constraints without anchors or layouts 295 9 Generating, Compiling, and Running Code 297 Using the Build menu 299 Building your application 300 Generating application code 302 What PhAB generates 303 Version control 305 Function prototypes 306 How application files are organized 309 Multiplatform applications 310 Single-platform applications 311 Converting to Eclipse 312 Editing source 312 Choosing an editor or browser 314 Creating a source module 314 October 6, 2005 Contents xi 2005, QNX Software Systems Changing the file display 314 Compiling and linking 315 Specifying additional libraries 315 Running make 316 Customizing the build process 317 Running the application 318 Debugging 319 Managing targets 320 The Build menu 321 Including non-PhAB files in your application 322 Eclipse Project applications 322 Multiplatform applications 322 Single-platform applications 323 Adding libraries 323 Making a DLL out of a PhAB application 324 Compiling and linking 324 Initializing your DLL 324 Unloading your DLL 326 10 Working with Code 327 Variables and manifests 329 Widget variables and manifests 329 Using the global variable and widget manifest 330 Handling multiple instances of a window 331 Internal link manifests 333 Global header file 333 Function names and filenames