SAP Control Framework

Transkript

1 HELP.BCCIGOF Release 4.6C

2 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 Software- Komponenten 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 TM sind eingetragene Marken der Informix Software Incorporated. 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

3 SAP AG Symbole Symbol Bedeutung Achtung Beispiel Empfehlung Hinweis Syntax Tip April

4 SAP AG Inhalt... 6 Architektur des Control Frameworks... 8 Ereignisbehandlung Registrieren und Verarbeiten von Ereignissen Kontextmenü Drag&Drop Ablauf einer Drag&Drop Operation Ereignisse bei Drag&Drop Beispiel für Drag&Drop-Programmierung Drag&Drop im WAN-Umfeld Lifetime Management Automation Queue Synchronisation der Automation Queue Fehlerbehandlung bei der Synchronisation Services rund um die Automation Queue Verwendung von Controls im WAN Anlegen eines Controls am Beispiel des SAP Picture Methoden der Klasse CL_GUI_CFW dispatch flush get_living_dynpro_controls set_new_ok_code update_view Methoden der Klasse CL_GUI_OBJECT is_valid free Methoden der Klasse CL_GUI_CONTROL...55 constructor finalize set_registered_events get_registered_events is_alive set_alignment set_position set_visible get_focus set_focus get_height get_width Methoden der Klasse CL_DRAGDROP constructor add April 2001

5 SAP AG clear destroy get get_handle modify remove Methoden der Klasse CL_DRAGDROPOBJECT set_flavor abort April

6 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

7 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

8 SAP AG Architektur des Control Frameworks 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 Instanzen Automation Queue Custom Control 1 Custom Control 2 OK_CODE GUI-RFC OO Control Framework Automation Queue Ereignisse Instanzen Applikationsprogramm 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

9 SAP AG Architektur des Control Frameworks 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

10 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

11 SAP AG Ereignisbehandlung SAPGUI Automation Controller Ereignisse: Ereignis Control DoppelKlick Control Control OO-Control Framework Ereignisse: Ereignis Control Behandler DoppelKlick Control DoppelKlick Applikationsprogramm CALL METHOD control->set_registered_events SET HANDLER handler->doppelklick FOR control. Funktionsumfang Applikationsserver 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

12 SAP AG Ereignisbehandlung SAPGUI Automation Controller Ereignisse: Ereignis Control DoppelKlick Control Ereignis DoppelKlick des Controls Control Control OO-Control Framework Ereignisse: Ereignis Control Behandler DoppelKlick Control DoppelKlick Applikationsprogramm CLASS lcl_handler IMPLEMENTATION. METHOD DoubleKlick. * DO SOMETHING ENDMETHOD. ENDCLASS. Applikationsserver 12 April 2001

13 SAP AG Registrieren und Verarbeiten von Ereignissen Registrieren und Verarbeiten von Ereignissen Einsatzmöglichkeiten Ü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

14 SAP AG Registrieren und Verarbeiten von Ereignissen 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

15 SAP AG Kontextmenü Kontextmenü Verwendung Kontextmenüs werden im SAP GUI for HTML nicht unterstützt. 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

16 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 Control- Verschalungen 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 ADD_MENU ADD_SUBMENU ADD_SEPARATOR RESET HIDE FUNCTIONS SHOW_FUNCTIONS DISABLE_FUNCTIONS ENABLE_FUNCTIONS Hinzufügen einer Funktion Hinzufügen eines im Menu Painter definierten Menüs Hinzufügen eines im Menu Painter definierten Menüs als Submenü Hinzufügen einer Trennlinie Zurücksetzen auf Initialwert Ausblenden einer Funktion Einblenden einer Funktion Deaktivieren einer Funktion 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

17 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&Drop- Ereignisse 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&Drop- Situation 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

18 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

19 SAP AG Ablauf einer Drag&Drop Operation 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&Drop- Verhalten 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

20 SAP AG Ablauf einer Drag&Drop Operation 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

21 SAP AG Ereignisse bei Drag&Drop 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 Control- Verschalung 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&Drop- Datenobjekt 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

