Examples

The following are several examples and descriptions for setting up some basic packets using the standard pick sequence methods.

Single Element Pick

The Single Element Pick defines an event packet that is totally self contained, it uses no controlling form or action macros in its definition.

The packet definition is defined so that it remembers the element you are at when the packet is placed in the event system. For each pick of an element in the graphics view, you will be navigated to the picked element, when packet is removed from the event system (using <esc> or being forced from the system by another event) you will be returned to the original element:

-- Define event packet

!packet     = object EDGPACKET()

-- Define standard element pick

!packet.elementPick('Pick Element')

-- Remember the element when the packet was first place in the

-- event system

!packet.initialisation     = '!this.input[1] = !!ce'

-- Move to the element picked

!packet.action     = '!!ce = !this.return[1].item'

-- Set the close sequence, so that the user returns to the original

-- element

!packet.close     = '!!ce = !this.input[1]

-- Add event packet to the system

!!edgCntrl.add(!packet)

Repeat Element Pick

The Repeat Element Pick defines an event packet that will keep picking elements, storing the picked element in the input member of the packet. Then, when <esc> button is pressed, the closing action will display all the elements in the input array.

-- Define event packet

!packet     = object EDGPACKET()

-- Define standard element pick

!packet.elementPick('Pick Element <esc> to finish')

-- Retain the element picked in the input member

!packet.action     = '!this.input.append(!this.return[1].item)'

-- Display the selected element on <esc>

!packet.close     = 'q var !this.input'

-- Add event packet to the system

!!edgCntrl.add(!packet)

Again, this packet does not use other objects, functions or forms in its running. However, it could be adapted to use objects, functions or forms when running. This could allow the elements picked twice to be removed from the list, then some special action carried out on all elements selected on the close of the packet.

The following is an example of a packet definition that will run functions that store the picked element (in a global variable), then on completion, enhance all the elements selected.

When the event is placed into the event system, it will automatically initialize the Global variable that is used to store the picked elements:

Event Packet Definition

-- Define event packet

!packet     = object EDGPACKET()

-- Define standard element pick

!packet.elementPick('Pick Element <esc> to finish')

-- Initialise the global store

!packet.initialisation     = '!!xxxGlobalStore = ARRAY()'

-- Retain the element picked in the input member

!packet.action     = '!!xxxStoreElement(!this.return[1].item)'

-- Tag the selected element on <esc> with their names

!packet.close     = '!!xxxTagElements(|NAME|)'

-- Add event packet to the system

!!edgCntrl.add(!packet)

The following is the function definition that stores the picked element in a global variable, enhancing the picked element. If the same element is picked twice, then it will be removed from the list and un-enhance it:

Store Element Function

-- Function Definition

define function !!xxxStoreElement(!element is DBREF)

-- Check if element exist in the global variable

!index = !!xxxGlobalStore.findFirst(!element)

-- Element already is in the store

if(!index.set()) then

-- Remove element from the list and un-enhance

!!xxxGlobalStore.remove(!index)

    UNENHANCE $!<element>

-- Add element to the list and enhance

else

!!xxxGlobalStore.append(!element)

    ENHANCE $!<element> COLOUR RED

endif

-- End of definition

endfunction

The following functions definition is used to tag 'MARK' all the elements that are in the global variable:

Store Element Function

-- Function Definition

define function !!xxxTagElements()

-- Loop through elements

do !i indices !!xxxGlobalStore

-- Tag Item

MARK $!!<xxxGlobalStore[$!<i>]>

-- Unenhance element

UNENHANCE $!!<xxxGlobalStore[$!<i>]>

enddo

-- End of definition

endfunction

Simple Standard Position Pick (Using Only Position Data)

The Simple Standard Position Pick defines an event packet that uses the standard positioning pick sequence. In this example, the packet definition has a controlling form (the detail of the form is irrelevant) that the derived picked position writes it data to after each pick.

When associating a form with an event packet, the developer must always make sure that the form has been build. This is because the form is passed by reference.

