Custom Controls

Allgemeines

Hintergrund

Framework Studio stellt eine breite Palette von Standard Controls zur Verfügung. Sie sind jedoch nicht darauf angewiesen, sich auf diese Controls zu beschränken. Mit Custom Controls bietet Framework Studio einen komfortablen Weg, eigene, komplexe oder stark spezialisierte Controls zu entwickeln und in Ihre Anwendung zu integrieren.

Beispiele für diese so genannten Graphical Custom Controls sind: dreidimensionale Darstellung von Statistiken Farbauswahldialog HTML-Textfeld ...

Ein weiteres Anwendungsgebiet für Custom Controls sind funktionelle Erweiterungen des Clients, die lokal am Client ausgeführt werden müssen.

Beispiele für Functional Custom Controls sind: lokaler Dateiauswahldialog Telefonanbindung (TAPI) Darstellung von Daten in externen Programmen (z.B. Word oder Excel) ...

Aufgrund der Client-Server Architektur, die Framework Studio unterstützt, muss für ein Custom Control sowohl der Client (ggf. auch mehrere) als auch Ihre Anwendung in Framework Studio um eine entsprechende Definition des Controls erweitert werden.

In dieser Dokumentation wird die Erweiterung in Framework Studio beschrieben. Informationen zur Erweiterung der Clients finden Sie in den entsprechenden Dokumentationen.

Erstellen und Löschen von Custom Controls

Erstellen eines Custom Controls Custom Controls werden wie alle anderen Elementtypen erzeugt. Dazu muss einer der drei Typen Functional, Graphical und Child Custom Control ausgewählt werden.

Elemente erstellen

Löschen eines Custom Controls

Elemente löschen

Verwendung von Custom Controls in Forms

Um ein Custom Control in ein Form zu integrieren, öffnen Sie das Form im Form-Designer (Forms) und wechseln Sie anschließend auf die Registerkarte Toolbox (Framework Designer). Von dort ziehen Sie das gewünschte Control auf die Registerkarte Default Variant des Form-Designers. Wenn Sie ein Functional Custom Control einfügen, wird dieses im Form-Designer auf der Registerkarte Functional Controls (Registerkarte Functional Controls) angezeigt.

Properties

Ein Custom Control kann bestimmte statische Eigenschaften besitzen, die der Entwickler im Form-Designer angeben können soll. Diese Properties werden bei der Initialisierung des Custom Controls übertragen.

Anwendungsfallbeispiele sind statische Spaltenüberschriften einer Tabelle oder allgemein Initialisierungsparameter für komplexe Controls.

Diese Eigenschaften sind Theme-spezifisch, sodass in den Default Control Styles z.B. Farbwerte und Schriftarten je nach Theme angepasst werden können. Die einzige Ausnahme bilden Properties mit dem Typ MLString. Diese sind Theme-übergreifend.

Wenn Sie für ein Custom Control ein neues Property anlegen möchten, benutzen Sie entweder den Button New... / Property oder wählen den Menüpunkt File / New / Property.

Custom Control Registerkarte Properties:

Anschließend können Sie auf der Registerkarte Properties die Eigenschaften des Properties festlegen.

In der Auswahlbox oben auf der Registerkarte können alle Properties des Custom Controls ausgewählt werden. Zum ausgewählten Property werden dann darunter die Eigenschaften angezeigt.

Name

Name des Properties.

Type

Typ des Properties. Hier werden alle Standard .NET Datentypen, einige speziellere .NET Datentypen wie Color und Font sowie der Framework Studio Datentyp MLString angeboten.

Category

Hier kann ein Name für die Kategorie angegeben werden, unter der das Property auf der Registerkarte Properties eines Forms bei markiertem Control angezeigt wird.

TypeConverter

Hier kann ein Typkonverter für die Eingabe im Propertygrid auf der Registerkarte Properties angegeben werden. Beispielsweise NonnegativeInt32Converter, um nur die Eingabe von positiven Ganzzahlen zu ermöglichen.

UITypeEditor

Ein Typeditor kann für eine komfortable Eingabe eines Wertes im Propertygrid angegeben werden. Zum Beispiel der UrlUITypeEditor, mit dem URLs eingegeben und auf Gültigkeit geprüft werden können.

Alle Default Control Styles, auch die von Custom Controls, werden im Namespace FSGeneral / Controls aufgelistet. Wenn Sie dort Ihr selbst definiertes Custom Control öffnen, können Sie für die Properties des Custom Controls Standardwerte vorbelegen.

Custom Control Default Control Style:

Wenn Sie ein Functional Custom Control auf ein Form ziehen und es markieren, werden Ihnen die selbst definierten Properties auf der Registerkarte Properties angezeigt.

Custom Control Instance Properties:

Actions

Actions ermöglichen dem Programmierer, am Client eine Methode des Custom Controls aufzurufen.

Um eine neue Action anzulegen, benutzen Sie entweder den Button New... / Action oder wählen den Menüpunkt File / New / Action.

Auf der Registerkarte Actions des Custom Control Designer-Fensters können Sie in der Auswahlbox zwischen allen Actions des Controls auswählen. Die ausgewählte Action wird darunter dargestellt.

Custom Control Registerkarte Actions:

Name

Name der Action. Dieser Name dient am Client zur Identifizierung der Action.

Declaration

Deklaration der Methode, die über das Control aufgerufen werden kann. Die Methode darf keinen Rückgabewert haben und kann beliebig viele Parameter entgegen nehmen. Die Parameter müssen einfache .NET Datentypen sein.

