Farsi Library - Working with Dates, Calendars, and DatePickers

• Download DLLs - 122.5 KB
• Download source code - 252.8 KB
• Download demo - 127.7 KB
• Download documentation - 213.1 KB

Introduction

The Persian Calendar is used in most countries where Persian is spoken, although some regions use different month names. The Persian calendar is the official calendar of Iran and Afghanistan, and is one of the alternative calendars in regions such as Kazakhstan and Tajikistan. The Persian calendar is based on a solar year and is approximately 365 days long. A year cycles through four seasons, and a new year begins when the sun appears to cross the equator from the southern hemisphere to the northern hemisphere as viewed from the center of the Earth. The new year marks the first day of the month of Farvardin, which is the first day of spring in the northern hemisphere.

Each of the first six months in the Persian calendar has 31 days, each of the next five months has 30 days, and the last month has 29 days in a common year and 30 days in a leap year. A leap year is a year that, when divided by 33, has a remainder of 1, 5, 9, 13, 17, 22, 26, or 30. For example, the year 1370 is a leap year because dividing it by 33 yields a remainder of 17. There are approximately 8 leap years in every 33-year cycle.

Since .NET Framework 1.0 and 1.1 does not provide any Persian Calendar, and Persian Calendar on .NET 2.0 has a bug and is useless, here, I'm going to show how to write the required DataType, and GUI controls to work with this DataType.

Persian Calendar Class

It seems that Microsoft forgot to provide a "Persian Calendar" on .NET 1.1, and while they do provide a class for this special kind of calendar in their second version of the Framework, they have somehow mis-calculated. We're going to write a Persian Calendar, plus a DataType to be replaced with the standard DateTime class, while maintaining the same structure. As it is required to convert standard DateTime to PersianDate, I'll be providing a converter class too. Since the use of these classes could be maximized when combined with GUI controls, I'll be providing a MonthView and a DatePicker control too.

Design-Time Integration

I've changed the design-time integration a little bit. Since some developers like to use PersianDate and others use DateTime classes to work with these libraries, I've exposed both of these properties as SelectedDate and SelectedDateTime. As for SelectedDate which has PersianDate type, there's a TypeConverter to do the conversion of Text to PersianDate instances at design time.

Theme Support

I'm using .NET 2.0 VisualStyleRenderer, which is a managed wrapper for XP styles. In addition, there are some classes to simulate Office 2003 rendering. There's also an Office 2000 style available. If theming is disabled or not supported by the OS, controls render using Office 2000 style.

Popup and Shadows

Popup controls should have shadows. On RTL controls, shadows should be at the left-bottom of the control. All the strings used in the controls are using a localizer manager class to get the strings based on StringID enumeration.To use the localized version you should change current thread's Culture and CultureUI properties to one of the defined cultures : (AR-SA for Arabic Culture, FA-IR for Persian Culture, and InvariantCulture for English or neutral culture. Here's how to do this in the application's Main() method:

//
// The main entry point for the application.
//
[STAThread]
static void Main()
{
    Thread.CurrentThread.CurrentUICulture =
            new System.Globalization.CultureInfo("fa-IR");
    Application.EnableVisualStyles();
    Application.SetCompatibleTextRenderingDefault(false);
    Application.Run(new Form1());
}

Here's the correct behavior of a popup control with standard strings and localized version for the FA-IR culture.

Using Arabic and Neutral Cultures

I primarily used AR-AE culture for Arabic, but in version 1.3.1.0, I had to change this to AR-SA. This is because of a problem (bug?) with the Hijri Calendar not being the default calendar of AR-AE culture, while it IS the default culture for AR-SA culture. Now the control is drawn in the correct way when you set the culture to Arabic.

Rendering in neutral culture is now done in Left-To-Right order. Generally the control decides to render in RTL or LTR based on the reading order of the current culture.

Using the Code

You can use the PersianDate class in much the same way as you use the DateTime class. Here are some examples:

//
// Use of Persian date class
//
PersianDate pd1 = PersianDate.Now.ToString(); // prints 1385/01/13
// constructs a new instance with the specified vales
PersianDate pd2 = new PersianDate(1386, 4, 26); 

// You can use operator overloading, too!
if(pd1 >= pd2)
   MessageBox.Show("Date is greater or equal");

// Use of normal DateTime and Conversion
PersianDate pd3 = PersianDateConverter.ToPersianDate(DateTime.Now);
DateTime dt1 = PersianDateConverter.ToGregorianDate(PersianDate.Now);

Points of Interest

Please send any suggestions/comments/feedbacks to my email address or use the Forum at the bottom of the page. For further releases or other libraries, visit my website.

.NET 1.1 and VisualStudio .NET 2003 Support

