SAP Control Framework

SAP Control Framework

Release 4 .6C

HE

LP

.BC

CIG

OF

SAP Control Framework SAP AG

2 April 2001

Copyright

© Copyright 2001 SAP AG. Alle Rechte vorbehalten.

Weitergabe und Vervielfältigung dieser Publikation oder von Teilen daraus sind, zu welchemZweck und in welcher Formauch immer, ohne die ausdrückliche schriftliche Genehmigung durch SAP AG nicht gestattet. Indieser Publikation enthaltene Informationen können ohne vorherige Ankündigung geändertwerden.

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 eingetrageneMarken derMicrosoft 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 ServerTM

sind eingetragene Marken derInformix 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 WideWeb 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 derLizenz 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.comsind Marken oder eingetragene Marken der SAP AG in Deutschland und vielen anderen Ländernweltweit. Alle anderen Produkte sind Marken oder eingetragene Marken der jeweiligen Firmen.

SAP AG SAP Control Framework

April 2001 3

Symbole

Symbol Bedeutung

Achtung

Beispiel

Empfehlung

Hinweis

Syntax

Tip


4 April 2001

Inhalt

SAP Control Framework................................................................................................ 6Architektur des Control Frameworks ........................................................................................................ 8Ereignisbehandlung .................................................................................................................................. 10

Registrieren und Verarbeiten von Ereignissen....................................................................................... 13Kontextmenü .......................................................................................................................................... 15Drag&Drop.............................................................................................................................................. 17

Ablauf einer Drag&Drop Operation ................................................................................................... 19Ereignisse bei Drag&Drop................................................................................................................. 21Beispiel für Drag&Drop-Programmierung ......................................................................................... 23Drag&Drop im WAN-Umfeld ............................................................................................................. 28

Lifetime Management ................................................................................................................................ 29Automation Queue..................................................................................................................................... 31

Synchronisation der Automation Queue................................................................................................. 33Fehlerbehandlung bei der Synchronisation............................................................................................ 35Services rund um die Automation Queue............................................................................................... 37

Verwendung von Controls im WAN ......................................................................................................... 42Anlegen eines Controls am Beispiel des SAP Picture .......................................................................... 44Methoden der Klasse CL_GUI_CFW ........................................................................................................ 46dispatch ...................................................................................................................................................... 47flush ............................................................................................................................................................ 48get_living_dynpro_controls...................................................................................................................... 49set_new_ok_code ...................................................................................................................................... 50update_view ............................................................................................................................................... 51Methoden der Klasse CL_GUI_OBJECT.................................................................................................. 52is_valid........................................................................................................................................................ 53free .............................................................................................................................................................. 54Methoden der Klasse CL_GUI_CONTROL .............................................................................................. 55constructor................................................................................................................................................. 56finalize......................................................................................................................................................... 58set_registered_events............................................................................................................................... 59get_registered_events............................................................................................................................... 60is_alive........................................................................................................................................................ 61set_alignment............................................................................................................................................. 62set_position................................................................................................................................................ 63set_visible................................................................................................................................................... 64get_focus.................................................................................................................................................... 65set_focus .................................................................................................................................................... 66get_height................................................................................................................................................... 67get_width .................................................................................................................................................... 68Methoden der Klasse CL_DRAGDROP.................................................................................................... 69constructor................................................................................................................................................. 70add............................................................................................................................................................... 71


April 2001 5

clear............................................................................................................................................................. 73destroy........................................................................................................................................................ 74get................................................................................................................................................................ 75get_handle.................................................................................................................................................. 77modify ......................................................................................................................................................... 78remove ........................................................................................................................................................ 80Methoden der Klasse CL_DRAGDROPOBJECT..................................................................................... 81set_flavor.................................................................................................................................................... 82abort ............................................................................................................................................................ 83



6 April 2001

SAP Control FrameworkEinsatzmöglichkeitenDas SAP-System erlaubt das Ansteuern von Desktop-Applikationen (Custom Controls) mit Hilfevon 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 ActiveXControls und JavaBeans sein.

Das folgende Beispiel zeigt ein SAP Tree Control in Kombination mit einem SAP TextEditControl:

FunktionsumfangDas beschriebene Framework unterstützt Controls (ActiveX und JavaBeans), die innerhalb desSAP 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 Containerfü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



April 2001 7

Controls als auch das Setzen und Lesen von deren Eigenschaften und den Aufruf dererMethoden ermöglichen.

Mit Blick auf die Performance in Client-Server-Umgebungen werden Puffermechanismen überdie Automation Queue unterstützt, mit der eine Serie von Methodenaufrufen zuunterschiedlichen Instanzen von Custom Controls in einem Kommunikationsschritt zum Frontendgeschickt werden kann.

Die Interpretation von Ereignissen, die auf einem Custom Control ausgelöst werden, erfolgt inzwei Schritten:

• Ausfiltern der nicht relevanten Ereignisse

• Weiterreichen der relevanten Ereignisse an den Applikationsserver. Ihr ABAP-Programmerhält dann an definierter Stelle über ein OO-Ereignis die Kontrolle und kann auf das Ereignisreagieren.

Die Lebensdauer eines Controls wird über das Lifetime Management geregelt. Es baut Controlsautomatisch am Frontend ab. Natürlich wird auch ein explizites Abbauen von Controls durch dasApplikationsprogramm unterstützt.

EinschränkungenBestimmte Methoden und Ereignisse in einigen Controls werden nicht unter dem SAP GUI forHTML unterstützt. Andere stehen nur in eingeschränkter Form zur Verfügung. Einzelheitenhierzu entnehmen Sie der Dokumentation zum jeweiligen Control.


Architektur des Control Frameworks

8 April 2001

Architektur des Control FrameworksDas SAP-System erlaubt das Ansteuern von Desktop-Applikationen (Custom Controls) mit Hilfevon ABAP. Der Applikationsserver ist der Automation Client, welcher die Custom Controls(Automation Server) am Frontend treibt. Das SAP GUI (SAPGUI.APPLICATION) dient alsContainer für die Custom Controls.

In der folgenden Grafik sind die beteiligten Elemente und ihre Kommunikationskanäle dargestellt:

SAPGUI

Applikationsserver

Custom Control 1

Custom Control 2Instanzen

EreignisseAutomationController

GUI-RFCOK_CODE

Applikations-programm

OO ControlFramework

Ereignisse

Instanzen

Automation Queue

Automation Queue

Automation ControllerDer Automation Controller ist die zentrale Instanz auf dem Frontend. Er verwaltet alle Instanzender Custom Controls.

Weiterhin enthält der Automation Controller eine Liste der relevanten Ereignisse, die von einemCustom Control ausgelöst werden können (siehe Ereignisbehandlung [Seite 10]).

Die gesamte Kommunikation zwischen den Controls am Frontend und demApplikationsprogramm am Backend läuft über den Automation Controller.

OO Control FrameworkAnalog zum Automation Controller existiert am Backend das OO Control Framework. AlleMethodenaufrufe aus einem Applikationsprogramm an ein Custom Control laufen über dasControl Framework. Damit nicht bei jedem Methodenaufruf eine Verbindung zum Frontendaufgebaut werden muß, werden die Methodenaufrufe in der Automation Queue gepuffert. Erstbeim Synchronisationspunkt wird dann die Automation Queue mit dem Frontend synchronisiert(Siehe Automation Queue [Seite 31]).


Architektur des Control Frameworks

April 2001 9

Das Control Framework besitzt wie auch der Automation Controller eine Liste der relevantenControl-Ereignisse. In dieser Liste sind zusätzlich die aufzurufenden Behandlermethodenhinterlegt (siehe Ereignisbehandlung [Seite 10]).

Auch eine Liste der angelegten Control-Instanzen wird im Control Framework gehalten. DieseListe dient auch als Grundlage für das Lifetime Management der Controls (siehe LifetimeManagement [Seite 29]).


Ereignisbehandlung

10 April 2001

EreignisbehandlungVerwendungDer Benutzer eines Applikationsprogramms kann Ereignisse auf Custom Controls auslösen. DasApplikationsprogramm bekommt dann die Kontrolle und kann auf das Ereignis reagieren.

Typische Ereignisse sind z.B. Doppelklick und Drag & Drop.

IntegrationWie in Architektur des Control Frameworks [Seite 8] angedeutet, besitzt sowohl der AutomationController als auch das OO Control Framework eine Tabelle aller relevanten Control-Ereignisse.Diese Tabellen müssen vom Applikationsprogramm aufgebaut werden. Die Ereignistabelle amFrontend besteht aus Control-Instanz und Ereignis, am Backend enthält die Ereignistabellezusä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ß dieApplikation festlegen, ob das Ereignis als Systemereignis oder als Applikationsereignisinterpretiert 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 nichtdurchlaufen. 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. Daherwerden Werte, die Sie aufgrund des Ereignisses verändert haben, nicht auf dem Dynproaktualisiert.

Die zum Ereignis definierte Behandlermethode wird automatisch vom Systemaufgerufen. Mit der Methode set_new_ok_code [Seite 50] haben Sie allerdings dieMöglichkeit, PAI und PBO auszulösen und einen OK_CODE zu setzen, den Sie dann ineinem PAI-Modul interpretieren können.

