Difference between revisions of "Turbopower Visual PlanIt"

From Lazarus wiki
Jump to navigationJump to search
Line 58: Line 58:
 
== Using the planner components ==
 
== Using the planner components ==
 
=== Getting started ===
 
=== Getting started ===
[[image:tvplanit_tutorial.png|right]]
+
[[image:tvplanit_tutorial.png]]
 +
 
 
Here is a quick tutoral for your first steps with the VisualPlanIt components.
 
Here is a quick tutoral for your first steps with the VisualPlanIt components.
  

Revision as of 00:29, 4 August 2016

English (en) português (pt) русский (ru)

About

Visual PlanIt is a set of synchronized, data-aware components for adding time, task, & contact management capabilities to applications. Get that Outlook look & feel without the hassle.

This component was designed for cross-platform applications.

Screenshot

Tvplanit.PNG

Author

Author: Turbo Power Software
LCL Port: Christian Ulrich and Werner Pamler

License

Mozilla Public Licence 1.1

Download

not at time

SVN

You can checkout the actual source from

https://lazarus-ccr.svn.sourceforge.net/svnroot/lazarus-ccr/components/tvplanit

The commandline to do this is

svn co https://lazarus-ccr.svn.sourceforge.net/svnroot/lazarus-ccr/components/tvplanit

Bug reporting / Feature request

Bug reports and feature requests should be sent to the Lazarus/Free Pascal Bug Tracker; please specify the "Lazarus-CCR" project: http://bugs.freepascal.org/

Change Log

  • Feb 02, 2008 - Initial port (version 1.03)
  • Aug 01, 2016 - (Almost) complete port (version 1.04)

Dependencies / System Requirements

  • FPC 2.6.4 or newer
  • Lazarus 1.4.4 or newer
  • These versions were available at the time of writing this update. It is not exluced that the package can be used with older versions as well.

