I18NFontsizeResizeGuidelines

Revision as of 12:08, 5 November 2009 by Admin (Talk | contribs)


Fontsize and resize guidelines for developers and those testing these areas


Information provided by Ken Frank, Tools I18N Quality and Testing

Contact kfrank@netbeans.org for more information or with comments or questions about these pages.




Main guideline for i18n is: The UI objects and information, labels, messages, etc shown in a given window or dialog should show completely to user in most cases (see below) AND User should not need to resize the window to see this information.

In general, when a window or dialog appears, user should not need to resize it or any part of it to see all parts of all labels and messages in it, with some exceptions discussed below. And that the fontsize should be that specified by user, not the default font size (unless user did not specify a size)



Resizing issues are not just I18N ones but also general and perhaps A11Y related.

              	 Because a user or localization can choose a larger fontsize, and because some translations of English are a lot longer in other languages, and if a given ui object has been hardcoded as to its size,  , user might not see all of that text, or may not see an entire area of text at all since this would be the effects of the harcoding of the sizes, which is often done assuming the default font size and English labels or messages.
         o Thus, window layouts and construction should use appropriate Java API and layout managers to have windows dynamically resize by themselves, with no needed user actions, based on size of actual text of labels or messages and/or fontsize of the ui elements in a given window.


Note that there are exceptions as to when and if a given ui object should need to resize itself and some of those are discussed below.



Guidelines and Requirements

   * make sure that all windows dynamically resize as needed for those who use fontsize option or for case of longer strings due to translated messages being longer in some locales.  This includes items in dropdown lists.
   * don't hardcode font names that are not jdk font names If a font name is used, it should be one that is named in the jdk font properties files as a standard java font; since in this case it can be mapped to a "real system font" when multibyte is used. That is, do NOT use a OS font not so named; it can cause serious issues of fonts not being found when user runs product.
   * don't hardcode font sizes, but use global font size as baseline. Since localized chinese release on unix still needs 14 point font for visiblity issues, its best not to reduce global font size for some item due to this situation.



   * 

Use Layout Managers

You can use a layout manager to control the size and location of the components in your application.

 For more

information on layout managers and fontsize/resize, see:

[see The Java Tutorial for more information| http://java.sun.com/docs/books/tutorial]

Using swing layout managers can help avoid resize problems http://java.sun.com/docs/books/tutorial/uiswing/layout/index.html


http://java.sun.com/developer/technicalArticles/GUI/AWTLayoutMgr/



Some other suggestions to avoid resize problems have been:

         o  use the NetBeans Form Editor and GridBag for the main panel if that applies. There may be situations where the Grid or Flow layout would be used.
         o Here are some other specific guidelines:
               +  don't set preferred size to any component except scroll panes in  certain situations
               +  use setColumns for text fields to set the preferred width taking into  account font size
               +  set preferred size to scroll panes so that the size of scroll pane  works okay with default font size
         o If parts of 2 UI areas overlap each other, it is often a resizing issue.


Checking your modules source code for possible fontsize and resize issues.

Some api calls are setFont, setPreferredSize. setMaximumSize that are used in code to set font sizes. Its where these calls might set a hardcoded value that are possible indications of fontsize or resize problems.

   * you need to know the api names of the calls that set font names or sizes; its not always just setFont, since sometimes teams or nb api  has wrapper or other api that calls the basic java apis.

Run the product with the --fontsize option set to 20, to make sure the components you are working with do resize properly. But running even at this large a font may not catch all these situations, so a code review is also advised.



Fontsize/resize testing and more information on fontsize/resize

In general, when a window or dialog appears, user should not need to resize it or any part of it to see all parts of all labels and messages in it, with some exceptions discussed below. And that the fontsize should be that specified by user, not the default font size (unless user did not specify a size)

However, the main menu items or the overall view of the various sub windows of the main NetBeans ide window are not subject to this requirement since its expected user would need to resize the sub windows (like editor, explorer, properties, etc) themselves. This is discussed more below.

This testing is meant to verify the requirements in this document

How to install, prepare and test

        1. get the build to test.
        2. install it as usual.
        3. run ide with new user directory each time !!
        4. start ide with this argument - <startcmd> --fontsize <size>


for example, netbeans --fontsize 18

   * Run at least using fontsize 16, or 18, which is still a reasonable size, but don't use sizes bigger than 22.


Test the UI for:

   *
         o See section below for more info on what is a fontsize/resize issue.
         o make sure all parts of a window or dialog shows completely without needing to resize it,  EXCEPT for the known kinds of windows or parts of windows where user might need to resize (see below)
         o make sure no parts of window overlap other part
         o resize a window to make sure that no part of it was hidden completely (or partially)
         o if some part of a window shows at a smaller font than the rest of it, and we assume the rest of it is showing at the font size indicated by startup command,  then it is usually ok since intended by developer, but if this smaller font size is less than 14 point, it is a problem since Chinese fonts do not display well on some OS smaller than 14 point, so an issue could be filed.


What are areas to look at in fontsize/resize testing ?

   * In general, the rule is, when a window appears, user should not need to resize it or any part of it to see all labels and text.

But there are exceptions that are not resize problems; see this section below - sometimes there might be a problem in one case of items below but not in another - please read this section carefully.

   * If you see a window come up that has one part overlap another part, that is usually a serious issue.


   * If you see a window come up that has not all of a certain message or label showing, that may or may not be an issue - see later section below.


   * If, when you resize a window larger, some message or textfield appears that was not visible at all when window first came up, that is usually a serious issue, since it means user can miss entire information or area that might need input.


  	 (It is highly recommended to always resize a window larger once you have checked it for basic resize issues since there might be parts not shown that we are not aware of.)


   *   If, when you resize a window smaller than what it was when it appeared, and not all of the messages or labels shows, I don't think that is an issue, since it could be expected that it might not show all msgs and labels ok then.  This document is not about testing of making a window smaller.


   *   If, in a given window, a part of window shows at a fontsize smaller or larger than usual font, that might be ok or might be an issue.
        	 o   Some UI areas did not follow global font size and they should have.
        	 o   Some UI areas want to have smaller or larger fontsize in part of a window, and this might be ok. You can do source code checking that hopefully can catch most of these issues. The rule is - its ok to use smaller or larger font size, but use an offset from global font size to get it, don't hard code it.
       	  o And also, since quality of some Asian fonts are not as good at smaller fontsizes than 12, a window should not show fonts with size less than 12 in any case.


   *  OS font names should never be used in assigning a font type/style - this can only be found by source code checking

SEE last section below for more on checking font name and size from source code.

* three dots in labels

If you see a label or message with three dots after it, it means not all text is being shown, so it can be an issue. If when you resize the window horizontally and more text appears, thats an issue)

this does not apply to a button with three dots unless not all the text of that button does not show. Buttons with 3 dots mean that pressing the button brings up another window.

BUT there could be a case where even the label of the button with 3 dots does not show fully.

   *   table row text height


If an area like a table row does not show the text at full height, it can be an issue. I think this might be a known swing or jtable nb issue, but its still an issue to be noted.

This could apply to a textfield height also.

   *   textfield width

Normally a textfield itself is not a problem as to resize since user can use arrow keys or mouse to navigate within it.

However, If a textfield is shown with a very small size on using larger size font, for example, if user can only input 1 or 2 characters in it, when normally it is shown wider, it could be an issue. In this case we suggest discussing with the developers.

I don't know if there is a guideline related to how many characters should be able to be seen in a textfield by default or if there are guidelines for that from xdesign.

   *   If a window shows on screen at its maximum width, so that it can't be resized anymore, but some part of a message or label still does not show, then it could be an issue as it seems that a UI label could wrap to next line, or scrollbars could appear.   That is, its expected that once a window is at a maximum width on a given screen, it cannot show anymore and will not wrap its text by default.

