EhLib.WinForms 2.0 Build 2.0.005 Beta
=====================================

EhLib.WinForms is a library of visual components for Windows Forms in Microsoft
Visual Studio, for .NET Framework 4.8 and .NET 8. It provides advanced data
grids, a pivot grid, a planner and edit controls with capabilities beyond the
standard Windows Forms controls.

Quick start
-----------

1.  Add the library to your project from the local NuGet package in the
    NuGetPackages folder (see Installation).
2.  Open the demo solution .\Demos\EhLibDemos.slnx in Visual Studio, then build
    and run the MainDemo project to see the library controls at work. Nothing
    has to be installed or configured for this: the demo projects automatically
    reference the NuGet package from the NuGetPackages folder.
3.  Read about the new features of this version in
    EhLib.WinForms 2.0 Release Notes Eng.html.
4.  Read the full documentation of the library in Doc\EhLib-WinForms-Help.chm
    and Doc\Eng\EhLib.WinForms - Developers guide.doc.

Contents
--------

- Requirements
- Supported platforms
- Installation
- Getting started
- Components
- Documentation
- Editions and licensing
- Support and contacts

Requirements
------------

  IDE                       Versions
  ------------------------- ----------------
  Microsoft Visual Studio   2022 and later

- The library has no dependencies on other packages.
- The library projects of the EhLib.WinForms with source code edition must be
  built with Visual Studio (or its MSBuild); dotnet build cannot compile the
  .NET Framework 4.8 resources of the library.

Supported platforms
-------------------

  Target framework     TFM              Windows Forms designer in Visual Studio
  -------------------- ---------------- -----------------------------------------
  .NET Framework 4.8   net48            Classic in-process designer
  .NET 8               net8.0-windows   Out-of-process designer

The library works on Windows only, as Windows Forms itself.

Installation
------------

There is no installer: the library is added to each project as a NuGet package
or, in the edition with source code, as projects of your solution.

Using the NuGet package

The easiest way for every edition is the local NuGet package
EhLib.WinForms.<Edition>.<Version>.nupkg from the NuGetPackages folder. It is
also the only way to get the design-time support for .NET 8 projects (see
Design-time support).

- Copy the files from the NuGetPackages folder to the folder where you keep your
  local NuGet packages. Visual Studio usually stores local packages in
  C:\Program Files (x86)\Microsoft SDKs\NuGetPackages; if that folder does not
  exist, use any folder, for example C:\MyNuGetPackages.
- In Visual Studio, open Tools -> NuGet Package Manager -> Manage NuGet Packages
  for Solution...
- In the Package source list, select Microsoft Visual Studio Offline Packages.
  If that source is not listed, add it in Tools -> Options -> NuGet Package
  Manager -> Package Sources and point it at your package folder.
- On the Browse tab, type EhLib in the search box and select the
  EhLib.WinForms.<Edition> package.
- Select the project(s) you want to install it into and click Install.

Adding the library projects to your solution

In the EhLib.WinForms with source code edition you can add the projects from the
Src folder to your solution instead of the package:

  ------------------------------------------------------------------------------------------------
  Project                                                  Purpose
  -------------------------------------------------------- ---------------------------------------
  Src\EhLib.WinForms\EhLib.WinForms.csproj                 The library.

  Src\EhLib.WinForms.Design\EhLib.WinForms.Design.csproj   Design-time support for .NET Framework
                                                           4.8.
  ------------------------------------------------------------------------------------------------

Then add project references to them in your Windows Forms project. Reference
EhLib.WinForms.Design only for the net48 target framework: it is not needed at
run time, and the .NET 8 designer does not take it from a project reference.

    <ItemGroup>
      <ProjectReference Include="..\Src\EhLib.WinForms\EhLib.WinForms.csproj" />
    </ItemGroup>
    <ItemGroup Condition="'$(TargetFramework)' == 'net48'">
      <ProjectReference Include="..\Src\EhLib.WinForms.Design\EhLib.WinForms.Design.csproj" />
    </ItemGroup>

To change the library source and keep the full .NET 8 design-time support, build
your own package from the compiled assemblies with the same layout as the
supplied package.

Evaluating with the Trial package from nuget.org

If you do not have a license but want to evaluate the library, install the Trial
version from nuget.org:

- In Visual Studio, create a new Windows Forms App project.
- Open Tools -> NuGet Package Manager -> Manage NuGet Packages for Solution...
  and select the nuget.org package source.
- On the Browse tab, type EhLib.WinForms in the search box and select the
  EhLib.WinForms.Trial package.
- Select the project(s), select the latest version and click Install.

Design-time support

