1<?xml version="1.0"?> 2<?xml-stylesheet href="docbook-css/driver.css" type="text/css" ?> 3<?xml-stylesheet href="haiku.css" type="text/css" ?> 4<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 5 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" > 6<book> 7 8<bookinfo> 9<date>9-1-2006</date> 10<title>Haiku Human Interface Guidelines</title> 11<subtitle>Better Known as "How <emphasis>NOT</emphasis> to Write Software</subtitle> 12<authorgroup> 13 <author>DarkWyrm</author> 14</authorgroup> 15</bookinfo> 16 17<chapter id="chapter1"> 18<title>How to Design Software Good</title> 19 20<para>Haiku is an operating system which is known for its speed and being easy 21 for anyone to use. This is partly because good programmers try to design 22 their apps for more than just themselves. We are going to examine how you 23 can also make your program more appealing. The reason is easy: easier to use 24 means more people using your program. Writing good software can be hard, but 25 it is worth the time and effort.</para> 26 27<sect1> <title>Who's Gonna Use It?</title> 28 29<para>You probably already know what kind of program you are going to write. If 30 not, put this book away and do some thinking first. Without a clear idea of 31 what you want, it's hard to do something about it. Once you know what 32 general kind of program you would like to create, you also need to figure 33 out who the program is meant for. This can be something as general as 34 'desktop users' to something as specific as 'Haiku Web Developers'. When you 35 know who the main users of your program will be, you can make certain 36 assumptions about what your users know. You can't necessarily expect a 37 musician to understand how to effectively use a 3D modelling program as 38 advanced as, say, 3D Studio Max, but you can expect them to have skills 39 which lend themselves to using a program for writing music.</para> 40 41<para>Depending on how concerned you are about details, you may even want to 42 create a user profile -- a fictional idea of an example user. This can 43 consist of just one or two sentences or can be several paragraphs. A short 44 user profile contains the person's first name, occupation, level of 45 expertise, and what kinds of things they want to be able to do with their 46 computer. One thing to be sure of is to make the user profile believable -- 47 like a person you might know. In fact, when you design your app, it may be 48 helpful if you know someone who fits into the target audience. You don't 49 want to design your app for that person specifically, but, rather, someone 50 just like them.</para> </sect1> 51 52<sect1> <title>What will the User be Doing?</title> 53 54<para>Most people will use your software to get work done, unless, of course, 55 you're writing the next hit game, and despite experiences you may have had 56 which might make you wonder, users are fairly intelligent. The saying that 57 no one reads manuals is mostly true: people generally have better things to 58 do than read software manuals except when either in trouble or as bathroom 59 reading. Try to keep in mind how busy most people are and how valuable their 60 time is to them when you are designing your program.</para> 61 62<para>In order to make doing work with your program easier, you need to 63 prioritize what kinds of work they will do in order of how often the work is 64 done. Come up with a list of tasks the user will be doing and put them into 65 one of 3 categories: Common, Uncommon, and Rare. Common tasks, 66 unsurprisingly, are those things which the user does all the time. In a word 67 processor, this would include typing in text, changing font sizes and 68 styles, and adjusting margins. Uncommon tasks are those which the user does 69 just from time to time. Depending on the user, this might be something like 70 printing labels, adding color to a table, or counting the words in the 71 document. Rare tasks are those which are done every once in a great while. 72 Often times, these tasks are ones which the user would quite likely not miss 73 if it were not possible to do it with your program. This would also be the 74 kinds of things that only 20 percent of your users or less would end up 75 using. If you do decide to include features to handle Rare tasks, think 76 carefully about each task's importance in the grand scheme of things before 77 deciding with any finality.</para> 78 79<para>To paraphrase Einstein, you must make your software as simple as possible 80 but no simpler. Complexity must be kept to a minimum. One major way this can 81 be done is by avoiding features which are used only in remote instances -- 82 the tasks in the Rare group. Design your application to meet the needs of 80 83 percent of your target audience. Features add complexity and complexity adds 84 difficulty.</para> </sect1> 85 86<sect1> 87<title>How will Your Users Do Their Work?</title> 88 89<para>Once you know who your users are and what they will be doing, you will 90 need to figure out how it will be done in a general sense. This does not 91 include what your program will actually look like, however. In a personal 92 finance application, one of the user's primary tasks will be entering in 93 transactions. The user will need to type in the data for each transaction or 94 download them from their bank over the Internet. You need to know this kind 95 of information for each task the user will have to perform, common or 96 otherwise.</para> 97 98<para>The actual implementation is determined last, which is why it has not been 99 discussed until now. This is where the general usage of the application is 100 determined. For example, the user will have a form to enter transactions 101 into an account. The form should have text fields for each of the different 102 kinds of data, such as the payee, the amount, and the check number. 103 Somewhere nearby, the user will be able to see a list of all the 104 transactions in the current account. Because this is where the actual 105 building of the look of the program takes place, it is crucial at this point 106 in development to know and understand what makes software truly easy to use, 107 so this is what we will examine next. Note that what technologies will be 108 used to actually create the program have not even been mentioned yet. For 109 your audience, technology is merely the means to an end -- a tool -- and not 110 the goal itself.</para> 111</sect1> 112 113<sect1> 114<title>Summary</title> 115 116<para>Careful planning is the key to writing excellent software, regardless of 117 what stage of development a project may be in. In order to be easy, good 118 software only has what is really needed. It also helps the user do their work 119 wherever possible. Only by thoroughly understanding what the work is, how it 120 is to be done, and who is doing it can a program provide the best experience 121 possible.</para> 122</sect1> 123 124</chapter> 125 126 127<chapter id="chapter2"> 128<title>Qualities of Good Software</title> 129 130<para>When it comes to software, the proof is in the usage. If a piece of 131 software requires significant time to learn, users will only invest the 132 time in learning it if (a) they have no other choice but to use that particular 133 software and (b) the importance of the need filled by the software is much 134 greater than the importance of the user's time. In short, users will learn 135 only what they must in order to do their job and even then only when forced to 136 do so.</para> 137 138 139<sect1> 140<title>Good Software Focuses on a User's Actual Needs</title> 141 142<para>In Chapter 1, it was mentioned that your program should meet the needs of 143 80 percent of your target audience. It is impossible to meet the needs of 144 all users in the same software and still retain some semblance of being easy 145 to use. Sometimes users don't even know that they need or don't need a 146 feature and it is up to the designer and developer to figure out what is 147 needed. Most often, it is better to have a small collection of more 148 specialized tools than one which does everything.</para> 149</sect1> 150 151<sect1> 152<title>Good Software Uses Everyday Language</title> 153 154<para>Jobs in the Information Technology industry are almost always professional 155 positions. One aspect which makes IT a profession is that it has its own 156 body of knowledge and terminology to go with it. Most people have only a 157 rudimentary 'computerese' vocabulary. The thing that they look at when they 158 use a computer is called a monitor or just 'the screen'; the little arrow on 159 the screen is called the cursor, and the thing they type with is called a 160 keyboard. Few users know (or care) what a 'file format' is and fewer still 161 do know what an 'invalid sector' on a floppy disk might be.</para> 162 163<para>Good programs use language appropriate for the audience. The problem is 164 that quite a lot of software intended for the general desktop user reads 165 like Yiddish for Joe User. In such cases, regular, everyday language should 166 be used as much as is possible. For file management software, 'volumes' are 167 really disks -- even though the term isn't quite accurate, a normal person 168 thinks a disk is a storage container and that volume is what you have up too 169 high at really good parties. Images are 'pictures'. A person doesn't 'kill' 170 a application that has 'hung' -- they 'force a frozen program to quit'. 171 Details like this may seem minor, but many small improvements in a program's 172 usability can have a profound effect overall. Of course, if your target 173 audience is IT professionals, these kinds of terms are perfectly acceptable. 174 Be sure that you match the everyday language of your audience and when in 175 doubt, err toward using less technical language.</para> 176</sect1> 177 178<sect1> 179<title>Good Software Does Not Expose Its Implementation</title> 180 181<para>Good software works a certain way because it is the best way to be done or 182 close to it, not because the code was written in a certain way or because it 183 was dictated by an underlying API. An example of this would be if a music 184 composition program has an easily-reached maximum song size because the code 185 monkey who wrote it used a 16-bit variable instead of a 32-bit one. While 186 there are sometimes limitations that cannot be overcome, the actual code 187 written and the architecture used when it was written should have as little 188 effect as possible on what the user sees and works with when using your 189 software.</para> 190</sect1> 191 192<sect1> 193<title>Good Software Uses Graphical Controls Properly</title> 194 195<para>GUI controls were meant to be used in certain ways, and when a program 196 does not use them in that particular way, it is confusing to the user and 197 possibly hazardous to the user's data. Check boxes, for example, are 198 commonly used in lists where a value can be turned on or off. Some programs, 199 however, uses them for choosing one option in a list even though radio 200 buttons are meant for this task. Text boxes should not be used for labelling 201 other controls. This might seem to be common sense for most, but, rest 202 assured, there are many programs which do not do something as simple as 203 this. In short, use standard controls the way they were intended.</para> 204</sect1> 205 206<sect1> 207<title>Good Software has a Natural Layout to its Controls</title> 208 209<para>Some tasks have a natural, logical workflow, and good programs are 210 designed in a way that capitalizes on this workflow. When entering an 211 address in the United States, the natural order is Name, Street and Number, 212 City, State, and Zip Code. Following any other order would both frustrate 213 the user and also lead to more mistakes in entering data. This also applies 214 to the Tab navigation order of controls in a window. Generally speaking, 215 this order should either be left-to-right, top-to-bottom or in a 216 counter-clockwise circle, depending on how the controls themselves are 217 placed and the expectations associated with the work to be done.</para> 218</sect1> 219 220<sect1> 221<title>Good Software Gives Plenty of Feedback</title> 222 223<para>Imagine for a moment that you have just started converting a movie file to 224 another format. You hit the button marked 'Go' and wait. Then you wait some 225 more. You go to the restroom, brew a new pot of coffee, get the mail from 226 the box, confirm that mullets are still out-of-style, and come back to wait 227 some more. You're sure you clicked the button, but nothing seems to be 228 happening. Did something go wrong? Only after some snooping around with a 229 file manager do you find out that everything is OK. You didn't know what was 230 happening because the program didn't tell you what it was doing.</para> 231 232<para>Good software keep the lines of communication open. Good feedback just 233 means making sure that the user knows what your program is doing at any 234 given time, especially if the program is busy doing something which makes 235 them wait. CD and DVD burning programs tell the user how much is left before 236 they are finished making a CD or DVD. File management programs tell how many 237 files are left to copy or move. Web browsers animate a little icon while 238 they download a web page. Users have a natural tendency to think that if 239 nothing seems to be happening, then the program is probably frozen. Making 240 sure that the user knows your program is hard at work puts their mind at 241 ease.</para> 242 243</sect1> 244 245<sect1> 246<title>Good Software Makes Errors Hard</title> 247 248<para>It has been said that nothing can be made foolproof because fools are so 249 ingenious. Even so, make it tough for the user to make a mistake. If, for 250 example, the user needs to enter in some text and certain characters are not 251 allowed, then disable those characters for the text box it needs to be 252 entered in instead of nagging the user with a message box. If resizing a 253 window horizontally should not be done for some reason, don't let the user 254 do it. Does your program require a selection from a list before the user 255 clicks OK? Tell the user that -- nicely, of course -- and then disable the 256 OK button until a selection is made. An even better solution would be to 257 select a good default choice for the user and give them the option to change 258 it. Build constraints into your application which prevent errors. This would 259 be why 3.5" floppy disks have a notch in one side -- it can be inserted into 260 a drive only one way. Constraints are also good for lazy developers because 261 then their software crashes less and they don't need to write as much 262 error-handling code.</para> 263</sect1> 264 265<sect1> 266<title>Good Applications Handle Errors Gracefully</title> 267 268<para>Even if you make it hard for a user to make a mistake, expect your program 269 to have to deal with errors. It is possible for a program to handle errors 270 in a way that doesn't leave the user wondering what happened. When code is 271 written, errors of all sorts need to be anticipated and handled, such as 272 lack of memory, lack of disk space, permissions errors, corrupted files, and 273 loss of network connectivity. As Murphy's Law states, if something can go 274 wrong in a given situation, it probably will. Hope for the best but prepare 275 for the worst: without bordering on the completely ridiculous, handle every 276 error that is likely to occur. Doing so greatly improves the perception of 277 your software by the outside world. Crashes are unacceptable in all cases. 278 Period. Error messages, for example, need to describe at the user's level of 279 expertise what happened and suggest what the user can do to remedy the 280 situation. In the worst case, the program needs to provide an easy way for 281 the user to send technical information about the problem back to you via 282 e-mail or some other means. In all cases, the user's data is to be 283 preserved.</para> 284 285<para>One way that you can see how well your program handles errors is to 286 deliberately try to break it in every way possible. Feed the entire text of 287 your Aunt May's quiche recipe into a text box all at once. Try to open files 288 it has no business being given. Take a valid document, back it up, open it 289 in DiskProbe, enter as much junk data into it as you like, and then try to 290 open it. Break your Internet connection while it's in the middle of an 291 update. Try to use files with really wonky filenames. Be creative and 292 ridiculous and, most of all, have fun breaking things!</para> 293</sect1> 294 295<sect1> 296<title>Good Software is Forgiving</title> 297 298<para>Computers are excellent tools for people because they are good at many 299 things that people are not. From a perspective which focuses on technology, 300 humans are imprecise, illogical, disorganized, and make mistakes frequently. 301 They are, however, excellent at forming habits and matching patterns, two 302 things computers have a difficult time doing. Make commands undoable 303 whenever possible and when it is not possible, be sure to inform the user 304 that such is the case. Capitalize on a computer's strengths to make up for a 305 person's inherent weaknesses.</para> 306</sect1> 307 308<sect1> 309<title>Summary</title> 310 311<para>Good software takes real work to produce. It is not for the stereotypical 312 'lazy programmer' unless they know where it is acceptable to be lazy. In 313 creating something of value to customers, good software creates a positive 314 image for a company and loyal customers who will do your own advertising for 315 you. The best advertising is done by your customers to their friends, 316 family, and coworkers.</para> 317</sect1> 318 319</chapter> 320 321<chapter id="chapter3"> 322<title>Conventions of Haiku</title> 323 324<para>Just as a person generally doesn't go barging into a stranger's home and 325 start redecorating and otherwise making himself at home merely because the 326 owner does not own a shotgun, your program needs to have good manners in 327 getting along with both the operating system and the other programs the user 328 has installed on the system. Some of these are merely good coding practices 329 meant to make your job easier and others are for ensuring that your program 330 can be more easily maintained. None of them are difficult or much work, so 331 there. Now you have no choice but to follow them. :D</para> 332 333 334<sect1> 335<title>Program Settings: Format and Location</title> 336 337<para>While there are lots of ways to store program settings, the easiest and 338 recommended method is placing them in a BMessage and flattening it to a 339 BFile. By using BMessages as your container, you don't have to concern 340 yourself with writing and debugging other code. The exact location used to 341 store them depends on the number of files you will need. If your software 342 needs only one file and will only ever need one, then it is just simplest to 343 place it in the user's config/settings folder. However, should you need more 344 than one file, please put them in their own folder to minimize the clutter. 345 The folder should either follow the format 346 home/config/settings/your_app_name_here or 347 home/config/settings/your_company_name_here/your_app_name_here.</para> 348</sect1> 349 350<sect1> 351<title>Maintain Responsiveness</title> 352 353<para>Probably the best-known quality about BeOS and Haiku as operating systems 354 is speed. This largely comes from the extensive use of multithreading in 355 applications. Being responsive does not necessarily mean that your program 356 should never be busy. It should just respond to input and redraw requests 357 even when it's doing something. A common experience encountered by Linux and 358 Windows users is the "blanking out" of a window or an entire program because 359 it is busy doing something else. This comes from two things: the program has 360 one thread of execution devoted to all its windows and that thread is busy 361 doing some sort of time-consuming work. Instead of falling into this trap, 362 which is unprofessional for you and confusing for the user, spawn another 363 thread to do the actual processing and allow the message-handling thread to 364 continue to do its job. This makes sure the user knows that your application 365 is still running properly and has not frozen.</para> 366</sect1> 367 368<sect1> 369<title>Avoid Hardcoded File Paths</title> 370 371<para>Whenever your program needs to specify a particular location on the 372 system, use of the find_directory() function to generate it. If and when the 373 day comes that Haiku supports multiple users, your application will make a 374 smooth transition to the new architecture. This will also allow for backward 375 compatibility with older versions of BeOS, such as the change in locations 376 for B_COMMON_FONTS_DIRECTORY being in a different place for Haiku than on 377 R5. find_directory() is supported in both C and C++ environments.</para> 378</sect1> 379 380<sect1> 381<title>Make Your App's Look Fits in with Others</title> 382 383<para>Certain function calls have been provided in the API to aid in making sure 384 that your software shares the same general look as other applications and 385 allow the user to make customizations to the system at the same time. Unless 386 there is a very good reason for it, get colors for your program with 387 ui_color() and the constants which go with it. Determine the size of your 388 controls dynamically - use the ResizeToPreferred and GetPreferredSize for 389 system controls and calculate the size of your own controls based on font 390 sizes obtained from the system instead of hardcoded values. If you're 391 writing code specifically for Haiku and don't care about compatibility with 392 other BeOS flavors, use the new layout API. All of this will allow better 393 ease-of-use for the user who prefers tiny fonts to increase use of desktop 394 real estate and also for older users who need larger font sizes to 395 accommodate weaker visual acuity. Graphics are an important part of a 396 program's look, but don't reimplement the look of the buttons and other 397 standard controls just to make your application stand out from the rest. By 398 keeping visual consistency with the rest of the operating system, you avoid 399 confusing the user with buttons that do not look like you can click on them, 400 strange-acting menus, and so forth.</para> 401</sect1> 402 403<sect1> 404<title>Live Updates</title> 405 406<para>One way to make sure that your application communicates effectively with 407 the user is to provide "live" updates to information in it. This mostly 408 relates to files in the system. A good example is an address book program 409 which automatically removes and adds entries when new People files are added 410 to the People folder. The information doesn't even have to be data that is 411 outside your program. It could just be as simple as updating an entry in a 412 list of items as the user types makes changes to it in a form in a different 413 part of the GUI. Responsiveness like this in a program helps the user feel 414 more in control of the work they are doing and prevents possible loss of 415 data.</para> 416</sect1> 417 418<sect1> 419<title>Translators</title> 420 421<para>Haiku comes with bits of technology that allows lazy programmers to be 422 lazy and still have their programs be good ones. One of them is the 423 Translation Kit. Merely including the library and making use of even 424 something as simple as the BTranslationUtils class will help to ensure that 425 at least this portion of your code is free of bugs. In general, you will 426 probably find yourself making use of image translators most in order to load 427 image resources that your program will use. Just remember that translators 428 are system add-ons and that unless your program has installed a translator 429 for a particular file format, depend only on the formats installed by 430 default in the system. As an aside, some formats are undocumented or require 431 licensing, which makes it difficult for users to access their own data. Use 432 open and documented formats as much as possible.</para> 433 434</sect1> 435 436<sect1> 437<title>Squeezing the Most Out of BFS: Queries and Attributes</title> 438 439<para>The filesystem that Be created was nothing short of amazing in the 1990s. 440 Even with the gradual evolution of other operating systems having progressed 441 since then, it is still one of the most powerful around. Attributes are a 442 powerful tool which allow you to store data about a file without being part 443 of the file. This kind of power is easily put to use with audio files, such 444 as FLAC, Ogg Vorbis, and the ubiquitous MP3. By attaching attributes to 445 audio files, you can search for them with a query. Queries also leverage the 446 filesystem's power. As long as the attribute you are querying for is indexed 447 in the filesystem, there is no place a file with that attribute can hide. To 448 top it all off, they are also a fast way of search for files meeting a 449 certain criteria.</para> 450 451<para>Although both attributes and queries are very powerful, use good sense. It 452 takes quite a while to read a large number of attributes from a file, so you 453 may wish to cache them if you are writing a program which will need to read 454 more than just a few of them. Queries can only make use of attributes which 455 are indexed, and their speed goes down as more and more attributes are 456 indexed.</para> 457</sect1> 458 459<sect1> 460<title>The System Tray: It's Not Just for Dinner Anymore</title> 461 462<para>Because it can very easily become cluttered, install icons in the 463 Deskbar's shelf only when it provides information that is updated often or 464 if it provides functionality which will be frequently accessed by the user. 465 Examples of these kinds of situations would be monitoring memory and 466 processor load, checking mail, or quick access to features provided by a 467 personal information management program. If it is unlikely that the user 468 will need to access the information or functionality less than once per 469 session, don't use the Deskbar -- accessing your program through the Be menu 470 or an icon on the desktop should be sufficient.</para> 471</sect1> 472 473<sect1> 474<title>Tracker and its Uses</title> 475 476<para>Tracker can be quite a useful tool for your program which requires little 477 effort to provide some courtesies to the user which would otherwise be a lot 478 of work. The Open and Save windows have already been done for you. Please 479 use them. If just a certain type of entry is needed, such as a 480 folder or specific type of file, make a filter that shows only those types 481 of entries. By removing unneeded items from the file navigation window, you 482 are reducing the number of choices the user must pick from and also 483 preventing him from opening the wrong kinds of files. Keep in mind that 484 there may be files that may not have had their MIME type identified, so do 485 not exclude them, either. You can also make Tracker show a window for a 486 particular folder in order to show the user where a particular file has been 487 stored and give them access to it directly.</para> 488</sect1> 489 490</chapter> 491 492<chapter id="chapter4"> 493<title>Getting Input from the User</title> 494 495<para>While it might seem a simple case to get input from the user, it is often 496 not the case if you wish to account for many external factors, such as 497 accessibility, speed, and user expertise.</para> 498 499 500<sect1> 501<title>Mouse Vocabulary, AKA "What's This Button Do?"</title> 502 503<para>The mouse, while the favorite rodent of most users, is not a very 504 intuitive device: mouse skills must be learned. Most of the time, mouse 505 skills are not an issue because the user is clicking on buttons, menus, and 506 so forth, but sometimes a program must deal directly with mouse clicks and 507 moves. Mouse operations fall into one of three categories.</para> 508 509<variablelist> 510<varlistentry><term>Skills you can expect the user to have:</term> 511<para> 512<itemizedlist> 513 <listitem>Single-click</listitem> 514 <listitem>Double-click on primary mouse button</listitem> 515 <listitem>Single click with secondary mouse button</listitem> 516 <listitem>Drag with primary mouse button</listitem> 517</itemizedlist> 518</para> 519</varlistentry> 520 521<varlistentry><term>Skills the user might have:</term> 522<para> 523<itemizedlist> 524 <listitem>Drag with secondary mouse button</listitem> 525 <listitem>Single-click with tertiary mouse button</listitem> 526 <listitem>Single-click on primary mouse button with modifier key</listitem> 527 <listitem>Triple-click with primary mouse button</listitem> 528 <listitem>Scroll with scroll wheel</listitem> 529 <listitem>Scroll with scroll wheel and modifier key</listitem> 530 <listitem>Drag with the tertiary mouse button</listitem> 531</itemizedlist> 532</para> 533</varlistentry> 534<varlistentry><term>Don't Use These:</term> 535<para> 536<itemizedlist> 537 <listitem>Click-and-a-half: Mouse down + mouse up + drag with a second mouse down</listitem> 538 <listitem>Multiple click with non-primary mouse button</listitem> 539 <listitem>More than 3 consecutive clicks (quadruple clicking or more)</listitem> 540 <listitem>Drag with tertiary mouse button</listitem> 541 <listitem>Drag with modifier keys</listitem> 542 <listitem>Secondary/Tertiary click with modifier keys</listitem> 543</itemizedlist> 544</para> 545</varlistentry> 546</variablelist> 547 548<para>In the event that your program must deal with directly handling mouse 549 input, there are certain rules of thumb for how each of the expected skills 550 is to be used. Single clicks are used for the most common actions in 551 operating a control. This would be selecting items in a list, pushing a 552 button, choosing a menu item, and placing the blinking text cursor in a 553 BTextView. Double clicks are used for secondary functions, such as invoking 554 an item in a BListView or selecting a word in a BTextView. Secondary mouse 555 clicks (most commonly called "right-clicking") are generally used for a 556 context-sensitive menu or, in the case of graphics programs, drawing with 557 the secondary color. Mouse dragging is used for selecting text or moving 558 things around. Mouse dragging with B_TERTIARY_BUTTON is generally used for 559 panning. The scroll wheel by itself should be used just for scrolling, but 560 your program may have a use for the scroll wheel when used with a modifier 561 key, as below:</para> 562 563<variablelist> 564<title>Scroll Wheel +</title> 565 566<varlistentry><term>B_COMMAND_KEY: </term><listitem>Zoom in/out</listitem></varlistentry> 567<varlistentry><term>B_OPTION_KEY: </term><listitem>Scroll by one full page</listitem></varlistentry> 568<varlistentry><term>B_CONTROL_KEY: </term><listitem>Increase/decrease font size</listitem></varlistentry> 569</variablelist> 570 571</sect1> 572 573<sect1> 574<title>Keyboard Accelerators: The Sports Cars of GUIs</title> 575 576<para>More advanced users often like using keyboard shortcuts for common tasks 577 because they reduce the considerable amount time spent switching between the 578 keyboard and the mouse.</para> 579 580<variablelist> 581<title>Standard System Accelerators:</title> 582 583<varlistentry><term>B_COMMAND_KEY + N: </term><listitem>New document</listitem></varlistentry> 584<varlistentry><term>B_COMMAND_KEY + O: </term><listitem>Open document</listitem></varlistentry> 585<varlistentry><term>B_COMMAND_KEY + S: </term><listitem>Save document</listitem></varlistentry> 586<varlistentry><term>B_COMMAND_KEY + Shift + S: </term><listitem>Save as… (show Save dialog window)</listitem></varlistentry> 587<varlistentry><term>B_COMMAND_KEY + P: </term><listitem>Print</listitem></varlistentry> 588<varlistentry><term>B_COMMAND_KEY + W: </term><listitem>Close active window</listitem></varlistentry> 589<varlistentry><term>B_COMMAND_KEY + Q: </term><listitem>Quit</listitem></varlistentry> 590 591<varlistentry><term>B_COMMAND_KEY + C: </term><listitem>Copy</listitem></varlistentry> 592<varlistentry><term>B_COMMAND_KEY + X: </term><listitem>Cut</listitem></varlistentry> 593<varlistentry><term>B_COMMAND_KEY + V: </term><listitem>Paste</listitem></varlistentry> 594 595<varlistentry><term>B_COMMAND_KEY + F: </term><listitem>Show find window</listitem></varlistentry> 596<varlistentry><term>B_COMMAND_KEY + G: </term><listitem>Find again</listitem></varlistentry> 597 598<varlistentry><term>B_COMMAND_KEY + B_OPTION_KEY + F: </term><listitem>Show Replace window</listitem></varlistentry> 599<varlistentry><term>B_COMMAND_KEY + L: </term><listitem>Replace and Find</listitem></varlistentry> 600 601<varlistentry><term>B_COMMAND_KEY + ,: </term><listitem>Settings window</listitem></varlistentry> 602 603<varlistentry><term>B_COMMAND_KEY + B: </term><listitem>(Word processor) Bold font</listitem></varlistentry> 604<varlistentry><term>B_COMMAND_KEY + U: </term><listitem>(Word processor) Underline font</listitem></varlistentry> 605<varlistentry><term>B_COMMAND_KEY + I: </term><listitem>(Word processor) Italicized font</listitem></varlistentry> 606<varlistentry><term>B_COMMAND_KEY + A: </term><listitem>Select all</listitem></varlistentry> 607 608<varlistentry><term>B_COMMAND_KEY + Z: </term><listitem>Undo</listitem></varlistentry> 609<varlistentry><term>B_COMMAND_KEY + B_SHIFT_KEY + Z: </term><listitem>Redo</listitem></varlistentry> 610 611<varlistentry><term>Tab / Shift + Tab: </term><listitem>Keyboard navigation</listitem></varlistentry> 612 613<varlistentry><term>B_CONTROL_KEY + Tab: </term><listitem>Switch programs</listitem></varlistentry> 614</variablelist> 615 616<para>When choosing keyboard accelerators for your program, use them only for 617 commonly-used tasks. Do not use one of the system combinations for a task 618 different from the list above. Doing so will only confuse and frustrate 619 users. Choose key combinations which are easily associated with the 620 functions that go with them. For example, Tracker uses Alt + Up to go to the 621 parent folder of the current window. The Command key should be the main 622 shortcut key. The Option key is generally used to modify an existing 623 shortcut with a closely related function. Command + F shows the Find window. 624 Command + Option + F shows the Replace window.</para> 625 626</sect1> 627<sect1> 628<title>Design to Prevent Fitts</title> 629 630<para>According to Mr. Fitts, when using a mouse or other pointing device, the 631 amount of time it takes to point to something is proportional to how far 632 away that something is and how big it is. While it might seem obvious, this 633 is often overlooked when a program is designed. The easiest places for a 634 user to click are the four corners of the screen and the pixel directly 635 under the cursor. The reason for this is because the mouse need not be moved 636 for to click on the pixel under it and the user does not have to think much 637 when moving the cursor to a corner because as soon as it reaches an edge, it 638 can go no farther in that direction regardless of how much the mouse is 639 moved. The Deskbar is in one corner of the screen for this reason.</para> 640 641<para>When you design the graphical interface for your program, make controls 642 easy to click on. Toolbars that have a text label as part of each button are 643 inherently easier to click because the labels add to the size of the 644 buttons. A number of existing image editing programs use the secondary mouse 645 button for a pop-up menu to access common features because the mouse doesn't 646 have to move in order to bring the menu up. Researchers have even 647 experimented with circular menus -- called pie menus -- which capitalize on 648 Fitts' Law in order to make a menu as fast as possible. Your program need 649 not go to such measures, but do keep in mind that teeny controls slow users 650 down.</para> 651 652</sect1> 653</chapter> 654 655<chapter id="chapter5"> 656<title>Dynamic Data Exchange: Pass Data Between Applications</title> 657 658 659<sect1> 660<title>Drag and Drop</title> 661 662<para>Not to be confused with falling reptiles, the ability of a user to click 663 on an object, drag it to some target, and drop it to make the target do 664 something with it is both familiar and empowering, just as are other direct 665 manipulation methods. Nonetheless, the drag-and-drop paradigm should be used 666 only where it makes sense to do so -- rearranging items in a list, file 667 management, opening a file dragged to your app from Tracker, etc.</para> 668 669<para>If you plan on supporting dragging within your program or to other 670 programs -- even just a little bit -- you should support drops to the most 671 probable targets in your program. This shouldn't normally be all that 672 difficult because drops to your program will come from either Tracker (in 673 the form of an entry_ref) or from within your own program. Drops from other 674 programs are not required, but if they are especially convenient, they can 675 be a nice bullet point in a marketing blurb for your program.</para> 676 677<para>When implementing dragging, be sure that your program provides feedback 678 about what is being dragged. This is often best done by using an image which 679 closely represents what is being dragged. If this is not possible, a 680 rectangle which is the size of the dragged item's selection should be used 681 in place of the picture.</para> 682 683<para>A feature which is very helpful to a user is drop feedback. Any time the 684 user is dragging something and the cursor passes over your program's window, 685 it can react in a way to show the user that your program will accept the 686 dragged object. Drop feedback can take a variety of forms: 687 688<itemizedlist> 689<listitem>A list control draws a line in between two items to show where 690 the dragged item would be placed if the user released the button.</listitem> 691 692<listitem>BTextView controls show a line where dragged text would be placed if 693 dropped.</listitem> 694 695<listitem>If the user drags an entry over a folder, Tracker shades it 696 slightly.</listitem> 697 698<listitem>A color well could highlight its border</listitem> 699</itemizedlist> 700 701There are other possible ways, but these should be enough for you to get the 702idea. As mentioned before, feedback is a Good Thing (TM). It allows the user to 703better understand how to use your program to get something done.</para> 704</sect1> 705 706<sect1> 707<title>The Clipboard</title> 708 709<para>Another way of getting data from one program into another is via the 710 system clipboard. Unlike other forms of data exchange, using the clipboard 711 requires very little effort or code because you have to do is plunk data 712 into a particular BMessage. Some of the standard controls already do it for 713 you. The BTextView class already implements copying, cutting, and pasting by 714 way of keyboard accelerators. In cases like these, all that you will want to 715 do is add some menu items for less advanced users.</para> 716 717<variablelist> 718 <title>Standardized Clipboard/Drag Data Formats</title> 719<varlistentry><term>Plain Text</term> 720 <listitem> 721 <para>It is easiest to describe the basics with this code snippet. 722 723 clipboard->AddData("text/plain", B_MIME_TYPE, your_text_string_here); 724 </para> 725 </listitem> 726</varlistentry> 727 728<varlistentry><term>Styled Text</term> 729 <listitem> 730 <para> 731 Use the same format as for plain text but add a text run array field to the 732 message also. You probably won't need to worry about this unless you're 733 writing a word processor or something similar. 734 735 clipboard->AddData("application/x-vnd.Be-text_run_array", B_MIME_TYPE, run_array, run_array_size); 736 </para> 737 </listitem> 738</varlistentry> 739 740<varlistentry><term>Generic File References</term> 741 <listitem> 742 <para>If the amount of data you wish to pass to another program is too large 743 to place on the clipboard without straining the system, dump the data to 744 a temporary file and place an entry_ref which points to it on the 745 clipboard instead. Audio and video files commonly suffer from this 746 problem. To do this, call AddRef() with the field name "refs" and add an 747 entry_ref pointing to the file you wish to pass this may. Multiple 748 entry_ref objects can be sent just by doing it more than once. If your 749 program is going to handle these kinds of drops file references, it 750 should look for multiple entries in the 'refs' field unless it would be 751 inappropriate to do so.</para> 752 </listitem> 753</varlistentry> 754 755<varlistentry><term>Image Data</term> 756 <listitem> 757 <para>If your program uses a different kind of data than what has already 758 been standardized, there are some guidelines you can follow so that 759 other programs can use it. First, make sure that the data that is put on 760 the clipboard is in as generalized a form as possible. 761 762 <segmentedlist> 763 <segtitle>Field Type</segtitle><segtitle>Name</segtitle><segtitle>Descriptions</segtitle> 764 <seglistitem><seg>B_STRING_TYPE</seg><seg>class</seg><seg>"BBitmap"</seg></seglistitem> 765 <seglistitem><seg>B_RECT_TYPE</seg><seg>_frame</seg><seg>A BRect containing the bounds of the bitmap data in pixels</seg></seglistitem> 766 <seglistitem><seg>B_INT32_TYPE</seg><seg>_cspace</seg><seg>The color_space constant for the image data, such as B_RGBA32</seg></seglistitem> 767 <seglistitem><seg>B_INT32_TYPE</seg><seg>_bmflags</seg><seg>The Flags() argument from BBitmap</seg></seglistitem> 768 <seglistitem><seg>B_INT32_TYPE</seg><seg>_rowbytes</seg><seg>The number of bytes per row, including padding</seg></seglistitem> 769 <seglistitem><seg>B_RAW_TYPE</seg><seg>_data</seg><seg>The raw image data</seg></seglistitem> 770 <seglistitem><seg>B_POINT_TYPE</seg><seg>be:location</seg><seg>The location from which the image data was copied. May be ignored.</seg> </seglistitem> 771 </segmentedlist> 772 773 </para> 774 </listitem> 775</varlistentry> 776</variablelist> 777</sect1> 778 779<sect1> 780<title>Replicants</title> 781 782<para>Replicants take their cue from Dolly the sheep in allowing a BView to be 783 cloned and allow you to do Really Neat Things(TM). As cool as replicant 784 technology is, it is only an emerging technology in other operating systems 785 and is unfamiliar to most users in general. As such, it is best left as an 786 extra feature and not the primary mode of operation for a program. Here are 787 some guidelines for using them, however. 788 789<orderedlist> 790<listitem>It is appropriate for program to be a replicant if it is a lightweight 791 program which provides information or a feature which the user will want to 792 be able to access frequently.</listitem> 793 794<listitem>Allow for the size of the dragger handle when computing layout</listitem> 795 796<listitem>Be sure it is big enough to not get lost when placed on a busy desktop 797 background. At the same time, do not take over the user's desktop unless he 798 wants this to happen. 32 pixels square is a good minimum size, for 799 example.</listitem> 800 801<listitem>Provide a reliable way for the user to control your replicant. Do not 802 rely on the menu provided by the dragger handle because the handle itself 803 may have been hidden. Instead, provide another means which is immediately 804 obvious or, at the very least, show a pop-up menu if the user clicks on it 805 (with either button) and there are no other clickable controls.</listitem> 806 807<listitem>Place a frame around the replicant's border so that it stands out from 808 its surroundings</listitem> 809 810<listitem>Do not make it too visually distracting. This mainly amounts to 811 avoiding lots of bright colors for the controls and limiting the amount of 812 animation and movement.</listitem> 813</orderedlist> 814 815</para> 816</sect1> 817</chapter> 818 819<chapter id="chapter6"> 820<title>Use of Text in the GUI</title> 821 822<para>Almost without exception, if you are writing a program, you will need to 823 pay at least a little attention to how it uses text. There are, believe it 824 or not, right ways and wrong ways, and while most of the guidelines for text 825 might seem trivial, paying attention to what seem like niggling little 826 details is what sets a good program apart from the rest.</para> 827 828<para>Above all else mentioned in this chapter, use language appropriate for 829 your audience -- most of the time, this means avoiding technical terms -- 830 and be both clear and concise.</para> 831 832<sect1> 833<title>Error Messages, or, "I'm sorry Dave, I'm afraid I can't do that"</title> 834 835<para>Perhaps the place where you should use text the most is in error messages. 836 They should appear as seldom as possible because you anticipated and handled 837 as many error conditions as possible and then tried to blow it up real good, 838 right? ;) When your program can't handle a particular error, the error 839 message given to the user should do the following: 840 841<orderedlist> 842<listitem>Explain what happened in everyday words.</listitem> 843 844<listitem>Provide enough information to know what happened without providing 845 details which could confuse the user. For example, if a mail client sends a 846 request to a server for e-mail and the server fails to respond, a way to 847 explain this might be something like "MyMailApp could not check your e-mail. 848 The mail server did not respond when contacted."</listitem> 849 850<listitem>Offer suggestions to help the user fix the problem, if possible. Using 851 the above example, one possible suggestion might be "Try checking your 852 Internet connection with your web browser. If your web browser works, the 853 mail server might not be working correctly and you may want to try again 854 later."</listitem> 855</orderedlist> 856</para> 857</sect1> 858 859<sect1> 860<title>…Ellipses…</title> 861 862<para>An ellipsis is a series of 3 dots (…) used to tell the user that a 863 control, often a menu item or button, will require further input. For example, a 864 menu item named "New…" will display a window which has the title "New". 865 However, if creating a new document does not require showing a window, then 866 an ellipsis should not be used. Please be sure to use the B_UTF8_ELLIPSIS 867 character instead of 3 periods. Most Haiku keymaps 868 allow you to type in an ellipsis with the Option + period keyboard 869 shortcut.</para> </sect1> 870 871<sect1> 872<title>Abbreviations, Acronyms, and Contractions, oh my!</title> 873 874<para>Sometimes space is at a premium. Abbreviations, acronyms, and contractions 875 can come in very handy in these instances, but they can also be confusing. 876 Whenever possible, avoid using them. Many times the reason there is not 877 enough space is it isn't being used as efficiently as possible. When you use 878 an abbreviation, please be sure that it is absolutely necessary, that it is 879 both common and clear, and that it is appropriate for your program's target 880 audience. For example, using the octothorpe (# symbol) as an abbreviation 881 for the word 'number' in the English language fits these criteria in 882 most cases. These same guidelines also apply to acronyms. For example, the 883 acronym CMYK (Cyan, Magenta, Yellow, Black) is acceptable in a color picker 884 for an image processing application designed for graphics professionals, but 885 not in one meant for children. Menus and button labels should never be 886 abbreviated or contain an acronym.</para> 887 888<para>Special care must be used with contractions. They can be a pitfall for 889 users who are not using a program in their native language. Because they 890 require a more advanced command of a language, avoid using them in a place 891 where their role is crucial in conveying the meaning of a message. For 892 example, a checkbox for a message dialog with a checkbox marked "Don't show 893 this message again" which is unchecked by default should be reworded "Always 894 show this message" and have the checkbox checked by default.</para> 895 896</sect1> 897 898<sect1> 899<title>Capitalization and Spelling</title> 900 901<para>Nothing is more unprofessional than spelling and capitalization errors. If 902 spelling is not your strong suit, consult a spell checker, dictionary, or at 903 least a friend. This is particularly important if you are working with a 904 language which is not your native one. Use sentence capitalization in all 905 places, that is, follow the normal grammar rules of the language. For 906 English, this means only to capitalize specific names like "Tracker" or 907 "Deskbar".</para> 908 909</sect1> 910<sect1> 911<title>Use of Fonts</title> 912 913<para>Good use of fonts can way make your program more visually appealing, but 914 when not used well, can make it ugly, hard to read, or worse. Stick to the 915 plain, bold, and fixed system fonts to maintain some general visual 916 consistency across the operating system. It is perfectly acceptable to use 917 different font sizes, but do it only when you need a heading or something 918 similar and try to limit the number of different sizes to just a few. A 919 window which has lots of different font styles and sizes is harder to read 920 and looks unprofessional. Control labels should always be in the system 921 plain font and size specified by the system.</para> 922 923<para>When calculating the layout for the controls, be sure that you do not 924 depend on the system font being set to a particular font size. Most 925 BControl-derived controls implement the methods GetPreferredSize and 926 ResizeToPreferred to take font size into account. A basic idea of the line 927 height for a font can be calculated by calling BFont::GetHeight() and adding 928 together the values of the font_height structure.</para> 929 930<para>Lastly, do not depend on the user having a particular font installed on 931 the system unless you are willing to ensure that the user has it installed 932 on the system. Font handling for your program is your responsibility, not 933 the user's. If you do follow this route, be sure to check to see if you have 934 redistribution rights for the font's license for the font in 935 question.</para> 936</sect1> 937 938<sect1> 939<title>Special Case: The Command Line</title> 940 941<para>When designing a program to work in a command-line environment there are 942 some special considerations which must be addressed. Interaction with other 943 programs, use in shell scripts, and a generally consistent interface for 944 command-line programs are just some of the things you will need to keep in 945 mind. The major design decisions you should make are how your program will 946 get its data, what options will be available, and what feedback the user 947 will be given.</para> 948 949<para>Spend some time thinking about how your program should interact with the 950 shell and with other programs. Most of the time, this will boil down to 951 whether your program is file-oriented or stream-oriented. Stream-oriented 952 programs like grep and less work pretty much like filters, getting data from 953 stdin and dumping data to stdout. File-oriented programs like zip and bzip2 954 are given a list of files which the program then operates on. Your program 955 can certainly do both, but choose a primary method because it will influence 956 design decisions later on. Seriously consider handling wildcards instead of 957 relying on the shell to do it for you if your program is file-oriented. This 958 does mean more work for you as a developer, but it also reduces typing and, 959 thus, typing errors for the user. Of course, if it doesn't make sense to 960 support wildcards, then don't do it.</para> 961 962<para>Choose options which are going to be accessible by command-line switches 963 carefully. Make each one available only if it fills a reasonably common 964 task. From the perspective of the user, adding an option is adding a 965 feature, which will, in turn, increase the complexity of your program. 966 Provide GNU-style (double dash + long name) switches for all options. The 967 most commonly-used options should also have a short (single-dash + single 968 letter) counterpart. The switches --help and -h are reserved for showing 969 help information. Only standard UNIX applications (ls, tar, df, etc.) are 970 not required to follow the standard for -h in order to avoid breaking 971 backward compatibility. All new command-line programs need to follow this. 972 Also, if your program requires one or more parameters, do the user a favor 973 and show the help message if there are no extra parameters instead of 974 telling the user to retype the command with the help switch.</para> 975 976<para>When an option requires a particular value, there is also a standard for 977 how the user is to provide the information. GNU-style command options should 978 follow the format --option=value with the option to enclose the value in 979 quotes. Multiple values for a switch should be comma-separated. Short-style 980 command options should place a space between each value that follows it like 981 this: -t value1 value2 value3 ... As mentioned above, wildcards should be 982 handled by the program except when it does not make sense. If your program 983 does something which modifies data, make sure that your program requires 984 some sort of parameter -- a switch, a file, or whatever -- so that data is 985 not lost if the user invokes your program without knowing what it does. You 986 can assume that the user is sharper than a bowling ball, but do not expect 987 the user to have expert knowledge of the operating system or, for that 988 matter, your program. Programs which merely report information -- ls and df 989 come to mind -- are not required to do this as long as the information 990 displayed gives the user an idea of what the program does.</para> 991 992<para>Be sure to give enough feedback when your program does its thing. Like 993 graphical programs, long tasks should inform the user of progress. This may 994 be something as complex as a full-fledged progress meter drawn with text, a 995 simple series of periods, a listing each file operated on, or something 996 else. *All* programs should provide some sort of feedback; the only time a 997 program may print nothing is if there is a "quiet" option which the user has 998 specified. The feedback your program gives doesn't even have to be 999 excessive; you can just give general details. A "verbose" option should 1000 provide more detail than the program does by default. As explained earlier 1001 in this chapter, error messages should be no more technical than absolutely 1002 necessary and should be helpful whenever possible. If your program requires 1003 a parameter of some sort and isn't given any, show either the same message 1004 as for the help option or an abbreviated version which is still reasonably 1005 informative along with something to point the user to the help option for 1006 more detailed information.</para> 1007 1008</sect1> 1009</chapter> 1010 1011<chapter id="chapter7"> 1012<title>Branding - Program Icons, About Windows, Graphics, and Other Visuals at the OK Corral</title> 1013 1014<para>With all this discussion, you may be beginning to think that having a 1015 well-designed program means that it is going to be boring to look at. You 1016 can definitely have it more interesting to look at than drying paint. There 1017 is plenty of freedom for creativity along with some suggestions to help get 1018 you started.</para> 1019 1020<sect1> 1021<title>Program Icons</title> 1022 1023<para>Your program's icon is one easy way to set it apart from the rest of the 1024 pack. BeOS-style icons follow one of two perspectives - flat and isometric. 1025 Flat icons look like a head-on view. Isometric icons "look down" on the icon 1026 from a point above and to the right of the object with angled lines being 1027 about 30 degrees from horizontal. A good icon can give your program a 1028 favorable and professional impression to people who otherwise doesn't know a 1029 thing about you or your program. Take some time to create or find a 1030 good-looking icon. Whatever you do, don't just slap together a 1031 shabby-looking icon. It would be better not provide an icon at all and rely 1032 on the system to show the default application icon than to have one which 1033 reflects poorly on your program's reputation. For more details on icon 1034 creation, consult the Haiku Icon Guidelines. </para> 1035 1036<variablelist> 1037<title>Design Tips</title> 1038<varlistentry> 1039<orderedlist> 1040<listitem>Remember that this will be small -- don't use too much detail.</listitem> 1041<listitem>Use color combinations pleasing to the eye.</listitem> 1042<listitem>Tie it into the general color scheme of your program if it has one.</listitem> 1043</orderedlist> 1044</varlistentry> 1045</variablelist> 1046 1047</sect1> 1048<sect1> 1049<title>About Windows… Doorways to Creative Expression</title> 1050 1051<para>Give yourself some credit in your program: make an About window. They 1052 don't need to be especially fancy, but they can be if you are so inclined. 1053 It should contain the title of your program, the version, you and any other 1054 authors or the name of your company, and copyright information. If nothing 1055 else, write a few lines of code to show a BAboutWindow with this information 1056 and you'll have enough. If there is a lot of information to show, using a 1057 marquee effect to automatically scroll the information or at least a 1058 read-only text view with a scroll bar. Do not include information about the 1059 computer itself, such as the amount of RAM or processor speed; it doesn't 1060 belong here. While you certainly may show something short about the 1061 licensing of your program like "Distributed under the terms of the GNU 1062 Public License," the full text of the license belongs elsewhere. The window 1063 should not have a tab and should either have a button marked 'Close' or 1064 simply disappear when clicked. It should also respond to the Command + W 1065 keyboard shortcut.</para> 1066 1067</sect1> 1068<sect1> 1069<title>Graphics and Other Stuff</title> 1070 1071<para>Graphics need not be limited to just the About window and the program 1072 icon. You can also use background images in BViews, toolbars, buttons, and 1073 other places. There are few hard-and-fast rules here, but there are some 1074 tips you might find useful: 1075 1076<orderedlist> 1077<listitem>Follow the Dos and Don'ts for toolbars mentioned in Chapter 12</listitem> 1078<listitem>Background images should not be too busy and should not reduce overall readability.</listitem> 1079<listitem>If your program uses only a few small pictures, you may want to 1080 package them in a resource file to prevent them from somehow coming up 1081 missing in the installation on a user's machine. Crazy things happen on 1082 people's computers.</listitem> 1083</orderedlist> 1084 1085</para> 1086</sect1> 1087</chapter> 1088 1089<chapter id="chapter8"> 1090<title>Cursors</title> 1091 1092<sect1> 1093<title>Predefined Cursors and their Uses</title> 1094 1095<para>There are predefined cursor icons in Haiku for a variety of uses, 1096 including text selection, hyperlinks, resizing, and the default hand used 1097 for anything else.</para> 1098</sect1> 1099 1100<sect1> 1101<title>Making Your Own Cursors</title> 1102 1103<para>You can very easily make your own cursors for your own purposes, but do it 1104 only if a different cursor will dramatically improve how well the user can 1105 work with your program. At the moment, cursors can only be 16 pixels square. 1106 Be sure that the hot spot -- the actual 1107 location passed to applications when a mouse button is pressed -- is very 1108 obvious. Good hot spots are the tip of the hand cursor, the point of an 1109 arrow, or the center of a crosshairs. Use the full dimensions available to 1110 increase the cursor's visibility at high screen resolutions.</para> 1111 1112<para><emphasis>NOTE:</emphasis> There is not nor will there ever be a busy 1113 cursor in BeOS-based operating systems. This is a deliberate design 1114 decision. If you have a need for a busy cursor, you need to make your 1115 program more responsive. Often you can use multiple threads to eliminate the 1116 need for a busy cursor.</para> 1117</sect1> 1118 1119<sect1> 1120<title>Animating Cursors</title> 1121 1122<para>While Haiku does not provide explicit support for them, you can animate 1123 cursors to provide a little more graphical appeal. As with any kind of 1124 movement in the display, use animation sparingly so that it is not 1125 distracting.</para> 1126</sect1> 1127</chapter> 1128 1129<chapter id="chapter9"> 1130<title>Menus, Menu Bars, and Menu Fields</title> 1131 1132<para>Menus are everywhere, but common as they may be, far too many programs 1133 could use them better. Attention to small details in a program's menus is 1134 one common difference between good programs and great ones. A developer can 1135 pack a lot of features into a small space and still not force the user to 1136 remember it all. Menus afford exploration of the interface in steps. This 1137 chapter will focus primarily on issues related to menus in general. Pop-up 1138 menus and menu fields are discussed in Chapter 12.</para> 1139 1140<sect1> 1141<title>Naming and Organization</title> 1142 1143<para>Choosing good names for menus and menu items is generally not difficult. A 1144 menu should have a name which is short and accurately describes the kinds of 1145 items it contains. For instance, a File menu should not have Copy and Paste 1146 items in it. The name for a menu item should both concisely and accurately 1147 describe the function it performs. Items are capitalized as described in 1148 Chapter 6 and an ellipsis is used with any item which requires further 1149 action. If a menu item opens a window, the names of both the item and the 1150 window should be the same.</para> 1151 1152<para>Two ways to organize menus are the Noun-Verb method and the Verb-Noun 1153 method. Noun-Verb names menus after the kind of object that it operates on 1154 and items in the menu are actions which can be performed on the object. For 1155 example, the File menu contains items such as Open, Print, Save, and Close. 1156 Verb-Noun names menus with an action and the items are objects which the 1157 action can be performed on. Two example menus could be View and Go. Some 1158 "standardized" menus, such as the Edit menu, do not follow either 1159 method.</para> 1160 1161<para>Items should be organized and grouped by function and/or attribute. Use a 1162 separator item between each item group. An example of this would be an Edit 1163 menu which looks like this: 1164 1165<literallayout> 1166 _________ 1167 | Edit | 1168 |-------| 1169 | Undo | 1170 | Redo | 1171 |-------| 1172 | Cut | 1173 | Copy | 1174 | Paste | 1175 |_______| 1176</literallayout> 1177</para> 1178 1179<para>Undo and Redo perform related, though opposite, functions. Cut, Copy, and 1180 Paste are all clipboard functions, so the belong in a group separate from 1181 Undo and Redo. A font menu would group font styles together. When organizing 1182 the menus in a menu bar, try to have a logical progression from one menu to 1183 another. A financial program might have these menus: Program, File, Account, 1184 Transaction, and Help.</para> 1185 1186<para>Submenus are another possibility for grouping menu items, particularly for 1187 attributes. They should be avoided when other options exist because they 1188 slow the user down and also add complexity to the interface. 1189 Users may also have trouble navigating to submenus because of the fine 1190 motor skills required. If your submenu has 6 or more items in it, consider 1191 placing them in their own top-level menu.</para> 1192</sect1> 1193 1194<sect1> 1195<title>Marking and Toggling Items</title> 1196 1197<para>Menus can also contain items which indicate the state of a feature, such 1198as the visibility of a tool window. The preferred method is to place a checkmark 1199beside the item indicating the positive state. This is less confusing than to 1200dynamically change menu item labels and has the advantage that it can be used 1201for choosing from more than two states at the expense of screen space. When 1202there are more than two states, all possible states need to be listed in order 1203to prevent confusion.</para> 1204 1205<literallayout> 1206<emphasis>Examples of Good Toogling/Multiple State Item Usage</emphasis> 1207 1208|Help| 1209----------------------- 1210Open manual… 1211----------------------- 1212* Show tooltips 1213----------------------- 1214Go to the MyApp website 1215----------------------- 1216 1217|Font| 1218----------------------- 1219Choose font and size… 1220----------------------- 1221* Normal 1222 Bold 1223 Italics 1224 Bold italics 1225 Strikeout 1226 Underline 1227----------------------- 1228</literallayout> 1229 1230</sect1> 1231<sect1> 1232<title>Common Menus and their Contents</title> 1233 1234<para>Below are descriptions for menus that are common to many programs. Because 1235 they are so common, there are some guidelines to their use so that there is 1236 some consistency from program to program. With the exception of the Program 1237 menu, each of these menus should be used only if they make sense for your 1238 program.</para> 1239 1240<variablelist> 1241<title>Program: Items related to operating on the program itself.</title> 1242 1243<varlistentry><term>About <app name here>… </term><listitem><para>Shows 1244 the About window. This is not a commonly-accessed item, so do not provide a 1245 keyboard shortcut for it.</para></listitem></varlistentry> 1246 1247<varlistentry><term>Settings…</term><listitem><para>Show the 1248 window which is used to customize settings for your program. This can be a 1249 submenu if your program only has a couple of settings.</para></listitem> 1250</varlistentry> 1251 1252<varlistentry><term>Quit (Command + Q) </term><listitem><para>This should be the 1253 bottom item in the menu and a separator should go above it. Clicking on this 1254 item should close all windows and quit the program.</para></listitem></varlistentry> 1255</variablelist> 1256 1257<variablelist> 1258<title>File: This contains items related to documents handled by your program.</title> 1259 1260<varlistentry><term> 1261New (Command + N) </term><listitem><para>Create a new document. This item should 1262 have an ellipsis if it shows a window asking for further information (for 1263 example, canvas size for a drawing program), but not if it 1264 doesn't.</para></listitem></varlistentry> 1265 1266<varlistentry><term> 1267Open… (Command + O) </term><listitem><para>Open a document from disk.</para></listitem></varlistentry> 1268 1269<varlistentry><term> 1270Open recent </term><listitem><para>This is a submenu in the File menu to allow 1271 fast access to recent documents. It should not open a window of any kind 1272 except if your program uses a one-window-per-document architecture. The 1273 number of recent items should be limited to no more than 5 1274 items.</para> 1275</listitem></varlistentry> 1276 1277<varlistentry><term> 1278Close (Command + W) </term><listitem><para>The function of this item depends on 1279 the program architecture. In a program which has one document per window, 1280 this closes the window. If there is only one open window, this quits the 1281 program. Although it is not recommended, if a program allows for multiple 1282 documents to be shown in the same window, this item closes one 1283 document.</para> 1284</listitem></varlistentry> 1285 1286<varlistentry><term> 1287Save (Command + S) </term><listitem><para>Save the current document. This should 1288 not show a window unless it is a new document that has not yet been saved. 1289 It does not normally show a window, so no ellipsis is 1290 necessary.</para> 1291</listitem></varlistentry> 1292 1293<varlistentry><term> 1294Save as… (Command + Shift + S) </term><listitem><para>This performs the same 1295 basic kind of task as Save, but it always shows a 1296 window.</para> 1297</listitem></varlistentry> 1298 1299<varlistentry><term> 1300Save all </term><listitem><para>This item executes a Save command for all 1301 documents in the program. The procedure for handling new documents which 1302 have not yet been saved is as follows: <para> 1303 <orderedlist> 1304 <listitem>Remember the current document window</listitem> 1305 <listitem>For each document needing a name, bring it to the front, open a 1306 Save window, save the document, and proceed to the next document needing 1307 a name.</listitem> 1308 <listitem>When all documents have been processed, bring the window which was 1309 originally the active one back to the front.</listitem> 1310 </orderedlist> 1311 Note that the same procedure is to be applied when closing the program. 1312 </para> 1313</para></listitem></varlistentry> 1314 1315<varlistentry><term> 1316Revert </term><listitem><para>Undoes all changes made to the document since the 1317 last save.</para> 1318</listitem></varlistentry> 1319 1320<varlistentry><term> 1321Import from… </term><listitem><para>Import data from another file format into a 1322 new document. Like Open…, this always shows a 1323 window.</para></listitem></varlistentry> 1324 1325<varlistentry><term> 1326Export to… </term><listitem><para>Convert the data in the current document to 1327 another format. Like Save as…, this always shows a 1328 window. This should be reserved for lossy conversions. If your program 1329 can save its data in multiple formats without any information loss, 1330 these should be available in the Save and Save as… menu items instead.</para> 1331</listitem></varlistentry> 1332 1333<varlistentry><term> 1334Page setup… </term><listitem><para>Shows the page settings window for printer 1335 setup.</para> 1336</listitem></varlistentry> 1337 1338<varlistentry><term> 1339Print… (Command + P) </term><listitem><para>This always shows the print window 1340 before printing the current document. This is not intended to be the same as 1341 when a toolbar button is pressed.</para> 1342</listitem></varlistentry> 1343</variablelist> 1344 1345 1346<variablelist> 1347<title>Edit: Items in this menu are used for different editing tasks</title> 1348 1349<varlistentry><term> 1350Undo (Command + Z) </term><listitem><para>Undoes the most recently performed 1351 edit. When possible, this item should be dynamic and also include the name 1352 of the task that it would undo, such as 'Undo Cut' or 'Undo Typing.' User 1353 operations which do not change document data, such as changing zoom levels 1354 or the like, should not be included in Undo 1355 operations.</para></listitem></varlistentry> 1356 1357<varlistentry><term> 1358Redo (Command + Shift + Z) </term><listitem><para>Undoes the most recent Undo 1359 operation. Like Undo, this menu item should also be dynamic when 1360 possible.</para></listitem></varlistentry> 1361 1362<varlistentry><term> 1363Cut (Command + X) </term><listitem><para>Copies the currently-selected data in 1364 the current document to the clipboard and removes it from the 1365 document.</para></listitem></varlistentry> 1366 1367<varlistentry><term> 1368Copy (Command + C) </term><listitem><para>Copies the currently-selected data in 1369 the current document to the clipboard.</para></listitem></varlistentry> 1370 1371<varlistentry><term> 1372Paste (Command + V) </term><listitem><para>Inserts the data on the clipboard 1373 into the current document. If there is an existing selection in the current 1374 document, the paste operation replaces the selected data with the pasted 1375 data. Like undo and redo, this menu item should be dynamic according to 1376 the clipboard content ('Paste Text' or 'Paste Image')</para> 1377</listitem></varlistentry> 1378 1379<varlistentry><term> 1380Select all (Command + A) </term><listitem><para>Selects all data in the current 1381 document.</para></listitem></varlistentry> </variablelist> 1382 1383 1384<variablelist> 1385<title>Search: Tasks in this menu include finding and replacing data and other 1386 navigation commands.</title> 1387 1388<varlistentry><term> 1389Find… (Command + F) </term><listitem><para>This always shows a Find window for 1390 the program. The Find window should then allow the user to choose whatever 1391 options he desires for the find and disappear when the actual find is 1392 executed.</para></listitem></varlistentry> 1393 1394<varlistentry><term> 1395Find again (Command + G) </term><listitem><para>This repeats the most recent 1396 Find. If no find has been performed in the program yet, it should show the 1397 Find window. Because this command does not normally show a window, no 1398 ellipsis is needed.</para></listitem></varlistentry> </variablelist> 1399 1400 1401<variablelist> 1402<title>Help: Different ways that the user can learn more about your program and 1403 get help when needed.</title> 1404 1405<varlistentry><term> 1406Open manual… </term><listitem><para>Shows the manual for the program in a new 1407 window. The manual should never be shown in a BAlert, prefer opening an 1408 HTML or read-only text file (using the preferred application set by the 1409 user), or showing a non-editable text view from which the text can 1410 be copied.</para></listitem></varlistentry> 1411 1412<varlistentry><term> 1413Go to (MyApp or MyCompany)'s website </term><listitem><para>Opens the default 1414 web browser at the website for the program or the program's company, 1415 respectively.</para></listitem></varlistentry> </variablelist> 1416 1417</sect1> 1418</chapter> 1419 1420<chapter id="chapter10"> 1421<title>Windows</title> 1422 1423<sect1> 1424<title>You Need the Basics</title> 1425 1426<para>Windows are such common controls that every developer should know the 1427 basics of how to use them properly. Some operating systems suffer from the 1428 overuse and abuse of windows, such as bizarre error messages, incessant 1429 confirmations, wrong window types for tasks, and many other mistakes. Learn 1430 the proper ways of working with windows and you will have overcome a major 1431 usability hurdle.</para> 1432</sect1> 1433 1434<sect1> 1435<title>Styles and Purpose</title> 1436 1437<para>Haiku allows you to specify the look and feel when creating a window. 1438 Setting these properly will help the user immediately know what kind of 1439 window they are dealing with, and it also restricts the operations 1440 they are allowed to perform on it.</para> 1441 1442<segmentedlist> 1443<segtitle>Look</segtitle><segtitle>Purpose</segtitle> 1444<seglistitem><seg>Document</seg><seg>Windows containing a user document, such as an editor or viewer</seg></seglistitem> 1445<seglistitem><seg>Titled</seg><seg>General purpose</seg></seglistitem> 1446<seglistitem><seg>Floating</seg><seg>Tool and utility windows</seg></seglistitem> 1447<seglistitem><seg>Modal</seg><seg>Modal window</seg></seglistitem> 1448<seglistitem><seg>Bordered</seg><seg>Alert-type dialog windows</seg></seglistitem> 1449<seglistitem><seg>Borderless</seg><seg>Splash screens</seg></seglistitem> 1450</segmentedlist> 1451 1452<segmentedlist> 1453<segtitle>Feel</segtitle><segtitle>Purpose</segtitle> 1454<seglistitem><seg>Normal</seg><seg>General purpose</seg></seglistitem> 1455<seglistitem><seg>Modal:Subset</seg><seg>Only when you need to block all windows in a subset</seg></seglistitem> 1456<seglistitem><seg>Modal:App</seg><seg>When a user decision is required to continue with the rest of the program</seg></seglistitem> 1457<seglistitem><seg>Modal:All</seg><seg>When the user needs to make a 1458 system-critical decision, such as system shutdown confirmation. Use this 1459 feel only when you absolutely have to.</seg></seglistitem> 1460<seglistitem><seg>Floating:Subset</seg><seg>When a subset window needs to take 1461 priority in its subset.</seg></seglistitem> 1462<seglistitem><seg>Floating:App</seg><seg>Tool and utility windows</seg></seglistitem> 1463<seglistitem><seg>Floating:All</seg><seg>System monitors and other windows which 1464 the user will always want to have visible. Like Modal:All, use this only 1465 when absolutely necessary.</seg></seglistitem> </segmentedlist> 1466 1467<segmentedlist> 1468<segtitle>Type</segtitle><segtitle>Look + Feel</segtitle> 1469<seglistitem><seg>Titled</seg><seg>Titled + Normal</seg></seglistitem> 1470<seglistitem><seg>Document</seg><seg>Document + Normal</seg></seglistitem> 1471<seglistitem><seg>Modal</seg><seg>Modal + Modal:App</seg></seglistitem> 1472<seglistitem><seg>Floating</seg><seg>Floating + Floating:App</seg></seglistitem> 1473<seglistitem><seg>Bordered</seg><seg>Bordered + Normal</seg></seglistitem> 1474</segmentedlist> 1475 1476<para>Probably 90% of the time you will end up using Titled and Document windows 1477 with an occasional floating window. Borderless windows are used frequently 1478 for splash windows that are displayed as a program is loading. Bordered 1479 windows, which, by the way, do not have a window tab, aren't used much 1480 except in BAlerts. Modal windows shouldn't be used more than is absolutely 1481 necessary for reasons explained under the Modality section in this 1482 chapter.</para> </sect1> 1483 1484<sect1> 1485<title>Naming, Placement, Size, and Other Decisions</title> 1486 1487<para>Merely knowing what kind of window look and feel to use in a given 1488 situation is not enough: you also have to be aware of resizing, zooming, 1489 moving, closing, and minimizing because they affect your program in 1490 different ways. Once you know what kind of window you need, you should also 1491 figure out what its initial size and location are going to be. You also 1492 should not restrict the other actions a user can perform on a window unless 1493 you have a good reason that does not include "I don't want to write code to 1494 handle this."</para> 1495 1496<para>Care should be given to what name is used for a window. The main window of 1497 your program should include your program's name. Windows which were opened 1498 from a menu item should have the same name as that of the menu item without 1499 the ellipsis. Document windows should include the document's name. The first 1500 new document in the application should use the name "Untitled" with 1501 subsequent new documents appending a number. A titled window should never 1502 have an empty title bar.</para> 1503 1504<para>The size of a window depends on a number of factors. An application window 1505 should have an initial size which is the minimum needed to see all controls 1506 in it without overcrowding. Controls should never overlap. This initial size 1507 should also be the minimum size for the window which is passed to 1508 SetSizeLimits. The initial size for a document window should be large enough 1509 to see the entire document or at least a significant portion of the document 1510 if it is larger than the screen. Do not arbitrarily restrict resizing unless 1511 it does not make sense to allow resizing in a particular direction. If a 1512 window allows resizing, its size should generally be saved when closed or 1513 the program quits and restored to that size when shown again.</para> 1514 1515<para>Zooming is similar to resizing, but there are differences in which should 1516 permit zooming and how it should be done. Utility windows, for example, are 1517 not intended to be the main focus of the program, so they should not allow 1518 zooming even though they should allow resizing except where inappropriate. 1519 Document windows should expand to fill the most sensible space to allow 1520 viewing or editing. Often times this is the entire screen, but some for 1521 some programs, this doesn't make sense. An image viewer, for example, should 1522 set its size to fit exactly the image currently being shown at its current 1523 zoom level.</para> 1524 1525<para>The placement of a window on the screen also varies depending on its 1526 usage. Program windows should initially either show themselves in the center 1527 of the screen or just a little above it (use BWindow::CenterOnScreen). 1528 The same goes for the initial 1529 placement of a document window. Additional document windows should duplicate 1530 the most recent document window's frame offset by the window tab height in both 1531 directions. As with size, a program should generally remember the screen 1532 placement of the windows and movement should not be restricted unless there 1533 is a good reason for it.</para> 1534 1535<para>A window need not always be visible. Duh. Considering that it can be 1536 hidden or closed altogether may be a bit confusing. Generally, a document 1537 should allow minimizing to make it possible for the user to get the document 1538 "out of the way" for a moment without having to close it entirely. Utility 1539 windows and program windows which are not the main window should normally 1540 not permit minimizing and just allow closing. The main window should allow 1541 minimizing. Note that when a program is not the focus, utility windows with 1542 the Floating:Subset and Floating:App behaviors will be hidden. Windows 1543 should normally be allowed to close unless there is a very good reason for 1544 it.</para> 1545 1546<para>A number of times in this document it has been mentioned that you should 1547 not prevent something unless there is sufficient reason to do so. 1548 Particularly on other platforms, developers have been known to just disallow 1549 resizing because they didn't want to bother themselves with writing handler 1550 code. There are other instances where, for example, a window could not be 1551 closed because the code had a design flaw which would cause a crash if the 1552 window were closed. Remember: the more work you do in making your program 1553 helpful means the less work the user has to do, which means that your 1554 program is easier to use.</para> 1555 1556</sect1> 1557<sect1> 1558<title>B_ACCEPTS_FIRST_CLICK</title> 1559 1560<para>In MacOS X, the feature this flag enables is called click-through. It 1561 means that clicking on the window passes the click through to the control 1562 the mouse was under at the time even when the window does not have the 1563 focus. As a rule, this behavior should not be used, but there are times when 1564 it is quite useful, such as for system monitor programs, the Deskbar, and so 1565 forth. Typically, this flag is used for "helper" applications and utility 1566 windows. Note that the user can override this from the Mouse preferences 1567 if they wish so, forcing all windows to accept the first click.</para> 1568</sect1> 1569 1570<sect1> 1571<title>Modality</title> 1572 1573<para>By default, windows in BeOS operating systems are modeless, meaning that 1574 you can click on other windows besides the one with the focus. Occasionally, 1575 there is a need to force the user to make a decision before moving on. This 1576 is an appropriate time to use a modal window. The need is far less often 1577 than what many would believe, however. Most of the time the only reason to 1578 use a modal window would be if not doing so would make potential for the 1579 user to lose data and there is nothing that can be done to the code 1580 architecture to prevent it. This follows the "no restrictions for no good 1581 reason" way of thinking mentioned above -- modal windows place restrictions 1582 on what windows he can or can't click on. </para> 1583</sect1> 1584 1585</chapter> 1586 1587<chapter id="chapter11"> 1588<title>Special Purpose Windows</title> 1589 1590<sect1> 1591<title>Alert Windows</title> 1592 1593<para>Alert windows are the single easiest way to make usability mistakes. Most 1594 often, they are used to show error messages. The problem is that they are 1595 used *far* more often than they should be and the error messages that are 1596 used in them are too technical for a regular user to understand or are just 1597 plain useless. They are also used to ask the user a question. More often 1598 than not, the question that is asked could have just as easily been answered 1599 by the developer, had he thought ahead a bit. Do just about whatever it 1600 takes to gracefully handle errors without bothering the user. Only when all 1601 other options have been exhausted should you show an error message. For help 1602 on writing good error messages, see Chapter 6.</para> 1603 1604<para>Before you ask the user a question, be sure that it is one which you 1605 honestly can't answer yourself or can't do without possibly disturbing the 1606 way the user works. For example, it is good courtesy to ask the user if he 1607 would like your program to be the default handler for a particular kind of 1608 file when your program is installed. It is *never* acceptable to ask the 1609 user "Are you sure you want to quit?" If your program is asked to quit, 1610 handle unsaved documents and quit. "Are you sure…" questions should be 1611 asked only if the action involves the undoable destruction of data, such as 1612 deleting a file instead of moving it to the Trash. Avoiding these kinds of 1613 situations entirely is a better solution. If the confirmation is asked too 1614 often, the user will develop the habit of confirming it without a second 1615 thought and your asking the question will be rendered moot.</para> 1616 1617<para>When you do use an alert window, please follow these guidelines: 1618 1619<orderedlist> 1620<listitem><para>On a notification, such as an error message, use "OK" for the label of the button</para></listitem> 1621 1622<listitem><para>When asking a question, make the least destructive of the most common choices the default.</para></listitem> 1623 1624<listitem><para>Avoid Yes / No button labels. It is much better to use the name 1625 of the action in the label, such as Save Changes / Discard Changes. Only 1626 in *very* rare cases are Yes / No labels the best 1627 choice.</para></listitem> 1628</orderedlist> 1629</para> 1630</sect1> 1631<sect1> 1632<title>Find Windows</title> 1633 1634<para>Windows used to search for data in a document are not very different from 1635 others, but how they are used can help, hinder, or annoy the user when 1636 searching. It only needs to be shown when the user needs to set the search 1637 terms. Once they are set, the window should itself disappear and the search 1638 should be performed. A find window which stays visible clutters the screen 1639 and often obscures part of the current document, even the result of the 1640 search. It also places the program in a separate mode, which should 1641 generally be avoided. The search itself should default to case-insensitive 1642 searches with an option to allow case sensitivity. Search by regular 1643 expression is an option that should normally be limited to programs which 1644 have programmers as the intended audience.</para> 1645 1646</sect1> 1647<sect1> 1648<title>Settings Window Design</title> 1649 1650<para>Windows to allow the user to change various program settings are another 1651 place where developers commonly commit a usability faux pas or two. The most 1652 common mistakes are poorly-chosen defaults, inappropriate language for the 1653 target audience, and too many choices. Here are some guidelines for making a 1654 good one: 1655 1656<itemizedlist> 1657<listitem><para>Choose defaults which fit the most number of people.</para></listitem> 1658 1659<listitem><para>When possible, have changes take place immediately instead of 1660 requiring the user to click OK. If you do this, provide buttons to 1661 revert changes and also to set the default values.</para></listitem> 1662 1663<listitem><para>Provide settings for significant features. This would include 1664 things like default file format for CD ripper, European vs American date 1665 format (although the system-wide setting should be used instead), 1666 or the default account in a mail client. Unncessary settings 1667 include "Use Ins key for paste" and "Confirm Program Quit".</para></listitem> 1668 1669<listitem><para>Use language appropriate for the target audience as mentioned in 1670 Chapter 2. For example, the web browser option "Move system caret with 1671 focus/selection changes" requires some technical knowledge. A better way 1672 to label such an option would be "Allow text to be selected with the 1673 keyboard." Both refer to the same option. The difference is how many 1674 people can understand what it does.</para></listitem> </itemizedlist> 1675 1676</para> 1677</sect1> 1678<sect1> 1679<title>Open and Save Panels</title> 1680 1681<para>BFilePanel is used for both opening and saving files, but there is more to 1682 using them well than merely showing a list of files. Remember the location 1683 the user was viewing, and if it is inaccessible for some reason, show the 1684 Home folder. When possible, make use of file filters to eliminate files your 1685 program does not handle. By filtering out "bad" files, you eliminate errors 1686 and at the same time reduce the amount of time the user needs to find the 1687 file he wants by reducing the number of options. Offering a possible file 1688 name when saving a new document is another way to help the user. The title 1689 of the panel needs to match the task, whether it is Import, Export as, 1690 Save as, Save, Open, or something else.</para> 1691</sect1> 1692</chapter> 1693 1694 1695<chapter id="chapter12"> 1696<title>Controls</title> 1697 1698<para>BeOS operating systems, while perhaps not as fully-featured as others, 1699 possess controls which are the bread and butter of working with GUI 1700 programs. Their basic usage is obvious to most, but for the sake of those 1701 not sure and for those who want their programs to be the very best, they are 1702 covered in detail from the basics to advanced details.</para> 1703 1704 1705<variablelist> 1706<varlistentry><term>Buttons</term> 1707<listitem> 1708<para> 1709 Buttons are all around us in the computer world and in the real one, too. A 1710 button is used to invoke a command or, much less often, show a window. 1711 <table frame="all"> 1712<title>Do's and Don'ts of Buttons</title> 1713<tgroup cols="2" align="left" colsep="1" rowsep="1"> 1714<colspec colname="c1" /> 1715<colspec colname="c2" /> 1716<thead><row><entry>Do</entry><entry>Don't</entry></row></thead> 1717<tbody><row> 1718<entry> 1719<itemizedlist> 1720<listitem>Use GetPreferredSize and ResizeToPreferred to reduce your work</listitem> 1721<listitem>Avoid using one button for opposite functions without appropriate feedback</listitem> 1722<listitem>Leave sufficient padding around them</listitem> 1723</itemizedlist> 1724</entry> 1725<entry> 1726<itemizedlist> 1727<listitem>Make them too small or ridiculously large -- like 100 pixels square 1728 for the word 'OK' when the font size is 10 point.</listitem> 1729<listitem>Leave them blank</listitem> 1730<listitem>Show a menu with one</listitem> 1731<listitem>Use them for labels</listitem> 1732<listitem>Change the label font</listitem> 1733</itemizedlist> 1734</entry> 1735</row></tbody> 1736</tgroup> 1737</table> 1738</para> 1739</listitem> 1740</varlistentry> 1741 1742<varlistentry><term>Checkboxes</term> 1743<listitem> 1744<para> 1745 Checkboxes are like a light switch with a label attached to it. Aside from 1746 turning an option on or off, they can also be used for quickly choosing 1747 multiple selections in a list of choices. 1748 1749<table frame="all"> 1750<title>Do's and Don'ts of Checkboxes</title> 1751<tgroup cols="2" align="left" colsep="1" rowsep="1"> 1752<colspec colname="c1" /> 1753<colspec colname="c2" /> 1754<thead><row><entry>Do</entry><entry>Don't</entry></row></thead> 1755<tbody><row> 1756<entry> 1757<itemizedlist> 1758<listitem>Label checkboxes so that the user understands ahead of time what clicking on it will do.</listitem> 1759<listitem>Use care in calculating bounding boxes</listitem> 1760<listitem>Carefully choose label text</listitem> 1761</itemizedlist> 1762</entry> 1763<entry> 1764<itemizedlist> 1765<listitem>Use them for choosing one item from a list. Use a group of radio buttons instead.</listitem> 1766<listitem>Use a checkbox in place of a button</listitem> 1767<listitem>Use a list of checkboxes as a progress indicator</listitem> 1768</itemizedlist> 1769</entry> 1770</row></tbody> 1771</tgroup> 1772</table> 1773</para> 1774</listitem> 1775</varlistentry> 1776 1777 1778<varlistentry><term>Radio Buttons</term> 1779<listitem> 1780<para> 1781 Radio buttons are used to choose an exclusive choice from a list of choices. 1782 They can also be used to turn an option on or off if you have plenty of 1783 space. 1784 1785<table frame="all"> 1786<title>Do's and Don'ts of Radio Buttons</title> 1787<tgroup cols="2" align="left" colsep="1" rowsep="1"> 1788<colspec colname="c1" /> 1789<colspec colname="c2" /> 1790<thead><row><entry>Do</entry><entry>Don't</entry></row></thead> 1791<tbody><row> 1792<entry> 1793<itemizedlist> 1794<listitem>Label radio buttons so that the user understands ahead of time what clicking on one will do.</listitem> 1795<listitem>Use care in calculating bounding boxes</listitem> 1796<listitem>Set a default value</listitem> 1797<listitem>Carefully choose label text</listitem> 1798</itemizedlist> 1799</entry> 1800<entry> 1801<itemizedlist> 1802<listitem>Use them individually or use them the same way as checkboxes</listitem> 1803<listitem>Use more than 5 or 6 in a group. Consider a list view instead.</listitem> 1804</itemizedlist> 1805</entry> 1806</row></tbody> 1807</tgroup> 1808</table> 1809</para> 1810</listitem> 1811</varlistentry> 1812 1813 1814<varlistentry><term>Control Groups</term> 1815<listitem> 1816<para> 1817 Control groups, namely, the BBox class, are often abused because they are 1818 not well-understood. Control groups are for visually associating different 1819 controls which work together for a common function. Unfortunately, they are 1820 most often used just for fluff. 1821 1822<table frame="all"> 1823<title>Do's and Don'ts of Control Groups</title> 1824<tgroup cols="2" align="left" colsep="1" rowsep="1"> 1825<colspec colname="c1" /> 1826<colspec colname="c2" /> 1827<thead><row><entry>Do</entry><entry>Don't</entry></row></thead> 1828<tbody><row> 1829<entry> 1830<itemizedlist> 1831<listitem>Label control group</listitem> 1832<listitem>Use control groups when there are lots of controls in window</listitem> 1833</itemizedlist> 1834</entry> 1835<entry> 1836<itemizedlist> 1837<listitem>Use a control group to label a single control</listitem> 1838<listitem>Nest control groups</listitem> 1839<listitem>Use a control group around all controls in a window</listitem> 1840<listitem>Mix control group border styles</listitem> 1841</itemizedlist> 1842</entry> 1843</row></tbody> 1844</tgroup> 1845</table> 1846</para> 1847</listitem> 1848</varlistentry> 1849 1850 1851<varlistentry><term>Sliders</term> 1852<listitem> 1853<para> 1854 Sliders are a good way to allow a user to choose a value that must be within 1855 a certain range, especially if the effect isn't exactly concrete or the 1856 value has no meaning to the user. Good uses for sliders include setting 1857 volume, mouse acceleration, and movie playback position. 1858 1859<table frame="all"> 1860<title>Do's and Don'ts of Sliders</title> 1861<tgroup cols="2" align="left" colsep="1" rowsep="1"> 1862<colspec colname="c1" /> 1863<colspec colname="c2" /> 1864<thead><row><entry>Do</entry><entry>Don't</entry></row></thead> 1865<tbody><row> 1866<entry> 1867<itemizedlist> 1868<listitem>Label the ends of the slider</listitem> 1869<listitem>Show tick marks for each value if your slider has distinct increments</listitem> 1870<listitem>Place the largest value at the right or top</listitem> 1871<listitem>Use the appropriate orientation</listitem> 1872<listitem>Label each slider position when the increment size changes, such as logarithmically</listitem> 1873</itemizedlist> 1874</entry> 1875<entry> 1876<itemizedlist> 1877<listitem>Use a slider for a progress indicator or scrollbar</listitem> 1878<listitem>Label each slider position for sliders with fixed increment sizes</listitem> 1879</itemizedlist> 1880</entry> 1881</row></tbody> 1882</tgroup> 1883</table> 1884</para> 1885</listitem> 1886</varlistentry> 1887 1888 1889<varlistentry><term>Labels</term> 1890<listitem> 1891<para> 1892 Labels help the user know what a particular control is for. Most of the 1893 controls in the BeOS API include and handle their own labels. This section 1894 deals with both the labels included with controls and ones created on their 1895 own. 1896 1897<table frame="all"> 1898<title>Do's and Don'ts of Labels</title> 1899<tgroup cols="2" align="left" colsep="1" rowsep="1"> 1900<colspec colname="c1" /> 1901<colspec colname="c2" /> 1902<thead><row><entry>Do</entry><entry>Don't</entry></row></thead> 1903<tbody><row> 1904<entry> 1905<itemizedlist> 1906<listitem>Label controls</listitem> 1907<listitem>Use a separate label when layout makes it hard to use a control's built-in label.</listitem> 1908<listitem>Use proximity to associate labels with their controls</listitem> 1909</itemizedlist> 1910</entry> 1911<entry> 1912<itemizedlist> 1913<listitem>Use a label for large amounts of static text. Consider a read-only text view.</listitem> 1914<listitem>Use a separate label object for controls which have label functions built-in</listitem> 1915</itemizedlist> 1916</entry> 1917</row></tbody> 1918</tgroup> 1919</table> 1920</para> 1921</listitem> 1922</varlistentry> 1923 1924 1925<varlistentry><term>Text Controls</term> 1926<listitem> 1927<para> 1928 Text controls are one-line editable text boxes. They are useful for entering 1929 text into forms. 1930 1931<table frame="all"> 1932<title>Do's and Don'ts of Text Controls</title> 1933<tgroup cols="2" align="left" colsep="1" rowsep="1"> 1934<colspec colname="c1" /> 1935<colspec colname="c2" /> 1936<thead><row><entry>Do</entry><entry>Don't</entry></row></thead> 1937<tbody><row> 1938<entry> 1939<itemizedlist> 1940<listitem>Disable characters you don't want in the field</listitem> 1941<listitem>Try hard to validate text entered</listitem> 1942<listitem>Make them large enough to accommodate the length of common entries</listitem> 1943<listitem>Allow clipboard operations when possible</listitem> 1944</itemizedlist> 1945</entry> 1946<entry> 1947<itemizedlist> 1948<listitem>Use a text control for a label</listitem> 1949<listitem>Make them too small</listitem> 1950<listitem>Use them for static text</listitem> 1951<listitem>Arbitrarily limit the number of characters without a very good reason</listitem> 1952</itemizedlist> 1953</entry> 1954</row></tbody> 1955</tgroup> 1956</table> 1957</para> 1958</listitem> 1959</varlistentry> 1960 1961 1962<varlistentry><term>Text Views</term> 1963<listitem> 1964<para> 1965 Text views are multiline text controls. They also provide undo, styled text, 1966 and a number of other useful text functions. 1967 1968<table frame="all"> 1969<title>Do's and Don'ts of Text Views</title> 1970<tgroup cols="2" align="left" colsep="1" rowsep="1"> 1971<colspec colname="c1" /> 1972<colspec colname="c2" /> 1973<thead><row><entry>Do</entry><entry>Don't</entry></row></thead> 1974<tbody><row> 1975<entry> 1976<itemizedlist> 1977<listitem>Disable editing if you use one to display static text</listitem> 1978<listitem>Allow both undo and selection of text unless there is a good reason not to</listitem> 1979<listitem>Allow clipboard operations when possible</listitem> 1980</itemizedlist> 1981</entry> 1982<entry> 1983<itemizedlist> 1984<listitem>Use one for single-line input</listitem> 1985<listitem>Forget to pad the text rectangle inside the text view</listitem> 1986</itemizedlist> 1987</entry> 1988</row></tbody> 1989</tgroup> 1990</table> 1991</para> 1992</listitem> 1993</varlistentry> 1994 1995 1996<varlistentry><term>Lists</term> 1997<listitem> 1998<para> 1999 Lists are used to display lots of individual items, possibly in a hierarchy. 2000 They can also allow multiple or single selections. 2001 2002<table frame="all"> 2003<title>Do's and Don'ts of List Views</title> 2004<tgroup cols="2" align="left" colsep="1" rowsep="1"> 2005<colspec colname="c1" /> 2006<colspec colname="c2" /> 2007<thead><row><entry>Do</entry><entry>Don't</entry></row></thead> 2008<tbody><row> 2009<entry> 2010<itemizedlist> 2011<listitem>Provide a way to select all items in multiple-selection lists.</listitem> 2012<listitem>Sort your list</listitem> 2013</itemizedlist> 2014</entry> 2015<entry> 2016<itemizedlist> 2017<listitem>Use just enough space to display just a couple of items</listitem> 2018<listitem>Try to use it to select from hundreds of items. Use a search instead.</listitem> 2019<listitem>Use list items to toggle options like a list of checkboxes</listitem> 2020</itemizedlist> 2021</entry> 2022</row></tbody> 2023</tgroup> 2024</table> 2025</para> 2026</listitem> 2027</varlistentry> 2028 2029 2030<varlistentry><term>Tabs</term> 2031<listitem> 2032<para> 2033 Tabs can be quite handy for displaying multiple views in a small space. 2034 Unfortunately, they seem to suffer from being too easy to abuse. 2035 2036<table frame="all"> 2037<title>Do's and Don'ts of Tabs</title> 2038<tgroup cols="2" align="left" colsep="1" rowsep="1"> 2039<colspec colname="c1" /> 2040<colspec colname="c2" /> 2041<thead><row><entry>Do</entry><entry>Don't</entry></row></thead> 2042<tbody><row> 2043<entry> 2044<itemizedlist> 2045<listitem>Use tabs to manage and organize otherwise complex dialog windows</listitem> 2046<listitem>Use a list instead of tabs to manage large numbers of views</listitem> 2047</itemizedlist> 2048</entry> 2049<entry> 2050<itemizedlist> 2051<listitem>Use tabs to select a particular mode</listitem> 2052<listitem>Nest tab views</listitem> 2053<listitem>Use so many tabs that a scrolling is needed to see them all</listitem> 2054<listitem>Place confirm / cancel buttons inside tabs</listitem> 2055<listitem>Overlay toolbars by using tabs</listitem> 2056<listitem>Use vertical text with vertical tabs</listitem> 2057<listitem>Use tabs on more than one side at once</listitem> 2058<listitem>Use one tab all by itself</listitem> 2059<listitem>Use unlabelled icons for tab titles</listitem> 2060<listitem>Use a scrollbar to scroll a form inside a tab</listitem> 2061</itemizedlist> 2062</entry> 2063</row></tbody> 2064</tgroup> 2065</table> 2066</para> 2067</listitem> 2068</varlistentry> 2069 2070 2071<varlistentry><term>Scrollbars</term> 2072<listitem> 2073<para> 2074 Scrollbars, unlike tabs, tend to not be abused. Use them to display more 2075 items than can fit on the screen, but don't overuse them. 2076 2077<table frame="all"> 2078<title>Do's and Don'ts of Scrollbars</title> 2079<tgroup cols="2" align="left" colsep="1" rowsep="1"> 2080<colspec colname="c1" /> 2081<colspec colname="c2" /> 2082<thead><row><entry>Do</entry><entry>Don't</entry></row></thead> 2083<tbody><row> 2084<entry> 2085<itemizedlist> 2086<listitem>Adjust range and step size when their target view is resized</listitem> 2087</itemizedlist> 2088</entry> 2089<entry> 2090<itemizedlist> 2091<listitem>Scroll forms</listitem> 2092<listitem>Try to customize their look</listitem> 2093<listitem>Use them like a slider control</listitem> 2094<listitem>Nest BScrollViews</listitem> 2095</itemizedlist> 2096</entry> 2097</row></tbody> 2098</tgroup> 2099</table> 2100</para> 2101</listitem> 2102</varlistentry> 2103 2104 2105<varlistentry><term>Menu Fields</term> 2106<listitem> 2107<para> 2108 Menu fields are buttons which display a label and pop up a menu when clicked. 2109 2110<table frame="all"> 2111<title>Do's and Don'ts of Menu Fields</title> 2112<tgroup cols="2" align="left" colsep="1" rowsep="1"> 2113<colspec colname="c1" /> 2114<colspec colname="c2" /> 2115<thead><row><entry>Do</entry><entry>Don't</entry></row></thead> 2116<tbody><row> 2117<entry> 2118<itemizedlist> 2119<listitem>Use them in place of radio buttons when space is limited</listitem> 2120<listitem>Remember to follow the menu construction guidelines mentioned in Chapter 9</listitem> 2121</itemizedlist> 2122</entry> 2123<entry> 2124<itemizedlist> 2125<listitem>Use them instead of a menu bar for the main program menu</listitem> 2126</itemizedlist> 2127</entry> 2128</row></tbody> 2129</tgroup> 2130</table> 2131</para> 2132</listitem> 2133</varlistentry> 2134 2135 2136<varlistentry><term>Pop-up Menus</term> 2137<listitem> 2138<para> 2139 Pop-up menus differ from regular menus in that they can be invoked from 2140 anywhere on the screen. 2141 2142<table frame="all"> 2143<title>Do's and Don'ts of Popup Menus</title> 2144<tgroup cols="2" align="left" colsep="1" rowsep="1"> 2145<colspec colname="c1" /> 2146<colspec colname="c2" /> 2147<thead><row><entry>Do</entry><entry>Don't</entry></row></thead> 2148<tbody><row> 2149<entry> 2150<itemizedlist> 2151<listitem>Make pop-up menus sticky</listitem> 2152<listitem>Use pop-up menus for context menus</listitem> 2153</itemizedlist> 2154</entry> 2155<entry> 2156<itemizedlist> 2157<listitem>Show a pop-up menu by clicking on a button or do other similar 2158 nonsensical control daisy-chaining.</listitem> 2159<listitem>Use a pop-up menu as a tooltip</listitem> 2160<listitem>Use the primary mouse button to show a context menu</listitem> 2161</itemizedlist> 2162</entry> 2163</row></tbody> 2164</tgroup> 2165</table> 2166</para> 2167</listitem> 2168</varlistentry> 2169 2170 2171<varlistentry><term>Progress Meters</term> 2172<listitem> 2173<para> 2174 BStatusBars are used to show progress in BeOS operating systems. 2175 2176<table frame="all"> 2177<title>Do's and Don'ts of Progress Meters</title> 2178<tgroup cols="2" align="left" colsep="1" rowsep="1"> 2179<colspec colname="c1" /> 2180<colspec colname="c2" /> 2181<thead><row><entry>Do</entry><entry>Don't</entry></row></thead> 2182<tbody><row> 2183<entry> 2184<itemizedlist> 2185<listitem>Choose a color carefully if you don't use the default</listitem> 2186<listitem>Use them whenever an operation has the potential to take a while</listitem> 2187<listitem>Properly label the progress bar</listitem> 2188</itemizedlist> 2189</entry> 2190<entry> 2191<itemizedlist> 2192<listitem>Use a slider or scrollbar for a progress bar.</listitem> 2193<listitem>Use a progress bar as a control separator</listitem> 2194</itemizedlist> 2195</entry> 2196</row></tbody> 2197</tgroup> 2198</table> 2199</para> 2200</listitem> 2201</varlistentry> 2202 2203 2204<varlistentry><term>Toolbars</term> 2205<listitem> 2206<para> 2207 Toolbars are little more than a collection of graphical 2208 buttons. They are used for providing fast access to commonly-used functions. 2209 2210<table frame="all"> 2211<title>Do's and Don'ts of Toolbars</title> 2212<tgroup cols="2" align="left" colsep="1" rowsep="1"> 2213<colspec colname="c1" /> 2214<colspec colname="c2" /> 2215<thead><row><entry>Do</entry><entry>Don't</entry></row></thead> 2216<tbody><row> 2217<entry> 2218<itemizedlist> 2219<listitem>Use them to speed up access to common functions</listitem> 2220<listitem>Use icons from the standard set if possible</listitem> 2221<listitem>Make the function of each button obvious from the icons used</listitem> 2222<listitem>Follow the specific icon guidelines for toolbar icons</listitem> 2223</itemizedlist> 2224</entry> 2225<entry> 2226<itemizedlist> 2227<listitem>Add a toolbar just for looks</listitem> 2228<listitem>Scroll toolbars</listitem> 2229<listitem>Use put too many buttons in a toolbar or have too many toolbars on the screen</listitem> 2230</itemizedlist> 2231</entry> 2232</row></tbody> 2233</tgroup> 2234</table> 2235</para> 2236</listitem> 2237</varlistentry> 2238 2239</variablelist> 2240</chapter> 2241 2242<appendix> 2243<title>How to Make a Good Error</title> 2244 2245<para>By nature of not being perfect, developers make mistakes and no program is 2246 without its bugs. As mentioned earlier, conditions which could cause errors 2247 should be anticipated and handled as much as reasonably possible. In those 2248 instances where there is nothing left to be done except show an error 2249 message, be helpful, polite, and as non-technical as possible.</para> 2250 2251<sect1> 2252<title>Examples of Good Error Messages</title> 2253 2254<para>Uh-oh... MyMP3Ripper couldn't create the playlist 2255 /boot/home/playlists/foo. This may have happened for a number of different 2256 reasons, but most often happens when making playlists on a non-BeOS drive, 2257 such as one shared with Windows. Certain characters, such as question marks 2258 and slashes cause problems on these disks. You may want to check the names 2259 of the artist, album, and songs for such characters and put a good 2260 substitute in its place or remove the character entirely.</para> 2261 2262<para>MyApp can't copy your file to the disk because there isn't enough space 2263 for it. If you would like to copy it, move or delete files on the 2264 destination disk and try again.</para> 2265 2266<para>MyApp didn't recognize the data in the file '/boot/home/foo'. It might not 2267 be a MyApp file or perhaps the file is corrupted.</para> 2268 2269<para>(From a website):: O No! If you are reading this message, it means we have 2270 made a mistake. Don't worry, you can be sure that as you are reading this 2271 people are freaking out around here - testing circuits, rebooting systems, 2272 and even typing resumés (just kidding). Please try back in 5 minutes, as we 2273 still have plenty of great stuff.</para> 2274 2275</sect1> 2276<sect1> 2277<title>Real World Examples of Bad Error Messages</title> 2278 2279 2280<para>Wrong Button! This button doesn't work. Solution: Try another.</para> 2281 2282<para>The project file "e:\ws\foo" may have been modified on disk by the 2283 preceding Source Control operation. However, you also have made changes to 2284 this project which have not been saved. If you reload the project you will 2285 lose your current changes, but if you don't, you risk overwriting the new 2286 changes on disk, which is usually much worse. Do you want to reload it now? 2287 [Yes] [No]</para> 2288 2289<para>Mail Engine: No Error</para> 2290 2291<para>Spell Check Cancelled</para> 2292 2293<para>Unexpected Error. Please investigate.</para> 2294 2295<para>System Error 0x80004005 (02147467259). Unspecified error.</para> 2296 2297<para>Question or information that needs the user's immediate attention.</para> 2298 2299</sect1> 2300</appendix> 2301</book> 2302