Quick Start: ALV Grid Control

1 Introduction
The ALV (SAP List Viewer) control is a tool for creating lists that you can use through a global class in your ABAP programs. This tool represents the control version of the classic SAP List Viewer which is limite! to !isplaying simple lists only. The ALV control allows you to" #isplay non$hierarchical lists with a consistent mo!ern !esign %se typical list functions $ such as sorting an! filtering $ without a!!itional programming effort &ustomi'e an! enhance pre$!efine! list functions Program in!ivi!ual responses to user actions (such as !ouble$clic(ing a line)

This !ocumentation provi!es a )uic( start for !evelopers who want to integrate the ALV control into their applications. &lassic ALV (nowle!ge is not re)uire!. The ne*t chapter intro!uces you to the theoretical basics necessary for using the tool. The chapter First Steps !escribes the easiest way how you can create an ALV control an! use it for !isplaying a list. The subse)uent chapters e*plain how you procee! to ma(e use of the capabilities the ALV control offers in specific cases.

2
2.1

Basics
Using Control Technology

+hen you create lists in the classic way the ABAP list processor is responsible for storing !isplaying an! managing a single list or multiple lists. ABAP statements are use! to temporarily store the lists on the application server while the program is e*ecute! an! !isplay them on a special container screen with the help of the list processor. ,n contrast the ALV control uses control technology for !isplaying lists. &ontrols are binary re$usable software components installe! on the local P&. -or e*ample this eliminates the nee! for the system to access the application server in or!er to move columns of a table currently !isplaye!. Basically if you use controls specific functions are shifte! from the application server (bac($en!) to the SAP.%, (front$en!). &ontrols are manage! by a central Control Framework. The following graphic shows a bir!/s eye view of control programming"

Application Server
ABAP Program
CREATE OBJECT grid1. ... CALL METHOD set_table_for_first_display. ... CL_G !_C"#$%"L &H.

Event

SAPGUI
Custom Control

RFC

Co'str()tor *grid1+ set_table_for_first_display

.2.1.1

Buffering Control Methods

The system must transfer metho!s use! for creating an! managing controls to the front$en! system by means of a 0emote -unction &all (0-&). To (eep necessary communication between the bac($en! an! the front$en! system to a minimum the &ontrol -ramewor( buffers the metho!s. The metho!s are not transferre! until you call the "L &H metho!. -or each internal mo!e there is a buffer that collects calls to all controls generate! in the ABAP program.

The methods of the ALV control are encapsulated in global class )l_g(i_al,_grid. From the Class Builder (transaction SE24), you can display an overview of the methods, attributes, and events of this class.

.2.1.2

Integrating a Control Into a Screen

,n or!er to !isplay a control on a screen you nee! a container control instance. A container control is responsible for !isplaying or arranging one ore more controls on the screen. -irst the container control is instantiate! using the CREATE OBJECT statement an! lin(e! to an area on the screen. +hen the control to be !isplaye! is instantiate! you can specify the container control as its parent. This creates a close connection between these two controls. ,t is possible to lin( the control together with its container control to another screen afterwar!s. This re)uires that the two screens are at the same popup level. This means that the call level for mo!al !ialog bo*es must be the same.

Chapter 5 deals with events. For a detailed introduction to events, see the Controls Tutorial.

2.2

Using the ALV Control

"eclaration "eclaration o) o) Re)erence Re)erence &aria$les &aria$les Instantiation Instantiation and and Screen Screen Integration Integration "ata "ata "ispla' "ispla' on on tt e e Control Control

The following graphic shows the in!ivi!ual steps necessary for !isplaying a list using the ALV control.
Field FieldCatalog Catalog

"ata "escription

A TypA ... C Typ& ...

or
""IC ""IC Structure Structure

CALL METHOD grid-%&et_table_for_first_display.

DATA )o'tai'er T12E RE" TO )l_g(i_)(sto/_)o'tai'er.

CREATE OBJECT )o'tai'er )o'tai'er_'a/e $ 3M1CO4T5.

B TypB ...

List "ispla'ed( Screen grid

