SAP Control Framework

Transcription

HELP.BCCIGOF
Release 4.6C
SAP AG
Copyright
© Copyright 2001 SAP AG. Alle Rechte vorbehalten.
Weitergabe und Vervielfältigung dieser Publikation oder von Teilen daraus sind, zu welchem
Zweck und in welcher Form
auch immer, ohne die ausdrückliche schriftliche Genehmigung durch SAP AG nicht gestattet. In
dieser Publikation enthaltene Informationen können ohne vorherige Ankündigung geändert
werden.
Die von SAP AG oder deren Vertriebsfirmen angebotenen Software-Produkte können SoftwareKomponenten auch anderer Software-Hersteller enthalten.
®
®
®
®
®
®
®
Microsoft , WINDOWS , NT , EXCEL , Word , PowerPoint und SQL Server sind eingetragene
Marken der
Microsoft Corporation.
®
®
®
®
®
®
®
®
®
IBM , DB2 , OS/2 , DB2/6000 , Parallel Sysplex , MVS/ESA , RS/6000 , AIX , S/390 ,
®
®
®
AS/400 , OS/390 und OS/400 sind eingetragene Marken der IBM Corporation.
®
ORACLE ist eine eingetragene Marke der ORACLE Corporation.
®
®
INFORMIX -OnLine for SAP und Informix Dynamic Server
Informix Software Incorporated.
®
®
®
TM
sind eingetragene Marken der
®
UNIX , X/Open , OSF/1 und Motif sind eingetragene Marken der Open Group.
®
HTML, DHTML, XML, XHTML sind Marken oder eingetragene Marken des W3C , World Wide
Web Consortium,
Massachusetts Institute of Technology.
®
JAVA ist eine eingetragene Marke der Sun Microsystems, Inc.
®
JAVASCRIPT ist eine eingetragene Marke der Sun Microsystems, Inc., verwendet unter der
Lizenz der von Netscape entwickelten und implementierten Technologie.
SAP, SAP Logo, R/2, RIVA, R/3, ABAP, SAP ArchiveLink, SAP Business Workflow, WebFlow,
SAP EarlyWatch, BAPI, SAPPHIRE, Management Cockpit, mySAP.com Logo und mySAP.com
sind Marken oder eingetragene Marken der SAP AG in Deutschland und vielen anderen Ländern
weltweit. Alle anderen Produkte sind Marken oder eingetragene Marken der jeweiligen Firmen.
2
April 2001
SAP AG
Symbole
Symbol
Bedeutung
Achtung
Beispiel
Empfehlung
Hinweis
Syntax
Tip
April 2001
3
SAP AG
Inhalt
SAP Control Framework................................................................................................ 6
Architektur des Control Frameworks ........................................................................................................ 8
Ereignisbehandlung .................................................................................................................................. 10
Registrieren und Verarbeiten von Ereignissen....................................................................................... 13
Kontextmenü .......................................................................................................................................... 15
Drag&Drop.............................................................................................................................................. 17
Ablauf einer Drag&Drop Operation ................................................................................................... 19
Ereignisse bei Drag&Drop................................................................................................................. 21
Beispiel für Drag&Drop-Programmierung ......................................................................................... 23
Drag&Drop im WAN-Umfeld ............................................................................................................. 28
Lifetime Management ................................................................................................................................ 29
Automation Queue..................................................................................................................................... 31
Synchronisation der Automation Queue................................................................................................. 33
Fehlerbehandlung bei der Synchronisation............................................................................................ 35
Services rund um die Automation Queue............................................................................................... 37
Verwendung von Controls im WAN ......................................................................................................... 42
Anlegen eines Controls am Beispiel des SAP Picture .......................................................................... 44
Methoden der Klasse CL_GUI_CFW ........................................................................................................ 46
dispatch ...................................................................................................................................................... 47
flush ............................................................................................................................................................ 48
get_living_dynpro_controls...................................................................................................................... 49
set_new_ok_code ...................................................................................................................................... 50
update_view ............................................................................................................................................... 51
Methoden der Klasse CL_GUI_OBJECT.................................................................................................. 52
is_valid........................................................................................................................................................ 53
free .............................................................................................................................................................. 54
Methoden der Klasse CL_GUI_CONTROL .............................................................................................. 55
constructor................................................................................................................................................. 56
finalize......................................................................................................................................................... 58
set_registered_events............................................................................................................................... 59
get_registered_events............................................................................................................................... 60
is_alive........................................................................................................................................................ 61
set_alignment............................................................................................................................................. 62
set_position................................................................................................................................................ 63
set_visible................................................................................................................................................... 64
get_focus.................................................................................................................................................... 65
set_focus .................................................................................................................................................... 66
get_height................................................................................................................................................... 67
get_width .................................................................................................................................................... 68
Methoden der Klasse CL_DRAGDROP.................................................................................................... 69
constructor................................................................................................................................................. 70
add............................................................................................................................................................... 71
4
April 2001
SAP AG
clear............................................................................................................................................................. 73
destroy........................................................................................................................................................ 74
get................................................................................................................................................................ 75
get_handle.................................................................................................................................................. 77
modify ......................................................................................................................................................... 78
remove ........................................................................................................................................................ 80
Methoden der Klasse CL_DRAGDROPOBJECT ..................................................................................... 81
set_flavor.................................................................................................................................................... 82
abort ............................................................................................................................................................ 83
April 2001
5
SAP AG
Einsatzmöglichkeiten
Das SAP-System erlaubt das Ansteuern von Desktop-Applikationen (Custom Controls) mit Hilfe
von ABAP. Die Applikationslogik läuft dabei auf dem R/3-Applikationsserver (Automation Client),
welcher die Custom Controls (Automation Server) am Frontend treibt.
Sollen am Frontend Custom Controls eingebunden werden, fungiert das SAP GUI
(SAPGUI.APPLICATION) als Container für diese. Custom Controls können dabei ActiveX
Controls und JavaBeans sein.
Das folgende Beispiel zeigt ein SAP Tree Control in Kombination mit einem SAP TextEdit
Control:
Funktionsumfang
Das beschriebene Framework unterstützt Controls (ActiveX und JavaBeans), die innerhalb des
SAP GUI dargestellt werden.
Aus Sicht des Automation Controllers wird hierbei immer nur mit genau einem Control
(SAPGUI.APPLICATION) - dem Automation Controller - kommuniziert, das selbst als Container
für die Custom Controls dient.
Die Steuerung des Automation Controllers aus ABAP geschieht über die Klassen CL_GUI_CFW,
CL_GUI_OBJECT und CL_GUI_CONTROL, die das Erzeugen und Zerstören von Custom
6
April 2001
SAP AG
Controls als auch das Setzen und Lesen von deren Eigenschaften und den Aufruf derer
Methoden ermöglichen.
Mit Blick auf die Performance in Client-Server-Umgebungen werden Puffermechanismen über
die Automation Queue unterstützt, mit der eine Serie von Methodenaufrufen zu
unterschiedlichen Instanzen von Custom Controls in einem Kommunikationsschritt zum Frontend
geschickt werden kann.
Die Interpretation von Ereignissen, die auf einem Custom Control ausgelöst werden, erfolgt in
zwei Schritten:
•
Ausfiltern der nicht relevanten Ereignisse
•
Weiterreichen der relevanten Ereignisse an den Applikationsserver. Ihr ABAP-Programm
erhält dann an definierter Stelle über ein OO-Ereignis die Kontrolle und kann auf das Ereignis
reagieren.
Die Lebensdauer eines Controls wird über das Lifetime Management geregelt. Es baut Controls
automatisch am Frontend ab. Natürlich wird auch ein explizites Abbauen von Controls durch das
Applikationsprogramm unterstützt.
Einschränkungen
Bestimmte Methoden und Ereignisse in einigen Controls werden nicht unter dem SAP GUI for
HTML unterstützt. Andere stehen nur in eingeschränkter Form zur Verfügung. Einzelheiten
hierzu entnehmen Sie der Dokumentation zum jeweiligen Control.
April 2001
7
SAP AG
Architektur des Control Frameworks
Das SAP-System erlaubt das Ansteuern von Desktop-Applikationen (Custom Controls) mit Hilfe
von ABAP. Der Applikationsserver ist der Automation Client, welcher die Custom Controls
(Automation Server) am Frontend treibt. Das SAP GUI (SAPGUI.APPLICATION) dient als
Container für die Custom Controls.
In der folgenden Grafik sind die beteiligten Elemente und ihre Kommunikationskanäle dargestellt:
SAPGUI
Automation
Controller
Ereignisse
Custom Control 1
Instanzen
Automation Queue
OK_CODE
OO Control
Framework
Custom Control 2
GUI-RFC
Automation Queue
Ereignisse
Applikationsprogramm
Instanzen
Applikationsserver
Automation Controller
Der Automation Controller ist die zentrale Instanz auf dem Frontend. Er verwaltet alle Instanzen
der Custom Controls.
Weiterhin enthält der Automation Controller eine Liste der relevanten Ereignisse, die von einem
Custom Control ausgelöst werden können (siehe Ereignisbehandlung [Seite 10]).
Die gesamte Kommunikation zwischen den Controls am Frontend und dem
Applikationsprogramm am Backend läuft über den Automation Controller.
OO Control Framework
Analog zum Automation Controller existiert am Backend das OO Control Framework. Alle
Methodenaufrufe aus einem Applikationsprogramm an ein Custom Control laufen über das
Control Framework. Damit nicht bei jedem Methodenaufruf eine Verbindung zum Frontend
aufgebaut werden muß, werden die Methodenaufrufe in der Automation Queue gepuffert. Erst
beim Synchronisationspunkt wird dann die Automation Queue mit dem Frontend synchronisiert
(Siehe Automation Queue [Seite 31]).
8
April 2001
SAP AG
Das Control Framework besitzt wie auch der Automation Controller eine Liste der relevanten
Control-Ereignisse. In dieser Liste sind zusätzlich die aufzurufenden Behandlermethoden
hinterlegt (siehe Ereignisbehandlung [Seite 10]).
Auch eine Liste der angelegten Control-Instanzen wird im Control Framework gehalten. Diese
Liste dient auch als Grundlage für das Lifetime Management der Controls (siehe Lifetime
Management [Seite 29]).
April 2001
9
SAP AG
Ereignisbehandlung
Ereignisbehandlung
Verwendung
Der Benutzer eines Applikationsprogramms kann Ereignisse auf Custom Controls auslösen. Das
Applikationsprogramm bekommt dann die Kontrolle und kann auf das Ereignis reagieren.
Typische Ereignisse sind z.B. Doppelklick und Drag & Drop.
Integration
Wie in Architektur des Control Frameworks [Seite 8] angedeutet, besitzt sowohl der Automation
Controller als auch das OO Control Framework eine Tabelle aller relevanten Control-Ereignisse.
Diese Tabellen müssen vom Applikationsprogramm aufgebaut werden. Die Ereignistabelle am
Frontend besteht aus Control-Instanz und Ereignis, am Backend enthält die Ereignistabelle
zusätzlich die ABAP-Behandlermethode für die Ereignisse.
Der Aufbau der Tabellen erfolgt über eine spezielle Methode des OO Control Frameworks
(control->set_registered_events). Bei der Registrierung des Ereignisses muß die
Applikation festlegen, ob das Ereignis als Systemereignis oder als Applikationsereignis
interpretiert werden soll:
•
Systemereignis: Dieses Ereignis wird ausgelöst, bevor die automatische Feldprüfung (z.B.
Mußeingabe) und der Feldtransport durchgeführt werden. Auch PAI und PBO werden nicht
durchlaufen. Daher haben Sie keinerlei Zugriff auf aktuell auf dem Dynpro veränderte Werte.
Es findet auch nach dem Ereignis kein Feldtransport mehr zu dem Dynpro statt. Daher
werden Werte, die Sie aufgrund des Ereignisses verändert haben, nicht auf dem Dynpro
aktualisiert.
Die zum Ereignis definierte Behandlermethode wird automatisch vom System
aufgerufen. Mit der Methode set_new_ok_code [Seite 50] haben Sie allerdings die
Möglichkeit, PAI und PBO auszulösen und einen OK_CODE zu setzen, den Sie dann in
einem PAI-Modul interpretieren können.
•
Applikationsereignis: Das Ereignis wird zum Zeitpunkt PAI verarbeitet. Daher wurden alle
Feldprüfungen durchgeführt, und auch der Feldtransport hat stattgefunden. Sofern Sie die
Behandlermethode an einer bestimmten Stelle Ihres Applikationsprogramms aufrufen wollen,
müssen Sie das Ereignis mit der statischen Methode CL_GUI_CFW=>DISPATCH auswerten.
Zum Festlegen der Behandlermethode eines Ereignisses muß das Applikationsprogramm über
das ABAP-Sprachelement SET HANDLER eine Behandlermethode registrieren. Die
Behandlermethode muß in dem Applikationsprogramm als Methode einer (lokalen) Klasse
angelegt werden. Es steht Ihnen frei, die Behandlermethode als Instanzmethode oder statische
Methode anzulegen.
10
April 2001
SAP AG
Ereignisbehandlung
SAPGUI
Ereignisse:
Ereignis
Control
DoppelKlick Control
OO-Control Framework
Ereignisse:
Ereignis
Control
DoppelKlick Control
Behandler
DoppelKlick
Control
CALL METHOD
control->set_registered_events
SET HANDLER handler->DoppelKlick
FOR control.
Applikationsserver
Funktionsumfang
Wird auf einem Custom Control ein Ereignis ausgelöst, überprüft der Automation Controller, ob
dieses Ereignis in seiner Tabelle registriert wurde. Wurde das Ereignis nicht registriert, wird das
Ereignis vom Automation Controller ignoriert. Wurde es dagegen registriert, generiert der
Automation Controller einen OK_CODE, der an das OO Control Framework weitergeleitet wird.
Je nach Art des Ereignisses wird dann entweder direkt (bei einem Systemereignis) oder nach
Aufruf der statischen Methode CL_GUI_CFW=>DISPATCH (bei einem Applikationsereignis) die
zum Ereignis registrierte Behandlermethode aufgerufen. Dabei wird über den Ereignisparameter
sender die Objektreferenz des Controls, welches das Ereignis ausgelöst hat, an die
Behandlermethode übergeben.
Die statische Methode CL_GUI_CFW=>DISPATCH muß zur Auswertung von
Applikationsereignissen innerhalb der PAI-Module aufgerufen werden.
Der OK_CODE eines Ereignisses wird durch den Aufruf der Methode
CL_GUI_CFW=>DISPATCH "verbraucht". Daher führt ein zweiter Aufruf der Methode
nicht zu einem erneuten Anspringen der Behandlermethode.
Über den Parameter RC der Methode CL_GUI_CFW=>DISPATCH [Seite 47]
erhalten Sie Informationen, ob das Ereignis erfolgreich an eine Behandlermethode
weitergeleitet werden konnte.
April 2001
11
SAP AG
Ereignisbehandlung
SAPGUI
Ereignisse:
Ereignis
Control
DoppelKlick Control
Ereignis
DoppelKlick
des Controls
Control
Control
OO-Control Framework
Ereignisse:
CLASS lcl_handler IMPLEMENTATION.
METHOD DoubleKlick.
* DO SOMETHING
ENDMETHOD.
ENDCLASS.
Ereignis
Control
DoppelKlick Control
Behandler
DoppelKlick
Applikationsserver
12
April 2001
SAP AG
Registrieren und Verarbeiten von Ereignissen
Über den Ereignismechanismus des Control Frameworks können Sie in Ihrem Programm in
Behandlermethoden auf Ereignisse reagieren, die auf dem Control ausgelöst wurden (z.B.
Doppelklick).
Voraussetzungen
Der Ablauf wurde allgemeingültig für alle Custom Controls gehalten. Control-spezifische
Informationen finden Sie in der jeweiligen Dokumentation zu der Control-Verschalung.
Ablauf
1. Es wird davon ausgegangen, daß Sie mit einem Custom Control mit der Verschalung
cl_gui_xyz arbeiten:
DATA my_control TYPE REF TO cl_gui_xyz.
Anmelden von Ereignissen beim Control Framework
2. Definieren Sie eine interne Tabelle (Typ cntl_simple_events) und einen
dazugehörenden Arbeitsbereich (Typ cntl_simple_event).
DATA events TYPE cntl_simple_events.
DATA wa_events TYPE cntl_simple_event.
3. Füllen Sie nun die Ereignistabelle mit den relevanten Ereignissen. Dazu benötigen Sie die
Identifikation des Ereignisses (event_id). Diese Information finden Sie wiederum in der
Klassenbibliothek in den Attributen der Klasse cl_gui_xyz. Weiterhin müssen Sie sich
entscheiden, ob das Ereignis als Systemereignis (appl_event = ' ') oder als
Applikationsereignis (appl_event = 'X') definiert werden soll.
wa_events-eventid = event_id.
wa_events-appl_event = appl_event.
APPEND wa_events TO events.
4. Im nächsten Schritt muß die Ereignistabelle an das Frontend geschickt werden, damit die
relevanten Ereignisse vom Frontend an das Backend weitergeleitet werden.
CALL METHOD my_control->set_registered_events
events = events.
Um auf ein Ereignis Ihres Custom Controls eingehen zu können, müssen Sie nun noch eine
Behandlermethode angeben. Die Behandlermethode kann eine Instanzmethode oder eine
statische Methode sein:
Behandlung des Ereignisses als Instanzmethode
5. Definieren Sie die (lokale) Klassendefinition für den Ereignisbehandler. Dabei legen Sie den
Namen der Ereignisbehandlermethode fest (Event_Handler). Als Information müssen Sie
sich in der Klassenbibliothek für die Klasse des Custom Controls cl_gui_xyz den Namen
des Ereignisses (event_name) und die zu diesem Ereignis gehörenden Ereignisparameter
(event_parameter) besorgen. Der Ereignisparameter sender wird bei jedem Ereignis zur
April 2001
13
SAP AG
Verfügung gestellt. Der Parameter enthält die Referenz des Controls, das dieses Ereignis
ausgelöst hat.
CLASS lcl_event_receiver DEFINITION.
PUBLIC SECTION.
METHODS Event_Handler
FOR EVENT event_name OF cl_gui_xyz
IMPORTING event_parameter
sender.
ENDCLASS.
6. Melden Sie jetzt noch für die registrierten Ereignisse Behandlermethoden beim OO Control
Framework an.
DATA event_receiver TYPE REF TO lcl_event_receiver.
CREATE OBJECT event_receiver.
SET HANDLER event_receiver->Event_Handler
FOR my_control.
Registrieren als statische Methode
7. Definieren Sie die (lokale) Klassendefinition für den Ereignisbehandler. Dabei legen Sie den
Namen der statischen Ereignisbehandlermethode fest (Event_Handler). Als Information
müssen Sie sich in der Klassenbibliothek für die Klasse des Custom Controls cl_gui_xyz
den Namen des Ereignisses (event_name) und die zu diesem Ereignis gehörenden
Ereignisparameter (event_parameter) besorgen.
CLASS lcl_event_receiver DEFINITION.
PUBLIC SECTION.
CLASS-METHODS Event_Handler
FOR EVENT event_name OF cl_gui_xyz
IMPORTING event_parameter
sender.
ENDCLASS.
8. Melden Sie jetzt noch für die registrierten Ereignisse Behandlermethoden beim OO Control
Framework an.
SET HANDLER lcl_event_receiver=>Event_Handler
FOR my_control.
Verarbeiten von Control-Ereignissen
9. Wie Sie auf ein Ereignis reagieren wollen, legen Sie im Implementierungsteil der
Behandlermethode fest.
CLASS lcl_event_receiver IMPLEMENTATION.
METHOD Event_Handler.
* Abarbeitung des Ereignisses
ENDMETHOD.
ENDCLASS.
10. Je nach Art des Ereignisses (System- oder Applikationsereignis) müssen Sie jetzt noch die
Methode CL_GUI_CFW=>DISPATCH aufrufen. Lesen Sie dazu Ereignisbehandlung [Seite
10].
14
April 2001
SAP AG
Kontextmenü
Kontextmenü
Kontextmenüs werden im SAP GUI for HTML nicht unterstützt.
Verwendung
Das Kontextmenü (Rechte Maustaste, SHIFT F10) ermöglicht das Anzeigen von
kontextsensitiven Menüs. Der Kontext wird über den Ort definiert, an dem der Benutzer das
Kontextmenü aufgerufen hat
Der Benutzer kann über das Kontextmenü Funktionen auswählen, die für den aktuellen Kontext
relevant sind.
Funktionsumfang
Soll auf einem Custom Controls ein Kontextmenü implementiert werden, muß das Ereignis für
das Anfordern eines Kontextmenüs (Ereignis context_menu) registriert werden. Das Ereignis
für das Auswählen eines Eintrags des Kontextmenüs (Ereignis context_menu_selected) wird
entweder von der Control-Verschalung automatisch registriert (z.B. SAP Tree) oder muß explizit
registriert werden (z.B. SAP Picture).
Fordert der Benutzer auf einem Objekt ein Kontextmenü an, wird über den normalen
Ereignismechanismus [Seite 10] das Anwendungsprogramm aufgerufen. In der
Ereignisbehandlermethode zum Ereignis context_menu erhält das Programm als
Ereignisparameter eine Menüreferenz. Das Programm benutzt diese Menüreferenz, um das
anzuzeigende Menü aufzubauen. Dabei können mit dem Menu Painter definierte Menüs oder
dynamisch aufgebaute Menüs benutzt werden. Nach Verlassen der Ereignisbehandlermethode
wird das Kontextmenü automatisch angezeigt.
Das SAP Picture bildet eine Ausnahme. Hier bekommen Sie keine Menüreferenz als
Ereignisparameter übergeben.
Wird eine Menüfunktion des Kontextmenüs ausgewählt, wird wiederum ein Ereignis ausgelöst,
das an das Applikationsprogramm übergeben wird. Auch auf dieses Ereignis muß die Applikation
eine Behandlermethode registrieren. In der Behandlermethode wird der übergebene
Funktionscode ausgewertet, der über einen Ereignisparameter übergeben wird.
Aktivitäten
•
Die Applikation registriert sich mit der Methode set_registered_events [Seite 59] auf das
Ereignis context_menu und auf das Ereignis context_menu_selected. Die
Identifikation des Ereignisses ist von der jeweiligen Control-Verschalung abhängig und wird
in der dazugehörigen Dokumentation beschrieben.
•
Weiterhin muß die Applikation Methoden zur Ereignisbehandlung der beiden Ereignisse
definieren.
April 2001
15
SAP AG
Kontextmenü
Der SAP Tree bildet eine Ausnahme bei der Registrierung der Ereignisse. Hier muß
nur das Ereignis context_menu registriert werden. Das Ereignis
context_menu_selected wird automatisch von der Control-Verschalung
mitregistriert.
Aufbau des Kontextmenüs
In der Implementierung der Behandlermethode für das Ereignis context_menu muß das Menü
dem Control zugeordnet werden. Dabei muß eventuell nachgeprüft werden, in welchem Kontext
das Kontextmenü aufgerufen wurde.
Der Aufbau des Kontextmenüs erfolgt über die Klasse CL_CTMENU. Bei fast allen ControlVerschalungen bekommen Sie als Ereignisparameter des Ereignisses context_menu ein
Objekt auf das anzuzeigende Menü geliefert. Ist dies nicht der Fall (z.B. beim SAP Picture),
müssen Sie ein Objekt der Klasse CL_CTMENU erzeugen.
Auf das Kontextmenü-Objekt können Sie folgende Methoden anwenden:
Methode
Bedeutung
LOAD_GUI_STATUS
Laden eines im Menu Painter vordefinierten Kontextmenüs (siehe
unten)
ADD_FUNCTION
Hinzufügen einer Funktion
ADD_MENU
Hinzufügen eines im Menu Painter definierten Menüs
ADD_SUBMENU
Hinzufügen eines im Menu Painter definierten Menüs als Submenü
ADD_SEPARATOR
Hinzufügen einer Trennlinie
RESET
Zurücksetzen auf Initialwert
HIDE FUNCTIONS
Ausblenden einer Funktion
SHOW_FUNCTIONS
Einblenden einer Funktion
DISABLE_FUNCTIONS
Deaktivieren einer Funktion
ENABLE_FUNCTIONS
Aktivieren einer Funktion
Nach dem Verlassen der Ereignisbehandlermethode wird das Kontextmenü automatisch
angezeigt. Ausnahmen bilden hier das SAP Picture Control und das SAP Toolbar Control. Bei
diesen muß das Kontextmenü explizit über die Methode display_context_menu [Extern] zur
Anzeige gebracht werden.
Auswerten des Funktionscodes
Die Interpretation des ausgewählten Menüpunktes erfolgt in der Behandlermethode zum Ereignis
context_menu_selected. Über den Funktionscode wird das ausgewählte Menü identifiziert
und eine entsprechende Reaktion ausgeführt.
16
April 2001
SAP AG
Drag&Drop
Drag&Drop
Verwendung
Mit Drag&Drop kann der Anwender Objekte aus einem Bereich eines Custom Controls (Quelle)
markieren und auf einen anderen Bereich eines Custom Controls (Ziel) fallen lassen. Je nach
Objekt wird dann im zweiten Bereich eine Aktion ausgeführt. Quelle und Ziel können dabei das
gleiche Control oder zwei unterschiedliche Controls sein.
Voraussetzungen
Damit Controls Drag&Drop-fähig sind, muß die Control-Verschalung zusätzliche Drag&DropEreignisse anbieten. Das Anwendungsprogramm muß für diese Ereignisse Behandlerroutinen
implementieren. Die Registrierung auf die Ereignisse erfolgt automatisch über die jeweilige
Control-Verschalung.
Funktionsumfang
Für jedes beteiligte Custom Control wird das Drag&Drop-Verhalten festgelegt. Je nach Control
wird das Verhalten auf alle Elemente des Controls bezogen (z.B. Editor), oder man kann für
jedes Teilobjekt ein eigenes Verhalten definieren (z.B. Tree). Jedes Verhalten besteht aus einer
oder mehreren Beschreibungen.
Die Beschreibung hat folgende Attribute:
•
DragSrc: Objekt ist Quelle eines Drag&Drop-Vorgangs
•
DropTarget: Objekt ist Ziel eines Drag&Drop-Vorgangs
•
Flavor: Der Flavor beschreibt den Typ einer Drag&Drop-Beschreibung. In einer Drag&DropSituation können Objekte nur in andere fallengelassen werden, wenn sie mindestens eine
gemeinsame Beschreibung besitzen.
•
Effect: Beschreibung, ob die Daten beim Drag&Drop-Vorgang kopiert und/oder verschoben
werden können
•
Effect_In_Ctrl: Mit welchem Drop-Effekt können Daten innerhalb des gleichen Controls
verschoben oder kopiert werden.
Sobald ein Drag-Ereignis ausgelöst wird, muß die Applikation in der entsprechenden
Behandlermethode feststellen, welches Objekt von dem Ereignis betroffen ist.
Weiterhin muß für das Drop-Ereignis implementiert werden, welche Aktionen durchgeführt
werden sollen. Die Aktionen sind dabei in der Regel abhängig von dem Objekt, das in das
Control fallengelassen wurde.
Wurden einem Objekt mehrere Flavors zugeordnet, muß zu einem speziellen Ereignis festgelegt
werden, welcher Flavor benutzt werden soll.
Nachdem das Drop-Ereignis abgeschlossen ist, können in einem zusätzlichen Ereignis weitere
Aktionen durchgeführt werden. Dieses Ereignis bietet sich insbesondere beim Verschieben des
Quellobjekts an, um dieses aus der Quelle zu löschen.
April 2001
17
SAP AG
Drag&Drop
Aktivitäten
Wenn die Drag&Drop-Funktionalität benutzt wird, sollte auf jeden Fall auch eine UNDO-Funktion
bereitgestellt werden, sofern die Drag&Drop-Funktion zu einem Verschieben des Objekts führt.
Diese muß von der Anwendung implementiert werden.
18
April 2001
SAP AG
Ablauf einer Drag&Drop Operation
Voraussetzungen
Im folgenden wird aufgezeigt, wie die Drag&Drop Operation abläuft. Dabei wird auf die Rolle des
Applikationsservers und des Frontends eingegangen. Aus diesem Ablauf leiten sich dann die
einzelnen Schritte ab, die in einem Anwendungsprogramm durchgeführt werden müssen, damit
Drag&Drop genutzt werden kann.
Ablauf
Applikationsserver
1. Sie erzeugen die Custom Controls [Seite 44].
2. Sie registrieren sich auf die Drag&Drop-Ereignisse [Seite 21].
3. Sie definieren das Drag&Drop-Verhalten für die einzelnen Custom Controls bzw. für deren
Teilobjekte. Dazu erzeugen Sie eines Instanz [Seite 70] der Klasse CL_DRAGDROP [Seite
69]. Dieser Instanz weisen Sie einen oder mehrere Flavors zu [Seite 71], die das Drag&DropVerhalten des entsprechenden Custom Controls beschreiben. Sie können diese Flavors
während des Programmablaufs auch noch verändern [Seite 78], löschen [Seite 80], abfragen
[Seite 75] oder auch die gesamte Instanz initialisieren [Seite 73] oder zerstören [Seite 74].
4. Die Zuweisung der Flavors an das Custom Control erfolgt über control-spezifische
Methoden. Lesen Sie dazu die jeweilige Control-Dokumentation.
Frontend
Die nachfolgenden Schritte führt das System automatisch durch. Sie dienen nur zum Verständnis
des Drag&Drop-Vorgangs.
5. Nachdem der Benutzer mit der linken Maustaste ein Objekt ausgewählt hat, startet der
Drag&Drop-Service.
6. Der Drag&Drop-Service überprüft, ob für das Objekt ein Drag&Drop-Verhalten definiert
wurde und ob darin die Fähigkeit des Objekts für Drag definiert wurde (Attribut DragSource).
7. Wurde das Attribut DragSource entsprechend gesetzt, wird das Drag&Drop gestartet. Der
Mauszeiger verändert sich dann automatisch.
8. Während der Benutzer die linke Maustaste gedrückt hält, wird ständig unter dem Mauszeiger
nachgefragt, ob sich dort ein Objekt in einem Custom Control befindet, das Drop-fähig ist
(Attribut DropTarget), und ob der Flavor dieses Objekts mit dem Flavor der Quelle
übereinstimmt. Ist dies der Fall, wird dem Benutzer dies über eine Veränderung des
Mauszeigers signalisiert.
9. Läßt der Benutzer nun das Objekt fallen, wird dies über ein Ereignis an den
Applikationsserver gemeldet.
Für das Frontend ist damit die Drag&Drop Operation abgeschlossen. Bisher wurden
noch keinerlei Veränderungen an den Inhalten der Custom Controls vorgenommen.
April 2001
19
SAP AG
Applikationsserver
10. Der Drag&Drop-Service des Applikationsservers erzeugt eine Instanz der Klasse
CL_DRAGDROPOBJECT [Seite 81]. Diese Instanz (z.B. drag_drop_object) steht Ihnen
in allen Ereignissen des Drag&Drop-Vorgangs als Ereignisparameter zur Verfügung und
dient zum Übermitteln des Kontexts zwischen den Ereignissen.
11. Der Drag&Drop-Service prüft nach, ob das Drag-Objekt und das Drop-Objekt mehrere
Flavors gemeinsam besitzen. Ist dies der Fall, wird das Ereignis ONGETFLAVOR ausgelöst. In
der dazugehörigen Behandlerroutine muß nun die Applikation entscheiden, welcher Flavor
verwendet werden soll. Dazu steht die Methode set_flavor [Seite 82] zur Verfügung.
12. Nun wird das Drag&Drop-Ereignis ONDRAG ausgelöst. Über Ereignisparameter erhalten Sie
die relevanten Informationen, welches Objekt der Benutzer gezogen hat. Innerhalb der
Behandlerroutine müssen Sie jetzt die in 9. angelegte Instanz des Drag&Drop-Datenobjekts
mit dem Kontext (Informationen über das Quellobjekt) versorgen:
drag_drop_object->object = mydragobject.
13. Als nächstes wird das Ereignis ONDROP ausgelöst. Aufgabe dieser Methode ist das
Verarbeiten des Drag&Drop-Datenobjekts. Hier müssen Sie implementieren, welche
Änderungen in dem Zielobjekt aufgrund des Drag&Drop-Vorgangs vorgenommen werden
sollen.
14. Das letzte Ereignis des Drag&Drop-Vorgangs ist ONDROPCOMPLETE. Hier sollte eventuell
eine Nachbearbeitung des Drag&Drop-Datenobjekts erfolgen. Besonders für den Fall einer
Verschiebeoperation sollte zu diesem Zeitpunkt das Quellobjekt aus dem DragSource
Control und den entsprechenden Datenstrukturen entfernt werden.
In Beispiel für Drag&Drop-Programmierung [Seite 23] finden Sie ein Beispiel, das
einen Drag&Drop-Vorgang zwischen einem SAP Tree und einem SAP TextEdit
beschreibt.
20
April 2001
SAP AG
Ereignisse bei Drag&Drop
Im folgenden Abschnitt werden nur die allgemeingültigen Eigenschaften der Ereignisse bei
Drag&Drop beschrieben. Diese können von den einzelnen Control-Verschalungen angereichert
werden. Daher sollten Sie auf jeden Fall auch in der Dokumentation zur jeweiligen ControlVerschalung die Besonderheiten des Controls nachlesen.
Verwendung
Im Umfeld des Drag&Drop gibt es vier Standardereignisse, bei denen Sie die Kontrolle in Ihrem
Applikationsprogramm bekommen können. In den Behandlerroutinen zu diesen Ereignissen
implementieren Sie, welche Aktionen bei einem Drag&Drop-Vorgang durchgeführt werden.
Bestimmte Control-Verschalungen können zusätzliche Drag&Drop-Ereignisse
anbieten. Hinweise dazu finden Sie in der jeweiligen Dokumentation.
Voraussetzungen
Um auf die Ereignisse reagieren zu können, müssen Sie sich auf sie registrieren. Im Gegensatz
zu der normalen Ereignisbehandlung werden aber die Ereignisse nicht mit der Methode
set_registered_events [Seite 59] am Control Framework angemeldet. Die Registrierung erfolgt
automatisch über die Verschalung des eingesetzten Custom Controls.
Sie müssen aber weiterhin Behandlermethoden für die Ereignisse angeben:
DATA tree TYPE REF TO cl_gui_simple_tree.
SET HANDLER dragdrop=>on_drag FOR tree.
Die Ereignisse werden immer als Systemereignisse angemeldet.
Funktionsumfang
Das Control Framework reicht beim Drag&Drop erst zum Drop-Zeitpunkt ein Ereignis an den
Applikationsserver weiter. Dieses wird dann am Applikationsserver, wie in Ablauf einer
Drag&Drop-Operation [Seite 19] beschrieben, innerhalb eines Drag&Drop-Vorgangs in maximal
vier Standardereignisse auseinandergesteuert. Alle Ereignisse haben ein Drag&DropDatenobjekt als Ereignisparameter. Über diesen Parameter müssen Sie den Kontext des
Drag&Drop-Vorgangs verwalten. Weiterhin übergibt Ihnen die jeweilige Control-Verschalung
weitere Informationen zu dem Drag&Drop-Kontext. Lesen Sie dazu die Dokumentation der
Control-Verschalung.
•
ONGETFLAVOR: Dieses Ereignis wird nur dann ausgelöst, wenn das Quellobjekt und das
Zielobjekt über mehrere gemeinsame Flavors verfügen. Sie müssen dann in der
Behandlermethode einen der gemeinsamen Flavors auswählen. Wenden Sie dazu die
Methode set_flavor [Seite 82] auf das Drag&Drop-Datenobjekt an.
Das Ereignis wird von dem Zielobjekt des Drag&Drop-Vorgangs ausgelöst.
•
ONDRAG: Dieses Ereignis wird immer dann ausgelöst, wenn der Drag&Drop-Vorgang am
Frontend beendet ist. In diesem Ereignis müssen Sie den Kontext des Quellobjekts
bestimmen. Diesen Kontext übergeben Sie dann an die als Ereignisparameter übergebene
Instanz der Klasse CL_DRAGDROPOBJECT.
Das Ereignis wird von dem Quellobjekt des Drag&Drop-Vorgangs ausgelöst.
April 2001
21
SAP AG
•
ONDROP: Zu diesem Ereignis definieren Sie die Aktionen, die im Zielobjekt durchgeführt
werden sollen. Dabei nutzen Sie den Ereignisparameter für den Kontext, den Sie zum
Ereignis ONDRAG gefüllt haben. Bei diesem Ereignis ist folgendes zu beachten:
−
Innerhalb des ONDROP-Ereignisses muß ein dynamischer TypeCast durchgeführt
werden. Die mögliche Ausnahme des TypeCast muß auf jeden Fall abgefangen werden.
Falls ein nicht passendes Objekt zugewiesen werden sollte, muß in der
Ausnahmebehandlung die Drag&Drop-Verarbeitung mit der Methode abort [Seite 83]
abgebrochen werden.
−
Die verwendeten Flavors sollten so gewählt werden, daß eine Zuordnung des
Drag&Drop-Objekts zu dem richtigen TypeCast möglich ist.
Das Ereignis wird von dem Zielobjekt des Drag&Drop-Vorgangs ausgelöst.
•
22
ONDROPCOMPLETE: Sofern Sie zum Abschluß des Drag&Drop-Vorgangs noch weitere
Aktionen durchführen wollen, können Sie dies in diesem Ereignis realisieren. Dies ist z.B. im
Falle einer Verschiebeoperation sinnvoll.
Das Ereignis wird von dem Quellobjekt des Drag&Drop-Vorgangs ausgelöst.
April 2001
SAP AG
Beispiel für Drag&Drop-Programmierung
Das Beispielprogramm geht von einem SAP Simple Tree Control und einem SAP TextEdit
Control aus. Von dem Tree Control soll eine Verschiebefunktion von Texten in das TextEdit
Control möglich sein.
Sie finden das Beispiel unter dem Namen RSDEMO_DRAG_DROP_EDIT_TREE.
*&-------------------------------------------------------------------*
*& Report RSDEMO_DRAG_DROP_EDIT_TREE
*&
*--------------------------------------------------------------------*
REPORT rsdemo_drag_drop_edit_tree
.
DATA ok_code TYPE sy-ucomm.
DATA node_itab LIKE node_str OCCURS 0.
DATA node LIKE node_str.
DATA container TYPE REF TO cl_gui_custom_container.
DATA splitter TYPE REF TO cl_gui_easy_splitter_container.
DATA right TYPE REF TO cl_gui_container.
DATA left TYPE REF TO cl_gui_container.
DATA editor TYPE REF TO cl_gui_textedit.
DATA tree TYPE REF TO cl_gui_simple_tree.
DATA behaviour_left TYPE REF TO cl_dragdrop.
DATA behaviour_right TYPE REF TO cl_dragdrop.
DATA handle_tree TYPE i.
*--------------------------------------------------------------------*
*
CLASS lcl_treeobject DEFINITION
* container class for drag object
*--------------------------------------------------------------------*
CLASS lcl_drag_object DEFINITION.
PUBLIC SECTION.
DATA text TYPE mtreesnode-text.
ENDCLASS.
*---------------------------------------------------------------------*
*
CLASS dragdrop_receiver DEFINITION
* event handler class for drag&drop events
*---------------------------------------------------------------------*
CLASS lcl_dragdrop_receiver DEFINITION.
PUBLIC SECTION.
METHODS:
flavor_select FOR EVENT on_get_flavor OF cl_gui_textedit
IMPORTING index line pos flavors dragdrop_object,
left_drag FOR EVENT on_drag OF cl_gui_simple_tree
IMPORTING node_key drag_drop_object,
right_drop FOR EVENT ON_DROP OF cl_gui_textedit
IMPORTING index line pos dragdrop_object,
drop_complete FOR EVENT on_drop_complete OF cl_gui_simple_tree
IMPORTING node_key drag_drop_object.
ENDCLASS.
START-OF-SELECTION.
CALL SCREEN 100.
*&-------------------------------------------------------------------*
*&
Module START OUTPUT
*&-------------------------------------------------------------------*
April 2001
23
SAP AG
MODULE start OUTPUT.
SET PF-STATUS 'BASE'.
IF container is initial.
CREATE OBJECT container
EXPORTING container_name = 'CONTAINER'.
CREATE OBJECT splitter
EXPORTING parent = container
orientation = 1.
left = splitter->top_left_container.
right = splitter->bottom_right_container.
CREATE OBJECT editor
EXPORTING parent = right.
CREATE OBJECT tree
EXPORTING parent = left
node_selection_mode = tree->node_sel_mode_single.
* Definition of drag drop behaviour for tree
CREATE OBJECT behaviour_left.
CALL METHOD behaviour_left->add
EXPORTING
flavor = 'Tree_move_to_Edit'
dragsrc = 'X'
droptarget = ' '
effect = cl_dragdrop=>copy.
CALL METHOD behaviour_left->add
EXPORTING
flavor = 'Tree_copy_to_Edit'
dragsrc = 'X'
droptarget = ' '
CALL METHOD behaviour_left->get_handle
IMPORTING handle = handle_tree.
* Drag Drop behaviour of tree control nodes are defined in the node
* structure
PERFORM fill_tree.
CALL METHOD tree->add_nodes
EXPORTING node_table = node_itab
table_structure_name = 'NODE_STR'.
* Definition of drag drop behaviour for tree
CREATE OBJECT behaviour_right.
CALL METHOD behaviour_right->add
EXPORTING
flavor = 'Tree_move_to_Edit'
dragsrc = ' '
droptarget = 'X'
CALL METHOD behaviour_right->add
EXPORTING
flavor = 'Tree_copy_to_Edit'
dragsrc = ' '
droptarget = 'X'
CALL METHOD editor->set_dragdrop
EXPORTING dragdrop = behaviour_right.
24
April 2001
SAP AG
* registration of drag and drop events
SET HANDLER dragdrop=>flavor_select FOR editor.
SET HANDLER dragdrop=>left_drag FOR tree.
SET HANDLER dragdrop=>right_drop FOR editor.
SET HANDLER dragdrop=>drop_complete for TREE.
ENDIF.
ENDMODULE.
" START OUTPUT
*&-------------------------------------------------------------------*
*&
Module EXIT INPUT
*&-------------------------------------------------------------------*
MODULE exit INPUT.
LEAVE PROGRAM.
ENDMODULE.
" EXIT INPUT
*&-------------------------------------------------------------------*
*&
Form fill_tree
*&-------------------------------------------------------------------*
FORM fill_tree.
DATA: node LIKE mtreesnode.
CLEAR node.
node-node_key = 'Root'.
node-isfolder = 'X'.
node-text = 'Text'.
node-dragdropid = ' '.
APPEND node TO node_itab.
CLEAR node.
node-node_key = 'Child1'.
node-relatkey = 'Root'.
node-relatship = cl_gui_simple_tree=>relat_last_child.
node-text = 'DragDrop Text 1'.
node-dragdropid = handle_tree.
" handle of behaviour
CLEAR node.
node-node_key = 'Child2'.
node-relatkey = 'Root'.
node-relatship = cl_gui_simple_tree=>relat_last_child.
node-text = 'DragDrop Text 2'.
node-dragdropid = handle_tree.
" handle of behaviour
ENDFORM.
" fill_tree
*&-------------------------------------------------------------------*
*&
Module USER_COMMAND_0100 INPUT
*&-------------------------------------------------------------------*
MODULE user_command_0100 INPUT.
CALL METHOD cl_gui_cfw=>dispatch.
ENDMODULE.
" USER_COMMAND_0100 INPUT
*--------------------------------------------------------------------*
*
CLASS DRAGDROP_RECEIVER IMPLEMENTATION
*--------------------------------------------------------------------*
CLASS lcl_dragdrop_receiver IMPLEMENTATION.
METHOD flavor_select. " set the right flavor
IF line > 5.
SEARCH flavors FOR 'Tree_move_to_Edit'.
IF sy-subrc = 0.
April 2001
25
SAP AG
CALL METHOD dragDROP_OBJECT->SET_FLAVOR
EXPORTING newflavor = 'Tree_move_to_Edit'.
ELSE.
CALL METHOD dragdrop_object->abort.
ENDIF.
ELSE.
SEARCH flavors FOR 'Tree_copy_to_Edit'.
IF sy-subrc = 0.
CALL METHOD dragdrop_object->set_flavor
EXPORTING newflavor = 'Tree_copy_to_Edit'.
ELSE.
ENDIF.
ENDIF.
ENDMETHOD.
METHOD left_drag. " define drag object
DATA drag_object TYPE REF TO lcl_drag_object.
READ TABLE node_itab WITH KEY node_key = node_key
INTO node.
CREATE OBJECT drag_object.
drag_object->text = node-text.
drag_drop_object->object = drag_object.
ENDMETHOD.
METHOD right_drop. " action in the drop object
DATA textline(256).
DATA text_table LIKE STANDARD TABLE OF textline.
DATA drag_object TYPE REF TO lcl_drag_object.
CATCH SYSTEM-EXCEPTIONS move_cast_error = 1.
drag_object ?= dragdrop_object->object.
ENDCATCH.
IF sy-subrc = 1.
" data object has unexpected class
" => cancel Drag & Drop operation
EXIT.
ENDIF.
CALL METHOD editor->get_text_as_stream
IMPORTING text
= text_table.
* Synchronize Automation Queue after Get Methods
CALL METHOD cl_gui_cfw=>flush.
textline = drag_object->text.
* Insert text in internal table
INSERT textline INTO text_table INDEX 1.
* Send modified table to frontend
CALL METHOD editor->set_text_as_stream
EXPORTING text = text_table
EXCEPTIONS error_dp
= 1
error_dp_create = 2.
ENDMETHOD.
METHOD drop_complete. " do something after drop
IF drag_drop_object->flavor = 'Tree_move_to_Edit'.
CALL METHOD tree->delete_node
EXPORTING node_key = node_key.
26
April 2001
SAP AG
delete node_itab where node_key = node_key.
ENDIF.
ENDMETHOD.
ENDCLASS.
April 2001
27
SAP AG
Drag&Drop im WAN-Umfeld
Drag&Drop im WAN-Umfeld
Beim Drag&Drop erzeugt jeder Flavor jeder Instanz der Klasse CL_DRAGDROP einen
Kommunikations-Overhead von 20..70 Byte. Solange die Anzahl der Instanzen der Klasse
CL_DRAGDROP nicht zu groß wird ( < 100), ist kein Problem zu erwarten. Der KommunikationsOverhead tritt zudem nur einmalig auf.
Die einzige Regel, die zu beachten ist:
Es darf nicht für jedes Drag&Drop-fähige Objekt eine Instanz der Klasse CL_DRAGDROP angelegt
werden, sondern für alle Objekte, die sich gleich verhalten sollen, wird die gleiche Instanz
verwendet.
28
April 2001
SAP AG
Lifetime Management
Lifetime Management
Verwendung
Das Lifetime Management regelt die Lebensdauer eines Custom Controls am Frontend. Wenn
die Lebensdauer abgelaufen ist, wird das Custom Control automatisch vom SAP-System am
Frontend abgebaut. Dabei wird die Methode free [Seite 54] bzw. finalize [Seite 58] für das
Control vom System aufgerufen. Natürlich können Sie ein Control mit diesen Methoden auch
programmgesteuert abbauen.
Funktionsumfang
Es gibt zwei Einstellungen für die Lebensdauer eines Controls, die beim Instanzieren vergeben
werden:
•
my_control->lifetime_imode: Das Control lebt, solange der interne Modus nicht
abgebaut wird (leave program. leave transaction.) Die Anweisung set screen
0, leave screen. baut den internen Modus nur dann ab, wenn keine andere
Dynproinstanz (erzeugt z.B. durch CALL SCREEN) mehr vorhanden ist. Danach wird die
Methode finalize [Seite 58] aufgerufen.
•
my_control->lifetime_dynpro: Das Control lebt, solange die Instanz des Dynpros
existiert, d.h. sich noch im Dynprostapel befindet. Danach wird die Methode free [Seite 54]
aufgerufen.
Die Benutzung dieses Modus regelt automatisch die Sichtbarkeit von Controls. Controls
werden immer nur dann eingeblendet, wenn das Dynpro aktiv ist, auf dem sie erzeugt
wurden. Ist ein anderes Dynpro aktiv, werden sie automatisch unsichtbar geschaltet.
•
my_control->lifetime_default: Wird das Control in einen Container eingebaut,
übernimmt es die Lebensdauer des Containers. Wird es nicht in einen Container eingebaut
(z.B. weil es selbst ein Container ist), dann wird die Lebensdauer auf my_control>lifetime_imode gesetzt.
Die Lebensdauer eines Controls darf nur kürzer, aber niemals länger sein als die
seines Containers.
Die Instanz eines Dynpros wird wie folgt definiert:
Eine Instanz wird erzeugt, wenn ein Dynpro auf den Dynprostapel gestellt wird ist
(z.B.: call screen 100 (starting at...); call transaction, ..) oder
wenn es in den Dynprostapel gestellt wird, da es der Nachfolger eines anderen
Dynpros ist.
Eine Instanz wird abgebaut, wenn das Nachfolgedynpro ein anderes als das Dynpro
der aktuellen Instanz ist (set screen 200 oder set screen 0).
Die Lebensdauer eines Controls wird in dem Attribut my_control->lifetime verwaltet.
April 2001
29
SAP AG
Lifetime Management
Mit der Methode is_alive [Seite 61] können Sie abfragen, ob ein instanziertes Control noch am
Frontend existiert. Die Methode get_living_dynpro_controls [Seite 49] liefert eine Liste aller
existierenden Controls zurück.
30
April 2001
SAP AG
Automation Queue
Automation Queue
Verwendung
Die Kommunikation zwischen Automation Controller und OO Control Framework wird über GUIRFC-Aufrufe abgewickelt:
SAPGUI
Automation
Controller
Custom Control 1
Automation Queue
OK_CODE
OO Control
Framework
Custom Control 2
GUI-RFC
Automation Queue
Applikationsserver
Um die Netzlast zwischen dem Backend und dem Frontend gering zu halten, werden Aufrufe
vom Backend an das Frontend gepuffert und zu definierten Synchronisationspunkten an das
Frontend gesendet. Der Synchronisationspunkt wird durch nicht gepufferte Methodenaufrufe
oder durch expliziten Aufruf einer generischen Methode (CALL METHOD cl_gui_cfw=>flush)
erreicht (siehe Synchronisation der Automation Queue [Seite 33]).
Die Kommunikation basiert auf einem RFC-Aufruf. Der Aufruf erfolgt synchron, was bedeutet,
daß bei jedem Synchronisationspunkt ein RFC-Aufruf erfolgt. Aufgrund der Architektur des SAPSystems dürfen diese RFC-Aufrufe eine bestimmte Dauer nicht überschreiten, da sonst die
Verbindung zum Präsentationsserver vom Applikationsserver beendet wird.
Die Pufferung von Operationen erhöht die Performance erheblich, da jede ungepufferte
Operation eine RFC-Kommunikation mit dem Frontend auslöst. Allerdings sind insbesondere
gepufferte Lesezugriffe auf ein Control mit größter Vorsicht zu behandeln, da eine falsche
Verwendung zu einem Laufzeitfehler führen kann (siehe Fehlerbehandlung [Seite 35])!
Performance-Hinweise
Bei der Performance ist vor allem die Anzahl der Synchronisationspunkte zu beachten. In der
Dynproablauflogik wird auf jeden Fall nach PBO automatisch die Automation Queue
synchronisiert.
April 2001
31
SAP AG
Automation Queue
Da allerdings eine Fehlerbehandlung von Methoden erst nach dem Synchronisationspunkt
möglich ist, ist ein Kompromiß zwischen Performance und Fehlerbehandlung zu schließen.
Weiterhin ist bei großen Datenmengen zu beachten, daß die Verbindung zwischen Applikationsund Präsentationsserver wegen Zeitüberschreitung nicht unterbrochen wird. In einem solchen
Fall müßten dann zusätzliche Synchronisationspunkte eingefügt werden.
Werkzeuge zur Unterstützung bei der Performace-Optimierung finden Sie unter Services rund
um die Automation Queue [Seite 37].
Voraussetzungen
Es gibt drei Arten von Methoden von Control-Schalen:
• Methoden, die immer vor der Rückkehr eine Synchronisation der Automation Queue
ausführen
• Methoden, bei denen nie eine Synchronisation der Automation Queue ausgeführt wird. Hier
ist der Anwender für die Übertragung des Puffers verantwortlich.
• Methoden, bei denen die Synchronisation über einen Parameter gesteuert werden kann.
Funktionsumfang
Gepufferte Operationen werden in der Automation Queue gesammelt. Ein interner Modus verfügt
über eine einzige Automation Queue für alle Custom Controls des internen Modus. Durch
Synchronisation der Automation Queue wird deren Inhalt zum Frontend gesendet und dort
ausgeführt. Das Ergebnis wird dann an das Backend zurückgemeldet:
Sie rufen eine Methode des SAP Tree Controls, um den selektierten Knoten zu
setzen (ohne Flush).
Die Methode stellt zwei Operationen in die Automation Queue: Op_Tree_1 und
Op_Tree_2.
Dann rufen Sie eine Methode eines TextEdit Controls, um den ausgewählten Text
anzuzeigen (ohne Flush). Die Methode stellt die Operation Op_TextEdit_1 in die
Queue.
Die Queue hat nun folgende Gestalt:
Op_Tree_1
Op_Tree_2
Op_TextEdit_1
Wenn Sie jetzt die Automation Queue synchronisieren, wird sie zum Frontend
übertragen und auf den Controls ausgeführt.
32
April 2001
SAP AG
Synchronisation der Automation Queue
Bei der Kommunikation zwischen dem OO Control Framework und dem Automation Server spielt
die Automation Queue eine zentrale Rolle. In ihr werden die Automation-Aufrufe gepuffert und zu
speziellen Synchronisationszeitpunkten vom Backend an das Frontend übertragen. Nach
Abarbeiten der Automation Queue am Frontend wird dann das Ergebnis an das Backend
zurückgeschickt.
Die Anzahl der Synchronisationszeitpunkte ist entscheidend für die Performance der
Anwendung. Informationen dazu bietet Ihnen der Automation Trace und der PerformanceMonitor. Beide Werkzeuge werden in Services rund um die Automation Queue [Seite 37]
vorgestellt.
Ablauf
Die Synchronisation der Automation Queue wird zu bestimmten Zeitpunkten automatisch vom
System durchgeführt:
•
am Ende jedes PBO-Zeitpunkts:
Die Synchronisation durch das System erfolgt erst nach dem Feldtransport zum
Dynpro. Daher können Ergebnisse aus Methodenaufrufen, die durch die
automatische Synchronisation abgearbeitet werden, nicht auf dem Dynpro angezeigt
werden.
•
nach dem Verlassen der Behandlermethode für Systemereignisse [Seite 10]
Weiterhin können Sie die Synchronisation auch explizit anstoßen. Dazu steht Ihnen die Methode
flush [Seite 48] der Klasse CL_GUI_CFW zur Verfügung.
Durch geeignete Programmierung können Sie die letzte explizite Synchronisation
durch das System implizit durchführen lassen.
Arbeiten mit gepufferten Operationen zur Performance-Optimierung
Die Performance kann anhand eines einfachen Schemas generell optimiert werden. Hierzu
sollten hinsichtlich der Ablauflogik am Backend, also pro PBO / PAI-Schritt, die Aufrufe an alle
vorhandenen Controls zweigeteilt werden:
•
Holen von Eigenschaften der Controls
−
Gepuffertes Holen der benötigten Eigenschaften aller Controls
−
•
Verarbeitung / Berechnungen
•
Setzen von Eigenschaften der Controls
−
Gepuffertes Setzen von Eigenschaften auf den Controls
April 2001
33
SAP AG
−
Somit werden nur zwei Synchronisationszeitpunkte für alle Controls zusammen benötigt. Es kann
allerdings sein, daß es mehrere Abschnitte ”Holen von Eigenschaften der Controls” geben muß.
Dies ist dann erforderlich, wenn erst nach dem Besorgen einer Information entschieden werden
kann, welche Information noch besorgt werden muß.
Gepuffertes Holen von Control-Eigenschaften
Beim gepufferten Holen von Control-Eigenschaften ist folgendes zu beachten: Die Adressen der
ABAP-Variablen, in welche die zu holenden Werte geschrieben werden sollen, werden in der
Automation Queue vermerkt. Die Wertübergabe an die Variablen erfolgt erst beim
Synchronisationszeitpunkt. Bis zu diesem Zeitpunkt müssen die Adressen dieser Variablen gültig
sein. Ist eine lokale Variable nicht mehr vorhanden (z.B. lokale Variable einer Formroutine), löst
die Synchronisation einen Laufzeitfehler aus. Die Tücke eines solchen Fehlers besteht darin, daß
im Debugger mit der Einstellung Automation Controller: Aufträge immer synchron verarbeiten
kein Fehler auftritt.
Die Verwendung globaler Variablen löst das Problem nicht. Zum einen ist es kein guter
Programmierstil, zum anderen führt ein zu später Synchronisationszeitpunkt dazu, daß eine
Anwendung nicht aktuelle Werte der Variablen benutzt.
Sicherheit bringt die Abfrage von Control-Eigenschaften in einer Formroutine, die am
Ende und bei jedem EXIT eine Synchronisation durchführt.
Beim Auswerten von Ereignissen macht es Sinn, sich die Eigenschaften des
auslösenden Controls im Ereignisbehandler zu holen und die Automation Queue
danach zu synchronisieren.
(Pseudo-Syntax): Der selektierte Knoten eines Tree Controls und der selektierte Text
eines TextEdit Controls sollen gelesen werden:
FORM GET_CONTROL_PROPERTIES.
DATA: tree_selected_node, combobox_selected_node.
CALL METHOD tree->GET_SELECTED_NODE
IMPORTING
NODE_KEY
= tree_selected_node
<Fehlerbehandlung>
CALL METHOD textedit-> GET_SELECTION_POS
IMPORTING
FROM_LINE = from_line
FROM_POS = from_pos
TO_LINE
= to_line
TO_POS
= to_pos.
<Fehlerbehandlung>
CALL METHOD CL_GUI_CFW=>FLUSH
<Fehlerbehandlung>
ENDFORM.
34
April 2001
SAP AG
Fehlerbehandlung bei der Synchronisation
Fehler bei Automation-Aufrufen können erst nach dem Synchronisationszeitpunkt ausgewertet
werden. Die dadurch entstehende Problematik soll an folgendem Beispiel verdeutlicht werden:
1. Nacheinander werden die Methoden set_registered_events, add_column,
add_nodes_and_items und expand_nodes auf einen SAP Tree aufgerufen.
Der Aufruf der Methode add_nodes_and_items beinhaltet einen Fehler.
2. Nun wird mit der Methode cl_gui_cfw=>flush die Automation Queue synchronisiert.
Dadurch wird die Automation Queue an das Frontend übertragen und dort abgearbeitet.
3. Die ersten beiden Methoden werden ohne Fehler abgearbeitet.
4. Bei der dritten Methode tritt allerdings ein Fehler auf. Das weitere Abarbeiten der Automation
Queue wird dadurch abgebrochen, und es wird ein Fehler an das Backend gemeldet.
5. Es wird die Ausnahme cntl_error der Methode cl_gui_cfw=>flush ausgelöst.
Daher ist die fehlerhafte Methode auf Anhieb nicht zu identifizieren.
In diesem Fall sollten Sie den Debugger [Seite 37] benutzen und dabei die Option
Automation Controller: Aufträge immer synchron verarbeiten setzen. Dann wird der
Fehler bei der Methode add_nodes_and_items ausgelöst.
Besonders kritisch wirkt sich dieses Verhalten bei der Synchronisation der
Automation Queue durch das System aus. Um auch hier eine Fehlerbehandlung
durch die Anwendung zu ermöglichen, löst das System in diesem Fall das
Systemereignis flush_error aus. Auf dieses sollten Sie sich auf jeden Fall
registrieren. Versäumen Sie dies, wird ein Fehlerprotokoll ausgegeben.
Ablauf
Um sich auf das Ereignis flush_error zu registrieren, müssen Sie folgende Schritte
durchführen:
1. Legen Sie eine (lokale) Klasse für die Ereignisbehandlung an.
2. Definieren Sie eine Ereignisbehandlermethode für das Ereignis flush_error der Klasse
cl_gui_cfw. Als Ereignisparameter erhalten Sie Informationen über den Kontext, in dem
der Fehler aufgetreten ist.
Beispiel als statische Methode:
*------------------------------------------*
*
CLASS lcl_event_handler DEFINITION
*------------------------------------------*
CLASS lcl_event_handler DEFINITION.
PUBLIC SECTION.
April 2001
35
SAP AG
class-METHODS
error FOR EVENT flush_error OF cl_gui_cfw
IMPORTING DYNPRO_PROGRAM DYNPRO_NUMBER SITUATION.
ENDCLASS.
Ereignisparameter
Parameter
Bedeutung
DYNPRO_PROGRAM
Programmname des Programms, in dem der Fehler aufgetreten ist
DYNPRO_NUMBER
Dynpronummer, auf der der Fehler aufgetreten ist
SITUATION
Fehler bei systemgesteuertem Synchronisieren der Automation Queue trat
auf bei
cl_gui_cfw=>flush_situation_pbo: Synchronisation nach PBO
cl_gui_cfw=>flush_situation_system_events: Synchronisation
nach einem Systemereignis
3. Implementieren Sie die Ereignisbehandlermethode. Werten Sie dabei die Informationen zum
Kontext des Fehlers aus:
*------------------------------------------*
*
CLASS lcl_event_handler IMPLEMENTATION
*- ----------------------------------------*
CLASS lcl_event_handler IMPLEMENTATION.
METHOD error.
<do something>
ENDMETHOD.
ENDCLASS.
Registrieren Sie das Ereignis am OO Control Framework:
SET HANDLER lcl_event_handler=>error.
Nach dem Auslösen des Ereignisses sollte auf keinen Fall weiter mit Controls
gearbeitet werden, da dann weitere Fehler auftreten können. Sie sollten daher Ihre
Anwendung kontrolliert beenden.
36
April 2001
SAP AG
Services rund um die Automation Queue
Verwendung
Zur Unterstützung bei der Verwendung von Controls in Anwendungen werden unterschiedliche
Services zur Verfügung gestellt:
Debugger: Lokalisieren von Fehlern
Performance-Anzeige: Performance-Optimierung
Automation Trace: Lokalisieren von Synchronisationszeitpunkten
Funktionsumfang
Debugger
Wenn Sie mit gepufferten Operationen bei der Kommunikation mit Controls arbeiten, werden
Fehler bei einem Methodenaufruf erst bei der Synchronisation der Automation Queue sichtbar.
Daher ist es sinnvoll, beim Debuggen nach jeder Methode die Automation Queue zu
synchronisieren. Dazu können Sie im Debugger die Einstellung Automation Controller: Aufträge
immer synchron verarbeiten setzen. Diese ruft dann nach jeder Automation Methode die
generische Methode CALL METHOD cl_gui_cfw=>flush auf.
Tritt bei direkter Ausführung der Operationen kein Fehler mehr auf, dann wurde die Methode
CL_GUI_CFW=>FLUSH zum falschen Zeitpunkt gerufen.
Fügen Sie nach jedem Methodenaufruf eine entsprechende Fehlerbehandlung
hinzu (Abfrage des SY-SUBRC). Beachten Sie aber, daß diese Fehlerbehandlung in
der Regel nur im Debugging durchlaufen wird.
April 2001
37
SAP AG
Performance-Anzeige
Wenn Sie die Anzahl der Roundtrips innerhalb Ihres Programms überprüfen wollen, haben Sie
zwei Möglichkeiten:
•
Schalten Sie die Anzeige der Roundtrips in der Statuszeile ein:
•
Aktivieren Sie die Performance-Anzeige. Wählen Sie dazu System → Hilfsmittel →
Performance Anzeige.
38
April 2001
SAP AG
Automation Trace
Sie können einen Trace über die Automation Queue erstellen. Dazu wird in den SAP-GUIEinstellungen in der Gruppe Trace das Ankreuzfeld Automation ausgewählt. Danach werden alle
Aufrufe mit ihren Parametern (create object, call method, set/get property,
free object) der Automation Queue in einer Tracedatei protokolliert.
Tritt ein Fehler auf, wird dieser in der Trace-Datei protokolliert (HRESULT error_code).
Zusätzlich kann verfolgt werden, wie viele Flushes von der Applikation pro PBO/PAI benötigt
werden. Überflüssige Flushes können dadurch eliminiert werden.
April 2001
39
SAP AG
Bei Mitverfolgung der Methodenaufrufe der Control-Verschalung im Trace ist zu beachten, daß
die ABAP-Methodennamen in der Regel nicht mit den Methodennamen im Trace
übereinstimmen. Die Methodennamen im Trace entsprechen nämlich den Automation-Aufrufen
an das Control. Weiterhin ist zu beachten, daß der Aufruf einer ABAP-Methode den Aufruf
mehrerer Automation-Methoden nach sich ziehen kann.
Das Laden eines Bildes in das SAP Picture hat im ABAP-Programm folgende Form:
CALL METHOD picture->load_picture_from_url
EXPORTING url = 'http://www.sap-ag.de/germany/images/sapag.gif'
Im Automation Trace entspricht dies folgenden Zeilen:
40
April 2001
SAP AG
April 2001
41
SAP AG
Verwendung von Controls im WAN
Die Verwendung von Controls zur Oberflächengestaltung führt in der Regel zu einer Belastung
des Kommunikationskanals zwischen Frontend und Backend. Dies kann schon im LAN-, aber
insbesondere im WAN-Umfeld ein performance-kritischer Aspekt sein.
Puffermechanismen helfen, diese Problematik zu entschärfen (siehe auch Automation Queue
[Seite 31]). Die aufgeführten Punkte sollen als Richtlinien bei der Verwendung von Controls im
WAN dienen.
Control-spezifische Hinweise zur Verwendung im WAN finden Sie in der Dokumentation zu dem
jeweiligen Control.
Verwendung von CL_GUI_CFW=>FLUSH
Der Aufruf CL_GUI_CFW=>FLUSH [Seite 48] dient zum Synchronisieren der Automation Queue
und der in der Queue enthaltenen ABAP-Variablen. Dieser Aufruf erzeugt in vielen Fällen einen
synchronen RFC vom Applikationsserver zum Frontend. Um optimale Performance zu erreichen,
sollten die Aufrufe dieser Methode minimiert werden.
Es ist in vielen Fällen zu empfehlen, alle Eigenschaften von allen Controls zentral an einer Stelle
(z.B. am Anfang des PAI) in einer Automation Queue zu lesen und dann über einen einmalige
Synchronisation zu besorgen. Diese Variante ist auch dann zu bevorzugen, wenn dabei
Eigenschaften gelesen werden, die nicht immer für den Ablauf des Ereignisbehandlers bzw. des
PAI – PBO Zyklus notwendig sind.
Es ist nicht notwendig, einen „Sicherheits-Flush“ am Ende von PBO zu codieren, damit
Methodenaufrufe der Controls garantiert an das Frontend transportiert werden. Diese
Funktionalität wird systemseitig garantiert, wenn das nächste Dynpro gesendet wird. Damit ist es
auch nicht möglich, eine Automation Queue über mehrere Bildwechsel hinweg aufzubauen.
Es ist nicht garantiert, daß eine Automation Queue durch den Aufruf CL_GUI_CFW=>FLUSH
gesendet wird. Die Queue erkennt, ob Returnwerte enthalten sind. Ist dies nicht der Fall,
wird das Senden unterdrückt!
Für alle Fälle, in denen auch bei einer Queue ohne Returnwert gewünscht wird, daß die
Automation Queue synchron versendet wird, gibt es im Control Framework die Methode
CL_GUI_CFW=>UPDATE_VIEW [Seite 51]. Diese Methode darf nur dann verwendet werden,
wenn es zwingend notwendig ist, ein Update des GUI zu erreichen. Beispiele hierfür sind sehr
lange laufende Anwendungen, die in regelmäßigen Abständen dem Benutzer ein Feedback über
den Fortschritt der Aktion anzeigen möchten.
Nach dem Lesen von Eigenschaften ist der Inhalt der entsprechenden ABAP-Variablen erst nach
dem nächsten FLUSH garantiert. Solange dieser Aufruf nicht erfolgt ist, ist der Inhalt der
entsprechenden ABAP-Variablen nicht definiert. In Zukunft wird es Fälle gegeben, in denen
dieser FLUSH unnötig sein wird. Diese Fälle werden von der Automation Queue erkannt; der
entsprechende FLUSH-Call wird dann ignoriert.
Erzeugen von Controls, Datenversorgung
Das Erzeugen eines Controls und die Datenversorgung ist in den meisten Fällen ein einmaliger
Vorgang und im Vergleich zu Dynproelementen sehr teuer. Deshalb sollten Controls nicht
unnötig erzeugt bzw. nicht unnötig mit Daten versorgt werden.
Ein typisches Beispiel hierfür sind TabStrips mit mehreren Seiten. Wenn diese Seiten Controls
tragen, ist immer abzuwägen, ob man auf lokale Seiten verzichtet und die Controls erst dann
42
April 2001
SAP AG
erzeugt, wenn der Benutzer die Seite aktiviert. Das gleiche trifft für die Datenversorgung dieser
Controls auf TabStrip-Seiten zu.
Muß bei der Datenversorgung eine Unterscheidung zwischen einer WAN- und einer LANAnmeldung vorgenommen werden, steht der Funktionsbaustein SAPGUI_GET_WANFLAG zur
Verfügung. In manchen Fällen kann es notwendig werden, daß eine Anwendung andere
Datenmengen oder ganze Fallbacks für die WAN-Anmeldung zur Verfügung stellen sollte. Ein
Beispiel, wann die WAN- bzw. LAN- Anmeldung einen Einfluß haben kann, ist die Anzahl von
Geschwistern in einem Tree Control, die ohne künstliche Zwischenebenen übertragen werden
können.
Im Gegensatz zu Dynproelementen werden die Controls nur einmalig erzeugt und mit Daten
versorgt. Controls werden unter Performance-Aspekten dann immer preiswerter, je länger diese
leben. In Anwendungen, die ständig neu aufgerufen und damit neu initialisiert werden, kann dies
zu einem erheblichen Performance-Nachteil werden; in Anwendungen, die sehr lange auf den
gleichen Bildern arbeiten, kann daraus sogar ein Performance-Vorteil entstehen.
Im Einzelfall kann über entsprechende Performance-Werkzeuge [Seite 37] überprüft werden,
welche Nachteile oder Vorteile die Verwendung eines Controls unter dem Aspekt der
Netzwerkauslastung bringt.
Ablegen von Dokumenten, Bildern etc.
Zum Release 4.6A wird ein Frontend-Cache für Zugriffe auf Dokumente aus dem BDS (Business
Dokument Service) realisiert. Es wird dringend empfohlen, Office-Dokumente, Bilder etc. im BDS
und nicht in der R/3-Datenbank abzulegen. Dokumente aus dem BDS können danach im
Frontend-Cache abgelegt werden. Sie müssen nur einmalig über das Netz geladen werden.
April 2001
43
SAP AG
Anlegen eines Controls am Beispiel des SAP Picture
Voraussetzungen
Der folgende Ablauf ist für alle von SAP ausgelieferten Custom Controls anwendbar. In den
Code-Beispielen wird immer auf das SAP Picture Control eingegangen. Für andere Controls ist
aber im Prinzip nur die Klasse des Controls auszutauschen.
Weiterhin geht das Beispiel davon aus, daß das Custom Control in einem Custom Container
eingebaut wird. Andere Szenarios werden in der Dokumentation zu den Control Containern
beschrieben.
Ablauf
Instanz anlegen
1. Definieren Sie eine Referenzvariable für den Custom Container, in dem das Custom Control
angezeigt werden soll (Siehe SAP Container [Extern])
DATA container TYPE REF TO cl_gui_custom_container.
2. Definieren Sie eine Referenzvariable für das Picture Control:
DATA picture TYPE REF TO cl_gui_picture.
3. Erzeugen Sie den Custom Container. Den Bereich 'CUSTOM' für den Custom Container
müssen Sie vorher im Screen Painter angelegt haben. Beim Erzeugen des Containers legen
Sie auch seine Lebensdauer [Seite 29] fest (siehe constructor [Seite 56]).
CREATE OBJECT container
EXPORTING container_name = 'CUSTOM'
lifetime
= lifetime.
4. Erzeugen Sie das Picture Control. Für dieses können Sie auch eine Lebensdauer festlegen.
Allerdings darf die Lebensdauer nicht größer sein als die seines Containers.
CREATE OBJECT picture
EXPORTING parent
= container
lifetime = lifetime.
Ereignis anmelden
5. Das Anmelden von Ereignissen gliedert sich in das Registrieren des Ereignisses am Control
Framework, das Definieren einer Behandlermethode und das Anmelden der
Behandlermethode. Diese Schritte finden Sie in Registrieren und Verarbeiten von
Ereignissen [Seite 13].
Arbeiten mit dem Control
6. Diese Schritte sind control-spezifisch und werden hier nicht beschrieben.
Abbau der Controls
In der Regel übernimmt das Lifetime Management [Seite 29] den Abbau der verwendeten
Controls. Wenn Sie die Controls aber in Ihrem Programm selbst abbauen wollen, führen Sie
folgende Schritte aus:
44
April 2001
SAP AG
7. Bauen Sie das Custom Control mit der Methode free [Seite 54] am Frontend ab. Sofern Sie
den Control Container nicht mehr benötigen, bauen Sie auch diesen ab:
CALL METHOD picture->free
EXCEPTIONS cntl_error
cntl_system_error
CALL METHOD container->free
cntl_system_error
= 1
= 2.
= 1
= 2.
Beachten Sie die Reihenfolge, in der Sie die Controls am Frontend abbauen. Wenn
Sie einen Container abbauen, werden nämlich automatisch alle in dem Container
eingebundenen Controls auch abgebaut. Der Versuch, ein bereits abgebautes
Control erneut abzubauen, führt zu einem Fehler. Mit der Methode is_alive [Seite 61]
kann nachgeprüft werden, ob das Control schon abgebaut wurde.
8. Löschen Sie die Referenzvariablen des Custom Controls und des Control Containers:
FREE PICTURE.
FREE CONTAINER.
April 2001
45
SAP AG
Methoden der Klasse CL_GUI_CFW
Methoden der Klasse CL_GUI_CFW
Die Klasse CL_GUI_CFW beinhaltet statische Methoden, die beim Aufruf auf alle instanzierten
Custom Controls wirken.
46
April 2001
SAP AG
dispatch
dispatch
Die Methode dispatch verteilt Applikationsereignisse (siehe Ereignisbehandlung [Seite 10]) an
die für das Ereignis angemeldeten Ereignisbehandler. Wenn diese Methode nicht im
Applikationsprogramm innerhalb von PAI aufgerufen wird, dann wird sie automatisch vom
System nach dem Abarbeiten von PAI aufgerufen. Die Methode liefert einen Returncode zurück,
über den der Erfolg des Aufrufs abzulesen ist.
CALL METHOD cl_gui_cfw=>dispatch
IMPORTING return_code = return_code.
Parameter
Bedeutung
return_code
cl_gui_cfw=>rc_found: Das Ereignis konnte erfolgreich an eine
Behandlermethode übergeben werden.
cl_gui_cfw=>rc_unknown: Das Ereignis wurde nicht in der Ereignisliste
registriert.
cl_gui_cfw=>rc_noevent: Es wurde kein Ereignis auf einem Control
ausgelöst. Der OK_CODE war daher ein normaler OK_CODE (z.B. von
einem Menüeintrag).
cl_gui_cfw=>rc_nodispatch: Dem Ereignis konnte keine
Behandlermethode zugeordnet werden.
Das Ereignis kann nur einmalig verteilt werden. Danach ist das Ereignis verbraucht.
Daher wird ein zweiter Aufruf der Methode nicht nochmals zu einem Sprung in den
Ereignisbehandler führen.
April 2001
47
SAP AG
flush
flush
Mit dieser Methode synchronisieren Sie explizit die Automation Queue [Seite 31]. Die gepufferten
Operationen werden dann zum Frontend per GUI-RFC geschickt. Dort wird die Automation
Queue in der Reihenfolge abgearbeitet, wie Sie sie gefüllt haben.
Im Fehlerfall wird eine Ausnahme ausgelöst, die Sie auf jeden Fall abfragen und behandeln
sollten. Da eine Zuordnung des Fehlers in der Regel nicht mehr möglich ist, stehen Ihnen sowohl
im Debugger als auch im SAP GUI Werkzeuge zur Verfügung, um den Fehler zu lokalisieren:
Debugger: Markieren Sie in den Einstellungen das Ankreuzfeld Automation Controller: Aufträge
immer synchron verarbeiten. Dies führt dazu, daß nach jeder Methode, die den Automation
Controller ruft, die Methode cl_gui_cfw=>flush automatisch aufgerufen wird.
SAP GUI: In den Einstellungen zum SAP GUI können Sie auf der Karteikarte Trace das
Ankreuzfeld Automation wählen. Dadurch wird die Kommunikation zwischen Applikationsserver
und Automation Controller in einer Trace-Datei mitgeschrieben. Diese kann dann ausgewertet
werden.
CALL METHOD cl_gui_cfw=>flush
EXCEPTIONS CNTL_SYSTEM_ERROR = 1
CNTL_ERROR = 2.
Führen Sie nur so viele Synchronisationspunkte in Ihr Programm ein, wie wirklich
nötig sind. Bei jeder Synchronisation wird nämlich eine RFC-Verbindung zum SAP
GUI geöffnet.
48
April 2001
SAP AG
get_living_dynpro_controls
get_living_dynpro_controls
Mit dieser Methode können Sie sich eine Liste von Referenzvariablen zu allen noch aktiven
Custom Controls besorgen.
CALL METHOD cl_gui_cfw=>get_living_dynpro_controls
IMPORTING control_list = control_list.
Parameter
Bedeutung
control_list
Liste der Referenzvariablen zu aktiven Custom Controls.
Liste ist vom Typ CNTO_CONTROL_LIST (in der Klasse CL_GUI_CFW
definiert)
April 2001
49
SAP AG
set_new_ok_code
set_new_ok_code
Diese Methode darf nur in Behandlermethoden zu Systemereignissen eingesetzt werden. Sie
setzt einen OK_CODE, der ein Ausführen von PAI nach sich zieht. Dadurch können Sie nach dem
Feldtransport nochmals die Kontrolle in Ihren PAI-Modulen bekommen.
CALL METHOD cl_gui_cfw=>set_new_ok_code
EXPORTING new_code = new_code
IMPORTING
rc = rc.
Parameter
Bedeutung
new_code
Funktionscode, der in das OK_CODE-Feld (SY-UCOMM) gestellt werden soll.
return_code
cl_gui_cfw=>rc_posted: Der OK_CODE wurde mit Erfolg gesetzt, und
die Verarbeitung wird nach Abschluß der Behandlermethode mit PAI
fortgesetzt (vorher wird noch die automatische Feldprüfung des Dynpros
durchgeführt).
cl_gui_cfw=>rc_wrong_state: Die Methode wurde nicht bei einem
Systemereignis aufgerufen.
cl_gui_cfw=>rc_invalid: Der gesetzte OK_CODE ist kein erlaubter
OK_CODE.
50
April 2001
SAP AG
update_view
update_view
Die Automation Queue wird durch den Aufruf der Methode flush [Seite 48] nur dann
synchronisiert, wenn in der Automation Queue Returnwerte enthalten sind.
Für alle Fälle, in denen auch im Fall einer Returnwert-freien Queue gewünscht wird, daß die
Automation Queue synchron versendet wird, gibt es im Control Framework die Methode
CL_GUI_CFW=>UPDATE_VIEW. Diese Methode darf nur dann verwendet werden, wenn es
zwingend notwendig ist, ein Update des SAP GUI zu erreichen. Beispiele hierfür sind sehr lange
laufende Anwendungen, die in regelmäßigen Abständen dem Benutzer ein Feedback über den
Fortschritt der Aktion anzeigen möchten.
CALL METHOD cl_gui_cfw=>update_view
EXCEPTIONS CNTL_SYSTEM_ERROR = 1
CNTL_ERROR
= 2.
April 2001
51
SAP AG
Methoden der Klasse CL_GUI_OBJECT
Methoden der Klasse CL_GUI_OBJECT
Die Klasse CL_GUI_OBJECT beinhaltet wichtige Methoden zum Verschalen von Custom
Controls. Für Anwendungsprogramme ist einzig die Methode is_valid [Seite 53] relevant.
52
April 2001
SAP AG
is_valid
is_valid
Diese Methode liefert als Ergebnis, ob ein Custom Control zu einer Objektreferenz noch am
Frontend vorhanden ist.
CALL METHOD my_control->is_valid
IMPORTING result = result.
Parameter
Bedeutung
result
0: Custom Control ist nicht mehr am Frontend aktiv
1: Custom Control ist noch aktiv
April 2001
53
SAP AG
free
free
Diese Methode baut ein Custom Control am Frontend ab. Nach Aufruf dieser Methode sollten Sie
auch die Objektreferenz initialisieren (FREE my_control).
CALL METHOD my_control->free
= 1
cntl_system_error = 2.
54
April 2001
SAP AG
Methoden der Klasse CL_GUI_CONTROL
Methoden der Klasse CL_GUI_CONTROL
Die Klasse CL_GUI_CONTROL beinhaltet Methoden, die zum Setzen von Control-Eigenschaften
(z.B. Visualisieren des Controls), Registrieren von Ereignissen und zum Abbau des Controls
dienen.
April 2001
55
SAP AG
constructor
constructor
Diese Methode wird von der Control-Verschalung des verwendeten Controls aufgerufen, um ein
Control am Frontend zu instanzieren.
Um ein SAP Control zu instanzieren, rufen Sie immer den Konstruktor der
dazugehörenden Klasse auf.
CREATE OBJECT my_control
EXPORTING
clsid
= clsid
lifetime
= lifetime
shellstyle
= shellstyle
parent
= parent
autoalign
= autoalign
= 1
cntl_system_error = 2
create_error
= 3
lifetime_error
= 4.
Parameter
Bedeutung
clsid
ID der Klasse
lifetime
Parameter für das Lifetime Management. Folgende Werte sind möglich:
my_control->lifetime_imode: Das Control lebt, solange der interne
Modus nicht abgebaut wird (z.B.: leave program. leave
transaction. set screen 0, leave screen.). Danach wird die
Methode finalize [Seite 58] aufgerufen.
my_control->lifetime_dynpro: Das Control lebt, solange die Instanz des
Dynpros existiert, d.h. sich noch im Dynprostapel befindet. Danach wird die
Methode free [Seite 54] aufgerufen.
Die Benutzung dieses Modus regelt automatisch die Sichtbarkeit von
Controls. Controls werden immer nur dann eingeblendet, wenn das Dynpro
aktiv ist, auf dem sie erzeugt wurden. Ist ein anderes Dynpro aktiv, werden
sie automatisch unsichtbar geschaltet.
my_control->lifetime_default: Wird das Control in einen Container
eingebaut, übernimmt es die Lebensdauer des Containers. Wird es nicht in
einen Container eingebaut (z.B. weil es selbst ein Container ist), dann wird
die Lebensdauer auf my_control->lifetime_imode gesetzt.
shellstyle
Steuerung des Erscheinungsbilds und des Verhaltens des Controls
Konstanten aus dem ABAP-Include <CTLDEF>, die mit WS beginnen, können
Sie übergeben. Kombinationen von mehreren Styles können Sie durch
Addieren der Konstanten erreichen. Der Vorschlagswert führt intern zum
Setzen einer ausreichenden Kombination von Style-Konstanten.
parent
56
Container, in dem das SAP Picture Control angezeigt werden kann (siehe SAP
Container [Extern])
April 2001
SAP AG
constructor
autoalign
' ': kein automatisches Ausrichten des Controls
'X': automatisches Ausrichten des Controls. Dabei wird der maximal verfügbare
Platz innerhalb eines Containers verwendet.
April 2001
57
SAP AG
finalize
finalize
Diese Methode wird von der verwendeten Controlverschalung überdefiniert. In ihr werden
control-spezifische Funktionen zum Abbau des Controls aufgerufen. Diese Methode wird
automatisch von der Methode free [Seite 54] aufgerufen, bevor das Control am Frontend
abgebaut wird.
CALL METHOD my_control->finalize.
58
April 2001
SAP AG
set_registered_events
set_registered_events
Mit dieser Methode registrieren Sie sich auf Ereignisse des Controls (siehe auch:
Ereignisbehandlung [Seite 10]).
CALL METHOD my_control->set_registered_events
EXPORTING events
= events
= 1
cntl_system_error = 2
illegal_event_combination = 3.
Parameter
Bedeutung
events
Tabelle der zu registrierenden Ereignisse für das Custom Control my_control
Die Tabelle events ist eine Liste mit Ereignissen, auf die Sie sich registrieren wollen. Die
Tabelle wird mit Bezug auf den Tabellentyp CNTL_SIMPLE_EVENTS definiert. Dem Tabellentyp
liegt die Struktur CNTL_SIMPLE_EVENT zugrunde. Dieser besteht aus folgenden Feldern:
Feld
Bedeutung
EVENTID
Name des Ereignisses
APPL_EVENT
Unterscheidung, ob es sich um ein Systemereignis (initial) oder ein
Applikationsereignis (X) handeln soll.
Die Werte, die dem Feld EVENTID zuzuordnen sind, sind control-spezifisch und werden daher
bei den entsprechenden Controls beschrieben.
April 2001
59
SAP AG
get_registered_events
get_registered_events
Diese Methode liefert eine Liste aller für das Custom Control my_control registrierten
Ereignisse zurück.
CALL METHOD my_control->get_registered_events
IMPORTING events
= events
EXCEPTIONS cntl_error = 1.
Parameter
Bedeutung
events
Tabelle der zu registrierenden Ereignisse für das Custom Control my_control
Die Tabelle events ist eine Liste mit Ereignissen, auf die Sie sich registriert haben. Die Tabelle
wird mit Bezug auf den Tabellentyp CNTL_SIMPLE_EVENTS definiert. Dem Tabellentyp liegt die
Struktur CNTL_SIMPLE_EVENT zugrunde. Dieser besteht aus folgenden Feldern:
Feld
Bedeutung
EVENTID
Name des Ereignisses
APPL_EVENT
Unterscheidung, ob es sich um ein Systemereignis (initial) oder ein
Applikationsereignis (X) handeln soll.
Die Werte, die dem Feld EVENTID zuzuordnen sind, sind control-spezifisch und werden daher
bei den entsprechenden Controls beschrieben.
Allgemeine Informationen zur Ereignisbehandlung finden Sie in der Dokumentation
des SAP Control Frameworks unter Ereignisbehandlung [Seite 10].
60
April 2001
SAP AG
is_alive
is_alive
Diese Methode liefert als Ergebnis, ob ein Custom Control zu einer Objektreferenz noch am
Frontend vorhanden ist.
CALL METHOD my_control->is_alive
RETURNING state = state.
Parameter
Bedeutung
state
my_control->state_dead: Custom Control ist nicht mehr am Frontend aktiv
my_control->state_alive: Custom Control ist auf aktuellem Dynpro aktiv
my_control->state_alive_on_other_dynpro: Custom Control ist auf dem
aktuellen Dynpro nicht aktiv, aber am Frontend noch aktiv (d.h. unsichtbar)
April 2001
61
SAP AG
set_alignment
set_alignment
Diese Methode richtet das Custom Control innerhalb seines Containers aus:
CALL METHOD my_control->set_alignment
EXPORTING alignment
= alignment
= 1
Parameter
Bedeutung
alignment
Ausrichtung des Controls
Der Parameter alignment kann aus Kombinationen folgender Ausrichtungen bestehen:
Name
Bedeutung
my_control->align_at_left
Ausrichtung am linken Rand
my_control->align_at_right
Ausrichtung am rechten Rand
my_control->align_at_top
Ausrichtung am oberen Rand
my_control->align_at_bottom
Ausrichtung am unteren Rand
Kombinationen erhält man durch Aufaddieren der Komponenten:
alignment = my_control->alingn_at_left + my_control->alingn_at_top.
62
April 2001
SAP AG
set_position
set_position
Diese Methode plaziert das Control an eine bestimmte Stelle des Dynpros.
In der Regel wird die Position des Controls über seinen Container geregelt.
CALL METHOD my_control->set_position
EXPORTING height
= height
left
= left
top
= top
width
= width
= 1
Parameter
Bedeutung
height
Höhe des Controls
left
Linker Rand des Controls
top
Oberer Rand des Controls
width
Breite des Controls
April 2001
63
SAP AG
set_visible
set_visible
Mit dieser Methode können Sie die Sichtbarkeit eines Custom Controls verändern.
CALL METHOD my_control->set_visible
EXPORTING visible
= visible
= 1
Parameter
Bedeutung
visible
X: Custom Control ist sichtbar
' ': Custom Control ist nicht sichtbar
64
April 2001
SAP AG
get_focus
get_focus
Diese statische Methode liefert die Objektreferenz des Custom Controls zurück, welches den
Fokus hat.
CALL METHOD cl_gui_control=>get_focus
IMPORTING control
= control
= 1
Parameter
Bedeutung
control
Objektreferenz (TYPE REF TO cl_gui_control) auf das Control, das den
Fokus hat
April 2001
65
SAP AG
set_focus
set_focus
Mit dieser statischen Methode können Sie den Fokus auf ein Custom Control setzen.
CALL METHOD cl_gui_control=>set_focus
EXPORTING control
= control
= 1
Parameter
Bedeutung
control
Objektreferenz (TYPE REF TO cl_gui_control) auf das Control, das den
Fokus bekommen soll
66
April 2001
SAP AG
get_height
get_height
Diese Methode liefert die Höhe des Controls zurück.
CALL METHOD control->get_height
IMPORTING height
Parameter
Bedeutung
height
Aktuelle Höhe des Controls
April 2001
= height
= 1.
67
SAP AG
get_width
get_width
Diese Methode liefert die Breite des Controls zurück.
CALL METHOD control->get_width
IMPORTING width
Parameter
Bedeutung
width
Aktuelle Breite des Controls
68
= width
= 1.
April 2001
SAP AG
Methoden der Klasse CL_DRAGDROP
Methoden der Klasse CL_DRAGDROP
Die Klasse CL_DRAGDROP beinhaltet Methoden, über die das Drag&Drop-Verhalten [Seite 17]
eines Custom Controls beschrieben wird.
April 2001
69
SAP AG
constructor
constructor
Der Konstruktor erzeugt eine Instanz für die Beschreibung des Drag&Drop-Verhaltens eines
Controls.
CREATE OBJECT dragdrop.
70
April 2001
SAP AG
add
add
Diese Methode fügt eine weitere Beschreibung zu dem Drag&Drop-Verhalten hinzu. Es können
beliebig viele Beschreibungen hinterlegt werden. Allerdings darf die gleiche Beschreibung nicht
mehrmals hinzugefügt werden.
CALL METHOD dragdrop->add
EXPORTING flavor
= flavor
dragsrc
= dragsrc
droptarget
= droptarget
effect
= effect
effect_in_ctrl = effect_in_ctrl
EXCEPTIONS allready_defined = 1
obj_invalid
= 2.
Parameter
Bedeutung
flavor
Bezeichnung des neuen Flavors
dragsrc
'X': Beschreibung ist eine Drag-Quelle
droptarget
'X': Beschreibung ist ein Drop-Ziel
effect
Drop-Effekt der Beschreibung zwischen verschiedenen Custom Controls.
Folgende Effekte werden unterstützt:
dragdrop->copy: Darstellung der Maus beim Drag&Drop als
Kopiervorgang
dragdrop->move: Darstellung der Maus beim Drag&Drop als
Verschiebevorgang
dragdrop->none: Es ist kein Drag&Drop möglich
effect_in_ctrl
Drop-Effekt der Beschreibung im gleichen Custom Controls. Folgende
Effekte werden unterstützt:
Kopiervorgang
Verschiebevorgang
dragdrop->use_default_effect: Es wird der gleiche Effekt benutzt,
der durch den Parmeter effect spezifiziert wurde
Ausnahmen
Bedeutung
allready_defined
Der angegebene Flavor wurde bereits definiert.
obj_invalid
Das Objekt wurde bereits mit der Methode destroy [Seite 74] zerstört
April 2001
71
SAP AG
add
Wird bei der Definition des Flavors sowohl der Effekt copy als auch move benutzt,
werden beim Drag&Drop-Vorgang bei normalem Drag die Flavors mit Effekt Move
und beim Drag in Verbindung mit Drücken der Steuerungstaste die Flavors mit Effekt
Copy verwendet.
72
April 2001
SAP AG
clear
clear
Der Inhalt der Instanz wird gelöscht. Nach Aufruf dieser Methode können keine Drag&DropVorgänge mehr auf dem betroffenen Custom Control durchgeführt werden.
CALL METHOD dragdrop->clear
EXCEPTIONS obj_invalid = 1.
Ausnahmen
Bedeutung
obj_invalid
April 2001
73
SAP AG
destroy
destroy
Der Inhalt der Instanz wird gelöscht. Weiterhin wird die Instanz zerstört. Nach Aufruf der Methode
sind keine Drag&Drop-Vorgänge mehr auf dem betroffenen Custom Control möglich.
CALL METHOD dragdrop->destroy.
74
April 2001
SAP AG
get
get
Diese Methode liefert die komplette Beschreibung zu einem Flavor zurück.
CALL METHOD dragdrop->get
EXPORTING
IMPORTING
flavor
=
isdragsrc
=
isdroptarget
=
effect
=
effect_in_ctrl =
EXCEPTIONS not_found
= 1
obj_invalid = 2.
flavor
isdragsrc
isdroptarget
effect
effect_in_ctrl
Parameter
Bedeutung
flavor
Bezeichnung des Flavors
dragsrc
droptarget
effect
Kopiervorgang
Verschiebevorgang
effect_in_ctrl
Drop-Effekt der Beschreibung im gleichen Custom Controls. Folgende
Effekte werden unterstützt:
Kopiervorgang
Verschiebevorgang
dragdrop->use_default_effect: Es wird der gleiche Effekt benutzt,
der durch den Parmeter effect spezifiziert wurde
Ausnahmen
Bedeutung
allready_defined
Der angegebene Flavor wurde bereits definiert.
wird beim Drag&Drop-Vorgang bei normalem Drag die Flavors mit Effekt Move und
beim Drag in Verbindung mit Drücken der Steuerungstaste die Flavors mit Effekt
Copy verwendet.
April 2001
75
SAP AG
get
76
April 2001
SAP AG
get_handle
get_handle
Die Methode liefert das Handle auf die Drag&Drop-Beschreibung. In den meisten Fällen ist ein
Aufruf dieser Methode nicht nötig. Für tabellarische Massendatenschnittstellen (z.B. SAP Tree
Control) muß dieses Handle aber vom Verwender des Controls in die Schnittstellentabelle kopiert
werden.
CALL METHOD dragdrop->get_handle
IMPORTING handle = handle
EXCEPTIONS obj_invalid = 1.
Parameter
Bedeutung
handle
Handle auf die Drag&Drop-Beschreibung
Ausnahmen
Bedeutung
obj_invalid
April 2001
77
SAP AG
modify
modify
Mit dieser Methode können Sie einen bestehenden Flavor verändern.
CALL METHOD dragdrop->modify
EXPORTING flavor
=
dragsrc
=
droptarget
=
effect
=
effect_in_ctrl =
= 1
obj_invalid = 2.
flavor
dragsrc
droptarget
effect
effect_in_ctrl
Parameter
Bedeutung
flavor
dragsrc
droptarget
effect
dragdrop->copy: Darstellung der Maus beim Drag&Drop als Kopiervorgang
Verschiebevorgang
effect_in_ctrl
Drop-Effekt der Beschreibung im gleichen Custom Controls. Folgende Effekte
werden unterstützt:
dragdrop->copy: Darstellung der Maus beim Drag&Drop als Kopiervorgang
Verschiebevorgang
dragdrop->use_default_effect: Es wird der gleiche Effekt benutzt, der
durch den Parmeter effect spezifiziert wurde
Ausnahmen
Bedeutung
not_found
Der angegebene Flavor existiert nicht
obj_invalid
wird beim Drag&Drop-Vorgang bei normalem Drag die Flavors mit Effekt Move und
beim Drag in Verbindung mit Drücken der Steuerungstaste die Flavors mit Effekt
Copy verwendet.
78
April 2001
SAP AG
modify
April 2001
79
SAP AG
remove
remove
Mit dieser Methode löschen Sie einen bestimmten Flavor.
CALL METHOD dragdrop->remove
EXPORTING flavor = flavor
= 1
obj_invalid = 2.
Parameter
Bedeutung
flavor
Ausnahmen
Bedeutung
not_found
Der angegebene Flavor existiert nicht
obj_invalid
80
April 2001
SAP AG
Methoden der Klasse CL_DRAGDROPOBJECT
Methoden der Klasse CL_DRAGDROPOBJECT
Die Klasse CL_DRAGDROPOBJECT dient zur Beschreibung des Kontextes eines Drag&DropVorgangs [Seite 17]. Er beinhaltet in der Regel Informationen zu dem Quellobjekt, den Flavor des
Drag&Drop-Vorgangs und Informationen zu Quelle und Ziel.
April 2001
81
SAP AG
set_flavor
set_flavor
Diese Methode verwenden Sie nur innerhalb der Ereignisbehandlung zu ONGETFLAVOR. Über
den Parameter newflavor bestimmen Sie, welcher Flavor innerhalb des Drag&Drop-Vorgangs
verwendet werden soll. Eine Liste der verfügbaren Flavors wird Ihnen als Ereignisparameter
übergeben.
CALL METHOD dragdropobject->set_flavor
EXPORTING newflavor = newflavor
EXCEPTIONS illegal_state = 1
illegal_flavor = 2.
Parameter
Bedeutung
newflavor
Ausnahmen
Bedeutung
invalid_state
Die Methode wurde nicht innerhalb der Ereignisbehandlung ONGETFLAVOR
aufgerufen.
obj_invalid
Es wurde ein Flavor verwendet, der nicht von der aktuellen Drag&DropSituation unterstützt wird.
82
April 2001
SAP AG
abort
abort
Der Drag&Drop-Vorgang wird sofort abgebrochen. Es werden keine weiteren Ereignisse
ausgelöst.
CALL METHOD dragdropobject->abort.
April 2001
83

SAP Control Framework

Transcription

Similar documents

unter

Yaesu FT-847 - Funkamateur

Leseprobe

nstrukcja top 1252 c

Medieninformatik : HTML / CSS

Sport-Ratgeber (D) 08-2013_V 0318-2007

Swiss Map online Manual

Das Handbuch zum KDE-Menü-Editor

- gds document systems gmbh