User Tools

Site Tools


getting_started_with_calendarset

Getting started with CalendarSet


Creating your first CalendarSet Area

It’s easy to create your first CalendarSet area.

  1. Create a new form, or open an existing one that you want to add a calendar to.
  2. Choose Plugin Area from the Plugin / Subform / Web Area button in the object bar:
  3. Your cursor will turn into a crosshair. Draw a box on the form in the size that you want your calendar to be. This will create a rectangular box named Plugin Area.
  4. In the Property List window, choose CalendarSet from the Type popup menu. (If the “CalendarSet” option is not available, please refer to the installation instructions).
  5. Enter a name for your new area in the Variable Name field in the Property List window.
  6. Your area will now show the CalendarSet version and copyright information.

The variable name will be used as a parameter for the CalendarSet commands.

Be careful to never have two CalendarSet objects with the same variable name on a 4D form.


Working with CalendarSet Commands and Functions

You can use the commands and functions to configure every aspect of a CalendarSet area, and to get information about an area.

The commands and functions are grouped into themes: User Action, Configuration, Drag and Drop, etc.

When to use the Commands and Functions

All CalendarSet commands and functions need to be passed a reference to the area on which they will act. Since CalendarSet areas are initialised in the On Load phase of a form, the commands must be called during this phase or afterwards; if you try to call any CalendarSet commands before the form has been loaded, you’ll get an error message because 4D does not recognize the area reference.

If you do not issue any CalendarSet commands in the On Load phase, and you haven’t chosen any arrays in the Advanced Properties dialog, an empty calendar will be displayed in the CalendarSet area on the form.

You can modify the area by making calls to commands during any other phase or from objects, such as buttons and menus, on the form or in menu bars.

The commands can be used completely independently of the Advanced Properties dialog, or they can work in conjunction with the options you set therein.

For example, you might select the arrays to display in the Advanced Properties dialog and then use some commands to specify different coloring for each event according to some criteria that you specify.

Anatomy of a CalendarSet Command

Each command you write must adhere to a specific syntax in order for it to be correctly understood by CalendarSet. Some commands return a result: these are functions. You can use the commands and functions to configure every operation performed by CalendarSet, and to get various information.

Each CalendarSet command has a syntax, or rules, that describe how to use the command in your 4D database. For each command, the name of the command is followed by the command’s parameters, and result in case of functions.

A CalendarSet command syntax looks like this:

CS_GetAreaPtrProperty (area:L; property:T; pointer:Z) → result:L

The parameters are enclosed in parenthesis, and separated by semicolons.


Command parameters

Each parameter is followed by a colon and a letter indicating the type of data required for that parameter:

:L - longint
:O - blob
:P - picture
:R - real
:T - text
:Y - array
:Z - pointer

Each is preceded by one of three arrow signs, which indicate whether it is a value that you pass to the command or one that the command returns to you, or a value that is passed, then modified and returned by the command in the same parameter:

→ parameter – A value that you pass to the command

← parameter – A value that is returned by the command

Note: when calling a plugin command, all omitted parameters are initialized to the NULL of the respective types (0, 0.0, "", !00:00:00!, …).


Area reference

The first parameter for most commands is the area reference, depending on the way the plugin area was created:

This parameter is a long integer, and is required to allow the commands to operate on the correct object.

Note: If an invalid area reference is passed to CalendarSet, the 4D debugger will open in trace (interpreted mode) or an alert is displayed (compiled mode).


Upgrading from Previous Versions of CalendarSet

To upgrade to CalendarSet version 6, simply install it as described in the Installation section of this manual, replacing your older version.

New in version 6

See the About CalendarSet v6 section.

New in version 5

See the About CalendarSet v5 section.

New in version 4

Online registration

CalendarSet provides an automated solution to register itself using an Internet connection.

This feature can be helpful whenever you don’t want to bother your end user with plugin registration, or want to save the time to collect the serial / machine ID, or any other reason when you want the process to be entirely and automatically managed from the client site.

See Online instant activation in the installation chapter.

Offscreen mode

CalendarSet v4 allows offscreen areas, which can be set, populated and printed or published on the Web (using CS_GetPicture) without being displayed.

Unicode

CalendarSet supports Unicode for display.

64 bit Server

CalendarSet version 4.0 supports 64 bit server on Windows and MacOS. This feature is only useful for registration or automatic purposes (no user interface), CalendarSet is not meant to be used on a server by a user. However, for example, printing CalendarSet areas will work on a 64 bit server.

Constants

Constants are available for most command parameter values, to help code legibility and maintenance.