The design-time support is provided by separate assemblies. You do not reference
them when you use the NuGet package: the package puts each part where the Visual
Studio Windows Forms designer looks for it.

  ------------------------------------------------------------------------------------------
  Target framework                        Design-time assemblies
  --------------------------------------- --------------------------------------------------
  .NET Framework 4.8                      EhLib.WinForms.Design.dll next to
                                          EhLib.WinForms.dll (the classic in-process
                                          designer).

  .NET 8                                  Design\WinForms\EhLib.WinForms.Design.Client.dll
                                          (loaded by Visual Studio) and
                                          Design\WinForms\Server\EhLib.WinForms.Design.dll
                                          (loaded by the designer server). The .NET 8
                                          designer finds them only in this NuGet package
                                          layout.
  ------------------------------------------------------------------------------------------

For a project with several target frameworks keep net48 first in
<TargetFrameworks>. Visual Studio designs forms for the first framework only,
and with net8.0-windows first the EhLib controls lose their design-time
features. The order does not affect running.

The design-time assemblies are not needed at run time. To run your application
it is enough to ship EhLib.WinForms.dll and, for localized messages, its de, fr
and ru resource folders.

Checking the installation

Open any form of your project in the designer and check that the Toolbox shows
the library controls: DataGridEh, DataVertGridEh, ComboBoxEh, etc. Drop a
DataGridEh on the form and set its DataSource (see the demo projects for binding
examples).

If you have problems with the installation, write to support@ehlib.com.

Getting started
---------------

- Demo projects. The solution .\Demos\EhLibDemos.slnx contains the demo projects
  listed below. To build and run them, you do not need to install or configure
  anything: the projects automatically reference the library NuGet package from
  the NuGetPackages folder of the archive (see .\Demos\NuGet.config and
  .\Demos\Directory.Build.props).
- Compiled demos. The compiled demo applications are available as a separate
  archive ehlib_winforms_demos.zip at
  http://www.ehlib.com/en/downloads_winforms.
- Upgrading from a previous version. Details about this version are in
  EhLib.WinForms 2.0 Release Notes Eng.html.

  -------------------------------------------------------------------------------
  Demo project                            Description
  --------------------------------------- ---------------------------------------
  MainDemo                                The main demo of the library controls.
                                          Its data files are in
                                          .\Demos\MainDemo\Data.

  ProcessList                             DataGridEh showing the list of running
                                          processes.

  DisplayLayoutStorableApp                Saving and restoring the grid layout.
  -------------------------------------------------------------------------------

Components
----------

All components are in the run-time assembly EhLib.WinForms.dll; the design-time
assemblies are described in Design-time support. The basic controls of the
library are DataGridEh and DataVertGridEh.

A full description of all components is in the developer's guide
Doc\Eng\EhLib.WinForms - Developers guide.doc and in the help file
Doc\EhLib-WinForms-Help.chm.

  ---------------------------------------------------------------------------------------
  Component / class               Description
  ------------------------------- -------------------------------------------------------
  Grids                           

  DataGridEh                      The main control of the library: displays and edits
                                  data in a tabular format. See DataGridEh features.

  DataVertGridEh                  Vertical grid that shows the contents of one record:
                                  each field is a row. Visually similar to the Windows
                                  Forms PropertyGrid.

  DataPropertyGridEh              A DataVertGridEh with a single data column that shows
                                  one item of the data source at a time.

  Pivot analysis                  

  PivotDataSourceEh               Builds and stores pivot data from a data source.

  PivotGridEh                     Displays pivot data as a cross table.

  PivotGridToolBoxEh              Configures the structure and sections of the pivot
                                  data.

  Planner                         

  PlannerDataSourceEh             Stores planner events.

  PlannerControlEh                Container for planner views: day, week, month, year,
                                  days line, hours line and timeline.

  PlannerCalendarPickerEh         Calendar for navigating through the days of a month.

  Edit controls                   

  TextBoxEh                       Single-line or multiline text edit control.

  MaskedTextBoxEh                 Text edit control with an input mask.

  NumericBoxEh                    Numeric edit control.

  ComboBoxEh                      Edit box combined with a drop-down list.

  DateTimeBoxEh                   Date and time edit control.

  RichTextBoxEh                   Rich text editor.

  Printing and preview            

  DataGridPrintService,           Print the corresponding control and show a print
  DataPropertyGridPrintService,   preview.
  PivotGridPrintService,          
  PlannerViewPrintService         
  ---------------------------------------------------------------------------------------

The grids work with different kinds of data sources and cannot work in unbound
mode. You configure them through properties and extend them by writing event
handlers or creating new types of columns, rows, cells and other grid elements.