• Applikationsereignis: Das Ereignis wird zum Zeitpunkt PAI verarbeitet. Daher wurden alleFeldprüfungen durchgeführt, und auch der Feldtransport hat stattgefunden. Sofern Sie dieBehandlermethode 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 überdas ABAP-Sprachelement SET HANDLER eine Behandlermethode registrieren. DieBehandlermethode muß in dem Applikationsprogramm als Methode einer (lokalen) Klasseangelegt werden. Es steht Ihnen frei, die Behandlermethode als Instanzmethode oder statischeMethode anzulegen.


Ereignisbehandlung

April 2001 11

SAPGUI

Applikationsserver

Control

Automation Controller

OO-Control FrameworkEreignisse: Ereignis Control BehandlerDoppelKlick Control DoppelKlick

ApplikationsprogrammCALL METHOD

control->set_registered_events

Ereignisse:Ereignis ControlDoppelKlick Control

SET HANDLER handler->DoppelKlick FOR control.

FunktionsumfangWird auf einem Custom Control ein Ereignis ausgelöst, überprüft der Automation Controller, obdieses Ereignis in seiner Tabelle registriert wurde. Wurde das Ereignis nicht registriert, wird dasEreignis vom Automation Controller ignoriert. Wurde es dagegen registriert, generiert derAutomation 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 nachAufruf der statischen Methode CL_GUI_CFW=>DISPATCH (bei einem Applikationsereignis) diezum Ereignis registrierte Behandlermethode aufgerufen. Dabei wird über den Ereignisparametersender die Objektreferenz des Controls, welches das Ereignis ausgelöst hat, an dieBehandlermethode übergeben.

Die statische Methode CL_GUI_CFW=>DISPATCH muß zur Auswertung vonApplikationsereignissen innerhalb der PAI-Module aufgerufen werden.

Der OK_CODE eines Ereignisses wird durch den Aufruf der MethodeCL_GUI_CFW=>DISPATCH "verbraucht". Daher führt ein zweiter Aufruf der Methodenicht 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 Behandlermethodeweitergeleitet werden konnte.


Ereignisbehandlung

12 April 2001

SAPGUI

Applikationsserver

Control

Automation Controller

OO-Control FrameworkEreignisse: Ereignis Control BehandlerDoppelKlick Control DoppelKlick

ApplikationsprogrammCLASS lcl_handler IMPLEMENTATION.

Ereignisse:Ereignis ControlDoppelKlick Control

METHOD DoubleKlick.* DO SOMETHINGENDMETHOD.ENDCLASS.

EreignisDoppelKlickdes Controls

Control


Registrieren und Verarbeiten von Ereignissen

April 2001 13

Registrieren und Verarbeiten von EreignissenEinsatzmöglichkeitenÜber den Ereignismechanismus des Control Frameworks können Sie in Ihrem Programm inBehandlermethoden auf Ereignisse reagieren, die auf dem Control ausgelöst wurden (z.B.Doppelklick).

VoraussetzungenDer Ablauf wurde allgemeingültig für alle Custom Controls gehalten. Control-spezifischeInformationen finden Sie in der jeweiligen Dokumentation zu der Control-Verschalung.

