Aren/haiku
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Some initial revisions for the first 11 chapters or so

Browse Source 
git-svn-id: file:///srv/svn/repos/haiku/haiku/trunk@18292 a95241bf-73f2-0310-859d-f6bbb57e9c96
This commit is contained in:
DarkWyrm 2006-07-27 01:30:57 +00:00
parent 6fd4020e03
commit f30d1a521a
1 changed files with 164 additions and 143 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

297
docs/user/uiguidelines/HaikuHIG.txt
View File

@ -21,16 +21,16 @@ Chapter 3: Conventions of the Haiku Operating System
Program Options: Format and Location
Maintain Responsiveness
Avoid Hardcoded File Paths
Make Your App's Look Fit in with Others
Make Your App's Look Fits in with Others
Live Updates
Translators
Squeezing the Most out of BFS: Queries and Attributes
The System Tray
Squeezing the Most Out of BFS: Queries and Attributes
The System Tray: It's Not Just for Dinner
Tracker and its Uses
Chapter 4: Getting Input from the User
Mouse Vocabulary, AKA "You Want Me to What?!"
Keyboard accelerators: The Sports Cars of GUIs
Keyboard Accelerators: The Sports Cars of GUIs
Design without Throwing Fitts
Chapter 5: Dynamic Data Exchange: Passing Data Between Applications
@ -39,20 +39,20 @@ Chapter 5: Dynamic Data Exchange: Passing Data Between Applications
Replicants
Chapter 6: Use of Text in the GUI
Error Messages
Ellipses
Error Messages, or, "I'm sorry Dave. I'm afraid I can't do that"
...Ellipses...
Abbreviations, Acronyms, and Contractions, oh my!
cApItAlIzAtIoN and Speling
Use of Fonts
Special Case: The Command Line
Chapter 7: Branding - Program Icons, About Windows, Graphics, and other Visuals
Chapter 7: Branding - Program Icons, About Windows, Graphics, and Other Visuals at the OK Corral
Program Icons
About Windows
Graphics and Other Visuals
About Windows... Doorways to Creative Expression
Graphics and Other Stuff
Chapter 8: Cursors
Predefined Cursors and their Use
Predefined Cursors and their Uses
Making Your Own Cursors
Animating Cursors
@ -96,44 +96,40 @@ Chapter 13: Installation and Updates
SoftwareValet packages
Getting Program Updates
Appendix A: Good and Bad Error Messages
Chapter 1: How to Design Software Good
Haiku is an operating system which is known for its speed and being easy for anyone to use. This is partly because good programmers try to design their apps for more than just themselves. We are going to examine how you can also make your program more appealing. The reason is easy: easier to use means more people using your program. Writing good software can be hard, but it is worth the time and effort.
Haiku is an operating system which is known for its speed and being easy for anyone to use. This is partly because good programmers try to design their apps for more than just themselves. We are going to examine how you can also make your program more appealing. The reason is easy: easier to use means more people using your program. Writing good software can be hard, but it is worth the time and effort.
1) Who Ya Writin' It Fer?
You probably already know what kind of program you are going to write. If not, put this book away and do some thinking first -- without a clear idea of what you want, it's hard to do something about it. Once you know what general kind of program you would like to create, you also need to figure out who the program is meant for. This can be something as general as 'desktop users' to something as specific as 'Haiku Web Developers'. When you know who the main users of your program will be, you can make certain assumptions about what your users know. You can't necessarily expect a musician to understand how to effectively use a 3D modelling program as advanced as, say, 3D Studio Max.
Depending on how concerned you are about details, you may even want to create a user profile -- a fictional idea of an example user. This can be consist of just one or two sentences or can be several paragraphs. A short user profile contains the person's first name, occupation, level of expertise, and what kinds of things they want to be able to do with their computer. One thing to be sure of is to make the user profile believable -- like a person you might know. In fact, when you design your app, it may be helpful if you know someone who fits into the target audience. You don't want to design you app for that person specifically, but, rather, someone just like them.
You probably already know what kind of program you are going to write. If not, put this book away and do some thinking first -- without a clear idea of what you want, it's hard to do something about it. Once you know what general kind of program you would like to create, you also need to figure out who the program is meant for. This can be something as general as 'desktop users' to something as specific as 'Haiku Web Developers'. When you know who the main users of your program will be, you can make certain assumptions about what your users know. You can't necessarily expect a musician to understand how to effectively use a 3D modelling program as advanced as, say, 3D Studio Max.
Depending on how concerned you are about details, you may even want to create a user profile -- a fictional idea of an example user. This can be consist of just one or two sentences or can be several paragraphs. A short user profile contains the person's first name, occupation, level of expertise, and what kinds of things they want to be able to do with their computer. One thing to be sure of is to make the user profile believable -- like a person you might know. In fact, when you design your app, it may be helpful if you know someone who fits into the target audience. You don't want to design you app for that person specifically, but, rather, someone just like them.
2) What will the User be Doing?
Most people will use your software to get work done, unless, of course, you're writing the next hit game, and despite experiences you may have had which might make you wonder, users are fairly intelligent. The saying that no one reads manuals is mostly true -- people generally have better things to do than read software manuals except when either in trouble or as bathroom reading. Try to keep in mind how busy most people are and how valuable their time is to them when you are designing your program.
In order to make doing work with your program easier, you need to prioritize what kinds of work they will do in order of how often the work is done. Come up with a list of tasks the user will be doing and put them into one of 3 categories: Common, Uncommon, and Rare. Common tasks, unsurprisingly, are those things which the user does all the time. In a word processor, this would include typing in text, changing font sizes and styles, and adjusting margins. Uncommon tasks are those which the user does just from time to time. Depending on the user, this might be something like printing labels, adding color to a table, or counting the words in the document. Rare tasks are those which are done every once in a great while. Often times, these tasks are ones which the user would quite likely not miss if it were not possible to do it with your program. This would also be the kinds of things that only 20 percent of your users or less would end up using. If you do decide to include features to handle Rare tasks, think carefully about each task's importance in the grand scheme of things before deciding with any finality.
In order for your software to be as simple to use as possible, you must, to paraphrase Einstein, make it as simple as possible, but not any simpler. Complexity must be kept to a minimum. One major way this can be done is by avoiding features which are used only in remote instances -- the tasks in the Rare group. Design your application to meet the needs of 80 percent of your target audience. With added features comes added complexity and with added complexity comes added difficulty.
Most people will use your software to get work done, unless, of course, you're writing the next hit game, and despite experiences you may have had which might make you wonder, users are fairly intelligent. The saying that no one reads manuals is mostly true: people generally have better things to do than read software manuals except when either in trouble or as bathroom reading. Try to keep in mind how busy most people are and how valuable their time is to them when you are designing your program.
In order to make doing work with your program easier, you need to prioritize what kinds of work they will do in order of how often the work is done. Come up with a list of tasks the user will be doing and put them into one of 3 categories: Common, Uncommon, and Rare. Common tasks, unsurprisingly, are those things which the user does all the time. In a word processor, this would include typing in text, changing font sizes and styles, and adjusting margins. Uncommon tasks are those which the user does just from time to time. Depending on the user, this might be something like printing labels, adding color to a table, or counting the words in the document. Rare tasks are those which are done every once in a great while. Often times, these tasks are ones which the user would quite likely not miss if it were not possible to do it with your program. This would also be the kinds of things that only 20 percent of your users or less would end up using. If you do decide to include features to handle Rare tasks, think carefully about each task's importance in the grand scheme of things before deciding with any finality.
To paraphrase Einstein, you must make your software as simple as possible but no simpler. Complexity must be kept to a minimum. One major way this can be done is by avoiding features which are used only in remote instances -- the tasks in the Rare group. Design your application to meet the needs of 80 percent of your target audience. Features add complexity and complexity adds difficulty.
3) How will Your Users Do Their Work?
Once you know who your users are and what they will be doing, you will need to figure out generally how it will be done. This does not imply what your program will actually look like, however. In a home finance application, one of the user's primary tasks will be entering in transactions. The user will need to type in the data for each transaction or download them from their bank over the Internet. You need to know this kind of information for each task the user will have to perform, common or otherwise.
The actual implementation of the application is determined last, which is why it has not been discussed until now. Note that what technologies will be used to actually create the program have not even been mentioned yet. Technology is the means to an end -- a tool -- and not the end itself. This is where the general usage of the application is determined. For example, the user will have a form to enter transactions into an account. The form should have text fields for each of the different kinds of data, such as the payee, the amount, and the check number. Somewhere nearby, the user will be able to see all a list of all the transactions in the current account. Because this is where the actual building of the look of the program takes place, it is crucial at this point in development to know and understand what makes software truly easy to use, so this is what we will examine next.
Once you know who your users are and what they will be doing, you will need to figure out how it will be done in a general sense. This does not include what your program will actually look like, however. In a personal finance application, one of the user's primary tasks will be entering in transactions. The user will need to type in the data for each transaction or download them from their bank over the Internet. You need to know this kind of information for each task the user will have to perform, common or otherwise.
The actual implementation is determined last, which is why it has not been discussed until now. This is where the general usage of the application is determined. For example, the user will have a form to enter transactions into an account. The form should have text fields for each of the different kinds of data, such as the payee, the amount, and the check number. Somewhere nearby, the user will be able to see all a list of all the transactions in the current account. Because this is where the actual building of the look of the program takes place, it is crucial at this point in development to know and understand what makes software truly easy to use, so this is what we will examine next. Note that what technologies will be used to actually create the program have not even been mentioned yet. For your audience, technology is merely the means to an end -- a tool -- and not the goal itself.
Summary
Careful planning is the key to writing excellent software, regardless of what stage of development a project may be in. In order to be easy, good programs only have what is really needed. They also help the user do his work wherever possible, and only by thoroughly understanding what and how work is to be done and who is doing it can a program provide the best experience possible.
Careful planning is the key to writing excellent software, regardless of what stage of development a project may be in. In order to be easy, good software only has what is really needed. It also helps the user do his work wherever possible. Only by thoroughly understanding what the work is, how it is to be done, and who is doing it can a program provide the best experience possible.
Chapter 2: Qualities of Good Software
When it comes to software, the proof is in the usage. If a piece of software requires significant time to learn, the user will only invest the time in learning it if (a) he has no other choice but to use that particular software and (b) the importance of the need filled by the software is much greater than the importance of the user's time.
When it comes to software, the proof is in the usage. If a piece of software requires significant time to learn, the user will only invest the time in learning it if (a) he has no other choice but to use that particular software and (b) the importance of the need filled by the software is much greater than the importance of the user's time. In short, a user will learn only what he must in order to do his job and even then only when forced to do so.
Good Software Focuses on a User's Actual Needs
@ -142,9 +138,8 @@ Good Software Focuses on a User's Actual Needs
Good Software Uses Everyday Language
Jobs in Information Technology industry are almost always professional positions. One aspect which makes IT a profession is that it has its own body of knowledge and terminology to go with it. Most people have only a rudimentary 'computerese' vocabulary -- the thing that they look at when they use a computer is called a monitor or just 'the screen', the little arrow on the screen is called the cursor, and the thing they type with is called a keyboard. Few users know (or care) what a 'file format' is and fewer still do not know what an 'invalid sector' on a floppy disk might be.
Good programs use regular language instead of technical terms. For file management software, 'volumes' are really disks – even though the term isn't quite accurate, a normal person thinks a disk is a storage container and that volume is what you have up too high at really good parties. Images are 'pictures'. A person doesn't 'kill' a application that has 'hung' -- he 'forces a frozen program to quit'. Details like this may seem minor, but many small improvements in a program's usability can have a profound effect overall. Of course, if your target audience is IT professionals, these kinds of terms are perfectly acceptable. Be sure that you match the everyday language of your audience.
Jobs in the Information Technology industry are almost always professional positions. One aspect which makes IT a profession is that it has its own body of knowledge and terminology to go with it. Most people have only a rudimentary 'computerese' vocabulary. The thing that they look at when they use a computer is called a monitor or just 'the screen'; the little arrow on the screen is called the cursor, and the thing they type with is called a keyboard. Few users know (or care) what a 'file format' is and fewer still do not know what an 'invalid sector' on a floppy disk might be.
Good programs use regular language instead of technical terms. For file management software, 'volumes' are really disks -- even though the term isn't quite accurate, a normal person thinks a disk is a storage container and that volume is what you have up too high at really good parties. Images are 'pictures'. A person doesn't 'kill' a application that has 'hung' -- he 'forces a frozen program to quit'. Details like this may seem minor, but many small improvements in a program's usability can have a profound effect overall. Of course, if your target audience is IT professionals, these kinds of terms are perfectly acceptable. Be sure that you match the everyday language of your audience.
Good Software Does Not Expose Its Implementation
@ -152,27 +147,29 @@ Good software works a certain way because it is the best way to be done, not bec
Good Software Uses Graphical Controls Properly
GUI controls were meant to be used in certain ways, and when a program does not use them in that particular way, it is confusing to the user. Check boxes, for example, are commonly used in lists where a value can be turned on or off. Some programs, however, uses them for choosing one option in a list even though radio buttons are meant for this task. Text boxes should not be used for labelling other controls. This might seem to be common sense for most, but, rest assured, there are many programs which do not do something as simple as this. In short, standard controls used in nonstandard ways are confusing.
GUI controls were meant to be used in certain ways, and when a program does not use them in that particular way, it is confusing to the user and possibly hazardous to the user's data. Check boxes, for example, are commonly used in lists where a value can be turned on or off. Some programs, however, uses them for choosing one option in a list even though radio buttons are meant for this task. Text boxes should not be used for labelling other controls. This might seem to be common sense for most, but, rest assured, there are many programs which do not do something as simple as this. In short, use standard controls the way they were intended.
Good Software has a Natural Layout to its Controls
When performing certain tasks, people have a logical order that they follow, and good programs place their GUI controls in a manner that reflects this. When entering an address in the United States, the natural order is Name, Street and Number, City, State, and Zip Code. Following any other order would not only frustrate the user, but it would also lead to more mistakes in entering the proper data. This also applies to the Tab navigation order of controls in a window. Generally speaking, this order should either be left-to-right, top-to-bottom or in a counter-clockwise circle, depending on how the controls themselves are placed and the expectations associated with the work to be done.
Some tasks have a natural, logical workflow, and good programs are designed in a way that capitalizes on this workflow. When entering an address in the United States, the natural order is Name, Street and Number, City, State, and Zip Code. Following any other order would both frustrate the user and also lead to more mistakes in entering data. This also applies to the Tab navigation order of controls in a window. Generally speaking, this order should either be left-to-right, top-to-bottom or in a counter-clockwise circle, depending on how the controls themselves are placed and the expectations associated with the work to be done.
Good Software Gives Plenty of Feedback
Picture this: you have just started converting a movie file to another format. You hit the button marked 'Go' and wait... and wait.. and wait. You're sure you clicked the button, but nothing seems to be happening. Did something go wrong? Only after some snooping around with a file manager do you find out that everything is OK. You didn't know what was happening because the program didn't tell you what it was doing. Good software does something that effective people do – keep the lines of communication open. Good feedback just means making sure that the user knows what your program is doing at any given time, especially if the program is busy doing something which makes him wait. CD and DVD burning programs tell the user how much is left before they are finished making a CD or DVD. File management programs tell how many files are left to copy or move. Web browsers animate a little icon while they download a web page.
Imagine for a moment that you have just started converting a movie file to another format. You hit the button marked 'Go' and wait. Then you wait some more. You go to the restroom, brew a new pot of coffee, get the mail from the box, and come back to wait some more. You're sure you clicked the button, but nothing seems to be happening. Did something go wrong? Only after some snooping around with a file manager do you find out that everything is OK. You didn't know what was happening because the program didn't tell you what it was doing.
Good software keep the lines of communication open. Good feedback just means making sure that the user knows what your program is doing at any given time, especially if the program is busy doing something which makes him wait. CD and DVD burning programs tell the user how much is left before they are finished making a CD or DVD. File management programs tell how many files are left to copy or move. Web browsers animate a little icon while they download a web page. Users have a natural tendency to think that if nothing seems to be happening, then the program is probably frozen. Making sure that the user knows your program is hard at work puts his mind at ease.
Good Software Makes Errors Hard
It should be tough for users to mess up. If, for example, the user needs to enter in some text and certain characters are not allowed, then disable those characters for the text box it needs to be entered in. If resizing a window horizontally should not be done for some reason, don't let the user do it. Does your program require a selection from a list before the user clicks OK? Tell the user that -- nicely, of course -- and then disable the OK button until a selection is made. Build constraints into your application which prevent errors. This would be why 3.5" floppy disks have a notch in one side – it can be inserted into a drive only one way.
It has been said that nothing can be made foolproof because fools are so ingenious. Even so, make it tough for the user to make a mistake. If, for example, the user needs to enter in some text and certain characters are not allowed, then disable those characters for the text box it needs to be entered in. If resizing a window horizontally should not be done for some reason, don't let the user do it. Does your program require a selection from a list before the user clicks OK? Tell the user that -- nicely, of course -- and then disable the OK button until a selection is made. An even better solution would be to select a good default choice for the user and give him the option to change it. Build constraints into your application which prevent errors. This would be why 3.5" floppy disks have a notch in one side -- it can be inserted into a drive only one way. Constraints are also good for lazy developers because then their software crashes less and they don't need to write as much error-handling code.
Good Applications Handle Errors Gracefully
It has been said that it is impossible to make an application entirely foolproof because fools are so ingenious, but it is possible for a program to handle errors in a way that doesn't leave the user wondering what happened. When code is written, errors of all sorts need to be anticipated and handled, such as lack of memory, lack of disk space, permissions errors, and loss of network connectivity. As Murphy's Law states, if something can go wrong in a given situation, it probably will. Anticipate this -- handle every error that is likely to occur with in reason. Doing so greatly improves the perception of your software by the outside world. Crashes are unacceptable in all cases. Period. Error messages, for example, need to describe at the user's level of expertise what happened and suggest what the user can do to remedy the situation. In the worst case, the program needs to provide an easy way for the user to send technical information about the problem back to you via e-mail or some other means. In all cases, the user's data is to be preserved.
Even if you make it hard for a user to make a mistake, expect your program to have to deal with errors. It is possible for a program to handle errors in a way that doesn't leave the user wondering what happened. When code is written, errors of all sorts need to be anticipated and handled, such as lack of memory, lack of disk space, permissions errors, corrupted files, and loss of network connectivity. As Murphy's Law states, if something can go wrong in a given situation, it probably will. Hope for the best but prepare for the worst: within reason, handle every error that is likely to occur. Doing so greatly improves the perception of your software by the outside world. Crashes are unacceptable in all cases. Period. Error messages, for example, need to describe at the user's level of expertise what happened and suggest what the user can do to remedy the situation. In the worst case, the program needs to provide an easy way for the user to send technical information about the problem back to you via e-mail or some other means. In all cases, the user's data is to be preserved.
One way that you can see how well your program handles errors is to deliberately try to break it in every way possible. Feed the entire text of your Aunt May's quiche recipe into a text box all at once. Try to open files it has no business being given. Take a valid document, back it up, open it in DiskProbe, enter as much junk data into it as you like, and then try to open it. Break your Internet connection while it's in the middle of an update. Try to using filenames with really wonky filenames. Be creative and ridiculous and, most of all, have fun breaking things!
Good Software is Forgiving
Computers are excellent tools for people because they are good at many things that people are not. From a perspective which focuses on technology, humans are imprecise, illogical, disorganized, and make mistakes frequently. They are, however, excellent at forming habits and matching patterns, two things computers have a difficult time doing. Make commands undoable whenever possible and when it is not possible, be sure to inform the user that such is the case. Utilize a computer's strengths to make up for a person's inherent weaknesses.
Computers are excellent tools for people because they are good at many things that people are not. From a perspective which focuses on technology, humans are imprecise, illogical, disorganized, and make mistakes frequently. They are, however, excellent at forming habits and matching patterns, two things computers have a difficult time doing. Make commands undoable whenever possible and when it is not possible, be sure to inform the user that such is the case. Utilize a computer's strengths to make up for a person's inherent weaknesses.
Summary
@ -180,84 +177,82 @@ Summary
Chapter 3: Conventions of the Haiku Operating System
Just as a person generally doesn't go barging into a stranger's home and start redecorating and otherwise making himself at home merely because the owner does not own a shotgun, your program needs to have good manners in getting along with both the operating system and other programs the user has installed on the system. Some of these are merely good coding practices meant to make your job easier and others are for ensuring that your program can be more easily maintained. None of them are difficult or much work, so there. Now you have no choice but to follow them. :D
Just as a person generally doesn't go barging into a stranger's home and start redecorating and otherwise making himself at home merely because the owner does not own a shotgun, your program needs to have good manners in getting along with both the operating system and the other programs the user has installed on the system. Some of these are merely good coding practices meant to make your job easier and others are for ensuring that your program can be more easily maintained. None of them are difficult or much work, so there. Now you have no choice but to follow them. :D
Program Options: Format and Location
While there are lots of ways to store program settings, the easiest -- and preferred -- method is placing them in a BMessage and flattening it to a BFile. By using BMessages as your container, you don't have to concern yourself with writing and debugging other code. The exact location used to store them depends on the number of files you will need. If your software needs only one file and will only ever need one, then it is just simplest to place it in the user's config/settings folder. However, should you need more than one file, please put them in their own folder to minimize the clutter. The folder should either follow the format home/config/settings/your_app_name_here or home/config/settings/your_company_name_here/your_app_name_here.
While there are lots of ways to store program settings, the easiest and recommended method is placing them in a BMessage and flattening it to a BFile. By using BMessages as your container, you don't have to concern yourself with writing and debugging other code. The exact location used to store them depends on the number of files you will need. If your software needs only one file and will only ever need one, then it is just simplest to place it in the user's config/settings folder. However, should you need more than one file, please put them in their own folder to minimize the clutter. The folder should either follow the format home/config/settings/your_app_name_here or home/config/settings/your_company_name_here/your_app_name_here.
Maintain Responsiveness
Probably the best-known quality about BeOS and Haiku as operating systems is speed. This largely comes from the extensive use of multithreading in applications. Note that responsiveness does not necessarily mean that your program should never be busy. It should just respond to input and redraw requests. A common experience encountered by Linux and Windows users is the "blanking out" of a window or an entire program because it is busy doing something else. This comes from two things: the program has one thread of execution devoted to all its windows and that thread is busy doing some sort of time-consuming work. Instead of falling into this trap which is unprofessional for you and confusing for the user, spawn another thread to do the actual processing and allow the message-handling thread to continue to do its job. This makes sure the user knows that your application is still running properly and has not frozen.
Probably the best-known quality about BeOS and Haiku as operating systems is speed. This largely comes from the extensive use of multithreading in applications. Being responsive does not necessarily mean that your program should never be busy. It should just respond to input and redraw requests even when it's doing something. A common experience encountered by Linux and Windows users is the "blanking out" of a window or an entire program because it is busy doing something else. This comes from two things: the program has one thread of execution devoted to all its windows and that thread is busy doing some sort of time-consuming work. Instead of falling into this trap, which is unprofessional for you and confusing for the user, spawn another thread to do the actual processing and allow the message-handling thread to continue to do its job. This makes sure the user knows that your application is still running properly and has not frozen.
Avoid Hardcoded File Paths
Whenever your program needs to specify a particular area on the system, make use of the find_directory() function to generate it. If and when the day comes that Haiku supports multiple users, your application will make a smooth transition to the new architecture. This will also allow for backward compatibility with older versions of BeOS, such as the change in locations for B_COMMON_FONTS_DIRECTORY being in a different place for Haiku than on R5. find_directory() is supported in both C and C++ environments.
Whenever your program needs to specify a particular area on the system, use of the find_directory() function to generate it. If and when the day comes that Haiku supports multiple users, your application will make a smooth transition to the new architecture. This will also allow for backward compatibility with older versions of BeOS, such as the change in locations for B_COMMON_FONTS_DIRECTORY being in a different place for Haiku than on R5. find_directory() is supported in both C and C++ environments.
Make Your App's Look Fit in with Others
Make Your App's Look Fits in with Others
Certain function calls have been provided in the API to aid in making sure that your software shares the same general look as other applications and allow the user to make customizations to the system at the same time. Unless there is a very good reason for it, utilize ui_color() and the constants which go with it to set colors for the views in your application. Determine the size of your controls dynamically - use the ResizeToPreferred and GetPreferredSize for system controls and calculate the size of your own controls based on font sizes obtained from the system instead of hardcoded values. All of this will allow better ease-of-use for the user who prefers tiny fonts to increase use of desktop real estate and also for older users who need larger font sizes to accomodate weaker visual acuity. Graphics are an important part of a program's look, but don't reimplement the look of the buttons and other standard controls just to make your application stand out from the rest. By keeping visual consistency with the rest of the operating system, you avoid confusing the user with buttons that do not look like you can click on them, strange-acting menus, and so forth.
Certain function calls have been provided in the API to aid in making sure that your software shares the same general look as other applications and allow the user to make customizations to the system at the same time. Unless there is a very good reason for it, get colors for your program with ui_color() and the constants which go with it. Determine the size of your controls dynamically - use the ResizeToPreferred and GetPreferredSize for system controls and calculate the size of your own controls based on font sizes obtained from the system instead of hardcoded values. All of this will allow better ease-of-use for the user who prefers tiny fonts to increase use of desktop real estate and also for older users who need larger font sizes to accomodate weaker visual acuity. Graphics are an important part of a program's look, but don't reimplement the look of the buttons and other standard controls just to make your application stand out from the rest. By keeping visual consistency with the rest of the operating system, you avoid confusing the user with buttons that do not look like you can click on them, strange-acting menus, and so forth.
Live Updates
One way to make sure that your application communicates effectively with the user is to provide "live" updates to information in it. This mostly relates to files in the system. A good example of l've updates is an address book program which automatically removes and adds entries when new People files are added to the People folder. The information doesn't even have to be data that is outside your program -- it could just be as simple as updating an entry in a list of items as the user types makes changes to it in a form in a different part of the GUI. Responsiveness like this in a program helps the user feel more in control of the work he is doing.
One way to make sure that your application communicates effectively with the user is to provide "live" updates to information in it. This mostly relates to files in the system. A good example is an address book program which automatically removes and adds entries when new People files are added to the People folder. The information doesn't even have to be data that is outside your program. It could just be as simple as updating an entry in a list of items as the user types makes changes to it in a form in a different part of the GUI. Responsiveness like this in a program helps the user feel more in control of the work he is doing.
Translators
Haiku comes with quite a bit of technology that allows lazy programmers to be lazy and still have their programs be good ones. One of those ways is with the Translation Kit. Merely by including the library and making use of even something as simple as the BTranslationUtils class will help to ensure that at least this portion of your code is free of bugs. In general, you will probably find yourself making use of image translators most in order to load image resources that your program will use. Just remember that translators are system add-ons and that unless your program has installed a translator for a particular file format, depend only on the formats installed by default in the system. Note that because MP3 is a format which requires licensing for decoding and encoding to be legal, depending on the MP3 format is not a good idea unless your program deals specifically with it.
Haiku comes with bits of technology that allows lazy programmers to be lazy and still have their programs be good ones. One of them is the Translation Kit. Merely by including the library and making use of even something as simple as the BTranslationUtils class will help to ensure that at least this portion of your code is free of bugs. In general, you will probably find yourself making use of image translators most in order to load image resources that your program will use. Just remember that translators are system add-ons and that unless your program has installed a translator for a particular file format, depend only on the formats installed by default in the system. As an aside, MP3 is a format which requires licensing for decoding and encoding to be legal, so depending on the MP3 format is not a good idea unless your program deals specifically with it.
Formats to prefer:
Image: JPEG/PNG
Image: JPEG or PNG
Sound: WAV or Ogg Vorbis
Movie: MPEG4 or AVI
Squeezing the Most out of BFS: Queries and Attributes
Squeezing the Most Out of BFS: Queries and Attributes
The filesystem that Be created was nothing short of amazing at the time. Even with the gradual evolution of other operating systems having progressed since then, it is still one of the most powerful around. Attributes are a powerful tool allowing you to store data about a file without being part of the file. This kind of power is very useful for audio files, such as FLAC, Ogg Vorbis, and the ubiquitous MP3. By using attributes, you can search for them with a query. Queries are also a powerful, unique tool in the operating system. As long as the attribute you are querying for is indexed in the filesystem, there is no place a file with that attribute can hide. In addition, they are a fast way of search for files meeting a certain criteria.
Although both attributes and queries are very powerful, use good sense in utilizing them. It takes quite a while to read a large number of attributes from a file, so you may wish to cache them if you are writing a program which will need to read more than just a few of them. Queries can only make use of attributes which are indexed, and their speed goes down as more and more attributes are indexed.
The filesystem that Be created was nothing short of amazing in the 1990s. Even with the gradual evolution of other operating systems having progressed since then, it is still one of the most powerful around. Attributes are a powerful tool which allow you to store data about a file without being part of the file. This kind of power is easily put to use with audio files, such as FLAC, Ogg Vorbis, and the ubiquitous MP3. By attaching attributes to audio files, you can search for them with a query. Queries also leverage the filesystem's power. As long as the attribute you are querying for is indexed in the filesystem, there is no place a file with that attribute can hide. To top it all off, they are also a fast way of search for files meeting a certain criteria.
Although both attributes and queries are very powerful, use good sense in utilizing them. It takes quite a while to read a large number of attributes from a file, so you may wish to cache them if you are writing a program which will need to read more than just a few of them. Queries can only make use of attributes which are indexed, and their speed goes down as more and more attributes are indexed, so use good sense, as well.
The System Tray
The System Tray: It's Not Just for Dinner
Because it can very easily become cluttered, install icons in the Deskbar's shelf only when it provides information that is updated often or if it provides functionality which will be frequently accessed by the user. Examples of these kinds of situations would be monitoring memory and processor load, checking mail, or quick access to features provided by a personal information management program. If it is unlikely that the user will need to access the information or functionality less than once per session, don't make use of the Deskbar. Accessing your program by way of the Programs menu or an icon on the desktop should be sufficient for tasks in these instances.
Because it can very easily become cluttered, install icons in the Deskbar's shelf only when it provides information that is updated often or if it provides functionality which will be frequently accessed by the user. Examples of these kinds of situations would be monitoring memory and processor load, checking mail, or quick access to features provided by a personal information management program. If it is unlikely that the user will need to access the information or functionality less than once per session, don't use the Deskbar -- accessing your program through the Be menu or an icon on the desktop should be sufficient.
Tracker and its Uses
Tracker can be quite a useful tool for your program which requires little effort to provide some courtesies to the user which would otherwise be a lot of work. The Open and Save windows have already been done for you -- please use them. Note that if your user will need only a certain type of entry, such as a folder or specific type of file, take the steps to show only those types of entries. By removing unneeded items from the file navigation window, you are reducing the number of choices the user must pick from and also preventing him from opening the wrong kinds of files. Keep in mind that there may be files that may not have had their MIME type identified, so do not exclude them, e'ther. You can also make Tracker show a window for a particular folder in order to show the user where a particular file has been stored and give him access to it directly.
Tracker can be quite a useful tool for your program which requires little effort to provide some courtesies to the user which would otherwise be a lot of work. The Open and Save windows have already been done for you. Please use them. Note that if just a certain type of entry is needed, such as a folder or specific type of file, make a filter that shows only those types of entries. By removing unneeded items from the file navigation window, you are reducing the number of choices the user must pick from and also preventing him from opening the wrong kinds of files. Keep in mind that there may be files that may not have had their MIME type identified, so do not exclude them, either. You can also make Tracker show a window for a particular folder in order to show the user where a particular file has been stored and give him access to it directly.
Chapter 4: Getting Input from the User
While it might seem a simple case to get input from the user, it is often not the case if you wish to account for many external factors, such as accessibility, speed, and user expertise.
While it might seem a simple case to get input from the user, it is often not the case if you wish to account for many external factors, such as accessibility, speed, and user expertise.
Mouse Vocabulary, AKA "You Want Me to What?!"
The mouse, while the favorite rodent of most users, is not a very intuitive device -- mouse skills must be learned. Most of the time, mouse skills are not an issue because the user is clicking on buttons, menus, and so forth, but sometimes a program must deal directly with mouse clicks and moves. Mouse operations fall into one of three categories.
The mouse, while the favorite rodent of most users, is not a very intuitive device: mouse skills must be learned. Most of the time, mouse skills are not an issue because the user is clicking on buttons, menus, and so forth, but sometimes a program must deal directly with mouse clicks and moves. Mouse operations fall into one of three categories.
Skills you can expect the user to have:
1) Single-click
2) Double-click on primary mouse button
3) Single click with secondary mouse button
4) Drag with primary mouse button
Skills the user might have:
1) Drag with secondary mouse button
2) Single-click with tertiary mouse button
3) Single-click on primary mouse button with modifier key
@ -267,13 +262,14 @@ Skills the user might have:
7) Drag with the tertiary mouse button
Don't Use These:
1) Click-and-a-half: Mouse down + mouse up + drag with a second mouse down
2) Multiple click with non-primary mouse button
3) More than 3 consecutive clicks (quadruple clicking or more)
4) Drag with tertiary mouse button
5) Drag with modifier keys
In the event that your program must deal with directly handling mouse input, there are certain guidelines to go by for how each of the expected skills is to be used. Single-clicks are used for the most common actions in operating a control. This would be selecting items in a list, pushing a button, choosing a menu item, and placing the blinking text cursor in a BTextView. Double-clicks are used for secondary functions, such as invoking an item in a BListView or selecting a word in a BTextView. Secondary mouse clicks (most commonly called "right-clicking") are generally used for a context-sensitive menu or, in the case of graphics programs, drawing with the secondary color. Mouse dragging is used for selecting text or moving things around. Mouse dragging with B_TERTIARY_BUTTON is generally used for panning. The scroll wheel by itself should be used just for scrolling, but your program may have a use for the scroll wheel when used with a modifier key, as below:
In the event that your program must deal with directly handling mouse input, there are certain rules of thumb for how each of the expected skills is to be used. Single clicks are used for the most common actions in operating a control. This would be selecting items in a list, pushing a button, choosing a menu item, and placing the blinking text cursor in a BTextView. Double clicks are used for secondary functions, such as invoking an item in a BListView or selecting a word in a BTextView. Secondary mouse clicks (most commonly called "right-clicking") are generally used for a context-sensitive menu or, in the case of graphics programs, drawing with the secondary color. Mouse dragging is used for selecting text or moving things around. Mouse dragging with B_TERTIARY_BUTTON is generally used for panning. The scroll wheel by itself should be used just for scrolling, but your program may have a use for the scroll wheel when used with a modifier key, as below:
Scroll Wheel +
@ -282,9 +278,9 @@ B_OPTION_KEY: Scroll by one full page
B_CONTROL_KEY: Increase/decrease font size
Keyboard accelerators: The Sports Cars of GUIs
Keyboard Accelerators: The Sports Cars of GUIs
More advanced users often like using keyboard shortcuts for common tasks because they are fast -- considerable time is spent simply moving your hand from the keyboard to the mouse or vice versa.
More advanced users often like using keyboard shortcuts for common tasks because they reduce the considerable amount time spent switching between the keyboard and the mouse.
Standard System Accelerators:
@ -292,7 +288,7 @@ Standard System Accelerators:
B_COMMAND_KEY + N: New Document
B_COMMAND_KEY + O: Open Document
B_COMMAND_KEY + S: Save Document
B_COMMAND_KEY + Shift + S: Save As (show Save Dialog window)
B_COMMAND_KEY + Shift + S: Save As (show Save dialog window)
B_COMMAND_KEY + P: Print
B_COMMAND_KEY + W: Close Active Window
B_COMMAND_KEY + Q: Quit
@ -323,16 +319,14 @@ Tab / Shift + Tab: Keyboard navigation
B_CONTROL_KEY + Tab: Switch programs
When choosing keyboard accelerators for your program, use them only for commonly-used tasks. Do not use one of the system combinations for a task different from the list above -- it will only confuse and frustrate users. Also, try to keep the number of them small with an immediately memorable association between the combination and the function that goes with it. For example, Tracker uses Alt + Up to go to the parent folder of the current window.
When choosing keyboard accelerators for your program, use them only for commonly-used tasks. Do not use one of the system combinations for a task different from the list above. Doing so will only confuse and frustrate users. Choose key combinations which are easily associated with the functions that go with them. For example, Tracker uses Alt + Up to go to the parent folder of the current window. The Command key should be the main shortcut key. The Option key is generally used to modify an existing shortcut with a closely related function. Command + F shows the Find window. Command + Option + F shows the Replace window.
Design without Throwing Fitts
According to Mr. Fitts, when using a mouse, the amount of time it takes to point to something is proportional to how far away that something is and how big it is. Duh. While it might seem obvious, this is often overlooked when the GUI to a program is designed. The easiest places for a user to click are the four corners of the screen and the pixel directly under the cursor. The reason for this is because the mouse need not be moved for to click on the pixel under it and the user does not have to think much when moving the cursor to a corner because as soon as it reaches an edge, it cannot go beyond the edge of the screen, regardless of how much the mouse is moved. This is the reason that the Deskbar is in one corner of the screen.
When you design the graphical interface for your program, make controls easy to click on. Toolbars that have labels for each button are inherently better because the labels add to the size of the buttons, making them easier to click. A number of existing image editing programs utilize the secondary mouse button for a pop-up menu to access common features because the mouse doesn't have to move in order to bring the menu up. Researchers have even experimented with circular menus -- called pie menus -- which capitalize on Fitts' Law in order to make a menu as fast as possible. Your program need not go to such measures, but do keep in mind that teeny targets make for slower usage.
According to Mr. Fitts, when using a mouse or other pointing device, the amount of time it takes to point to something is proportional to how far away that something is and how big it is. While it might seem obvious, this is often overlooked when a program is designed. The easiest places for a user to click are the four corners of the screen and the pixel directly under the cursor. The reason for this is because the mouse need not be moved for to click on the pixel under it and the user does not have to think much when moving the cursor to a corner because as soon as it reaches an edge, it can go no farther in that direction regardless of how much the mouse is moved. For this reason the Deskbar is in one corner of the screen.
When you design the graphical interface for your program, make controls easy to click on. Toolbars that have a text label as part of each button are inherently easier to click because the labels add to the size of the buttons. A number of existing image editing programs use the secondary mouse button for a pop-up menu to access common features because the mouse doesn't have to move in order to bring the menu up. Researchers have even experimented with circular menus -- called pie menus -- which capitalize on Fitts' Law in order to make a menu as fast as possible. Your program need not go to such measures, but do keep in mind that teeny controls slow users down.
@ -341,10 +335,10 @@ Chapter 5: Dynamic Data Exchange: Pass Data Between Applications
Drag and Drop
The ability of a user to click and drag an object and drop it somewhere else is a powerful design tool, just as other means of direct manipulation. In general, it should be used only where it makes sense to do so -- rearranging items in a list, file management, opening a file dragged to your app from Tracker, etc.
If you plan on supporting dragging within your program or to other programs -- even just a little bit -- you should support drops to the likely places a user might drop something into your program. Most of the time, this shouldn't be all that difficult because drops to your program will come from either Tracker (in the form of an entry_ref) or from within your own program. Drops from other programs are not required, but if they are especially convenient, they can be a nice bullet point in a marketing blurb for your program.
Not to be confused with falling reptiles, the ability of a user to click on an object, drag it to some target, and drop it to make the target do something with it is both familiar and empowering, just as are other direct manipulation methods. Nonetheless, the drag-and-drop paradigm should be used only where it makes sense to do so -- rearranging items in a list, file management, opening a file dragged to your app from Tracker, etc.
If you plan on supporting dragging within your program or to other programs -- even just a little bit -- you should support drops to the most probable targets in your program. This shouldn't normally be all that difficult because drops to your program will come from either Tracker (in the form of an entry_ref) or from within your own program. Drops from other programs are not required, but if they are especially convenient, they can be a nice bullet point in a marketing blurb for your program.
When implementing dragging, be sure that your program provides feedback about what is being dragged. This is often best done by using an image which closely represents what is being dragged. If this is not possible, a rectangle which is the size of the dragged item's selection should be used in place of the picture.
A feature which is very helpful to a user is drop feedback. Any time the user is dragging something and the cursor passes over your program's window, it can react in a way to show the user that your program will accept the dragged object. This can be done in a variety of ways:
A feature which is very helpful to a user is drop feedback. Any time the user is dragging something and the cursor passes over your program's window, it can react in a way to show the user that your program will accept the dragged object. Drop feedback can take a variety of forms:
- A list control could draw a line in between two items to show where the item would go.
@ -354,12 +348,12 @@ Drag and Drop
- A color well could highlight its border
There are other possible ways, but these should be enough for you to get the idea. As mentioned before, feedback is a Good Thing (TM) -- one more way to be responsive -- which allows the user to better understand how to use your program to get something done.
There are other possible ways, but these should be enough for you to get the idea. As mentioned before, feedback is a Good Thing (TM). It allows the user to better understand how to use your program to get something done.
The Clipboard
One way of getting data from one program into another is via the system clipboard. Unlike other forms of data exchange, using the clipboard requires very little effort or code because all that is needed is to plunk data into a particular BMessage. Depending on what the needs are for your app, there may be very little you need to do to add clipboard support. The BTextView class already implements copying, cutting, and pasting by way of keyboard accelerators. In cases like these, all that you will want to do is add some menu items to let less advanced users know that it is available for use.
Another way of getting data from one program into another is via the system clipboard. Unlike other forms of data exchange, using the clipboard requires very little effort or code because you have to do is to plunk data into a particular BMessage. Some of the standard controls already do it for you. The BTextView class already implements copying, cutting, and pasting by way of keyboard accelerators. In cases like these, all that you will want to do is add some menu items for less advanced users.
Standardized Clipboard Data Formats
@ -367,15 +361,15 @@ Plain Text: It is easiest to describe the basics with this code snippet.
clipboard->AddData("text/plain", B_MIME_TYPE, your_text_string_here);
Styled Text: The same as plain text but adding a text run array field to the message also. You probably won't need to worry about this unless you're writing a word processor or something similar.
Styled Text: Use the same format as for plain text but add a text run array field to the message also. You probably won't need to worry about this unless you're writing a word processor or something similar.
clipboard->AddData("application/x-vnd.Be-text_run_array", B_MIME_TYPE, run_array, run_array_size);
Generic File References: If the amount of data you wish to pass to another program is too large to place on the clipboard without straining the system, you may wish to place an entry_ref which points to it on the clipboard instead. Audio and video files commonly fall into this category. To do this, call AddRef() with the field name "refs" and add an entry_ref pointing to the file you wish to pass this may. Note that you may pass multiple entry_ref objects this way. Programs wishing to receive file references should look for multiple entries in the 'refs' field unless it is inappropriate for the particular application to do so.
Generic File References: If the amount of data you wish to pass to another program is too large to place on the clipboard without straining the system, dump the data to a temporary file and place an entry_ref which points to it on the clipboard instead. Audio and video files commonly suffer from this problem. To do this, call AddRef() with the field name "refs" and add an entry_ref pointing to the file you wish to pass this may. Multiple entry_ref objects can be sent just by doing it more than once. If your program is going to handle these kinds of drops file references, it should look for multiple entries in the 'refs' field unless it would be inappropriate to do so.
Image Data:
If your program uses a different kind of data than what has already been standardized, there are some guidelines you can follow so that other programs can make use of what yours puts on the system clipboard. First, make sure that the data that is put on the clipboard is in as generalized a form as possible.
If your program uses a different kind of data than what has already been standardized, there are some guidelines you can follow so that other programs can use it. First, make sure that the data that is put on the clipboard is in as generalized a form as possible.
Field Type Name Description
B_STRING_TYPE class "BBitmap"
@ -386,38 +380,34 @@ B_INT32_TYPE _rowbytes The number of bytes per row, including padding
B_RAW_TYPE _data The raw image data
B_POINT_TYPE be:location The location from which the image data was copied. May be ignored.
Video Data:
TODO: This needs to be decided upon by people who know media better than I do
Replicants
Replicants are neat. Replicants are neat. Replicants are ... *thump* .... Sorry - I got carried away, so to speak. :^) As cool as replicant technology is, it is best left as an extra feature and not the primary mode of operation for a program because it is only an emerging technology in other, more popular operating systems and is unfamiliar to most users as such. There are some guidelines for using them, however.
Replicants are neat. Replicants are neat. Replicants are ... *thump* .... Sorry - I got carried away, so to speak. :^) As cool as replicant technology is, it is only an emerging technology in other operating systems and is unfamiliar to most users in general. As such, it is best left as an extra feature and not the primary mode of operation for a program. There are some guidelines for using them, however.
1) It is apppropriate for program to be a replicant if it is a lightweight program which provides information or a feature which the user will want to be able to access frequently.
1) It is appropriate for program to be a replicant if it is a lightweight program which provides information or a feature which the user will want to be able to access frequently.
2) Allow for the size of the dragger handle when computing layout
3) Be sure it is of sufficient size to not get lost when placed in the midst of a busy desktop background. At the same time, do not take over the user's desktop unless he wants this to happen. 32 pixels square is a good size, for example.
3) Be sure it is big enough to not get lost when placed on a busy desktop background. At the same time, do not take over the user's desktop unless he wants this to happen. 32 pixels square is a good minimum size, for example.
4) Do not rely on the menu provided by the dragger handle to control the replicant if it does not have a menu bar of its own. Instead, provide another means which is immediately obvious or, at the very least, show a pop-up menu if the user clicks on it (with either button) and there are no other clickable controls.
4) Provide a reliable way for the user to control your replicant. Do not rely on the menu provided by the dragger handle it does not have a menu bar of its own because the handle may have been hidden. Instead, provide another means which is immediately obvious or, at the very least, show a pop-up menu if the user clicks on it (with either button) and there are no other clickable controls.
5) Place a frame around the replicant's main border so that it stands out from its surroundings
5) Place a frame around the replicant's border so that it stands out from its surroundings
6) The replicant should not be too visually distracting. This mainly entails choosing muted colors for the controls and limiting the amount of animation and movement.
6) Do not make it too visually distracting. This mainly amounts to avoiding lots of bright colors for the controls and limiting the amount of animation and movement.
Chapter 6: Use of Text in the GUI
Almost without exception, if you are writing a program, you will need to pay at least a little attention to how it uses text. There is, believe it or not, a right way and a wrong way to use text in your program, and while most of the guidelines for text might seem trivial, attention to detail is what separates a good program from a great one.
Almost without exception, if you are writing a program, you will need to pay at least a little attention to how it uses text. There is, believe it or not, are right ways and wrong ways, and while most of the guidelines for text might seem trivial, paying attention to what seem like niggling little details is what makes a good program into a great one.
Above all else mentioned in this chapter, use everyday language and be both clear and concise.
Above all else mentioned in this chapter, use everyday language -- not technical terms-- and be both clear and concise.
Error Messages
Error Messages, or, "I'm sorry Dave. I'm afraid I can't do that"
Perhaps the place where you should use text the most is in error messages. They should appear as seldom as possible because you anticipated and handled as many error conditions as possible, right? Right? :) When your program can't handle a particular error, the error message given to the user should follow these rules of thumb:
Perhaps the place where you should use text the most is in error messages. They should appear as seldom as possible because you anticipated and handled as many error conditions as possible and tried to blow it up real good, right? ;) When your program can't handle a particular error, the error message given to the user should do the following:
1) Explain what happened in everyday words.
@ -425,13 +415,13 @@ Error Messages
3) Offer suggestions to help the user fix the problem, if possible. Using the above example, one possible suggestion might be "Try checking your Internet connection with your web browser. If that works, the mail server might not be working correctly and you may want to try again later."
Ellipses
...Ellipses...
An ellipsis is a series of 3 dots (...). It is used in a GUI to convey to the user that a control, often a menu item or button, will open a window. For example, a menu item named "New..." will display a window which has the title "New". However, if creating a new document does not require showing a window, then an ellipsis should not be used. Please be sure to use the B_UTF8_ELLIPSIS character instead of 3 periods. Many keymaps allow you to type in an ellipsis with Option + period.
An ellipsis is a series of 3 dots (...) used to tell the user that a control, often a menu item or button, will open a window. For example, a menu item named "New..." will display a window which has the title "New". However, if creating a new document does not require showing a window, then an ellipsis should not be used. Please be sure to use the B_UTF8_ELLIPSIS character instead of 3 periods. Many keymaps allow you to type in an ellipsis with the Option + period keyboard shortcut.
Abbreviations, Acronyms, and Contractions, oh my!
Sometimes space is at a premium. Abbreviations, acronyms, and contractions can come in very handy in these instances, but they can also lead to confusion. Whenever possible, avoid using them -- many times the reason there is not enough space is because more can be done with control layout to use existing screen real estate more efficiently. When using an abbreviation, please be sure that it is absolutely necessary, that it is both common and clear, and that it is appropriate for your program's target audience. For example, using the octothorpe (# symbol) is an abbreviation for the word 'number' in the English language which fits these criteria in most cases. These same guidelines also apply to acronyms. For example, the acronym CMYK (Cyan, Magenta, Yellow, Black) is acceptable in a color picker for an image processing application designed for graphics professionals, but not in one meant for children.
Sometimes space is at a premium. Abbreviations, acronyms, and contractions can come in very handy in these instances, but they can also be confusing. Whenever possible, avoid using them. Many times the reason there is not enough space is it isn't being used as efficiently as possible. When you use an abbreviation, please be sure that it is absolutely necessary, that it is both common and clear, and that it is appropriate for your program's target audience. For example, using the octothorpe (# symbol) is an abbreviation for the word 'number' in the English language which fits these criteria in most cases. These same guidelines also apply to acronyms. For example, the acronym CMYK (Cyan, Magenta, Yellow, Black) is acceptable in a color picker for an image processing application designed for graphics professionals, but not in one meant for children. Menus and button labels should never be abbreviated or contain an acronym.
Special care must be used with contractions. They can be a pitfall for users who are not using a program which is in their native language. Because they require more advanced command of the language, avoid using them in a place where their role is crucial in conveying the meaning of a message. For example, a checkbox for a message dialog with a checkbox marked "Don't show this message again" which is unchecked by default should be reworded "Always show this message" and have the checkbox checked by default.
cApItAlIzAtIoN and Speling
@ -440,54 +430,52 @@ cApItAlIzAtIoN and Speling
Use of Fonts
Good use of fonts can make your program more visually appealing, but when not used well, can make it an eyesore, hard-to-read, or worse. As a general rule, stick to the plain, bold, and fixed system fonts. This will result in more visual consistency across the operating system. It is perfectly acceptable to use a different font size, but do so only when a heading is needed or something similar and try to limit the number of different sizes to 2 or 3. A window which has lots of different font styles or sizes is harder to read and looks less professional. Control labels should always be in the system plain font and size specified by the system.
Good use of fonts can way make your program more visually appealing, but when not used well, can make it ugly, hard to read, or worse. Stick to the plain, bold, and fixed system fonts to maintain some general visual consistency across the operating system. It is perfectly acceptable to use a different font size, but do it only when you need a heading or something similar and try to limit the number of different sizes to just a few. A window which has lots of different font styles and sizes is harder to read and looks unprofessional. Control labels should always be in the system plain font and size specified by the system.
When calculating the layout for the controls, be sure that you do not depend on the system font being set to a particular font size. Most BControl-derived controls implement the methods GetPreferredSize and ResizeToPreferred to take font size into account. A basic idea of the line height for a font can be calculated by calling BFont::GetHeight() and adding together the values of the font_height structure.
Lastly, do not depend on the user having a particular font installed on the system unless you are willing to ensure that the user has it installed on the system. If you do follow this route, be sure to check to see if you have redistribution rights for the font's license for the font in question.
Lastly, do not depend on the user having a particular font installed on the system unless you are willing to ensure that the user has it installed on the system. Font handling for your program is your responsibility, not the user's. If you do follow this route, be sure to check to see if you have redistribution rights for the font's license for the font in question.
Special Case: The Command Line
When designing a program to work in a command-line environment there are some special considerations which must be addressed. Interaction with other programs, use in shell scripts, and a generally consistent interface for command-line programs are just some of the things you will need to keep in mind. The major design decisions you should make are how your program will get its data, what options are available, and what feedback the user will be given.
Give some thought to how your program should interact with the shell and with other programs. Most of the time, this will boil down to whether your program is file-oriented or stream-oriented. Stream-oriented programs more or less work like filters -- getting data from stdin and dumping data to stdout. Programs like grep and less work this way. File-oriented programs like zip and bzip2 are given a list of files which the program then operates on. Your program can certainly use both stream input and file input, but one of the two methods should be considered the primary method because of the influence it will have on other design decisions. If your program is file-oriented, seriously consider handling wildcards instead of relying on the shell to do it. While this does mean more work for you as a developer, it also reduces typing and, thus, typing errors. Of course, if supporting wildcards does not make sense for reasons specific to your program, then don't do it.
Options accessible by command-line switches should be carefully designed just like any other feature of your program. An option should be available only if it fills a reasonably common task. Please remember that complexity in using your program increases as options are added -- options are essentially additional features. GNU-style (double dash + long name) switches should be provided for all options. The most commonly-used options should also have a corresponding short (single-dash + single letter) one. The GNU-style --help and short-style -h switches are reserved for showing help. Note that while standard UNIX applications (ls, tar, df, etc.) are not required to follow the standard for -h in order to avoid breaking backward compatibility, all new command-line programs need to follow this.
When an option requires a particular value, there is also a standard for how the user is to provide the information. GNU-style command options should follow the format --option=value with the option to enclose the value in quotes. Multiple values should be comma-separated. Short-style command options should place a space between each value that follows it in this manner: -t value1 value2 value2 ... Note that as mentioned above wildcards should be handled by the program except when it does not make sense to do so. If your program does something which modifies data, make sure that your program requires some sort of parameter -- a switch, a file, or whatever -- so that data is not lost should the user invoke your program without knowing what it does; do not expect the user to have expert knowledge of the operating system or, for that matter, your program. Programs which merely report information -- ls comes to mind -- are not required to follow this provided that the information shown gives the user a sufficient idea of what the program does.
Be sure to provide adequate feedback when your program performs its task. Just as in graphical programs, long tasks should inform the user of progress. This may be something as complex as the progress meter used by wget, a simple series of periods, a listing each file operated on, or something else. *All* programs should provide some sort of feedback -- the only time a program may print nothing is if there is a "quiet" option which the user has specified. The feedback doesn't even have to be excessive; general details can be provided. A "verbose" option should provide more detail than the program does by default. Error messages should be no more technical than absolutely necessary and should be helpful whenever possible. If no input is specified and is required, show the same message as for the help option or an abbreviated version thereof which is still reasonably informative along with a message pointing the user to the help option for more detailed information.
Spend some time thinking about how your program should interact with the shell and with other programs. Most of the time, this will boil down to whether your program is file-oriented or stream-oriented. Stream-oriented programs like grep and less work more or less like filters, getting data from stdin and dumping data to stdout. File-oriented programs like zip and bzip2 are given a list of files which the program then operates on. Your program can certainly do both, but choose a primary method because it will influence design decisions later on. Seriously consider handling wildcards instead of relying on the shell to do it if your program is file-oriented. This does mean more work for you as a developer, but it also reduces typing and, thus, typing errors for the user. Of course, if it doesn't make sense to support wildcards, then don't do it.
Choose options which are going to be accessible by command-line switches carefully. Make each one available only if it fills a reasonably common task. From the perspective of the user, adding an option is adding a feature, which will, int turn, increase the complexity of your program. Provide GNU-style (double dash + long name) switches for all options. The most commonly-used options should also have a corresponding short (single-dash + single letter) one. The switches --help and -h are reserved for showing help information. Only standard UNIX applications (ls, tar, df, etc.) are not required to follow the standard for -h in order to avoid breaking backward compatibility. All new command-line programs need to follow this.
When an option requires a particular value, there is also a standard for how the user is to provide the information. GNU-style command options should follow the format --option=value with the option to enclose the value in quotes. Multiple values for a switch should be comma-separated. Short-style command options should place a space between each value that follows it like this: -t value1 value2 value2 ... As mentioned above, wildcards should be handled by the program except when it does not make sense. If your program does something which modifies data, make sure that your program requires some sort of parameter -- a switch, a file, or whatever -- so that data is not lost if the user invokes your program without knowing what it does. You can assume that the user is sharper than a bowling ball, but do not expect the user to have expert knowledge of the operating system or, for that matter, your program. Programs which merely report information, ls and df come to mind, are not required to do this as long as the information displayed gives the user an idea of what the program does.
Be sure to give enough feedback when your program does its thing. Like graphical programs, long tasks should inform the user of progress. This may be something as complex as a full-fledged progress meter drawn with text, a simple series of periods, a listing each file operated on, or something else. *All* programs should provide some sort of feedback -- the only time a program may print nothing is if there is a "quiet" option which the user has specified. The feedback your program gives doesn't even have to be excessive; you can just give general details. A "verbose" option should provide more detail than the program does by default. As explained earlier in this chapter, error messages should be no more technical than absolutely necessary and should be helpful whenever possible. If your program requires a parameter of some sort and isn't given any, show either the same message as for the help option or an abbreviated version which is still reasonably informative along with something to point the user to the help option for more detailed information.
Chapter 7: Branding - Program Icons, About Windows, Graphics, and other Visuals
Chapter 7: Branding - Program Icons, About Windows, Graphics, and Other Visuals at the OK Corral
With all this discussion, you may be beginning to think that having a well-designed program means that it is visually boring. This is not at all the case. There is plenty of freedom for creativity along with some guidelines to get you started.
With all this discussion, you may be beginning to think that having a well-designed program means that it is going to be boring to look at. You can definitely have it more interesting to look at than drying paint. There is plenty of freedom for creativity along with some suggestions to help get you started.
Program Icons
Your program's icon is one easy way to set it apart from the rest of the pack. BeOS icons follow one of two perspectives - flat and isometric. Flat icons are those which are from a head-on view. Isometric icons "look down" on the icon from a point above and to the right of the object with "horizontal" lines angling at about -30 degrees. A good icon can impart a favorable and professional impression of your program to people who are otherwise unfamiliar with it. Take some time to create or find a good-looking icon. At worst, don't use an icon at all and rely on the system to show the default application icon. The default icon, while not as good as a well-designed one unique to your program, is a much better choice than a shabby one. An icon which was drawn in haste does not reflect well on your program's reputation.
Your program's icon is one easy way to set it apart from the rest of the pack. BeOS-style icons follow one of two perspectives - flat and isometric. Flat icons look like a head-on view. Isometric icons "look down" on the icon from a point above and to the right of the object with angled lines being about 30 degrees from horizontal. A good icon can give your program a favorable and professional impression to people who otherwise doesn't know a thing about you or your program. Take some time to create or find a good-looking icon. Whatever you do, don't just slap together a shabby-looking icon. It would be better not provide an icon at all and rely on the system to show the default application icon than to have one which reflects poorly on your program's reputation.
Icon Design Tips:
Design Tips:
- Remember that this will be small - don't use too much detail.
1) Remember that this will be small -- don't use too much detail.
- Use color combinations pleasing to the eye.
2) Use color combinations pleasing to the eye.
- Tie it into the general color scheme of your program if there is one.
3) Tie it into the general color scheme of your program if it has one.
About Windows
About Windows... Doorways to Creative Expression
Give yourself some credit in your program - make an About Window. They don't need to be especially fancy, but they can be if you are so inclined. It should contain the title of your program, the version, you and any other authors, and copyright information. If nothing else, a few lines of code to show a BAlert with this information is all that is needed. If there is a lot of information to show, using a marquee effect to automatically scroll the information or something similar would be a good idea. Do not include information about the computer itself, such as the amount of RAM or processor speed. While you certainly may show something like "Distributed under the terms of the GNU Public License," the full text of the license your program is distributed under belongs elsewhere. The window should not have a title and should either have a button marked 'Close' or simply disappear when clicked. It should also respond to the Command + W keyboard shortcut.
Give yourself some credit in your program: make an About window. They don't need to be especially fancy, but they can be if you are so inclined. It should contain the title of your program, the version, you and any other authors or the name of your company, and copyright information. If nothing else, write a few lines of code to show a BAlert with this information and you'll have enough. If there is a lot of information to show, using a marquee effect to automatically scroll the information or at least a read-only text view with a scroll bar. Do not include information about the computer itself, such as the amount of RAM or processor speed -- it doesn't belong here. While you certainly may show something short about the licensing of your program like "Distributed under the terms of the GNU Public License," the full text of the license belongs elsewhere. The window should not have a tab and should either have a button marked 'Close' or simply disappear when clicked. It should also respond to the Command + W keyboard shortcut.
Graphics and Other Visuals
Graphics and Other Stuff
Graphics need not even be limited to your About window and the program icon. You can also use background images in BViews, toolbars, buttons, and other places. There are few hard-and-fast rules here, but there are some tips you might find useful:
Graphics need not be limited to just the About window and the program icon. You can also use background images in BViews, toolbars, buttons, and other places. There are few hard-and-fast rules here, but there are some tips you might find useful:
- The associated function of each toolbar icon should be immediately recognizable
1) Follow the Dos and Don'ts for toolbars mentioned in Chapter 12
- Labelled toolbar buttons are easier to click and the reduces -- but doesn't eliminate -- the amount of care needed when designing their icons.
2) Background images should not be too busy and should not reduce overall readability.
- Background images should not be too busy and should not reduce overall readability.
- If your program uses only a few small pictures, you may want to package them in a resource file to prevent them from somehow coming up missing in the installation on a user's machine. Crazy things happen on people's computers.
3) If your program uses only a few small pictures, you may want to package them in a resource file to prevent them from somehow coming up missing in the installation on a user's machine. Crazy things happen on people's computers.
@ -495,21 +483,21 @@ Chapter 8: Cursors
Predefined Cursors and their Use
Predefined Cursors and their Uses
As of this writing, there are only two predefined icons available for use in Haiku: the hand cursor and the text cursor. The text cursor is used whenever text editing is needed and the hand is used everywhere else. There will be more cursors for other uses at some future time which will include resizing and drag and drop.
As of this writing, there are only two predefined icons available in Haiku: the hand cursor and the text cursor. The text cursor is used whenever text editing is needed and the hand is used everywhere else. There will be more cursors for other uses at some future time which will include resizing and drag and drop.
Making Your Own Cursors
You can very easily make your own cursors for your own purposes, but do so only if a different cursor will dramatically improve how well the user can work with your program. When designing a cursor, keep in mind that at the moment they can only be 16 pixels square and in black and white. Be sure that the hot spot, the actual location passed to applications when a mouse button is pressed, is very obvious. Examples of this would be the tip of the hand cursor, the point of the arrow, or the center of a crosshairs. Use the full dimensions available whenever possible to increase the cursor's visibility at high screen resolutions.
You can very easily make your own cursors for your own purposes, but do it only if a different cursor will dramatically improve how well the user can work with your program. At the moment cursors can only be 16 pixels square and be black, white, or transparent. Be sure that the hot spot -- the actual location passed to applications when a mouse button is pressed -- is very obvious. Good hot spots are the tip of the hand cursor, the point of an arrow, or the center of a crosshairs. Use the full dimensions available to increase the cursor's visibility at high screen resolutions.
NOTE: There is not nor will there ever be a busy cursor in BeOS-based operating systems. This is a deliberate design decision. If you have a need for a busy cursor, you need to redesign your program for better responsiveness. Often you can use multiple threads to eliminate the need for a busy cursor.
NOTE: There is not nor will there ever be a busy cursor in BeOS-based operating systems. This is a deliberate design decision. If you have a need for a busy cursor, you need to make your program more responsive. Often you can use multiple threads to eliminate the need for a busy cursor.
Animating Cursors
While Haiku does not provide explicit support for them, it is possible to animate cursors to provide a little more graphical appeal. As with any kind of movement in the display, use animation sparingly so that it is not distracting.
While Haiku does not provide explicit support for them, you can animate cursors to provide a little more graphical appeal. As with any kind of movement in the display, use animation sparingly so that it is not distracting.
@ -517,14 +505,13 @@ Chapter 9: Menus, Menu Bars, and Menu Fields
Menus are about as commonplace in programs as windows are, but even though they are everywhere, far too many programs don't use them as well as they could be. Attention to small details in a program's menus is one common difference between good programs and great ones.
Menus are powerful and simple at the same time. They allow a developer to pack a lot of functionality into a small space and, at the same time, the user does not have to remember what the particular command is called -- they afford exploration of the interface in steps. This chapter will focus primarily on issues related to menus in general. Pop-up menus and menu fields are discussed in Chapter 11.
Menus are everywhere, but common as they may be, far too many programs could use them better. Attention to small details in a program's menus is one common difference between good programs and great ones. A developer can pack a lot of features into a small space and still not force the user to remember it all. Menus afford exploration of the interface in steps. This chapter will focus primarily on issues related to menus in general. Pop-up menus and menu fields are discussed in Chapter 12.
Naming and Organization
Choosing good names for menus and items is generally not difficult. A menu should have a name which is as short as possible and still accurately describes the items contained in it. For example, a File menu should not have Copy and Paste items in it. The same goes for items in the menu. The items are capitalized as described in Chapter 6 and an ellipsis is used after any items which open a window. Any window which is shown this way should have the same title as the item which showed it, so remember this when constructing menu item titles.
A common method for organizing menus is the Noun-Verb method, which names menus after the items that it pertains to and items in the menu are actions which can be operated on that item. For example, the File menu contains items such as Open, Print, Save, and Close.
Choosing good names for menus and menu items is generally not difficult. A menu should have a name which is short and accurately describes the kinds of items it contains. For instance, a File menu should not have Copy and Paste items in it. The name for a menu item should both concisely and accurately describe the function it performs. Items are capitalized as described in Chapter 6 and an ellipsis is used with any item which opens a window. If a menu item opens a window, the names of both the item and the window should be the same.
Two ways to organize menus are the Noun-Verb method and the Verb-Noun method. Noun-Verb names menus after the kind of object that it operates on and items in the menu are actions which can be performed on the object. For example, the File menu contains items such as Open, Print, Save, and Close. Verb-Noun names menus with an action and the items are objects which the action can be performed on. Two example menus could be View and Go. Some "standardized" menus, such as the Edit menu, do not follow either method.
Items should be organized and grouped by function and/or attribute. Use a separator item between each item group. An example of this would be an Edit menu which looks like this:
_________
@ -543,24 +530,55 @@ Naming and Organization
Marking and Toggling Items
Menus can also contain items which indicate the state of a feature, such as the visibility of a tool window. There are two ways that this can be done. The first is to use a menu item with a dynamic title. In both states, it must be completely clear to the user what will happen when the item is clicked just be reading the title. The other method is to place a checkmark beside the item indicating the current state. The advantage to this method is that it can be used for a choice of more than two states with the drawback of using more screen space. When using this method, all possible states need to be listed in order to prevent confusion.
Menus can also contain items which indicate the state of a feature, such as the visibility of a tool window. There are two ways that this can be done. The first is to use a menu item with a dynamic title. In both states, it must be completely clear to the user what will happen when the item is clicked just be reading the title. The other method is to place a checkmark beside the item indicating the current state. The advantage to this method is that it can be used for choosing from more than two states at the expense of screen space. When using this method, all possible states need to be listed in order to prevent confusion.
Examples of Good Dynamic Menu Item Usage:
|Window| -> Show Tool Window / Hide Tool Window, Show Color Picker / Hide Color Picker
|Options| -> Change to Wireframe Preview / Change to Full Preview
|Window|
-----------------
Show Tool Window
Hide Tool Window
-----------------
Show Color Picker
Hide Color Picker
-----------------
|Options|
---------------------------
Change to Wireframe Preview
Change to Full Preview
---------------------------
Examples of Good Multiple State Item Usage:
|Help| -> Read the Manual...|Show Tooltips,Do Not Show Tooltips|Go to the MyApp Website
|Font| -> Choose Font and Size...|Normal,Bold,Italics,Strikeout,Underline
|Help|
-----------------------
Read the Manual...
-----------------------
* Show Tooltips
Do Not Show Tooltips
-----------------------
Go to the MyApp Website
-----------------------
|Font|
-----------------------
Choose Font and Size...
-----------------------
* Normal
Bold
Italics
Bold Italics
Strikeout
Underline
-----------------------
Common Menus and their Contents
Below are descriptions for menus that are common to many programs. Because they are so common, there are some guidelines to how they should be used so that there is some consistency across the operating system. With the exception of the Program menu, each of these menus should be used only if they make sense for your program.
Below are descriptions for menus that are common to many programs. Because they are so common, there are some guidelines to their use so that there is some consistency from program to program. With the exception of the Program menu, each of these menus should be used only if they make sense for your program.
Program: Items related to operating on the program itself.
@ -569,25 +587,25 @@ About <app name here>... - shows the About window. This is not a commonly-access
Options... (Command - ,) - Show the window which is used to customize options for your program. This can be a submenu if your program only has a couple of options.
Quit (Command + Q) - This should be the bottom item in the menu and a separator should go above it.
Quit (Command + Q) - This should be the bottom item in the menu and a separator should go above it. Clicking on this item should close all windows and quit the program.
File: This contains items related to documents handled by your program.
New (Command + N) - Create a new document. This item should have an ellipsis if it shows a "Create Document" kind of window, but not if it doesn't.
New (Command + N) - Create a new document. This item should have an ellipsis if it shows a window, but not if it doesn't.
Open... (Command + O) - Open a document from disk.
Open Recent - This is a submenu in the File menu to allow fast access to recent documents. It should not open a window of any kind. The number of recent items should be limited to no more than 5 items.
Close (Command + W) - The function of this item depends on the kind of program architecture. In a program which has one document per window, this closes the window. If there are no more windows in the program, this also quits the program. Although it is not recommended, should a program allow for multiple documents in the same window, this item closes one document.
Close (Command + W) - The function of this item depends on the program architecture. In a program which has one document per window, this closes the window. If there is only one open window, this quits the program. Although it is not recommended, if a program allows for multiple documents to be shown in the same window, this item closes one document.
Save (Command + S) - Save the current document. This should not show a window unless the document is new and has not yet been saved. It does not normally show a window, so no ellipsis is necessary.
Save (Command + S) - Save the current document. This should not show a window unless it is a new document that has not yet been saved. It does not normally show a window, so no ellipsis is necessary.
Save As... (Command + Shift + S) -
Save As... (Command + Shift + S) - This performs the same basic kind of task as Save, but it always shows a window.
Save All - This item executes a Save command for all documents in the program. The procedure for handling new documents which have not yet been saved is as follows:
1) Make note of the current document window
1) Remember the current document window
2) For each document needing a name, bring it to the front, open a Save window, save the document, and proceed to the next document needing a name.
3) When all documents have been processed, bring the window which was originally the active one back to the front.
@ -626,7 +644,7 @@ Find Again (Command + G) - This repeats the most recent Find. If no find has bee
Help: Different ways that the user can learn more about your program and get help when needed.
Read the Manual... - Shows the manual for the program in a new window.
Read the Manual... - Shows the manual for the program in a new window. The manual should never be shown in a BAlert.
Go to (MyApp or MyCompany)'s Website - Opens the default web browser at the website for the program or the program's company, respectively.
@ -637,11 +655,9 @@ Chapter 10: Windows
You Need the Basics
Windows are such common controls that every developer should know the basics in when and how they should and should not be used. Some operating systems suffer from the overuse and abuse of windows, such as bizarre error messages, incessant confirmations, wrong window types for tasks, and many other mistakes. Learn the proper ways of working with windows and you will have overcome a major usability hurdle.
Windows are such common controls that every developer should know the basics of how to use them properly. Some operating systems suffer from the overuse and abuse of windows, such as bizarre error messages, incessant confirmations, wrong window types for tasks, and many other mistakes. Learn the proper ways of working with windows and you will have overcome a major usability hurdle.
Styles
There is quite a lot of power and flexibility in how window looks and behaviors can be combined in BeOS operating systems. To paraphrase the bard, such power requires responsibility in its use. If you first consider how a window is to be used, it is not nearly as difficult to get things right.
Styles and Purpose
Look Purpose
---- -------
@ -1003,7 +1019,7 @@ Zip Files
Zipped software is the simplest method for the developer at the cost of more work for the user. If your program has a simple structure, this is generally no big deal -- the user unzips it, sticks it somewhere, and creates a symlink in the Be menu. If, on the other hand, your program has shared libraries that need installed or other files that need to be installed in more than one folder, it is much, much better to use a Software Valet package.
SoftwareValet packages
Software Valet packages
Package files make more work for a developer but much less for the user. As a result, they are the method of choice when a software package requires files be stored in more than one folder on the user's hard drive. They also allow the user to choose different types of installation, such as just an update, minimal installs, or developer installs.
When you make a Software Valet package, there are a few considerations to keep in mind. Installing shortcuts are a pain in the neck unless you have a fixed install location and you make separate packages for Zeta and R5. You should also make sure that all the little details, such as version, build date, and so forth have been set to the proper values. Lastly, test the installation before actually releasing the software to make sure that it actually works the way that it should.
@ -1013,3 +1029,8 @@ Getting Program Updates
While there is no official support from the operating system, a conscientious developer will make a way for the user to easily update your program. Ideally, your program should automatically check for updates, ask the user if he would like to download them, download them in the background, and then install the updates when your program closes. Providing a way to roll back the updates in case of something going seriously wrong is also a very good idea. The only problem with this kind of setup is that it is a *lot* of work.
Because of the popularity of BeOS download sites such as BeBits, it is relatively simple to post updates merely by releasing the new version on such sites. It places the check-download-install responsibility on the user, though. More motivated users will update their software; a great many users will not, so keep this in mind if this is the route you would choose to go.
Appendix A: Good and Bad Error Messages