New commands

  • CS_GetDrgSrcArea returns the source area reference and process when a Drag and Drop has occurred.
  • CS_NewOSArea creates an offscreen area.
  • CS_DeleteOSArea destroys an offscreen area previously created with CS_NewOSArea.
  • CS_SimClick posts a click event in an area, either on screen (same as 4D’s POST CLICK) or offscreen.
  • CS_GetPicture returns a PDF (MacOS)or EMF (Windows) vector picture of the specified area. This feature can be useful for web publishing or offscreen printing, amongst others.

Event times

Time is now supported in events.

  • CS_SetArray has a new parameter (timeArray), which must contain the name of a longint or time array.
  • CS_SetEventOpts has a new parameter :showEventTimes. When the column is wide enough, if the timeArray was provided and showEventTimes is nonzero, events are displayed with the time on the right side.

Alternate “Windows” date popup

An alternate “Windows” look popup date control is available on both platforms when the new design parameter to MM_SetOptions is set to 1:

What’s Changed

Drag and Drop

In previous versions, CalendarSet used its own drag and drop manager. It now uses 4D’s drag and drop manager. Drop always occurs in the context of the destination process.

This means that you will need to make a few changes to your drag and drop handling. For more information, see CalendarSet Dragging Commands.

Event Handling

If a drag is initiated, CalendarSet receives a drag event. But this has nothing to do with the actual drop: it could end anywhere (e.g. if the user pressed Esc — no drop). 4D does not inform CalendarSet that the drag was not successful.

When a drop has occurred, an On Drop event is fired. You should therefore use the new CS_GetDrgSrcArea command to find out what was dropped.

Accepting Drops from non-CalendarSet objects

CalendarSet can accept drags from non-CalendarSet objects such as AreaList Pro areas or other 4D objects (in the same process or a different one) and external sources (text selection or document). Furthermore, the drop from external sources can be allowed or disallowed.

Drag and drop to banners

It is now possible to drag and drop to banners.

Native drawing of text

CalendarSet uses CoreText on Mac and GDI+ on Windows.

Only fonts and font faces supported by these technologies can be used in CalendarSet. In particular, GDI+ does not support non-TrueType fonts on some Windows versions.

MM_SetOptions new parameters

MM_SetOptions (area; popIndicator; useDoubleClick; design; colors)

  • popIndicator is 3-state: 0 = popup arrow(s), 1 = nothing (transparent), 2 = calendar picture
  • useDoubleClick defaults to 0, which means “close on single click”
  • design selects the Date Popup variant — identical to AreaList Pro (0 = MacOS, 1 = Windows)
  • colors is the text specifying the 8 different colors used by the Date Popup — identical to AreaList Pro

TM_SetOptions new parameters

TM_SetOptions (area; popIndicator; useDoubleClick)

  • popIndicator is 3-state: 0 = popup arrow(s), 1 = nothing (transparent), 2 = time picture
  • useDoubleClick defaults to 0, which means “close on single click”

Current day background

Current day background is supported (CS_FontDefaults with selector 5, advanced properties).

For compatibility reasons, when the area background color is set (CS_SetCalColor), the current day background color is set to the same value. Set the current day background color after setting the area background color.

Unused days background

Unused days background can be set separately from the background color (third parameter to CS_SetCalColor).

First day of the week

The default value for the first day of week is taken from the system (use -1 to apply the system setting in your call to CS_Options).

Icons

The resource fork model is now completely obsolete. Therefore you must move the icons to be used into the picture library before calling CS_SetIconArray.

Banners

Banners are stacked from the bottom and can be partially visible below the events.

Ellipsis in banners

CalendarSet will automatically truncate data and display the standard ellipsis (…) if the banner width is too small to display the full text. The ellipsis is now displayed in the middle of the banner text instead of at the end.

Obsolete Commands

If you are using any of the following commands, you will need to remove them from your code:

Old Command How to replace it
CS_DoResize No longer exists, remove and use 4D options (“Grow”) or commands (OBJECT MOVE).
CS_DragMgrAvail No longer relevant; always true.
CS_GetContRef Obsolete.
CS_GetDrgArea Obsolete, use CS_GetDrgSrcArea.
CS_SetSizeOpts No longer exists, remove and use 4D options (“Grow”) or commands (OBJECT MOVE).
Util_SetDate Deprecated, use 4D’s Add to date (!00/00/0000!;$years;$months;$days)

getting_started_with_calendarset.txt · Last modified: 2020/06/10 08:58 by cs_admin