Best Practice - Programmierung von Ribbons

Transkript

1 Best Practice - Programmierung von Ribbons

2 Copyright 2016 Lexmark. All rights reserved. Lexmark is a trademark of Lexmark International, Inc., registered in the U.S. and/or other countries. All other trademarks are the property of their respective owners. No part of this publication may be reproduced, stored, or transmitted in any form without the prior written permission of Lexmark.

3 Inhaltsverzeichnis 1 Einführung Aufbau des Ribbons Funktionsbeschreibung Events Steuerelemente per Event steuern Erstellen von Ribbon-Elementen Erstellen von Tabs Erstellen von Gruppen Erstellen von Steuerelementen Steuerelement-Typen Allgemeine Eigenschaften... 5 BeginGroup... 6 Enabled... 6 IconId... 6 Style... 6 TooltipText... 6 Visible... 7 Text... 7 Width Steuerelemente um Icons erweitern Steuerelement in die Schnellzugriffsliste einbinden Beispielmakro "ribbon.bas" Erweiterungen Ribbon-Icons aus Ressource laden Anhang s SAPERION Hauptmenü "Start" Menü "Ordner" Menü "Import" Menü "Erweitert" Menü "Design" Menü "Administration" Menü "Dokumentenkorb" Menü "Bearbeiten" Menü... 14

4 Best Practice - Programmierung von Ribbons 1 Einführung Die mit SAPERION 7 eingeführten Ribbons basieren auf Drittprogrammen der Firma Codejock Software. Sie werden in Form von ActiveX-Objekten (Codejock.*.ocx; im SAPERION Verzeichnis) zur Verfügung gestellt. Über die API-Schnittstelle haben Sie die Möglichkeit eigene Ribbons zu erzeugen und anzeigen zulassen. In diesem Best Practice Handbuch wird die Programmierung anhand einiger Beispiele beschrieben. 2 Aufbau des Ribbons Die Ribbons setzen sich aus Tabs (Registerkarten) zusammen, die aufgabenorientiert und entsprechend bestimmter Anwendungsszenarien gestaltet sind. Dies bedeutet, dass nur bestimmte Gruppen von Controls (Steuerelementen) relevant sind, wenn Objekte bestimmten Typs bearbeitet werden. Abb. 2 1: Aufbau des Ribbons Ein Ribbon enthält in der Regel folgende Elemente: Schnellzugriffsliste (Quick Access Toolbar) Diese Schnellzugriffsleiste ist individuell konfigurierbar und enthält beispielsweise häufig benutzte Befehle. Tabs (Registerkarten) Registerkarten dienen zur Strukturierung der Ribbon-Gruppen und können nur Gruppen enthalten. Gruppen Gruppen dienen zur Strukturierung der Ribbon-Controls und können nur Controls enthalten. Steuerelemente (Controls) Jedes Ribbon-Control (Steuerelement) ist einer bestimmten, kontextabhängigen Ribbon-Gruppe zugeordnet. Jedes Element im Ribbon hat eine fest definierte ID.! Bitte beachten Sie, dass Sie für selbst erstellte Elemente im Ribbon die ID selber vergeben müssen und dabei nur der ID- Bereich größer als vorgesehen ist. 1

5 3 3 Funktionsbeschreibung 3.1 Events Funktionsbeschreibung Damit bestimmte Funktionen ausgeführt werden, sobald der Rich Client Anwender ein Steuerelement betätigt, wird ein entsprechender Callback implementiert. Der Callback ist eine fest definierte Schnittstelle, deren Name bei der Erstellung des Menüobjekts festgelegt wird. Anhand der cmid können Sie festlegen, welche Aktion ausgeführt wird. Dabei entspricht die cmdid der ID des betätigten Ribbon-Controls. Beispiel Sub CallbackName( cmdid As Long, cmdstring As String, ocurrmask As Object ) Select Case cmdid Case ControlId MsgBox "Control: " & CStr(cmdId) & "was pressed!" Case Else MsgBox "Unknown command Id : " & CStr(cmdId) & "!" End Select End Sub 3.2 i Steuerelemente per Event steuern Ab SAPERION 7.1 SP4 werden Ribbons über ein OnRibbonEvent gesteuert. Da dies gegenüber der herkömmlichen Handhabung eine wesentliche Vereinfachung darstellt, empfehlen wir, diese ab SP4 anzuwenden. Das OnRibbonEvent ermöglicht es, das gesamte Ribbon-Handling in einer Methode zu behandeln. Zu diesem Zweck müssen Sie lediglich das Ribbon-Event mit einer eigenen Ribbon-Methode, die die Standard EventAPI vorweist, verknüpfen. Beispiel Function OnRibbonEvent( pre As Long, note As String ) As Boolean Pre = 0 : This value has no special meaning note = <form name>.<event name> Definieren Sie die Parameter form name: Name des aktuell aktiven Formulars. Ist kein Formular aktiv, ist gilt der Wert "Application". event name: Name des Events (siehe folgende Tabelle). Die folgende Tabelle listet alle verfügbaren Events auf: 2