(Linked to Screen T roug Container!
"L &H

A B C
Internal Internal Ta$le Ta$le

DATA grid T12E RE" TO )l_g(i_al,_grid.

0'a/e%

CREATE OBJECT grid pare't $ )o'tai'er.

A B C a1 b1 c1 a2 b2 c2 a3 b3 c3

#utput Ta$le

Data

a1 b1 c1 a2 b2 c2 a3 b3 c3

Container Container%it %it Integrated IntegratedAL& AL& Control Control

&ele)t . fro/ 0'a/e%

#isplaying the !ata re)uires that you provi!e the following two types of information as a minimum" An internal table containing the !ata to be !isplaye! calle! the output table. A structure !escription of this !ata that is !eclare! to the ALV control either through the field catalog or the correspon!ing #ata #ictionary structure.

1ormally the output table inclu!es !ata that you selecte! from !atabase tables beforehan!.

The reference to the output table that you pass to the ALV control should be valid as long as the ALV control operates on it. Besides defining this reference as a global table, you can also hold the reference in an ABAP Objects instance using a public attribute. The fiel! catalog is a table that contains information on the fiel!s to be !isplaye!. +ith the help of this table the ALV recogni'es the type of a fiel! for e*ample. 2owever you can also use special fiel!s of this catalog to !etermine the number format an! column properties of the list to be !isplaye!. ,n some e*ceptional cases it is not necessary to pass the fiel! catalog. -or more information refer to section 3.4.

First Steps

This chapter !escribes the easiest way of !isplaying a list with selecte! !ata in the ALV control. To !o this" 4. .enerate an instance of the ALV control an! integrate it into a screen. 5. Select the !ata to be !isplaye! an! pass it to the instance together with a !escription of the fiel!s.

See also example report BCAL6_GR!D_DEMO in the Reuse Library (transaction SE83).

3.1

Creating an ALV Control

6ou instantiate ALV controls in the same way as other controls" 4. #eclare reference variables for the ALV control an! the container. ,n a!!ition !eclare an internal table that you fill with selecte! !ata later on"
DATA7 grid T12E RE" TO )l_g(i_al,_grid8 g_)(sto/_)o'tai'er T12E RE" TO )l_g(i_)(sto/_)o'tai'er gt_sflig9t T12E TABLE O" sflig9t.

For integrating a control into a screen, you can use four different container control types (in this example, we use a custom container control). For more information on container controls, see the SAP Container documentation in the Knowledge Engineer. 5. &reate a normal screen an! !efine a container for the custom container control in the graphical Screen Painter version (icon with letter /&/). Assign name CCCO4TA!4ER to this container.

Exercise 1: Reserving an Area for a Control of the Controls Tutorial explains how to create a container in the alphanumerical Screen Painter version. 7. ,n the PB8 mo!ule of the screen you must instantiate the container an! the ALV control. +hen !oing this you lin( the container control to the screen using the container you create! in the Screen Painter. %sing parameter pare't you !efine the container control as the parent of the ALV control"
!" g_)(sto/_)o'tai'er !& !4!T!AL.

CREATE OBJECT g_)(sto/_)o'tai'er E:2ORT!4G CO4TA!4ER_4AME $ 3CCCO4TA!4ER3. CREATE OBJECT GR!D1 E:2ORT!4G !_2ARE4T $ g_)(sto/_)o'tai'er. E4D!".

The !" query of reference variable g_)(sto/_)o'tai'er ensures that the instances are only created when the PBO module is processed for the first time.