Solving this would be a design decision by team implementing the given window or dialog if they wanted to wrap the message in question.

* Properties windows left and right sides

information in properties windows anywhere in the product, including options window right side - user might need to resize the key or value sections of any given property to see all of it - and since there are ui controls provided, this is not considered a resize issue situation.

A property window is one with the 2 sections, a key and a value, and these labels often separated by a vertical resizing control between them. Also, sometimes clicking on the value, where there are 3 dots, brings up a property editor, or sometimes it allows editing in text field or sometimes there is a popdown menu with choices.

If there is a choice in the value part of a property window that involves a dropdown menu, each iteam of the menu does need to show fully. There is a programattic way to have this done, so its a valid issue.


* drop down menus of property or other windows - these are the dropdown windows referred to in previous section.

information in drop down menus, sometimes part of property windows and sometimes in other parts of other windows - not all of the text of the choices might show completely and this is a valid issue if they don't. It can be fixed by certain programming steps.


* Table headers text

Certain windows that use the JTable and TreeTable for showing information in columns may need resizing of the column areas and its not a resize issue if they do.

There are many windows of this type in the ide; for example, the properties windows discussed above and many other windows that typically have columns of data to be shown. For these windows, in the column headers, there is a veritical bar between each column header that user can use to make it larger or smaller.

For these kind of windows, it is expected that the user would need to resize columns to see actual data, but the goal is to show the column labels themselves fully. Thus its not a resize issue if the data in some column does not show completely since the columns can be resized by using the controls.



What is not an issue, that is, where would user be expected to resize or see fontsize at a different size ? (as opposed to section above where sometimes a situation was a resize problem and sometimes not)

General situations that are not a bug

         * If there is a part of window where fontsize is smaller than the font size you are using, that might be ok - see discussion above.
         * In javadoc help right side and in template descriptors that are part of the file-> new window - its ok if the fontsize is smaller since the html code does not follow the global font size (in other words, most html is not controlled by ide default fontsize or fontsize argument)


         * info controlled by horizontal or vertical scrollbars in any part of a window - user expected to use scrollbars to see all text; window doesnt need to resize to show all that text.
         * information in a text field if you can use arrow keys or mouse to scroll thru it - user expected to use arrow keys or mouse to see all text (if cant do that, its a bug) See discussion in section above.


         * window headers provided by the window manager of the OS do not need to show at same font size as ide font but if they are provided by ide, they do (33212)

Likewise, window headers provided by window manager do not need to show all information without resizing, but ones provided by ide do.

But its suggested that the amount of information provided in a window header be limited, since sometimes file names and other information appear in it, which might cause user to need to resize it even though actual UI elements in that window do not require window to be resized.

         o information in rows of tables or properties as discussed in properties window left and right sides and table headers text in above section


         o   three dots

If you see a button with three dots on it, but the button shows all its text, that is not an issue since it means pressing it will bring up another window.

If the button does not show all its text, it is an issue.

Compare this to previous section above, about 3 dots in labels.



Checking your modules source code for possible fontsize and resize issues.

Some api calls are setFont, setPreferredSize. setMaximumSize that are used in code to set font sizes. Its where these calls might set a hardcoded value that are possible indications of fontsize or resize problems.

   *  do not report every case of these calls, just where they seem to hardcode a specific numerical size.
   * you need to know the api names of the calls that set font names or sizes; its not always just setFont, since sometimes teams or nb api  has wrapper or other api that calls the basic java apis.
   * for font names, make sure the font name is a standard jdk font name, NOT name of some OS font, even if that font is standard with the OS. If it is not a standard jdk font name, then it can be reported as an issue.
Not logged in. Log in, Register

By use of this website, you agree to the NetBeans Policies and Terms of Use. © 2012, Oracle Corporation and/or its affiliates. Sponsored by Oracle logo