This library is tested on VS.NET 2005 and .NET Framework version 2.0. So, it won't run on VS.NET 2003. If you REALLY need to get this going, you'll have to port this to VS.NET 2003 and you'll have to change the drawing part of the code, since it actually uses managed classes of .NET 2.0 to draw in WindowsXP style. You'll have to use a wrapper on Theme API (there is already a project in CodeProject) to do the job for you. To make the porting easier, you can also cut out all the drawings in WindowsXP and Office 2003 style, and stick to the good-old Office2000 theme which uses GDI+ classes to draw.

WPF Version

The WPF version is out. You can have a look at the Vista (Windows Presentation Foundation) section of The Code Project website. Your feedbacks and comments are greatly appreciated.

History

Version 1.9.0.0

• Fixed: Bugs regarding wrong mapping of Persian/Arabic weekdays and Gregorian weekdays, which resulted in wrong display of weekday in Gregorian calendar.
• Added: Better handling of multi-selection mode. You can add/remove the SelectedDateRange property and changes will be reflected on the UI.
• Added: PersianDayOfWeek enum with correct days order.
• Added: DayOfWeek property to PersianDate class, to return the correct day of the week.

Version 1.6.0.0

• Fixed: Some bugs posted through feedback.
• Added: MessageBox control with RTL and LTR views, and ability to remember the selected value, with both standard and custom MessageBox buttons.
• Added: Custom formatting of the PersianDate.ToString() method, (like the DateTime control), which gives the functionality to return formatted strings, e.g. Long Date, Long Time, DateTime, etc.
• Added: Custom draw of each preferred day. Could be used to draw some days in disabled format, along with the SelectedDateTimeChanging event.

Version 1.5.0.0

• Fixed: Exceptions of the FAMonthView control when selecting a date prior to MinValue and greater than MaxValue.
• Fixed: Broadened the range of PersianDate MinValue and MaxValue classes.
• Fixed: Invariant Culture's MonthNames is a zero-based index. First month's name is now okay in Invariant Culture.
• Fixed: Checking of Year, Month, Day,... values on setting the property of the PersianDate.
• Fixed: Checking of null values on != and == operators of PersianDate.
• Fixed: Removed duplicate DateTime and PersianDate properties and events of the GUI controls. You can convert DateTime instances directly to PersianDate.
• Fixed: Validation process of DatePicker.
• Added: Complete two-way binding to any data source.
• Added: Ability to use other cultures and calendars with the controls.
• Added: Implicit conversion of DateTime and PersianDate.
• Added: Added Millisecond property to PersianDate class for better precision.
• Added: PersianDate class is now serializable and implements the following interfaces: ICloneable , IComparable , IComparable<T>, IComparer , IComparer<T>, IEquatable<T>.
• Added: Ability to select scrolling feature of FAMonthView. You can scroll through days, months, or years.
• Added: FAThemeManager class that handles selected themes of all controls. To change the theme globally, you just need to set this class' Theme property.
• Added: FALocalizeManager class that handles other cultures. You can now localize strings into any culture.
• Added: ToolStrip support. Now you can integrate controls in ToolStrip, MenuStrip, etc.
• Added: Microsoft DataGridView custom column and editor support.

Version 1.4.0.0

• Added: Complete test and demo of the functionalities provided with the library, with source code.
• Added: Documentation
• Added: Diagram for PopupForms, Controls hierarchy and Painter classes.
• Implemented correct Office 2003 look and feel on ComboBox controls.
• Implemented correct RTL and LTR views of FADatePickerConverter.
• Bug Fix: FADa<code>tePicker control now displays the popup calendar according to its theme.
• Bug Fix: Correct direction of popup controls in RTL and LTR mode.
• Bug Fix: Correct Shadow location of popup controls in RTL and LTR mode.
• Bug Fix: FADatePicker control not showing text property correctly.
• Changes: Relocation of namespaces.
• Known Issues : localization of strings in Arabic language. (anyone could give me a hand there?)

Version 1.3.1.0

• Implementing Windows 2000 drawing on non-Windows XP computers or when the visual styles are disabled.
• Better drawing of Windows XP and Office 2003 styles.
• Drawing the control based on user's culture. Currently these cultures are allowed: Neutral (Gregorial Calendar), AR-SA (Hijri Calendar) and FA-IR (Persian Calendar).
• Better localization. You can use Localizer class to update strings.
• Support for Gregorian Calendar (Neutral Culture) and Hijri Calendar.
• Rendering Left-To-Right for Cultures that are not Right-To-Left specific (e.g. Neutral Culture, English Culture, etc.)
• New DatePickerConverter control which converts selected date by pressing a button.

Version 1

• Providing base classes, and GUI controls to work with "Persian Dates". Some of the features (e.g. Office 2000 drawing) are not yet implemented.