Normally, you must use method )l_g(i_)f;$%fl(s9 to transfer the methods called to the front-end system. However, since the Control Framework automatically performs the flush at the end of the PBO module, this is not necessary in this case. +hen you start the program although the two instances (the container an! the ALV control) are generate! they are not visible.

3.2

Displaying a List in the ALV Control

After you have generate! an ALV control an! integrate! it into a screen using a container control you must pass the !ata an! its structure to the ALV control" 4. -ill the internal table with !ata"
&ELECT . "ROM sflig9t !4TO TABLE gt_sflig9t.

5. Pass the output table an! the structure !ata to the ALV control. Again you must ensure that this metho! is calle! only once after the ALV control is generate!"
CALL METHOD grid-%set_table_for_first_display E:2ORT!4G !_&TR CT RE_4AME $ 3&"L!GHT3 CHA4G!4G !T_O TTAB $ gt_sflig9t.

In this case, the structure data is provided from the Data Dictionary. The ALV control uses table &"L!GHT to obtain the field information and displays all fields of the table.

Generating the Field Catalog

Automatically through a #ata #ictionary structure 9anually in your ABAP program Semi$automatically by combining the above two proce!ures.

Basically you nee! a fiel! catalog for each list that is !isplaye! using the ALV control. 6ou have several options of generating a fiel! catalog"

4.1

Generating the Field Catalog Automatically

,f the structure of your output table correspon!s to a structure store! in the #ata #ictionary (##,&) the ALV control can use this information to generate the fiel! catalog automatically. ,n this case all fiel!s of this ##,& structure are !isplaye! in the list. To pass the structure to the ALV control" 4. 0eference the structure with L!<E or inclu!e the structure in a separate structure with !4CL DE &TR CT RE.

If you use !4CL DE &TR CT RE, you can have the ALV generate part of your output table automatically, and then add more fields. Chapter 4.3describes the general procedure. 5. Pass the structure in metho! &et_table_for_first_display with parameter !_&TR CT RE_4AME to the control generate!. ,f you neither want to a!! more fiel!s to the structure nor want to hi!e specific fiel!s you !o not nee! to pass the fiel! catalog (see graphic).
""IC ""IC Structure Structure

"ata "escription

"ata "ictionar'

0'a/e% A B C

&et_table_for_first_display
!4CL DE &TR CT RE 0'a/e%

List "ispla'ed( Screen A B C a1 b1 c1 a2 b2 c2 a3 b3 c3

Container Container%it %it Integrated IntegratedAL& AL& Control Control

or
DATA ... L!<E 0'a/e%

>> !_&TR CT RE_4AME <> !T_O TTAB.

C9a'gi'g

E=porti'g

#utput Ta$le

Data

a1 b1 c1 a2 b2 c2 a3 b3 c3
Internal Internal Ta$le Ta$le

"L &H

Instance o) an AL& Control

(Linked to Screen T roug Container!

&ele)t . fro/ 0'a/e%

4.2

Generating the Field Catalog Manually

,t may be the case that the !ata you want to !isplay is not at all or only partially represente! by a structure in the #ata #ictionary. Then you must use the fiel!s of the fiel! catalog to !escribe the structure of the output table. The fiel! catalog is !efine! in the #ata #ictionary through table type L6C_T_"CAT. :ach row of the fiel! catalog table e*plains a fiel! in your output table. #epen!ing on whether a reference structure e*ists in the ##,& or not you must at least fill the following fiel!s of the fiel! catalog structure for each fiel!"

Required Fields of the Field Catalog Output table fields with DDIC reference
"!ELD4AME

Output table fields without DDIC reference

"!ELD4AME

Explanation
*ame o) t e )ield o) t e

internal output ta$le RE"_TABLE RE"_"!ELD *ame o) t e ""IC re)erence structure *ame o) t e ""IC re)erence )ield (onl' needed i) ot er t an "!ELD4AME! !4TT12E O T2 TLE4 COLTE:T &ELTE:T A+AP data t'pe o) t e )ield o) t e internal output ta$le Column %idt Column eader Column description in column selection )or displa' variant

6ou pass the fiel! catalog using parameter !T_"!ELDCATALOG (see graphic).
Field Field Catalog Catalog

"ata "escription

A TypA ... B TypB ... C Typ& ...

&et_table_for_first_display

List "ispla'ed( Screen A B C a1 b1 c1 a2 b2 c2 a3 b3 c3

Container Container%it %it Integrated IntegratedAL& AL& Control Control

<> !T_"!ELDCATALOG <> !T_O TTAB.

C9a'gi'g

#utput Ta$le

Data

a1 b1 c1 a2 b2 c2 a3 b3 c3
Internal Internal Ta$le Ta$le

"L &H

Instance o) an AL& Control

(Linked to Screen T roug Container!

&ele)t . fro/ 0'a/e%

.4.2.1

Texts in the Field Catalog

A list !isplaye! by the ALV control shows three !ifferent te*ts for a column" The column hea!er The popup column selection (for e*ample in the current variant) A tool tip for the column hea!er.

-or fiel!s with #ata #ictionary reference the system automatically a!opts the fiel! labels of the correspon!ing !ata element. The te*ts for the short me!ium an! long fiel! labels as well as for the hea!er are copie! into the fiel!s &CRTE:T_& &CRTE:T_M &CRTE:T_L an! RE2TE:T of the fiel! catalog. There are several possibilities how the ALV control assigns te*t to a column"