22 SAP AG Ereignisse bei Drag&Drop 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. 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. 22 April 2001

23 SAP AG Beispiel für Drag&Drop-Programmierung 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

24 SAP AG Beispiel für Drag&Drop-Programmierung 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 = ' ' effect = cl_dragdrop=>copy. 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' effect = cl_dragdrop=>copy. CALL METHOD behaviour_right->add EXPORTING flavor = 'Tree_copy_to_Edit' dragsrc = ' ' droptarget = 'X' effect = cl_dragdrop=>copy. CALL METHOD editor->set_dragdrop EXPORTING dragdrop = behaviour_right. 24 April 2001

25 SAP AG Beispiel für Drag&Drop-Programmierung * 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 APPEND node TO node_itab. 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 APPEND node TO node_itab. 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

26 SAP AG Beispiel für Drag&Drop-Programmierung 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. CALL METHOD dragdrop_object->abort. 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 CALL METHOD dragdrop_object->abort. 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

27 SAP AG delete node_itab where node_key = node_key. ENDIF. ENDMETHOD. ENDCLASS. Beispiel für Drag&Drop-Programmierung April

28 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 Byte. Solange die Anzahl der Instanzen der Klasse CL_DRAGDROP nicht zu groß wird ( < 100), ist kein Problem zu erwarten. Der Kommunikations- Overhead 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

29 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

30 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

31 SAP AG Automation Queue Automation Queue Verwendung Die Kommunikation zwischen Automation Controller und OO Control Framework wird über GUI- RFC-Aufrufe abgewickelt: SAPGUI Automation Controller Custom Control 1 Automation Queue Custom Control 2 OK_CODE GUI-RFC OO Control Framework Automation Queue Applikationsprogramm 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 SAP- Systems 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

32 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

33 SAP AG Synchronisation der Automation Queue Synchronisation der Automation Queue Einsatzmöglichkeiten 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 Performance- Monitor. 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 Synchronisation der Automation Queue Verarbeitung / Berechnungen Setzen von Eigenschaften der Controls Gepuffertes Setzen von Eigenschaften auf den Controls April

34 SAP AG Synchronisation der Automation Queue Synchronisation der Automation Queue 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

35 SAP AG Fehlerbehandlung bei der Synchronisation Fehlerbehandlung bei der Synchronisation Einsatzmöglichkeiten 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. Ablauf 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. 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

36 SAP AG Fehlerbehandlung bei der Synchronisation class-methods error FOR EVENT flush_error OF cl_gui_cfw IMPORTING DYNPRO_PROGRAM DYNPRO_NUMBER SITUATION. ENDCLASS. Ereignisparameter Parameter DYNPRO_PROGRAM DYNPRO_NUMBER SITUATION Bedeutung Programmname des Programms, in dem der Fehler aufgetreten ist Dynpronummer, auf der der Fehler aufgetreten ist 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

37 SAP AG Services rund um die Automation Queue 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

38 SAP AG Services rund um die Automation Queue 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

39 SAP AG Services rund um die Automation Queue Automation Trace Sie können einen Trace über die Automation Queue erstellen. Dazu wird in den SAP-GUI- Einstellungen 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

40 SAP AG Services rund um die Automation Queue 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 = ' Im Automation Trace entspricht dies folgenden Zeilen: 40 April 2001

41 SAP AG Services rund um die Automation Queue April

42 SAP AG Verwendung von Controls im WAN 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

43 SAP AG Verwendung von Controls im WAN 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 LAN- Anmeldung 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

44 SAP AG Anlegen eines Controls am Beispiel des SAP Picture 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

45 SAP AG Anlegen eines Controls am Beispiel des SAP Picture 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 = 1 cntl_system_error = 2. CALL METHOD container->free EXCEPTIONS cntl_error = 1 cntl_system_error = 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

46 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

47 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 return_code Bedeutung 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

48 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

49 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 control_list Bedeutung Liste der Referenzvariablen zu aktiven Custom Controls. Liste ist vom Typ CNTO_CONTROL_LIST (in der Klasse CL_GUI_CFW definiert) April