Installation

  • Create a directory for the components, such as lazarus\components\tvplanit
  • In this directory, unzip the files from the zip file, or execute the svn commandline from above.
  • Open lazarus
  • Open the package laz_visualplanit.lpk from the source folder with Package/Open package file (.lpk).
  • (Click on Compile only if you don't want to install the component into the IDE)
  • Click on Install
  • If you need the Zeos datastore repeat with package laz_visualplanit_zeos.lpk from folder source/addons/zeos. Make sure that the Zeos components are installed.

Documentation

If you need a full documentation of the the VisualPlanIt suite get TurboPower's original 300-page pdf file from the official SourceForge site of the Delphi version (https://sourceforge.net/projects/tpvplanit/files/tpvplanit_docs/).

Using the planner components

Getting started

tvplanit tutorial.png

Here is a quick tutoral for your first steps with the VisualPlanIt components.

  • Create a new application. Save it into its own folder.
  • Add a TPageControl with three sheets. Name them "Events", "Tasks", and "Contacts".
  • In the component palette seek for the tab Visual PlanIt.
  • Pick TVpDayView and add it to the "Events" sheet of PageControl. This is a day calendar and displays events (appointments, meetings, etc) for the entire day with a resolution as defined by its so-called Granularity.
    • If you are used to times in the 24-hour format switch TimeFormat to tf24Hours.
    • If the calendar is sufficiently wide you may want to change NumDays to - say - 2 to see two days at once.
    • Give the components a more modern look by setting DrawingStyle to dsFlat.
    • Similarly you can add a TVpWeekView (a week calendar) and/or a TVpMonthView (a month calendar) to the "Events" sheet. They give an overview of the same events, but with less resolution. Text ellipsis ("...") are shown if the event text cannot be fully displayed.
  • Now add a TVpTaskList to the "Tasks" sheet of the PageControl. It is a listing of to-do items along with their due dates. Overdue tasks are written in red. Completed tasks are striked out. Note that DisplayOptions.ShowCompleted or .ShowAll must be checked in order to see completed tasks.
  • Finally add a TVpContactGrid to sheet "Contacts" of the PageControl.
  • Again, you may want to use DrawingStyle dsFlat for a more modern look.
  • Play with the properties to setup all these visual controls according to your preferences. The TVpWeekView, for example, has a property to define whether the week starts on Monday or Sunday (WeekStartsOn).
  • Two ingredient are missing: the DataStore and the ControlLink.
    • The Datastore is a component which stores the data to be displayed in the visual controls. The Visual PlanIt package contains a series of predefined datastores - see below. We select here a TVpIniDatastore or TVpXmlDatastore which store the data in an ini or xml file - these stores do not require a database like the other datastores.
    • In the property Filename, enter a name for the datastore file, e.g. data.ini or data.xml, respectively. Using a relative filename here means that the path will be relative to the location of the exe file of the program which is convenient for this tutorial. In a "real" application, however, an absolute path may be preferrable. And it may also be advantageous to enter the filename at runtime, e.g. in the FormCreate event handler.
    • If the filename is known at designtime you can set AutoConnect to true in order to open the datastore automatically when the program starts. If the filename is specified at runtime leave AutoConnect at false and set the datastore's Connected property to true.
    • The ControlLink automatically establishes a link between the datastore and the visual controls and makes sure that the controls get their data if needed and are synchronized.
  • Now it's time to run the program
  • How to add data? This is done by double-clicking on any of the controls that we added to open a specific built-in editor for convenient entering of the data needed.
  • At the first time, however, a dialog pops up saying that "no resources have been defined". A resource is everything which can be administrated by the VisualPlanIt tools, such as an employee, a meeting room, a library of books, etc. Enter the name of the resource. If your program will deal with various resources you can add a TVpResourceCombobox to select the resource needed for the program run. Make sure to use unique resource names because VisualPlanIt will throw a duplicate-resource exception otherwise.
  • When you restart the program the next time you will notice that the data are no longer visible. No reason to be alarmed - the data are still there, but the program just does not know which resource to open. Enter this code in the FormCreate event, after connecting to the datastore:
procedure TForm1.FormCreate(Sender: TObject);
begin
  // Use this code if the filename is not set in the Object Inspector...
  VpXmlDatastore1.FileName := name_of_the_datastore_file;
  // ... and the datastore is not autoconnected.
  VpXmlDatastore1.Connected := true;
  // This code selects the first resource (index 0) found in the datastore.
  if VpXmlDatastore1.Resources.Count > 0 then
    VpXmlDatastore1.Resource := VpXmlDatastore1.Resources.Items[0];  
end;

Datastores

Datastores are responsible for persistent storage of event, task and contact data records.

The ancestor of this hierachy of classes is TVpCustomDatastore. It implements the basic functionality and provides fundamental abstract methods, such as LoadEvents, LoadTasks, LoadContacts, PostResources, PostEvents, PostTasks, PostContacts. Its member class Resources (type: TVpResources) stores all resources in a list as TVpResource items. Such a resource item, in turn, contains other lists: Schedule, Tasks, and Contacts for all event, task and contact records. The currently selected resource can be accessed by the datastore's Resource or ResourceID properties (the latter is a unique numerical ID to identify the resource).

TVpCustomDBDatastore inherited directly from TVpCustomDatastore. It is another (pseudo-) abstract class which provides the basic database functionality by means of four datasets, ResourceTable, EventsTable, TasksTable, and ContactsTable.

TVpIniDatastore

This is a simple file datastore which inherits from TVpCustomDatastore. It stores the data records in a simple ini file structure. The name of the ini file must be specified in the corresponding property. The file is loaded after the datastore has been created if the design-time property AutoConnect is true, or when the run-tim property Connected is switched to true. The file is saved automatically when Connected goes back to false - this happens before the datstore is destroyed.

The demo project examples/datastores/ini is an example how the ini datastore can be used.

TVpXmlDatastore

This is another simple file datastore. It works similarly as the ini datastore except that the file is an xml file now. The datastore's tree of xml nodes can be inserted into any existing xml file, e.g. files written by TXMLDataStorage. For this purpose, the node must be specified to which the datastore's nodes will be attached (property ParentNode).

Have a look at the demo project in examples/datastores/xml to see the xml datastore at work.

Printing and print preview

Using the navigation bar

vpnavbar.png

TVpNavBar, seen in the left of this screenshot of the navbar demo, is a navigation tool smiliar to the one known from Outlook. It consists of several folders represented by button-like controls and several items - these are the labelled icons in the large space between two buttons. The folder button - which can be drawn in several button- or tab-like styles - is always shown above the associated item area. Clicking on a folder divides the stack of folders in an upper and lower part, and displays the items assigned to this folder between the corresponding folder at the top and the next folder at the bottom. The index of the currently expanded folder is given by the property ActiveFolder, and the index of the clicked items within this folder is given by property ActiveItem. An event OnItemClick fires when an item is clicked, it has the index of the clicked item as a parameter.

Populating a TNavBar at designtime is a bit complicated. In the original version of VisualPlainIt there exists a component editor, but this does not work and was not ported/adapted to Lazarus so far. Therefore, it is best to learn this task by means of the object inspector:

  • Add a TVpNavBar component to the form.
  • Add an imagelist with, ideally 32x32 images, and assign it to the Images property of the NavBar.
  • Click on the "..." button next to FolderCollection to open the collection editor for the folders.
  • Click "Add" to add a new folder.
  • Select the new folder in the collection editor, its properties appear in the object inspector.
  • Specify the Caption of the folder - this is the text to appear on the button/tab assigned to the folder.
  • Leave IconSize at isLarge if you want to use large icons for this folder's items. In this case, icons and their captions will be centered, the caption will be below the icon and word-wrapped if the text is longer than the width of the NavBar. If you select isSmall, on the other hand, icons and captions are left aligned, and the (non-wrapped) captions are drawn at the right of the icons. If the image size is larger than 16x16 pixels, images will be scaled down to this size. IconSize can change from folder to folder. If you plan to use both small and large images you should ideally add a second ImageList with 16x16 images to the form and switch ImageLists in the OnfolderChanged event.
  • Do not set the FolderType to ftContainer - this feature of adding other controls to the folder is not working at the time of this writing in Lazarus.
  • In order to add icons to the folder click on ItemCollection. This opens the collection editor fot the items belonging to the current folder.
  • Again click "Add" to create a new item, and select it in the collection editor to show its properties in the object inspector.
  • Caption is the text assigned to the item.
  • IconIndex identifies the icon to be drawn for this item. It is the index in the ImageList assigned to the NavBar's Images.

Gadgets

vpgadgets.png

In addition to the planner components the Visual PlanIt package contains also two stand-alone gadgets:

TVpLEDLabel

This is a 14-segment LED display which can display any ASCII string. The string is defined by means of the property Caption, but the count of LED characters must be defined explicitly using the property Columns

TVpClock

This is a digital or analog clock - depending on the property DisplayMode. A variety of settings can be adjusted for each mode separately by using the properties in AnalogOptions and DigitalOptions. The properties are pretty much self-explanatory, except maybe the DigitalOptions.MilitaryTime which activates the 24-hour display if true, or the 12-hour am/pm mode if false. The AnalogOptions.ClockFace replaces the default-drawn clock face by a bitmap - see screenshot above.

With the property ClockMode the operation of the clock can be changed from standard clock (count-up or count-down timer, cmClock, cmTimer, cmCountdownTimer, respectively).