,f no other te*t is specifie! the te*t copie! from the #ata #ictionary is use!. The ALV control automatically choses the short fiel! label (&CRTE:T_&) as the column hea!er an! the long fiel! label for the other two te*ts. ,f fiel!s COLDD!CT:T &ELDD!CT:T or T!2DD!CT:T of the fiel! catalog are not empty the relevant fiel! !etermines the fiel! label that is to be !isplaye! as the column hea!er the popup column selection or the column hea!er tool tip. The value range of these fiel!s is as follows" &2ACE /L/ /M/ an! /&/. 6ou can use the fiel!s COLTE:T &ELTE:T an! TOOLT!2 of the fiel! catalog to !efine your own te*ts for the column. ,f fiel! labels have been copie! from the #ata #ictionary these are ignore!. This means that you can use these fiel!s to !efine column te*ts for fiel!s without reference to the #ata #ictionary.

4.3

Generating the Field Catalog Semi-Automatically

+hen generating the fiel! catalog semi$automatically you combine structure information of the #ata #ictionary with your own structure information. ,n this conte*t you can" mo!ify or a!! structure !escriptions of new fiel!s to

the fiel! catalog generate! automatically using the ##,& structure. -or e*ample this metho! is helpful for the following scenarios"

You want to display a Data Dictionary table without displaying all possible columns initially (using field 4O_O T and possibly field <E1_&EL of the field catalog).

You want to display additional columns containing icons or other information. See the table in chapter 4.2for the required fields. This section also explains how to define texts for a new column. To generate a fiel! catalog semi$automatically" 4. #eclare an internal table of type L6C_T_"CAT. 5. &all function mo!ule L6C_"!ELDCATALOG_MERGE an! pass the ##,& structure of the output table an! the internal table for the fiel! catalog. The function mo!ule generates the fiel! catalog an! fills the internal table accor!ingly. 7. 0ea! the rows you want to change an! a!apt the fiel!s accor!ingly. ,f your output table contains more fiel!s than are store! in the #ata #ictionary you must appen! one row for each new fiel! to the fiel! catalog (for information on the fiel!s of the fiel! catalog see chapter 3.5). To !isplay the output table with the settings of the fiel! catalog you pass the fiel! catalog in metho! set_table_for_first_display.

Event Handling