50 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 new_code return_code Bedeutung Funktionscode, der in das OK_CODE-Feld (SY-UCOMM) gestellt werden soll. 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

51 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

52 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

53 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 result Bedeutung 0: Custom Control ist nicht mehr am Frontend aktiv 1: Custom Control ist noch aktiv April

54 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 EXCEPTIONS cntl_error = 1 cntl_system_error = April 2001

55 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

56 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 EXCEPTIONS cntl_error = 1 cntl_system_error = 2 create_error = 3 lifetime_error = 4. Parameter clsid lifetime shellstyle parent Bedeutung ID der Klasse 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. 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. Container, in dem das SAP Picture Control angezeigt werden kann (siehe SAP Container [Extern]) 56 April 2001

57 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

58 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

59 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 EXCEPTIONS cntl_error = 1 cntl_system_error = 2 illegal_event_combination = 3. Parameter events Bedeutung 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 EVENTID APPL_EVENT Bedeutung Name des Ereignisses 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

60 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 events Bedeutung 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 EVENTID APPL_EVENT Bedeutung Name des Ereignisses 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 s unter Ereignisbehandlung [Seite 10]. 60 April 2001

61 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 state Bedeutung 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

62 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 EXCEPTIONS cntl_error = 1 cntl_system_error = 2. Parameter alignment Bedeutung Ausrichtung des Controls Der Parameter alignment kann aus Kombinationen folgender Ausrichtungen bestehen: Name my_control->align_at_left my_control->align_at_right my_control->align_at_top my_control->align_at_bottom Bedeutung Ausrichtung am linken Rand Ausrichtung am rechten Rand Ausrichtung am oberen Rand 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

63 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 EXCEPTIONS cntl_error = 1 cntl_system_error = 2. Parameter height left top width Bedeutung Höhe des Controls Linker Rand des Controls Oberer Rand des Controls Breite des Controls April

64 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 EXCEPTIONS cntl_error = 1 cntl_system_error = 2. Parameter visible Bedeutung X: Custom Control ist sichtbar ' ': Custom Control ist nicht sichtbar 64 April 2001

65 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 EXCEPTIONS cntl_error = 1 cntl_system_error = 2. Parameter control Bedeutung Objektreferenz (TYPE REF TO cl_gui_control) auf das Control, das den Fokus hat April

66 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 EXCEPTIONS cntl_error = 1 cntl_system_error = 2. Parameter control Bedeutung Objektreferenz (TYPE REF TO cl_gui_control) auf das Control, das den Fokus bekommen soll 66 April 2001

67 SAP AG get_height get_height Diese Methode liefert die Höhe des Controls zurück. CALL METHOD control->get_height IMPORTING height = height EXCEPTIONS cntl_error = 1. Parameter height Bedeutung Aktuelle Höhe des Controls April

68 SAP AG get_width get_width Diese Methode liefert die Breite des Controls zurück. CALL METHOD control->get_width IMPORTING width = width EXCEPTIONS cntl_error = 1. Parameter width Bedeutung Aktuelle Breite des Controls 68 April 2001

69 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

70 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

71 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 flavor dragsrc droptarget effect effect_in_ctrl Bedeutung Bezeichnung des neuen Flavors 'X': Beschreibung ist eine Drag-Quelle 'X': Beschreibung ist ein Drop-Ziel 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 Drop-Effekt der Beschreibung im gleichen 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 dragdrop->use_default_effect: Es wird der gleiche Effekt benutzt, der durch den Parmeter effect spezifiziert wurde Ausnahmen allready_defined obj_invalid Bedeutung Der angegebene Flavor wurde bereits definiert. Das Objekt wurde bereits mit der Methode destroy [Seite 74] zerstört April

72 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

73 SAP AG clear clear Der Inhalt der Instanz wird gelöscht. Nach Aufruf dieser Methode können keine Drag&Drop- Vorgänge mehr auf dem betroffenen Custom Control durchgeführt werden. CALL METHOD dragdrop->clear EXCEPTIONS obj_invalid = 1. Ausnahmen obj_invalid Bedeutung Das Objekt wurde bereits mit der Methode destroy [Seite 74] zerstört April