The edit controls support edit buttons and data binding.

DataGridEh features

- Select records, columns and a rectangular region.
- Copy the selection to the clipboard, and paste content back into the grid.
- Create complex headers (MultiTitle) that span several columns.
- Create a footer that shows aggregated values (sum, count, etc.) of the fields.
- Group the data and show group headers and footers.
- Show the data as a tree.
- Automatically resize columns so their total width always matches the visible
  grid width.
- Adjust the height of rows and headers through properties.
- Automatically wrap long column headings and cell data into multiple lines,
  extending the row height.
- Sort the data by clicking a column header.
- Fix (freeze) columns on the left and right sides of the grid.
- Show ScreenTips (ToolTips) for text that does not fit in a cell.
- Search the data visually through the built-in SearchBox.
- Filter and pick values through the built-in TitleFilter.
- Save and restore the columns layout (visible columns, order, width, sort
  order) to/from classes that can be serialized to a settings file.
- Print the grid and show a print preview.

DataVertGridEh shares the automatic column resizing, row height adjustment,
multiline wrapping and ScreenTips features.

Column and row types

Columns of DataGridEh and rows of DataVertGridEh can be created at design time
(static) or dynamically from the property list of the data source.

  -----------------------------------------------------------------------------------
  Column of DataGridEh        Row of DataVertGridEh        Shows the data as
  --------------------------- ---------------------------- --------------------------
  DataGridTextColumn          DataVertGridTextRow          Text.

  DataGridMaskedTextColumn    DataVertGridMaskedTextRow    Text with an input mask.

  DataGridComboBoxColumn      DataVertGridComboBoxRow      Text with a drop-down
                                                           list.

  DataGridDateTimeColumn      DataVertGridDateTimeRow      Date/time value.

  DataGridButtonColumn        DataVertGridButtonRow        Button.

  DataGridCheckBoxColumn      DataVertGridCheckBoxRow      Check box.

  DataGridRadioButtonColumn   DataVertGridRadioButtonRow   Radio button.

  DataGridImageColumn         DataVertGridImageRow         Picture.

  DataGridProgressBarColumn   DataVertGridProgressBarRow   Progress bar.
  -----------------------------------------------------------------------------------

Documentation
-------------

  -----------------------------------------------------------------------------------------
  Document                                Location
  --------------------------------------- -------------------------------------------------
  Release notes for this version          EhLib.WinForms 2.0 Release Notes Eng.html

  Help file                               Doc\EhLib-WinForms-Help.chm

  Help for the Visual Studio Help Viewer  Doc\Mshc (install with
                                          Install_EhLib-WinForms-Help.bat)

  Developer's guide                       Doc\Eng\EhLib.WinForms - Developers guide.doc

  Developer's guide in Russian            Doc\Rus

  Demo projects                           Demos\EhLibDemos.slnx

  Online help                             https://www.ehlib.com/en/ehlib.vcl-online-guide

  Home page                               https://www.ehlib.com
  -----------------------------------------------------------------------------------------

Editions and licensing
----------------------

EhLib.WinForms is a commercial product. It is supplied in three editions:

  -------------------------------------------------------------------------------------
  Edition                    NuGet package                   Contents
  -------------------------- ------------------------------- --------------------------
  EhLib.WinForms with source EhLib.WinForms.SourceIncluded   Source code of the library
  code                                                       in C# and the compiled
                                                             assemblies with debug
                                                             symbols.

  EhLib.WinForms without     EhLib.WinForms.WithoutSource    Compiled assemblies of the
  source                                                     library.

  EhLib.WinForms Trial       EhLib.WinForms.Trial            Compiled assemblies for
                                                             evaluation; the grids show
                                                             a "Trial Version"
                                                             watermark. Also available
                                                             on nuget.org.
  -------------------------------------------------------------------------------------

Registration

If you find EhLib.WinForms useful, please register your evaluation copy. After
registration, you will receive by e-mail the download address of the registered
version and the password for unpacking it.

Registered users get:

- new versions of the library free of charge for one year from the date of
  registration;
- technical support of any complexity, unlimited in time.

Registration also helps the EhLib Team make the library even better.

- Prices and Registration: https://www.ehlib.com/en/node/330

Support and contacts
--------------------

Contact us if you have any questions, comments or suggestions.

  ------------------ --------------------------------------
  Company            EhLib Team
  Website            https://www.ehlib.com
  E-mail             support@ehlib.com
  MS Teams support   ehlib.support
  Support forum      https://forum.ehlib.com/en
  Feedback           https://www.ehlib.com/en/feedback-28
  ------------------ --------------------------------------
