windowsforms-2949-controls-and-libraries-scheduler-getting-started.md
In Visual Studio, create a new WinForms project and drag the SchedulerControl from the Toolbox onto the form. Set the Scheduler’s Dock property to Fill.
Use the Scheduler’s smart tag menu to access its main settings. For example, click the “Create Ribbon” link under the Command UI category, then select “Create All Bars”. This generates a Ribbon UI with relevant commands.
End-user capabilities include:
Close the application and specify the following properties:
When you add a Scheduler Control to a form, it automatically adds the associated SchedulerDataStorage component - an external storage that keeps all Scheduler data: appointments, resources, labels, etc. The storage is associated with the Scheduler control via the SchedulerControl.DataStorage property. You can manually add more storage to the form and use the control’s smart tag to select the currently active one.
You can bind the storage to a data source that stores appointments. This example requires the “CarsDB.mdb” MS Access database located in the demo source code folder (SchedulerDemos\Data).
Invoke the Scheduler’s smart tag menu, open the “Appointments Data Source” combo box, and click the “Add Project Data Source…” link.
In the Data Source Configuration Wizard, select “Database” and then “Dataset”. Click “New Connection…” to proceed to connection settings.
Change the database type to “Microsoft Access Database File (OLE DB)” and search for the sample “CarsDB.mdb” file. Click “OK” to add a new connection.
Select the “Cars Scheduling” table and click “Finish”.
Each appointment has data associated with it: start and end time stamps, descriptions, labels, etc. To display appointments, the Scheduler needs to know which appointment properties relate to which data source fields. The process of binding appointment properties to source fields is called mapping. This operation is performed in the “Setup Appointment Storage” dialog that pops up automatically after binding the storage to a data source. Should you need to modify these mappings later on, invoke a control or a storage smart tag and click “Mappings Wizard…”
You can set up all required mappings manually, or use the Wizard. Click the “Generate” button to scan data source fields and automatically assign them to the corresponding properties.
The final Wizard page shows all data source fields that remain unmapped, and allows you to bind them to custom fields. You can skip this step for now and click “Finish”.
Visual Studio adds two standard WinForms components when you bind to the MS Access database - DataSet and TableAdapter. Invoke the adapter’s smart tag menu, choose “Preview Data…” and then click the “Preview” button. Inspect the loaded database records: all sample appointments belong to the last three months of 2016.
Run the application to test the result.
To customize appointment backgrounds (Labels) and side strips (Statuses), load custom labels and statuses from external sources bound to the SchedulerDataStorage.Labels and SchedulerDataStorage.Statuses properties.
In real-life applications, appointments often have related resources. A resource is an entity that owns appointments. For instance, the sample CardsDB database belongs to a fictional car rental agency. In this case, any car owned by this agency is a resource that has related appointments (time intervals during which these cars are leased, washed or repaired). In this section, you will learn how to add these resources to the Scheduler.
Open the “Resources Data Source” editor in the Scheduler’s smart tag and repeat the same steps performed for appointments. Use the project’s existing connection, but this time select the ”Cars” table.
When the Mapping Wizard pops up, use the following mappings:
Now when you have resources, restore appointment “ResourceID” property mapping removed earlier. Assign the “CarID” data field to this property.
Run the application and add a new appointment or modify an existing one: the appointment edit form now allows you to choose a parent resource.
Set the SchedulerControl.GroupType property to Resources to display resources on main Scheduler screen and organize appointments under their parent resources. The number of simultaneously visible resources is managed for each View individually via the SchedulerViewBase.ResourcesPerPage property.
You can slightly modify the Edit Appointment form (for example, rename the “Resource” label to “Car” in this example) or completely re-design this form and make it display custom field values, not shown by default. In this section, the editor for the custom “Contacts” field is added.
Click the SchedulerControl’s smart tag to invoke the SchedulerControl Tasks menu and click the Create Custom Appointment Form item.
Open the CustomAppointmentForm in design mode. Drag the LabelControl control and the MemoExEdit control from the DX.25.2: Common Controls Toolbox tab to the form.
To add the capability to obtain a custom field value or set a custom appointment field, modify the LoadFormData(), SaveFormData() and IsAppointmentChanged() methods in the CustomAppointmentForm code file.
Handle the EditAppointmentFormShowing event to pass your custom form to the Scheduler Control.
Run the application to see the result.
In some instances a data source does not contain a field that matches the required appointment\resource property. For example, the sample database stores three categories of cars - sports, truck, and saloon. You cannot map this “Category” field to the resource’s “Color” property so that all resources that belong to the same category have the same color. This is not possible because the data source field stores strings, and the resource property accepts colors (in various formats, ResourceDataStorage.ColorSaving). Use Mapping Converters to modify data source values.
Declare a custom converter class that implements the ISchedulerMappingConverter interface, implement the conversion logic, create a new converter instance and assign it to the required <Mapping_Property_Name>Converter property. The following code converts category names to colors and implements the scenario described above: trucks are LightSeaGreen, sport cars are LightCoral and saloons are LightGoldenrodYellow.
schedulerControl2.DataStorage.Resources.Mappings.ColorConverter = new ColorMappingConverter();
schedulerControl2.DataStorage.Resources.ColorSaving = ColorSavingType.Color;
schedulerControl2.DataStorage.Resources.Mappings.ColorConversionBehavior = MappingConversionBehavior.InPlaceOfMapping;
schedulerControl2.DataStorage.Resources.Mappings.Color = "Category";
class ColorMappingConverter : ISchedulerMappingConverter {
object ISchedulerMappingConverter.Convert(object obj, Type targetType, object parameter) {
string category = obj as string;
Color resColor = Color.White;
switch (category) {
case ("SALOON"):
resColor = Color.LightGoldenrodYellow;
break;
case ("SPORTS"):
resColor = Color.LightCoral;
break;
case ("TRUCK"):
resColor = Color.LightSeaGreen;
break;
}
return resColor;
}
object ISchedulerMappingConverter.ConvertBack(object obj, Type targetType, object parameter) {
string resColorName = obj as string;
string category = "NO CATEGORY";
switch (resColorName) {
case ("LightGoldenrodYellow"):
category = "SALOON";
break;
case ("LightCoral"):
category = "SPORTS";
break;
case ("LightSeaGreen"):
category = "TRUCK";
break;
}
return category;
}
}
schedulerControl2.DataStorage.Resources.Mappings.ColorConverter = New ColorMappingConverter()
schedulerControl2.DataStorage.Resources.ColorSaving = ColorSavingType.Color
schedulerControl2.DataStorage.Resources.Mappings.ColorConversionBehavior = MappingConversionBehavior.InPlaceOfMapping
schedulerControl2.DataStorage.Resources.Mappings.Color = "Category"
class ColorMappingConverter : ISchedulerMappingConverter
Object ISchedulerMappingConverter.Convert(Object obj, Type targetType, Object parameter)
Dim category As String = TryCast(obj, String)
Dim resColor As Color = Color.White
Select Case category
Case ("SALOON")
resColor = Color.LightGoldenrodYellow
Case ("SPORTS")
resColor = Color.LightCoral
Case ("TRUCK")
resColor = Color.LightSeaGreen
End Select
Return resColor
Object ISchedulerMappingConverter.ConvertBack(Object obj, Type targetType, Object parameter)
Dim resColorName As String = TryCast(obj, String)
Dim category As String = "NO CATEGORY"
Select Case resColorName
Case ("LightGoldenrodYellow")
category = "SALOON"
Case ("LightCoral")
category = "SPORTS"
Case ("LightSeaGreen")
category = "TRUCK"
End Select
Return category