The class wrapper of a control contains a number of events. -or e*ample these events are triggere! by a user action (such as a !ouble$clic() or by the control itself at some clearly !efine! point. 6ou can catch an! respon! to those events in your ABAP program.

The event handling technique of the ALV control replaces the callback technique of the classic ALV and is based on the ABAP Objects event handling concept.

5.1
.5.1.1

Registering Events
Control Events

A control is encapsulate! through an ABAP Objects class an! provi!es events at the class interface to which you can respon!. The runtime environment on the application server processes such an event li(e any other ABAP 8b;ects event that has nothing to !o with controls. 2owever you must register events of controls on the front$en! system beforehan!. This is !ue to the fact that the system must transfer events to the application server that were triggere! on the front$en! system. ,f all events (such as mouse movements) were allowe! initially the connection from the front$en! to the bac($en! system woul! be e*pose! to heavy loa!s. This is why all events are first of all filtere! out by the front$ en! system.

If we talk of event registration in this documentation, we refer to event registration on the front-end system and not to ABAP Objects event registration. 6ou can therefore select specific events by registering them. 0egistere! events are transferre! from the SAP.%, to the bac($en! system when they are triggere!. There are two types of events" :vents where the PA,<PB8 mo!ules of the associate! screen are not processe! when they are triggere!. These events are calle! system events. :vents where the PA,<PB8 mo!ules of the associate! screen are processe! when they are triggere!. These events are calle! application events.

Application !evelopers must !eci!e whether they register an event as a system event or as an application event. Basically it ma(es sense to register an event as" A system event if no screen fiel!s must be accesse! when the event is processe! An application event if screen fiel!s must be accesse! an! if losing events is not critical. This can occur in connection with automatic input chec(s using "!ELD>CHA!4 statements.

Lesson 2: Event Handling of the Controls Tutorial describes the advantages and disadvantages of system and application events.

.5.1.2

Events of the ALV Control

+ith the ALV control most events are alrea!y registere! when the control is instantiate!. The reason is that the ALV control uses the wrapper of the gri! control. The ALV control ma(es fre)uently use! events (nown to the gri! control an! !oes not register e*ceptional events. &onse)uently you can register all events either as system events or as application events for the ALV control. ,n its !efault setting the ALV control registers all events as system events.

If you want to register the events as application events, you must set the !_A22L_E6E4T& parameter for the constructor.

The following table categori'es the ALV control events base! on their usage"

Event Categorization in the ALV Control Events

2R!4T_TO2_O"_2AGE 2R!4T_TO2_O"_2AGE 2R!4T_E4D_O"_L!&T 2R!4T_E4D_O"_L!&T > & BTOTAL_TE:T DO BLE_CL!C< DELA1ED_CALLBAC< DELA1ED_CHA4GED_&EL_CALLBAC<8 HOT&2OT_CL!C< BE"ORE_ &ER_COMMA4D A"TER_ &ER_COMMA4D &ER_COMMA4D

Event usage Text output on printer / as list Response to mouse interactions on the list output Response to ALV-specific and selfdefined function codes Integration of self-defined functions in the context menu, in menus or in the tool bar

CO4TE:T_ME4 _RE? E&T ME4 _B TTO4 TOOLBAR

6ou must e*plicitly register only the DELA1ED_CHA4GED_&EL_CALLBAC< an! DELA1ED_CALLBAC< events. 6ou can register these events using metho! REG!&TER_DELA1ED_E6E4T by passing their event ,#s" -or event DELA1ED_CALLBAC<7
CALL METHOD 0i'sta')e of AL6 )o'trol%-%REG!&TER_DELA1ED_E6E4T E:2ORT!4G !_E6E4T_!D $ CL_G !_AL6_GR!D$%MC_E6T_DELA1ED_MO6E_C RR_CELL.

-or event DELA1ED_CHA4GED_&EL_CALLBAC<7

CALL METHOD 0i'sta')e of AL6 )o'trol%-%REG!&TER_DELA1ED_E6E4T E:2ORT!4G !_E6E4T_!D $ CL_G !_AL6_GR!D$%MC_E6T_DELA1ED_CHA4GE_&ELECT.

This registers the events which are then transferre! from the front$en! to the bac($en! system when triggere!.

5.2

Processing Events

6ou respon! to events by means of event han!ler metho!s that are lin(e! to the relevant event. This correspon!s to the event han!ling techni)ue use! in ABAP 8b;ects. :vents triggere! by a control on the front$en! system must first be transferre! to the application server. 8n the application server the &ontrol -ramewor( assigns the event to the associate! instance an! triggers the event for that instance. The time when event han!ling is initiate! !epen!s on the event type" -or system events the event han!ler metho! is calle! imme!iately after the event is triggere! by the &ontrol -ramewor(. After the event han!ler metho! is processe! control is given bac( to the front$en! system.

Using method )l_g(i_)f;$%set_'e;_o@_)ode, you also have the option of setting an application-specific OK code in the event handler method. For system events, the Control Framework then processes the PAI/PBO modules of the screen after the event handler method. You can then query the OK code set and access screen fields.

-or application events you use metho! )l_g(i_)f;$%dispat)9 in the PA, mo!ule to !etermine when event han!ling shoul! be starte!. 9etho! D!&2ATCH then initiates the event han!ling of ABAP 8b;ects using the RA!&E E:CE2T!O4 statement.

To respon! to events" 4. &reate a class in which you want to bun!le event han!ler metho!s. 6ou !efine an event han!ler metho! as follows"
METHOD =metho! name> "OR E6E4T =event name> O" CL_G !_AL6_GR!D !M2ORT!4G =event parameter4> ... =event parameter1>.