Ablauf1. 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 Framework2. 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 dieIdentifikation des Ereignisses (event_id). Diese Information finden Sie wiederum in derKlassenbibliothek in den Attributen der Klasse cl_gui_xyz. Weiterhin müssen Sie sichentscheiden, ob das Ereignis als Systemereignis (appl_event = ' ') oder alsApplikationsereignis (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 dierelevanten Ereignisse vom Frontend an das Backend weitergeleitet werden.

CALL METHOD my_control->set_registered_eventsevents = events.

Um auf ein Ereignis Ihres Custom Controls eingehen zu können, müssen Sie nun noch eineBehandlermethode angeben. Die Behandlermethode kann eine Instanzmethode oder einestatische Methode sein:

Behandlung des Ereignisses als Instanzmethode5. Definieren Sie die (lokale) Klassendefinition für den Ereignisbehandler. Dabei legen Sie den

Namen der Ereignisbehandlermethode fest (Event_Handler). Als Information müssen Siesich in der Klassenbibliothek für die Klasse des Custom Controls cl_gui_xyz den Namendes Ereignisses (event_name) und die zu diesem Ereignis gehörenden Ereignisparameter(event_parameter) besorgen. Der Ereignisparameter sender wird bei jedem Ereignis zur


Registrieren und Verarbeiten von Ereignissen

14 April 2001

Verfügung gestellt. Der Parameter enthält die Referenz des Controls, das dieses Ereignisausgelöst hat.

CLASS lcl_event_receiver DEFINITION.PUBLIC SECTION.METHODS Event_Handler

FOR EVENT event_name OF cl_gui_xyzIMPORTING event_parameter

sender.ENDCLASS.

6. Melden Sie jetzt noch für die registrierten Ereignisse Behandlermethoden beim OO ControlFramework 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 Methode7. Definieren Sie die (lokale) Klassendefinition für den Ereignisbehandler. Dabei legen Sie den

Namen der statischen Ereignisbehandlermethode fest (Event_Handler). Als Informationmüssen Sie sich in der Klassenbibliothek für die Klasse des Custom Controls cl_gui_xyzden Namen des Ereignisses (event_name) und die zu diesem Ereignis gehörendenEreignisparameter (event_parameter) besorgen.

CLASS lcl_event_receiver DEFINITION.PUBLIC SECTION.CLASS-METHODS Event_Handler

FOR EVENT event_name OF cl_gui_xyzIMPORTING event_parameter

sender.ENDCLASS.

8. Melden Sie jetzt noch für die registrierten Ereignisse Behandlermethoden beim OO ControlFramework an.

SET HANDLER lcl_event_receiver=>Event_HandlerFOR my_control.

Verarbeiten von Control-Ereignissen9. Wie Sie auf ein Ereignis reagieren wollen, legen Sie im Implementierungsteil der

Behandlermethode fest.CLASS lcl_event_receiver IMPLEMENTATION.METHOD Event_Handler.* Abarbeitung des EreignissesENDMETHOD.ENDCLASS.

10. Je nach Art des Ereignisses (System- oder Applikationsereignis) müssen Sie jetzt noch dieMethode CL_GUI_CFW=>DISPATCH aufrufen. Lesen Sie dazu Ereignisbehandlung [Seite10].


Kontextmenü

April 2001 15

Kontextmenü

Kontextmenüs werden im SAP GUI for HTML nicht unterstützt.

VerwendungDas Kontextmenü (Rechte Maustaste, SHIFT F10) ermöglicht das Anzeigen vonkontextsensitiven Menüs. Der Kontext wird über den Ort definiert, an dem der Benutzer dasKontextmenü aufgerufen hat

Der Benutzer kann über das Kontextmenü Funktionen auswählen, die für den aktuellen Kontextrelevant sind.

FunktionsumfangSoll auf einem Custom Controls ein Kontextmenü implementiert werden, muß das Ereignis fürdas Anfordern eines Kontextmenüs (Ereignis context_menu) registriert werden. Das Ereignisfür das Auswählen eines Eintrags des Kontextmenüs (Ereignis context_menu_selected) wirdentweder von der Control-Verschalung automatisch registriert (z.B. SAP Tree) oder muß explizitregistriert werden (z.B. SAP Picture).

Fordert der Benutzer auf einem Objekt ein Kontextmenü an, wird über den normalenEreignismechanismus [Seite 10] das Anwendungsprogramm aufgerufen. In derEreignisbehandlermethode zum Ereignis context_menu erhält das Programm alsEreignisparameter eine Menüreferenz. Das Programm benutzt diese Menüreferenz, um dasanzuzeigende Menü aufzubauen. Dabei können mit dem Menu Painter definierte Menüs oderdynamisch aufgebaute Menüs benutzt werden. Nach Verlassen der Ereignisbehandlermethodewird das Kontextmenü automatisch angezeigt.

Das SAP Picture bildet eine Ausnahme. Hier bekommen Sie keine Menüreferenz alsEreignisparameter ü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 Applikationeine Behandlermethode registrieren. In der Behandlermethode wird der übergebeneFunktionscode 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. DieIdentifikation des Ereignisses ist von der jeweiligen Control-Verschalung abhängig und wirdin der dazugehörigen Dokumentation beschrieben.

• Weiterhin muß die Applikation Methoden zur Ereignisbehandlung der beiden Ereignissedefinieren.


Kontextmenü

16 April 2001

Der SAP Tree bildet eine Ausnahme bei der Registrierung der Ereignisse. Hier mußnur das Ereignis context_menu registriert werden. Das Ereigniscontext_menu_selected wird automatisch von der Control-Verschalungmitregistriert.

Aufbau des KontextmenüsIn 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 Kontextdas 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 einObjekt 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 BedeutungLOAD_GUI_STATUS Laden eines im Menu Painter vordefinierten Kontextmenüs (siehe

unten)ADD_FUNCTION Hinzufügen einer FunktionADD_MENU Hinzufügen eines im Menu Painter definierten MenüsADD_SUBMENU Hinzufügen eines im Menu Painter definierten Menüs als SubmenüADD_SEPARATOR Hinzufügen einer TrennlinieRESET Zurücksetzen auf InitialwertHIDE FUNCTIONS Ausblenden einer FunktionSHOW_FUNCTIONS Einblenden einer FunktionDISABLE_FUNCTIONS Deaktivieren einer Funktion

ENABLE_FUNCTIONS Aktivieren einer Funktion

Nach dem Verlassen der Ereignisbehandlermethode wird das Kontextmenü automatischangezeigt. Ausnahmen bilden hier das SAP Picture Control und das SAP Toolbar Control. Beidiesen muß das Kontextmenü explizit über die Methode display_context_menu [Extern] zurAnzeige gebracht werden.

Auswerten des FunktionscodesDie Interpretation des ausgewählten Menüpunktes erfolgt in der Behandlermethode zum Ereigniscontext_menu_selected. Über den Funktionscode wird das ausgewählte Menü identifiziertund eine entsprechende Reaktion ausgeführt.


Drag&Drop

April 2001 17

Drag&DropVerwendungMit 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 nachObjekt wird dann im zweiten Bereich eine Aktion ausgeführt. Quelle und Ziel können dabei dasgleiche Control oder zwei unterschiedliche Controls sein.

VoraussetzungenDamit Controls Drag&Drop-fähig sind, muß die Control-Verschalung zusätzliche Drag&Drop-Ereignisse anbieten. Das Anwendungsprogramm muß für diese Ereignisse Behandlerroutinenimplementieren. Die Registrierung auf die Ereignisse erfolgt automatisch über die jeweiligeControl-Verschalung.

FunktionsumfangFür jedes beteiligte Custom Control wird das Drag&Drop-Verhalten festgelegt. Je nach Controlwird das Verhalten auf alle Elemente des Controls bezogen (z.B. Editor), oder man kann fürjedes Teilobjekt ein eigenes Verhalten definieren (z.B. Tree). Jedes Verhalten besteht aus eineroder 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 einegemeinsame Beschreibung besitzen.

• Effect: Beschreibung, ob die Daten beim Drag&Drop-Vorgang kopiert und/oder verschobenwerden können

• Effect_In_Ctrl: Mit welchem Drop-Effekt können Daten innerhalb des gleichen Controlsverschoben oder kopiert werden.

Sobald ein Drag-Ereignis ausgelöst wird, muß die Applikation in der entsprechendenBehandlermethode feststellen, welches Objekt von dem Ereignis betroffen ist.

Weiterhin muß für das Drop-Ereignis implementiert werden, welche Aktionen durchgeführtwerden sollen. Die Aktionen sind dabei in der Regel abhängig von dem Objekt, das in dasControl fallengelassen wurde.

Wurden einem Objekt mehrere Flavors zugeordnet, muß zu einem speziellen Ereignis festgelegtwerden, welcher Flavor benutzt werden soll.

Nachdem das Drop-Ereignis abgeschlossen ist, können in einem zusätzlichen Ereignis weitereAktionen durchgeführt werden. Dieses Ereignis bietet sich insbesondere beim Verschieben desQuellobjekts an, um dieses aus der Quelle zu löschen.


Drag&Drop

18 April 2001

AktivitätenWenn die Drag&Drop-Funktionalität benutzt wird, sollte auf jeden Fall auch eine UNDO-Funktionbereitgestellt werden, sofern die Drag&Drop-Funktion zu einem Verschieben des Objekts führt.Diese muß von der Anwendung implementiert werden.


Ablauf einer Drag&Drop Operation

April 2001 19

Ablauf einer Drag&Drop OperationVoraussetzungenIm folgenden wird aufgezeigt, wie die Drag&Drop Operation abläuft. Dabei wird auf die Rolle desApplikationsservers und des Frontends eingegangen. Aus diesem Ablauf leiten sich dann dieeinzelnen Schritte ab, die in einem Anwendungsprogramm durchgeführt werden müssen, damitDrag&Drop genutzt werden kann.

AblaufApplikationsserver1. 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 derenTeilobjekte. Dazu erzeugen Sie eines Instanz [Seite 70] der Klasse CL_DRAGDROP [Seite69]. 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 Flavorswä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-spezifischeMethoden. Lesen Sie dazu die jeweilige Control-Dokumentation.

FrontendDie nachfolgenden Schritte führt das System automatisch durch. Sie dienen nur zum Verständnisdes Drag&Drop-Vorgangs.

5. Nachdem der Benutzer mit der linken Maustaste ein Objekt ausgewählt hat, startet derDrag&Drop-Service.

6. Der Drag&Drop-Service überprüft, ob für das Objekt ein Drag&Drop-Verhalten definiertwurde 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. DerMauszeiger verändert sich dann automatisch.

8. Während der Benutzer die linke Maustaste gedrückt hält, wird ständig unter dem Mauszeigernachgefragt, 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 desMauszeigers signalisiert.

9. Läßt der Benutzer nun das Objekt fallen, wird dies über ein Ereignis an denApplikationsserver gemeldet.

Für das Frontend ist damit die Drag&Drop Operation abgeschlossen. Bisher wurdennoch keinerlei Veränderungen an den Inhalten der Custom Controls vorgenommen.


Ablauf einer Drag&Drop Operation

20 April 2001

Applikationsserver10. Der Drag&Drop-Service des Applikationsservers erzeugt eine Instanz der Klasse

CL_DRAGDROPOBJECT [Seite 81]. Diese Instanz (z.B. drag_drop_object) steht Ihnenin allen Ereignissen des Drag&Drop-Vorgangs als Ereignisparameter zur Verfügung unddient zum Übermitteln des Kontexts zwischen den Ereignissen.

11. Der Drag&Drop-Service prüft nach, ob das Drag-Objekt und das Drop-Objekt mehrereFlavors gemeinsam besitzen. Ist dies der Fall, wird das Ereignis ONGETFLAVOR ausgelöst. Inder dazugehörigen Behandlerroutine muß nun die Applikation entscheiden, welcher Flavorverwendet 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 Siedie relevanten Informationen, welches Objekt der Benutzer gezogen hat. Innerhalb derBehandlerroutine müssen Sie jetzt die in 9. angelegte Instanz des Drag&Drop-Datenobjektsmit 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 dasVerarbeiten des Drag&Drop-Datenobjekts. Hier müssen Sie implementieren, welcheÄnderungen in dem Zielobjekt aufgrund des Drag&Drop-Vorgangs vorgenommen werdensollen.

14. Das letzte Ereignis des Drag&Drop-Vorgangs ist ONDROPCOMPLETE. Hier sollte eventuelleine Nachbearbeitung des Drag&Drop-Datenobjekts erfolgen. Besonders für den Fall einerVerschiebeoperation sollte zu diesem Zeitpunkt das Quellobjekt aus dem DragSourceControl und den entsprechenden Datenstrukturen entfernt werden.

In Beispiel für Drag&Drop-Programmierung [Seite 23] finden Sie ein Beispiel, daseinen Drag&Drop-Vorgang zwischen einem SAP Tree und einem SAP TextEditbeschreibt.


Ereignisse bei Drag&Drop

April 2001 21

Ereignisse bei Drag&DropIm folgenden Abschnitt werden nur die allgemeingültigen Eigenschaften der Ereignisse beiDrag&Drop beschrieben. Diese können von den einzelnen Control-Verschalungen angereichertwerden. Daher sollten Sie auf jeden Fall auch in der Dokumentation zur jeweiligen Control-Verschalung die Besonderheiten des Controls nachlesen.

VerwendungIm Umfeld des Drag&Drop gibt es vier Standardereignisse, bei denen Sie die Kontrolle in IhremApplikationsprogramm bekommen können. In den Behandlerroutinen zu diesen Ereignissenimplementieren Sie, welche Aktionen bei einem Drag&Drop-Vorgang durchgeführt werden.

Bestimmte Control-Verschalungen können zusätzliche Drag&Drop-Ereignisseanbieten. Hinweise dazu finden Sie in der jeweiligen Dokumentation.

VoraussetzungenUm auf die Ereignisse reagieren zu können, müssen Sie sich auf sie registrieren. Im Gegensatzzu der normalen Ereignisbehandlung werden aber die Ereignisse nicht mit der Methodeset_registered_events [Seite 59] am Control Framework angemeldet. Die Registrierung erfolgtautomatisch ü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.

FunktionsumfangDas Control Framework reicht beim Drag&Drop erst zum Drop-Zeitpunkt ein Ereignis an denApplikationsserver weiter. Dieses wird dann am Applikationsserver, wie in Ablauf einerDrag&Drop-Operation [Seite 19] beschrieben, innerhalb eines Drag&Drop-Vorgangs in maximalvier Standardereignisse auseinandergesteuert. Alle Ereignisse haben ein Drag&Drop-Datenobjekt als Ereignisparameter. Über diesen Parameter müssen Sie den Kontext desDrag&Drop-Vorgangs verwalten. Weiterhin übergibt Ihnen die jeweilige Control-Verschalungweitere Informationen zu dem Drag&Drop-Kontext. Lesen Sie dazu die Dokumentation derControl-Verschalung.

• ONGETFLAVOR: Dieses Ereignis wird nur dann ausgelöst, wenn das Quellobjekt und dasZielobjekt über mehrere gemeinsame Flavors verfügen. Sie müssen dann in derBehandlermethode einen der gemeinsamen Flavors auswählen. Wenden Sie dazu dieMethode 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 amFrontend beendet ist. In diesem Ereignis müssen Sie den Kontext des Quellobjektsbestimmen. Diesen Kontext übergeben Sie dann an die als Ereignisparameter übergebeneInstanz der Klasse CL_DRAGDROPOBJECT.Das Ereignis wird von dem Quellobjekt des Drag&Drop-Vorgangs ausgelöst.


Ereignisse bei Drag&Drop

22 April 2001

• ONDROP: Zu diesem Ereignis definieren Sie die Aktionen, die im Zielobjekt durchgeführtwerden sollen. Dabei nutzen Sie den Ereignisparameter für den Kontext, den Sie zumEreignis ONDRAG gefüllt haben. Bei diesem Ereignis ist folgendes zu beachten:

− Innerhalb des ONDROP-Ereignisses muß ein dynamischer TypeCast durchgeführtwerden. Die mögliche Ausnahme des TypeCast muß auf jeden Fall abgefangen werden.Falls ein nicht passendes Objekt zugewiesen werden sollte, muß in derAusnahmebehandlung die Drag&Drop-Verarbeitung mit der Methode abort [Seite 83]abgebrochen werden.

− Die verwendeten Flavors sollten so gewählt werden, daß eine Zuordnung desDrag&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 weitereAktionen durchführen wollen, können Sie dies in diesem Ereignis realisieren. Dies ist z.B. imFalle einer Verschiebeoperation sinnvoll.Das Ereignis wird von dem Quellobjekt des Drag&Drop-Vorgangs ausgelöst.


Beispiel für Drag&Drop-Programmierung

April 2001 23

Beispiel für Drag&Drop-ProgrammierungDas Beispielprogramm geht von einem SAP Simple Tree Control und einem SAP TextEditControl aus. Von dem Tree Control soll eine Verschiebefunktion von Texten in das TextEditControl 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_texteditIMPORTING index line pos flavors dragdrop_object,

left_drag FOR EVENT on_drag OF cl_gui_simple_treeIMPORTING node_key drag_drop_object,

right_drop FOR EVENT ON_DROP OF cl_gui_texteditIMPORTING index line pos dragdrop_object,

drop_complete FOR EVENT on_drop_complete OF cl_gui_simple_treeIMPORTING node_key drag_drop_object.

ENDCLASS.START-OF-SELECTION.

CALL SCREEN 100.*&-------------------------------------------------------------------**& Module START OUTPUT*&-------------------------------------------------------------------*



24 April 2001

MODULE start OUTPUT.SET PF-STATUS 'BASE'.IF container is initial.

CREATE OBJECT containerEXPORTING container_name = 'CONTAINER'.

CREATE OBJECT splitterEXPORTING 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 = leftnode_selection_mode = tree->node_sel_mode_single.

* Definition of drag drop behaviour for treeCREATE OBJECT behaviour_left.CALL METHOD behaviour_left->add

EXPORTINGflavor = 'Tree_move_to_Edit'dragsrc = 'X'droptarget = ' 'effect = cl_dragdrop=>copy.

CALL METHOD behaviour_left->addEXPORTING

flavor = 'Tree_copy_to_Edit'dragsrc = 'X'droptarget = ' 'effect = cl_dragdrop=>copy.

CALL METHOD behaviour_left->get_handleIMPORTING 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_itabtable_structure_name = 'NODE_STR'.

* Definition of drag drop behaviour for treeCREATE OBJECT behaviour_right.

CALL METHOD behaviour_right->addEXPORTING

flavor = 'Tree_move_to_Edit'dragsrc = ' 'droptarget = 'X'effect = cl_dragdrop=>copy.

CALL METHOD behaviour_right->addEXPORTING

flavor = 'Tree_copy_to_Edit'dragsrc = ' 'droptarget = 'X'effect = cl_dragdrop=>copy.

CALL METHOD editor->set_dragdropEXPORTING dragdrop = behaviour_right.



April 2001 25

* registration of drag and drop eventsSET 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 behaviourAPPEND 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 behaviourAPPEND 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 flavorIF line > 5.

SEARCH flavors FOR 'Tree_move_to_Edit'.IF sy-subrc = 0.



26 April 2001

CALL METHOD dragDROP_OBJECT->SET_FLAVOREXPORTING 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_flavorEXPORTING 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 tableINSERT textline INTO text_table INDEX 1.

* Send modified table to frontendCALL METHOD editor->set_text_as_stream

EXPORTING text = text_tableEXCEPTIONS 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.



April 2001 27

delete node_itab where node_key = node_key.ENDIF.ENDMETHOD.

ENDCLASS.


Drag&Drop im WAN-Umfeld

28 April 2001

Drag&Drop im WAN-UmfeldBeim Drag&Drop erzeugt jeder Flavor jeder Instanz der Klasse CL_DRAGDROP einenKommunikations-Overhead von 20..70 Byte. Solange die Anzahl der Instanzen der KlasseCL_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 angelegtwerden, sondern für alle Objekte, die sich gleich verhalten sollen, wird die gleiche Instanzverwendet.


Lifetime Management

April 2001 29

Lifetime ManagementVerwendungDas Lifetime Management regelt die Lebensdauer eines Custom Controls am Frontend. Wenndie Lebensdauer abgelaufen ist, wird das Custom Control automatisch vom SAP-System amFrontend abgebaut. Dabei wird die Methode free [Seite 54] bzw. finalize [Seite 58] für dasControl vom System aufgerufen. Natürlich können Sie ein Control mit diesen Methoden auchprogrammgesteuert abbauen.

FunktionsumfangEs gibt zwei Einstellungen für die Lebensdauer eines Controls, die beim Instanzieren vergebenwerden:

• my_control->lifetime_imode: Das Control lebt, solange der interne Modus nichtabgebaut wird (leave program. leave transaction.) Die Anweisung set screen0, leave screen. baut den internen Modus nur dann ab, wenn keine andereDynproinstanz (erzeugt z.B. durch CALL SCREEN) mehr vorhanden ist. Danach wird dieMethode finalize [Seite 58] aufgerufen.

• my_control->lifetime_dynpro: Das Control lebt, solange die Instanz des Dynprosexistiert, 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. Controlswerden immer nur dann eingeblendet, wenn das Dynpro aktiv ist, auf dem sie erzeugtwurden. 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 dieseines 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, ..) oderwenn es in den Dynprostapel gestellt wird, da es der Nachfolger eines anderenDynpros ist.