6 4.1 Erstellen von Tabs OnRibbonEvents Event Beschreibung FormCreate Das Formular wird geöffnet. Bei diesem Event werden - abhängig von den Masken - die Steuerelemente angezeigt, die für die Maske und das eventuell aktive Element der Ergebnisliste gültig sind. FormSetFocus Das Formular erhält den Fokus. Bei diesem Event werden - abhängig von den Masken - die Steuerelemente angezeigt, die für die Maske und das eventuell aktive Element der Ergebnisliste gültig sind. FormKillFocus Das Formular verliert den Fokus. Die Steuerelemente dieser Maske werden deaktiviert bzw. versteckt. FormRefresh Die Ereignisliste eines Formulars wird aktualisiert. Bei diesem Event müssen die Steuerelemente der Ergebnisliste deaktiviert werden. FormClose Das Formular wird geschlossen. Die Steuerelemente dieser Maske werden deaktiviert bzw. versteckt. ItemSelect Eine Zeile der Ergebnisliste wird ausgewählt. Bei diesem Event werden - abhängig von den Masken - die Steuerelemente, die für das aktive Element der Ergebnisliste gültig sind, aktiviert. RibbonInit Der gesamte Ribbon wird aktualisiert. Alle eigenen Steuerelemente werden angezeigt. HINWEIS: Bitte prüfen Sie den Kontext der Masken. RibbonCreate Der Ribbon wird neu erzeugt. Bei diesem Event werden ein Menüobjekt sowie für jedes Steuerelement ein entsprechender Eintrag erzeugt. Zusätzlich wird der Ribbon um die gewünschten Tabs, Gruppen und Controls erweitert. 4 Erstellen von Ribbon-Elementen 4.1 Erstellen von Tabs Ein Tab wird anhand folgender Funktion hinzugefügt: Dim otab As Object Set otab = Application.Ribbon.InsertTab( Index, "TabName" ) Set otab = TabID Damit der hinzugefügte Tab später über die Suche wieder gefunden wird, weisen Sie diesem über die Eigenschaft otab.id = TabID eine eindeutige ID zu. 3

7 4 Erstellen von Ribbon-Elementen otab = Application.Ribbon.FindTab(TabID) 4.2 Erstellen von Gruppen Sie können eine Ribbon-Gruppe einem bestehenden SAPERION Tab oder einem eigenen Tab hinzufügen. In beiden Fällen wird das entsprechende Tabobjekt gebraucht. Hierbei bestehen zwei Möglichkeiten, eine Gruppe einem bestimmten Tab zuzuordnen: Funktion 1 Set ogroup = otab.groups.addgroup(gruppenname, GruppenID) Mit dieser Funktion wird eine Gruppe an der letzten Stelle des Tabs erstellt. Funktion 2 Set ogroup = otab.groups.insertgroup(index,gruppenname, GruppenID) Über diese Funktion können Sie anhand der Parameter zusätzlich steuern, an welcher Stelle die neue Gruppe innerhalb des Tabs hinzugefügt werden soll. 4.3 Erstellen von Steuerelementen Steuerelemente können einer beliebigen Gruppe zugeordnet werden. Mit der folgenden Funktion können Sie einem Gruppenobjekt das gewünschte Control hinzufügen: Set octl = ogrp.add(controltyp, ControlID, ControlName, Position) Der Parameter für die Position ist hier optional Steuerelement-Typen In der folgenden Übersicht sind alle in SAPERION eingesetzten Control-Typen aufgelistet. Steuerelement-Typen Steuerelement-Typ Beschreibung Button Button-Steuerelement: Durch Klicken der Schaltfläche wird ein Ereignis ausgelöst. Popup Steuerelement, das nur als Beschriftung und ohne Icon angezeigt wird. Beim Anklicken erscheint ein Menü mit weiteren Steuerelementen. Button Popup Steuerelement, das nur als Icon und ohne Beschriftung angezeigt wird. Beim Anklicken erscheint ein Menü mit weiteren Steuerelementen. Split Button Popup Steuerelement, das aus einem Button und einem Popup besteht. 4

