Program Interaction

Object-Oriented Programming

 

The PxPlus OOP interface for NOMADS allows for the definition of standard methods and properties within objects and enables them to be used by NOMADS. This allows developers to create objects with consistent method names and to have the system automatically link to these methods without having to define the method on every field on the panels.

See NOMADS Object and Folder Object below.

NOMADS Object

To interface NOMADS with objects, the NOMADS class *nomads.pvc must be inherited when a new class is defined using the LIKE directive:

Example:

0010 DEF CLASS "demo"
0020 LIKE "*nomads"
...

This defines the PROCESS( ) method which is used to invoke the NOMADS panel. The panel name and library must be declared as either properties or local properties within your object and return the name of the panel and library respectively.

Example:

0030 PROPERTY SCREEN_LIB$="abc.en"
0040 PROPERTY SCREEN_ID$="test"
...

Note:
The Library name may be a specific or generic reference. See Cascading Language Suffixes.

In addition to PROCESS( ), the NOMADS class includes methods for control events, panel events, panels, classes and folders.

Control, Panel and Folder Event Methods

Suppose that a control named WRITE_BUTTON exists on a panel. If a method called WRITE_BUTTON( ) is included in a class written to process the panel, it will be invoked by NOMADS automatically in response to a button press event for this button.

Similarly, if a multi-line called CLIENT_ID exists on a panel, its methods could include ChangeCLIENT_ID( ), OnFocusCLIENT_ID( ) and ValidateCLIENT_ID$(new_val$,id$).

Note:
The ValidateControlName$( ) method takes two parameters and returns a string.

Panel event methods include PreLoad( ), PostLoad( ) and OnExit( ). It is not necessary to specify the panel name for these methods.

Default and Class Methods

Methods are invoked if they exist and no logic is specified for the panel or field. Logic on the panel or field overrides the methods invocation. If the method is not defined, then no action is taken.

Default…. methods (if present) are invoked when there is no method specified for a control or panel; the default is overridden by a control-specific method or logic.

Default control methods include DefaultInitialize( ), DefaultPush( ), DefaultChange( ), DefaultOnFocus( ), DefaultValidate$(new_val$), and DefaultFormatter$(new_val$).

Class... methods (if present) are applied to controls based on data classes. Like default methods, they are invoked only when no control-specific method is present. For example, if we have a multi-line named DATE defined on a panel and it is based on the DATEFIELD data class, then we can invoke the method ClassInitializeDATEFIELD(id).

Other available methods include ClassValidateclass(id,new_val$,id$), ClassOnFocusclass(id), ClassPushclass(id) where class represents the class name.

Using the Methods

The NOMADS object (*nomads.pvc) includes methods for control events, panel events, classes and folders. The available methods are listed below.

Methods

Description