When the event packet is added to the edg system, the form will automatically be shown in the top right hand corner of the screen (there is no control over this). In the case of the positioning pick sequence, the positioning control form will also be displayed above the event packets form.

-- Define event packet

!packet      = object EDGPACKET()

-- Define standard element pick

!packet.definePosition('Pick Position')

-- Retain the element picked in the input member

!packet.action      = '!!xxxForm.position(!this.return[1].position)'

-- Build form if required

if(undefined(!!xxxForm)) then

pml reload form !!xxxForm

endif

-- Associate form

!packet.form      = !!xxxForm

-- Execute the forms tidy method on completion

!packet.close      = '!!xxxForm.tidy()'

-- Add event packet to the system

!!edgCntrl.add(!packet)

It should be noted that there are several ways in which the event packet form can be closed:

• Form gadget, OK/Cancel/Dismiss button or Close on pull-down.

• Close from the forms pull-down, top-left-hand corner of the form.

• Using the <esc> key when in a design graphics canvas.

When closing the event from the from (one of the first two methods), then the event packet must be removed using the event systems .remove method, supplying the same description that event packet was placed onto the system with:

!!edgCntrl.remove(<event packet description>)

When using the <esc> in the design canvas, then only the relevant tidy-up sequence of the form should to be used.

Note:
The developer must not use a method that has the event systems .remove method in, this could cause problems.

Equivalents to "VAR !<id> PICK" Commands

The following are examples of the old style PML 1 commands used to suspend the currently active macro with a pick from the graphics canvas.

The following example equates to the old style "pick an element":

VAR !<varid> PICK

-- Define event packet

!packet     = object EDGPACKET()

-- Define standard element pick

-- Equates to old      PROMPT OFF

--                     PROMPT LOAD ESCAPE '<prompt>'

!packet.elementPick ('Identify element')

-- Defines action on completion of the pick, passing complete

-- pick data

!packet.action      ='!action(!this.return[1])'

-- Add event packet to the system

-- Equate to old     VAR !varID PICK

!!edgCntrl.add(!packet)

The following example equates to the old style "pick a pline of a section":

VAR !<varid> PICK PLINE

-- Define event packet

!packet      = object EDGPACKET()

-- Define standard element pick

-- Equates to old      PROMPT OFF

--                     PROMPT LOAD ESCAPE '<prompt>'

!packet. plinePick ('Identify pline of section)

-- Defines action on completion of the pick, passing complete

-- pick data

!packet.action       ='!action(!this.return[1])'

-- Add event packet to the system

-- Equate to old       VAR !varID PICK PLINE

!!edgCntrl.add(!packet)

The following example equates to the old style "pick a ppoint of an element":

VAR !<varid> PICK PLINE

-- Define event packet

!packet      = object EDGPACKET()

-- Define standard element pick

-- Equates to old       PROMPT OFF

--                      PROMPT LOAD ESCAPE '<prompt>'

!packet. plinePick ('Identify element ppoint)

-- Defines action on completion of the pick, passing complete

-- pick data

!packet.action       ='!action(!this.return[1])'

-- Add event packet to the system

-- Equate to old     VAR !varID PICK POINT

!!edgCntrl.add(!packet)

Notes:

• With the EDG system, it is not possible to instigate an event and suspend the currently active macro then return to the same point in the macro, once the pick is completed. If the developer wants to simulate the suspension of a macro, i.e. wait for the pick on the graphics canvas. Then, the invocation of the event packet must be the last command within the file and the action to be carried out after the pick, must be in the function/method defined in the .action member.
  Command defined after the invocation of an event packet within the same macro, must not rely on the pick data of the event. Also it should be noted that any changes to the packet definition will not have any effect on the event packet that has been added to the system.

• All of the above will automatically use the standard filters set via the filter utility within the application.
  If an event packet is required that has a specific type of pick filter and the standard filters are to be ignored, refer to Limitations and Restrictions.