Custom Control Registerkarte Method:

Nach der Definition einer Action kann diese Action aus einem Form heraus, wie im obigen Bild dargestellt, aufgerufen werden.

Datasources

Datasources dienen zum bidirektionalen Datenaustausch zwischen Client und Broker. Die gemeinsame Datenquelle funktioniert genau wie die Datasources an den Standardcontrols.

Um einen neuen Datasource anzulegen, benutzen Sie entweder den Button New... / Datasource oder wählen den Menüpunkt File / New / Datasource.

Custom Control Registerkarte DataSources:

Auf der Registerkarte DataSources können Sie in der obersten Auswahlbox zwischen allen Datasources des Controls auswählen. Die Eigenschaften der ausgewählten Datenquelle werden darunter dargestellt.

Name

Name des Datasources.

Type

Typ des Datasources. Zur Auswahl stehen folgende Werte:

• Value: Die Datenquelle kann mit einem beliebigen FS-Standarddatentypen gefüllt werden (z.B. string, int, object, ...)
• Record: Objekt vom Typ DevFrameworkObject
• Collection: Collection vom Typ DevFrameworkObjectColl
• SelectedRowsCollection: SelectedRowsCollection
• Inherit: Funktionslos

Bei den Typen Record, Collection und SelectedRowsCollection müssen Methoden implementiert werden, welche die gewünschten Daten aus einem Objekt in Xml und zurück in ein Objekt übertragen! Beim Typ Value ist dies nicht nötig.

Custom Control Instance Datasource:

GetXML

Diese Methode wird zum Senden der Daten vom Broker an den Client benötigt. Die Daten müssen aus dem Objekt in einen geeigneten Xml-Knoten umgewandelt werden. Die Methodendeklaration lautet:

IEnumerable<XObject> GetDataSourceXml(Dictionary[…] value)

Wobei DataSource durch den Namen der Datenquelle ersetzt wird. Alle zurückgegebenen Elemente oder auch Attribute werden in den von Framework Studio generierten XML-Knoten mit dem Typ XElement eingefügt. Diese Methode kann das Ergebnis als Liste zurückgeben. Man kann das Ergebnis aber auch mit Hilfe von „yield return“ enumerieren. Wenn keine Informationen an den Client übergeben werden sollen, dann wird einfach „return null;“ aufgerufen.

Beispiel einer GetXML-Methode:

List<XObject> xaList = new List<XObject>();
cColor oColor = value as cColor;
if (oColor != null)
{
    xaList.Add(new XAttribute("A", oColor.intA.ToString()));
    xaList.Add(new XAttribute("R", oColor.intR.ToString()));
    xaList.Add(new XAttribute("G", oColor.intG.ToString()));
    xaList.Add(new XAttribute("B", oColor.intB.ToString()));
}
xaList.Add(new XElement("EinUnterKnoten"));
return xaList;

Dasselbe Beispiel als Enumerator mit yield return:

cColor oColor = value as cColor;
if (oColor != null)
{
    yield return new XAttribute("A", oColor.intA.ToString());
    yield return new XAttribute("R", oColor.intR.ToString());
    yield return new XAttribute("G", oColor.intG.ToString());
    yield return new XAttribute("B", oColor.intB.ToString());
}
yield return new XElement("EinUnterKnoten");

Das erzeugte XML sieht folgendermaßen aus:

<Data>
    <Color A="0" R="0" G="0" B="0">
        <EinUnterKnoten />
    </Color>
</Data>

SetXML

Diese Methode wird zum Empfangen der Daten vom Client am Broker benötigt. Die Daten müssen aus dem XML-Knoten ausgelesen und in das Objekt kopiert werden. Die Methodendeklaration lautet:

void SetDataSourceXML (XElement xeNode,
Dictionary<string, string> properties,
Dictionary<string, Dictionary<string, string>> children,
DevFrameworkObject value)

Mit dem Parameter xeNode wird der komplette DataSource-Knoten übergeben. Aus diesem können jetzt die Attribute und Elemente ausgelesen werden.

Einfaches Beispiel:

cColor oColor = value as cColor;
if (oColor != null)
{
    oColor.intA = int.Parse(xeNode.Attribute("A").Value);
    oColor.intR = int.Parse(xeNode.Attribute("R").Value);
    oColor.intG = int.Parse(xeNode.Attribute("G").Value);
    oColor.intB = int.Parse(xeNode.Attribute("B").Value);
}
foreach(XElement xeSubNode in xeNode.Elements())
{
    ... Unterknoten auswerten ...
}

Events

Events kann der Client senden. Auf diese Events kann dann am Broker reagiert werden.

Um ein Event anzulegen, benutzen Sie entweder den Button New... / Event oder wählen den Menüpunkt File / New / Event.

In der Klassenansicht (Registerkarte ClassView im Hauptfenster) können Sie den Namen des Events ändern.

Wenn Sie Ihr Custom Control in ein Form gezogen haben, können Sie im Form an das Event wie gewohnt einen Eventhandler anhängen.

Custom Control Eventhandler:

Child Custom Controls

Wenn Sie auf der Registerkarte Namespaces des Framework-Designers im Objekt-Baum ein Custom Control markieren, können Sie über den Menüpunkt File / New / Custom Control / Child Custom Control ein Untercontrol anlegen.

Warning

An einem Untercontrol können Sie nur Properties definieren. Alle anderen Funktionen müssen über das Hauptcontrol abgewickelt werden.