Eine Instanz wird abgebaut, wenn das Nachfolgedynpro ein anderes als das Dynproder aktuellen Instanz ist (set screen 200 oder set screen 0).

Die Lebensdauer eines Controls wird in dem Attribut my_control->lifetime verwaltet.


Lifetime Management

30 April 2001

Mit der Methode is_alive [Seite 61] können Sie abfragen, ob ein instanziertes Control noch amFrontend existiert. Die Methode get_living_dynpro_controls [Seite 49] liefert eine Liste allerexistierenden Controls zurück.


Automation Queue

April 2001 31

Automation QueueVerwendung Die Kommunikation zwischen Automation Controller und OO Control Framework wird über GUI-RFC-Aufrufe abgewickelt:

SAPGUI

Applikationsserver

Custom Control 1

Custom Control 2

AutomationController

GUI-RFCOK_CODE

Applikations-programm

OO ControlFramework

Automation Queue

Automation Queue

Um die Netzlast zwischen dem Backend und dem Frontend gering zu halten, werden Aufrufevom Backend an das Frontend gepuffert und zu definierten Synchronisationspunkten an dasFrontend gesendet. Der Synchronisationspunkt wird durch nicht gepufferte Methodenaufrufeoder 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 dieVerbindung zum Präsentationsserver vom Applikationsserver beendet wird.

Die Pufferung von Operationen erhöht die Performance erheblich, da jede ungepufferteOperation eine RFC-Kommunikation mit dem Frontend auslöst. Allerdings sind insbesonderegepufferte Lesezugriffe auf ein Control mit größter Vorsicht zu behandeln, da eine falscheVerwendung zu einem Laufzeitfehler führen kann (siehe Fehlerbehandlung [Seite 35])!

Performance-HinweiseBei der Performance ist vor allem die Anzahl der Synchronisationspunkte zu beachten. In derDynproablauflogik wird auf jeden Fall nach PBO automatisch die Automation Queuesynchronisiert.


Automation Queue

32 April 2001

Da allerdings eine Fehlerbehandlung von Methoden erst nach dem Synchronisationspunktmöglich ist, ist ein Kompromiß zwischen Performance und Fehlerbehandlung zu schließen.