8 4.3 Erstellen von Steuerelementen Steuerelement-Typ Beschreibung Edit Texteingabefeld Checkbox Checkbox-Steuerelement: Der Anwender kann eine Option auswählen oder deaktivieren. Eigenschaft Checked (Boolean) Public Property Checked() As Long Combobox Combobox-Steuerelement: Der Anwender kann eine Liste mit vorgegebenen Optionen öffnen und eine gewünschte daraus wählen. Eigenschaft AutoComplete: De-/aktiviert die automatische Vervollständigung Public Property AutoComplete() As Boolean Methoden AddItem: Mit dieser Methode wird ein Eintrag (String oder optional Integer) hinzugefügt. Public Sub AddItem( _ ByVal Text As String, _#Optional ByVal Index As Variant _) Public Sub AddItem( _ ByVal Text As String, _#Optional ByVal dex As VaClear: Mit dieser Methode werden alle Einträge gelöscht. Public Sub Clear() FindItem: Mit dieser Methode wird der erste Eintrag in der Combobox gefunden, der mit dem spezifizierten String beginnt. Public Function FindItem( _#ByVal Text As String _#) As Long Public Function FindItem( _#ByVal Text As String Text As String RemoveItem: Mit dieser Methode wird ein Eintrag aus der Conbobox gelöscht. Public Sub RemoveItem( _#ByVal nindex As Long _#) Public Sub RemoveItem( _#ByVal nindex As Radiobutton Radiobutton-Steuerelemente werden gruppiert, so dass der Anwender aus mehreren Optionen jeweils ein Optionsfeld auswählen kann Allgemeine Eigenschaften Im Folgenden sind Eigenschaften aufgelistet, die auf alle oben genannten Steuerelemente anwendbar sind. 5

9 Erstellen von Ribbon-Elementen BeginGroup Public Property BeginGroup() As Boolean Mit dieser Funktion wird vor dem Steuerelement ein Separator eingefügt Enabled Public Property Enabled() As Boolean Mit dieser Funktion wird das Steuerelement aktiviert (TRUE) bzw. deaktiviert (FALSE) IconId Public Property IconId() As Long Liest/ setzt den Icon ID des Steuerelements. Mit Hilfe des Icon ID können Sie das Icon, das mit dem Steuerelement dargestellt wird, beliebig austauschen, ohne den Control ID zu ändern Style Public Property Style() As Long Liest/ setzt den Stil des Steuerelements. 0 = automatische Anzeige 1 = nur die Überschrift wird angezeigt 2 = nur das Icon wird angezeigt 3 = die Beschriftung und das Icon werden angezeigt 4 = die Beschriftung wird unter dem Icon angezeigt TooltipText Public Property TooltipText() As String 6

10 4.3 Erstellen von Steuerelementen Liest/ setzt den Tooltip-Text für das Steuerelement Visible Public Property Visible() As Boolean Definiert, ob das Steuerelement sichtbar ist (TRUE) Text Public Property Text() As String Liest/ setzt den Text in der aktuellen Auswahl. Sie können den Text durch Ihren eigenen Text ersetzen Width Public Property Width() As Long Liest/ setzt die Größe (in Pixeln) des Elements Steuerelemente um Icons erweitern Sie können einem Steuerelement ein eigenes Icon zuweisen, indem Sie zunächst das gewünschte Icon zu der internen Verwaltung hinzufügen. omen.addicon <IconPfad,IconId> Anschließend kann dieses Icon einem Steuerelement direkt zugeordnet werden. octl.iconid = IconId Steuerelement in die Schnellzugriffsliste einbinden Es besteht auch die Möglichkeit, eigene Steuerelemente in die Schnellzugriffsliste hinzuzufügen. Dabei muss es sich nicht nur um Controls handeln, die bereits dem Ribbon hinzugefügt wurden. Wenn Sie ein Steuerelement in die Schnellzugriffsliste hinzufügen möchten, verwenden Sie folgende Funktion: octl = Application.Ribbon.QuickAccessControls.Add(ControlTyp, ControlID, ControlName, Position) 7

11 4 Erstellen von Ribbon-Elementen Um das hinzugefügte Steuerelement in der Schnellzugriffsliste wiederzufinden, wird folgende Funktion eingesetzt: octl = Application.Ribbon.QuickAccessControls.Find(0, ControlId) i Steuerelemnte, die sich in der Schnellzugriffsliste befinden, können nicht über die Funktion octl = Application.Ribbon.FindControl( 0, ControlId ) gefunden werden. Das gilt auch für Steuerelemente, die zusätzlich im Ribbon hinzugefügt wurden und die gleiche ID haben. 4.4 Beispielmakro "ribbon.bas" Mit der SAPERION Installation erhalten Sie standardmäßig ein Beispielmakro für die Programmierung von Ribbons. Die Datei "ribbon.bas" wird im Verzeichnis "...\Program Files (x86)\saperion\macros" abgelegt. Das Makro enthält beispielhaft einige Anwendungsfälle wie etwa das Erzeugen von neuen Tabs, neuen Gruppen, neue Controls und Icons oder Controls, die aktiv sind, wenn eine bestimmte Maske aktiv ist und ein Zeileneintrag der Ergebnisliste markiert ist Erweiterungen Folgende Erweiterungen werden durch "ribbon.bas" ausgeführt: Erweiterung des "Start"-Tabs um Controls Der "Start"-Tab wird um folgende vier Controls in einer bestehenden Gruppe erweitert: ein Button, der immer aktiv ist ein Button, der nur aktiv ist, wenn die Maske "example71_q" aktiv ist eine Checkbox, die aktiviert ist, wenn in der Maske "example71_q" eine Zeile der Ergebnisliste ausgewählt wird alle Elemente der Maske "example71_q" sind unsichtbar, wenn die Maske nicht aktiv ist Erweiterung des "Start"-Tabs um eine Gruppe Der "Start"-Tab wird um eine Gruppe erweitert, die immer sichtbar ist (auch wenn die Maske nicht aktiv ist). Diese enthält einen Button, der aktiv ist, wenn die Maske "example71_q" aktiviert wird. Hinzufügen eines neuen Tabs Ein neuer Tab wird nach dem "Start"-Tab erzeugt, der eine Gruppe mit einem Button enthält. Hier sind die Elemente immer sichtbar Ribbon-Icons aus Ressource laden Beim Laden der Ribbon-Icons können Sie direkt auf Ressourcen verweisen, d.h. der Pfad zu den Images muss nicht mehr angegeben werden. Beispiele 8

12 5.1 Icon aus der Ressource-Datei laden omen.addicon "!CustomLightRed16",ICON_BTN_FORM Icon "test.png" oder "test.bmp" aus dem "Image"-Verzeichnis laden omen.addicon "!Test",ICON_BTN_FORM 5 Anhang 5.1 s SAPERION Hauptmenü Ribbons ID - SAPERION Hauptmenü 5002 Fenster-Eigenschaften 1703 Fensterposition beim Beenden speichern 1704 Fensterposition jetzt speichern 1705 Gespeicherte Fensterposition löschen 1706 Titelzeile bearbeiten Layout zurücksetzen 1062 Ausgecheckte Dokumente Drucken Druckvorschau 5954 Dokument(e) 1221 Suchabfrage Protokolltabelle Aus Dokumentenkorb Suchabfrage Protokolltabelle Einstellungen Einstellungen 1304 OCR System Autokorrektur Stempel verwalten 1308 Aktuellen Benutzer... 9 s

13 Statuszeile anzeigen Records-Management 1333 Regeln Hilfe 1504 Hilfe verwenden Info Aktuellen Benutzer wechseln Beenden "Start" Menü Ribbons ID - "Start" 2258 Aktualisieren 2259 Zurücksetzen 1249 Zu Favoriten 1241 Exportieren Anzeigen 5953 Bearbeiten Annotationen bearbeiten 5955 Indexieren Struktur 1060 Auschecken 1059 Einchecken 1061 Verwerfen 5957 Löschen 46 Revisionen Speichern unter Senden 1072 Verknüpfung senden 1073 Als Kopie senden 1074 Kopie und Verknüpfung senden 1250 Dokumente zu Favoriten 1067 Verwendungsnachweis 5972 Zugriffslisten setzen Prozess starten Adhoc Prozess starten Anhang

14 Persönliche Templates 5993 Öffentliche Templates 3581 Historie Bemerkungen Delegieren Wiedervorlage Zurück legen 3587 Aufgaben "Ordner" Menü Ribbons ID - "Ordner" 4308 Aktualisieren 4300 Neuer Ordner 4301 Neue Anwendung Neuer Korb Ordner Löschen 4305 Zugriffsliste Klassen "Import" Menü Ribbons ID - "Import" 1054 Einzug Einzeln Seite ersetzen Scan-Profil 1339 Duplex 1000 Datei(en) Neue Seite Massendaten-Import COLD-Daten Gescannte Seiten Geladene Dateien s

15 Konfiguration 1300 Optionen Formatvorlage Eingang 1051 Dokumente 1052 Offen "Erweitert" Menü Ribbons ID - "Erweitert" 1218 Reader erzeugen Qualitäts-Sicherung Neu 1201 Laden Speichern Löschen Aktualisieren 1242 Zurück zur Maske "Design" Menü Ribbons ID - "Design" 1212 Erstellen Laden Bearbeiten Speichern als Löschen Dokumentformate Prozess-Designer Ereignisse Skripte Maske bearbeiten Suchmaske erstellen Indexmaske erstellen Drucklisten Anhang

16 Deckblätter Hintergrund-Formulare "Administration" Menü Ribbons ID - "Administration" 1329 Neuer Content-Typ Content-Typ bearbeiten Neue Aufbewahrungsklasse Aufbewahrungsklasse bearbeiten Verschlüsselung 1337 Lokalisierung Verwaltung Zugriffslisten Abfrage Maske 1226 Masken konfigurieren Einstellungen Exportieren "Dokumentenkorb" Menü Ribbons ID - "Dokumentenkorb" 2451 Ordnen 2450 Trennen 2454 Speichern unter 2455 Format 2456 Abschließen 1076 Senden 1206 Seite hinzufügen 1207 Alle hinzufügen 2460 Hoch 2461 Runter 2459 Rechts 2458 Links 13 s

17 Anzeigen 1110 Bearbeiten Benennen 2465 Löschen 2477 Alle Löschen 2467 Verschlüsseln 2466 Sicherheit 2471 Rendern 1210 Einzelnes Dokument 1211 Indexmaske Alle Dokumente 1233 Optionen Masken aktivieren Indexmaske 1208 Indexieren Automatisch indexieren Signatur erstellen Bearbeiten Verifizieren 2469 Löschen 2473 Fertigstellen 2474 Alle fertigstellen 2475 Massensignatur starten "Bearbeiten" Menü Ribbons ID - "Bearbeiten" 2013 vorheriges Dokument 2054 erste Seite 2011 vorherige Seite 2010 nächste Seite 2055 letzte Seite 2012 nächstes Dokument 2005 Größer 2006 Kleiner 2000 Anpassen 14 Anhang

18 Keine Automatische Skalierung 2082 Auf Seite anpassen 2083 Ganze Seite anpassen 2048 Vergrößern 2049 Verkleinern 2036 Vorheriger Link 1103 Einfügen 1101 Ausschneiden 1102 Kopieren 1100 Rückgängig 1104 Löschen 2014 Drehen Drehen Drehen Alles markieren 15 s