jxProject Icon jxProject.com

Loading
jxProject Advertisement
. Home Products Advertising News About Contact Legal

Purchase / Buy

Documentation

Future Plans

Links

ScreenShots


jxProject 0

JxProject 2.7.1.2 – Date and Time Line Formatting

User Documentation

June 19, 2012

 

Milliseconds (1/1000th second) is the basis of the time/date utilities of the Java platform and jxProject. Any place in time is measured as the number of milliseconds from the Unix epoch on January 1, 1970, 00:00:00 GMT. All time calculations in jxProject are performed in milliseconds. This is a higher level of detail than most projects require, however the detail is available if you need it. Java has several time/date utilities used to format these millisecond values into calendar formats. This is done when the user specifies a date format pattern to be used for formatting the millisecond values. The date formatting capabilities of jxProject ride very close to the Java platform capabilities. Formatting milliseconds into dates is performed by the class: java.text.SimpleDateFormat. If you want to get more information on date formating perform a Google search on “java SimpleDateFormat” and you will get a lot of good information.

Date Format Dialog:




The Date Format Dialog has two roles; it allows the user to select from a defined set of date formats and to modify or create new date formats. Any time this dialog appears you can select from existing formats or define and select new formats.

Date Format Dialog Table:

  1. Row: The rows are numbered sequentially starting at 1. A row number with an asterisk next to it ( i.e. 7 * ) indicates a user defined date format, or a default date format which has been modified by the user.

  2. Description: A modifiable description of the date format.

  3. Format String: This is specific formatting string for converting milliseconds to calendar date strings. This string must follow the formatting conventions of the Java class: java.text.SimpleDateFormat.

  4. Result: If the Format String is valid, this will contain the current date, formatted with the Format String. If the format string is invalid, this will contain the text “Date Parse Error”. You cannot assign invalid date formats for use in other parts of the application.

Date Format Dialog Buttons:

  1. Up: This will move the currently selected row, up one row.

  2. Down: This will move the currently select row, down one row.

  3. Copy: This will make a copy of the currently selected row and insert it into the table at the currently selected row.

  4. New: This will create a new row, at the currently selected row, or at the bottom of the table if no row is currently selected.

  5. Restore: The application comes with several predefined date formats. This will go through the table of formats searching for those predefined format Strings. If the exact format string is not found, it will be added back into the table. If the the string is found, the entire row will be restored to its default values. Any new data formats added by the user will be unchanged.

  6. Delete: This will delete the currently selected row.

  7. OK: Save all changes and apply the selected date format to the element which opened the dialog if it is valid. Then close the dialog.

  8. Apply: Save all changes and apply the selected date format to the element which opened the dialog if the date format is valid.

  9. Cancel: Cancel any and all changes since the dialog was opened or last “applied”. Do not apply the selected date format to the element which opened it. Close the dialog.

Date Format Dialog Behavior:

There are four places where this dialog is currently used; 1) Tools -> Date Formats ... 2) Gantt Table Start Date column header pop up 3) Gantt Table Finnish Date column header pop up and 4) date pattern selection from the time line format dialog. There are no connections between the elements of the application that use the date formats. You may define and assign a date format, and then delete that format from the dialog without affecting the components which are using that format. This is because the formatting string is assigned to the elements, not a link to a record in the date format table. This makes managing the date formats very flexible. All of the date formats in the date format dialog are stored with the users preferences.

An example: The user wants to change the date format of the Start date in the Gantt table. The user right clicks the header and selects the “Date Format...” menu item. The current start date format string is sent to the dialog before it is shown to the user. If the exact format string is found, that row is selected. If the format string is not found, it is added to the table and selected with a description that says “unknown”.

Note: The text and descriptions below regarding Date and Time Patters are directly from Oracle documentation on the class java.text.SimpleDateFormat. There is more complete information and examples if you read Sun's JavaDoc on SimpleDateFormat which you can locate on the Internet by searching on “java SimpleDateFormat”.

Date and Time Patterns:

Date and time formats are specified by date and time pattern strings. Within date and time pattern strings, unquoted letters from 'A' to 'Z' and from 'a' to 'z' are interpreted as pattern letters representing the components of a date or time string. Text can be quoted using single quotes (') to avoid interpretation. "''" represents a single quote. All other characters are not interpreted; they're simply copied into the output string during formatting or matched against the input string during parsing.

The following pattern letters are defined (all other characters from 'A' to 'Z' and from 'a' to 'z' are reserved):

Letter

Date or Time Component

Presentation

Examples

G

Era designator

Text

AD

y

Year

Year

1996; 96

M

Month in year

Month

July; Jul; 07

w

Week in year

Number

27

W

Week in month

Number

2

D

Day in year

Number

189

d

Day in month

Number

10

F

Day of week in month

Number

2

E

Day in week

Text

Tuesday; Tue

a

Am/pm marker

Text

PM

H

Hour in day (0-23)

Number

0

k

Hour in day (1-24)

Number

24

K

Hour in am/pm (0-11)

Number

0

h

Hour in am/pm (1-12)

Number

12

m

Minute in hour

Number

30

s

Second in minute

Number

55

S

Millisecond

Number

978

z

Time zone

General time zone

Pacific Standard Time; PST; GMT-08:00

Z

Time zone

RFC 822 time zone

-0800

Pattern letters are usually repeated, as their number determines the exact presentation:



TimeLine Format Dialog:




The “TimeLine” Format Dialog is used to format the headers for the Gantt and Schedule charts. It allows custom date formats, date alignment, alternating intervals to be defined for both top and bottom scales. This dialog is accessed from the chart headers by right clicking on the header and selecting “TimeLine Format...” from the pop up menu.

You can stretch and compress the time line by holding down the shift key and press/hold the right mouse button, and drag to the left or right. As the scale of the time line is changed in this way, the time line formats are automatically selected and implemented to format the time line. If you have the dialog open while you are stretching the time line, you will see the format being used getting selected.

TimeLine Format Dialog Table:

  1. Row #: The rows are numbered sequentially starting at 1. A row number with an asterisk next to it ( i.e. 7 * ) indicates a user defined format, or a default format which has been modified by the user.

  2. Enabled: If enabled, it is can be used for formatting the header, if not enabled, it will be not be used.

  3. Pixels per day: This is the scaling factor over which this format will be used. Typical computer screens display about 100 pixels/inch or 40 pixels/cm. If the header is set to a scale of 115 pixels/day it means the 24 hour representation of the day will typically occupy 115 pixels on your computer screen which would translate to a visual width of 1.15 inches/45 cm. This is the “key” field/value for determining which format to use for the time line.

  4. Top Units: For the top scale, this is a pull down menu ranging from seconds to years. If this is set to “days” then 1 interval is one day.

  5. Top Interval: For the top scale, this determines the number of intervals per display. For example, if the units are months years, and the interval is 3, then every 3rd month is shown on the time line, which is basically quarters.

  6. Top Date Format: For each displayed interval, this date pattern is used to format the date. You can edit the format string directly in the cell, or select the “...” button and the date format dialog will be shown and you can select/define a date format in that dialog. If the date format string is invalid, the text on the header will display “Date Parse Error” at every displayed interval. An empty value is valid and results in not text being written to the display interval.

  7. Top Date Alignment: This is a pull down menu with values left/right/center. The text string of the date will align within its interval according to this value. Note: The millisecond time used for producing the date string is taken from the left most position of the interval regardless of the text alignment value.

  8. Top Tick Lines: This is a boolean (true/false) to display vertical lines between each displayed interval.

  9. Scale Divisor: This is a boolean (true/false) to display a horizontal line between the top and bottom scales.

  10. Bottom Units: For the bottom scale, this is a pull down menu ranging from seconds to years. If this is set to “days” then 1 interval is one day.

  11. Bottom Interval: For the bottom scale, this determines the number of intervals per display. For example, if the units are months years, and the interval is 3, then every 3rd month is shown on the time line, which is basically quarters.

  12. Bottom Date Format: For each displayed interval, this date pattern is used to format the date. You can edit the format string directly in the cell, or select the “...” button and the date format dialog will be shown and you can select/define a date format in that dialog. If the date format string is invalid, the text on the header will display “Date Parse Error” at every displayed interval. An empty value is valid and results in not text being written to the display interval.

  13. Bottom Date Alignment: This is a pull down menu with values left/right/center. The text string of the date will align within its interval according to this value. Note: The millisecond time used for producing the date string is taken from the left most position of the interval regardless of the text alignment value.

  14. Bottom Tick Lines: This is a boolean (true/false) to display vertical lines between each displayed interval.



TimeLine Format Dialog Buttons:

  1. Up: This will move the currently selected row, up one row.

  2. Down: This will move the currently select row, down one row.

  3. Copy: This will make a copy of the currently selected row and insert it into the table at the currently selected row.

  4. New: This will create a new row, at the currently selected row, or at the bottom of the table if no row is currently selected.

  5. Restore: The application comes with several predefined formats. This will go through the table of formats searching on the “Pixels per day” field for those predefined formats. If the value is found, it will be have all of its values set back to their original values. If the the string is found, the entire row will be inserted. Any new data formats added by the user will be unchanged.

  6. Delete: This will delete the currently selected row.

  7. OK: Save all changes and apply the selected “Pixels per day” format to the time line which opened the dialog. Then close the dialog.

  8. Apply: Save all changes and apply the selected “Pixels per day” scale and format to the timeline which opened the dialog.

  9. Cancel: Cancel any and all changes since the dialog was opened or last “applied”. Close the dialog.

Date Format Dialog Behavior:

When the dialog is opened, the currently active format for the header will be selected. If you stretch/compress the time line while the dialog is open, the selected format will change. The format which is used by the time line is that which has a “Pixels per day” value which is closest but less than or equal to the headers current “Pixels per day” scale. The defined time line formats are active for both Gantt and Schedule headers, you cannot define a different set of formats for each header. By default, the formats are sorted by “Pixels per day”. It is not necessary that they be sorted, but it is probably easier for the user to maintain if they are.

If there are formats which you do not like, you can delete them, but the recommendation is to disable them so they can be easily restored if you want them back.

Although most time line formats have the top scale as the major scale, you can have the major scale on the bottom with the minor scale on top. The header will always try to align the top and bottom scales, for example year/months will align, but months/weeks won't align, weeks do not necessarily start or end on month boundaries.








Copyright ©2002-2012 jxProject Company