Weiterhin ist bei großen Datenmengen zu beachten, daß die Verbindung zwischen Applikations-und Präsentationsserver wegen Zeitüberschreitung nicht unterbrochen wird. In einem solchenFall müßten dann zusätzliche Synchronisationspunkte eingefügt werden.

Werkzeuge zur Unterstützung bei der Performace-Optimierung finden Sie unter Services rundum 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 Queueausführen

• Methoden, bei denen nie eine Synchronisation der Automation Queue ausgeführt wird. Hierist 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. DurchSynchronisation der Automation Queue wird deren Inhalt zum Frontend gesendet und dortausgeführt. Das Ergebnis wird dann an das Backend zurückgemeldet:

Sie rufen eine Methode des SAP Tree Controls, um den selektierten Knoten zusetzen (ohne Flush).

Die Methode stellt zwei Operationen in die Automation Queue: Op_Tree_1 undOp_Tree_2.

Dann rufen Sie eine Methode eines TextEdit Controls, um den ausgewählten Textanzuzeigen (ohne Flush). Die Methode stellt die Operation Op_TextEdit_1 in dieQueue.

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.


Synchronisation der Automation Queue

April 2001 33

Synchronisation der Automation QueueEinsatzmöglichkeitenBei der Kommunikation zwischen dem OO Control Framework und dem Automation Server spieltdie Automation Queue eine zentrale Rolle. In ihr werden die Automation-Aufrufe gepuffert und zuspeziellen Synchronisationszeitpunkten vom Backend an das Frontend übertragen. NachAbarbeiten der Automation Queue am Frontend wird dann das Ergebnis an das Backendzurückgeschickt.

Die Anzahl der Synchronisationszeitpunkte ist entscheidend für die Performance derAnwendung. Informationen dazu bietet Ihnen der Automation Trace und der Performance-Monitor. Beide Werkzeuge werden in Services rund um die Automation Queue [Seite 37]vorgestellt.

AblaufDie Synchronisation der Automation Queue wird zu bestimmten Zeitpunkten automatisch vomSystem durchgeführt:

• am Ende jedes PBO-Zeitpunkts:

Die Synchronisation durch das System erfolgt erst nach dem Feldtransport zumDynpro. Daher können Ergebnisse aus Methodenaufrufen, die durch dieautomatische Synchronisation abgearbeitet werden, nicht auf dem Dynpro angezeigtwerden.

• nach dem Verlassen der Behandlermethode für Systemereignisse [Seite 10]

Weiterhin können Sie die Synchronisation auch explizit anstoßen. Dazu steht Ihnen die Methodeflush [Seite 48] der Klasse CL_GUI_CFW zur Verfügung.

Durch geeignete Programmierung können Sie die letzte explizite Synchronisationdurch das System implizit durchführen lassen.

Arbeiten mit gepufferten Operationen zur Performance-Optimierung Die Performance kann anhand eines einfachen Schemas generell optimiert werden. Hierzusollten hinsichtlich der Ablauflogik am Backend, also pro PBO / PAI-Schritt, die Aufrufe an allevorhandenen 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


Synchronisation der Automation Queue

34 April 2001

− Synchronisation der Automation Queue

Somit werden nur zwei Synchronisationszeitpunkte für alle Controls zusammen benötigt. Es kannallerdings sein, daß es mehrere Abschnitte ”Holen von Eigenschaften der Controls” geben muß.Dies ist dann erforderlich, wenn erst nach dem Besorgen einer Information entschieden werdenkann, welche Information noch besorgt werden muß.

Gepuffertes Holen von Control-EigenschaftenBeim gepufferten Holen von Control-Eigenschaften ist folgendes zu beachten: Die Adressen derABAP-Variablen, in welche die zu holenden Werte geschrieben werden sollen, werden in derAutomation Queue vermerkt. Die Wertübergabe an die Variablen erfolgt erst beimSynchronisationszeitpunkt. Bis zu diesem Zeitpunkt müssen die Adressen dieser Variablen gültigsein. Ist eine lokale Variable nicht mehr vorhanden (z.B. lokale Variable einer Formroutine), löstdie Synchronisation einen Laufzeitfehler aus. Die Tücke eines solchen Fehlers besteht darin, daßim Debugger mit der Einstellung Automation Controller: Aufträge immer synchron verarbeitenkein Fehler auftritt.

Die Verwendung globaler Variablen löst das Problem nicht. Zum einen ist es kein guterProgrammierstil, zum anderen führt ein zu später Synchronisationszeitpunkt dazu, daß eineAnwendung nicht aktuelle Werte der Variablen benutzt.

Sicherheit bringt die Abfrage von Control-Eigenschaften in einer Formroutine, die amEnde und bei jedem EXIT eine Synchronisation durchführt.

Beim Auswerten von Ereignissen macht es Sinn, sich die Eigenschaften desauslösenden Controls im Ereignisbehandler zu holen und die Automation Queuedanach zu synchronisieren.

(Pseudo-Syntax): Der selektierte Knoten eines Tree Controls und der selektierte Texteines TextEdit Controls sollen gelesen werden:

FORM GET_CONTROL_PROPERTIES.DATA: tree_selected_node, combobox_selected_node.CALL METHOD tree->GET_SELECTED_NODE

IMPORTINGNODE_KEY = tree_selected_node

<Fehlerbehandlung>CALL METHOD textedit-> GET_SELECTION_POS

IMPORTINGFROM_LINE = from_line

FROM_POS = from_posTO_LINE = to_lineTO_POS = to_pos.

<Fehlerbehandlung>CALL METHOD CL_GUI_CFW=>FLUSH

<Fehlerbehandlung>ENDFORM.


Fehlerbehandlung bei der Synchronisation

April 2001 35

Fehlerbehandlung bei der SynchronisationEinsatzmöglichkeitenFehler bei Automation-Aufrufen können erst nach dem Synchronisationszeitpunkt ausgewertetwerden. 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 AutomationQueue 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 OptionAutomation Controller: Aufträge immer synchron verarbeiten setzen. Dann wird derFehler bei der Methode add_nodes_and_items ausgelöst.

Besonders kritisch wirkt sich dieses Verhalten bei der Synchronisation derAutomation Queue durch das System aus. Um auch hier eine Fehlerbehandlungdurch die Anwendung zu ermöglichen, löst das System in diesem Fall dasSystemereignis flush_error aus. Auf dieses sollten Sie sich auf jeden Fallregistrieren. Versäumen Sie dies, wird ein Fehlerprotokoll ausgegeben.

AblaufUm sich auf das Ereignis flush_error zu registrieren, müssen Sie folgende Schrittedurchführen:

1. Legen Sie eine (lokale) Klasse für die Ereignisbehandlung an.

2. Definieren Sie eine Ereignisbehandlermethode für das Ereignis flush_error der Klassecl_gui_cfw. Als Ereignisparameter erhalten Sie Informationen über den Kontext, in demder Fehler aufgetreten ist.Beispiel als statische Methode:

*------------------------------------------** CLASS lcl_event_handler DEFINITION*------------------------------------------*CLASS lcl_event_handler DEFINITION.

PUBLIC SECTION.


Fehlerbehandlung bei der Synchronisation

36 April 2001

class-METHODSerror FOR EVENT flush_error OF cl_gui_cfwIMPORTING DYNPRO_PROGRAM DYNPRO_NUMBER SITUATION.

ENDCLASS.

Ereignisparameter

Parameter BedeutungDYNPRO_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 tratauf bei

cl_gui_cfw=>flush_situation_pbo: Synchronisation nach PBO

cl_gui_cfw=>flush_situation_system_events: Synchronisationnach einem Systemereignis

3. Implementieren Sie die Ereignisbehandlermethode. Werten Sie dabei die Informationen zumKontext 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 Controlsgearbeitet werden, da dann weitere Fehler auftreten können. Sie sollten daher IhreAnwendung kontrolliert beenden.


Services rund um die Automation Queue

April 2001 37

Services rund um die Automation QueueVerwendungZur Unterstützung bei der Verwendung von Controls in Anwendungen werden unterschiedlicheServices zur Verfügung gestellt:

Debugger: Lokalisieren von Fehlern

Performance-Anzeige: Performance-Optimierung

Automation Trace: Lokalisieren von Synchronisationszeitpunkten

FunktionsumfangDebuggerWenn Sie mit gepufferten Operationen bei der Kommunikation mit Controls arbeiten, werdenFehler bei einem Methodenaufruf erst bei der Synchronisation der Automation Queue sichtbar.Daher ist es sinnvoll, beim Debuggen nach jeder Methode die Automation Queue zusynchronisieren. Dazu können Sie im Debugger die Einstellung Automation Controller: Aufträgeimmer synchron verarbeiten setzen. Diese ruft dann nach jeder Automation Methode diegenerische Methode CALL METHOD cl_gui_cfw=>flush auf.

Tritt bei direkter Ausführung der Operationen kein Fehler mehr auf, dann wurde die MethodeCL_GUI_CFW=>FLUSH zum falschen Zeitpunkt gerufen.