BckLoadctrl(evn(id$+''''.load''''))

Background load logic for control ctrl. Invoked when there is no user input.

Return value is the load status, where load status can be 0 (load in process), 1 (load completed) or -1 (force a reload). Control type can be a List Box or Grid.

Note:
To force a reload of a list box or grid, you must define the controlname.load variable as a local variable (see Example).

See Background Loading.

Example:

Sample program to load list box LB1 using the Background Load method:

   DEF CLASS "BCKLOAD"
   LIKE "*nomads"
   PROPERTY SCREEN_LIB$="TEST.EN"
   PROPERTY SCREEN_ID$="BCKLOAD"
   LOCAL C,Z,X2,Y2 
   LOCAL LB1.LOAD
   FUNCTION Preload()Predisplay_Logic ! panel header pre-display logic
   FUNCTION BckloadLb1(loadstatus)Load_ListBox ! background loading logic for list box 'LB1'
   FUNCTION Reload_Btn()Reload_Lbx ! on change logic for button 'Reload_Btn' (force background loading to occur for 'LB1')
   END DEF
   !
   Predisplay_Logic:
   LET c=0,z=0,X2=0,Y2=0
   LET LB1.LOAD=0
   RETURN
   ! Load_ListBox:
   ENTER loadstatus 
   LET Y2=Y2+100,z=Y2,c=X2
   IF Y2>80000 THEN LET loadstatus=1; RETURN loadstatus 
   SETTRACE PRINT "Loading another 100 items starting at "+STR(c)+" for list box 'LB1'"
   FOR I=c TO z
   LIST_BOX LOAD LB1.CTL,0,STR(I)
   NEXT
   LET X2=z+1
   RETURN loadstatus 
   !
   Reload_Lbx:
   LET c=0,z=0,X2=0,Y2=0
   LET LB1.LOAD=-1 ! force a reload
   LIST_BOX LOAD LB1.CTL,""
   RETURN

Changectrl( )

Invoked whenever the control ctrl changes its value. Return value is ignored.

ClassBckLoadclass$(id,evn(id$+''''.load''''))

Background load logic for controls in class class. Invoked when there is no user input.

Return value is the load status, where load status can be 0 (load in process), 1 (load completed) or -1 (force a reload). Control type can be a List Box or Grid.

See Background Loading.

ClassChangeclass(id)

Invoked whenever the control id changes its value and there is no specific change logic associated with the control. Return value is ignored.

Note:
class refers to the class name.

ClassDragclass1ClassDropclass2$(_dragfrom$,_dropon$)

Invoked when controls in class1 are dropped on controls in class2.

ClassFormatterclass$(id,new_val$,id$)

Invoked to format the new contents of id. It should return an error message if the value is invalid. Returning a null string indicates that the value is acceptable.

Note:
class refers to the class name.

ClassInitializeclass(id)

Invoked to initialize the control id and there is no specific control initialization. Return value is ignored.

Note:
class refers to the class name.

ClassOnFocusclass(id)

Invoked whenever the control id receives focus and there is no specific on focus logic associated with the control. Return value is ignored.

Note:
class refers to the class name.

ClassOnItemNeededclass(id)

Load On Demand logic for all controls in class class.Invoked when user scrolls the control to request items.

Supported on the following List Box types (Standard, Formatted, List View). Return value is ignored.

ClassPushclass(id)

Invoked when a button is pressed and there is no specific logic associated with the button. Return value is ignored.

Note:
class refers to the class name.

ClassValidateclass$(id,new_val$,id$)

Invoked to validate the new contents of id. It should return an error message if the value is incorrect. Returning a null string indicates that the value is acceptable.

If the message is blank (NUL( msg ) returns true), it is assumed you have displayed the error message in your validator routine, and the field will be rejected upon return to *winproc. Control-specific methods override class methods.

Note:
class refers to the class name.

DefaultBckLoad(evn(id$+''''.load'''')

Default method invoked for background loading of a List Box or Grid and no field specific logic exists.

See Background Loading.

DefaultChange( )

Default method invoked when a field changes and no field specific logic exists. Return value is ignored.

DefaultFolderOnExit( )

Default folder On-Exit logic. Invoked when the user/application requests the current tab to be terminated or closed. If the method returns 0, then the tab will not be terminated.

DefaultFolderPostLoad( )

Default folder Post-Load logic. Invoked after the tab contents are displayed but before the first input. Return value is ignored.

DefaultFolderPreload( )

Default folder Pre-Load logic. Invoked before the tab contents are displayed. Return value is ignored.

DefaultFormatter$(new_val$)

Default method invoked to format a field and no field specific logic exists.

DefaultInitialize( )

Default panel field initialization logic. Return value is ignored.

DefaultOnFocus( )

Default method invoked when a field receives focus and no field specific logic exists. Return value is ignored.

DefaultOnItemNeeded( )

Default method invoked for standard, formatted or list view list boxes using Load-On-Demand and no field specific logic exists.

DefaultPush( )

Default method invoked when a button is pressed and there is no specific logic associated with the button. Return value is ignored.

DefaultValidate$(new_val$)

Default method invoked to validate a field and no field specific logic exists.

Dragctrl1Dropctrl2( )

Invoked when control ctrl1 is dropped on control ctrl2.

Formatterctrl$(new_val$,id$)

Invoked to format the new contents of ctrl. It should return an error message if the value is invalid. Returning a null string indicates that the value is acceptable.

GetName$(id)

Get control name for control id.

GetVariable$(id)

Get variable name for control id. Will return string or numeric variable name.

Initializectrl( )

Invoked to initialize the control ctrl. Return value is ignored.

Jumpto(panel$,library$)

Jump to a specific panel and library:

panel$ - Name of panel
library$ - Path to library name (Optional)

OnExit( )

Invoked when the user/application requests main panel termination. Return value must be 1 in order to allow the panel to terminate. If the method returns 0, then the panel will not be closed.

OnExitffffff( )

Invoked when the user/application requests sub-panel fffffff to be terminated or closed. Return value must be 1 in order to allow the sub-panel to terminate. If the method returns 0, then the sub-panel will not be closed.

OnFocusctrl( )

Invoked when control ctrl receives focus. Return value is ignored.

OnItemNeededctrl( )

Load On Demand logic for control ctrl. Invoked when user scrolls the control to request items.

Supported on the following List Box types (Standard, Formatted, List View). Return value is ignored.

PostLoad( )

Invoked after the main panel is displayed but before the first input. Return value is ignored.

PostLoadffffff( )

Invoked after the sub-panel fffffff is displayed but before the first input.

PostResize_ffffff( )

Invoked after the panel fffffff has been resized.

PreLoad( )

Invoked before the main panel is displayed. Return value is ignored.

PreLoadffffff( )

Invoked before the sub-panel fffffff is displayed.

RefreshScrn( )

Invoke screen refresh logic.

Validatectrl$(new_val$,id$)

Invoked to validate the new contents of ctrl. It should return an error message if the value is invalid. Returning a null string indicates that the value is acceptable.

If the message is blank (NUL(msg) returns true), it is assumed you have displayed the error message in your validator routine and the field will be rejected upon return to *winproc.

Ctrl( )

Invoked whenever the button Ctrl is pressed.

Example:

If a button on the panel has the name Add, pressing it causes the method Add( ) to be invoked. Return value is ignored.

'_Parent

Provides the object handle to the prior OOP-based Nomads panel.

Variables

See NOMADS Reserved Variables for a list of variables inherited from the NOMADS class.

Drag and Drop Methods

In OOP methodology, it is generally desirable to encapsulate the logic pertaining to the functionality of an object into itself. To this end, NOMADS objects may include the DragCtrl1DropCtrl2( ) and/or ClassDragClass1ClassDropClass2$( ) method to process drag and drop events. In addition to coding the methods to process the drag and drop events, the application must include a POSTLOAD( ) function to interface with the program *winproc.drg;build_method.

Setting Up DragCtrl1DropCtrl2( ) Method

In the POST_LOAD( ) method of the class, the variable _CLASS_DRAG must be initialized equal to 0, _DRAGFROM_NME$ and _DROPON_NME$ receive the names for the controls which are dragged from and dropped on respectively. Lastly, the program *winproc.drg;build_method must be performed.

Note:
If a panel requires more than one drag and drop event, all steps must be repeated for each of the drag and drop events.

Setting Up ClassDragClass1ClassDropClass2$( ) Method

To set up drag and drop methods for a data class, set the _CLASS_DRAG variable equal to 1 and load the variables _DRAGFROM_CLASS$ and _DROPON_CLASS$ with the name of the class to drag from and drop on. _DRAGFROM_NME$ receives the name of the control being dragged from while _DROPON_NME$ contains the name of the dropped on control. PERFORM"*winproc.drg;build_method".

Folder Object

The Folder Object (*obj/folder.pvc) can be used to draw and manage folders in both NOMADS and non-NOMADS environments. This allows developers to design and implement different looking folders to satisfy their own application requirements.

General folder information is defined via the Folder object. A Tab Object (*obj/tab.pvc) is created for each tab within a Folder.

In NOMADS, the Folder object is instantiated by *winproc. The object identifier for the Folder is stored in the variable Fldr. The object identifier for the current tab is stored in the property Fldr'CurrentTab.

Note:
Many of the _F_ and _Fldr_ tables and variables that were previously used in *winproc are now obsolete.

Using the Methods

The following methods can be used at run time after the Folder is drawn (see Folder Methods for a complete list):

AddTab(Text$,PanelName$,Suppress,FillClr1$,FillClr2$,FillPattern)

Used to add a tab to the end of the tab list. The Suppress, FillClr1$, FillClr2$ and FillPattern parameters are optional.

Example:

Fldr'AddTab("NewTab","Newpnl",0,"rgb:255 174 174","Light Cyan",2)
Fldr'AddTab("Another Tab","AnotherPnl")

DisableActiveTab( )

Used to disable all the controls on the current active tab and the folder tab button. See Note.

DisableFldr( )

Used to disable all the controls on the active tab and all the folder tab buttons. See Note.

DropTab(Idx)

Used to drop a tab at run time. The remaining tabs are re-sequenced and the folder control is redrawn.

Example:

DropTab(2)

EnableActiveTab( )

Used to enable all the controls on the current active tab and the folder tab button. See Note.

EnableFldr( )

Used to enable all the controls on the active tab and all the folder tab buttons. See Note.

GotoTab(Idx)

Used to activate a specific tab.

Example:

GotoTab(3)

InsertTab(Idx,Text$,PanelName$,Suppress,FillClr1$,FillClr2$,FillPattern)

Used to insert a tab at run time. All tabs following the inserted tab are re-sequenced. Suppress, FillClr1$, FillClr2$, and FillPattern parameters are optional.

Example:

Fldr'InsertTab(3,"NewTab","Newpnl",0,"rgb:255 174 174","Light Cyan",2)

Redraw( )

Used to change folder and tab information; i.e. change text, fill pattern and fill colours for the current tab.

Example:

0010 Fldr'CurrentTab'SetText("New Tab Text")
0020 Fldr'CurrentTab'SetFillPattern(3)
0030 Fldr'CurrentTab'SetTabColour("Light Magenta")
0040 Fldr'CurrentTab'SetAltColour("Light Green")
0050 Fldr'SetFont("Comic Sans MS,1,&C")
0060 Fldr'Redraw()

 

Note:
When using the DisableActiveTab( ), EnableActiveTab( ), DisableFldr ( ) and EnableFldr( ) methods:

Only the controls on the current active tab will be affected since the controls on the other tabs are not drawn until that tab is active.

These methods can also be used for tabless folders. Only the controls in the folder region will be enabled or disabled as there are no tab buttons on a tabless folder.

Using the Object Outside NOMADS

The Folder object can also be used outside of NOMADS. To do so, the NOMADS property must be set to 0. The application will be responsible for handling the Folder events.

Example:

1000 ! 1000
1010 PRINT 'DIALOGUE'(10,5,80,35,"Draw Folder Object",'B?'),'SR','CS',
1020 LET Fldr=New("*obj/folder")
1030 LET Fldr'Nomads=0
1040 Fldr'SetColours("RGB:215 0 230;Light yellow") ! this is the colour for the tabs (text and background)
1050 Fldr'SetTabAlignment("T") ! top, bottom, left, right (T,B,L,R)
1060 Fldr'SetFont("Verdana,1,&CS") ! S - fill textbackground (not whole region) with chosen colour
1070 Fldr'SetLine(5)
1080 Fldr'SetColumn(4)
1090 Fldr'SetColumns(60)
1100 Fldr'SetLines(18)
1110 Fldr'SetFillColours1("Light yellow/Light Green/")
1120 Fldr'SetFillColours2("2,Light red/2,RGB:255 128 0/")
1130 LET T$="Panel1=Tab 1"+$01$+""+$00$+"Panel2=Tab 2"+$01$+""+$00$
1140 Fldr'SetTabInfo(T$)
1150 Fldr'SetOrigTabCount(2)
1160 Fldr'SetOrigTabWidth(15)
1170 Fldr'draw()
1180 OBTAIN (0,SIZ=1)'ME',*,'MN',; IF CTL<>0 THEN END ELSE GOTO *SAME
1190 Drop Object Fldr 
1200 End