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