Fügen Sie nach jedem Methodenaufruf eine entsprechende Fehlerbehandlunghinzu (Abfrage des SY-SUBRC). Beachten Sie aber, daß diese Fehlerbehandlung inder Regel nur im Debugging durchlaufen wird.



38 April 2001

Performance-AnzeigeWenn Sie die Anzahl der Roundtrips innerhalb Ihres Programms überprüfen wollen, haben Siezwei 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.



April 2001 39

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 alleAufrufe 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ötigtwerden. Überflüssige Flushes können dadurch eliminiert werden.



40 April 2001

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-Aufrufenan das Control. Weiterhin ist zu beachten, daß der Aufruf einer ABAP-Methode den Aufrufmehrerer 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:



April 2001 41


Verwendung von Controls im WAN

42 April 2001

Verwendung von Controls im WANDie Verwendung von Controls zur Oberflächengestaltung führt in der Regel zu einer Belastungdes Kommunikationskanals zwischen Frontend und Backend. Dies kann schon im LAN-, aberinsbesondere 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 imWAN dienen.

Control-spezifische Hinweise zur Verwendung im WAN finden Sie in der Dokumentation zu demjeweiligen Control.

Verwendung von CL_GUI_CFW=>FLUSHDer Aufruf CL_GUI_CFW=>FLUSH [Seite 48] dient zum Synchronisieren der Automation Queueund der in der Queue enthaltenen ABAP-Variablen. Dieser Aufruf erzeugt in vielen Fällen einensynchronen 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 einmaligeSynchronisation zu besorgen. Diese Variante ist auch dann zu bevorzugen, wenn dabeiEigenschaften gelesen werden, die nicht immer für den Ablauf des Ereignisbehandlers bzw. desPAI – PBO Zyklus notwendig sind.

Es ist nicht notwendig, einen „Sicherheits-Flush“ am Ende von PBO zu codieren, damitMethodenaufrufe der Controls garantiert an das Frontend transportiert werden. DieseFunktionalität wird systemseitig garantiert, wenn das nächste Dynpro gesendet wird. Damit ist esauch 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=>FLUSHgesendet 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ß dieAutomation Queue synchron versendet wird, gibt es im Control Framework die MethodeCL_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 sehrlange laufende Anwendungen, die in regelmäßigen Abständen dem Benutzer ein Feedback überden Fortschritt der Aktion anzeigen möchten.

Nach dem Lesen von Eigenschaften ist der Inhalt der entsprechenden ABAP-Variablen erst nachdem nächsten FLUSH garantiert. Solange dieser Aufruf nicht erfolgt ist, ist der Inhalt derentsprechenden ABAP-Variablen nicht definiert. In Zukunft wird es Fälle gegeben, in denendieser FLUSH unnötig sein wird. Diese Fälle werden von der Automation Queue erkannt; derentsprechende FLUSH-Call wird dann ignoriert.

Erzeugen von Controls, DatenversorgungDas Erzeugen eines Controls und die Datenversorgung ist in den meisten Fällen ein einmaligerVorgang und im Vergleich zu Dynproelementen sehr teuer. Deshalb sollten Controls nichtunnötig erzeugt bzw. nicht unnötig mit Daten versorgt werden.

Ein typisches Beispiel hierfür sind TabStrips mit mehreren Seiten. Wenn diese Seiten Controlstragen, ist immer abzuwägen, ob man auf lokale Seiten verzichtet und die Controls erst dann


Verwendung von Controls im WAN

April 2001 43

erzeugt, wenn der Benutzer die Seite aktiviert. Das gleiche trifft für die Datenversorgung dieserControls 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 zurVerfügung. In manchen Fällen kann es notwendig werden, daß eine Anwendung andereDatenmengen oder ganze Fallbacks für die WAN-Anmeldung zur Verfügung stellen sollte. EinBeispiel, wann die WAN- bzw. LAN- Anmeldung einen Einfluß haben kann, ist die Anzahl vonGeschwistern in einem Tree Control, die ohne künstliche Zwischenebenen übertragen werdenkönnen.

Im Gegensatz zu Dynproelementen werden die Controls nur einmalig erzeugt und mit Datenversorgt. Controls werden unter Performance-Aspekten dann immer preiswerter, je länger dieseleben. In Anwendungen, die ständig neu aufgerufen und damit neu initialisiert werden, kann dieszu einem erheblichen Performance-Nachteil werden; in Anwendungen, die sehr lange auf dengleichen 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 derNetzwerkauslastung bringt.

Ablegen von Dokumenten, Bildern etc.Zum Release 4.6A wird ein Frontend-Cache für Zugriffe auf Dokumente aus dem BDS (BusinessDokument Service) realisiert. Es wird dringend empfohlen, Office-Dokumente, Bilder etc. im BDSund nicht in der R/3-Datenbank abzulegen. Dokumente aus dem BDS können danach imFrontend-Cache abgelegt werden. Sie müssen nur einmalig über das Netz geladen werden.


Anlegen eines Controls am Beispiel des SAP Picture

44 April 2001

Anlegen eines Controls am Beispiel des SAP PictureVoraussetzungenDer folgende Ablauf ist für alle von SAP ausgelieferten Custom Controls anwendbar. In denCode-Beispielen wird immer auf das SAP Picture Control eingegangen. Für andere Controls istaber im Prinzip nur die Klasse des Controls auszutauschen.

Weiterhin geht das Beispiel davon aus, daß das Custom Control in einem Custom Containereingebaut wird. Andere Szenarios werden in der Dokumentation zu den Control Containernbeschrieben.

AblaufInstanz anlegen1. 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 Containermüssen Sie vorher im Screen Painter angelegt haben. Beim Erzeugen des Containers legenSie auch seine Lebensdauer [Seite 29] fest (siehe constructor [Seite 56]).

CREATE OBJECT containerEXPORTING 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 pictureEXPORTING parent = container

lifetime = lifetime.

Ereignis anmelden5. Das Anmelden von Ereignissen gliedert sich in das Registrieren des Ereignisses am Control

Framework, das Definieren einer Behandlermethode und das Anmelden derBehandlermethode. Diese Schritte finden Sie in Registrieren und Verarbeiten vonEreignissen [Seite 13].

Arbeiten mit dem Control6. Diese Schritte sind control-spezifisch und werden hier nicht beschrieben.

Abbau der ControlsIn der Regel übernimmt das Lifetime Management [Seite 29] den Abbau der verwendetenControls. Wenn Sie die Controls aber in Ihrem Programm selbst abbauen wollen, führen Siefolgende Schritte aus:


Anlegen eines Controls am Beispiel des SAP Picture

April 2001 45

7. Bauen Sie das Custom Control mit der Methode free [Seite 54] am Frontend ab. Sofern Sieden Control Container nicht mehr benötigen, bauen Sie auch diesen ab:

CALL METHOD picture->freeEXCEPTIONS cntl_error = 1

cntl_system_error = 2.CALL METHOD container->free

EXCEPTIONS cntl_error = 1cntl_system_error = 2.

Beachten Sie die Reihenfolge, in der Sie die Controls am Frontend abbauen. WennSie einen Container abbauen, werden nämlich automatisch alle in dem Containereingebundenen Controls auch abgebaut. Der Versuch, ein bereits abgebautesControl 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.


Methoden der Klasse CL_GUI_CFW

46 April 2001

Methoden der Klasse CL_GUI_CFWDie Klasse CL_GUI_CFW beinhaltet statische Methoden, die beim Aufruf auf alle instanziertenCustom Controls wirken.


dispatch

April 2001 47

dispatchDie Methode dispatch verteilt Applikationsereignisse (siehe Ereignisbehandlung [Seite 10]) andie für das Ereignis angemeldeten Ereignisbehandler. Wenn diese Methode nicht imApplikationsprogramm innerhalb von PAI aufgerufen wird, dann wird sie automatisch vomSystem 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 Bedeutungreturn_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 Ereignislisteregistriert.

cl_gui_cfw=>rc_noevent: Es wurde kein Ereignis auf einem Controlausgelöst. Der OK_CODE war daher ein normaler OK_CODE (z.B. voneinem Menüeintrag).

cl_gui_cfw=>rc_nodispatch: Dem Ereignis konnte keineBehandlermethode 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 denEreignisbehandler führen.


flush

48 April 2001

flushMit dieser Methode synchronisieren Sie explizit die Automation Queue [Seite 31]. Die gepuffertenOperationen werden dann zum Frontend per GUI-RFC geschickt. Dort wird die AutomationQueue in der Reihenfolge abgearbeitet, wie Sie sie gefüllt haben.

Im Fehlerfall wird eine Ausnahme ausgelöst, die Sie auf jeden Fall abfragen und behandelnsollten. Da eine Zuordnung des Fehlers in der Regel nicht mehr möglich ist, stehen Ihnen sowohlim 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ägeimmer synchron verarbeiten. Dies führt dazu, daß nach jeder Methode, die den AutomationController 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 dasAnkreuzfeld Automation wählen. Dadurch wird die Kommunikation zwischen Applikationsserverund Automation Controller in einer Trace-Datei mitgeschrieben. Diese kann dann ausgewertetwerden.CALL METHOD cl_gui_cfw=>flush

