QNX® Neutrino® Realtime Operating System Photon® Microgui Programmer’S Guide
Total Page:16
File Type:pdf, Size:1020Kb
QNX® Neutrino® Realtime Operating System Photon® microGUI Programmer’s Guide For QNX® Neutrino® 6.5.0 © 2010, QNX Software Systems GmbH & Co. KG. © 1995 – 2010, QNX Software Systems GmbH & Co. KG. All rights reserved. Published 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/ Electronic edition published 2010. QNX, Neutrino, Photon, Photon microGUI, Momentics, Aviage, and related marks, names, and logos are trademarks, registered in certain jurisdictions, of QNX Software Systems GmbH & Co. KG. and are used under license by QNX Software Systems Co. All other trademarks belong to their respective owners. Contents About This Guide xxv What you’ll find in this guide xxvii Typographical conventions xxviii Note to Windows users xxix Technical support xxx 1 Introduction 1 Overview of the Photon architecture 3 Photon Application Builder (PhAB) 5 Widget concepts 6 Widget life cycle 9 Widget geometry 11 Programming paradigm 13 Text-mode application 13 Non-PhAB application 14 PhAB application 15 Photon libraries 16 API categories and libraries 16 Versions and platforms 18 Building applications with PhAB—an overview 18 Step 1: Create modules 18 Step 2: Add widgets 19 Step 3: Attach callbacks 19 Step 4: Generate code 20 Step 5: Run your application 20 Step 6: Repeat any previous step 20 Writing applications without PhAB 21 2 Tutorials 23 Before you start... 25 Creating a Photon project and starting PhAB 25 PhAB’s Interface 26 Tutorial 1 — Hello, world 27 May 13, 2010 Contents iii © 2010, QNX Software Systems GmbH & Co. KG. Creating the application 27 Generating code 28 Want more info? 30 Tutorial 2 — editing resources 30 Adding a button widget 31 Changing the bevel width 31 Changing the font 32 Changing the text alignment 32 Setting flags 33 Changing the fill color 34 Editing a pixmap 35 Editing multiline text 36 Editing a list of text items 37 Creating a template 39 Want more info? 41 Tutorial 3 — creating menus and menubars 42 About link callbacks 42 About instance names 42 Creating a menubar 43 Creating the File menu module 44 Adding menu items 44 Creating the Help menu module 46 Attaching link callbacks 46 Setting up the code 48 Want more info? 49 Tutorial 4 — creating dialogs 49 About dialogs 50 More on instance names 50 Attaching a dialog module 50 Adding widgets to the dialog 51 Adding a callback to the Done button 53 Modifying a generated code function 54 Compiling and Running 55 Want more info? 55 Tutorial 5 — creating windows 56 Creating a window 56 Attaching callbacks 57 Adding widgets 57 Generating and modifying the code 59 Compiling and running 63 Want more info? 63 iv Contents May 13, 2010 © 2010, QNX Software Systems GmbH & Co. KG. 3 PhAB’s Environment 65 Menus 67 File menu 67 Edit menu 68 Project menu 69 Build menu 70 Widget menu 71 View menu 72 Window menu 72 Help menu 73 Toolbars 73 Control panels 76 Widget palette 77 Modes (create vs select) 79 Resources panel 80 Callbacks panel 81 Module Tree panel 82 Module Links panel 84 Browse Files panel 85 Search dialog 86 Customizing your PhAB environment 87 General preferences 88 Color preferences 89 Dragging preferences 90 Grid preferences 90 4 Working with Applications 93 Creating an application 95 Opening an application 96 Saving an application 98 From the IDE 98 From standalone PhAB 98 Closing an application 100 Specifying project properties 100 Startup Windows tab 101 Generate Options tab 104 Run options 107 Build and Debug options 108 Importing files 109 Importing PhAB modules from other applications 110 Importing XBM images 110 May 13, 2010 Contents v © 2010, QNX Software Systems GmbH & Co. KG. Importing graphics images 110 Exporting files 111 5 Working with Modules 113 Module types 115 Anatomy of a module 115 Selecting a module 117 How modules are saved 117 Changing module resources 117 Creating a new module 118 Deleting a module 118 Iconifying modules 118 Displaying modules at run time 119 Positioning a module 119 Finding lost modules and icons 121 Window modules 121 Resizing a window module 122 Dialog modules 122 Resizing a dialog module 122 Predefined dialogs 122 Menu modules 123 Opening the menu editor 123 Specifying instance names 125 Creating hotkeys and shortcuts 125 Resizing a menu module 126 Creating command items 126 Creating submenu items 127 Creating separator items 127 Creating toggle items 127 Creating function items 128 Moving menu items 129 Using a menu module 129 Picture modules 129 Displaying a picture 130 Using pictures as widget databases 130 Resizing a picture module 130 6 Creating Widgets in PhAB 131 Types of widgets 133 Instance names 133 Default instance name 134 vi Contents May 13, 2010 © 2010, QNX Software Systems GmbH & Co. KG. When to assign a unique name 134 Instance names and translations 135 Duplicate names 135 Creating a widget 135 Creating several widgets 136 Canceling create mode 136 Selecting widgets 136 A single widget 137 Multiple widgets 138 Widgets within a group 139 Hidden widgets 140 Aligning widgets 140 To another widget 141 To a parent container 141 Distributing widgets 141 Common User Access (CUA) and handling focus 142 Changing focus with the keyboard 142 Controlling focus 142 Focus callbacks 143 Focus-handling functions 143 Ordering widgets 144 Dragging widgets 145 Setting a widget’s x and y coordinates 147 Transferring widgets between containers 147 Resizing widgets and modules 147 Clipboard 148 Cutting and copying 148 Pasting 149 Duplicating widgets and containers 150 Deleting widgets or modules 150 Matching widget resources and callbacks 151 Importing graphic files 152 Changing a widget’s class 152 Templates 153 Creating templates 153 Adding a widget class 155 Editing templates 156 Deleting templates 157 7 Editing Resources and Callbacks in PhAB 159 Editing widget resources 161 May 13, 2010 Contents vii © 2010, QNX Software Systems GmbH & Co. KG. Pixmap editor 162 Setting the pixmap’s size 163 How to draw and erase 164 Choosing colors 164 Drawing freehand 164 Drawing lines, rectangles, and circles 165 Filling an enclosed area 165 Selecting an area 165 Nudging an area 165 Using the Pixmap toolbar 166 Other pixmap controls 166 Color editor 167 Full color editor 167 Quick color editor 168 Flag/choice editor 168 Flag resources 169 Option list resources 169 Font editor 170 List editor 171 Editing existing list items 172 Deleting list items 172 Number editor 172 Text editors 173 Code editor 175 Layout editors 176 Fill layout info editor 176 Row layout info editor 177 Grid layout info editor: 178 Row layout data editor 179 Grid layout data editor 180 Callbacks 181 Editing callbacks 182 Module callbacks 184 Prerealize setup function 185 Postrealize setup function 185 Setup functions are stored in stub files 185 Code callbacks 185 Callback functions are stored in stub files 186 Hotkey callbacks 186 Hotkeys — the basics 186 Specifying the hotkey label 187 viii Contents May 13, 2010 © 2010, QNX Software Systems GmbH & Co. KG. Specifying the callback 187 Processing hotkeys 189 Disabling hotkeys 189 Event handlers — raw and filter callbacks 190 8 Geometry Management 193 Container widgets 195 Geometry negotiation 195 Resize policy 196 Absolute positioning 199 Aligning widgets using groups 200 Joining widgets into a group 200 Accessing widgets in a group 200 Aligning widgets horizontally or vertically 201 Aligning widgets in rows and columns 201 Using the Group flags 202 Splitting apart a group 203 Constraint management using anchors 204 Anchor resources 206 Using layouts 208 PtFillLayout 210 PtRowLayout 212 PtGridLayout 216 Using hints 226 Enforcing position or size constraints without anchors or layouts 229 9 Generating, Compiling, and Running Code 231 Using the Build menu 233 Building your application 234 Generating application code 235 What PhAB generates 236 Version control 237 Function prototypes 238 How application files are organized 239 Multiplatform applications 240 Single-platform applications 241 Converting to Eclipse 242 Editing source 242 Choosing an editor or browser 243 Creating a source module 244 Changing the file display 244 May 13, 2010 Contents ix © 2010, QNX Software Systems GmbH & Co. KG. Compiling and linking 244 Specifying additional libraries 244 Running make 245 Customizing the build process 246 Running the application 246 Debugging 247 Managing targets 248 The Build menu 249 Including non-PhAB files in your application 249 Eclipse Project applications 250 Multiplatform applications 250 Single-platform applications 250 Adding libraries 251 Making a DLL out of a PhAB application 251 Compiling and linking 251 Initializing your DLL 251 Unloading your DLL 252 10 Working with Code 255 Variables and manifests 257 Widget variables and manifests 257 Using the global variable and widget manifest 258 Handling multiple instances of a window 258 Internal link manifests 260 Global header file 260 Function names and filenames 261 Initialization function 262 Processing command-line options 263 Module setup functions 264 Code-callback functions 266 Geometry data types 267 Timers 267 Using PtTimer 268 RtTimer* functions 268 Initializing menus 269 Enabling, disabling, or toggling menu items 269 Changing menu-item text 270 Generating menu items 270 Delaying and forcing updates to the display 275 Globally 275 For a specific container 275 x Contents May 13, 2010 © 2010, QNX Software Systems GmbH & Co. KG. Forcing updates 276 11 Manipulating Resources in Application Code 277 Argument lists 279 Setting