Custom Widgets

From VirtualFabWiki
Jump to: navigation, search

Custom Widgets

As for now VGDD was in some way limited in its usage since you could only use GOL widgets already built in and coded into the program.

My commitment in staying in sync with GOL enhancements (new controls, new behaviours) has always been high, but

  1. It's hard to develop in Dot.net a component whose aspect and behaviour on PC is exactly the same as its original GOL on hardware
  2. And most important of all I can't develop a custom control in VGDD for each control YOU developed.

So the answer is VGDD version 2.x.x that has a built-in mechanism that lets you define every property of your custom widget, give it a bitmap representation to handle it on screen and generate the suitable C code as for the others GOL controls.

It's a milestone enhancement, and it took a long way to make it work and more to come, but it opens up new usages for VGDD: not only GOL objects, but also other Third Parties Graphical Libraries!

What are Custom Widgets

Custom Widgets are controls whose C code is already developed, by you or someone else, that have their properties, graphical on-screen representation and optionally their events. They also have a declaration in C code and a constructor like any other standard GOL widget.

With the new Custom Widget Editor you simply (!) give these information to VGDD in order to let it handle your widgets like VGDD does with the standard GOL Widgets.

Once these informations about your Widgets are known to VGDD, it lets you handle them on screen exactly as if they were Buttons or StaticText.


Custom Widgets Editor

The Editor lets you define and edit your Widget. To edit an existent one, simply select it in the combobox. To create a new one, type its name in the same combobox: the New button will appear and when you click it, an empty widget definition will be loaded into the treeview below:

CustomWidgetsEditor.png

Definition

Clicking on the Definition node will let you add new properties for the widget: type in property name and click on 'Create New Property' Note that you'll have to define each and every property such as left, top, right, bottom that are common to almost every GOL Widget.

Bitmaps

Each Custom Widget has two bitmaps associated with it: the one that will be used to give a visual representation while manipulating it on screen, and one for the ToolBox on the left, from which you drag and drop widgets on the screen. It can be the same bitmap; VGDD rescales the ToolBox bitmap to a .ico file 16x16 pixels to let it be correctly displayed.

Properties

For each property you have to define two mandatory elements: Name and Type. The other are optional and self explanatory. Only the following need some clarification:

  • DestProperty: When you define a property (like Hidden or Enabled) whose value should not be directly used but instead used to determine another property for the widget (the STATE property in this example), then here you have to specify the destination property name. VGDD will use the 'Hidden' property value to calculate the STATE final property and use that value in code.
  • Eval: this feature has been created mainly for the different handling between Dot.Net Surface Designer and GOL for the dimensions of the widgets: while GOL uses right and bottom absolute coordinates, Dot.Net, and therefore VGDD, modify width and height values while moving widgets on the screen. So in your widget you ought to define the right and bottom properties (for GOL to use them) but you also have to make VGDD calculate their values while moving it on the screen. This is achieved by entering for example "left+width" for the "right" property in the Eval box. VGDD will evaluate the expression and place the correct value in the "right" property. Ok, a little bit complicated, but it works! :-)

CodeGen

Here you have the code-generation sections.

Header

Type in the C code you want to be added to the header file (.h) in the generated code. For example:

#define ID_[CONTROLID_NOINDEX][CONTROLID_INDEX] [NEXT_NUMID]

The values between square brackets are special names whose value is explained in the CodeGen Special Values page.

CodeHeadComment

Here you can specify some additional code or comment that will be placed on top of the code file (.c). For example:

// #define USE_ANALOGCLOCK  // Enable Analog Clock Object

Constructor

Here goes the code that builds the object:

ANALOGCLOCK *p[CONTROLID];

Code

And finally the code itself, the one that creates the object in GOL:

p[CONTROLID] = AcCreate(ID_[CONTROLID], [LEFT], [TOP], [RIGHT], [BOTTOM], [HOUR], [MINUTE], [RADIUS], [SECHAND], [STATE], [BITMAP], GOLScheme_[SCHEME]);

As you can see, it is only a parametrized version of the AcCreate function call, with each parameter (left, top, etc.) put in uppercase and between square brackets.

So one thing appears clear: in your widget you have to create a property for each of the parameters the widget needs for its creation. Then you put all these properties in the Code section and to help you in this work there is a Property Picker named "Code Options" in the upper part of the editor that lists every defined property and other Special Values like [CONTROLID]. Simply pick the desired one from the list and then click on the Insert button to have it pasted in the code below.

State

The State section lets you define state values like Hidden or Disabled, and their relative C values as defined in your widget's header. This values are associated with the property having the same name. See the Grid and DigitalMeter widgets for an explanation

Events

In this section you can define event names for your widget. The Event names defined here will populate the Event Window in VGDD letting you to define specific code to be executed when those events are fired. See the Automatic Event Handling page for details on Event handling.

Actions

Here you can specify Action helpers for the Event Editor.