EXCEPTIONS CNTL_SYSTEM_ERROR = 1CNTL_ERROR = 2.

Führen Sie nur so viele Synchronisationspunkte in Ihr Programm ein, wie wirklichnötig sind. Bei jeder Synchronisation wird nämlich eine RFC-Verbindung zum SAPGUI geöffnet.


get_living_dynpro_controls

April 2001 49

get_living_dynpro_controlsMit dieser Methode können Sie sich eine Liste von Referenzvariablen zu allen noch aktivenCustom Controls besorgen.CALL METHOD cl_gui_cfw=>get_living_dynpro_controls

IMPORTING control_list = control_list.

Parameter Bedeutungcontrol_list Liste der Referenzvariablen zu aktiven Custom Controls.

Liste ist vom Typ CNTO_CONTROL_LIST (in der Klasse CL_GUI_CFWdefiniert)


set_new_ok_code

50 April 2001

set_new_ok_codeDiese Methode darf nur in Behandlermethoden zu Systemereignissen eingesetzt werden. Siesetzt einen OK_CODE, der ein Ausführen von PAI nach sich zieht. Dadurch können Sie nach demFeldtransport nochmals die Kontrolle in Ihren PAI-Modulen bekommen.

CALL METHOD cl_gui_cfw=>set_new_ok_codeEXPORTING new_code = new_codeIMPORTING rc = rc.

Parameter Bedeutungnew_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, unddie Verarbeitung wird nach Abschluß der Behandlermethode mit PAIfortgesetzt (vorher wird noch die automatische Feldprüfung des Dynprosdurchgeführt).

cl_gui_cfw=>rc_wrong_state: Die Methode wurde nicht bei einemSystemereignis aufgerufen.

cl_gui_cfw=>rc_invalid: Der gesetzte OK_CODE ist kein erlaubterOK_CODE.


update_view

April 2001 51

update_viewDie Automation Queue wird durch den Aufruf der Methode flush [Seite 48] nur dannsynchronisiert, 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ß dieAutomation Queue synchron versendet wird, gibt es im Control Framework die MethodeCL_GUI_CFW=>UPDATE_VIEW. Diese Methode darf nur dann verwendet werden, wenn eszwingend notwendig ist, ein Update des SAP GUI zu erreichen. Beispiele hierfür sind sehr langelaufende Anwendungen, die in regelmäßigen Abständen dem Benutzer ein Feedback über denFortschritt der Aktion anzeigen möchten.CALL METHOD cl_gui_cfw=>update_view

EXCEPTIONS CNTL_SYSTEM_ERROR = 1CNTL_ERROR = 2.


Methoden der Klasse CL_GUI_OBJECT

52 April 2001

Methoden der Klasse CL_GUI_OBJECTDie Klasse CL_GUI_OBJECT beinhaltet wichtige Methoden zum Verschalen von CustomControls. Für Anwendungsprogramme ist einzig die Methode is_valid [Seite 53] relevant.


is_valid

April 2001 53

is_validDiese Methode liefert als Ergebnis, ob ein Custom Control zu einer Objektreferenz noch amFrontend vorhanden ist.CALL METHOD my_control->is_valid

IMPORTING result = result.

Parameter Bedeutungresult 0: Custom Control ist nicht mehr am Frontend aktiv

1: Custom Control ist noch aktiv


free

54 April 2001

freeDiese Methode baut ein Custom Control am Frontend ab. Nach Aufruf dieser Methode sollten Sieauch die Objektreferenz initialisieren (FREE my_control).

CALL METHOD my_control->freeEXCEPTIONS cntl_error = 1

cntl_system_error = 2.


Methoden der Klasse CL_GUI_CONTROL

April 2001 55

Methoden der Klasse CL_GUI_CONTROLDie Klasse CL_GUI_CONTROL beinhaltet Methoden, die zum Setzen von Control-Eigenschaften(z.B. Visualisieren des Controls), Registrieren von Ereignissen und zum Abbau des Controlsdienen.


constructor

56 April 2001

constructorDiese Methode wird von der Control-Verschalung des verwendeten Controls aufgerufen, um einControl am Frontend zu instanzieren.

Um ein SAP Control zu instanzieren, rufen Sie immer den Konstruktor derdazugehörenden Klasse auf.

CREATE OBJECT my_controlEXPORTING clsid = clsid

lifetime = lifetimeshellstyle = shellstyleparent = parentautoalign = autoalign

EXCEPTIONS cntl_error = 1cntl_system_error = 2create_error = 3lifetime_error = 4.

Parameter Bedeutungclsid ID der Klasse

lifetime Parameter für das Lifetime Management. Folgende Werte sind möglich:

my_control->lifetime_imode: Das Control lebt, solange der interneModus nicht abgebaut wird (z.B.: leave program. leavetransaction. set screen 0, leave screen.). Danach wird dieMethode finalize [Seite 58] aufgerufen.

my_control->lifetime_dynpro: Das Control lebt, solange die Instanz desDynpros existiert, d.h. sich noch im Dynprostapel befindet. Danach wird dieMethode free [Seite 54] aufgerufen.Die Benutzung dieses Modus regelt automatisch die Sichtbarkeit vonControls. Controls werden immer nur dann eingeblendet, wenn das Dynproaktiv ist, auf dem sie erzeugt wurden. Ist ein anderes Dynpro aktiv, werdensie automatisch unsichtbar geschaltet.

my_control->lifetime_default: Wird das Control in einen Containereingebaut, übernimmt es die Lebensdauer des Containers. Wird es nicht ineinen Container eingebaut (z.B. weil es selbst ein Container ist), dann wirddie 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önnenSie übergeben. Kombinationen von mehreren Styles können Sie durchAddieren der Konstanten erreichen. Der Vorschlagswert führt intern zumSetzen einer ausreichenden Kombination von Style-Konstanten.

parent Container, in dem das SAP Picture Control angezeigt werden kann (siehe SAPContainer [Extern])


constructor

April 2001 57

autoalign ' ': kein automatisches Ausrichten des Controls

'X': automatisches Ausrichten des Controls. Dabei wird der maximal verfügbarePlatz innerhalb eines Containers verwendet.


finalize

58 April 2001

finalizeDiese Methode wird von der verwendeten Controlverschalung überdefiniert. In ihr werdencontrol-spezifische Funktionen zum Abbau des Controls aufgerufen. Diese Methode wirdautomatisch von der Methode free [Seite 54] aufgerufen, bevor das Control am Frontendabgebaut wird.CALL METHOD my_control->finalize.


set_registered_events

April 2001 59

set_registered_eventsMit dieser Methode registrieren Sie sich auf Ereignisse des Controls (siehe auch:Ereignisbehandlung [Seite 10]).CALL METHOD my_control->set_registered_events

EXPORTING events = eventsEXCEPTIONS cntl_error = 1

cntl_system_error = 2illegal_event_combination = 3.

Parameter Bedeutungevents 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. DieTabelle wird mit Bezug auf den Tabellentyp CNTL_SIMPLE_EVENTS definiert. Dem Tabellentypliegt die Struktur CNTL_SIMPLE_EVENT zugrunde. Dieser besteht aus folgenden Feldern:

Feld BedeutungEVENTID Name des Ereignisses

APPL_EVENT Unterscheidung, ob es sich um ein Systemereignis (initial) oder einApplikationsereignis (X) handeln soll.

Die Werte, die dem Feld EVENTID zuzuordnen sind, sind control-spezifisch und werden daherbei den entsprechenden Controls beschrieben.


get_registered_events

60 April 2001

get_registered_eventsDiese Methode liefert eine Liste aller für das Custom Control my_control registriertenEreignisse zurück.CALL METHOD my_control->get_registered_events

IMPORTING events = eventsEXCEPTIONS cntl_error = 1.

Parameter Bedeutungevents 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 Tabellewird mit Bezug auf den Tabellentyp CNTL_SIMPLE_EVENTS definiert. Dem Tabellentyp liegt dieStruktur CNTL_SIMPLE_EVENT zugrunde. Dieser besteht aus folgenden Feldern:

Feld BedeutungEVENTID Name des Ereignisses

APPL_EVENT Unterscheidung, ob es sich um ein Systemereignis (initial) oder einApplikationsereignis (X) handeln soll.

Die Werte, die dem Feld EVENTID zuzuordnen sind, sind control-spezifisch und werden daherbei den entsprechenden Controls beschrieben.

Allgemeine Informationen zur Ereignisbehandlung finden Sie in der Dokumentationdes SAP Control Frameworks unter Ereignisbehandlung [Seite 10].


is_alive

April 2001 61

is_aliveDiese Methode liefert als Ergebnis, ob ein Custom Control zu einer Objektreferenz noch amFrontend vorhanden ist.CALL METHOD my_control->is_alive

RETURNING state = state.

Parameter Bedeutungstate 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 demaktuellen Dynpro nicht aktiv, aber am Frontend noch aktiv (d.h. unsichtbar)