74 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

75 SAP AG get get Diese Methode liefert die komplette Beschreibung zu einem Flavor zurück. CALL METHOD dragdrop->get EXPORTING flavor = flavor IMPORTING isdragsrc = isdragsrc isdroptarget = isdroptarget effect = effect effect_in_ctrl = effect_in_ctrl EXCEPTIONS not_found = 1 obj_invalid = 2. Parameter flavor dragsrc droptarget effect effect_in_ctrl Bedeutung Bezeichnung des Flavors 'X': Beschreibung ist eine Drag-Quelle 'X': Beschreibung ist ein Drop-Ziel 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 Drop-Effekt der Beschreibung im gleichen 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 dragdrop->use_default_effect: Es wird der gleiche Effekt benutzt, der durch den Parmeter effect spezifiziert wurde Ausnahmen allready_defined Bedeutung Der angegebene Flavor wurde bereits definiert. Wird bei der Definition des Flavors sowohl der Effekt copy als auch move benutzt, 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

76 SAP AG get 76 April 2001

77 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 handle Bedeutung Handle auf die Drag&Drop-Beschreibung Ausnahmen obj_invalid Bedeutung Das Objekt wurde bereits mit der Methode destroy [Seite 74] zerstört April

78 SAP AG modify modify Mit dieser Methode können Sie einen bestehenden Flavor verändern. CALL METHOD dragdrop->modify EXPORTING flavor = flavor dragsrc = dragsrc droptarget = droptarget effect = effect effect_in_ctrl = effect_in_ctrl EXCEPTIONS not_found = 1 obj_invalid = 2. Parameter flavor dragsrc droptarget effect effect_in_ctrl Bedeutung Bezeichnung des Flavors 'X': Beschreibung ist eine Drag-Quelle 'X': Beschreibung ist ein Drop-Ziel 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 Drop-Effekt der Beschreibung im gleichen 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 dragdrop->use_default_effect: Es wird der gleiche Effekt benutzt, der durch den Parmeter effect spezifiziert wurde Ausnahmen not_found obj_invalid Bedeutung Der angegebene Flavor existiert nicht Das Objekt wurde bereits mit der Methode destroy [Seite 74] zerstört Wird bei der Definition des Flavors sowohl der Effekt copy als auch move benutzt, 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

79 SAP AG modify April

80 SAP AG remove remove Mit dieser Methode löschen Sie einen bestimmten Flavor. CALL METHOD dragdrop->remove EXPORTING flavor = flavor EXCEPTIONS not_found = 1 obj_invalid = 2. Parameter flavor Bedeutung Bezeichnung des Flavors Ausnahmen not_found obj_invalid Bedeutung Der angegebene Flavor existiert nicht Das Objekt wurde bereits mit der Methode destroy [Seite 74] zerstört 80 April 2001

81 SAP AG Methoden der Klasse CL_DRAGDROPOBJECT Methoden der Klasse CL_DRAGDROPOBJECT Die Klasse CL_DRAGDROPOBJECT dient zur Beschreibung des Kontextes eines Drag&Drop- Vorgangs [Seite 17]. Er beinhaltet in der Regel Informationen zu dem Quellobjekt, den Flavor des Drag&Drop-Vorgangs und Informationen zu Quelle und Ziel. April

82 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 newflavor Bedeutung Bezeichnung des Flavors Ausnahmen invalid_state obj_invalid Bedeutung Die Methode wurde nicht innerhalb der Ereignisbehandlung ONGETFLAVOR aufgerufen. Es wurde ein Flavor verwendet, der nicht von der aktuellen Drag&Drop- Situation unterstützt wird. 82 April 2001

83 SAP AG abort abort Der Drag&Drop-Vorgang wird sofort abgebrochen. Es werden keine weiteren Ereignisse ausgelöst. CALL METHOD dragdropobject->abort. April