peNeighborhood - cObject

Determines how an object and its descendents participate in object neighborhood referencing

Type: Property

Access: Read/Write

Data Type: Integer

Parameters: None

 Property Integer peNeighborhood

Read Access: Get peNeighborhood to IntegerVariable
Write Access: Set peNeighborhood to IntegerVariable/Value


The peNeighborhood property determines how an object and its descendents should participate in object neighborhood referencing. Three modes are supported:

nhPrivateThe object defines a private neighborhood. All descendant objects are private and will not support neighborhood referencing. This is the default for all non-visual objects and all visual controls.
nhPublicThe object defines a public Neighborhood. It maintains a list of all of its descendents. When an object name is requested of this object either directly or via object access name delegation it will search its list to see if the object exists. This is the default mode for visual "panel" objects such as views, panels and modal panels.
nhNoThis mode indicates that this object does not define a neighborhood either public or private. Instead it allows its descendents (all objects within this object) to ignore this object and check with its parent to see what its neighborhood status might be. This is the default mode for visual grouping containers .

The Purpose of Object Neigborhoods

The purpose of object neighborhoods is to make it easier for objects to communicate with each other. Objects within a neighborhood can talk to other objects within the neighborhood by the first name (their simple object name: object_label ) without needing to worry about where those objects are located.

Object Neighborhoods make it easier to manage visual objects within views. In a view, visual controls are often nested inside containers for appearance purposes only. As you design an application you may decide that it looks better to place several objects within dbGroups and that it then looks better to place those groups within a dbContainer3d. The Studio makes it very easy to make these kinds of changes. However, every time you move these objects around and put them in different containers you change the way those objects are referenced from other objects within the view. This creates the need to generate complex object reference statements and it may require code change every time you move objects around. This results in code that looks like this:

Get SortOrder of (oSortOrder(oSortParamsGroup(oSetUpContainer(oTabPageReport(oTabDialog))))) to iOrder

And, if you decide to move your oSortOrder object somewhere else in the view, you need to start all over.

With neighborhoods all objects in the view are registered with the view and all objects within the view are visible to all other objects within the view. The same object placed anywhere within the view is now coded as:

Get SortOrder of oSortOrder to iOrder

Object Neigborhoods with different classes

Normally, object neighborhoods are only needed with visual objects. This allows you to nest objects for visual purposes without worrying about how this changes object access. Object neighborhoods "flatten" the object structure of visual controls making it possible for all visible controls to see each other. Objects will still properly encapsulate (hide) non-visual and class-based objects that are clearly not meant to be public. This allows easy access to the objects you want easy access to while still writing properly encapsulated applications. You do not want to use neighborhoods with non-visual objects as their use would only encourage impoper encapsulation.

Views and modal panels are defined as public neighborhoods (View, dbView, ModalPanel, dbModalPanel, dbTabView, etc.). You should be able to use object neighborhoods with all visual objects within these views and panels.

All of other visual containers (Container3d, dbContainer3d, Group, dbGroup, TabDialog, dbTabDialog, TabPage, dbTabPage, etc.) set their peNeighborhood mode to nhNo which causes references to pass through them. This is what flattens the access structure.

All visual controls (Form, dbForm, Grid, dbGrid, etc.) and non-visual controls (cObject, Array, BusinessProcess, etc.) are set their peNeighborhood to nhPrivate which keeps all of their children private.

Objects that are not part of neighborhoods are still referenced using normal object access referencing (check if name exists as a child, if not delegate to parent and repeat search, repeat until object is found).

Note:The peNeighborhood property is already set appropriately for each class in the framework. These modes are set to provide the best mix of proper encapsulation, ease of visual design and ease of object access. You should never need to change this property in any class. Before you change this mode you should review your object structure and see if you can solve your problem by restructuring your objects.