set_alignment

62 April 2001

set_alignmentDiese Methode richtet das Custom Control innerhalb seines Containers aus:CALL METHOD my_control->set_alignment

EXPORTING alignment = alignmentEXCEPTIONS cntl_error = 1


Parameter Bedeutungalignment Ausrichtung des Controls

Der Parameter alignment kann aus Kombinationen folgender Ausrichtungen bestehen:

Name Bedeutungmy_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.


set_position

April 2001 63

set_positionDiese 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 = heightleft = lefttop = topwidth = width

EXCEPTIONS cntl_error = 1cntl_system_error = 2.

Parameter Bedeutungheight Höhe des Controls

left Linker Rand des Controls

top Oberer Rand des Controls

width Breite des Controls


set_visible

64 April 2001

set_visibleMit dieser Methode können Sie die Sichtbarkeit eines Custom Controls verändern.CALL METHOD my_control->set_visible

EXPORTING visible = visibleEXCEPTIONS cntl_error = 1


Parameter Bedeutungvisible X: Custom Control ist sichtbar

' ': Custom Control ist nicht sichtbar


get_focus

April 2001 65

get_focusDiese statische Methode liefert die Objektreferenz des Custom Controls zurück, welches denFokus hat.CALL METHOD cl_gui_control=>get_focus

IMPORTING control = controlEXCEPTIONS cntl_error = 1


Parameter Bedeutungcontrol Objektreferenz (TYPE REF TO cl_gui_control) auf das Control, das den

Fokus hat


set_focus

66 April 2001

set_focusMit dieser statischen Methode können Sie den Fokus auf ein Custom Control setzen.CALL METHOD cl_gui_control=>set_focus

EXPORTING control = controlEXCEPTIONS cntl_error = 1


Parameter Bedeutungcontrol Objektreferenz (TYPE REF TO cl_gui_control) auf das Control, das den

Fokus bekommen soll


get_height

April 2001 67

get_heightDiese Methode liefert die Höhe des Controls zurück.CALL METHOD control->get_height

IMPORTING height = heightEXCEPTIONS cntl_error = 1.

Parameter Bedeutungheight Aktuelle Höhe des Controls


get_width

68 April 2001

get_widthDiese Methode liefert die Breite des Controls zurück.CALL METHOD control->get_width

IMPORTING width = widthEXCEPTIONS cntl_error = 1.

Parameter Bedeutungwidth Aktuelle Breite des Controls


Methoden der Klasse CL_DRAGDROP

April 2001 69

Methoden der Klasse CL_DRAGDROPDie Klasse CL_DRAGDROP beinhaltet Methoden, über die das Drag&Drop-Verhalten [Seite 17]eines Custom Controls beschrieben wird.


constructor

70 April 2001

constructorDer Konstruktor erzeugt eine Instanz für die Beschreibung des Drag&Drop-Verhaltens einesControls.CREATE OBJECT dragdrop.


add

April 2001 71

addDiese Methode fügt eine weitere Beschreibung zu dem Drag&Drop-Verhalten hinzu. Es könnenbeliebig viele Beschreibungen hinterlegt werden. Allerdings darf die gleiche Beschreibung nichtmehrmals hinzugefügt werden.CALL METHOD dragdrop->add

EXPORTING flavor = flavordragsrc = dragsrcdroptarget = droptargeteffect = effecteffect_in_ctrl = effect_in_ctrl

EXCEPTIONS allready_defined = 1obj_invalid = 2.

Parameter Bedeutungflavor 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 alsKopiervorgang

dragdrop->move: Darstellung der Maus beim Drag&Drop alsVerschiebevorgang

dragdrop->none: Es ist kein Drag&Drop möglich

effect_in_ctrl Drop-Effekt der Beschreibung im gleichen Custom Controls. FolgendeEffekte werden unterstützt:




dragdrop->use_default_effect: Es wird der gleiche Effekt benutzt,der durch den Parmeter effect spezifiziert wurde

Ausnahmen Bedeutungallready_defined Der angegebene Flavor wurde bereits definiert.

obj_invalid Das Objekt wurde bereits mit der Methode destroy [Seite 74] zerstört


add

72 April 2001

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 Moveund beim Drag in Verbindung mit Drücken der Steuerungstaste die Flavors mit EffektCopy verwendet.


clear

April 2001 73

clearDer 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->clearEXCEPTIONS obj_invalid = 1.

Ausnahmen Bedeutungobj_invalid Das Objekt wurde bereits mit der Methode destroy [Seite 74] zerstört


destroy

74 April 2001

destroyDer Inhalt der Instanz wird gelöscht. Weiterhin wird die Instanz zerstört. Nach Aufruf der Methodesind keine Drag&Drop-Vorgänge mehr auf dem betroffenen Custom Control möglich.

CALL METHOD dragdrop->destroy.


get

April 2001 75

getDiese Methode liefert die komplette Beschreibung zu einem Flavor zurück.CALL METHOD dragdrop->get

EXPORTING flavor = flavorIMPORTING isdragsrc = isdragsrc

isdroptarget = isdroptargeteffect = effecteffect_in_ctrl = effect_in_ctrl

EXCEPTIONS not_found = 1obj_invalid = 2.

Parameter Bedeutungflavor Bezeichnung des Flavors







effect_in_ctrl Drop-Effekt der Beschreibung im gleichen Custom Controls. FolgendeEffekte werden unterstützt:




dragdrop->use_default_effect: Es wird der gleiche Effekt benutzt,der durch den Parmeter effect spezifiziert wurde

Ausnahmen Bedeutungallready_defined 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 undbeim Drag in Verbindung mit Drücken der Steuerungstaste die Flavors mit EffektCopy verwendet.


get

76 April 2001


get_handle

April 2001 77

get_handleDie Methode liefert das Handle auf die Drag&Drop-Beschreibung. In den meisten Fällen ist einAufruf dieser Methode nicht nötig. Für tabellarische Massendatenschnittstellen (z.B. SAP TreeControl) muß dieses Handle aber vom Verwender des Controls in die Schnittstellentabelle kopiertwerden.CALL METHOD dragdrop->get_handle

IMPORTING handle = handleEXCEPTIONS obj_invalid = 1.

Parameter Bedeutunghandle Handle auf die Drag&Drop-Beschreibung

Ausnahmen Bedeutungobj_invalid Das Objekt wurde bereits mit der Methode destroy [Seite 74] zerstört


modify

78 April 2001

modifyMit dieser Methode können Sie einen bestehenden Flavor verändern.CALL METHOD dragdrop->modify

EXPORTING flavor = flavordragsrc = dragsrcdroptarget = droptargeteffect = effecteffect_in_ctrl = effect_in_ctrl

EXCEPTIONS not_found = 1obj_invalid = 2.





dragdrop->copy: Darstellung der Maus beim Drag&Drop als Kopiervorgang



effect_in_ctrl Drop-Effekt der Beschreibung im gleichen Custom Controls. Folgende Effektewerden unterstützt:

dragdrop->copy: Darstellung der Maus beim Drag&Drop als Kopiervorgang



dragdrop->use_default_effect: Es wird der gleiche Effekt benutzt, derdurch den Parmeter effect spezifiziert wurde

Ausnahmen Bedeutungnot_found Der angegebene Flavor existiert nicht


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 undbeim Drag in Verbindung mit Drücken der Steuerungstaste die Flavors mit EffektCopy verwendet.


modify

April 2001 79


remove

80 April 2001

removeMit dieser Methode löschen Sie einen bestimmten Flavor.CALL METHOD dragdrop->remove

EXPORTING flavor = flavorEXCEPTIONS not_found = 1

obj_invalid = 2.


Ausnahmen Bedeutungnot_found Der angegebene Flavor existiert nicht



Methoden der Klasse CL_DRAGDROPOBJECT

April 2001 81

Methoden der Klasse CL_DRAGDROPOBJECTDie 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 desDrag&Drop-Vorgangs und Informationen zu Quelle und Ziel.


set_flavor

82 April 2001

set_flavorDiese Methode verwenden Sie nur innerhalb der Ereignisbehandlung zu ONGETFLAVOR. Überden Parameter newflavor bestimmen Sie, welcher Flavor innerhalb des Drag&Drop-Vorgangsverwendet werden soll. Eine Liste der verfügbaren Flavors wird Ihnen als Ereignisparameterübergeben.CALL METHOD dragdropobject->set_flavor

EXPORTING newflavor = newflavorEXCEPTIONS illegal_state = 1

illegal_flavor = 2.

Parameter Bedeutungnewflavor Bezeichnung des Flavors

Ausnahmen Bedeutunginvalid_state Die Methode wurde nicht innerhalb der Ereignisbehandlung ONGETFLAVOR

aufgerufen.

obj_invalid Es wurde ein Flavor verwendet, der nicht von der aktuellen Drag&Drop-Situation unterstützt wird.


abort

April 2001 83

abortDer Drag&Drop-Vorgang wird sofort abgebrochen. Es werden keine weiteren Ereignisseausgelöst.CALL METHOD dragdropobject->abort.

Documents

SAP Control Framework