5. ?uery the event parameters (such as the position of a !ouble$clic() in the implementation of your metho!. By calling a!!itional metho!s you !etermine further processing after an event has occurre!. 7. ,nstantiate your class using the CREATE OBJECT statement (where you instantiate the associate! ALV control for e*ample). 3. After this lin( the events to the relevant event han!ler metho!"
&ET HA4DLER =class name>-%=name of event han!ler metho! name> "OR =name of an ALV control instance for which the lin( is vali! >.

@. -or application events call metho! CL_G !_C"#$%D!&2ATCH in the PA, of the screen that is associate! with the container of the control. A. -or system events you can optionally call metho! CL_G !_C"#$%&ET_4E#_O<_CODE an! set an 8B co!e in your event han!ler metho!. At the en! of the event han!ler metho! the associate! PA, mo!ule is processe! in which you can )uery this 8B co!e.

Report BCAL6_GR!D_A1 in the Reuse Library is a simple example of handling system events.

Display Variants

+ith the help of !isplay variants users can customi'e the list output to meet their re)uirements. The current !isplay variant (that is basically the selection an! the or!er of the columns !isplaye!) can be mo!ifie! by clic(ing the first icon in the stan!ar! tool bar of the ALV control. ,n a!!ition you can" Allow users to save an! loa! variants Loa! an! e*ecute variants before list output.

6.1

Saving Display Variants

To allow users to save !isplay variants" 4. #eclare a variable for !etermining the saving options available to the user an! a structure for i!entifying a variant"
DATA7 :_&A6E8 Bfor para/eter !_&A6E G&_6AR!A4T T12E D!&6AR!A4T. Bfor para/eter !&_6AR!A4T

5. The structure of type D!&6AR!A4T must contain the report ,# as a minimum"

G_RE2!D $ &1-RE2!D. G&_6AR!A4T-RE2ORT $ G_RE2!D.

7. #etermine the saving options available to the user"

:_&A6E $ 3 3.

B,aria'ts )a' o'ly be sa,ed as (ser spe)ifi) o'es

3. Pass both variables using the set_table_for_first_display call"

CALL METHOD GR!D1-%&ET_TABLE_"OR_"!R&T_D!&2LA1 E:2ORT!4G !_&TR CT RE_4AME $ 3&"L!GHT3 !&_6AR!A4T $ G&_6AR!A4T !_&A6E $ :_&A6E CHA4G!4G !T_O TTAB $ GT_&"L!GHT.

The tool bar now inclu!es a pull$!own menu ne*t to the variant icon that allows users to save an! loa! variants. #epen!ing on the value of parameter !_&A6E the following options for saving variants are available"

Saving Options for Display Variants

!_&A6E $ &2ACE !_&A6E $ 3 3 !_&A6E $ 3:3 I_SAVE = 'A'

Variants cannot be save!. 8nly user$!efine! variants can be save!. 8nly global variants can be save!. Both user$!efine! an! global variants can be save!.

See also report BCAL6_GR!D_AC in the Reuse Library.

6.2

Loading Variants Before List Output

The following function mo!ules are available for loa!ing variants"

Function Modules for Loading Variants Function Module

L6C_6AR!A4T_DE"A LT_GET L6C_6AR!A4T_E:!&TE4CE_CHEC<

Purpose Reads the default variant Checks if a specific variant exists F4 help for selecting a variant Reads a variant, using a dialog box if required

Applicable Event (any)

AT &ELECT!O4-&CREE4

L6C_6AR!A4T_"D

AT &ELECT!O4-&CREE4 O4 6AL E RE? E&T "OR ...

L6C_6AR!A4T_&ELECT

(any)

,f the correspon!ing variant e*ists or has been selecte! by the user the system fills a structure of type D!&6AR!A4T. 6ou can pass this structure in the set_table_for_first_display call. ,t is also possible to restrict access to specific variables (for e*ample to user$!efine! variables) using parameter !_&A6E (see section A.4).

See also report BCAL6_GR!D_1A in the Reuse Library.

Integrating Self-Defined Functions

0eplace e*isting functions with self$!efine! functions A!! new functions to the tool bar or the conte*t menu.

The ALV control provi!es stan!ar! functions for e!iting lists. %sers can access these functions from the tool bar or the conte*t menu. To integrate your own functions you can"

6ou can also hi!e or !isable functions that are not nee!e! in a specific conte*t.

7.1

Changing Standard Functions

The stan!ar! functions are not !esigne! for specific applications. As a result special (nowle!ge of the !ata !isplaye! cannot be consi!ere!. ,n in!ivi!ual cases you may !esign a stan!ar! function $ such as sorting by a specific column $ more efficiently in a specific application. To !o this" 4. #efine an event han!ler metho! for event BE"ORE_ &ER_COMMA4D. This event is triggere! after the user has selecte! a function. This means that the ALV control passes control to the application before the function is e*ecute!. %sing event parameter !_ COMM you can restrict the function co!e to the function you want to mo!ify. 5. ,mplement your own algorithm for the function within the event han!ler metho!. ,n this conte*t you can call metho!s of the ALV control. 7. 0eset the function co!e to ensure that the stan!ar! function is no longer e*ecute!"
CALL METHOD 0i'sta')e of t9e AL6 )o'trol%-%set_(ser_)o//a'd e=porti'g !_ COMM $ &2ACE.

If you never need specific functions of the tool bar, you may hide them for the entire lifecycle of the control. To do this, you use parameter !T_TOOLBAR_E:CL D!4G of method set_table_for_first_display to pass a table that contains the function codes to be hidden.

7.2

Adding Self-Defined Functions

Pushbuttons an! menus in the tool bar A conte*t menu that provi!es !ifferent functions !epen!ing on the column an! row position.

6ou can a!! the following .%, elements to the ALV control"

To !o this" 4. #efine the new interface elements. 5. ?uery the associate! function co!e in event &ER_COMMA4D an! further process that co!e.

.7.2.1

Overview: Defining Self-Defined GUI Elements

#efining or a!!ing new .%, elements is event$controlle!. There is an event for each element type (tool bar pushbutton tool bar menu an! conte*t menu). ,n the relevant event han!ler metho! you !efine the properties of an element (such as its menu options). 6ou must assign a function co!e to each e*ecutable function. The following table shows which .%, elements are !efine! in which event an! at which time the events are triggere!"

Programmable GUI Elements in the ALV Control Element Event in which the elements must be defined
TOOLBAR

Event is triggered:

Pushbutton or menu button in the tool bar

When the function

set_toolbar_i'tera)ti,e

is

called or by the ALV Control itself Menu in the tool bar

ME4 _B TTO4

When the (left button) of the mouse is clicked on a menu button in the tool bar When the (right button) of the mouse is clicked on an element of the table

Context menu

CO4TE:T_ME4 _RE? E&T

The !efinable .%, elements nee! to be rebuilt each time the correspon!ing event is triggere!. -or this purpose the event has the E_OBJECT parameter which contains a reference to the tool bar the conte*t menu or the tool bar menus. ,n the event han!ler metho! you can then e*ten! or mo!ify these ob;ects accor!ingly.

For information on how to write event handler methods and link them to an event, see section 5.2.

.7.2.2

Defining GUI Elements in the Tool Bar

To a!! new elements to the tool bar" 4. #efine an event han!ler metho! for event TOOLBAR. 5. #eclare a structure for !efining a tool bar element"
data7 ls_toolbar T12E stb_b(tto'.

7. -or a pushbutton for e*ample you woul! fill the following fiel!s"
CLEAR ls_toolbar. MO6E A TO ls_toolbar-b(t'_type. MO6E 3BOO<!4G&3 TO ls_toolbar-f(')tio'. MO6E i)o'_e/ployee TO ls_toolbar-i)o'. MO6E 3&9o; Boo@i'gs3*111+ TO ls_toolbar-E(i)@i'fo. MO6E &2ACE TO ls_toolbar-disabled.

In the b(t'_type field, you specify the type of the GUI element for the ALV control. For possible values, see the value range of domain TB_BT12E.

3. %se event parameter E_OBJECT to appen! the new !efinition to table /t_toolbar"
A22E4D ls_toolbar TO e_obFe)t-%/t_toolbar.

@. ,f you want to !efine a!!itional elements go bac( to step 7. A. &all metho! set_toolbar_i'tera)ti,e if you want to rebuil! the tool bar. ,n the event han!ler metho! of event &ER_COMMA4D you can )uery the function co!e you specifie! in fiel! f(')tio' to implement the associate! function.

See also report BCAL6_GR!D_AG in the Reuse Library.

.7.2.3

Defining a Context Menu

The conte*t menu is an instance of class CL_CTME4 . ,f event CO4TE:T_ME4 _RE? E&T is triggere! by the user event parameter E_OBJECT contains a reference to the stan!ar! conte*t menu. 6ou can mo!ify this menu as follows" To a!! an option to the menu call metho! add_f(')tio'"
CALL METHOD E_OBJECT-%ADD_" 4CT!O4 E:2ORT!4G "CODE $ 3DELE3 TE:T $ TE:T-AAH. BDelete

To !isable e*isting functions (an! gray them out) you pass all correspon!ing function co!es of metho! !isableCfunctions in a table"
DATA7 LT_"CODE& T12E !_" 4CT!O4&8 CLEAR LT_"CODE&. A22E4D CL_G !_AL6_GR!D$%MC_"C_COL_O2T!M!IE TO LT_"CODE&. A22E4D CL_G !_AL6_GR!D$%MC_"C_HEL2 TO LT_"CODE&. CALL METHOD E_OBJECT-%D!&ABLE_" 4CT!O4& E:2ORT!4G "CODE& $ LT_"CODE&.

To hi!e e*isting functions you follow the same proce!ure an! call metho! 9ide_f(')tio's rather than metho! disable_f(')tio's.

+ith metho!s e'able_f(')tio's an! s9o;_f(')tio's you can enable or !isplay the relevant functions again.

See also report BCAL6_GR!D_AJ in the Reuse Library.

.7.2.4

Defining a Menu in the Tool Bar

Dust as a conte*t menu a menu of the tool bar is an instance of class CL_CTME4 . To a!! a new menu to the tool bar" 4. #efine a .%, element of type 4 (menu with a !efault button) or type 5 (menu without a !efault button) in the tool bar. -or a !escription of the proce!ure see section E.5.5. 5. ,n the event han!ler metho! of event ME4 _B TTO4 )uery the function co!e you assigne! for the menu in step 4 (using event parameter E_ COMM). This way you can !istinguish between the !ifferent tool bar menus. 7. -or each function co!e !efine a menu as !escribe! in section E.5.7. -or each menu function assign a!!itional function co!es in step 7 that you can )uery in event &ER_COMMA4D.

See also report BCAL6_GR!D_AK in the 0euse Library.

Special Aspects for Menus with a Default Button

-or a menu with a !efault button the ALV control triggers the following events" ,f the menu arrow is clic(e! event ME4 _B TTO4 is triggere!. ,f the !efault button is clic(e! event &ER_COMMA4D is triggere!.

-or both events the system passes the function co!e that you assigne! in the f(')tio' fiel!. So if you want to assign a menu function to the !efault button the function co!e for the menu must be i!entical to that of the menu function. ,n the ME4 _B TTO4 event you then buil! the menu !irectly while in the &ER_COMMA4D event you can !irectly )uery the function co!e for the !efault function.

See also report BCAL6_GR!D_AL in the Reuse Library.

Migration from the Classic ALV to the ALV Control

,n contrast to the classic ALV the ALV control is a!!resse! through an ob;ect$oriente! interface. Lists are !isplaye! through an ALV instance an! events are processe! base! on the event concept of ABAP 8b;ects. As a result it woul! be very time$consuming to a!;ust ol! programs that use the classic ALV for list output. 2owever to allow ALV users nevertheless to replace classic ALV lists with the ALV control we have !evelope! the RE &E_AL6_GR!D_D!&2LA1 function mo!ule. This function mo!ule has the same interface as the RE &E_AL6_L!&T_D!&2LA1 mo!ule an! supports the output of non$hierarchical lists $ li(e the ALV control. ,!eally users of the ol! mo!ule only nee! to replace L!&T with GR!D in the function mo!ule call.

This way of using the ALV control is also called fullscreen mode.

.8.1.1

Formatting the Page Header

,n 0eporting general information is normally !isplaye! by means of the TO2_O"_2AGE event before the list is output. ALV control event 2R!4T_TO2_O"_2AGE which is very similar is now only use! for print output. ,f function mo!ule RE &E_AL6_GR!D_D!&2LA1 is calle! this output is therefore not !isplaye! on$screen. ,f you alrea!y use function mo!ule RE &E_AL6_COMME4TAR1_#R!TE for page hea!er output no further steps are re)uire!. 8utput is formatte! by the system an! !isplaye! in an 2T9L control in a!vance of the list. ,n this connection the system calls metho!s that generate a so$calle! dynamic document.

You can format the page header yourself by calling the methods for generating a dynamic document. To do this, use parameter !_CALLBAC<_HTML_TO2_O"_2AGE of function module RE &E_AL6_GR!D_D!&2LA1 to specify the name of a form in which you want to call the methods. 0eport DD_AL6_&TA4DARD_TO2 illustrates the output of a page hea!er using function mo!ule RE &E_AL6_COMME4TAR1_#R!TE.